X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/59cadffbe83582bda5116ada81e97525be1ac616..9360f3989e2484d0528e68fb72bff90fa0643ced:/docs/usage.rst diff --git a/docs/usage.rst b/docs/usage.rst index 6150ec5..ecbe0d8 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,42 +1,49 @@ 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. +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. The recommended method of utilizing this API is explained in the present. +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. +Kamaki interfaces rely on a list of configuration options. A detailed guide for +setting up kamaki can be found in the `Setup `_ section. -It is essential for users to get a configuration token (okeanos.grnet.gr users go `here `_) and provide it to kamaki: +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 user token to myt0k3n== + Example 1.1: Set authentication URL, user token and cloud alias "default" - $ kamaki set token myt0k3n== + $ kamaki config set cloud.default.url + $ kamaki config set cloud.default.token myt0k3n== -To use the storage service, a user should also provide the corresponding user-name: - -.. code-block:: console - :emphasize-lines: 1 - - Example 1.2: Set user name to user@domain.com - - $ kamaki set account user@domain.com +.. 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 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. +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 -* session history with "up" / "down" keys +* tab completion for commands (if supported by host command line shell) +* session history with ↑ or ↓ keys (if supported by host command line shell) * shorter commands with command context switching +* re-run old commands with /history In favor of one-command behavior: @@ -64,7 +71,7 @@ To use kamaki as a shell, run: Example 2.2.2: Run kamaki shell with custom configuration file - $ kamaki --config myconfig.file + $ kamaki -c myconfig.file Run as one-command @@ -92,14 +99,16 @@ To use kamaki as an one-command tool, run: One-command interface --------------------- -Kamaki usage as a one-command tool is detailed in this section - Using help ^^^^^^^^^^ -Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments. +Kamaki help is used to list available commands with description, syntax and +corresponding optional arguments. -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. +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 @@ -109,7 +118,7 @@ To see the command groups, users should use -h or --help like in example 1.3.1. $ kamaki -h usage: kamaki [ ...] - [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h] + [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h] optional arguments: -v, --verbose More info at response @@ -117,31 +126,34 @@ To see the command groups, users should use -h or --help like in example 1.3.1. -V, --version Print current version -d, --debug Include debug output -i, --include Include protocol headers in the output - --config CONFIG Path to configuration file + -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: - - - - - astakos: Astakos API commands - config : Configuration commands - flavor : Compute/Cyclades API flavor commands - history: Command history - image : Compute/Cyclades or Plankton API image commands - network: Compute/Cyclades API network commands - server : Compute/Cyclades API server commands - store : Pithos+ storage commands + config : Kamaki configurations + file : Pithos+/Storage API commands + flavor : Cyclades/Compute API flavor commands + history: Kamaki command history + image : Cyclades/Plankton API image commands + image compute: Cyclades/Compute API image commands + network: Cyclades/Compute API network commands + server : Cyclades/Compute API server commands + user : Astakos API commands .. code-block:: console - :emphasize-lines: 1 - - Example 3.1.2: Cyclades help contains all first-level commands of Cyclades command group + :emphasize-lines: 1,2 + Example 3.1.2: Cyclades help contains all first-level commands of Cyclades + command group - $ kamaki cyclades -h - usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG] - [-o OPTIONS] [-h] + $ 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 @@ -149,53 +161,66 @@ To see the command groups, users should use -h or --help like in example 1.3.1. -V, --version Print current version -d, --debug Include debug output -i, --include Include protocol headers in the output - --config CONFIG Path to configuration file + -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: - - - - - 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 + addr : List the addresses of all network interfaces on a server (VM) + console : Get a VNC console to access an existing server (VM) + create : Create a server (aka Virtual Machine) + delete : Delete a server (VM) + firewall: Manage server (VM) firewall profiles for public networks + info : Detailed information on a Virtual Machine + list : List Virtual Machines accessible by user + metadata: Manage Server metadata (key:value pairs of server attributes) + reboot : Reboot a server (VM) + rename : Set/update a server (VM) name + shutdown: Shutdown an active server (VM) + start : Start an existing server (VM) + stats : Get server (VM) 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 + :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] [-i] [--config CONFIG] [-h] [-l] + 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 servers + List Virtual Machines accessible by user + User Authentication: + * to check authentication: /user authenticate + * to set authentication token: /config set cloud.default.token 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 + -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 configuration file + -o OPTIONS, --options OPTIONS + Override a config value + --cloud CLOUD Chose a cloud to connect to + -h, --help Show help message + --since SINCE show only items since date (' d/m/Y H:M:S ') + --enumerate Enumerate results + -l, --details show detailed output + --more output results in pages (-n to set items per page, + default 10) + -n LIMIT, --number LIMIT + limit number of listed VMs + -j, --json show headers in json .. _using-history-ref: @@ -213,9 +238,11 @@ Every syntactically correct command is appended at the end of that file. In orde $ kamaki history -h - ... - clean: Clean up history - show : Show history + 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 @@ -235,20 +262,70 @@ The following example showcases how to use history in kamaki 1. kamaki server list 3. kamaki history show --match server +Debug and logging +^^^^^^^^^^^^^^^^^ + Debug -^^^^^ +""""" -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. +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 +To run kamaki in debug mode use the -d or --debug option (can be combined with +any other parameters or options) -Verbose +Logging """"""" -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. +Kamaki keeps its logs in a file specified as global.log_file and its value +defaults to ${HOME}/.kamaki.log . This value may change with a config setting:: + + kamaki config set log_file /new/log/file/path + +Kamaki logs mostly the http connection requests and responses, including http +methods, urls, parameters and headers. There is some special handling in two +cases: + +* HTTP bodies 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 + +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 ^^^^^^^^^^^^^^^^^^^^ @@ -257,44 +334,55 @@ 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 + Example 3.4.1: List the trash container contents, containing c1_ - $ kamaki astakos authenticate -o token=us3rt0k3n== | grep uniq - uniq : user@synnefo.org + $ 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 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). +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 astakos-authenticate command in example 3.4.1 run against an explicitly provided token, which temporarily overrode the token provided in the configuration file. +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). Interactive shell ----------------- -Kamaki interactive shell is details in this section - 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 ("store" in example 4.1.1). +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 store commands context / group + Example 4.1.1: Enter file commands context / group $ kamaki - [kamaki]:store - [store]: + [kamaki]: file + [file]: -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. +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 store context and then exit kamaki + Example 4.1.2: Exit file context and then exit kamaki - [store]: exit + [file]: exit [kamaki]: exit $ @@ -306,21 +394,22 @@ A user might **browse** through different contexts during one session. Example 4.1.3: Execute list command in different contexts $ kamaki - [kamaki]:config - [config]:list + [kamaki]: config + [config]: list ... (configuration options listing) ... - [config]:exit - [kamaki]:store - [store]:list + [config]: exit + [kamaki]: file + [file]: list ... (storage containers listing) ... - [store]:exit - [kamaki]:server - [server]:list + [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. +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 @@ -328,11 +417,11 @@ Users have the option to avoid switching between contexts: all commands can run Example 4.1.4: Execute different "list" commands from top context - [kamaki]:config list + [kamaki]: config list ... (configuration options listing) ... - [kamaki]:store list + [kamaki]: file list ... (storage container listing) ... - [kamaki]:server list + [kamaki]: server list ... (VMs listing) ... [kamaki]: @@ -341,42 +430,43 @@ 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** 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]:? + [context]: help + [context]: ? * Show help for command cmd * - [context]:help cmd - [context]:?cmd + [context]: help cmd + [context]: ?cmd -The context-level help results change from context to context +The context-level help results may 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 + Example 4.2.1: Get available commands and then get help in a context - [kamaki]:help + [kamaki]: help kamaki commands: ================ - astakos config flavor history image network server store + user config flavor history image network server file interactive shell commands: =========================== exit help shell - [kamaki]:?config + [kamaki]: ?config Configuration commands (config -h for more options) - [kamaki]:config + [kamaki]: config - [config]:? + [config]: ? config commands: ================ @@ -386,24 +476,30 @@ The context-level help results change from context to context =========================== exit help shell - [config]:help set + [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. +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** 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 + [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. +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 @@ -411,16 +507,16 @@ Command-level help mechanism is exactly the same as the one used in one-command Example 4.2.2: Get command-level help for config and config-set - [kamaki]:config --help + [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 + [kamaki]: config - [config]:set -h + [config]: set -h usage: set