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 <clients.html>`_ 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.
16 It is essential for users to get a configuration token (to get in Okeanos.grnet.gr log `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
18 .. code-block:: console
21 Example 1.1.1: Set user token to myt0k3n==
23 $ kamaki set token myt0k3n==
25 To use the storage service, a user should also provide the corresponding user-name:
27 .. code-block:: console
30 Example 1.1.2: Set user name to user@domain.com
32 $ kamaki set account user@domain.com
36 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.
38 In favor of interactive shell behavior:
40 * tab completion for commands
41 * session history with "up" / "down" keys
42 * shorter commands with command context switching
44 In favor of one-command behavior:
46 * can be used along with advanced shell features (pipelines, redirection, etc.)
47 * can be used in shell scripts
48 * prints debug and verbose messages if needed
52 To use kamaki as a shell, run:
54 * without any parameters or arguments
56 .. code-block:: console
59 Example 2.2.1: Run kamaki shell
63 * with any kind of '-' prefixed arguments, except '-h', '--help'.
65 .. code-block:: console
68 Example 2.2.2: Run kamaki shell with custom configuration file
70 $ kamaki --config myconfig.file
75 To use kamaki as an one-command tool, run:
77 * with the '-h' or '--help' arguments (help for kamaki one-command)
79 .. code-block:: console
82 Example 2.3.1: Kamaki help
86 * with one or more command parameters:
88 .. code-block:: console
91 Example 2.3.2: List VMs managed by user
98 Client commands are grouped by service (see example 3.1.1 on how to list available groups). Commands behavior is as uniform as possible, but there are still differences between groups due to the special nature of each service and server-side implementation.
100 Typically, commands consist of a group name (e.g. store for storage commands) one or more terms (e.g. list for listing) and the command specific parameters (e.g. the name of the container), if any.
102 .. code-block:: console
105 Example 3.1.1: List stored files in container mycontainer.
107 $ kamaki store list mycontainer
109 Example 2.3.2 showcases a command without parameters (the group is "server", the command is "list").
111 The "server" command group is also referred in the following example.
113 .. code-block:: console
116 Example 3.1.2 Show information about a user-managed VM with id 42
118 $ kamaki server info 42
120 Client commands can feature an arbitrary number of terms:
124 kamaki <group> <cmd term 1> <cmd term 2> ... <cmd term N> [arguments]
126 Although there are no multi-termed client commands until version 0.6.1 , the feature is supported and might be used in feature extensions.
128 The following pattern applies to all client commands up to version 0.6.1:
132 kamaki <group> <command> [arguments]
134 The commands supported in version 0.6.1 are described bellow, grouped by service. The examples showcase a sample set of group commands. The kamaki interactive shell has been chosen as the execution environment:
136 astakos (Identity Manager)
137 ^^^^^^^^^^^^^^^^^^^^^^^^^^
141 authenticate: Authenticate a user
143 Showcase: get user information, provided the token was set
145 .. code-block:: console
146 :emphasize-lines: 1,4
148 * Enter astakos context *
151 * Authenticate user *
152 [astakos]:authenticate
153 auth_token : s0m3t0k3nth@t1sr3m0v3d==
154 auth_token_created: 2012-11-13T14:12:40.917034
155 auth_token_expires: 2012-12-13T14:12:40.917035
159 has_signed_terms : True
160 uniq : myaccount@grnet.gr
161 username : 4215th3b357num9323v32
163 flavor (Compute/Cyclades)
164 ^^^^^^^^^^^^^^^^^^^^^^^^^
168 info: Get flavor details
171 Showcase: show details for flavor with id 43
173 .. code-block:: console
174 :emphasize-lines: 1,4
176 * Enter flavor context *
179 * Get details about flavor with id 43 *
181 SNF:disk_template: drbd
188 image (Compute/Cyclades + Glance)
189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
193 addmember : Add a member to an image
194 addproperty: Add an image property
195 delete : Delete image
196 delmember : Remove a member from an image
197 delproperty: Delete an image property
198 info : Get image details
200 members : Get image members
201 meta : Get image metadata
202 properties : Get image properties
203 public : List public images
204 register : (Re)Register an image
205 setmembers : Set the members of an image
206 setproperty: Update an image property
207 shared : List shared images
209 Showcase: Pick an image and list the properties
211 .. code-block:: console
212 :emphasize-lines: 1,4,18
214 * Enter image context *
217 * list all available images *
219 1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)
220 1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
221 18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)
222 6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
223 6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
224 78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
225 86bc2414-0fb3-4898-a637-240292243302 (Fedora)
226 926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
227 b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
228 baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
229 c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
231 * Get properties of image with id b2dffe52-64a4-48c3-8a4c-8214cc3165cf *
232 [image]:properties b2dffe52-64a4-48c3-8a4c-8214cc3165cf
233 description : Debian 6.0.6 (Squeeze) Base System
242 server (Compute/Cyclades)
243 ^^^^^^^^^^^^^^^^^^^^^^^^^
247 addmeta : Add server metadata
248 addr : List a server's nic address
249 console : Get a VNC console
250 create : Create a server
251 delete : Delete a server
252 delmeta : Delete server metadata
253 firewall: Set the server's firewall profile
254 info : Get server details
256 meta : Get a server's metadata
257 reboot : Reboot a server
258 rename : Update a server's name
259 setmeta : Update server's metadata
260 shutdown: Shutdown a server
261 start : Start a server
262 stats : Get server statistics
263 wait : Wait for server to finish
265 Showcase: Create a server.
267 .. code-block:: console
268 :emphasize-lines: 1,4,21,35,44,62
270 * Enter server context *
273 * See server-create help *
275 usage: create <name> <flavor id> <image id>
276 [--personality PERSONALITY] [-h] [--config CONFIG]
281 -v, --verbose More info at response
282 --personality PERSONALITY
283 add a personality file
284 -d, --debug Include debug output
285 -h, --help Show help message
286 -i, --include Include protocol headers in the output
287 --config CONFIG Path to configuration file
288 -s, --silent Do not output anything
290 * List all available images *
292 1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)
293 1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
294 18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)
295 6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
296 6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
297 78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
298 86bc2414-0fb3-4898-a637-240292243302 (Fedora)
299 926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
300 b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
301 baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
302 c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
304 * See details of flavor with id 1 *
305 [server]:/flavor info 1
306 SNF:disk_template: drbd
313 * Create a debian server named 'My Small Debian Server'
314 [server]:create 'My Small Debian Server' 1 b2dffe52-64a4-48c3-8a4c-8214cc3165cf
315 adminPass: L8gu2wbZ94
316 created : 2012-11-23T16:56:04.190813+00:00
320 imageRef : b2dffe52-64a4-48c3-8a4c-8214cc3165cf
325 name : My Small Debian Server
329 updated : 2012-11-23T16:56:04.761962+00:00
331 * wait for server to build (optional) *
333 Server 11687 still in BUILD mode ||||||||||||||||| | 80% - 3s
334 Server 11687 is now in ACTIVE mode
336 .. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
338 network (Compute/Cyclades)
339 ^^^^^^^^^^^^^^^^^^^^^^^^^^
343 connect : Connect a server to a network
344 create : Create a network
345 delete : Delete a network
346 disconnect: Disconnect a nic of a server to a network
347 info : Get network details
349 rename : Update network name
351 Showcase: Connect a network to a VM
353 .. code-block:: console
354 :emphasize-lines: 1,4,9,24,27,44
356 * Enter network context *
359 * List user-owned VMs *
360 [network]:/server list
361 11687 (My Small Debian Server)
362 11688 (An Ubuntu server)
364 * Try network-connect (to get help) *
367 usage: connect <server id> <network id> [-s] [-h] [-i] [--config CONFIG]
369 Connect a server to a network
371 Syntax: connect <server id> <network id>
372 --config : Path to configuration file
373 -d,--debug : Include debug output
374 -h,--help : Show help message
375 -i,--include: Include protocol headers in the output
376 -s,--silent : Do not output anything
377 -v,--verbose: More info at response
379 * Connect VM with id 11687 to network with id 1409
380 [network]: connect 11687 1409
382 * Get details on network with id 1409
386 cidr : 192.168.1.0/24
388 created : 2012-11-23T17:17:20.560098+00:00
396 type : PRIVATE_MAC_FILTERED
397 updated : 2012-11-23T17:18:25.095225+00:00
399 * Get connectivity details on VM with id 11687 *
400 [network]:/server addr 11687
404 mac_address: aa:0f:c2:0b:0e:85
406 firewallProfile: DISABLED
408 ipv4 : 83.212.106.111
409 ipv6 : 2001:648:2ffc:1116:a80c:f2ff:fe12:a9e
410 mac_address : aa:0c:f2:12:0a:9e
413 .. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
415 store (Storage/Pithos+)
416 ^^^^^^^^^^^^^^^^^^^^^^^
420 append : Append local file to remote
421 cat : Print a file to console
422 copy : Copy an object
423 create : Create a container or a directory object
424 delete : Delete a container [or an object]
425 delgroup : Delete a user group on an account
426 delmeta : Delete an existing metadatum of account [, container [or object]]
427 delpermissions: Delete all sharing permissions
428 download : Download a file
429 group : Get user groups details for account
430 hashmap : Get the hashmap of an object
431 info : Get information for account [, container [or object]]
432 list : List containers, object trees or objects in a directory
433 manifest : Create a remote file with uploaded parts by manifestation
434 meta : Get custom meta-content for account [, container [or object]]
435 mkdir : Create a directory
436 move : Copy an object
437 overwrite : Overwrite part (from start to end) of a remote file
438 permissions : Get object read/write permissions
439 publish : Publish an object
440 purge : Purge a container
441 quota : Get quota for account [or container]
442 setgroup : Create/update a new user group on account
443 setmeta : Set a new metadatum for account [, container [or object]]
444 setpermissions: Set sharing permissions
445 setquota : Set new quota (in KB) for account [or container]
446 setversioning : Set new versioning (auto, none) for account [or container]
447 sharers : List the accounts that share objects with default account
448 truncate : Truncate remote file up to a size
449 unpublish : Unpublish an object
450 upload : Upload a file
451 versioning : Get versioning for account [or container ]
452 versions : Get the version list of an object
454 Showcase: Upload and download a file.
456 .. code-block:: console
457 :emphasize-lines: 1,7,11,16,21,29,33,37,41,44,51,55,60,64
459 * Create a random binarry file at current OS path *
460 [kamaki]:!dd bs=4M if=/dev/zero of=rndm_local.file count=5
463 20971520 bytes (21 MB) copied, 0.016162 s, 1.3 GB/s
465 * Enter store context *
470 [store]:!ls -lh rndm_local.file
471 -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
474 * Create two containers *
475 [store]:create mycont1
476 [store]:create mycont2
479 * List accessible containers *
481 1. mycont1 (0B, 0 objects)
482 2. mycont2 (0B, 0 objects)
483 3. pithos (0B, 0 objects)
484 4. trash (0B, 0 objects)
487 * Upload local file to 1st container *
488 [store]:upload rndm_local.file mycont1
491 * Check if file has been uploaded *
493 1. 20M rndm_local.file
495 * Create director mydir on second container *
496 [store]:mkdir mycont2:mydir
499 * Move file from 1st to 2nd container (and in the directory) *
500 [store]:move mycont1:rndm_local.file mycont2:mydir/rndm_local.file
502 * Check the container of both containers *
506 2. 20M mydir/rndm_local.file
509 * Copy file from 2nd to 1st container, with a new name *
510 [store]:copy mycont2:mydir/rndm_local.file mycont1:rndm_remote.file
513 * Check pasted file *
515 1. 20M rndm_remote.file
518 * Download pasted file to local file system *
519 [store]:download mycont1:rndm_remote.file rndm_remote.file
522 * Check if file is downloaded and if it is the same to original *
523 [store]:!ls -lh *.file
524 -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
525 -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:42 rndm_remote.file
526 [store]:!diff rndm_local.file rndm_remote.file
528 .. Note:: In kamaki shell, ! is used to execute OS shell commands (bash in the above)
530 One-command interface
531 ---------------------
533 Kamaki usage as a one-command tool is detailed in this section
538 Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments.
540 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.
542 .. code-block:: console
545 Example 4.1.1: kamaki help shows available parameters and command groups
549 usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
550 [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h]
553 -v, --verbose More info at response
554 -s, --silent Do not output anything
555 -V, --version Print current version
556 -d, --debug Include debug output
557 -i, --include Include protocol headers in the output
558 --config CONFIG Path to configuration file
559 -o OPTIONS, --options OPTIONS
560 Override a config value
561 -h, --help Show help message
565 astakos: Astakos API commands
566 config : Configuration commands
567 flavor : Compute/Cyclades API flavor commands
568 history: Command history
569 image : Compute/Cyclades or Glance API image commands
570 network: Compute/Cyclades API network commands
571 server : Compute/Cyclades API server commands
572 store : Pithos+ storage commands
574 .. code-block:: console
577 Example 4.1.2: Cyclades help contains all first-level commands of Cyclades command group
581 usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
585 -v, --verbose More info at response
586 -s, --silent Do not output anything
587 -V, --version Print current version
588 -d, --debug Include debug output
589 -i, --include Include protocol headers in the output
590 --config CONFIG Path to configuration file
591 -o OPTIONS, --options OPTIONS
592 Override a config value
593 -h, --help Show help message
597 addmeta : Add server metadata
598 addr : List a server's nic address
599 console : Get a VNC console
600 create : Create a server
601 delete : Delete a server
602 delmeta : Delete server metadata
603 firewall: Set the server's firewall profile
604 info : Get server details
606 meta : Get a server's metadata
607 reboot : Reboot a server
608 rename : Update a server's name
609 setmeta : Update server's metadata
610 shutdown: Shutdown a server
611 start : Start a server
612 stats : Get server statistics
613 wait : Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
615 .. code-block:: console
618 Example 4.1.3: Help for command "server list" with syntax, description and available user options
621 $ kamaki server list -h
622 usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l]
627 -v, --verbose More info at response
628 -s, --silent Do not output anything
629 -V, --version Print current version
630 -d, --debug Include debug output
631 -i, --include Include protocol headers in the output
632 --config CONFIG Path to configuration file
633 -o OPTIONS, --options OPTIONS
634 Override a config value
635 -h, --help Show help message
636 -l show detailed output
638 .. _using-history-ref:
643 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>`_).
645 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:
647 .. code-block:: console
650 Example 4.2.1: Available history options
655 clean: Clean up history
658 The following example showcases how to use history in kamaki
660 .. code-block:: console
663 Example 4.2.2: Clean up everything, run a kamaki command, show full and filtered history
666 $ kamaki history clean
669 $ kamaki history show
670 1. kamaki server list
671 2. kamaki history show
672 $ kamaki history show --match server
673 1. kamaki server list
674 3. kamaki history show --match server
679 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.
681 To run kamaki in debug mode use the -d or --debug option
686 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.
688 To run kamaki in verbose mode use the -v or --verbose option
693 Kamaki commands can be used along with advanced shell features.
695 .. code-block:: console
698 Example 4.4.1: Print username for token us3rt0k3n== using grep
701 $ kamaki astakos authenticate -o token=us3rt0k3n== | grep uniq
702 uniq : user@synnefo.org
704 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).
706 The astakos-authenticate command in example 4.4.1 run against an explicitly provided token, which temporarily overrode the token provided in the configuration file.
711 Kamaki interactive shell is details in this section
716 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 5.1.1).
718 .. code-block:: console
721 Example 5.1.1: Enter store commands context / group
728 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.
730 .. code-block:: console
733 Example 5.1.2: Exit store context and then exit kamaki
739 A user might **browse** through different contexts during one session.
741 .. code-block:: console
744 Example 5.1.3: Execute list command in different contexts
749 ... (configuration options listing) ...
753 ... (storage containers listing) ...
757 ... (VMs listing) ...
761 Users have the option to avoid switching between contexts: all commands can run from the **top context**. As a result, examples 5.1.3 and 5.1.4 are equivalent.
763 .. code-block:: console
766 Example 5.1.4: Execute different "list" commands from top context
770 ... (configuration options listing) ...
772 ... (storage container listing) ...
774 ... (VMs listing) ...
780 There are two help mechanisms: a context-level and a command-level.
782 **Context-level help** lists the available commands in a context and can also offer a short description for each command.
784 Context-level help syntax::
786 * Show available commands in current context *
790 * Show help for command cmd *
794 The context-level help results change from context to context
796 .. code-block:: console
799 Example 5.2.1: Get available commands, pick a context and get help there as well
806 astakos config flavor history image network server store
808 interactive shell commands:
809 ===========================
813 Configuration commands (config -h for more options)
823 interactive shell commands:
824 ===========================
828 Set a configuration option (set -h for more options)
830 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.
832 **Command-level help** prints the syntax, arguments and description of a specific (terminal) command
834 Command-level help syntax::
836 * Get help for command cmd1 cmd2 ... cmdN *
837 [context]:cmd1 cmd2 ... cmdN -h
842 <arguments and possible extensions>
844 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.
846 .. code-block:: console
849 Example 5.2.2: Get command-level help for config and config-set
852 [kamaki]:config --help
853 config: Configuration commands
854 delete: Delete a configuration option (and use the default value)
855 get : Show a configuration option
856 list : List configuration options
857 set : Set a configuration option
862 usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
864 Set a configuration option
867 -v, --verbose More info at response
868 -d, --debug Include debug output
869 -h, --help Show help message
870 -i, --include Include protocol headers in the output
871 --config CONFIG Path to configuration file
872 -s, --silent Do not output anything
874 There are many ways of producing a help message, as shown in example 5.2.3
876 .. code-block:: console
879 Example 5.2.3: Equivalent calls of command-level help for config-set
884 [kamaki]:config set -h
885 [kamaki]:config set --help
886 [store]:/config set -h
887 [server]:/config set --help
889 .. _accessing-top-level-commands-ref:
891 Accessing top-level commands
892 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
894 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::
896 * access a command "anothercontext cmd1 cmd2 ... cmdN"
897 [context]:/anothercontext cmd1 cmd2 ... cmdN
899 An example (5.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:
901 * the name of the new VM
905 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.
907 .. code-block:: console
910 Example 5.3.1: Create a VM from server context
913 create <name> <flavor id> <image id> ...
916 [server]:/flavor list
919 SNF:disk_template: drbd
926 1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
927 18a82962-43eb-8f8880af89d7 (Windows 7)
928 531aa018-9a40-a4bfe6a0caff (Windows XP)
929 6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
931 [server]:create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
934 An other example (5.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.
936 .. code-block:: console
939 Example 5.3.2: Set a new token from store context
943 (401) UNAUTHORIZED Access denied
945 [store]:/astakos authenticate
946 (401) UNAUTHORIZED Invalid X-Auth-Token
948 [store]:/config get token
951 [store]:/config set token myfr35ht0k3n==
953 [store]:/config get token
957 1. pithos (10MB, 2 objects)
958 2. trash (0B, 0 objects)
960 The following example compares some equivalent calls that run *astakos-authenticate* after a *store-list* 401 failure.
962 .. code-block:: console
963 :emphasize-lines: 1,3,10,17,26
965 Example 5.3.3: Equivalent astakos-authenticate calls after a store-list 401 failure
967 * without kamaki interactive shell *
969 (401) UNAUTHORIZED Access denied
970 $ kamaki astakos authenticate
974 * from top-level context *
976 (401) UNAUTHORIZED Access denied
977 [kamaki]:astakos authenticate
983 (401) UNAUTHORIZED Access denied
986 [astakos]:authenticate
992 (401) UNAUTHORIZED Access denied
993 [store]:/astakos authenticate
997 .. hint:: To exit kamaki shell while in a context, try */exit*
1002 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.
1004 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.
1006 .. 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)
1008 In example 5.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.
1010 .. code-block:: console
1013 Example 5.4.1: Set default storage container
1017 1. mycontainer (32MB, 2 objects)
1018 2. pithos (0B, 0 objects)
1019 3. trash (2MB, 1 objects)
1021 [store]:list mycontainer
1023 2. 20M mydir/rndm_local.file
1025 [store]:/config set store.container mycontainer
1029 2. 20M mydir/rndm_local.file
1031 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 5.4.2 .
1033 .. code-block:: console
1036 Example 5.4.2: Delete a setting option
1039 [store]:/config delete store.container
1042 1. mycontainer (32MB, 2 objects)
1043 2. pithos (0B, 0 objects)
1044 3. trash (2MB, 1 objects)
1046 .. 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.
1051 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.
1053 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
1055 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).
1060 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 ).
1062 OS Shell integration
1063 ^^^^^^^^^^^^^^^^^^^^
1065 Kamaki shell features the ability to execute OS-shell commands from any context. This can be achieved by typing *!* or *shell*::
1067 [kamaki_context]:!<OS shell command>
1068 ... OS shell command output ...
1070 [kamaki_context]:shell <OS shell command>
1071 ... OS shell command output ...
1073 .. code-block:: console
1076 Example 5.7.1: Run unix-style shell commands from kamaki shell
1081 drwxrwxr-x 2 saxtouri saxtouri 4096 Nov 27 16:47 .
1082 drwxrwxr-x 7 saxtouri saxtouri 4096 Nov 27 16:47 ..
1083 -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 kamaki-logo.png
1085 [kamaki]:shell cp kamaki-logo.png logo-copy.png
1087 [kamaki]:shell ls -al
1089 drwxrwxr-x 2 saxtouri saxtouri 4096 Nov 27 16:47 .
1090 drwxrwxr-x 7 saxtouri saxtouri 4096 Nov 27 16:47 ..
1091 -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 kamaki-logo.png
1092 -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 logo-copy.png
1095 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 5.7.2 .
1097 .. code-block:: console
1100 Example 5.7.2: Attempt (and fail) to change working directory
projects / kamaki / blob