Revision 0ea31480 docs/usage.rst
b/docs/usage.rst | ||
---|---|---|
114 | 114 |
|
115 | 115 |
Options: |
116 | 116 |
- - - - |
117 |
astakos: Astakos API commands
|
|
118 |
config : Configuration commands
|
|
119 |
flavor : Compute/Cyclades API flavor commands
|
|
120 |
history: Command history |
|
121 |
image : Plankton (and Compute) Image API commands
|
|
122 |
network: Compute/Cyclades API network commands |
|
123 |
server : Compute/Cyclades API server commands
|
|
124 |
store : Pithos+ storage commands
|
|
117 |
user: Astakos API commands
|
|
118 |
config: Configuration commands
|
|
119 |
flavor: Compute/Cyclades API flavor commands
|
|
120 |
history: Command history
|
|
121 |
image: Plankton (and Compute) Image API commands |
|
122 |
network: Compute/Cyclades API network commands
|
|
123 |
server: Compute/Cyclades API server commands
|
|
124 |
file: Pithos+ storage commands
|
|
125 | 125 |
|
126 | 126 |
.. code-block:: console |
127 | 127 |
:emphasize-lines: 1 |
... | ... | |
254 | 254 |
Example 3.4.1: Print username for token us3rt0k3n== using grep |
255 | 255 |
|
256 | 256 |
|
257 |
$ kamaki astakos authenticate -o token=us3rt0k3n== | grep userame
|
|
257 |
$ kamaki user authenticate -o token=us3rt0k3n== | grep userame
|
|
258 | 258 |
userame : user@synnefo.org |
259 | 259 |
|
260 | 260 |
The -o argument can be used to temporarily override various (set or unset) options. In one command, all -o option sets are forgotten just after the command has been completed, and the previous settings are restored (a.k.a. the configuration file is not modified). |
261 | 261 |
|
262 |
The astakos-authenticate command in example 3.4.1 runs with an explicitly provided token, which temporarily overrides the token provided in the configuration file.
|
|
262 |
The user-authenticate command in example 3.4.1 runs with an explicitly provided token, which temporarily overrides the token provided in the configuration file.
|
|
263 | 263 |
|
264 | 264 |
Interactive shell |
265 | 265 |
----------------- |
... | ... | |
267 | 267 |
Command Contexts |
268 | 268 |
^^^^^^^^^^^^^^^^ |
269 | 269 |
|
270 |
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).
|
|
270 |
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).
|
|
271 | 271 |
|
272 | 272 |
.. code-block:: console |
273 | 273 |
:emphasize-lines: 1 |
274 | 274 |
|
275 |
Example 4.1.1: Enter store commands context / group
|
|
275 |
Example 4.1.1: Enter file commands context / group
|
|
276 | 276 |
|
277 | 277 |
|
278 | 278 |
$ kamaki |
279 |
[kamaki]: store
|
|
280 |
[store]:
|
|
279 |
[kamaki]: file
|
|
280 |
[file]:
|
|
281 | 281 |
|
282 | 282 |
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. |
283 | 283 |
|
284 | 284 |
.. code-block:: console |
285 | 285 |
:emphasize-lines: 1 |
286 | 286 |
|
287 |
Example 4.1.2: Exit store context and then exit kamaki
|
|
287 |
Example 4.1.2: Exit file context and then exit kamaki
|
|
288 | 288 |
|
289 |
[store]: exit
|
|
289 |
[file]: exit
|
|
290 | 290 |
[kamaki]: exit |
291 | 291 |
$ |
292 | 292 |
|
... | ... | |
302 | 302 |
[config]: list |
303 | 303 |
... (configuration options listing) ... |
304 | 304 |
[config]: exit |
305 |
[kamaki]: store
|
|
306 |
[store]: list
|
|
305 |
[kamaki]: file
|
|
306 |
[file]: list
|
|
307 | 307 |
... (storage containers listing) ... |
308 |
[store]: exit
|
|
308 |
[file]: exit
|
|
309 | 309 |
[kamaki]: server |
310 | 310 |
[server]: list |
311 | 311 |
... (VMs listing) ... |
... | ... | |
322 | 322 |
|
323 | 323 |
[kamaki]: config list |
324 | 324 |
... (configuration options listing) ... |
325 |
[kamaki]: store list
|
|
325 |
[kamaki]: file list
|
|
326 | 326 |
... (storage container listing) ... |
327 | 327 |
[kamaki]: server list |
328 | 328 |
... (VMs listing) ... |
... | ... | |
357 | 357 |
|
358 | 358 |
kamaki commands: |
359 | 359 |
================ |
360 |
astakos config flavor history image network server store
|
|
360 |
user config flavor history image network server file
|
|
361 | 361 |
|
362 | 362 |
interactive shell commands: |
363 | 363 |
=========================== |
... | ... | |
437 | 437 |
[config]: set --help |
438 | 438 |
[kamaki]: config set -h |
439 | 439 |
[kamaki]: config set --help |
440 |
[store]: /config set -h
|
|
440 |
[file]: /config set -h
|
|
441 | 441 |
[server]: /config set --help |
442 | 442 |
|
443 | 443 |
.. _accessing-top-level-commands-ref: |
... | ... | |
484 | 484 |
[server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e |
485 | 485 |
... |
486 | 486 |
|
487 |
An other example (4.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 acquire a new token (valid for the astakos identity manager of preference) which has to be set to kamaki.
|
|
487 |
An other example (4.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 acquire a new token (valid for the Astakos identity manager of preference) which has to be set to kamaki.
|
|
488 | 488 |
|
489 | 489 |
.. code-block:: console |
490 | 490 |
:emphasize-lines: 1 |
491 | 491 |
|
492 |
Example 4.3.2: Set a new token from store context
|
|
492 |
Example 4.3.2: Set a new token from file context
|
|
493 | 493 |
|
494 | 494 |
|
495 |
[store]: list
|
|
495 |
[file]: list
|
|
496 | 496 |
(401) UNAUTHORIZED Access denied |
497 | 497 |
|
498 |
[store]: /astakos authenticate
|
|
498 |
[file]: /user authenticate
|
|
499 | 499 |
(401) UNAUTHORIZED Invalid X-Auth-Token |
500 | 500 |
|
501 |
[store]: /config get token
|
|
501 |
[file]: /config get token
|
|
502 | 502 |
my3xp1r3dt0k3n== |
503 | 503 |
|
504 |
[store]: /config set token myfr35ht0k3n==
|
|
504 |
[file]: /config set token myfr35ht0k3n==
|
|
505 | 505 |
|
506 |
[store]: /config get token
|
|
506 |
[file]: /config get token
|
|
507 | 507 |
myfr35ht0k3n== |
508 | 508 |
|
509 |
[store]: list
|
|
509 |
[file]: list
|
|
510 | 510 |
1. pithos (10MB, 2 objects) |
511 | 511 |
2. trash (0B, 0 objects) |
512 | 512 |
|
513 | 513 |
.. note:: The error messages on this example where shortened for clarity. Actual kamaki error messages are more helpful and descriptive. |
514 | 514 |
|
515 |
The following example compares some equivalent calls that run *astakos-authenticate* after a *store-list* 401 failure.
|
|
515 |
The following example compares some equivalent calls that run *user-authenticate* after a *file-list* 401 failure.
|
|
516 | 516 |
|
517 | 517 |
.. code-block:: console |
518 | 518 |
:emphasize-lines: 1,3,10,17,26 |
519 | 519 |
|
520 |
Example 4.3.3: Equivalent astakos-authenticate calls after a store-list 401 failure
|
|
520 |
Example 4.3.3: Equivalent user-authenticate calls after a file-list 401 failure
|
|
521 | 521 |
|
522 | 522 |
* without kamaki interactive shell * |
523 |
$ kamaki store list
|
|
523 |
$ kamaki file list
|
|
524 | 524 |
(401) UNAUTHORIZED Access denied |
525 |
$ kamaki astakos authenticate
|
|
525 |
$ kamaki user authenticate
|
|
526 | 526 |
... |
527 | 527 |
$ |
528 | 528 |
|
529 | 529 |
* from top-level context * |
530 |
[kamaki]: store list
|
|
530 |
[kamaki]: file list
|
|
531 | 531 |
(401) UNAUTHORIZED Access denied |
532 |
[kamaki]: astakos authenticate
|
|
532 |
[kamaki]: user authenticate
|
|
533 | 533 |
... |
534 | 534 |
[kamaki] |
535 | 535 |
|
536 | 536 |
* maximum typing * |
537 |
[store]: list
|
|
537 |
[file]: list
|
|
538 | 538 |
(401) UNAUTHORIZED Access denied |
539 |
[store]: exit
|
|
540 |
[kamaki]: astakos
|
|
541 |
[astakos]: authenticate
|
|
539 |
[file]: exit
|
|
540 |
[kamaki]: user
|
|
541 |
[user]: authenticate
|
|
542 | 542 |
... |
543 |
[astakos]:
|
|
543 |
[user]:
|
|
544 | 544 |
|
545 | 545 |
* minimum typing * |
546 |
[store]: list
|
|
546 |
[file]: list
|
|
547 | 547 |
(401) UNAUTHORIZED Access denied |
548 |
[store]: /astakos authenticate
|
|
548 |
[file]: /user authenticate
|
|
549 | 549 |
... |
550 |
[store]:
|
|
550 |
[file]:
|
|
551 | 551 |
|
552 | 552 |
.. hint:: To exit kamaki shell while in a context, try */exit* |
553 | 553 |
|
... | ... | |
562 | 562 |
|
563 | 563 |
All setting changes affect the physical kamaki config file. The config file is created automatically at callers' home firectory the first time a config option is set, and lives there as *.kamakirc* . It can be edited with any text editor or managed with kamaki config commands. |
564 | 564 |
|
565 |
In example 4.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 sets a container name as default, the container name can be omitted. This is possible by setting a *store.container* setting.
|
|
565 |
In example 4.4.1 the user is going to work with only one storage container. The file commands use the container:path syntax, but if the user sets a container name as default, the container name can be omitted. This is possible by setting a *file.container* setting.
|
|
566 | 566 |
|
567 | 567 |
.. code-block:: console |
568 | 568 |
:emphasize-lines: 1 |
... | ... | |
570 | 570 |
Example 4.4.1: Set default storage container |
571 | 571 |
|
572 | 572 |
|
573 |
[store]: list
|
|
573 |
[file]: list
|
|
574 | 574 |
1. mycontainer (32MB, 2 objects) |
575 | 575 |
2. pithos (0B, 0 objects) |
576 | 576 |
3. trash (2MB, 1 objects) |
577 | 577 |
|
578 |
[store]: list mycontainer
|
|
578 |
[file]: list mycontainer
|
|
579 | 579 |
1. D mydir/ |
580 | 580 |
2. 20M mydir/rndm_local.file |
581 | 581 |
|
582 |
[store]: /config set store.container mycontainer
|
|
582 |
[file]: /config set file.container mycontainer
|
|
583 | 583 |
|
584 |
[store]: list
|
|
584 |
[file]: list
|
|
585 | 585 |
1. D mydir/ |
586 | 586 |
2. 20M mydir/rndm_local.file |
587 | 587 |
|
588 |
After a while, the user needs to work with multiple containers, therefore a default container is no longer needed. The *store.container* setting can be deleted, as shown in example 4.4.2 .
|
|
588 |
After a while, the user needs to work with multiple containers, therefore a default container is no longer needed. The *file.container* setting can be deleted, as shown in example 4.4.2 .
|
|
589 | 589 |
|
590 | 590 |
.. code-block:: console |
591 | 591 |
:emphasize-lines: 1 |
... | ... | |
593 | 593 |
Example 4.4.2: Delete a setting option |
594 | 594 |
|
595 | 595 |
|
596 |
[store]: /config delete store.container
|
|
596 |
[file]: /config delete file.container
|
|
597 | 597 |
|
598 |
[store]: list
|
|
598 |
[file]: list
|
|
599 | 599 |
1. mycontainer (32MB, 2 objects) |
600 | 600 |
2. pithos (0B, 0 objects) |
601 | 601 |
3. trash (2MB, 1 objects) |
... | ... | |
620 | 620 |
:emphasize-lines: 1,12,19,32 |
621 | 621 |
|
622 | 622 |
* Download mycontainer1:myfile and upload it to mycontainer2:myfile |
623 |
[kamaki]: store
|
|
624 |
[store]: copy mycontainer1:somefile mycontainer1:myfile
|
|
625 |
[store]: download mycontainer1:myfile mylocalfile
|
|
623 |
[kamaki]: file
|
|
624 |
[file]: copy mycontainer1:somefile mycontainer1:myfile
|
|
625 |
[file]: download mycontainer1:myfile mylocalfile
|
|
626 | 626 |
Download completed |
627 |
[store]: upload mylocalfile mycontainer2:myfile
|
|
627 |
[file]: upload mylocalfile mycontainer2:myfile
|
|
628 | 628 |
Upload completed |
629 | 629 |
|
630 | 630 |
* undo the process * |
631 |
[store]: !rm mylocalfile
|
|
632 |
[store]: delete mycontainer1:myfile
|
|
633 |
[store]: delete mycontainer2:myfile
|
|
631 |
[file]: !rm mylocalfile
|
|
632 |
[file]: delete mycontainer1:myfile
|
|
633 |
[file]: delete mycontainer2:myfile
|
|
634 | 634 |
|
635 | 635 |
* check history entries * |
636 |
[store]: exit
|
|
636 |
[file]: exit
|
|
637 | 637 |
[kamaki]: history |
638 | 638 |
[history]: show |
639 |
1. store
|
|
640 |
2. store copy mycontainer1:somefile mycontainer1:myfile
|
|
641 |
3. store download mycontainer1:myfile mylocalfile
|
|
642 |
4. store upload mylocalfile mycontainer2:myfile
|
|
643 |
5. store delete mycontainer1:myfile
|
|
644 |
6. store delete mycontainer2:myfile
|
|
639 |
1. file
|
|
640 |
2. file copy mycontainer1:somefile mycontainer1:myfile
|
|
641 |
3. file download mycontainer1:myfile mylocalfile
|
|
642 |
4. file upload mylocalfile mycontainer2:myfile
|
|
643 |
5. file delete mycontainer1:myfile
|
|
644 |
6. file delete mycontainer2:myfile
|
|
645 | 645 |
7. history |
646 | 646 |
8. history show |
647 | 647 |
|
648 | 648 |
*repeat the process * |
649 | 649 |
[history]: run 2-4 |
650 |
<store copy mycontainer1:somefile mycontainer1:myfile>
|
|
651 |
<store download mycontainer1:myfile mylocalfile>
|
|
650 |
<file copy mycontainer1:somefile mycontainer1:myfile>
|
|
651 |
<file download mycontainer1:myfile mylocalfile>
|
|
652 | 652 |
Download completed |
653 |
<store upload mylocalfile mycontainer2:myfile>
|
|
653 |
<file upload mylocalfile mycontainer2:myfile>
|
|
654 | 654 |
Upload completed |
655 | 655 |
|
656 | 656 |
For powerfull scripting, users are advised to take advantage of their os shell scripting capabilities and combine them with kamaki one-command. Still, the history-run functionality might prove handy in many occasions. |
Also available in: Unified diff