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

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 authentication URL, user token and cloud alias "default"

    the user. This term will serve as a cloud alias for kamaki users, and can

    be easily modified.

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.

* 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

* can be used along with advanced shell features (pipelines, redirection, etc.)

* prints debug and verbose messages if needed

* without any parameters or arguments

    $ kamaki

    $ kamaki -c myconfig.file

* with one or more command parameters:

Kamaki help provides information on available commands (description, syntax and

corresponding optional arguments).

To see the command groups, use -h or --help (example 1.3.1). The

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

      -i, --include         Include protocol headers in the output

    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

    image: Cyclades/Plankton API image commands

    image compute:  Cyclades/Compute API image commands

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

      -i, --include         Include protocol headers in the output

    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

    list: List Virtual Machines accessible by user

    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]

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

      -i, --include         Include raw connection data in the output

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

The following example showcases how to use history in kamaki

.. code-block:: console

    :emphasize-lines: 1

and http logs). Kamaki in debug mode cancels suppression of warning messages.

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

options (see next section)

.. tip:: Use the -o runtime option to enable config options on the fly, e.g, to

    include http data:

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 commands can be used along with advanced shell features.

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

    c1_1370859409.0 20KB

    c1_1370859414.0 9MB

    c1_1370859409.1 110B

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

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

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

    ... (storage containers listing) ...

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.

    ... (storage container listing) ...

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

context-shell functions.

.. _accessing-top-level-commands-ref:

Accessing top-level commands

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

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

    * access a command "anothercontext cmd1 cmd2 ... cmdN"

    [context]: /anothercontext cmd1 cmd2 ... cmdN

An example (4.3.1) that showcases how top-level access improves user experience

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 server

* the flavor id

* the image id

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 server from server context

    [server]: create -h

    create <name> <flavor id> <image id> ...

    ...

    [server]: /flavor list

    ...

    43 AFLAVOR

        SNF:disk_template:  drbd

        cpu              :  4

        disk             :  10

        ram              :  2048

    [server]: /image compute list

    1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)

    18a82962-43eb-8f8880af89d7 (Windows 7)

    531aa018-9a40-a4bfe6a0caff (Windows XP)

    6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)

    [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e

    ...

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.

.. code-block:: console

    :emphasize-lines: 1

    Example 4.3.2: Token suddenly expires. Set a new token from file context

    [file]: list

    (401) UNAUTHORIZED Access denied

    [file]: /user authenticate

    (401) UNAUTHORIZED Invalid X-Auth-Token

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

    my3xp1r3dt0k3n==

    [file]: /config set cloud.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 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.

.. code-block:: console

    :emphasize-lines: 1,3,10,17,26

    Example 4.3.3: Equivalent user-authenticate calls after a file-list 401

    * I. without kamaki interactive shell *

    $ kamaki file list

    (401) UNAUTHORIZED Access denied

    $ kamaki user authenticate

    ...

    $

    * II. from top-level context *

    [kamaki]: file list

    (401) UNAUTHORIZED Access denied

    [kamaki]: user authenticate

    ...

    [kamaki]

    * III. maximum typing *

    [file]: list

    (401) UNAUTHORIZED Access denied

    [file]: exit

    [kamaki]: user

    [user]: authenticate

    ...

    [user]:

    * IV. minimum typing *

    [file]: list

    (401) UNAUTHORIZED Access denied

    [file]: /user authenticate

    ...

    [file]:

.. hint:: To exit kamaki shell while in a context, try */exit*

Using config

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

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.

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

.. code-block:: console

    :emphasize-lines: 1

    Example 4.4.1: Set default storage container (cloud alias: default)

    [file]: list

      mycontainer (32MB, 2 objects)

      pithos (0B, 0 objects)

      trash (2MB, 1 objects)

    [file]: list mycontainer

      D mydir/

      20M mydir/rndm_local.file

    [file]: /config set cloud.default.pithos_container mycontainer

    [file]: list

      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

deleted, as shown in example 4.4.2

.. code-block:: console

    :emphasize-lines: 1

    Example 4.4.2: Delete a setting option (cloud: default)

    [file]: /config delete cloud.default.pithos_container

    [file]: list

      mycontainer (32MB, 2 objects)

      pithos (0B, 0 objects)

      trash (2MB, 1 objects)

    [file]: copy mycontainer1:somefile mycontainer1:myfile

    [file]: download mycontainer1:myfile mylocalfile

    [file]: upload mylocalfile mycontainer2:myfile -f

    [file]: delete mycontainer1:myfile

    [file]: delete mycontainer2:myfile

    2.  file copy mycontainer1:somefile mycontainer1:myfile

    3.  file download mycontainer1:myfile mylocalfile

    4.  file upload mylocalfile mycontainer2:myfile -f

    5.  file delete mycontainer1:myfile

    6.  file delete mycontainer2:myfile

    <file copy mycontainer1:somefile mycontainer1:myfile>

    <file download mycontainer1:myfile mylocalfile>

    <file upload mylocalfile mycontainer2:myfile>

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.