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.
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 valid configuration token that works with for a synnefo-compliant Identity Manager service (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 config set token myt0k3n==
24 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.
26 In favor of interactive shell behavior:
28 * tab completion for commands (mostly on (X)nix OSs)
29 * session history with "up" / "down" keys
30 * shorter commands with command context switching
31 * re-run old commands with /history
33 In favor of one-command behavior:
35 * can be used along with advanced shell features (pipelines, redirection, etc.)
36 * can be used in shell scripts
37 * prints debug and verbose messages if needed
41 To use kamaki as a shell, run:
43 * without any parameters or arguments
45 .. code-block:: console
48 Example 2.2.1: Run kamaki shell
52 * with any kind of '-' prefixed arguments, except '-h', '--help'.
54 .. code-block:: console
57 Example 2.2.2: Run kamaki shell with custom configuration file
59 $ kamaki --config myconfig.file
64 To use kamaki as an one-command tool, run:
66 * with the '-h' or '--help' arguments (help for kamaki one-command)
68 .. code-block:: console
71 Example 2.3.1: Kamaki help
75 * with one or more command parameters:
77 .. code-block:: console
80 Example 2.3.2: List VMs managed by user
90 Kamaki help is used to list available commands with description, syntax and corresponding optional arguments.
92 To see the command groups, 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.
94 .. code-block:: console
97 Example 3.1.1: kamaki help shows available parameters and command groups
101 usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
102 [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h]
105 -v, --verbose More info at response
106 -s, --silent Do not output anything
107 -V, --version Print current version
108 -d, --debug Include debug output
109 -i, --include Include protocol headers in the output
110 --config CONFIG Path to configuration file
111 -o OPTIONS, --options OPTIONS
112 Override a config value
113 -h, --help Show help message
117 user: Astakos API commands
118 config: Configuration commands
119 flavor: Compute/Cyclades API flavor commands
120 history: Command history
121 image: Plankton (and Compute) Image API commands
122 network: Compute/Cyclades API network commands
123 server: Compute/Cyclades API server commands
124 file: Pithos+ storage commands
126 .. code-block:: console
129 Example 3.1.2: Cyclades help contains all first-level commands of Cyclades command group
133 usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
137 -v, --verbose More info at response
138 -s, --silent Do not output anything
139 -V, --version Print current version
140 -d, --debug Include debug output
141 -i, --include Include protocol headers in the output
142 --config CONFIG Path to configuration file
143 -o OPTIONS, --options OPTIONS
144 Override a config value
145 -h, --help Show help message
149 addr : List a server's nic address
150 console : Get a VNC console
151 create : Create a server
152 delete : Delete a server
153 firewall: Manage the server's firewall profile
154 set: Set the server's firewall profile
155 get: Get the server's firewall profile
156 info : Get server details
158 metadata: Manage server metadata
159 list : Get a server metadata
160 set : Add or update server metadata
161 delete: Delete a piece of server metadata
162 reboot : Reboot a server
163 rename : Update a server's name
164 shutdown: Shutdown a server
165 start : Start a server
166 stats : Get server statistics
167 wait : Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
169 .. code-block:: console
172 Example 3.1.3: Help for command "server list" with syntax, description and available user options
175 $ kamaki server list -h
176 usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l]
181 -v, --verbose More info at response
182 -s, --silent Do not output anything
183 -V, --version Print current version
184 -d, --debug Include debug output
185 -i, --include Include protocol headers in the output
186 --config CONFIG Path to configuration file
187 -o OPTIONS, --options OPTIONS
188 Override a config value
189 -h, --help Show help message
190 -l show detailed output
192 .. _using-history-ref:
197 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>`_).
199 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:
201 .. code-block:: console
204 Example 3.2.1: Available history options
210 clean: Clean up history (permanent)
211 run : Run previously executed command(s)
212 show : Show intersession command history
214 The following example showcases how to use history in kamaki
216 .. code-block:: console
219 Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
222 $ kamaki history clean
225 $ kamaki history show
226 1. kamaki server list
227 2. kamaki history show
228 $ kamaki history show --match server
229 1. kamaki server list
230 3. kamaki history show --match server
235 In case of errors, kamaki in debug mode shows useful debug information, like the stack trace. Kamaki in debug mode cancels suppression of warning messages.
237 To run kamaki in debug mode use the -d or --debug option (can be combined with any other parameters or options)
242 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.
244 To run kamaki in verbose mode use the -v or --verbose option
246 Be default, kamaki in verbose mode prints down only the headers and the address information, thus hiding the data body of the request or response. To see the data body, the -i option can be used.
251 Kamaki commands can be used along with advanced shell features.
253 .. code-block:: console
256 Example 3.4.1: Print username for token us3rt0k3n== using grep
259 $ kamaki user authenticate -o token=us3rt0k3n== | grep userame
260 userame : user@synnefo.org
262 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 (a.k.a. the configuration file is not modified).
264 The user-authenticate command in example 3.4.1 runs with an explicitly provided token, which temporarily overrides the token provided in the configuration file.
272 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).
274 .. code-block:: console
277 Example 4.1.1: Enter file commands context / group
284 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.
286 .. code-block:: console
289 Example 4.1.2: Exit file context and then exit kamaki
295 A user might **browse** through different contexts during one session.
297 .. code-block:: console
300 Example 4.1.3: Execute list command in different contexts
305 ... (configuration options listing) ...
309 ... (storage containers listing) ...
313 ... (VMs listing) ...
317 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.
319 .. code-block:: console
322 Example 4.1.4: Execute different "list" commands from top context
325 [kamaki]: config list
326 ... (configuration options listing) ...
328 ... (storage container listing) ...
329 [kamaki]: server list
330 ... (VMs listing) ...
336 There are two help mechanisms: a context-level and a command-level.
338 **Context-level help** lists the available commands in a context and can also offer a short description for each command.
340 Context-level help syntax::
342 * Show available commands in current context *
346 * Show help for command cmd *
350 The context-level help results change from context to context
352 .. code-block:: console
355 Example 4.2.1: Get available commands, pick a context and get help there as well
362 user config flavor history image network server file
364 interactive shell commands:
365 ===========================
369 Configuration commands (config -h for more options)
379 interactive shell commands:
380 ===========================
384 Set a configuration option (set -h for more options)
386 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.
388 **Command-level help** prints the syntax, arguments and description of a specific (terminal) command
390 Command-level help syntax::
392 * Get help for command cmd1 cmd2 ... cmdN *
393 [context]: cmd1 cmd2 ... cmdN -h
398 <arguments and possible extensions>
400 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.
402 .. code-block:: console
405 Example 4.2.2: Get command-level help for config and config-set
408 [kamaki]: config --help
409 config: Configuration commands
410 delete: Delete a configuration option (and use the default value)
411 get : Show a configuration option
412 list : List configuration options
413 set : Set a configuration option
418 usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
420 Set a configuration option
423 -v, --verbose More info at response
424 -d, --debug Include debug output
425 -h, --help Show help message
426 -i, --include Include protocol headers in the output
427 --config CONFIG Path to configuration file
428 -s, --silent Do not output anything
430 There are many ways of producing a help message, as shown in example 4.2.3
432 .. code-block:: console
435 Example 4.2.3: Equivalent calls of command-level help for config-set
440 [kamaki]: config set -h
441 [kamaki]: config set --help
442 [file]: /config set -h
443 [server]: /config set --help
445 .. _accessing-top-level-commands-ref:
447 Accessing top-level commands
448 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
450 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::
452 * access a command "anothercontext cmd1 cmd2 ... cmdN"
453 [context]: /anothercontext cmd1 cmd2 ... cmdN
455 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:
457 * the name of the new VM
461 It is often the case that a user who works in the context command, needs to create a new VM, but hasn't selected a flavor or an image id, or cannot recall the id of that flavor or image. Therefore, it is necessary to list all available flavors (flavor-list) or images (image-compute-list). Both commands belong to different contexts.
463 .. code-block:: console
466 Example 4.3.1: Create a VM from server context
469 create <name> <flavor id> <image id> ...
472 [server]: /flavor list
475 SNF:disk_template: drbd
480 [server]: /image compute list
481 1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
482 18a82962-43eb-8f8880af89d7 (Windows 7)
483 531aa018-9a40-a4bfe6a0caff (Windows XP)
484 6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
486 [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
489 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.
491 .. code-block:: console
494 Example 4.3.2: Set a new token from file context
498 (401) UNAUTHORIZED Access denied
500 [file]: /user authenticate
501 (401) UNAUTHORIZED Invalid X-Auth-Token
503 [file]: /config get token
506 [file]: /config set token myfr35ht0k3n==
508 [file]: /config get token
512 1. pithos (10MB, 2 objects)
513 2. trash (0B, 0 objects)
515 .. note:: The error messages on this example where shortened for clarity. Actual kamaki error messages are more helpful and descriptive.
517 The following example compares some equivalent calls that run *user-authenticate* after a *file-list* 401 failure.
519 .. code-block:: console
520 :emphasize-lines: 1,3,10,17,26
522 Example 4.3.3: Equivalent user-authenticate calls after a file-list 401 failure
524 * without kamaki interactive shell *
526 (401) UNAUTHORIZED Access denied
527 $ kamaki user authenticate
531 * from top-level context *
533 (401) UNAUTHORIZED Access denied
534 [kamaki]: user authenticate
540 (401) UNAUTHORIZED Access denied
549 (401) UNAUTHORIZED Access denied
550 [file]: /user authenticate
554 .. hint:: To exit kamaki shell while in a context, try */exit*
559 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.
561 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.
563 .. Note:: config updates in kamaki shell persist even after the session is over.
565 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.
567 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. This is possible by setting a *file.container* setting.
569 .. code-block:: console
572 Example 4.4.1: Set default storage container
576 1. mycontainer (32MB, 2 objects)
577 2. pithos (0B, 0 objects)
578 3. trash (2MB, 1 objects)
580 [file]: list mycontainer
582 2. 20M mydir/rndm_local.file
584 [file]: /config set file.container mycontainer
588 2. 20M mydir/rndm_local.file
590 After a while, the user needs to work with multiple containers, therefore a default container is no longer needed. The *file.container* setting can be deleted, as shown in example 4.4.2 .
592 .. code-block:: console
595 Example 4.4.2: Delete a setting option
598 [file]: /config delete file.container
601 1. mycontainer (32MB, 2 objects)
602 2. pithos (0B, 0 objects)
603 3. trash (2MB, 1 objects)
608 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.
610 Session history is only available in interactive shell mode. Users can iterate through past commands in the same session with the *up* and *down* keys. Session history is not stored, although syntactically correct commands are recorded through the permanent history mechanism
612 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).
617 The history-run feature allows the sequential run of previous command executions in kamaki shell.
619 The following sequence copies and downloads a file from *mycontainer1* , uploads it to *mycontainer2* , then undo the proccess and repeats it with history-run
621 .. code-block:: console
622 :emphasize-lines: 1,12,19,32
624 * Download mycontainer1:myfile and upload it to mycontainer2:myfile
626 [file]: copy mycontainer1:somefile mycontainer1:myfile
627 [file]: download mycontainer1:myfile mylocalfile
629 [file]: upload mylocalfile mycontainer2:myfile
633 [file]: !rm mylocalfile
634 [file]: delete mycontainer1:myfile
635 [file]: delete mycontainer2:myfile
637 * check history entries *
642 2. file copy mycontainer1:somefile mycontainer1:myfile
643 3. file download mycontainer1:myfile mylocalfile
644 4. file upload mylocalfile mycontainer2:myfile
645 5. file delete mycontainer1:myfile
646 6. file delete mycontainer2:myfile
650 *repeat the process *
652 <file copy mycontainer1:somefile mycontainer1:myfile>
653 <file download mycontainer1:myfile mylocalfile>
655 <file upload mylocalfile mycontainer2:myfile>
658 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.
663 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 / is used (see :ref:`accessing-top-level-commands-ref` ).
668 Kamaki shell features the ability to execute OS-shell commands from any context. This can be achieved by typing *!* or *shell*::
670 [kamaki_context]: !<OS shell command>
671 ... OS shell command output ...
673 [kamaki_context]: shell <OS shell command>
674 ... OS shell command output ...
676 .. code-block:: console
679 Example 4.7.1: Run unix-style shell commands from kamaki shell
684 drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
685 drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
686 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
688 [kamaki]: shell cp kamaki-logo.png logo-copy.png
690 [kamaki]: shell ls -al
692 drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
693 drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
694 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
695 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png
698 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 .
700 .. code-block:: console
703 Example 4.8.2: Attempt (and fail) to change working directory