4 Kamaki offers command-line interfaces that implement specific command
5 specifications. A detailed list of the command specifications can be found in
6 `Commands <commands.html>`_ section. This guide covers the generic usage of
9 What's more, kamaki offers a clients library for the development of external
10 client applications for Synnefo. The clients library API is detailed in the
11 `Clients lib <developers/code.html#the-clients-api>`_ section.
16 Kamaki interfaces rely on a list of configuration options. A detailed guide for
17 setting up kamaki can be found in the `Setup <setup.html>`_ section.
19 As rule of the thump, it is enough to set the authentication URL and user token
20 for the cloud kamaki should communicate with by default:
22 .. code-block:: console
25 Example 1.1: Set authentication URL, user token and cloud alias "default"
27 $ kamaki config set cloud.default.url <authentication URL>
28 $ kamaki config set cloud.default.token myt0k3n==
30 .. note:: The term *default* can be replaced by any arbitary term chosen by
31 the user. This term will serve as a cloud alias for kamaki users, and can
36 Kamaki users can access Synnefo services through either the interactive shell
37 or the one-command interface. In practice, both systems rely on the same
38 command set implementations and API clients, with identical responses and error
39 messages. Still, there are some differences.
41 In favor of interactive shell:
43 * tab completion for commands (if supported by the user's shell)
44 * session history with ↑ or ↓ keys (if supported by the user's shell)
45 * shorter commands with command context switching
46 * re-run old commands with /history
48 In favor of one-command:
50 * can be used along with advanced shell features (pipelines, redirection, etc.)
51 * can be used in shell scripts
52 * prints debug and verbose messages if needed
56 To use kamaki as a shell, run:
58 * without any parameters or arguments
60 .. code-block:: console
63 Example 2.2.1: Run kamaki shell
67 * with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
70 .. code-block:: console
73 Example 2.2.2: Run kamaki shell with custom configuration file
75 $ kamaki -c myconfig.file
80 To use kamaki as an one-command tool, run:
82 * with the '-h' or '--help' arguments (help for kamaki one-command)
84 .. code-block:: console
87 Example 2.3.1: Kamaki help
91 * with one or more command parameters:
93 .. code-block:: console
96 Example 2.3.2: List servers managed by user
100 One-command interface
101 ---------------------
106 Kamaki help provides information on available commands (description, syntax and
107 corresponding optional arguments).
109 To see the command groups, use -h or --help (example 1.3.1). The
110 following examples demonstrate the help messages of kamaki, in the context of a
111 command group (server) and of a command in that group (list).
113 .. code-block:: console
116 Example 3.1.1: kamaki help shows available parameters and command groups
120 usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
121 [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
124 -v, --verbose More info at response
125 -s, --silent Do not output anything
126 -V, --version Print current version
127 -d, --debug Include debug output
128 -i, --include Include protocol headers in the output
129 -c CONFIG, --config CONFIG
130 Path to configuration file
131 -o OPTIONS, --options OPTIONS
132 Override a config value
133 --cloud CLOUD Chose a cloud to connect to
134 -h, --help Show help message
138 network: Cyclades/Compute API network commands
139 user: Astakos API commands
140 livetest: Client func. tests on live servers
141 server: Cyclades/Compute API server commands
142 project: Synnefo project management CLI
143 file: Pithos+/Storage API commands
144 flavor: Cyclades/Compute API flavor commands
145 config: Kamaki configurations
146 image: Cyclades/Plankton API image commands
147 image compute: Cyclades/Compute API image commands
148 history: Kamaki command history
151 .. code-block:: console
152 :emphasize-lines: 1,2
154 Example 3.1.2: Cyclades help contains all first-level commands of Cyclades
158 usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG]
159 [-o OPTIONS] [--cloud CLOUD] [-h]
162 -v, --verbose More info at response
163 -s, --silent Do not output anything
164 -V, --version Print current version
165 -d, --debug Include debug output
166 -i, --include Include protocol headers in the output
167 -c CONFIG, --config CONFIG
168 Path to configuration file
169 -o OPTIONS, --options OPTIONS
170 Override a config value
171 --cloud CLOUD Chose a cloud to connect to
172 -h, --help Show help message
176 info: Detailed information on a Virtual Machine
177 rename: Set/update a virtual server name
178 delete: Delete a virtual server
179 console: Get a VNC console to access an existing virtual server
180 addr: List the addresses of all network interfaces on a virtual server
181 firewall: Manage virtual server firewall profiles for public networks
182 ip: Manage floating IPs for the servers
183 create: Create a server (aka Virtual Machine)
184 list: List Virtual Machines accessible by user
185 reboot: Reboot a virtual server
186 start: Start an existing virtual server
187 shutdown: Shutdown an active virtual server
188 stats: Get virtual server statistics
189 metadata: Manage Server metadata (key:value pairs of server attributes)
190 resize: Set a different flavor for an existing server
191 wait: Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
193 .. code-block:: console
194 :emphasize-lines: 1,2
196 Example 3.1.3: Help for command "server list" with syntax, description and
197 available user options
199 $ kamaki server list -h
200 usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS]
201 [--cloud CLOUD] [-h] [--since SINCE] [--enumerate]
202 [-l] [--more] [-n LIMIT] [-j]
204 List Virtual Machines accessible by user
207 -v, --verbose More info at response
208 -s, --silent Do not output anything
209 -V, --version Print current version
210 -d, --debug Include debug output
211 -i, --include Include raw connection data in the output
212 -c CONFIG, --config CONFIG
214 -o OPTIONS, --options OPTIONS
215 Override a config value
216 --cloud CLOUD Chose a cloud to connect to
217 -h, --help Show help message
218 --status STATUS filter by status (ACTIVE, STOPPED, REBOOT, ERROR,
220 --enumerate Enumerate results
221 --name-suffix NAME_SUFF
222 filter by name suffix (case insensitive)
223 --image-id IMAGE_ID filter by image id
224 --metadata META filter by metadata key=values
225 -j, --json show headers in json
227 --user-id USER_ID filter by user id
228 --id-like ID_LIKE print only if id contains this (case insensitive)
229 --id-suffix ID_SUFF filter by id suffix (case insensitive)
230 --since SINCE show only items since date (' d/m/Y H:M:S ')
231 -l, --details show detailed output
232 --name NAME filter by name
233 --more output results in pages (-n to set items per page,
235 --name-prefix NAME_PREF
236 filter by name prefix (case insensitive)
237 -n LIMIT, --number LIMIT
238 limit number of listed virtual servers
239 --id-prefix ID_PREF filter by id prefix (case insensitive)
240 --user-name USER_NAME
242 --name-like NAME_LIKE
243 print only if name contains this (case insensitive)
244 --metadata-like META_LIKE
245 print only if in key=value, the value is part of
247 --flavor-id FLAVOR_ID
251 Use filtering arguments (e.g. --name-like) to manage long server lists
253 .. _using-history-ref:
258 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>`_).
260 Every command is appended at the end of that file. In order to see how to use
261 history, use the kamaki help system:
263 .. code-block:: console
266 Example 3.2.1: Available history options
272 clean: Clean up history (permanent)
273 run : Run previously executed command(s)
274 show : Show intersession command history
276 The following example showcases how to use history in kamaki
278 .. code-block:: console
281 Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
284 $ kamaki history clean
287 $ kamaki history show
288 1. kamaki server list
289 2. kamaki history show
290 $ kamaki history show --match server
291 1. kamaki server list
292 3. kamaki history show --match server
300 When in debug mode, kamaki outputs some useful debug information (stack trace
301 and http logs). Kamaki in debug mode cancels suppression of warning messages.
303 To run kamaki in debug mode use the -d or --debug option.
309 Most kamaki commands are translated into http requests. Kamaki clients API
310 translated the semantics to REST and handles the response. Users who need to
311 have access to these commands can use the verbose mode that presents the HTTP
312 Request details as well as the full server response.
314 To run kamaki in verbose mode use the *-v/- - verbose* option
316 Verbose mode outputs the request and response mode, address and
317 headers as well as the size of the data block, if any. Sensitive information
318 (x-auth-token header and data body) are omitted by default,. Users who need
319 this information may enable it through the log_token and log_data configuration
320 options (see next section)
322 .. tip:: Use the -o runtime option to enable config options on the fly, e.g, to
325 .. code-block:: console
327 $ kamaki server list -v -o log_data=on
333 Kamaki keeps its logs in a file specified by the *log_file* option and it
334 defaults to *${HOME}/.kamaki.log*. This configuration option can be modified::
336 kamaki config set log_file /new/log/file/path
338 Kamaki logs http request and response information, namely the method, URL,
339 headers and data size. Sensitive information (data and token header) are
340 omitted by default. There are some configuration options that can switch them
343 * HTTP data blocks are not logged by default
344 to enable logging the full http bodies, set log_data to `on`::
346 kamaki config set log_data on
348 to disable it, set it to `off`::
350 kamaki config set log_data off
354 kamaki config delete log_data
356 * X-Auth-Token header is not logged by default
357 to enable logging the X-Auth-Token header, set log_token to `on`::
359 kamaki config set log_token on
361 to disable it, set it to `off`::
363 kamaki config set log_token off
367 kamaki config delete log_token
369 * The information (pid, name, date) of the processes that handle http requests
370 is not logged by default, because if they are, logs are difficult to read.
371 Still, they are useful for resolving race condition problems, so to enable
372 logging proccess information::
374 kamaki config set log_pid on
376 to disable it, set if to off::
378 kamaki config set log_pid off
382 kamaki config delete log_pid
387 Kamaki commands can be used along with advanced shell features.
389 .. code-block:: console
392 Example 3.4.1: List the trash container contents, containing c1_
395 $ kamaki file list -o cloud.default.pithos_container=trash| grep c1_
400 The -o argument can be used to temporarily override various (set or unset)
401 options. In one command, all -o option sets are forgotten just after the
402 command has been completed, and the previous settings are restored (the
403 configuration file is not modified).
405 The file-list command in example 3.4.1 runs with an explicitly provided
406 pithos_account, which temporarily overrides the one probably provided in the
407 configuration file (it works even if the user has not set the optional
408 pithos_account config option).
410 .. tip:: There are better ways to list the contents of a container. Example
411 3.4.1 is using this method for demonstration purposes only. The suggested
412 method for listing container contents is *- - container=<container>*
420 The kamaki interactive shell implements the notion of command contexts. Each
421 command group is also a context where the users can **enter** by typing the
422 group name. If the context switch is successful, the kamaki shell prompt
423 changes to present the new context ("*file*" in example 4.1.1).
425 .. code-block:: console
428 Example 4.1.1: Start kamaki and switch to file context
435 Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in
436 Windows) to exit a context and return to the context of origin. If already at
437 the top context (kamaki), an exit is equivalent to exiting the program.
439 .. code-block:: console
442 Example 4.1.2: Exit file context and then exit kamaki
448 A user might **browse** through different contexts during one session.
450 .. code-block:: console
453 Example 4.1.3: Execute list command in different contexts
458 ... (configuration options listing) ...
462 ... (storage containers listing) ...
466 ... (servers listing) ...
470 Users have the option to avoid switching between contexts: all commands can run
471 from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent.
473 .. code-block:: console
476 Example 4.1.4: Execute different "list" commands from top context
479 [kamaki]: config list
480 ... (configuration options listing) ...
482 ... (storage container listing) ...
483 [kamaki]: server list
484 ... (servers listing) ...
490 There are two help mechanisms: a context-level and a command-level.
492 **Context-level help** lists the available commands in a context and can also
493 offer a short description for each command.
495 Context-level help syntax::
497 * Show available commands in current context *
503 * Show help for command cmd *
509 The context-level help results may change from context to context
511 .. code-block:: console
514 Example 4.2.1: Get available commands and then get help in a context
521 user config flavor history image network server file ...
523 interactive shell commands:
524 ===========================
528 Configuration commands (config -h for more options)
538 interactive shell commands:
539 ===========================
543 Set a configuration option (set -h for more options)
545 In context-level, there is a distinction between kamaki-commands and
546 interactive shell commands. The former are available in one-command mode and
547 are related to the cloud client setup and use, while the later are
548 context-shell functions.
550 **Command-level help** prints the syntax, arguments and description of a
551 specific (terminal) command
553 Command-level help syntax::
555 * Get help for command cmd1 cmd2 ... cmdN *
556 [context]: cmd1 cmd2 ... cmdN -h
561 <arguments and possible extensions>
563 Command-level help mechanism is exactly the same as the one used in
564 one-command mode. For example, it is invoked by using the -h or --help
565 parameter at any point.
567 .. code-block:: console
570 Example 4.2.2: Get command-level help for config and config-set
573 [kamaki]: config --help
574 config: Configuration commands
575 delete: Delete a configuration option (and use the default value)
576 get : Show a configuration option
577 list : List configuration options
578 set : Set a configuration option
583 usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
585 Set a configuration option
588 -v, --verbose More info at response
589 -d, --debug Include debug output
590 -h, --help Show help message
591 -i, --include Include protocol headers in the output
592 --config CONFIG Path to configuration file
593 -s, --silent Do not output anything
595 There are many ways of producing a help message, as shown in example 4.2.3
597 .. code-block:: console
600 Example 4.2.3: Equivalent calls of command-level help for config-set
605 [kamaki]: config set -h
606 [kamaki]: config set --help
607 [file]: /config set -h
608 [server]: /config set --help
610 .. _accessing-top-level-commands-ref:
612 Accessing top-level commands
613 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
615 When working in a context, it is often useful to access other contexts or
616 top-level commands. Kamaki offers access to top-level commands by using the
617 `/` prefix, as shown bellow::
619 * access a command "anothercontext cmd1 cmd2 ... cmdN"
620 [context]: /anothercontext cmd1 cmd2 ... cmdN
622 An example (4.3.1) that showcases how top-level access improves user experience
623 is the creation of a server. A server is created with the command server-create. This
624 command is called with three parameters:
626 * the name of the new server
630 An average user would enter the server context and type *create -h* to check the
631 syntax of the command. In that point, it would be nice to have some easy way of
632 accessing the *flavor* and *image* contexts, to list and pick a flavor id and an
633 image id. This is achieved with the / notation, as demonstrated in the following
636 .. code-block:: console
639 Example 4.3.1: Create a server from server context
642 create <name> <flavor id> <image id> ...
645 [server]: /flavor list
648 SNF:disk_template: drbd
653 [server]: /image compute list
654 1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
655 18a82962-43eb-8f8880af89d7 (Windows 7)
656 531aa018-9a40-a4bfe6a0caff (Windows XP)
657 6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
659 [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
662 An other example (4.3.2) showcases how to acquire and modify configuration
663 settings from a different context. In this scenario, the user token expires at
664 server side while the user is working. When that happens, the system responds
665 with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid
666 for the Astakos identity manager of preference) which has to be set to kamaki.
668 .. code-block:: console
671 Example 4.3.2: Token suddenly expires. Set a new token from file context
675 (401) UNAUTHORIZED Access denied
677 [file]: /user authenticate
678 (401) UNAUTHORIZED Invalid X-Auth-Token
680 [file]: /config get cloud.default.token
683 [file]: /config set cloud.default.token myfr35ht0k3n==
685 [file]: /config get cloud.default
686 cloud.default.url = https://astakos.example.com/astakos/identity/2.0/
687 cloud.default.token = myfr35ht0k3n==
690 1. pithos (10MB, 2 objects)
691 2. trash (0B, 0 objects)
693 .. note:: The error messages on examples are shortened for clarity. Actual error
694 messages are more helpful and descriptive.
696 The following example compares some equivalent calls that run
697 *user-authenticate* after a *file-list* 401 failure.
699 .. code-block:: console
700 :emphasize-lines: 1,3,10,17,26
702 Example 4.3.3: Equivalent user-authenticate calls after a file-list 401
704 * I. without kamaki interactive shell *
706 (401) UNAUTHORIZED Access denied
707 $ kamaki user authenticate
711 * II. from top-level context *
713 (401) UNAUTHORIZED Access denied
714 [kamaki]: user authenticate
718 * III. maximum typing *
720 (401) UNAUTHORIZED Access denied
727 * IV. minimum typing *
729 (401) UNAUTHORIZED Access denied
730 [file]: /user authenticate
734 .. hint:: To exit kamaki shell while in a context, try */exit*
739 The configuration mechanism of kamaki is detailed in the
740 `setup section <setup.html>`_, it is accessible as *config* and it is common for
741 both interaction modes. In specific, the configuration mechanism is implemented
742 as `config`. Using the config commands is as straightforward as in any other
745 It is often useful to set, delete or update a value. This can be managed either
746 inside the config context or from any command context by using the / prefix.
748 .. Note:: config updates in kamaki shell persist even after the session is over
750 All setting changes affect the physical kamaki config file. The config file is
751 created automatically at callers' home firectory the first time a config option
752 is set, and lives there as *.kamakirc* . It can be edited with any text editor
753 or managed with kamaki config commands.
755 In example 4.4.1 the user is going to work with only one storage container. The
756 file commands use the container:path syntax, but if the user sets a container
757 name as default, the container name can be omitted.
759 .. code-block:: console
762 Example 4.4.1: Set default storage container (cloud alias: default)
766 mycontainer (32MB, 2 objects)
767 pithos (0B, 0 objects)
768 trash (2MB, 1 objects)
770 [file]: list mycontainer
772 20M mydir/rndm_local.file
774 [file]: /config set cloud.default.pithos_container mycontainer
778 20M mydir/rndm_local.file
780 After a while, the user needs to work with multiple containers, therefore a
781 default container is no longer needed. The *pithos_container* setting can be
782 deleted, as shown in example 4.4.2
784 .. code-block:: console
787 Example 4.4.2: Delete a setting option (cloud: default)
790 [file]: /config delete cloud.default.pithos_container
793 mycontainer (32MB, 2 objects)
794 pithos (0B, 0 objects)
795 trash (2MB, 1 objects)
800 There are two history modes: session and permanent. Session history keeps
801 record of all actions in a kamaki shell session, while permanent history
802 appends all commands to an accessible history file.
804 Session history is only available in interactive shell mode. Users can iterate
805 through past commands in the same session with the ↑ and ↓ keys. Session
806 history is not stored, although commands are recorded through the permanent
809 Permanent history is implemented as a command group and is common to both the
810 one-command and shell interfaces. In specific, every command is appended in a
811 history file (configured as `history_file` in settings, see
812 `setup section <setup.html>`_ for details). Commands executed in one-command
813 mode are mixed with the ones run in kamaki shell (also see
814 :ref:`using-history-ref` section on this guide).
819 The history-run feature allows the sequential run of previous command
820 executions in kamaki shell.
822 The following sequence copies and downloads a file from *mycontainer1* ,
823 uploads it to *mycontainer2* , then undo the proccess and repeats it with
826 .. code-block:: console
827 :emphasize-lines: 1,12,19,32
829 * Download mycontainer1:myfile and upload it to mycontainer2:myfile *
831 [file]: copy mycontainer1:somefile mycontainer1:myfile
832 [file]: download mycontainer1:myfile mylocalfile
835 [file]: upload mylocalfile mycontainer2:myfile -f
840 [file]: !rm mylocalfile
841 [file]: delete mycontainer1:myfile
842 [file]: delete mycontainer2:myfile
844 * check history entries *
849 2. file copy mycontainer1:somefile mycontainer1:myfile
850 3. file download mycontainer1:myfile mylocalfile
851 4. file upload mylocalfile mycontainer2:myfile -f
852 5. file delete mycontainer1:myfile
853 6. file delete mycontainer2:myfile
857 *repeat the process *
859 <file copy mycontainer1:somefile mycontainer1:myfile>
860 <file download mycontainer1:myfile mylocalfile>
862 <file upload mylocalfile mycontainer2:myfile>
865 For powerfull scripting, users are advised to take advantage of their os shell
866 scripting capabilities and combine them with kamaki one-command. Still, the
867 history-run functionality might prove handy in many occasions.
872 Kamaki shell features the ability to execute OS-shell commands from any
873 context. This can be achieved by typing *!* or *shell*::
875 [kamaki_context]: !<OS shell command>
876 ... OS shell command output ...
878 [kamaki_context]: shell <OS shell command>
879 ... OS shell command output ...
881 .. code-block:: console
884 Example 4.7.1: Run unix-style shell commands from kamaki shell
889 drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
890 drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
891 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
893 [kamaki]: shell cp kamaki-logo.png logo-copy.png
895 [kamaki]: shell ls -al
897 drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
898 drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
899 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
900 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png
903 Kamaki shell commits command strings to the outside shell and prints the
904 results, without interacting with it. After a command is finished, kamaki shell
905 returns to its initial state, which involves the current directory, as shown in
908 .. code-block:: console
911 Example 4.8.2: Attempt (and fail) to change working directory