Usage
=====
-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.
+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.
+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.
-Setup
------
+Quick 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.html>`_ 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.
-Quick guide
-^^^^^^^^^^^
-
-It is essential for users to get a configuration token (to get in Okeanos.grnet.gr log `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
+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:
.. code-block:: console
+ :emphasize-lines: 1
- $ kamaki set token myt0k3n==
-
-
- Example 1.1.1: Set user token to myt0k3n==
+ Example 1.1: Set authentication URL, user token and cloud alias "default"
-To use the storage service, a user should also provide the corresponding username:
-
-.. code-block:: console
+ $ kamaki config set cloud.default.url <authentication URL>
+ $ kamaki config set cloud.default.token myt0k3n==
- $ kamaki set account user@domain.com
-
-
- 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.
+.. 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
-^^^^^^^^^^^^^^^^^^^^
-In favor of interactive shell behavior:
+--------------------
+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
-* session history with "up"/"down" keys
-* shorter commants with command namespace switching
+In favor of interactive shell:
-In favor of one-command behavior:
+* 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:
* 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
-""""""""""""
+^^^^^^^^^^^^
To use kamaki as a shell, run:
* without any parameters or arguments
.. code-block:: console
+ :emphasize-lines: 1
- $ kamaki
-
-
- Example 2.2.1: Running kamaki shell
+ Example 2.2.1: Run kamaki shell
+ $ 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
- $ kamaki --config myconfig.file
+ Example 2.2.2: Run kamaki shell with custom configuration file
-
- Example 2.2.2: Running kamaki shell with custom configuration file
+ $ kamaki -c myconfig.file
Run as one-command
-""""""""""""""""""
+^^^^^^^^^^^^^^^^^^
To use kamaki as an one-command tool, run:
* with the '-h' or '--help' arguments (help for kamaki one-command)
.. code-block:: console
-
- $kamaki -h
-
+ :emphasize-lines: 1
Example 2.3.1: Kamaki help
+ $kamaki -h
+
* with one or more command parameters:
.. code-block:: console
+ :emphasize-lines: 1
- $ kamaki server list
+ Example 2.3.2: List servers managed by user
+ $ kamaki server list
- Example 2.3.2: List VMs managed by user
+One-command interface
+---------------------
-Commands
-^^^^^^^^
+Using help
+^^^^^^^^^^
-Client commands are grouped by service (see example 3.1.1 on how to list available 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 help provides information on available commands (description, syntax and
+corresponding optional arguments).
-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.
+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
- $ kamaki store list mycontainer
+ Example 3.1.1: kamaki help shows available parameters and command groups
- Example 3.1.1: List stored files in container mycontainer.
+ $ kamaki -h
+ usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
+ [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
-Example 2.3.2 showcases a command without parameters (the group is "server", the command is "list").
+ 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
+ -c CONFIG, --config CONFIG
+ Path to configuration file
+ -o OPTIONS, --options OPTIONS
+ Override a config value
+ --cloud CLOUD Chose a cloud to connect to
+ -h, --help Show help message
+
+ Options:
+ - - - -
+ 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
+ history: Kamaki command history
-The "server" command group is also refered in the following example.
.. code-block:: console
+ :emphasize-lines: 1,2
- $ kamaki server info 42
+ Example 3.1.2: Cyclades help contains all first-level commands of Cyclades
+ command group
+ $ kamaki server -h
+ usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG]
+ [-o OPTIONS] [--cloud CLOUD] [-h]
- Example 3.1.2 Show information about a user-managed VM with id 42
+ 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
+ -c CONFIG, --config CONFIG
+ Path to configuration file
+ -o OPTIONS, --options OPTIONS
+ Override a config value
+ --cloud CLOUD Chose a cloud to connect to
+ -h, --help Show help message
+
+ Options:
+ - - - -
+ 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]
-Client commands can feature an arbitarry number of terms:
+.. code-block:: console
+ :emphasize-lines: 1,2
+
+ Example 3.1.3: Help for command "server list" with syntax, description and
+ available user options
-.. code-block:: text
+ $ kamaki server list -h
+ usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS]
+ [--cloud CLOUD] [-h] [--since SINCE] [--enumerate]
+ [-l] [--more] [-n LIMIT] [-j]
- kamaki <group> <cmd term 1> <cmd term 2> ... <cmd term N> [arguments]
+ List Virtual Machines accessible by user
-Although there are no multi-termed client commands until version 0.6.1 , the feature is supported and might be used in feature extentions.
+ 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 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:
-The following pattern applies to all client commands up to version 0.6.1:
+Using history
+^^^^^^^^^^^^^
-.. code-block:: text
+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>`_).
- kamaki <group> <command> [arguments]
+Every command is appended at the end of that file. In order to see how to use
+history, use the kamaki help system:
-The commands supported in version 0.6.1 are described bellow, grouped by service. The examples showcase a sample set of group commands. The kamaki interactive shell has been chosen as the execution enviroment:
+.. code-block:: console
+ :emphasize-lines: 1
-astakos (Identity Manager)
-""""""""""""""""""""""""""
+ Example 3.2.1: Available history options
-.. code-block:: text
- authenticate: Authenticate a user
+ $ kamaki history -h
+ Options:
+ - - - -
+ clean: Clean up history (permanent)
+ run : Run previously executed command(s)
+ show : Show intersession command history
-Showcase: get user information, provided the token was set
+The following example showcases how to use history in kamaki
.. code-block:: console
- :emphasize-lines: 3-11
+ :emphasize-lines: 1
- [kamaki]:astakos
- [astakos]:authenticate
- auth_token : s0m3t0k3nth@t1sr3m0v3d==
- auth_token_created: 2012-11-13T14:12:40.917034
- auth_token_expires: 2012-12-13T14:12:40.917035
- groups :
- default
- has_credits : False
- has_signed_terms : True
- uniq : myaccount@grnet.gr
- username : 4215th3b357num9323v32
- [astakos]:
+ Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
+
-flavor (Compute/Cyclades)
-"""""""""""""""""""""""""
+ $ kamaki history 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
+
+Debug and logging
+^^^^^^^^^^^^^^^^^
+
+Debug
+"""""
+
+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
+
+
+Logging
+"""""""
+
+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 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 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
+
+ to disable it, set it to `off`::
+
+ kamaki config set log_data off
+
+ or delete it::
+
+ kamaki config delete log_data
-.. code-block:: text
+* X-Auth-Token header is not logged by default
+ to enable logging the X-Auth-Token header, set log_token to `on`::
- info: Get flavor details
- list: List flavors
+ kamaki config set log_token on
-Showcase: show details for flavor with id 43
+ to disable it, set it to `off`::
+
+ kamaki config set log_token off
+
+ or delete it::
+
+ kamaki config delete log_token
+
+* 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::
+
+ kamaki config set log_pid on
+
+ to disable it, set if to off::
+
+ kamaki config set log_pid off
+
+ or delete it::
+
+ kamaki config delete log_pid
+
+One-command features
+^^^^^^^^^^^^^^^^^^^^
+
+Kamaki commands can be used along with advanced shell features.
.. code-block:: console
- :emphasize-lines: 3-8
-
- [kamaki]: flavor
- [flavor]: info 43
- SNF:disk_template: drbd
- cpu : 4
- disk : 10
- id : 43
- name : C4R2048D10
- ram : 2048
- [flavor]:
-
-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
-
-Showcase: show a list of public images, list the properties of Debian Base
+ :emphasize-lines: 1
+
+ Example 3.4.1: List the trash container contents, containing c1_
+
+
+ $ kamaki file list -o cloud.default.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).
+
+.. 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
+-----------------
+
+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 successful, the kamaki shell prompt
+changes to present the new context ("*file*" in example 4.1.1).
.. code-block:: console
- :emphasize-lines: 3-13,15-22
-
- [kamaki]:image
- [image]:list
- 1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS (Long Term Support))
- 1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
- 18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS (Long Term Support))
- 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)
- [image]:properties b2dffe52-64a4-48c3-8a4c-8214cc3165cf
- description : Debian 6.0.6 (Squeeze) Base System
- gui : No GUI
- kernel : 2.6.32
- os : debian
- osfamily : linux
- root_partition: 1
- sortorder : 1
- users : root
- [image]:
-
-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
-
-Showcase: Create a server: Show create help, find a flavor and an image make a server. Wait for server to be build, get server details. Note that the progress bar feature is optional (see )
+ :emphasize-lines: 1
+
+ Example 4.1.1: Start kamaki and switch to file context
+
+
+ $ kamaki
+ [kamaki]: file
+ [file]:
+
+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.
.. code-block:: console
- :emphasize-lines: 3-16,18-33,35-40,42-56,58,59,61-66
+ :emphasize-lines: 1
- [kamaki]:server
- [server]:create -h
- usage: create <name> <flavor id> <image id>
- [--personality PERSONALITY] [-h] [--config CONFIG]
+ Example 4.1.2: Exit file context and then exit kamaki
- Create a server
+ [file]: exit
+ [kamaki]: exit
+ $
- optional arguments:
- -v, --verbose More info at response
- --personality PERSONALITY
- add a personality file
- -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
- [server]:/image list
- 1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)
- 1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
- |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)
- [server]:/flavor info 1
- SNF:disk_template: drbd
- cpu : 1
- disk : 20
- id : 1
- name : C1R1024D20
- ram : 1024
- [server]:create 'My Small Debian Server' 1 b2dffe52-64a4-48c3-8a4c-8214cc3165cf
- adminPass: L8gu2wbZ94
- created : 2012-11-23T16:56:04.190813+00:00
- flavorRef: 1
- hostId :
- id : 11687
- imageRef : b2dffe52-64a4-48c3-8a4c-8214cc3165cf
- metadata :
- values:
- os : debian
- users: root
- name : My Small Debian Server
- progress : 0
- status : BUILD
- suspended: False
- updated : 2012-11-23T16:56:04.761962+00:00
- [server]:wait 11687
- Server 11687 still in BUILD mode ||||||||||||||||| | 80% - 3s
- Server 11687 is now in ACTIVE mode
- [server]:
-
-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
-
-Showcase: Connect a network to a VM: create a network, list available VMs, connect to 'My Small Debian Server', check network info and server connectivity.
+A user might **browse** through different contexts during one session.
.. code-block:: console
- :emphasize-lines: 1, 2, 5, 14, 15, 30, 42
-
- [kamaki]:network
- [network]:/server list
- 11687 (My Small Debian Server)
- 11688 (An Ubuntu server)
- [network]:connect
- Connect a server to a network
- Syntax: connect <server id> <network id>
- --config : Path to configuration file
- -d,--debug : Include debug output
- -h,--help : Show help message
- -i,--include: Include protocol headers in the output
- -s,--silent : Do not output anything
- -v,--verbose: More info at response
- [network]: connect 11687 1409
- [network]:info 1409
- attachments:
- nic-11687-1
- cidr : 192.168.1.0/24
- cidr6 : None
- created : 2012-11-23T17:17:20.560098+00:00
- dhcp : True
- gateway : None
- gateway6 : None
- id : 1409
- name : my network
- public : False
- status : ACTIVE
- type : PRIVATE_MAC_FILTERED
- updated : 2012-11-23T17:18:25.095225+00:00
- [network]:/server addr 11687
- id: nic-11687-1
- ipv4 : 192.168.1.1
- ipv6 : None
- mac_address: aa:0f:c2:0b:0e:85
- network_id : 1409
- firewallProfile: DISABLED
- id: nic-11687-0
- ipv4 : 83.212.106.111
- ipv6 : 2001:648:2ffc:1116:a80c:f2ff:fe12:a9e
- mac_address : aa:0c:f2:12:0a:9e
- network_id : 1369
- [network]:
-
-
-
-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
+ :emphasize-lines: 1
-One-command interface
-^^^^^^^^^^^^^^^^^^^^^
+ Example 4.1.3: Execute list command in different contexts
-Kamaki usage as a one-command tool is detailed in this section
+ $ kamaki
+ [kamaki]: config
+ [config]: list
+ ... (configuration options listing) ...
+ [config]: exit
+ [kamaki]: file
+ [file]: list
+ ... (storage containers listing) ...
+ [file]: exit
+ [kamaki]: server
+ [server]: list
+ ... (servers 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 4.1.3 and 4.1.4 are equivalent.
-Using help
-""""""""""
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.1.4: Execute different "list" commands from top context
+
+
+ [kamaki]: config list
+ ... (configuration options listing) ...
+ [kamaki]: file list
+ ... (storage container listing) ...
+ [kamaki]: server list
+ ... (servers listing) ...
+ [kamaki]:
+
+Using 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.
-Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments.
+Context-level help syntax::
-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.
+ * 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
.. code-block:: console
+ :emphasize-lines: 1
- $ kamaki -h
- usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd> [-v] [-s] [-V] [-d] [-i]
- [--config CONFIG]
- [-o OPTIONS] [-h]
+ Example 4.2.1: Get available commands and then get help in a context
- 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
+ [kamaki]: help
+
+ kamaki commands:
+ ================
+ user config flavor history image network server file ...
+
+ 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 related to the cloud client setup and use, while the later are
+context-shell functions.
- Example 4.1.1: kamaki help shows available parameters and command groups
+**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 extensions>
+
+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 4.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
- $ kamaki cyclades -h
- usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
- [-o OPTIONS] [-h]
+ [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
- -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
+ -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
- 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
+There are many ways of producing a help message, as shown in example 4.2.3
.. code-block:: console
+ :emphasize-lines: 1
- $ kamaki server list -h
- usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
- [-o OPTIONS] [-h] [-l]
+ Example 4.2.3: Equivalent calls of command-level help for config-set
- 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
+ [config]: set -h
+ [config]: set --help
+ [kamaki]: config set -h
+ [kamaki]: config set --help
+ [file]: /config set -h
+ [server]: /config set --help
+.. _accessing-top-level-commands-ref:
- Example 4.1.3: Help for command "server list" with syntax, description and avaiable user options
+Accessing top-level commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Using history
-"""""""""""""
+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::
-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>`_).
+ * 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
-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:
+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
- $ kamaki history -h
+ 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
...
- clean: Clean up history
- show : Show history
+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.
- Example 4.2.1: Available history options
+.. code-block:: console
+ :emphasize-lines: 1
-The following example showcases how to use history in kamaki
+ 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
- $ kamaki history clean --match clean
- $ kamaki server list
+ 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
...
- $ 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
+ $
+ * 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]:
- Example 4.2.2: Clean up everything, run a kamaki command, show full and filtered history
+ * IV. minimum typing *
+ [file]: list
+ (401) UNAUTHORIZED Access denied
+ [file]: /user authenticate
+ ...
+ [file]:
-Debug
-"""""
+.. hint:: To exit kamaki shell while in a context, try */exit*
-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.
+Using config
+^^^^^^^^^^^^
-To run kamaki in debug mode use the -d or --debug option
+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.
-Verbose
-"""""""
+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.
-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.
+.. Note:: config updates in kamaki shell persist even after the session is over
-To run kamaki in verbose mode use the -v or --verbose option
+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.
-Client 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
-Kamaki commands can be used along with advanced shell features.
+ 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
- $ kamaki server list -l > vmlist.txt
+ Example 4.4.2: Delete a setting option (cloud: default)
- Example 4.4.1: Store a vm list in file vmlist.txt in a unix shell
+ [file]: /config delete cloud.default.pithos_container
+
+ [file]: list
+ mycontainer (32MB, 2 objects)
+ pithos (0B, 0 objects)
+ trash (2MB, 1 objects)
+
+History modes
+^^^^^^^^^^^^^
+
+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 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 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
+^^^^^^^^^
+
+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
+
+.. code-block:: console
+ :emphasize-lines: 1,12,19,32
+
+ * 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 -f
+ ...
+ Upload completed
+
+ * undo the process *
+ [file]: !rm mylocalfile
+ [file]: delete mycontainer1:myfile
+ [file]: delete mycontainer2:myfile
+
+ * check history entries *
+ [file]: exit
+ [kamaki]: history
+ [history]: show
+ 1. file
+ 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
+ 7. history
+ 8. history show
+
+ *repeat the process *
+ [history]: run 2-4
+ <file copy mycontainer1:somefile mycontainer1:myfile>
+ <file download mycontainer1:myfile mylocalfile>
+ Download completed
+ <file upload mylocalfile mycontainer2:myfile>
+ Upload completed
+
+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.
+
+OS Shell integration
+^^^^^^^^^^^^^^^^^^^^
+
+Kamaki shell features the ability to execute OS-shell commands from any
+context. This can be achieved by typing *!* or *shell*::
+
+ [kamaki_context]: !<OS shell command>
+ ... OS shell command output ...
+
+ [kamaki_context]: shell <OS shell command>
+ ... OS shell command output ...
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.7.1: Run unix-style shell commands from kamaki shell
+
+
+ [kamaki]: !ls -al
+ total 16
+ drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
+ drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
+ -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
+
+ [kamaki]: shell cp kamaki-logo.png logo-copy.png
+
+ [kamaki]: shell ls -al
+ total 24
+ drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
+ drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
+ -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
+ -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png
+
+
+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 shown in
+example 4.8.2
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.8.2: Attempt (and fail) to change working directory
-Interactive shell
-^^^^^^^^^^^^^^^^^
+ [kamaki]: !pwd
+ /home/username
+ [kamaki]: !cd ..
-Creating applications over the Clients API
-------------------------------------------
+ [kamaki]: shell pwd
+ /home/username
projects / kamaki / blobdiff