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 features commands of the form::
-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] <object> <action> [identifier(s)] <non-positional arguments>
+ e.g.,
+ kamaki user info --username=user@example.com
+
+A detailed list of the command specifications can be found in
+`Commands <commands.html>`_ section.
+
+All commands can run either from the host shell or through the kamaki
+interactive shell:
+
+.. code-block:: console
+
+ # Run from host shell
+ $ kamaki user info
+ ... RESULTS ...
+
+ # Run from kamaki interactive shell
+ $ kamaki-shell
+ [kamaki]: user info
+ ... RESULTS ...
+
+In the later, the term "one-command" will be user to refer to running kamaki
+commands from host shell, while the term "shell" will refer to the kamaki's own
+interactive shell
+
+.. note:: This section refers to the kamaki CLI. Developers and people who write
+ scripts, should rather use the the
+ `Clients lib <developers/code.html#the-clients-api>`_ instead of the kamaki
+ CLI.
Quick Setup
-----------
-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.
+Kamaki interfaces rely on a list of configuration options. Check the
+`Setup <setup.html>`_ guide for a full list.
-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:
+As rule of the thump, it is enough to set a cloud authentication URL and TOKEN:
.. code-block:: console
:emphasize-lines: 1
- Example 1.1: Set authentication URL, user token and cloud alias "default"
+ Example 1.1: Set authentication URL, user token for cloud alias "default"
$ 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.
+ the user.
Shell vs one-command
--------------------
-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.
+
+Kamaki users can access Synnefo services through either the kamaki shell or the
+one-command interface. Both systems feature identical responses and error
+messages, since they rely on the same internal command and library API
+implementation. However, there are some minor differences.
In favor of interactive shell:
-* 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
+* shorter commands (context switching)
+* tab completion for commands (if supported by host shell)
+* kamaki-specific history with ↑ or ↓ keys (if supported by host shell)
* re-run old commands with /history
In favor of one-command:
-* can be used along with advanced shell features (pipelines, redirection, etc.)
+* users take advantage of host 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
Example 2.2.1: Run kamaki shell
- $ kamaki
+ $ kamaki-shell
* with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
'- - version'.
Example 2.2.2: Run kamaki shell with custom configuration file
- $ kamaki -c myconfig.file
+ $ kamaki-shell -c myconfig.file
+
+ Example 2.2.3: Run kamaki shell so as to use a specific cloud
+
+ $ kamaki-shell --cloud=my_demo_cloud
+
+ Example 2.2.4: Run kamaki shell with verbosity (shows HTTP requests)
+
+ $ kamaki-shell -v
+.. note:: Valid arguments can be combined e.g., it is ok to run a shell with
+ verbosity and a specific cloud::
+
+ $ kamaki-shell -v --cloud=my_demo_cloud
Run as one-command
^^^^^^^^^^^^^^^^^^
$kamaki -h
-* with one or more command parameters:
+* with one or more command parameters (object and, maybe, action):
.. code-block:: console
:emphasize-lines: 1
Using help
^^^^^^^^^^
-Kamaki help provides information on available commands (description, syntax and
-corresponding optional arguments).
+Kamaki help provides information on commands (description, syntax).
-To see the command groups, use -h or --help (example 1.3.1). The
+To see the command groups (objects), 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).
$ kamaki -h
usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
- [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
+ [-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
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
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
+ resource: Astakos/Account API commands for resources
+ group: Pithos+/Storage user groups
+ network: Networking API network commands
+ subnet: Networking API network commands
+ ip: Networking API floatingip commands
+ image: Cyclades/Plankton API image commands
+ imagecompute: Cyclades/Compute API image commands
+ quota: Astakos/Account API commands for quotas
+ sharer: Pithos+/Storage sharers
+ project: Astakos project API commands
+ user: Astakos/Identity API commands
+ file: Pithos+/Storage object level API commands
+ container: Pithos+/Storage container level API commands
flavor: Cyclades/Compute API flavor commands
+ server: Cyclades/Compute API server commands
config: Kamaki configurations
- image: Cyclades/Plankton API image commands
- image compute: Cyclades/Compute API image commands
+ port: Networking API network commands
history: Kamaki command history
-
+ kamaki-shell: An interactive command line shell
.. code-block:: console
:emphasize-lines: 1,2
command group
$ kamaki server -h
- usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG]
+ usage: kamaki server <...> [-v] [-s] [-V] [-d] [-c CONFIG]
[-o OPTIONS] [--cloud CLOUD] [-h]
optional arguments:
-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
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
+ modify: Modify attributes of a virtual server
create: Create a server (aka Virtual Machine)
- list: List Virtual Machines accessible by user
+ list: List virtual servers 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]
+ delete: Delete a virtual server
.. code-block:: console
:emphasize-lines: 1,2
available user options
$ kamaki server list -h
- usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS]
+ usage: kamaki server list [-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS]
[--cloud CLOUD] [-h] [--since SINCE] [--enumerate]
[-l] [--more] [-n LIMIT] [-j]
-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
Using history
^^^^^^^^^^^^^
-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 command history is stored in '${HOME}/.kamaki.history' by default). To
+set a custom history file path users must set the history.file config option
+(more on config options `here <setup.html#editing-options>`_).
Every command is appended at the end of that file. In order to see how to use
history, use the kamaki help system:
Example 3.2.1: Available history options
-
$ kamaki history -h
Options:
- - - -
run : Run previously executed command(s)
show : Show intersession command history
-The following example showcases how to use history in kamaki
-
-.. code-block:: console
- :emphasize-lines: 1
Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
-
$ kamaki history clean
$ kamaki server list
"""""
When in debug mode, kamaki outputs some useful debug information (stack trace
-and http logs). Kamaki in debug mode cancels suppression of warning messages.
+and http logs). Kamaki in debug mode cancels the suppression of warning
+messages too.
To run kamaki in debug mode use the -d or --debug option.
"""""""
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.
+translates command semantics to REST and handles the response. Users who need
+to have access to these commands can use the verbose mode that outputs the
+HTTP Request and Response details along with the (possibly modified) regular
+command output.
-To run kamaki in verbose mode use the *-v/- - verbose* option
+To run kamaki in verbose mode use the *-v/- - verbose* argument, it goes with
+everything.
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)
+options
-.. tip:: Use the -o runtime option to enable config options on the fly, e.g, to
- include http data:
+.. tip:: Use the -o argument to include http data in the output:
.. code-block:: console
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 logs in a file specified by the *log_file* option which defaults to
+*${HOME}/.kamaki.log*. This configuration option can be modified::
kamaki config set log_file /new/log/file/path
One-command features
^^^^^^^^^^^^^^^^^^^^
-Kamaki commands can be used along with advanced shell features.
-
.. code-block:: console
: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
+ $ kamaki file list -v -o log_token=on
+ ...
+ X-Auth-Token: s0m3-3x4mp1e-70k3n
+ ...
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).
+For security reasons, all commands hide the authentication token from outputs
+and the logs. In example 3.4.1 the token is not hided, because of the
+*log_token=on* 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>*
+.. warning:: Complimentary output i.e., http logs and informative messages are
+ printed to standard error stream
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
+The command namespaces in kamaki interactive shell are called **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
[config]: exit
[kamaki]: file
[file]: list
- ... (storage containers listing) ...
+ ... (file listing) ...
[file]: exit
[kamaki]: server
[server]: list
[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.
+Users can avoid switching between contexts: all commands can run from the
+**top context** e.g., examples 4.1.3 and 4.1.4 are equivalent.
.. 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) ...
+ ... (file listing) ...
[kamaki]: server list
... (servers listing) ...
[kamaki]:
+While in a context, other contexts are accessible by using a **/** as shown in
+the following example:
+
+.. code-block:: console
+
+ Example 4.1.5: Execute different "list" commands from the config context
+
+ [kamaki]: config
+ [config]: list
+ ... (configuration option listing) ...
+ [config]: /file list
+ ... (file listing) ...
+ [config]: /server list
+ ... (servers listing) ...
+ [config]:
+
Using Help
^^^^^^^^^^
Example 4.2.1: Get available commands and then get help in a context
-
[kamaki]: help
kamaki commands:
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.
+are the main functionality of kamaki, while the later are used to manage the
+kamaki-shell.
**Command-level help** prints the syntax, arguments and description of a
specific (terminal) command
[file]: /config set -h
[server]: /config set --help
-.. _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)
-
History modes
^^^^^^^^^^^^^
* Download mycontainer1:myfile and upload it to mycontainer2:myfile *
[kamaki]: file
- [file]: copy mycontainer1:somefile mycontainer1:myfile
- [file]: download mycontainer1:myfile mylocalfile
+ [file]: copy /mycontainer1/somefile /mycontainer1/myfile
+ [file]: download /mycontainer1/myfile mylocalfile
...
Download completed
- [file]: upload mylocalfile mycontainer2:myfile -f
+ [file]: upload mylocalfile /mycontainer2/myfile -f
...
Upload completed
* undo the process *
[file]: !rm mylocalfile
- [file]: delete mycontainer1:myfile
- [file]: delete mycontainer2:myfile
+ [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
+ 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>
+ <file copy /mycontainer1/somefile /mycontainer1/myfile>
+ <file download /mycontainer1/myfile mylocalfile>
Download completed
- <file upload mylocalfile mycontainer2:myfile>
+ <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.
+The suggested best practice for scripting is python scripts that import the
+`kamaki.clients` library. Another option is host shell scripting (e.g., bash)
+with kamaki one-command. Still, the history-run functionality might prove handy
+in many occasions.
OS Shell integration
^^^^^^^^^^^^^^^^^^^^
projects / kamaki / commitdiff