Statistics
| Branch: | Tag: | Revision:

root / docs / usage.rst @ d88ba587

History | View | Annotate | Download (21.7 kB)

1
Usage
2
=====
3

    
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.
5

    
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 <developers/code.html#the-clients-api>`_ section. The recommended method of utilizing this API is explained in the present.
7

    
8
Quick Setup
9
-----------
10

    
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.
12

    
13
It is essential for users to get a configuration token (okeanos.grnet.gr users go `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
14

    
15
.. code-block:: console
16
    :emphasize-lines: 1
17

    
18
    Example 1.1: Set user token to myt0k3n==
19

    
20
    $ kamaki set token myt0k3n==
21

    
22
To use the storage service, a user should also provide the corresponding user-name:
23

    
24
.. code-block:: console
25
    :emphasize-lines: 1
26

    
27
    Example 1.2: Set user name to user@domain.com
28

    
29
    $ kamaki set account user@domain.com
30

    
31
Shell vs one-command
32
--------------------
33
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.
34

    
35
In favor of interactive shell behavior:
36

    
37
* tab completion for commands
38
* session history with "up" / "down" keys
39
* shorter commands with command context switching
40

    
41
In favor of one-command behavior:
42

    
43
* can be used along with advanced shell features (pipelines, redirection, etc.)
44
* can be used in shell scripts
45
* prints debug and verbose messages if needed
46

    
47
Run as shell
48
^^^^^^^^^^^^
49
To use kamaki as a shell, run:
50

    
51
* without any parameters or arguments
52

    
53
.. code-block:: console
54
    :emphasize-lines: 1
55

    
56
    Example 2.2.1: Run kamaki shell
57

    
58
    $ kamaki
59

    
60
* with any kind of '-' prefixed arguments, except '-h', '--help'.
61

    
62
.. code-block:: console
63
    :emphasize-lines: 1
64

    
65
    Example 2.2.2: Run kamaki shell with custom configuration file
66

    
67
    $ kamaki --config myconfig.file
68

    
69

    
70
Run as one-command
71
^^^^^^^^^^^^^^^^^^
72
To use kamaki as an one-command tool, run:
73

    
74
* with the '-h' or '--help' arguments (help for kamaki one-command)
75

    
76
.. code-block:: console
77
    :emphasize-lines: 1
78

    
79
    Example 2.3.1: Kamaki help
80

    
81
    $kamaki -h
82

    
83
* with one or more command parameters:
84

    
85
.. code-block:: console
86
    :emphasize-lines: 1
87

    
88
    Example 2.3.2: List VMs managed by user
89

    
90
    $ kamaki server list
91

    
92
One-command interface
93
---------------------
94

    
95
Kamaki usage as a one-command tool is detailed in this section
96

    
97
Using help
98
^^^^^^^^^^
99

    
100
Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments.
101

    
102
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.
103

    
104
.. code-block:: console
105
    :emphasize-lines: 1
106

    
107
    Example 3.1.1: kamaki help shows available parameters and command groups
108

    
109

    
110
    $ kamaki -h
111
    usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
112
        [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h]
113

    
114
    optional arguments:
115
      -v, --verbose         More info at response
116
      -s, --silent          Do not output anything
117
      -V, --version         Print current version
118
      -d, --debug           Include debug output
119
      -i, --include         Include protocol headers in the output
120
      --config CONFIG       Path to configuration file
121
      -o OPTIONS, --options OPTIONS
122
                            Override a config value
123
      -h, --help            Show help message
124

    
125
    Options:
126
     - - - -
127
    astakos:  Astakos API commands
128
    config :  Configuration commands
129
    flavor :  Compute/Cyclades API flavor commands
130
    history:  Command history
131
    image  :  Compute/Cyclades or Plankton API image commands
132
    network:  Compute/Cyclades API network commands
133
    server :  Compute/Cyclades API server commands
134
    store  :  Pithos+ storage commands
135

    
136
.. code-block:: console
137
    :emphasize-lines: 1
138

    
139
    Example 3.1.2: Cyclades help contains all first-level commands of Cyclades command group
140

    
141

    
142
    $ kamaki cyclades -h
143
    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
144
                               [-o OPTIONS] [-h]
145

    
146
    optional arguments:
147
      -v, --verbose         More info at response
148
      -s, --silent          Do not output anything
149
      -V, --version         Print current version
150
      -d, --debug           Include debug output
151
      -i, --include         Include protocol headers in the output
152
      --config CONFIG       Path to configuration file
153
      -o OPTIONS, --options OPTIONS
154
                            Override a config value
155
      -h, --help            Show help message
156

    
157
    Options:
158
     - - - -
159
    addmeta :  Add server metadata
160
    addr    :  List a server's nic address
161
    console :  Get a VNC console
162
    create  :  Create a server
163
    delete  :  Delete a server
164
    delmeta :  Delete server metadata
165
    firewall:  Set the server's firewall profile
166
    info    :  Get server details
167
    list    :  List servers
168
    meta    :  Get a server's metadata
169
    reboot  :  Reboot a server
170
    rename  :  Update a server's name
171
    setmeta :  Update server's metadata
172
    shutdown:  Shutdown a server
173
    start   :  Start a server
174
    stats   :  Get server statistics
175
    wait    :  Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
176

    
177
.. code-block:: console
178
    :emphasize-lines: 1
179

    
180
    Example 3.1.3: Help for command "server list" with syntax, description and available user options
181

    
182

    
183
    $ kamaki server list -h
184
    usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l]
185

    
186
    List servers
187

    
188
    optional arguments:
189
      -v, --verbose         More info at response
190
      -s, --silent          Do not output anything
191
      -V, --version         Print current version
192
      -d, --debug           Include debug output
193
      -i, --include         Include protocol headers in the output
194
      --config CONFIG       Path to configuration file
195
      -o OPTIONS, --options OPTIONS
196
                            Override a config value
197
      -h, --help            Show help message
198
      -l                    show detailed output
199

    
200
.. _using-history-ref:
201

    
202
Using history
203
^^^^^^^^^^^^^
204

    
205
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>`_).
206

    
207
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:
208

    
209
.. code-block:: console
210
    :emphasize-lines: 1
211

    
212
    Example 3.2.1: Available history options
213

    
214

    
215
    $ kamaki history -h
216
    ...
217
    clean:  Clean up history
218
    show :  Show history
219

    
220
The following example showcases how to use history in kamaki
221

    
222
.. code-block:: console
223
    :emphasize-lines: 1
224

    
225
    Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
226
    
227

    
228
    $ kamaki history clean
229
    $ kamaki server list
230
    ...
231
    $ kamaki history show
232
    1.  kamaki server list
233
    2.  kamaki history show
234
    $ kamaki history show --match server
235
    1. kamaki server list
236
    3. kamaki history show --match server
237

    
238
Debug
239
^^^^^
240

    
241
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.
242

    
243
To run kamaki in debug mode use the -d or --debug option
244

    
245
Verbose
246
"""""""
247

    
248
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.
249

    
250
To run kamaki in verbose mode use the -v or --verbose option
251

    
252
One-command features
253
^^^^^^^^^^^^^^^^^^^^
254

    
255
Kamaki commands can be used along with advanced shell features.
256

    
257
.. code-block:: console
258
    :emphasize-lines: 1
259

    
260
    Example 3.4.1: Print username for token us3rt0k3n== using grep
261
    
262

    
263
    $ kamaki astakos authenticate -o token=us3rt0k3n== | grep uniq
264
    uniq        : user@synnefo.org
265

    
266
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).
267

    
268
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.
269

    
270
Interactive shell
271
-----------------
272

    
273
Kamaki interactive shell is details in this section
274

    
275
Command Contexts
276
^^^^^^^^^^^^^^^^
277

    
278
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).
279

    
280
.. code-block:: console
281
    :emphasize-lines: 1
282

    
283
    Example 4.1.1: Enter store commands context / group
284

    
285

    
286
    $ kamaki
287
    [kamaki]:store
288
    [store]:
289

    
290
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.
291

    
292
.. code-block:: console
293
    :emphasize-lines: 1
294

    
295
    Example 4.1.2: Exit store context and then exit kamaki
296

    
297
    [store]: exit
298
    [kamaki]: exit
299
    $
300

    
301
A user might **browse** through different contexts during one session.
302

    
303
.. code-block:: console
304
    :emphasize-lines: 1
305

    
306
    Example 4.1.3: Execute list command in different contexts
307

    
308
    $ kamaki
309
    [kamaki]:config
310
    [config]:list
311
    ... (configuration options listing) ...
312
    [config]:exit
313
    [kamaki]:store
314
    [store]:list
315
    ... (storage containers listing) ...
316
    [store]:exit
317
    [kamaki]:server
318
    [server]:list
319
    ... (VMs listing) ...
320
    [server]: exit
321
    [kamaki]:
322

    
323
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.
324

    
325
.. code-block:: console
326
    :emphasize-lines: 1
327

    
328
    Example 4.1.4: Execute different "list" commands from top context
329

    
330

    
331
    [kamaki]:config list
332
    ... (configuration options listing) ...
333
    [kamaki]:store list
334
    ... (storage container listing) ...
335
    [kamaki]:server list
336
    ... (VMs listing) ...
337
    [kamaki]:
338

    
339
Using Help
340
^^^^^^^^^^
341

    
342
There are two help mechanisms: a context-level and a command-level.
343

    
344
**Context-level help** lists the available commands in a context and can also offer a short description for each command.
345

    
346
Context-level help syntax::
347

    
348
    * Show available commands in current context *
349
    [context]:help
350
    [context]:?
351

    
352
    * Show help for command cmd *
353
    [context]:help cmd
354
    [context]:?cmd
355

    
356
The context-level help results change from context to context
357

    
358
.. code-block:: console
359
    :emphasize-lines: 1
360

    
361
    Example 4.2.1: Get available commands, pick a context and get help there as well
362

    
363

    
364
    [kamaki]:help
365

    
366
    kamaki commands:
367
    ================
368
    astakos  config  flavor  history  image  network  server  store
369

    
370
    interactive shell commands:
371
    ===========================
372
    exit  help  shell
373

    
374
    [kamaki]:?config
375
    Configuration commands (config -h for more options)
376

    
377
    [kamaki]:config
378

    
379
    [config]:?
380

    
381
    config commands:
382
    ================
383
    delete  get  list  set
384

    
385
    interactive shell commands:
386
    ===========================
387
    exit  help  shell
388

    
389
    [config]:help set
390
    Set a configuration option (set -h for more options)
391

    
392
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.
393

    
394
**Command-level help** prints the syntax, arguments and description of a specific (terminal) command
395

    
396
Command-level help syntax::
397

    
398
    * Get help for command cmd1 cmd2 ... cmdN *
399
    [context]:cmd1 cmd2 ... cmdN -h
400
    <syntax>
401

    
402
    <description>
403

    
404
    <arguments and possible extensions>
405

    
406
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.
407

    
408
.. code-block:: console
409
    :emphasize-lines: 1
410

    
411
    Example 4.2.2: Get command-level help for config and config-set
412

    
413

    
414
    [kamaki]:config --help
415
    config: Configuration commands
416
    delete:  Delete a configuration option (and use the default value)
417
    get   :  Show a configuration option
418
    list  :  List configuration options
419
    set   :  Set a configuration option
420

    
421
    [kamaki]:config
422

    
423
    [config]:set -h
424
    usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
425

    
426
    Set a configuration option
427

    
428
    optional arguments:
429
      -v, --verbose    More info at response
430
      -d, --debug      Include debug output
431
      -h, --help       Show help message
432
      -i, --include    Include protocol headers in the output
433
      --config CONFIG  Path to configuration file
434
      -s, --silent     Do not output anything
435

    
436
There are many ways of producing a help message, as shown in example 4.2.3
437

    
438
.. code-block:: console
439
    :emphasize-lines: 1
440

    
441
    Example 4.2.3: Equivalent calls of command-level help for config-set
442

    
443

    
444
    [config]:set -h
445
    [config]:set -help
446
    [kamaki]:config set -h
447
    [kamaki]:config set --help
448
    [store]:/config set -h
449
    [server]:/config set --help
450

    
451
.. _accessing-top-level-commands-ref:
452

    
453
Accessing top-level commands
454
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
455

    
456
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::
457

    
458
    * access a command "anothercontext cmd1 cmd2 ... cmdN"
459
    [context]:/anothercontext cmd1 cmd2 ... cmdN
460

    
461
An example (4.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:
462

    
463
* the name of the new VM
464
* the flavor id
465
* the image id
466

    
467
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.
468

    
469
.. code-block:: console
470
    :emphasize-lines: 1
471

    
472
    Example 4.3.1: Create a VM from server context
473

    
474
    [server]:create -h
475
    create <name> <flavor id> <image id> ...
476
    ...
477
    
478
    [server]:/flavor list
479
    ...
480
    20. AFLAVOR
481
        SNF:disk_template:  drbd
482
        cpu              :  4
483
        disk             :  10
484
        id               :  43
485
        ram              :  2048
486
    
487
    [server]:/image list
488
    1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
489
    18a82962-43eb-8f8880af89d7 (Windows 7)
490
    531aa018-9a40-a4bfe6a0caff (Windows XP)
491
    6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
492
    
493
    [server]:create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
494
    ...
495

    
496
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 acquires a new token (with a browser) which has to be set to kamaki.
497

    
498
.. code-block:: console
499
    :emphasize-lines: 1
500

    
501
    Example 4.3.2: Set a new token from store context
502

    
503

    
504
    [store]:list
505
    (401) UNAUTHORIZED Access denied
506

    
507
    [store]:/astakos authenticate
508
    (401) UNAUTHORIZED Invalid X-Auth-Token
509

    
510
    [store]:/config get token
511
    my3xp1r3dt0k3n==
512

    
513
    [store]:/config set token myfr35ht0k3n==
514

    
515
    [store]:/config get token
516
    myfr35ht0k3n==
517

    
518
    [store]:list
519
    1.  pithos (10MB, 2 objects)
520
    2.  trash (0B, 0 objects)
521

    
522
The following example compares some equivalent calls that run *astakos-authenticate* after a *store-list* 401 failure.
523

    
524
.. code-block:: console
525
    :emphasize-lines: 1,3,10,17,26
526

    
527
    Example 4.3.3: Equivalent astakos-authenticate calls after a store-list 401 failure
528

    
529
    * without kamaki interactive shell *
530
    $ kamaki store list
531
    (401) UNAUTHORIZED Access denied
532
    $ kamaki astakos authenticate
533
    ...
534
    $
535

    
536
    * from top-level context *
537
    [kamaki]:store list
538
    (401) UNAUTHORIZED Access denied
539
    [kamaki]:astakos authenticate
540
    ...
541
    [kamaki]
542

    
543
    * maximum typing *
544
    [store]:list
545
    (401) UNAUTHORIZED Access denied
546
    [store]:exit
547
    [kamaki]:astakos
548
    [astakos]:authenticate
549
    ...
550
    [astakos]:
551

    
552
    * minimum typing *
553
    [store]: list
554
    (401) UNAUTHORIZED Access denied
555
    [store]:/astakos authenticate
556
    ...
557
    [store]:
558

    
559
.. hint:: To exit kamaki shell while in a context, try */exit*
560

    
561
Using config
562
^^^^^^^^^^^^
563

    
564
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.
565

    
566
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.
567

    
568
.. 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)
569

    
570
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 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.
571

    
572
.. code-block:: console
573
    :emphasize-lines: 1
574

    
575
    Example 4.4.1: Set default storage container
576

    
577

    
578
    [store]:list
579
    1.  mycontainer (32MB, 2 objects)
580
    2.  pithos (0B, 0 objects)
581
    3.  trash (2MB, 1 objects)
582

    
583
    [store]:list mycontainer
584
    1.  D mydir/
585
    2.  20M mydir/rndm_local.file
586
    
587
    [store]:/config set store.container mycontainer
588

    
589
    [store]: list
590
    1.  D mydir/
591
    2.  20M mydir/rndm_local.file
592

    
593
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 4.4.2 .
594

    
595
.. code-block:: console
596
    :emphasize-lines: 1
597

    
598
    Example 4.4.2: Delete a setting option
599

    
600

    
601
    [store]:/config delete store.container
602

    
603
    [store]:list
604
    1.  mycontainer (32MB, 2 objects)
605
    2.  pithos (0B, 0 objects)
606
    3.  trash (2MB, 1 objects)
607

    
608
.. 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.
609

    
610
Using history
611
^^^^^^^^^^^^^
612

    
613
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.
614

    
615
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
616

    
617
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).
618

    
619
Tab completion
620
^^^^^^^^^^^^^^
621

    
622
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` ).
623

    
624
OS Shell integration
625
^^^^^^^^^^^^^^^^^^^^
626

    
627
Kamaki shell features the ability to execute OS-shell commands from any context. This can be achieved by typing *!* or *shell*::
628

    
629
    [kamaki_context]:!<OS shell command>
630
    ... OS shell command output ...
631

    
632
    [kamaki_context]:shell <OS shell command>
633
    ... OS shell command output ...
634

    
635
.. code-block:: console
636
    :emphasize-lines: 1
637

    
638
    Example 4.7.1: Run unix-style shell commands from kamaki shell
639

    
640

    
641
    [kamaki]:!ls -al
642
    total 16
643
    drwxrwxr-x 2 saxtouri saxtouri 4096 Nov 27 16:47 .
644
    drwxrwxr-x 7 saxtouri saxtouri 4096 Nov 27 16:47 ..
645
    -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 kamaki-logo.png
646

    
647
    [kamaki]:shell cp kamaki-logo.png logo-copy.png
648

    
649
    [kamaki]:shell ls -al
650
    total 24
651
    drwxrwxr-x 2 saxtouri saxtouri 4096 Nov 27 16:47 .
652
    drwxrwxr-x 7 saxtouri saxtouri 4096 Nov 27 16:47 ..
653
    -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 kamaki-logo.png
654
    -rw-rw-r-- 1 saxtouri saxtouri 8063 Jun 28 14:48 logo-copy.png
655

    
656

    
657
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 4.7.2 .
658

    
659
.. code-block:: console
660
    :emphasize-lines: 1
661

    
662
    Example 4.7.2: Attempt (and fail) to change working directory
663

    
664

    
665
    [kamaki]:!pwd
666
    /home/username
667

    
668
    [kamaki]:!cd ..
669

    
670
    [kamaki]:shell pwd
671
    /home/username