Usage
=====
-Kamaki offers command line interfaces that implement specific command
+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 development of
-external applications for synnefo. The clients API is listed in the
+What's more, kamaki offers a clients library for the development of external
+client applications for Synnefo. The clients library API is detailed in the
`Clients lib <developers/code.html#the-clients-api>`_ section.
Quick Setup
.. code-block:: console
:emphasize-lines: 1
- Example 1.1: Set default authentication user and token
+ Example 1.1: Set authentication URL, user token and cloud alias "default"
- $ kamaki config set remote.default.url <authentication URL>
- $ kamaki config set remote.default.token myt0k3n==
+ $ kamaki config set cloud.default.url <authentication URL>
+ $ kamaki config set cloud.default.token myt0k3n==
+
+.. note:: The term *default* can be replaced by any arbitary term chosen by
+ the user. This term will serve as a cloud alias for kamaki users, and can
+ be easily modified.
Shell vs one-command
--------------------
-Kamaki users can access synnefo services through either the interactive shell
-or the one-command behaviors. In practice, both systems rely on the same
+Kamaki users can access Synnefo services through either the interactive shell
+or the one-command interface. In practice, both systems rely on the same
command set implementations and API clients, with identical responses and error
messages. Still, there are some differences.
-In favor of interactive shell behavior:
+In favor of interactive shell:
-* tab completion for commands (if supported by host OS)
-* session history with ↑ or ↓ keys
+* tab completion for commands (if supported by the user shell)
+* session history with ↑ or ↓ keys (if supported by the user shell)
* shorter commands with command context switching
* re-run old commands with /history
-In favor of one-command behavior:
+In favor of one-command:
* can be used along with advanced shell features (pipelines, redirection, etc.)
* can be used in shell scripts
$ kamaki
-* with any kind of '-' prefixed arguments, except '-h', '--help'.
+* with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
+ '- - version'.
.. code-block:: console
:emphasize-lines: 1
Example 2.2.2: Run kamaki shell with custom configuration file
- $ kamaki --config myconfig.file
+ $ kamaki -c myconfig.file
Run as one-command
.. code-block:: console
:emphasize-lines: 1
- Example 2.3.2: List VMs managed by user
+ Example 2.3.2: List servers managed by user
$ kamaki server list
Using help
^^^^^^^^^^
-Kamaki help is used to list available commands with description, syntax and
-corresponding optional arguments.
+Kamaki help provides information on available commands (description, syntax and
+corresponding optional arguments).
-To see the command groups, 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.
+To see the command groups, use -h or --help (example 1.3.1). The
+following examples demonstrate the help messages of kamaki, in the context of a
+command group (server) and of a command in that group (list).
.. code-block:: console
:emphasize-lines: 1
Path to configuration file
-o OPTIONS, --options OPTIONS
Override a config value
- --cloud CLOUD Chose a remote cloud to connect to
+ --cloud CLOUD Chose a cloud to connect to
-h, --help Show help message
Options:
- - - -
- config : Kamaki configurations
- file : Pithos+/Storage API commands
- flavor : Cyclades/Compute API flavor commands
- history : Kamaki command history
- image : Cyclades/Plankton API image commands
+ network: Cyclades/Compute API network commands
+ user: Astakos API commands
+ livetest: Client func. tests on live servers
+ server: Cyclades/Compute API server commands
+ project: Synnefo project management CLI
+ file: Pithos+/Storage API commands
+ flavor: Cyclades/Compute API flavor commands
+ config: Kamaki configurations
+ image: Cyclades/Plankton API image commands
image compute: Cyclades/Compute API image commands
- network : Cyclades/Compute API network commands
- server : Cyclades/Compute API server commands
- user : Astakos API commands
+ history: Kamaki command history
+
.. code-block:: console
:emphasize-lines: 1,2
Path to configuration file
-o OPTIONS, --options OPTIONS
Override a config value
- --cloud CLOUD Chose a remote cloud to connect to
+ --cloud CLOUD Chose a cloud to connect to
-h, --help Show help message
Options:
- - - -
- addr : List the addresses of all network interfaces on a server (VM)
- console : Get a VNC console to access an existing server (VM)
- create : Create a server (aka Virtual Machine)
- delete : Delete a server (VM)
- firewall: Manage server (VM) firewall profiles for public networks
- info : Detailed information on a Virtual Machine
- list : List Virtual Machines accessible by user
- metadata: Manage Server metadata (key:value pairs of server attributes)
- reboot : Reboot a server (VM)
- rename : Set/update a server (VM) name
- shutdown: Shutdown an active server (VM)
- start : Start an existing server (VM)
- stats : Get server (VM) statistics
- wait : Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
+ info: Detailed information on a Virtual Machine
+ rename: Set/update a virtual server name
+ delete: Delete a virtual server
+ console: Get a VNC console to access an existing virtual server
+ addr: List the addresses of all network interfaces on a virtual server
+ firewall: Manage virtual server firewall profiles for public networks
+ create: Create a server (aka Virtual Machine)
+ list: List Virtual Machines accessible by user
+ reboot: Reboot a virtual server
+ start: Start an existing virtual server
+ shutdown: Shutdown an active virtual server
+ stats: Get virtual server statistics
+ metadata: Manage Server metadata (key:value pairs of server attributes)
+ resize: Set a different flavor for an existing server
+ wait: Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
.. code-block:: console
:emphasize-lines: 1,2
[-l] [--more] [-n LIMIT] [-j]
List Virtual Machines accessible by user
- User Authentication:
- * to check authentication: /user authenticate
- * to set authentication token: /config set remote.default.token <token>
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 raw connection data in the output
- -c CONFIG, --config CONFIG
- Path to configuration file
- -o OPTIONS, --options OPTIONS
- Override a config value
- --cloud CLOUD Chose a remote cloud to connect to
- -h, --help Show help message
- --since SINCE show only items since date (' d/m/Y H:M:S ')
- --enumerate Enumerate results
- -l, --details show detailed output
- --more output results in pages (-n to set items per page,
- default 10)
- -n LIMIT, --number LIMIT
- limit number of listed VMs
- -j, --json show headers in json
+ -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 raw connection data in the output
+ -c CONFIG, --config CONFIG
+ Path to config file
+ -o OPTIONS, --options OPTIONS
+ Override a config value
+ --cloud CLOUD Chose a cloud to connect to
+ -h, --help Show help message
+ --status STATUS filter by status (ACTIVE, STOPPED, REBOOT, ERROR,
+ etc.)
+ --enumerate Enumerate results
+ --name-suffix NAME_SUFF
+ filter by name suffix (case insensitive)
+ --image-id IMAGE_ID filter by image id
+ --metadata META filter by metadata key=values
+ -j, --json show headers in json
+ --id ID filter by id
+ --user-id USER_ID filter by user id
+ --id-like ID_LIKE print only if id contains this (case insensitive)
+ --id-suffix ID_SUFF filter by id suffix (case insensitive)
+ --since SINCE show only items since date (' d/m/Y H:M:S ')
+ -l, --details show detailed output
+ --name NAME filter by name
+ --more output results in pages (-n to set items per page,
+ default 10)
+ --name-prefix NAME_PREF
+ filter by name prefix (case insensitive)
+ -n LIMIT, --number LIMIT
+ limit number of listed virtual servers
+ --id-prefix ID_PREF filter by id prefix (case insensitive)
+ --user-name USER_NAME
+ filter by user name
+ --name-like NAME_LIKE
+ print only if name contains this (case insensitive)
+ --metadata-like META_LIKE
+ print only if in key=value, the value is part of
+ actual value
+ --flavor-id FLAVOR_ID
+ filter by flavor id
+
+ Details:
+ Use filtering arguments (e.g., --name-like) to manage long server lists
.. _using-history-ref:
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:
+Every 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
:emphasize-lines: 1
Debug
"""""
-In case of errors, kamaki in debug mode shows useful debug information, like
-the stack trace. Kamaki in debug mode cancels suppression of warning messages.
+When in debug mode, kamaki outputs some useful debug information (stack trace
+and http logs). Kamaki in debug mode cancels suppression of warning messages.
+
+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 presents the HTTP
+Request details as well as the full server response.
+
+To run kamaki in verbose mode use the *-v/- - verbose* option
+
+Verbose mode outputs the request and response mode, address and
+headers as well as the size of the data block, if any. Sensitive information
+(x-auth-token header and data body) are omitted by default,. Users who need
+this information may enable it through the log_token and log_data configuration
+options (see next section)
+
+.. tip:: Use the -o runtime option to enable config options on the fly, e.g, to
+ include http data:
+
+ .. code-block:: console
+
+ $ kamaki server list -v -o log_data=on
-To run kamaki in debug mode use the -d or --debug option (can be combined with
-any other parameters or options)
Logging
"""""""
-Kamaki keeps its logs in a file specified as global.log_file and its value
-defaults to ${HOME}/.kamaki.log . This value may change with a config setting::
+Kamaki keeps its logs in a file specified by the *log_file* option and it
+defaults to *${HOME}/.kamaki.log*. This configuration option can be modified::
kamaki config set log_file /new/log/file/path
-Kamaki logs mostly the http connection requests and responses, including http
-methods, urls, parameters and headers. There is some special handling in two
-cases:
+Kamaki logs http request and response information, namely the method, URL,
+headers and data size. Sensitive information (data and token header) are
+omitted by default. There are some configuration options that can switch them
+on, though:
-* HTTP bodies are not logged by default
+* HTTP data blocks are not logged by default
to enable logging the full http bodies, set log_data to `on`::
kamaki config set log_data on
kamaki config delete log_token
-Verbose and Include
-"""""""""""""""""""
+* The information (pid, name, date) of the processes that handle http requests
+ is not logged by default, because if they are, logs are difficult to read.
+ Still, they are useful for resolving race condition problems, so to enable
+ logging proccess information::
-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 presents the HTTP
-Request details as well as the full server response.
+ kamaki config set log_pid on
+
+ to disable it, set if to off::
-To run kamaki in verbose mode use the -v or --verbose option
+ kamaki config set log_pid off
+
+ or delete it::
-Be default, kamaki in verbose mode prints down only the headers and the address
-information, thus hiding the data body of the request or response. To see the
-data body, the -i option can be used.
+ kamaki config delete log_pid
One-command features
^^^^^^^^^^^^^^^^^^^^
Example 3.4.1: List the trash container contents, containing c1_
- $ kamaki file list -o global.pithos_container=trash| grep c1_
+ $ kamaki file list -o cloud.default.pithos_container=trash| grep c1_
c1_1370859409.0 20KB
c1_1370859414.0 9MB
c1_1370859409.1 110B
configuration file (it works even if the user has not set the optional
pithos_account config option).
+.. tip:: There are better ways to list the contents of a container. Example
+ 3.4.1 is using this method for demonstration purposes only. The suggested
+ method for listing container contents is *- - container=<container>*
+
Interactive shell
-----------------
The kamaki interactive shell implements the notion of command contexts. Each
command group is also a context where the users can **enter** by typing the
group name. If the context switch is successful, the kamaki shell prompt
-changes to present the new context ("file" in example 4.1.1).
+changes to present the new context ("*file*" in example 4.1.1).
.. code-block:: console
:emphasize-lines: 1
- Example 4.1.1: Enter file commands context / group
+ Example 4.1.1: Start kamaki and switch to file context
$ kamaki
[file]: exit
[kamaki]: server
[server]: list
- ... (VMs listing) ...
+ ... (servers listing) ...
[server]: exit
[kamaki]:
[kamaki]: file list
... (storage container listing) ...
[kamaki]: server list
- ... (VMs listing) ...
+ ... (servers listing) ...
[kamaki]:
Using Help
* Show available commands in current context *
[context]: help
+ ...
[context]: ?
+ ...
* Show help for command cmd *
[context]: help cmd
+ ...
[context]: ?cmd
+ ...
The context-level help results may change from context to context
kamaki commands:
================
- user config flavor history image network server file
+ user config flavor history image network server file ...
interactive shell commands:
===========================
[context]: /anothercontext cmd1 cmd2 ... cmdN
An example (4.3.1) that showcases how top-level access improves user experience
-is the creation of a VM. A VM is created with the command server-create. This
+is the creation of a server. A server is created with the command server-create. This
command is called with three parameters:
-* the name of the new VM
+* the name of the new server
* the flavor id
* the image id
-It is often the case that a user who works in the context command, needs to
-create a new VM, but hasn't selected a flavor or an image id, or cannot recall
-the id of that flavor or image. Therefore, it is necessary to list all
-available flavors (flavor-list) or images (image-compute-list). Both commands
-belong to different contexts.
+An average user would enter the server context and type *create -h* to check the
+syntax of the command. In that point, it would be nice to have some easy way of
+accessing the *flavor* and *image* contexts, to list and pick a flavor id and an
+image id. This is achieved with the / notation, as demonstrated in the following
+example:
.. code-block:: console
:emphasize-lines: 1
- Example 4.3.1: Create a VM from server context
+ Example 4.3.1: Create a server from server context
[server]: create -h
create <name> <flavor id> <image id> ...
.. code-block:: console
:emphasize-lines: 1
- Example 4.3.2: Set a new token from file context
+ Example 4.3.2: Token suddenly expires. Set a new token from file context
[file]: list
[file]: /user authenticate
(401) UNAUTHORIZED Invalid X-Auth-Token
- [file]: /config get remote.default.token
+ [file]: /config get cloud.default.token
my3xp1r3dt0k3n==
- [file]: /config set remote.default.token myfr35ht0k3n==
+ [file]: /config set cloud.default.token myfr35ht0k3n==
- [file]: /config get remote.default
- remote.default.url = https://astakos.example.com/astakos/identity/2.0/
- remote.default.token = myfr35ht0k3n==
+ [file]: /config get cloud.default
+ cloud.default.url = https://astakos.example.com/astakos/identity/2.0/
+ cloud.default.token = myfr35ht0k3n==
[file]: list
1. pithos (10MB, 2 objects)
2. trash (0B, 0 objects)
-.. note:: The error messages on this example where shortened for clarity.
-Actual kamaki error messages are more helpful and descriptive.
+.. note:: The error messages on examples are shortened for clarity. Actual error
+ messages are more helpful and descriptive.
The following example compares some equivalent calls that run
*user-authenticate* after a *file-list* 401 failure.
Example 4.3.3: Equivalent user-authenticate calls after a file-list 401
- * without kamaki interactive shell *
+ * I. without kamaki interactive shell *
$ kamaki file list
(401) UNAUTHORIZED Access denied
$ kamaki user authenticate
...
$
- * from top-level context *
+ * II. from top-level context *
[kamaki]: file list
(401) UNAUTHORIZED Access denied
[kamaki]: user authenticate
...
[kamaki]
- * maximum typing *
+ * III. maximum typing *
[file]: list
(401) UNAUTHORIZED Access denied
[file]: exit
...
[user]:
- * minimum typing *
+ * IV. minimum typing *
[file]: list
(401) UNAUTHORIZED Access denied
[file]: /user authenticate
Using config
^^^^^^^^^^^^
-The configuration mechanism of kamaki is detailed at the
-`setup section <setup.html>`_ and it is common for both interaction modes. In
-specific, the configuration mechanism is implemented as a command group, namely
-`config`. Using the config commands is as straightforward as any other kamaki
-commands.
+The configuration mechanism of kamaki is detailed in the
+`setup section <setup.html>`_, it is accessible as *config* and it is common for
+both interaction modes. In specific, the configuration mechanism is implemented
+as `config`. Using the config commands is as straightforward as in any other
+group of commands.
It is often useful to set, delete or update a value. This can be managed either
inside the config context or from any command context by using the / prefix.
In example 4.4.1 the user is going to work with only one storage container. The
file commands use the container:path syntax, but if the user sets a container
-name as default, the container name can be omitted. This is possible by setting
-a *file.container* setting.
+name as default, the container name can be omitted.
.. code-block:: console
:emphasize-lines: 1
- Example 4.4.1: Set default storage container
+ Example 4.4.1: Set default storage container (cloud alias: default)
[file]: list
- 1. mycontainer (32MB, 2 objects)
- 2. pithos (0B, 0 objects)
- 3. trash (2MB, 1 objects)
+ mycontainer (32MB, 2 objects)
+ pithos (0B, 0 objects)
+ trash (2MB, 1 objects)
[file]: list mycontainer
- 1. D mydir/
- 2. 20M mydir/rndm_local.file
+ D mydir/
+ 20M mydir/rndm_local.file
- [file]: /config set pithos_container mycontainer
+ [file]: /config set cloud.default.pithos_container mycontainer
[file]: list
- 1. D mydir/
- 2. 20M mydir/rndm_local.file
+ D mydir/
+ 20M mydir/rndm_local.file
After a while, the user needs to work with multiple containers, therefore a
default container is no longer needed. The *pithos_container* setting can be
.. code-block:: console
:emphasize-lines: 1
- Example 4.4.2: Delete a setting option
+ Example 4.4.2: Delete a setting option (cloud: default)
- [file]: /config delete pithos_container
+ [file]: /config delete cloud.default.pithos_container
[file]: list
- 1. mycontainer (32MB, 2 objects)
- 2. pithos (0B, 0 objects)
- 3. trash (2MB, 1 objects)
+ mycontainer (32MB, 2 objects)
+ pithos (0B, 0 objects)
+ trash (2MB, 1 objects)
-Using history
+History modes
^^^^^^^^^^^^^
There are two history modes: session and permanent. Session history keeps
Session history is only available in interactive shell mode. Users can iterate
through past commands in the same session with the ↑ and ↓ keys. Session
-history is not stored, although syntactically correct commands are recorded
-through the permanent history mechanism.
+history is not stored, although commands are recorded through the permanent
+history mechanism.
Permanent history is implemented as a command group and is common to both the
-one-command and shell interfaces. In specific, every syntactically correct
-command is appended in a history file (configured as `history_file` in
-settings, see `setup section <setup.html>`_ for details). Commands executed in
-one-command mode are mixed with the ones run in kamaki shell (also
-see :ref:`using-history-ref` section on this guide).
+one-command and shell interfaces. In specific, every command is appended in a
+history file (configured as `history_file` in settings, see
+`setup section <setup.html>`_ for details). Commands executed in one-command
+mode are mixed with the ones run in kamaki shell (also see
+:ref:`using-history-ref` section on this guide).
Scripting
^^^^^^^^^
.. code-block:: console
:emphasize-lines: 1,12,19,32
- * Download mycontainer1:myfile and upload it to mycontainer2:myfile
+ * Download mycontainer1:myfile and upload it to mycontainer2:myfile *
[kamaki]: file
[file]: copy mycontainer1:somefile mycontainer1:myfile
[file]: download mycontainer1:myfile mylocalfile
+ ...
Download completed
- [file]: upload mylocalfile mycontainer2:myfile
+ [file]: upload mylocalfile mycontainer2:myfile -f
+ ...
Upload completed
* undo the process *
1. file
2. file copy mycontainer1:somefile mycontainer1:myfile
3. file download mycontainer1:myfile mylocalfile
- 4. file upload mylocalfile mycontainer2:myfile
+ 4. file upload mylocalfile mycontainer2:myfile -f
5. file delete mycontainer1:myfile
6. file delete mycontainer2:myfile
7. history
scripting capabilities and combine them with kamaki one-command. Still, the
history-run functionality might prove handy in many occasions.
-Tab completion
-^^^^^^^^^^^^^^
-
-Kamaki shell features tab completion for the first level of command terms of
-the current context. Tab completion pool changes dynamically when the context
-is switched. Currently, tab completion is not supported when / is used
-(see :ref:`accessing-top-level-commands-ref` ).
-
OS Shell integration
^^^^^^^^^^^^^^^^^^^^
Kamaki shell commits command strings to the outside shell and prints the
results, without interacting with it. After a command is finished, kamaki shell
-returns to its initial state, which involves the current directory, as show in
+returns to its initial state, which involves the current directory, as shown in
example 4.8.2
.. code-block:: console
projects / kamaki / blobdiff