root / docs / usage.rst @ f6822a26
History | View | Annotate | Download (28 kB)
1 |
Usage |
---|---|
2 |
===== |
3 |
|
4 |
Kamaki offers command-line interfaces that implement specific command |
5 |
specifications. A detailed list of the command specifications can be found in |
6 |
`Commands <commands.html>`_ section. This guide covers the generic usage of |
7 |
both interfaces. |
8 |
|
9 |
What's more, kamaki offers a clients library for the development of external |
10 |
client applications for Synnefo. The clients library API is detailed in the |
11 |
`Clients lib <developers/code.html#the-clients-api>`_ section. |
12 |
|
13 |
Quick Setup |
14 |
----------- |
15 |
|
16 |
Kamaki interfaces rely on a list of configuration options. A detailed guide for |
17 |
setting up kamaki can be found in the `Setup <setup.html>`_ section. |
18 |
|
19 |
As rule of the thump, it is enough to set the authentication URL and user token |
20 |
for the cloud kamaki should communicate with by default: |
21 |
|
22 |
.. code-block:: console |
23 |
:emphasize-lines: 1 |
24 |
|
25 |
Example 1.1: Set authentication URL, user token and cloud alias "default" |
26 |
|
27 |
$ kamaki config set cloud.default.url <authentication URL> |
28 |
$ kamaki config set cloud.default.token myt0k3n== |
29 |
|
30 |
.. note:: The term *default* can be replaced by any arbitary term chosen by |
31 |
the user. This term will serve as a cloud alias for kamaki users, and can |
32 |
be easily modified. |
33 |
|
34 |
Shell vs one-command |
35 |
-------------------- |
36 |
Kamaki users can access Synnefo services through either the interactive shell |
37 |
or the one-command interface. In practice, both systems rely on the same |
38 |
command set implementations and API clients, with identical responses and error |
39 |
messages. Still, there are some differences. |
40 |
|
41 |
In favor of interactive shell: |
42 |
|
43 |
* tab completion for commands (if supported by the user's shell) |
44 |
* session history with ↑ or ↓ keys (if supported by the user's shell) |
45 |
* shorter commands with command context switching |
46 |
* re-run old commands with /history |
47 |
|
48 |
In favor of one-command: |
49 |
|
50 |
* can be used along with advanced shell features (pipelines, redirection, etc.) |
51 |
* can be used in shell scripts |
52 |
* prints debug and verbose messages if needed |
53 |
|
54 |
Run as shell |
55 |
^^^^^^^^^^^^ |
56 |
To use kamaki as a shell, run: |
57 |
|
58 |
* without any parameters or arguments |
59 |
|
60 |
.. code-block:: console |
61 |
:emphasize-lines: 1 |
62 |
|
63 |
Example 2.2.1: Run kamaki shell |
64 |
|
65 |
$ kamaki |
66 |
|
67 |
* with any kind of '-' prefixed arguments, except '-h', '--help', '-V', |
68 |
'- - version'. |
69 |
|
70 |
.. code-block:: console |
71 |
:emphasize-lines: 1 |
72 |
|
73 |
Example 2.2.2: Run kamaki shell with custom configuration file |
74 |
|
75 |
$ kamaki -c myconfig.file |
76 |
|
77 |
|
78 |
Run as one-command |
79 |
^^^^^^^^^^^^^^^^^^ |
80 |
To use kamaki as an one-command tool, run: |
81 |
|
82 |
* with the '-h' or '--help' arguments (help for kamaki one-command) |
83 |
|
84 |
.. code-block:: console |
85 |
:emphasize-lines: 1 |
86 |
|
87 |
Example 2.3.1: Kamaki help |
88 |
|
89 |
$kamaki -h |
90 |
|
91 |
* with one or more command parameters: |
92 |
|
93 |
.. code-block:: console |
94 |
:emphasize-lines: 1 |
95 |
|
96 |
Example 2.3.2: List servers managed by user |
97 |
|
98 |
$ kamaki server list |
99 |
|
100 |
One-command interface |
101 |
--------------------- |
102 |
|
103 |
Using help |
104 |
^^^^^^^^^^ |
105 |
|
106 |
Kamaki help provides information on available commands (description, syntax and |
107 |
corresponding optional arguments). |
108 |
|
109 |
To see the command groups, use -h or --help (example 1.3.1). The |
110 |
following examples demonstrate the help messages of kamaki, in the context of a |
111 |
command group (server) and of a command in that group (list). |
112 |
|
113 |
.. code-block:: console |
114 |
:emphasize-lines: 1 |
115 |
|
116 |
Example 3.1.1: kamaki help shows available parameters and command groups |
117 |
|
118 |
|
119 |
$ kamaki -h |
120 |
usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd> |
121 |
[-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h] |
122 |
|
123 |
optional arguments: |
124 |
-v, --verbose More info at response |
125 |
-s, --silent Do not output anything |
126 |
-V, --version Print current version |
127 |
-d, --debug Include debug output |
128 |
-i, --include Include protocol headers in the output |
129 |
-c CONFIG, --config CONFIG |
130 |
Path to configuration file |
131 |
-o OPTIONS, --options OPTIONS |
132 |
Override a config value |
133 |
--cloud CLOUD Chose a cloud to connect to |
134 |
-h, --help Show help message |
135 |
|
136 |
Options: |
137 |
- - - - |
138 |
network: Cyclades/Compute API network commands |
139 |
user: Astakos API commands |
140 |
livetest: Client func. tests on live servers |
141 |
server: Cyclades/Compute API server commands |
142 |
project: Synnefo project management CLI |
143 |
file: Pithos+/Storage API commands |
144 |
flavor: Cyclades/Compute API flavor commands |
145 |
config: Kamaki configurations |
146 |
image: Cyclades/Plankton API image commands |
147 |
image compute: Cyclades/Compute API image commands |
148 |
history: Kamaki command history |
149 |
|
150 |
|
151 |
.. code-block:: console |
152 |
:emphasize-lines: 1,2 |
153 |
|
154 |
Example 3.1.2: Cyclades help contains all first-level commands of Cyclades |
155 |
command group |
156 |
|
157 |
$ kamaki server -h |
158 |
usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG] |
159 |
[-o OPTIONS] [--cloud CLOUD] [-h] |
160 |
|
161 |
optional arguments: |
162 |
-v, --verbose More info at response |
163 |
-s, --silent Do not output anything |
164 |
-V, --version Print current version |
165 |
-d, --debug Include debug output |
166 |
-i, --include Include protocol headers in the output |
167 |
-c CONFIG, --config CONFIG |
168 |
Path to configuration file |
169 |
-o OPTIONS, --options OPTIONS |
170 |
Override a config value |
171 |
--cloud CLOUD Chose a cloud to connect to |
172 |
-h, --help Show help message |
173 |
|
174 |
Options: |
175 |
- - - - |
176 |
info: Detailed information on a Virtual Machine |
177 |
rename: Set/update a virtual server name |
178 |
delete: Delete a virtual server |
179 |
console: Get a VNC console to access an existing virtual server |
180 |
addr: List the addresses of all network interfaces on a virtual server |
181 |
firewall: Manage virtual server firewall profiles for public networks |
182 |
ip: Manage floating IPs for the servers |
183 |
create: Create a server (aka Virtual Machine) |
184 |
list: List Virtual Machines accessible by user |
185 |
reboot: Reboot a virtual server |
186 |
start: Start an existing virtual server |
187 |
shutdown: Shutdown an active virtual server |
188 |
stats: Get virtual server statistics |
189 |
metadata: Manage Server metadata (key:value pairs of server attributes) |
190 |
resize: Set a different flavor for an existing server |
191 |
wait: Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE] |
192 |
|
193 |
.. code-block:: console |
194 |
:emphasize-lines: 1,2 |
195 |
|
196 |
Example 3.1.3: Help for command "server list" with syntax, description and |
197 |
available user options |
198 |
|
199 |
$ kamaki server list -h |
200 |
usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] |
201 |
[--cloud CLOUD] [-h] [--since SINCE] [--enumerate] |
202 |
[-l] [--more] [-n LIMIT] [-j] |
203 |
|
204 |
List Virtual Machines accessible by user |
205 |
|
206 |
optional arguments: |
207 |
-v, --verbose More info at response |
208 |
-s, --silent Do not output anything |
209 |
-V, --version Print current version |
210 |
-d, --debug Include debug output |
211 |
-i, --include Include raw connection data in the output |
212 |
-c CONFIG, --config CONFIG |
213 |
Path to config file |
214 |
-o OPTIONS, --options OPTIONS |
215 |
Override a config value |
216 |
--cloud CLOUD Chose a cloud to connect to |
217 |
-h, --help Show help message |
218 |
--status STATUS filter by status (ACTIVE, STOPPED, REBOOT, ERROR, |
219 |
etc.) |
220 |
--enumerate Enumerate results |
221 |
--name-suffix NAME_SUFF |
222 |
filter by name suffix (case insensitive) |
223 |
--image-id IMAGE_ID filter by image id |
224 |
--metadata META filter by metadata key=values |
225 |
-j, --json show headers in json |
226 |
--id ID filter by id |
227 |
--user-id USER_ID filter by user id |
228 |
--id-like ID_LIKE print only if id contains this (case insensitive) |
229 |
--id-suffix ID_SUFF filter by id suffix (case insensitive) |
230 |
--since SINCE show only items since date (' d/m/Y H:M:S ') |
231 |
-l, --details show detailed output |
232 |
--name NAME filter by name |
233 |
--more output results in pages (-n to set items per page, |
234 |
default 10) |
235 |
--name-prefix NAME_PREF |
236 |
filter by name prefix (case insensitive) |
237 |
-n LIMIT, --number LIMIT |
238 |
limit number of listed virtual servers |
239 |
--id-prefix ID_PREF filter by id prefix (case insensitive) |
240 |
--user-name USER_NAME |
241 |
filter by user name |
242 |
--name-like NAME_LIKE |
243 |
print only if name contains this (case insensitive) |
244 |
--metadata-like META_LIKE |
245 |
print only if in key=value, the value is part of |
246 |
actual value |
247 |
--flavor-id FLAVOR_ID |
248 |
filter by flavor id |
249 |
|
250 |
Details: |
251 |
Use filtering arguments (e.g. --name-like) to manage long server lists |
252 |
|
253 |
.. _using-history-ref: |
254 |
|
255 |
Using history |
256 |
^^^^^^^^^^^^^ |
257 |
|
258 |
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>`_). |
259 |
|
260 |
Every command is appended at the end of that file. In order to see how to use |
261 |
history, use the kamaki help system: |
262 |
|
263 |
.. code-block:: console |
264 |
:emphasize-lines: 1 |
265 |
|
266 |
Example 3.2.1: Available history options |
267 |
|
268 |
|
269 |
$ kamaki history -h |
270 |
Options: |
271 |
- - - - |
272 |
clean: Clean up history (permanent) |
273 |
run : Run previously executed command(s) |
274 |
show : Show intersession command history |
275 |
|
276 |
The following example showcases how to use history in kamaki |
277 |
|
278 |
.. code-block:: console |
279 |
:emphasize-lines: 1 |
280 |
|
281 |
Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history |
282 |
|
283 |
|
284 |
$ kamaki history clean |
285 |
$ kamaki server list |
286 |
... |
287 |
$ kamaki history show |
288 |
1. kamaki server list |
289 |
2. kamaki history show |
290 |
$ kamaki history show --match server |
291 |
1. kamaki server list |
292 |
3. kamaki history show --match server |
293 |
|
294 |
Debug and logging |
295 |
^^^^^^^^^^^^^^^^^ |
296 |
|
297 |
Debug |
298 |
""""" |
299 |
|
300 |
When in debug mode, kamaki outputs some useful debug information (stack trace |
301 |
and http logs). Kamaki in debug mode cancels suppression of warning messages. |
302 |
|
303 |
To run kamaki in debug mode use the -d or --debug option. |
304 |
|
305 |
|
306 |
Verbose |
307 |
""""""" |
308 |
|
309 |
Most kamaki commands are translated into http requests. Kamaki clients API |
310 |
translated the semantics to REST and handles the response. Users who need to |
311 |
have access to these commands can use the verbose mode that presents the HTTP |
312 |
Request details as well as the full server response. |
313 |
|
314 |
To run kamaki in verbose mode use the *-v/- - verbose* option |
315 |
|
316 |
Verbose mode outputs the request and response mode, address and |
317 |
headers as well as the size of the data block, if any. Sensitive information |
318 |
(x-auth-token header and data body) are omitted by default,. Users who need |
319 |
this information may enable it through the log_token and log_data configuration |
320 |
options (see next section) |
321 |
|
322 |
.. tip:: Use the -o runtime option to enable config options on the fly, e.g, to |
323 |
include http data: |
324 |
|
325 |
.. code-block:: console |
326 |
|
327 |
$ kamaki server list -v -o log_data=on |
328 |
|
329 |
|
330 |
Logging |
331 |
""""""" |
332 |
|
333 |
Kamaki keeps its logs in a file specified by the *log_file* option and it |
334 |
defaults to *${HOME}/.kamaki.log*. This configuration option can be modified:: |
335 |
|
336 |
kamaki config set log_file /new/log/file/path |
337 |
|
338 |
Kamaki logs http request and response information, namely the method, URL, |
339 |
headers and data size. Sensitive information (data and token header) are |
340 |
omitted by default. There are some configuration options that can switch them |
341 |
on, though: |
342 |
|
343 |
* HTTP data blocks are not logged by default |
344 |
to enable logging the full http bodies, set log_data to `on`:: |
345 |
|
346 |
kamaki config set log_data on |
347 |
|
348 |
to disable it, set it to `off`:: |
349 |
|
350 |
kamaki config set log_data off |
351 |
|
352 |
or delete it:: |
353 |
|
354 |
kamaki config delete log_data |
355 |
|
356 |
* X-Auth-Token header is not logged by default |
357 |
to enable logging the X-Auth-Token header, set log_token to `on`:: |
358 |
|
359 |
kamaki config set log_token on |
360 |
|
361 |
to disable it, set it to `off`:: |
362 |
|
363 |
kamaki config set log_token off |
364 |
|
365 |
or delete it:: |
366 |
|
367 |
kamaki config delete log_token |
368 |
|
369 |
* The information (pid, name, date) of the processes that handle http requests |
370 |
is not logged by default, because if they are, logs are difficult to read. |
371 |
Still, they are useful for resolving race condition problems, so to enable |
372 |
logging proccess information:: |
373 |
|
374 |
kamaki config set log_pid on |
375 |
|
376 |
to disable it, set if to off:: |
377 |
|
378 |
kamaki config set log_pid off |
379 |
|
380 |
or delete it:: |
381 |
|
382 |
kamaki config delete log_pid |
383 |
|
384 |
One-command features |
385 |
^^^^^^^^^^^^^^^^^^^^ |
386 |
|
387 |
Kamaki commands can be used along with advanced shell features. |
388 |
|
389 |
.. code-block:: console |
390 |
:emphasize-lines: 1 |
391 |
|
392 |
Example 3.4.1: List the trash container contents, containing c1_ |
393 |
|
394 |
|
395 |
$ kamaki file list -o cloud.default.pithos_container=trash| grep c1_ |
396 |
c1_1370859409.0 20KB |
397 |
c1_1370859414.0 9MB |
398 |
c1_1370859409.1 110B |
399 |
|
400 |
The -o argument can be used to temporarily override various (set or unset) |
401 |
options. In one command, all -o option sets are forgotten just after the |
402 |
command has been completed, and the previous settings are restored (the |
403 |
configuration file is not modified). |
404 |
|
405 |
The file-list command in example 3.4.1 runs with an explicitly provided |
406 |
pithos_account, which temporarily overrides the one probably provided in the |
407 |
configuration file (it works even if the user has not set the optional |
408 |
pithos_account config option). |
409 |
|
410 |
.. tip:: There are better ways to list the contents of a container. Example |
411 |
3.4.1 is using this method for demonstration purposes only. The suggested |
412 |
method for listing container contents is *- - container=<container>* |
413 |
|
414 |
Interactive shell |
415 |
----------------- |
416 |
|
417 |
Command Contexts |
418 |
^^^^^^^^^^^^^^^^ |
419 |
|
420 |
The kamaki interactive shell implements the notion of command contexts. Each |
421 |
command group is also a context where the users can **enter** by typing the |
422 |
group name. If the context switch is successful, the kamaki shell prompt |
423 |
changes to present the new context ("*file*" in example 4.1.1). |
424 |
|
425 |
.. code-block:: console |
426 |
:emphasize-lines: 1 |
427 |
|
428 |
Example 4.1.1: Start kamaki and switch to file context |
429 |
|
430 |
|
431 |
$ kamaki |
432 |
[kamaki]: file |
433 |
[file]: |
434 |
|
435 |
Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in |
436 |
Windows) to exit a context and return to the context of origin. If already at |
437 |
the top context (kamaki), an exit is equivalent to exiting the program. |
438 |
|
439 |
.. code-block:: console |
440 |
:emphasize-lines: 1 |
441 |
|
442 |
Example 4.1.2: Exit file context and then exit kamaki |
443 |
|
444 |
[file]: exit |
445 |
[kamaki]: exit |
446 |
$ |
447 |
|
448 |
A user might **browse** through different contexts during one session. |
449 |
|
450 |
.. code-block:: console |
451 |
:emphasize-lines: 1 |
452 |
|
453 |
Example 4.1.3: Execute list command in different contexts |
454 |
|
455 |
$ kamaki |
456 |
[kamaki]: config |
457 |
[config]: list |
458 |
... (configuration options listing) ... |
459 |
[config]: exit |
460 |
[kamaki]: file |
461 |
[file]: list |
462 |
... (storage containers listing) ... |
463 |
[file]: exit |
464 |
[kamaki]: server |
465 |
[server]: list |
466 |
... (servers listing) ... |
467 |
[server]: exit |
468 |
[kamaki]: |
469 |
|
470 |
Users have the option to avoid switching between contexts: all commands can run |
471 |
from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent. |
472 |
|
473 |
.. code-block:: console |
474 |
:emphasize-lines: 1 |
475 |
|
476 |
Example 4.1.4: Execute different "list" commands from top context |
477 |
|
478 |
|
479 |
[kamaki]: config list |
480 |
... (configuration options listing) ... |
481 |
[kamaki]: file list |
482 |
... (storage container listing) ... |
483 |
[kamaki]: server list |
484 |
... (servers listing) ... |
485 |
[kamaki]: |
486 |
|
487 |
Using Help |
488 |
^^^^^^^^^^ |
489 |
|
490 |
There are two help mechanisms: a context-level and a command-level. |
491 |
|
492 |
**Context-level help** lists the available commands in a context and can also |
493 |
offer a short description for each command. |
494 |
|
495 |
Context-level help syntax:: |
496 |
|
497 |
* Show available commands in current context * |
498 |
[context]: help |
499 |
... |
500 |
[context]: ? |
501 |
... |
502 |
|
503 |
* Show help for command cmd * |
504 |
[context]: help cmd |
505 |
... |
506 |
[context]: ?cmd |
507 |
... |
508 |
|
509 |
The context-level help results may change from context to context |
510 |
|
511 |
.. code-block:: console |
512 |
:emphasize-lines: 1 |
513 |
|
514 |
Example 4.2.1: Get available commands and then get help in a context |
515 |
|
516 |
|
517 |
[kamaki]: help |
518 |
|
519 |
kamaki commands: |
520 |
================ |
521 |
user config flavor history image network server file ... |
522 |
|
523 |
interactive shell commands: |
524 |
=========================== |
525 |
exit help shell |
526 |
|
527 |
[kamaki]: ?config |
528 |
Configuration commands (config -h for more options) |
529 |
|
530 |
[kamaki]: config |
531 |
|
532 |
[config]: ? |
533 |
|
534 |
config commands: |
535 |
================ |
536 |
delete get list set |
537 |
|
538 |
interactive shell commands: |
539 |
=========================== |
540 |
exit help shell |
541 |
|
542 |
[config]: help set |
543 |
Set a configuration option (set -h for more options) |
544 |
|
545 |
In context-level, there is a distinction between kamaki-commands and |
546 |
interactive shell commands. The former are available in one-command mode and |
547 |
are related to the cloud client setup and use, while the later are |
548 |
context-shell functions. |
549 |
|
550 |
**Command-level help** prints the syntax, arguments and description of a |
551 |
specific (terminal) command |
552 |
|
553 |
Command-level help syntax:: |
554 |
|
555 |
* Get help for command cmd1 cmd2 ... cmdN * |
556 |
[context]: cmd1 cmd2 ... cmdN -h |
557 |
<syntax> |
558 |
|
559 |
<description> |
560 |
|
561 |
<arguments and possible extensions> |
562 |
|
563 |
Command-level help mechanism is exactly the same as the one used in |
564 |
one-command mode. For example, it is invoked by using the -h or --help |
565 |
parameter at any point. |
566 |
|
567 |
.. code-block:: console |
568 |
:emphasize-lines: 1 |
569 |
|
570 |
Example 4.2.2: Get command-level help for config and config-set |
571 |
|
572 |
|
573 |
[kamaki]: config --help |
574 |
config: Configuration commands |
575 |
delete: Delete a configuration option (and use the default value) |
576 |
get : Show a configuration option |
577 |
list : List configuration options |
578 |
set : Set a configuration option |
579 |
|
580 |
[kamaki]: config |
581 |
|
582 |
[config]: set -h |
583 |
usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s] |
584 |
|
585 |
Set a configuration option |
586 |
|
587 |
optional arguments: |
588 |
-v, --verbose More info at response |
589 |
-d, --debug Include debug output |
590 |
-h, --help Show help message |
591 |
-i, --include Include protocol headers in the output |
592 |
--config CONFIG Path to configuration file |
593 |
-s, --silent Do not output anything |
594 |
|
595 |
There are many ways of producing a help message, as shown in example 4.2.3 |
596 |
|
597 |
.. code-block:: console |
598 |
:emphasize-lines: 1 |
599 |
|
600 |
Example 4.2.3: Equivalent calls of command-level help for config-set |
601 |
|
602 |
|
603 |
[config]: set -h |
604 |
[config]: set --help |
605 |
[kamaki]: config set -h |
606 |
[kamaki]: config set --help |
607 |
[file]: /config set -h |
608 |
[server]: /config set --help |
609 |
|
610 |
.. _accessing-top-level-commands-ref: |
611 |
|
612 |
Accessing top-level commands |
613 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
614 |
|
615 |
When working in a context, it is often useful to access other contexts or |
616 |
top-level commands. Kamaki offers access to top-level commands by using the |
617 |
`/` prefix, as shown bellow:: |
618 |
|
619 |
* access a command "anothercontext cmd1 cmd2 ... cmdN" |
620 |
[context]: /anothercontext cmd1 cmd2 ... cmdN |
621 |
|
622 |
An example (4.3.1) that showcases how top-level access improves user experience |
623 |
is the creation of a server. A server is created with the command server-create. This |
624 |
command is called with three parameters: |
625 |
|
626 |
* the name of the new server |
627 |
* the flavor id |
628 |
* the image id |
629 |
|
630 |
An average user would enter the server context and type *create -h* to check the |
631 |
syntax of the command. In that point, it would be nice to have some easy way of |
632 |
accessing the *flavor* and *image* contexts, to list and pick a flavor id and an |
633 |
image id. This is achieved with the / notation, as demonstrated in the following |
634 |
example: |
635 |
|
636 |
.. code-block:: console |
637 |
:emphasize-lines: 1 |
638 |
|
639 |
Example 4.3.1: Create a server from server context |
640 |
|
641 |
[server]: create -h |
642 |
create <name> <flavor id> <image id> ... |
643 |
... |
644 |
|
645 |
[server]: /flavor list |
646 |
... |
647 |
43 AFLAVOR |
648 |
SNF:disk_template: drbd |
649 |
cpu : 4 |
650 |
disk : 10 |
651 |
ram : 2048 |
652 |
|
653 |
[server]: /image compute list |
654 |
1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop) |
655 |
18a82962-43eb-8f8880af89d7 (Windows 7) |
656 |
531aa018-9a40-a4bfe6a0caff (Windows XP) |
657 |
6aa6eafd-dccb-67fe2bdde87e (Debian Desktop) |
658 |
|
659 |
[server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e |
660 |
... |
661 |
|
662 |
An other example (4.3.2) showcases how to acquire and modify configuration |
663 |
settings from a different context. In this scenario, the user token expires at |
664 |
server side while the user is working. When that happens, the system responds |
665 |
with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid |
666 |
for the Astakos identity manager of preference) which has to be set to kamaki. |
667 |
|
668 |
.. code-block:: console |
669 |
:emphasize-lines: 1 |
670 |
|
671 |
Example 4.3.2: Token suddenly expires. Set a new token from file context |
672 |
|
673 |
|
674 |
[file]: list |
675 |
(401) UNAUTHORIZED Access denied |
676 |
|
677 |
[file]: /user authenticate |
678 |
(401) UNAUTHORIZED Invalid X-Auth-Token |
679 |
|
680 |
[file]: /config get cloud.default.token |
681 |
my3xp1r3dt0k3n== |
682 |
|
683 |
[file]: /config set cloud.default.token myfr35ht0k3n== |
684 |
|
685 |
[file]: /config get cloud.default |
686 |
cloud.default.url = https://astakos.example.com/astakos/identity/2.0/ |
687 |
cloud.default.token = myfr35ht0k3n== |
688 |
|
689 |
[file]: list |
690 |
1. pithos (10MB, 2 objects) |
691 |
2. trash (0B, 0 objects) |
692 |
|
693 |
.. note:: The error messages on examples are shortened for clarity. Actual error |
694 |
messages are more helpful and descriptive. |
695 |
|
696 |
The following example compares some equivalent calls that run |
697 |
*user-authenticate* after a *file-list* 401 failure. |
698 |
|
699 |
.. code-block:: console |
700 |
:emphasize-lines: 1,3,10,17,26 |
701 |
|
702 |
Example 4.3.3: Equivalent user-authenticate calls after a file-list 401 |
703 |
|
704 |
* I. without kamaki interactive shell * |
705 |
$ kamaki file list |
706 |
(401) UNAUTHORIZED Access denied |
707 |
$ kamaki user authenticate |
708 |
... |
709 |
$ |
710 |
|
711 |
* II. from top-level context * |
712 |
[kamaki]: file list |
713 |
(401) UNAUTHORIZED Access denied |
714 |
[kamaki]: user authenticate |
715 |
... |
716 |
[kamaki] |
717 |
|
718 |
* III. maximum typing * |
719 |
[file]: list |
720 |
(401) UNAUTHORIZED Access denied |
721 |
[file]: exit |
722 |
[kamaki]: user |
723 |
[user]: authenticate |
724 |
... |
725 |
[user]: |
726 |
|
727 |
* IV. minimum typing * |
728 |
[file]: list |
729 |
(401) UNAUTHORIZED Access denied |
730 |
[file]: /user authenticate |
731 |
... |
732 |
[file]: |
733 |
|
734 |
.. hint:: To exit kamaki shell while in a context, try */exit* |
735 |
|
736 |
Using config |
737 |
^^^^^^^^^^^^ |
738 |
|
739 |
The configuration mechanism of kamaki is detailed in the |
740 |
`setup section <setup.html>`_, it is accessible as *config* and it is common for |
741 |
both interaction modes. In specific, the configuration mechanism is implemented |
742 |
as `config`. Using the config commands is as straightforward as in any other |
743 |
group of commands. |
744 |
|
745 |
It is often useful to set, delete or update a value. This can be managed either |
746 |
inside the config context or from any command context by using the / prefix. |
747 |
|
748 |
.. Note:: config updates in kamaki shell persist even after the session is over |
749 |
|
750 |
All setting changes affect the physical kamaki config file. The config file is |
751 |
created automatically at callers' home firectory the first time a config option |
752 |
is set, and lives there as *.kamakirc* . It can be edited with any text editor |
753 |
or managed with kamaki config commands. |
754 |
|
755 |
In example 4.4.1 the user is going to work with only one storage container. The |
756 |
file commands use the container:path syntax, but if the user sets a container |
757 |
name as default, the container name can be omitted. |
758 |
|
759 |
.. code-block:: console |
760 |
:emphasize-lines: 1 |
761 |
|
762 |
Example 4.4.1: Set default storage container (cloud alias: default) |
763 |
|
764 |
|
765 |
[file]: list |
766 |
mycontainer (32MB, 2 objects) |
767 |
pithos (0B, 0 objects) |
768 |
trash (2MB, 1 objects) |
769 |
|
770 |
[file]: list mycontainer |
771 |
D mydir/ |
772 |
20M mydir/rndm_local.file |
773 |
|
774 |
[file]: /config set cloud.default.pithos_container mycontainer |
775 |
|
776 |
[file]: list |
777 |
D mydir/ |
778 |
20M mydir/rndm_local.file |
779 |
|
780 |
After a while, the user needs to work with multiple containers, therefore a |
781 |
default container is no longer needed. The *pithos_container* setting can be |
782 |
deleted, as shown in example 4.4.2 |
783 |
|
784 |
.. code-block:: console |
785 |
:emphasize-lines: 1 |
786 |
|
787 |
Example 4.4.2: Delete a setting option (cloud: default) |
788 |
|
789 |
|
790 |
[file]: /config delete cloud.default.pithos_container |
791 |
|
792 |
[file]: list |
793 |
mycontainer (32MB, 2 objects) |
794 |
pithos (0B, 0 objects) |
795 |
trash (2MB, 1 objects) |
796 |
|
797 |
History modes |
798 |
^^^^^^^^^^^^^ |
799 |
|
800 |
There are two history modes: session and permanent. Session history keeps |
801 |
record of all actions in a kamaki shell session, while permanent history |
802 |
appends all commands to an accessible history file. |
803 |
|
804 |
Session history is only available in interactive shell mode. Users can iterate |
805 |
through past commands in the same session with the ↑ and ↓ keys. Session |
806 |
history is not stored, although commands are recorded through the permanent |
807 |
history mechanism. |
808 |
|
809 |
Permanent history is implemented as a command group and is common to both the |
810 |
one-command and shell interfaces. In specific, every command is appended in a |
811 |
history file (configured as `history_file` in settings, see |
812 |
`setup section <setup.html>`_ for details). Commands executed in one-command |
813 |
mode are mixed with the ones run in kamaki shell (also see |
814 |
:ref:`using-history-ref` section on this guide). |
815 |
|
816 |
Scripting |
817 |
^^^^^^^^^ |
818 |
|
819 |
The history-run feature allows the sequential run of previous command |
820 |
executions in kamaki shell. |
821 |
|
822 |
The following sequence copies and downloads a file from *mycontainer1* , |
823 |
uploads it to *mycontainer2* , then undo the proccess and repeats it with |
824 |
history-run |
825 |
|
826 |
.. code-block:: console |
827 |
:emphasize-lines: 1,12,19,32 |
828 |
|
829 |
* Download mycontainer1:myfile and upload it to mycontainer2:myfile * |
830 |
[kamaki]: file |
831 |
[file]: copy mycontainer1:somefile mycontainer1:myfile |
832 |
[file]: download mycontainer1:myfile mylocalfile |
833 |
... |
834 |
Download completed |
835 |
[file]: upload mylocalfile mycontainer2:myfile -f |
836 |
... |
837 |
Upload completed |
838 |
|
839 |
* undo the process * |
840 |
[file]: !rm mylocalfile |
841 |
[file]: delete mycontainer1:myfile |
842 |
[file]: delete mycontainer2:myfile |
843 |
|
844 |
* check history entries * |
845 |
[file]: exit |
846 |
[kamaki]: history |
847 |
[history]: show |
848 |
1. file |
849 |
2. file copy mycontainer1:somefile mycontainer1:myfile |
850 |
3. file download mycontainer1:myfile mylocalfile |
851 |
4. file upload mylocalfile mycontainer2:myfile -f |
852 |
5. file delete mycontainer1:myfile |
853 |
6. file delete mycontainer2:myfile |
854 |
7. history |
855 |
8. history show |
856 |
|
857 |
*repeat the process * |
858 |
[history]: run 2-4 |
859 |
<file copy mycontainer1:somefile mycontainer1:myfile> |
860 |
<file download mycontainer1:myfile mylocalfile> |
861 |
Download completed |
862 |
<file upload mylocalfile mycontainer2:myfile> |
863 |
Upload completed |
864 |
|
865 |
For powerfull scripting, users are advised to take advantage of their os shell |
866 |
scripting capabilities and combine them with kamaki one-command. Still, the |
867 |
history-run functionality might prove handy in many occasions. |
868 |
|
869 |
OS Shell integration |
870 |
^^^^^^^^^^^^^^^^^^^^ |
871 |
|
872 |
Kamaki shell features the ability to execute OS-shell commands from any |
873 |
context. This can be achieved by typing *!* or *shell*:: |
874 |
|
875 |
[kamaki_context]: !<OS shell command> |
876 |
... OS shell command output ... |
877 |
|
878 |
[kamaki_context]: shell <OS shell command> |
879 |
... OS shell command output ... |
880 |
|
881 |
.. code-block:: console |
882 |
:emphasize-lines: 1 |
883 |
|
884 |
Example 4.7.1: Run unix-style shell commands from kamaki shell |
885 |
|
886 |
|
887 |
[kamaki]: !ls -al |
888 |
total 16 |
889 |
drwxrwxr-x 2 username username 4096 Nov 27 16:47 . |
890 |
drwxrwxr-x 7 username username 4096 Nov 27 16:47 .. |
891 |
-rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png |
892 |
|
893 |
[kamaki]: shell cp kamaki-logo.png logo-copy.png |
894 |
|
895 |
[kamaki]: shell ls -al |
896 |
total 24 |
897 |
drwxrwxr-x 2 username username 4096 Nov 27 16:47 . |
898 |
drwxrwxr-x 7 username username 4096 Nov 27 16:47 .. |
899 |
-rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png |
900 |
-rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png |
901 |
|
902 |
|
903 |
Kamaki shell commits command strings to the outside shell and prints the |
904 |
results, without interacting with it. After a command is finished, kamaki shell |
905 |
returns to its initial state, which involves the current directory, as shown in |
906 |
example 4.8.2 |
907 |
|
908 |
.. code-block:: console |
909 |
:emphasize-lines: 1 |
910 |
|
911 |
Example 4.8.2: Attempt (and fail) to change working directory |
912 |
|
913 |
|
914 |
[kamaki]: !pwd |
915 |
/home/username |
916 |
|
917 |
[kamaki]: !cd .. |
918 |
|
919 |
[kamaki]: shell pwd |
920 |
/home/username |