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 library for the development of external client applications for Synnefo. The clients library API is detailed in the `Clients lib `_ section. Quick Setup ----------- Kamaki interfaces rely on a list of configuration options. A detailed guide for setting up kamaki can be found in the `Setup `_ section. 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: .. code-block:: console :emphasize-lines: 1 Example 1.1: Set authentication URL, user token and cloud alias "default" $ kamaki config set cloud.default.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. 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. 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 * re-run old commands with /history In favor of one-command: * 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', '-V', '- - version'. .. code-block:: console :emphasize-lines: 1 Example 2.2.2: Run kamaki shell with custom configuration file $ kamaki -c 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 servers managed by user $ kamaki server list One-command interface --------------------- Using help ^^^^^^^^^^ Kamaki help provides information on available commands (description, syntax and corresponding optional arguments). To see the command groups, 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). .. code-block:: console :emphasize-lines: 1 Example 3.1.1: kamaki help shows available parameters and command groups $ kamaki -h usage: kamaki [ ...] [-v] [-s] [-V] [-d] [-i] [-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 Override a config value --cloud CLOUD Chose a cloud to connect to -h, --help Show help message 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 flavor: Cyclades/Compute API flavor commands config: Kamaki configurations image: Cyclades/Plankton API image commands image compute: Cyclades/Compute API image commands history: Kamaki command history .. code-block:: console :emphasize-lines: 1,2 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] [-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 Override a config value --cloud CLOUD Chose a cloud to connect to -h, --help Show help message 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 create: Create a server (aka Virtual Machine) list: List Virtual Machines 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] .. code-block:: console :emphasize-lines: 1,2 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] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h] [--since SINCE] [--enumerate] [-l] [--more] [-n LIMIT] [-j] List Virtual Machines accessible by user 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 raw connection data in the output -c CONFIG, --config CONFIG Path to config file -o OPTIONS, --options OPTIONS Override a config value --cloud CLOUD Chose a cloud to connect to -h, --help Show help message --status STATUS filter by status (ACTIVE, STOPPED, REBOOT, ERROR, etc.) --enumerate Enumerate results --name-suffix NAME_SUFF filter by name suffix (case insensitive) --image-id IMAGE_ID filter by image id --metadata META filter by metadata key=values -j, --json show headers in json --id ID filter by id --user-id USER_ID filter by user id --id-like ID_LIKE print only if id contains this (case insensitive) --id-suffix ID_SUFF filter by id suffix (case insensitive) --since SINCE show only items since date (' d/m/Y H:M:S ') -l, --details show detailed output --name NAME filter by name --more output results in pages (-n to set items per page, default 10) --name-prefix NAME_PREF filter by name prefix (case insensitive) -n LIMIT, --number LIMIT limit number of listed virtual servers --id-prefix ID_PREF filter by id prefix (case insensitive) --user-name USER_NAME filter by user name --name-like NAME_LIKE print only if name contains this (case insensitive) --metadata-like META_LIKE print only if in key=value, the value is part of actual value --flavor-id FLAVOR_ID filter by flavor id Details: Use filtering arguments (e.g., --name-like) to manage long server lists .. _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 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 and logging ^^^^^^^^^^^^^^^^^ Debug """"" When in debug mode, kamaki outputs some useful debug information (stack trace and http logs). Kamaki in debug mode cancels suppression of warning messages. To run kamaki in debug mode use the -d or --debug option. Verbose """"""" 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/- - verbose* option 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) .. tip:: Use the -o runtime option to enable config options on the fly, e.g, to include http data: .. code-block:: console $ kamaki server list -v -o log_data=on 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 config set log_file /new/log/file/path Kamaki logs http request and response information, namely the method, URL, headers and data size. Sensitive information (data and token header) are omitted by default. There are some configuration options that can switch them on, though: * HTTP data blocks are not logged by default to enable logging the full http bodies, set log_data to `on`:: kamaki config set log_data on to disable it, set it to `off`:: kamaki config set log_data off or delete it:: kamaki config delete log_data * X-Auth-Token header is not logged by default to enable logging the X-Auth-Token header, set log_token to `on`:: kamaki config set log_token on to disable it, set it to `off`:: kamaki config set log_token off or delete it:: kamaki config delete log_token * The information (pid, name, date) of the processes that handle http requests is not logged by default, because if they are, logs are difficult to read. Still, they are useful for resolving race condition problems, so to enable logging proccess information:: kamaki config set log_pid on to disable it, set if to off:: kamaki config set log_pid off or delete it:: kamaki config delete log_pid 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 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). .. 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=* 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: Start kamaki and switch to file context $ 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 ... (servers 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 ... (servers 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 may change from context to context .. code-block:: console :emphasize-lines: 1 Example 4.2.1: Get available commands and then get help in a context [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