Usage ===== Kamaki offers command line interfaces that implement specific command specifications. A detailed list of the command specifications can be found in `Commands `_ section. This guide covers the generic usage of both interfaces. 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 `_ section. Quick Setup ----------- 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 `_ section. 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 `_) and provide it to kamaki: .. code-block:: console :emphasize-lines: 1 Example 1.1: Set user token to myt0k3n== $ kamaki config set token myt0k3n== Shell vs one-command -------------------- 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. In favor of interactive shell behavior: * tab completion for commands (mostly on (X)nix OSs) * session history with "up" / "down" keys * shorter commands with command context switching * re-run old commands with /history In favor of one-command behavior: * 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 Example 2.2.1: Run kamaki shell $ kamaki * with any kind of '-' prefixed arguments, except '-h', '--help'. .. code-block:: console :emphasize-lines: 1 Example 2.2.2: Run kamaki shell with custom configuration file $ kamaki --config 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 :emphasize-lines: 1 Example 2.3.1: Kamaki help $kamaki -h * with one or more command parameters: .. code-block:: console :emphasize-lines: 1 Example 2.3.2: List VMs managed by user $ kamaki server list One-command interface --------------------- Using help ^^^^^^^^^^ Kamaki help is used to list available commands with description, syntax and corresponding optional arguments. 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. .. code-block:: console :emphasize-lines: 1 Example 3.1.1: kamaki help shows available parameters and command groups $ kamaki -h usage: kamaki [ ...] [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-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 --config CONFIG Path to configuration file -o OPTIONS, --options OPTIONS Override a config value -h, --help Show help message Options: - - - - user: Astakos API commands config: Configuration commands flavor: Compute/Cyclades API flavor commands history: Command history image: Plankton (and Compute) Image API commands network: Compute/Cyclades API network commands server: Compute/Cyclades API server commands file: Pithos+ storage commands .. code-block:: console :emphasize-lines: 1 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] [--config CONFIG] [-o OPTIONS] [-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 --config CONFIG Path to configuration file -o OPTIONS, --options OPTIONS Override a config value -h, --help Show help message 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] .. code-block:: console :emphasize-lines: 1 Example 3.1.3: Help for command "server list" with syntax, description and available user options $ kamaki server list -h usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l] 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 .. _using-history-ref: 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 `_). 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: .. code-block:: console :emphasize-lines: 1 Example 3.2.1: Available history options $ kamaki history -h Options: - - - - clean: Clean up history (permanent) 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 ... $ 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 ^^^^^ 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. To run kamaki in debug mode use the -d or --debug option (can be combined with any other parameters or options) Verbose and Include """"""""""""""""""" 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 or --verbose option 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. One-command features ^^^^^^^^^^^^^^^^^^^^ Kamaki commands can be used along with advanced shell features. .. code-block:: console :emphasize-lines: 1 Example 3.4.1: Print username for token us3rt0k3n== using grep $ kamaki user authenticate -o token=us3rt0k3n== | grep userame userame : user@synnefo.org 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). 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. 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: 1 Example 4.1.1: Enter file commands context / group $ 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: 1 Example 4.1.2: Exit file context and then exit kamaki [file]: exit [kamaki]: exit $ A user might **browse** through different contexts during one session. .. code-block:: console :emphasize-lines: 1 Example 4.1.3: Execute list command in different contexts $ kamaki [kamaki]: config [config]: list ... (configuration options listing) ... [config]: exit [kamaki]: file [file]: list ... (storage containers listing) ... [file]: exit [kamaki]: server [server]: list ... (VMs 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. .. 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 ... (VMs 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. Context-level help syntax:: * Show available commands in current context * [context]: help [context]: ? * Show help for command cmd * [context]: help cmd [context]: ?cmd The context-level help results change from context to context .. code-block:: console :emphasize-lines: 1 Example 4.2.1: Get available commands, pick a context and get help there as well [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. **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 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 [config]: set -h usage: set