4 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.
6 What's more, kamaki offers a clients API that allows the development of external applications for synnefo. The clients API is listed in the `Clients lib <developers/code.html#the-clients-api>`_ section. The recommended method of utilizing this API is explained in the present.
11 Kamaki interfaces rely on a list of configuration options. In the initial state, kamaki is configured to communicate with the Okeanos IaaS. A detailed guide for setting up kamaki can be found in the `Setup <setup.html>`_ section.
13 It is essential for users to get a configuration token (okeanos.grnet.gr users go `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
15 .. code-block:: console
18 Example 1.1: Set user token to myt0k3n==
20 $ kamaki set token myt0k3n==
22 To use the storage service, a user should also provide the corresponding user-name:
24 .. code-block:: console
27 Example 1.2: Set user name to user@domain.com
29 $ kamaki set account user@domain.com
33 Kamaki users can access synnefo services through either the interactive shell or the one-command behaviors. 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.
35 In favor of interactive shell behavior:
37 * tab completion for commands
38 * session history with "up" / "down" keys
39 * shorter commands with command context switching
41 In favor of one-command behavior:
43 * can be used along with advanced shell features (pipelines, redirection, etc.)
44 * can be used in shell scripts
45 * prints debug and verbose messages if needed
49 To use kamaki as a shell, run:
51 * without any parameters or arguments
53 .. code-block:: console
56 Example 2.2.1: Run kamaki shell
60 * with any kind of '-' prefixed arguments, except '-h', '--help'.
62 .. code-block:: console
65 Example 2.2.2: Run kamaki shell with custom configuration file
67 $ kamaki --config myconfig.file
72 To use kamaki as an one-command tool, run:
74 * with the '-h' or '--help' arguments (help for kamaki one-command)
76 .. code-block:: console
79 Example 2.3.1: Kamaki help
83 * with one or more command parameters:
85 .. code-block:: console
88 Example 2.3.2: List VMs managed by user
95 Kamaki usage as a one-command tool is detailed in this section
100 Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments.
102 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.
104 .. code-block:: console
107 Example 3.1.1: kamaki help shows available parameters and command groups
111 usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
112 [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h]
115 -v, --verbose More info at response
116 -s, --silent Do not output anything
117 -V, --version Print current version
118 -d, --debug Include debug output
119 -i, --include Include protocol headers in the output
120 --config CONFIG Path to configuration file
121 -o OPTIONS, --options OPTIONS
122 Override a config value
123 -h, --help Show help message
127 astakos: Astakos API commands
128 config : Configuration commands
129 flavor : Compute/Cyclades API flavor commands
130 history: Command history
131 image : Compute/Cyclades or Plankton API image commands
132 network: Compute/Cyclades API network commands
133 server : Compute/Cyclades API server commands
134 store : Pithos+ storage commands
136 .. code-block:: console
139 Example 3.1.2: Cyclades help contains all first-level commands of Cyclades command group
143 usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
147 -v, --verbose More info at response
148 -s, --silent Do not output anything
149 -V, --version Print current version
150 -d, --debug Include debug output
151 -i, --include Include protocol headers in the output
152 --config CONFIG Path to configuration file
153 -o OPTIONS, --options OPTIONS
154 Override a config value
155 -h, --help Show help message
159 addmeta : Add server metadata
160 addr : List a server's nic address
161 console : Get a VNC console
162 create : Create a server
163 delete : Delete a server
164 delmeta : Delete server metadata
165 firewall: Set the server's firewall profile
166 info : Get server details
168 meta : Get a server's metadata
169 reboot : Reboot a server
170 rename : Update a server's name
171 setmeta : Update server's metadata
172 shutdown: Shutdown a server
173 start : Start a server
174 stats : Get server statistics
175 wait : Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
177 .. code-block:: console
180 Example 3.1.3: Help for command "server list" with syntax, description and available user options
183 $ kamaki server list -h
184 usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l]
189 -v, --verbose More info at response
190 -s, --silent Do not output anything
191 -V, --version Print current version
192 -d, --debug Include debug output
193 -i, --include Include protocol headers in the output
194 --config CONFIG Path to configuration file
195 -o OPTIONS, --options OPTIONS
196 Override a config value
197 -h, --help Show help message
198 -l show detailed output
200 .. _using-history-ref:
205 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>`_).
207 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:
209 .. code-block:: console
212 Example 3.2.1: Available history options
217 clean: Clean up history
220 The following example showcases how to use history in kamaki
222 .. code-block:: console
225 Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
228 $ kamaki history clean
231 $ kamaki history show
232 1. kamaki server list
233 2. kamaki history show
234 $ kamaki history show --match server
235 1. kamaki server list
236 3. kamaki history show --match server
241 In case of errors, kamaki in debug mode shows useful 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.
243 To run kamaki in debug mode use the -d or --debug option
248 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.
250 To run kamaki in verbose mode use the -v or --verbose option
255 Kamaki commands can be used along with advanced shell features.
257 .. code-block:: console
260 Example 3.4.1: Print username for token us3rt0k3n== using grep
263 $ kamaki astakos authenticate -o token=us3rt0k3n== | grep uniq
264 uniq : user@synnefo.org
266 The -o argument can be used to override temporarily various (set or unset) options. In one command, all -o options are forgotten just after the command had been completed, and the previous settings are restored (the configuration file is not modified).
268 The astakos-authenticate command in example 3.4.1 run against an explicitly provided token, which temporarily overrode the token provided in the configuration file.
273 Kamaki interactive shell is details in this section
278 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 ("store" in example 4.1.1).
280 .. code-block:: console
283 Example 4.1.1: Enter store commands context / group
290 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 program.
292 .. code-block:: console
295 Example 4.1.2: Exit store context and then exit kamaki
301 A user might **browse** through different contexts during one session.
303 .. code-block:: console
306 Example 4.1.3: Execute list command in different contexts
311 ... (configuration options listing) ...
315 ... (storage containers listing) ...
319 ... (VMs listing) ...
323 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.
325 .. code-block:: console
328 Example 4.1.4: Execute different "list" commands from top context
332 ... (configuration options listing) ...
334 ... (storage container listing) ...
336 ... (VMs listing) ...
342 There are two help mechanisms: a context-level and a command-level.
344 **Context-level help** lists the available commands in a context and can also offer a short description for each command.
346 Context-level help syntax::
348 * Show available commands in current context *
352 * Show help for command cmd *
356 The context-level help results change from context to context
358 .. code-block:: console
361 Example 4.2.1: Get available commands, pick a context and get help there as well
368 astakos config flavor history image network server store
370 interactive shell commands:
371 ===========================
375 Configuration commands (config -h for more options)
385 interactive shell commands:
386 ===========================
390 Set a configuration option (set -h for more options)
392 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.
394 **Command-level help** prints the syntax, arguments and description of a specific (terminal) command
396 Command-level help syntax::
398 * Get help for command cmd1 cmd2 ... cmdN *
399 [context]:cmd1 cmd2 ... cmdN -h
404 <arguments and possible extensions>
406 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.
408 .. code-block:: console
411 Example 4.2.2: Get command-level help for config and config-set
414 [kamaki]:config --help
415 config: Configuration commands
416 delete: Delete a configuration option (and use the default value)
417 get : Show a configuration option
418 list : List configuration options
419 set : Set a configuration option
424 usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
426 Set a configuration option
429 -v, --verbose More info at response
430 -d, --debug Include debug output
431 -h, --help Show help message
432 -i, --include Include protocol headers in the output
433 --config CONFIG Path to configuration file
434 -s, --silent Do not output anything
436 There are many ways of producing a help message, as shown in example 4.2.3
438 .. code-block:: console
441 Example 4.2.3: Equivalent calls of command-level help for config-set
446 [kamaki]:config set -h
447 [kamaki]:config set --help
448 [store]:/config set -h
449 [server]:/config set --help
451 .. _accessing-top-level-commands-ref:
453 Accessing top-level commands
454 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
456 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::
458 * access a command "anothercontext cmd1 cmd2 ... cmdN"
459 [context]:/anothercontext cmd1 cmd2 ... cmdN
461 An example (4.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:
463 * the name of the new VM
467 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 necessary to list all available flavors (flavor-list) or images (image-list. Both commands belong to different contexts.
469 .. code-block:: console
472 Example 4.3.1: Create a VM from server context
475 create <name> <flavor id> <image id> ...
478 [server]:/flavor list
481 SNF:disk_template: drbd
488 1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
489 18a82962-43eb-8f8880af89d7 (Windows 7)
490 531aa018-9a40-a4bfe6a0caff (Windows XP)
491 6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
493 [server]:create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
496 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 acquires a new token (with a browser) which has to be set to kamaki.
498 .. code-block:: console
501 Example 4.3.2: Set a new token from store context
505 (401) UNAUTHORIZED Access denied
507 [store]:/astakos authenticate
508 (401) UNAUTHORIZED Invalid X-Auth-Token
510 [store]:/config get token
513 [store]:/config set token myfr35ht0k3n==
515 [store]:/config get token
519 1. pithos (10MB, 2 objects)
520 2. trash (0B, 0 objects)
522 The following example compares some equivalent calls that run *astakos-authenticate* after a *store-list* 401 failure.
524 .. code-block:: console
525 :emphasize-lines: 1,3,10,17,26
527 Example 4.3.3: Equivalent astakos-authenticate calls after a store-list 401 failure
529 * without kamaki interactive shell *
531 (401) UNAUTHORIZED Access denied
532 $ kamaki astakos authenticate
536 * from top-level context *
538 (401) UNAUTHORIZED Access denied
539 [kamaki]:astakos authenticate
545 (401) UNAUTHORIZED Access denied
548 [astakos]:authenticate
554 (401) UNAUTHORIZED Access denied
555 [store]:/astakos authenticate
559 .. hint:: To exit kamaki shell while in a context, try */exit*
564 The configuration mechanism of kamaki is detailed at the `setup section <setup.html>`_ and it is common for both interaction modes. In specific, the configuration mechanism is implemented as a command group, namely *config*. Using the config commands is as straightforward as any other kamaki commands.
566 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 / detour.
568 .. Note:: config updates in kamaki shell persist even after the session is over. All setting changes affects the physical kamaki config file (automatically created, if not set manually)
570 In example 4.4.1 the user is going to work with only one storage container. The store commands use the container:path syntax, but if the user could set a container as a default, the container name could be omitted in most cases. This is possible by setting a store.container setting.
572 .. code-block:: console
575 Example 4.4.1: Set default storage container
579 1. mycontainer (32MB, 2 objects)
580 2. pithos (0B, 0 objects)
581 3. trash (2MB, 1 objects)
583 [store]:list mycontainer
585 2. 20M mydir/rndm_local.file
587 [store]:/config set store.container mycontainer
591 2. 20M mydir/rndm_local.file
593 After a while, the user needs to work with multiple containers, therefore a default container is not longer needed. The store.container setting can be deleted, as shown in example 4.4.2 .
595 .. code-block:: console
598 Example 4.4.2: Delete a setting option
601 [store]:/config delete store.container
604 1. mycontainer (32MB, 2 objects)
605 2. pithos (0B, 0 objects)
606 3. trash (2MB, 1 objects)
608 .. warning:: In some cases, the config setting updates are not immediately effective. If that is the case, they will be after the next command run, whatever that command is.
613 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.
615 Session history is only available in interactive shell mode. Users can iterate through past commands in the same session by with the *up* and *down* keys. Session history is not stored, although syntactically correct commands are recorded through the permanent history mechanism
617 Permanent history is implemented as a command group and is common to both the one-command and shell interfaces. In specific, every syntactically correct 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).
622 Since version 6.2, the history-load feature allows the sequential execution of previously run kamaki commands in kamaki shell.
624 The following kamaki sequence copies and downloads a file from mycontainer1, uploads it to mycontainer2, then undo the proccess and repeats it with history-load
626 .. code-block:: console
627 :emphasize-lines: 1,12,19,32
629 * Download mycontainer1:myfile and upload it to mycontainer2:myfile
632 [store]: copy mycontainer1:somefile mycontainer1:myfile
634 [store]: download mycontainer1:myfile mylocalfile
637 [store]: upload mylocalfile mycontainer2:myfile
641 [store]: !rm mylocalfile
643 [store]: delete mycontainer1:myfile
645 [store]: delete mycontainer2:myfile
647 * check history entries *
654 2. store copy mycontainer1:somefile mycontainer1:myfile
655 3. store download mycontainer1:myfile mylocalfile
656 4. store upload mylocalfile mycontainer2:myfile
660 *repeat the process *
662 store copy mycontainer1:somefile mycontainer1:myfile
663 store download mycontainer1:myfile mylocalfile
665 store upload mylocalfile mycontainer2:myfile
668 The above strategy is still very primitive. Users are advised to take advantage of their os shell scripting capabilities and combine them with kamaki one-command for powerful scripting. Still, the history-load functionality might prove handy for kamaki shell users.
673 Kamaki shell features tab completion for the first level of command terms of the current context. Tab completion pool changes dynamically when the context is switched. Currently, tab completion is not supported when the / detour is used (see :ref:`accessing-top-level-commands-ref` ).
678 Kamaki shell features the ability to execute OS-shell commands from any context. This can be achieved by typing *!* or *shell*::
680 [kamaki_context]:!<OS shell command>
681 ... OS shell command output ...
683 [kamaki_context]:shell <OS shell command>
684 ... OS shell command output ...
686 .. code-block:: console
689 Example 4.7.1: Run unix-style shell commands from kamaki shell
694 drwxrwxr-x 2 saxtouri saxtouri 4096 Nov 27 16:47 .
695 drwxrwxr-x 7 saxtouri saxtouri 4096 Nov 27 16:47 ..
696 -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 kamaki-logo.png
698 [kamaki]:shell cp kamaki-logo.png logo-copy.png
700 [kamaki]:shell ls -al
702 drwxrwxr-x 2 saxtouri saxtouri 4096 Nov 27 16:47 .
703 drwxrwxr-x 7 saxtouri saxtouri 4096 Nov 27 16:47 ..
704 -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 kamaki-logo.png
705 -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 logo-copy.png
708 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 show in example 4.8.2 .
710 .. code-block:: console
713 Example 4.8.2: Attempt (and fail) to change working directory