Synnefo » ./kamaki

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

`Clients lib <developers/code.html#the-clients-api>`_ section.

Kamaki interfaces rely on a list of configuration options. A detailed guide for

setting up kamaki can be found in the `Setup <setup.html>`_ section.

As rule of the thump, it is enough to set the authentication URL and user token

for the cloud kamaki should communicate with by default:

    Example 1.1: Set default authentication user and token

    $ kamaki config set remote.default.url <authentication URL>

    $ kamaki config set remote.default.token myt0k3n==

Kamaki users can access synnefo services through either the interactive shell

or the one-command behaviors. 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.

* tab completion for commands (if supported by host OS)

* session history with ↑ or ↓ keys

Kamaki help is used to list available commands with 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.

        [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]

      -c CONFIG, --config CONFIG

                            Path to configuration file

      --cloud CLOUD         Chose a remote cloud to connect to

    config  :  Kamaki configurations

    file    :  Pithos+/Storage API commands

    flavor  :  Cyclades/Compute API flavor commands

    history :  Kamaki command history

    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

    :emphasize-lines: 1,2

    Example 3.1.2: Cyclades help contains all first-level commands of Cyclades

    command group

    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG]

                               [-o OPTIONS] [--cloud CLOUD] [-h]

      -c CONFIG, --config CONFIG

                            Path to configuration file

      --cloud CLOUD         Chose a remote cloud to connect to

    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

    :emphasize-lines: 1,2

    Example 3.1.3: Help for command "server list" with syntax, description and

    available user options

    usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS]

                              [--cloud CLOUD] [-h] [--since SINCE] [--enumerate]

                              [-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>

    -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

Debug and logging

^^^^^^^^^^^^^^^^^

"""""

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.

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 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:

* HTTP bodies are not logged by default

    to enable logging the full http bodies, set log_data to `on`::

        kamaki config set log_data on

    to disable it, set it to `off`::

        kamaki config set log_data off

    or delete it::

        kamaki config delete log_data

* X-Auth-Token header is not logged by default

    to enable logging the X-Auth-Token header, set log_token to `on`::

        kamaki config set log_token on

    to disable it, set it to `off`::

        kamaki config set log_token off

    or delete it::

        kamaki config delete log_token

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.

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.

    Example 3.4.1: List the trash container contents, containing c1_

    $ kamaki file list -o global.pithos_container=trash| grep c1_

    c1_1370859409.0 20KB

    c1_1370859414.0 9MB

    c1_1370859409.1 110B

The -o argument can be used to temporarily override various (set or unset)

options. In one command, all -o option sets are forgotten just after the

command has been completed, and the previous settings are restored (the

configuration file is not modified).

The file-list command in example 3.4.1 runs with an explicitly provided

pithos_account, which temporarily overrides the one probably provided in the

configuration file (it works even if the user has not set the optional

pithos_account config option).

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).

Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in

Windows) to exit a context and return to the context of origin. If already at

the top context (kamaki), an exit is equivalent to exiting the program.

Users have the option to avoid switching between contexts: all commands can run

from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent.

**Context-level help** lists the available commands in a context and can also

offer a short description for each command.

The context-level help results may change from context to context

    Example 4.2.1: Get available commands and then get help in a context

In context-level, there is a distinction between kamaki-commands and

interactive shell commands. The former are available in one-command mode and

are related to the cloud client setup and use, while the later are

context-shell functions.

**Command-level help** prints the syntax, arguments and description of a

specific (terminal) command

Command-level help mechanism is exactly the same as the one used in

one-command mode. For example, it is invoked by using the -h or --help

parameter at any point.

When working in a context, it is often useful to access other contexts or

top-level commands. Kamaki offers access to top-level commands by using the

`/` prefix, as shown bellow::

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

command is called with three parameters:

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 other example (4.3.2) showcases how to acquire and modify configuration

settings from a different context. In this scenario, the user token expires at

server side while the user is working. When that happens, the system responds

with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid

for the Astakos identity manager of preference) which has to be set to kamaki.

    [file]: /config get remote.default.token

    [file]: /config set remote.default.token myfr35ht0k3n==

    [file]: /config get remote.default

    remote.default.url = https://astakos.example.com/astakos/identity/2.0/

    remote.default.token = myfr35ht0k3n==

.. note:: The error messages on this example where shortened for clarity.

Actual kamaki 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

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.

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.

.. Note:: config updates in kamaki shell persist even after the session is over

All setting changes affect the physical kamaki config file. The config file is

created automatically at callers' home firectory the first time a config option

is set, and lives there as *.kamakirc* . It can be edited with any text editor

or managed with kamaki config commands.

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.

    [file]: /config set pithos_container mycontainer

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

deleted, as shown in example 4.4.2

    [file]: /config delete pithos_container

There are two history modes: session and permanent. Session history keeps

record of all actions in a kamaki shell session, while permanent history

appends all commands to an accessible history file.

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.

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).

The history-run feature allows the sequential run of previous command

executions in kamaki shell.

The following sequence copies and downloads a file from *mycontainer1* ,

uploads it to *mycontainer2* , then undo the proccess and repeats it with

history-run

For powerfull scripting, users are advised to take advantage of their os shell

scripting capabilities and combine them with kamaki one-command. Still, the

history-run functionality might prove handy in many occasions.

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` ).

Kamaki shell features the ability to execute OS-shell commands from any

context. This can be achieved by typing *!* or *shell*::

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

example 4.8.2