Synnefo » ./kamaki

    :emphasize-lines: 1

    $ kamaki set token myt0k3n==

    :emphasize-lines: 1

    $ kamaki set account user@domain.com

    :emphasize-lines: 1

    Example 2.2.1: Run kamaki shell

    $ kamaki

    :emphasize-lines: 1

    Example 2.2.2: Run kamaki shell with custom configuration file

    $ kamaki --config myconfig.file

    :emphasize-lines: 1

    $kamaki -h

    :emphasize-lines: 1

    $ kamaki server list

    :emphasize-lines: 1

    $ kamaki store list mycontainer

    :emphasize-lines: 1

    $ kamaki server info 42

    :emphasize-lines: 1,4

    * Enter astakos context *

    * Authenticate user *

    :emphasize-lines: 1,4

    * Enter flavor context *

    * Get details about flavor with id 43 *

Showcase: Pick an image and list the properties

    :emphasize-lines: 1,4,18

    * Enter image context *

    * list all available images *

    1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)

    18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)

    * Get properties of image with id b2dffe52-64a4-48c3-8a4c-8214cc3165cf *

Showcase: Create a server.

    :emphasize-lines: 1,4,21,35,44,62

    * Enter server context *

    * See server-create help *

    * List all available images *

    18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)

    6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)

    6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)

    78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)

    86bc2414-0fb3-4898-a637-240292243302 (Fedora)

    926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)

    b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)

    baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)

    c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)

    * See details of flavor with id 1 *

    * Create a debian server named 'My Small Debian Server'

    * wait for server to build (optional) *

.. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts

Showcase: Connect a network to a VM

    :emphasize-lines: 1,4,9,24,27,44

    * Enter network context *

    * List user-owned VMs *

    * Try network-connect (to get help) *

    Syntax error

    usage: connect <server id> <network id> [-s] [-h] [-i] [--config CONFIG]

    * Connect VM with id 11687 to network with id 1409

    * Get details on network with id 1409

    * Get connectivity details on VM with id 11687 *

.. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts

Showcase: Upload and download a file.

.. code-block:: console

    :emphasize-lines: 1,7,11,16,21,29,33,37,41,44,51,55,60,64

    * Create a random binarry file at current OS path *

    [kamaki]:!dd bs=4M if=/dev/zero of=rndm_local.file count=5

    5+0 records in

    5+0 records out

    20971520 bytes (21 MB) copied, 0.016162 s, 1.3 GB/s

    * Enter store context *

    [kamaki]:store

    * Check local file *

    [store]:!ls -lh rndm_local.file

    -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file

    * Create two containers *

    [store]:create mycont1

    [store]:create mycont2

    * List accessible containers *    

    [store]:list

    1. mycont1 (0B, 0 objects)

    2. mycont2 (0B, 0 objects)

    3. pithos (0B, 0 objects)

    4. trash (0B, 0 objects)

    * Upload local file to 1st container *

    [store]:upload rndm_local.file mycont1

    * Check if file has been uploaded *

    [store]:list mycont1

    1.    20M rndm_local.file

    * Create director mydir on second container *

    [store]:mkdir mycont2:mydir

    * Move file from 1st to 2nd container (and in the directory) *

    [store]:move mycont1:rndm_local.file mycont2:mydir/rndm_local.file

    * Check the container of both containers *

    [store]:list mycont1

    [store]:list mycont2

    1.      D mydir/

    2.    20M mydir/rndm_local.file

    * Copy file from 2nd to 1st container, with a new name *

    [store]:copy mycont2:mydir/rndm_local.file mycont1:rndm_remote.file

    * Check pasted file *

    [store]:list mycont1

    1.    20M rndm_remote.file

    * Download pasted file to local filesystem *

    [store]:download mycont1:rndm_remote.file rndm_remote.file

    * Check if file is downloaded and if it is the same to original *

    [store]:!ls -lh *.file

    -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file

    -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:42 rndm_remote.file

    [store]:!diff rndm_local.file rndm_remote.file

.. Note:: In kamaki shell, ! is used to execute OS shell commands (bash in the above)

    :emphasize-lines: 1

    Example 4.1.1: kamaki help shows available parameters and command groups

    usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>

        [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h]

.. code-block:: console

    :emphasize-lines: 1

    Example 4.1.2: Cyclades help contains all first-level commands of cyclades command group

.. code-block:: console

    :emphasize-lines: 1

    Example 4.1.3: Help for command "server list" with syntax, description and avaiable user options

    usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l]

    :emphasize-lines: 1

    Example 4.2.1: Available history options

    :emphasize-lines: 1

    Example 4.2.2: Clean up everything, run a kamaki command, show full and filtered history

One-command features

""""""""""""""""""""

    :emphasize-lines: 1

    Example 4.4.1: Print username for token us3rt0k3n== using grep

    $ kamaki astakos authenticate -o token=us3rt0k3n== | grep uniq

    uniq        : user@synnefo.org

The -o argument can be used to overide temporarily various (set or unset) options. In one command, all -o options are forgoten just after the command had been completed, and the previous settings are restored (the configuration file is not modified).

The astakos-authenticate command in example 4.4.1 run against an explicitly provided token, which temporarily overode the token provided in the configuration file.

Kamaki interactive shell is details in this section

Command Contexts

""""""""""""""""

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 succesful, the kamaki shell prompt changes to present the new context ("store" in example 5.1.1).

.. code-block:: console

    :emphasize-lines: 1

    Example 5.1.1: Enter store commands context/group

    $ kamaki

    [kamaki]:store

    [store]:

Type **exit** or **ctrl-D** 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 programm.

.. code-block:: console

    :emphasize-lines: 1

    Example 5.1.2: Exit store context and then exit kamaki

    [store]: exit

    [kamaki]: exit

    $

A user might **browse** through different contexts during one session.

.. code-block:: console

    :emphasize-lines: 1

    Example 5.1.3: Execute list command in different contexts

    $ kamaki

    [kamaki]:config

    [config]:list

    ... (configuration options listing) ...

    [config]:exit

    [kamaki]:store

    [store]:list

    ... (storage containers listing) ...

    [store]:exit

    [kamaki]:server

    [server]:list

    ... (VMs listing) ...

    [server]: exit

    [kamaki]:

Users have the option to avoid switching between contexts: all commands can run from the **top context**. As a result, examples 5.1.3 and 5.1.4 are equivalent.

.. code-block:: console

    :emphasize-lines: 1

    Example 5.1.4: Execute different "list" commands from top context

    [kamaki]:config list

    ... (configuration options listing) ...

    [kamaki]:store list

    ... (storage container listing) ...

    [kamaki]:server list

    ... (VMs listing) ...

    [kamaki]:

Help

""""

There are two help mechanisms: a context-level and a command-level.

**Context-level help** lists the available commands in a context and can also offer a short description for each command.

Context-level help syntax::

    * Show available commands in current context *

    [context]:help

    [context]:?

    * Show help for command cmd *

    [context]:help cmd

    [context]:?cmd

The context-level help results change from context to context

.. code-block:: console

    :emphasize-lines: 1

    Example 5.2.1: Get available commands, pick a context and get help there as well

    [kamaki]:help

    kamaki commands:

    ================

    astakos  config  flavor  history  image  network  server  store

    interactive shell commands:

    ===========================

    exit  help  shell

    [kamaki]:?config

    Configuration commands (config -h for more options)

    [kamaki]:config

    [config]:?

    config commands:

    ================

    delete  get  list  set

    interactive shell commands:

    ===========================

    exit  help  shell

    [config]:help set

    Set a configuration option (set -h for more options)

In context-level, there is a distinction between kamaki-commands and interactive shell commands. The former are available in one-command mode and are releated 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 syntax::

    * Get help for command cmd1 cmd2 ... cmdN *

    [context]:cmd1 cmd2 ... cmdN -h

    <syntax>

    <description>

    <arguments and possible extentions>

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.

.. code-block:: console

    :emphasize-lines: 1

    Example 5.2.2: Get command-level help for config and config-set

    [kamaki]:config --help

    config: Configuration commands

    delete:  Delete a configuration option (and use the default value)

    get   :  Show a configuration option

    list  :  List configuration options

    set   :  Set a configuration option

    [kamaki]:config

    [config]:set -h

    usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]

    Set a configuration option

    optional arguments:

      -v, --verbose    More info at response

      -d, --debug      Include debug output

      -h, --help       Show help message

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

      --config CONFIG  Path to configuration file

      -s, --silent     Do not output anything

There are many ways of producing a help message, as shown in example 5.2.3

.. code-block:: console

    :emphasize-lines: 1

    Example 5.2.3: Equivalent calls of command-level help for config-set

    [config]:set -h

    [config]:set -help

    [kamaki]:config set -h

    [kamaki]:config set --help

    [store]:/config set -h

    [server]:/config set --help

Accessing top-level commands

""""""""""""""""""""""""""""

When working in a context, it is often usefull 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 (5.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:

* the name of the new VM

* 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 doesn't know the flavor or image id of preference. Therefore, it is nessecary to list all available flavors (flavor-list) or images (image-list. Both commands belong to different contexts.

.. code-block:: console

    :emphasize-lines: 1

    Example 5.3.1: Create a VM from server context

    [server]:create -h

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

    ...

    [server]:/flavor list

    ...

    20. AFLAVOR

        SNF:disk_template:  drbd

        cpu              :  4

        disk             :  10

        id               :  43

        ram              :  2048

    [server]:/image 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 (5.3.2) showcases how to aquire and modify configuration settings from a different context. In this case, user token changes while the user is working, so a token modification is needed.

.. code-block:: console

    :emphasize-lines: 1

    Example 5.3.2: Set a new token from store context

    [store]:list

    (401) UNAUTHORIZED Access denied

    [store]:/astakos authenticate

    (401) UNAUTHORIZED Invalid X-Auth-Token

    [store]:/config get token

    my3xp1r3dt0k3n==

    [store]:/config set token myfr35ht0k3n==

    [store]:/config get token

    myfr35ht0k3n==

    [store]:list

    1.  pithos (10MB, 2 objects)

    2.  trash (0B, 0 objects)

The following example presents some equivalent calls that call *astakos-authenticate* after a *store-list* 401 failure.

.. code-block:: console

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

    Example 5.3.3: Equivalent astakos-authenticate calls after a store-list 401 failure

    * one-command *

    $ kamaki store list

    (401) UNAUTHORIZED Access denied

    $ kamaki astakos authenticate

    ...

    $

    * from top-level context *

    [kamaki]:store list

    (401) UNAUTHORIZED Access denied

    [kamaki]:astakos authenticate

    ...

    [kamaki]

    * maximum typing *

    [store]:list

    (401) UNAUTHORIZED Access denied

    [store]:exit

    [kamaki]:astakos

    [astakos]:authenticate

    ...

    [astakos]:exit

    [kamaki]:store

    [store]:

    * minimum typing *

    [store]: list

    (401) UNAUTHORIZED Access denied

    [store]:/astakos authenticate

    ...

    [store]:

Config

""""""

History

"""""""

Tab completion

""""""""""""""

OS Shell integration

""""""""""""""""""""

Creating applications with the Clients API