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
^^^^^^^^^^^
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
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
$ kamaki
- Example 1.2.1: Running kamaki shell
+ Example 2.2.1: Running kamaki shell
* with any kind of '-' prefixed arguments, except '-h', '--help'.
$ 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)
$kamaki -h
- Example 1.3.1: Kamaki help
+ Example 2.3.1: Kamaki help
* with one or more command parameters:
$ 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.
$ 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
------------------------------------------
projects / kamaki / commitdiff