Commit a6370d73 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Document command specs and one-command interface

parent 48cae069
......@@ -138,6 +138,9 @@ The [global] group is treated by kamaki as a generic group for arbitrary options
* astakos.cli <UI command specifications for Astakos authentication service>
a special package that is used to load astakos-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
* history.file <history file path>
the path of a simple file for inter-session kamaki history. Make sure kamaki is executed in a context where this file is accessible for reading and writting. Kamaki automatically creates the file if it doesn't exist
Hidden features
^^^^^^^^^^^^^^^
......
Usage
=====
Kamaki offers two command line interfaces: an one-command tool and an interactive shell. Both systems implement the exact same command specifications. A detailed list of the command specifications can be found in `Commands <commands.html>`_ section. This guide covers the generic usage of both interfaces.
Kamaki offers command line interfaces that implement specific command specifications. A detailed list of the command specifications can be found in `Commands <commands.html>`_ section. This guide covers the generic usage of both interfaces.
What's more, kamaki offers a clients API that allows the developement of external applications for synnefo. The clients API is listed in the `Clients lib <clients.html>`_ section. The recomended method of utilizing this API is explained in the present.
Setup
-----
Kamaki interfaces rely on a list of configuration options. In the initial state, kamaki is configured to communicate with the Okenos IaaS. A detailed guide for setting up kamaki can be found in the `Setup <setup.rst>`_ section.
Kamaki interfaces rely on a list of configuration options. In the initial state, kamaki is configured to communicate with the Okenos IaaS. A detailed guide for setting up kamaki can be found in the `Setup <setup.html>`_ section.
Quick guide
^^^^^^^^^^^
......@@ -22,7 +22,7 @@ It is essential for users to get a configuration token (to get in Okeanos.grnet.
Example 1.1.1: Set user token to myt0k3n==
To use the storage service, a user should also provide the username:
To use the storage service, a user should also provide the corresponding username:
.. code-block:: console
......@@ -31,9 +31,27 @@ To use the storage service, a user should also provide the username:
Example 1.1.2: Set user name to user@domain.com
Command line interfaces
-----------------------
Kamaki users can access synnefo services through either the interactive shell or the one-command behaviors. In practice, both systems relly on the same command set implementations and API clients, with identical responses and error messages. Still, there are some differenses.
Shell vs one-command
^^^^^^^^^^^^^^^^^^^^
In favor of interactive shell behavior:
* tab completion for commands
* session history with "up"/"down" keys
* shorter commants with command namespace switching
In favor of one-command behavior:
* can be used along with advanced shell features (pipelines, redirection, etc.)
* can be used in shell scripts
* prints debug and verbose messages if needed
Run as shell
""""""""""""
Call kamaki
To use kamaki as a shell, run:
* without any parameters or arguments
......@@ -42,7 +60,7 @@ Call kamaki
$ kamaki
Example 1.2.1: Running kamaki shell
Example 2.2.1: Running kamaki shell
* with any kind of '-' prefixed arguments, except '-h', '--help'.
......@@ -52,12 +70,12 @@ Call kamaki
$ kamaki --config myconfig.file
Example 1.2.2: Running kamaki shell with custom configuration file
Example 2.2.2: Running kamaki shell with custom configuration file
Run as one-command
""""""""""""""""""
Call kamaki:
To use kamaki as an one-command tool, run:
* with the '-h' or '--help' arguments (help for kamaki one-command)
......@@ -66,7 +84,7 @@ Call kamaki:
$kamaki -h
Example 1.3.1: Kamaki help
Example 2.3.1: Kamaki help
* with one or more command parameters:
......@@ -75,10 +93,10 @@ Call kamaki:
$ kamaki server list
Example 1.3.2: List VMs managed by user
Example 2.3.2: List VMs managed by user
Command parameters
""""""""""""""""""
Commands
^^^^^^^^
Typically, commands consist of a group name (e.g. store for storage commands) one or more terms (e.g. list for listing) and the command specific parameters (e.g. the name of the container), if any.
......@@ -87,23 +105,319 @@ Typically, commands consist of a group name (e.g. store for storage commands) on
$ kamaki store list mycontainer
Example 1.4.1: List stored files in container mycontainer
Example 3.1.1: List stored files in container mycontainer
E.g. in example 1.3.2, the group is "server", the command is "list" and there are no parameters. Example 6 is another example using the "server" command group.
Example 2.3.2 showcases a command without parameters (the group is "server", the command is "list").
The "server" command group is also refered in the following example.
.. code-block:: console
$ kamaki server info 42
Example 1.4.2: Show information about a user-managed VM with id 42
Example 3.1.2: Show information about a user-managed VM with id 42
Client commands can feature an arbitarry number of terms:
.. code-block:: text
kamaki <group> <cmd term 1> <cmd term 2> ... <cmd term N> [arguments]
Although there are no multi-termed client commands until version 0.6.1 , the feature is supported and might be used in feature extentions.
The following pattern applies to all client commands up to version 0.6.1:
.. code-block:: text
kamaki <group> <command> [arguments]
The commands supported in version 0.6.1 are described bellow, grouped by service:
astakos (Identity Manager)
""""""""""""""""""""""""""
.. code-block:: text
authenticate: Authenticate a user
flavor (Compute/Cyclades)
"""""""""""""""""""""""""
.. code-block:: text
info: Get flavor details
list: List flavors
image (Compute/Cyclades + Glance)
""""""""""""""""""""""""""""""""""
.. code-block:: text
addmember : Add a member to an image
addproperty: Add an image property
delete : Delete image
delmember : Remove a member from an image
delproperty: Delete an image property
info : Get image details
list : List images
members : Get image members
meta : Get image metadata
properties : Get image properties
public : List public images
register : (Re)Register an image
setmembers : Set the members of an image
setproperty: Update an image property
shared : List shared images
network (Compute/Cyclades)
""""""""""""""""""""""""""
.. code-block:: text
connect : Connect a server to a network
create : Create a network
delete : Delete a network
disconnect: Disconnect a nic of a server to a network
info : Get network details
list : List networks
rename : Update network name
server (Compute/Cyclades)
"""""""""""""""""""""""""
.. code-block:: text
addmeta : Add server metadata
addr : List a server's nic address
console : Get a VNC console
create : Create a server
delete : Delete a server
delmeta : Delete server metadata
firewall: Set the server's firewall profile
info : Get server details
list : List servers
meta : Get a server's metadata
reboot : Reboot a server
rename : Update a server's name
setmeta : Update server's metadata
shutdown: Shutdown a server
start : Start a server
stats : Get server statistics
wait : Wait for server to finish
store (Storage/Pithos+)
"""""""""""""""""""""""
.. code-block:: text
append : Append local file to remote
cat : Print a file to console
copy : Copy an object
create : Create a container or a directory object
delete : Delete a container [or an object]
delgroup : Delete a user group on an account
delmeta : Delete an existing metadatum of account [, container [or object]]
delpermissions: Delete all sharing permissions
download : Download a file
group : Get user groups details for account
hashmap : Get the hashmap of an object
info : Get information for account [, container [or object]]
list : List containers, object trees or objects in a directory
manifest : Create a remote file with uploaded parts by manifestation
meta : Get custom meta-content for account [, container [or object]]
mkdir : Create a directory
move : Copy an object
overwrite : Overwrite part (from start to end) of a remote file
permissions : Get object read/write permissions
publish : Publish an object
purge : Purge a container
quota : Get quota for account [or container]
setgroup : Create/update a new user group on account
setmeta : Set a new metadatum for account [, container [or object]]
setpermissions: Set sharing permissions
setquota : Set new quota (in KB) for account [or container]
setversioning : Set new versioning (auto, none) for account [or container]
sharers : List the accounts that share objects with default account
truncate : Truncate remote file up to a size
unpublish : Unpublish an object
upload : Upload a file
versioning : Get versioning for account [or container ]
versions : Get the version list of an object
One-command interface
---------------------
^^^^^^^^^^^^^^^^^^^^^
Kamaki usage as a one-command tool is detailed in this section
Using help
""""""""""
Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments.
To see the command groups, users should use -h or --help like in example 1.3.1. In the same way, help information for command groups and commands is printed. In the following examples, the help messages of kamaki, of a command group (server) and of a command in that group (list) are shown.
.. code-block:: console
$ kamaki -h
usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd> [-v] [-s] [-V] [-d] [-i]
[--config CONFIG]
[-o OPTIONS] [-h]
optional arguments:
-v, --verbose More info at response
-s, --silent Do not output anything
-V, --version Print current version
-d, --debug Include debug output
-i, --include Include protocol headers in the output
--config CONFIG Path to configuration file
-o OPTIONS, --options OPTIONS
Override a config value
-h, --help Show help message
Options:
- - - -
astakos: Astakos API commands
config : Configuration commands
flavor : Compute/Cyclades API flavor commands
history: Command history
image : Compute/Cyclades or Glance API image commands
network: Compute/Cyclades API network commands
server : Compute/Cyclades API server commands
store : Pithos+ storage commands
Example 4.1.1: kamaki help shows available parameters and command groups
.. code-block:: console
$ kamaki cyclades -h
usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
[-o OPTIONS] [-h]
optional arguments:
-v, --verbose More info at response
-s, --silent Do not output anything
-V, --version Print current version
-d, --debug Include debug output
-i, --include Include protocol headers in the output
--config CONFIG Path to configuration file
-o OPTIONS, --options OPTIONS
Override a config value
-h, --help Show help message
Options:
- - - -
addmeta : Add server metadata
addr : List a server's nic address
console : Get a VNC console
create : Create a server
delete : Delete a server
delmeta : Delete server metadata
firewall: Set the server's firewall profile
info : Get server details
list : List servers
meta : Get a server's metadata
reboot : Reboot a server
rename : Update a server's name
setmeta : Update server's metadata
shutdown: Shutdown a server
start : Start a server
stats : Get server statistics
wait : Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
Example 4.1.2: Cyclades help contains all first-level commands of cyclades command group
.. code-block:: console
$ kamaki server list -h
usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
[-o OPTIONS] [-h] [-l]
List servers
optional arguments:
-v, --verbose More info at response
-s, --silent Do not output anything
-V, --version Print current version
-d, --debug Include debug output
-i, --include Include protocol headers in the output
--config CONFIG Path to configuration file
-o OPTIONS, --options OPTIONS
Override a config value
-h, --help Show help message
-l show detailed output
Example 4.1.3: Help for command "server list" with syntax, description and avaiable user options
Using history
"""""""""""""
Kamaki command history is stored in a file at user home (".kamaki.history" by default). To set a custom history file path users must set the history.file config option (see `available config options <setup.html#editing-options>`_).
Every syntactically correct command is appended at the end of that file. In order to see how to use history, use the kamaki help system:
.. code-block:: console
$ kamaki history -h
...
clean: Clean up history
show : Show history
Example 4.2.1: Available history options
The following example showcases how to use history in kamaki
.. code-block:: console
$ kamaki history clean --match clean
$ kamaki server list
...
$ kamaki history show
1. kamaki server list
2. kamaki history show
$ kamaki history show --match server
1. kamaki server list
3. kamaki history show --match server
Example 4.2.2: Clean up everything, run a kamaki command, show full and filtered history
Debug
"""""
In case of errors, kamaki in debug mode shows usefull debug information, like the stack trace, instead of a user-friendly error message. Kamaki also suppresses various warning messages that are also allowed in debug mode.
To run kamaki in debug mode use the -d or --debug option
Verbose
"""""""
Most kamaki commands are translated into http requests. Kamaki clients API translated the semantics to REST and handles the response. Users who need to have access to these commands can use the verbose mode that presentes the HTTP Request details as well as the full server response.
To run kamaki in verbose mode use the -v or --verbose option
Client commands
"""""""""""""""
Client commands are grouped by service (see example 3.1.1 for how to list availabel groups). Commands behavior is as uniform as possible, but there are still differences between groups due to the special nature of each service and server-side implementation.
Kamaki commands can be used along with advanced shell features.
.. code-block:: console
$ kamaki server list -l > vmlist.txt
Example 4.4.1: Store a vm list in file vmlist.txt in a unix shell
In that case, kamaki modifies the output (e.g. removes colors - if enabled)
Interactive shell
-----------------
^^^^^^^^^^^^^^^^^
Creating applications over the Clients API
------------------------------------------
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment