Statistics
| Branch: | Tag: | Revision:

root / docs / usage.rst @ 8be50626

History | View | Annotate | Download (26.2 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 API that allows the development of
10
external applications for synnefo. The clients API is listed 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 behaviors. 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 behavior:
42

    
43
* tab completion for commands (if supported by host command line shell)
44
* session history with ↑ or ↓ keys (if supported by host command line shell)
45
* shorter commands with command context switching
46
* re-run old commands with /history
47

    
48
In favor of one-command behavior:
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'.
68

    
69
.. code-block:: console
70
    :emphasize-lines: 1
71

    
72
    Example 2.2.2: Run kamaki shell with custom configuration file
73

    
74
    $ kamaki -c myconfig.file
75

    
76

    
77
Run as one-command
78
^^^^^^^^^^^^^^^^^^
79
To use kamaki as an one-command tool, run:
80

    
81
* with the '-h' or '--help' arguments (help for kamaki one-command)
82

    
83
.. code-block:: console
84
    :emphasize-lines: 1
85

    
86
    Example 2.3.1: Kamaki help
87

    
88
    $kamaki -h
89

    
90
* with one or more command parameters:
91

    
92
.. code-block:: console
93
    :emphasize-lines: 1
94

    
95
    Example 2.3.2: List VMs managed by user
96

    
97
    $ kamaki server list
98

    
99
One-command interface
100
---------------------
101

    
102
Using help
103
^^^^^^^^^^
104

    
105
Kamaki help is used to list available commands with description, syntax and
106
corresponding optional arguments.
107

    
108
To see the command groups, use -h or --help like in example 1.3.1. In the same
109
way, help information for command groups and commands is printed. In the
110
following examples, the help messages of kamaki, of a command group (server)
111
and of a command in that group (list) are shown.
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
    config :  Kamaki configurations
139
    file   :  Pithos+/Storage API commands
140
    flavor :  Cyclades/Compute API flavor commands
141
    history:  Kamaki command history
142
    image  :  Cyclades/Plankton API image commands
143
    image compute:  Cyclades/Compute API image commands
144
    network:  Cyclades/Compute API network commands
145
    server :  Cyclades/Compute API server commands
146
    user   :  Astakos API commands
147

    
148
.. code-block:: console
149
    :emphasize-lines: 1,2
150

    
151
    Example 3.1.2: Cyclades help contains all first-level commands of Cyclades
152
    command group
153

    
154
    $ kamaki server -h
155
    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG]
156
                               [-o OPTIONS] [--cloud CLOUD] [-h]
157

    
158
    optional arguments:
159
      -v, --verbose         More info at response
160
      -s, --silent          Do not output anything
161
      -V, --version         Print current version
162
      -d, --debug           Include debug output
163
      -i, --include         Include protocol headers in the output
164
      -c CONFIG, --config CONFIG
165
                            Path to configuration file
166
      -o OPTIONS, --options OPTIONS
167
                            Override a config value
168
      --cloud CLOUD         Chose a cloud to connect to
169
      -h, --help            Show help message
170

    
171
    Options:
172
     - - - -
173
    addr    :  List the addresses of all network interfaces on a server (VM)
174
    console :  Get a VNC console to access an existing server (VM)
175
    create  :  Create a server (aka Virtual Machine)
176
    delete  :  Delete a server (VM)
177
    firewall:  Manage server (VM) firewall profiles for public networks
178
    ip      :  Manage floating IPs for the servers
179
    info    :  Detailed information on a Virtual Machine
180
    list    :  List Virtual Machines accessible by user
181
    metadata:  Manage Server metadata (key:value pairs of server attributes)
182
    reboot  :  Reboot a server (VM)
183
    rename  :  Set/update a server (VM) name
184
    shutdown:  Shutdown an active server (VM)
185
    start   :  Start an existing server (VM)
186
    stats   :  Get server (VM) statistics
187
    resize  :  Set a different flavor for an existing server
188
    wait    :  Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
189

    
190
.. code-block:: console
191
    :emphasize-lines: 1,2
192

    
193
    Example 3.1.3: Help for command "server list" with syntax, description and
194
    available user options
195

    
196
    $ kamaki server list -h
197
    usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS]
198
                              [--cloud CLOUD] [-h] [--since SINCE] [--enumerate]
199
                              [-l] [--more] [-n LIMIT] [-j]
200

    
201
    List Virtual Machines accessible by user
202
    User Authentication:    
203
    * to check authentication: /user authenticate    
204
    * to set authentication token: /config set cloud.default.token <token>
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 configuration 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
    --since SINCE         show only items since date (' d/m/Y H:M:S ')
219
    --enumerate           Enumerate results
220
    -l, --details         show detailed output
221
    --more                output results in pages (-n to set items per page,
222
                          default 10)
223
    -n LIMIT, --number LIMIT
224
                          limit number of listed VMs
225
    -j, --json            show headers in json
226

    
227
.. _using-history-ref:
228

    
229
Using history
230
^^^^^^^^^^^^^
231

    
232
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>`_).
233

    
234
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:
235

    
236
.. code-block:: console
237
    :emphasize-lines: 1
238

    
239
    Example 3.2.1: Available history options
240

    
241

    
242
    $ kamaki history -h
243
    Options:
244
     - - - -
245
    clean:  Clean up history (permanent)
246
    run  :  Run previously executed command(s)
247
    show :  Show intersession command history
248

    
249
The following example showcases how to use history in kamaki
250

    
251
.. code-block:: console
252
    :emphasize-lines: 1
253

    
254
    Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
255
    
256

    
257
    $ kamaki history clean
258
    $ kamaki server list
259
    ...
260
    $ kamaki history show
261
    1.  kamaki server list
262
    2.  kamaki history show
263
    $ kamaki history show --match server
264
    1. kamaki server list
265
    3. kamaki history show --match server
266

    
267
Debug and logging
268
^^^^^^^^^^^^^^^^^
269

    
270
Debug
271
"""""
272

    
273
In case of errors, kamaki in debug mode shows useful debug information, like
274
the stack trace. Kamaki in debug mode cancels suppression of warning messages.
275

    
276
To run kamaki in debug mode use the -d or --debug option (can be combined with
277
any other parameters or options)
278

    
279
Logging
280
"""""""
281

    
282
Kamaki keeps its logs in a file specified as global.log_file and its value
283
defaults to ${HOME}/.kamaki.log . This value may change with a config setting::
284

    
285
    kamaki config set log_file /new/log/file/path
286

    
287
Kamaki logs mostly the http connection requests and responses, including http
288
methods, urls, parameters and headers. There is some special handling in two
289
cases:
290

    
291
* HTTP bodies are not logged by default
292
    to enable logging the full http bodies, set log_data to `on`::
293

    
294
        kamaki config set log_data on
295

    
296
    to disable it, set it to `off`::
297

    
298
        kamaki config set log_data off
299

    
300
    or delete it::
301

    
302
        kamaki config delete log_data
303

    
304
* X-Auth-Token header is not logged by default
305
    to enable logging the X-Auth-Token header, set log_token to `on`::
306

    
307
        kamaki config set log_token on
308

    
309
    to disable it, set it to `off`::
310

    
311
        kamaki config set log_token off
312

    
313
    or delete it::
314

    
315
        kamaki config delete log_token
316

    
317
Verbose and Include
318
"""""""""""""""""""
319

    
320
Most kamaki commands are translated into http requests. Kamaki clients API
321
translated the semantics to REST and handles the response. Users who need to
322
have access to these commands can use the verbose mode that presents the HTTP
323
Request details as well as the full server response.
324

    
325
To run kamaki in verbose mode use the -v or --verbose option
326

    
327
Be default, kamaki in verbose mode prints down only the headers and the address
328
information, thus hiding the data body of the request or response. To see the
329
data body, the -i option can be used.
330

    
331
One-command features
332
^^^^^^^^^^^^^^^^^^^^
333

    
334
Kamaki commands can be used along with advanced shell features.
335

    
336
.. code-block:: console
337
    :emphasize-lines: 1
338

    
339
    Example 3.4.1: List the trash container contents, containing c1_
340
    
341

    
342
    $ kamaki file list -o cloud.default.pithos_container=trash| grep c1_
343
    c1_1370859409.0 20KB
344
    c1_1370859414.0 9MB
345
    c1_1370859409.1 110B
346

    
347
The -o argument can be used to temporarily override various (set or unset)
348
options. In one command, all -o option sets are forgotten just after the
349
command has been completed, and the previous settings are restored (the
350
configuration file is not modified).
351

    
352
The file-list command in example 3.4.1 runs with an explicitly provided
353
pithos_account, which temporarily overrides the one probably provided in the
354
configuration file (it works even if the user has not set the optional
355
pithos_account config option).
356

    
357
Interactive shell
358
-----------------
359

    
360
Command Contexts
361
^^^^^^^^^^^^^^^^
362

    
363
The kamaki interactive shell implements the notion of command contexts. Each
364
command group is also a context where the users can **enter** by typing the
365
group name. If the context switch is successful, the kamaki shell prompt
366
changes to present the new context ("file" in example 4.1.1).
367

    
368
.. code-block:: console
369
    :emphasize-lines: 1
370

    
371
    Example 4.1.1: Enter file commands context / group
372

    
373

    
374
    $ kamaki
375
    [kamaki]: file
376
    [file]:
377

    
378
Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in
379
Windows) to exit a context and return to the context of origin. If already at
380
the top context (kamaki), an exit is equivalent to exiting the program.
381

    
382
.. code-block:: console
383
    :emphasize-lines: 1
384

    
385
    Example 4.1.2: Exit file context and then exit kamaki
386

    
387
    [file]: exit
388
    [kamaki]: exit
389
    $
390

    
391
A user might **browse** through different contexts during one session.
392

    
393
.. code-block:: console
394
    :emphasize-lines: 1
395

    
396
    Example 4.1.3: Execute list command in different contexts
397

    
398
    $ kamaki
399
    [kamaki]: config
400
    [config]: list
401
    ... (configuration options listing) ...
402
    [config]: exit
403
    [kamaki]: file
404
    [file]: list
405
    ... (storage containers listing) ...
406
    [file]: exit
407
    [kamaki]: server
408
    [server]: list
409
    ... (VMs listing) ...
410
    [server]: exit
411
    [kamaki]:
412

    
413
Users have the option to avoid switching between contexts: all commands can run
414
from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent.
415

    
416
.. code-block:: console
417
    :emphasize-lines: 1
418

    
419
    Example 4.1.4: Execute different "list" commands from top context
420

    
421

    
422
    [kamaki]: config list
423
    ... (configuration options listing) ...
424
    [kamaki]: file list
425
    ... (storage container listing) ...
426
    [kamaki]: server list
427
    ... (VMs listing) ...
428
    [kamaki]:
429

    
430
Using Help
431
^^^^^^^^^^
432

    
433
There are two help mechanisms: a context-level and a command-level.
434

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

    
438
Context-level help syntax::
439

    
440
    * Show available commands in current context *
441
    [context]: help
442
    [context]: ?
443

    
444
    * Show help for command cmd *
445
    [context]: help cmd
446
    [context]: ?cmd
447

    
448
The context-level help results may change from context to context
449

    
450
.. code-block:: console
451
    :emphasize-lines: 1
452

    
453
    Example 4.2.1: Get available commands and then get help in a context
454

    
455

    
456
    [kamaki]: help
457

    
458
    kamaki commands:
459
    ================
460
    user  config  flavor  history  image  network  server  file
461

    
462
    interactive shell commands:
463
    ===========================
464
    exit  help  shell
465

    
466
    [kamaki]: ?config
467
    Configuration commands (config -h for more options)
468

    
469
    [kamaki]: config
470

    
471
    [config]: ?
472

    
473
    config commands:
474
    ================
475
    delete  get  list  set
476

    
477
    interactive shell commands:
478
    ===========================
479
    exit  help  shell
480

    
481
    [config]: help set
482
    Set a configuration option (set -h for more options)
483

    
484
In context-level, there is a distinction between kamaki-commands and
485
interactive shell commands. The former are available in one-command mode and
486
are related to the cloud client setup and use, while the later are
487
context-shell functions.
488

    
489
**Command-level help** prints the syntax, arguments and description of a
490
specific (terminal) command
491

    
492
Command-level help syntax::
493

    
494
    * Get help for command cmd1 cmd2 ... cmdN *
495
    [context]: cmd1 cmd2 ... cmdN -h
496
    <syntax>
497

    
498
    <description>
499

    
500
    <arguments and possible extensions>
501

    
502
Command-level help mechanism is exactly the same as the one used in
503
one-command mode. For example, it is invoked by using the -h or --help
504
parameter at any point.
505

    
506
.. code-block:: console
507
    :emphasize-lines: 1
508

    
509
    Example 4.2.2: Get command-level help for config and config-set
510

    
511

    
512
    [kamaki]: config --help
513
    config: Configuration commands
514
    delete:  Delete a configuration option (and use the default value)
515
    get   :  Show a configuration option
516
    list  :  List configuration options
517
    set   :  Set a configuration option
518

    
519
    [kamaki]: config
520

    
521
    [config]: set -h
522
    usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
523

    
524
    Set a configuration option
525

    
526
    optional arguments:
527
      -v, --verbose    More info at response
528
      -d, --debug      Include debug output
529
      -h, --help       Show help message
530
      -i, --include    Include protocol headers in the output
531
      --config CONFIG  Path to configuration file
532
      -s, --silent     Do not output anything
533

    
534
There are many ways of producing a help message, as shown in example 4.2.3
535

    
536
.. code-block:: console
537
    :emphasize-lines: 1
538

    
539
    Example 4.2.3: Equivalent calls of command-level help for config-set
540

    
541

    
542
    [config]: set -h
543
    [config]: set --help
544
    [kamaki]: config set -h
545
    [kamaki]: config set --help
546
    [file]: /config set -h
547
    [server]: /config set --help
548

    
549
.. _accessing-top-level-commands-ref:
550

    
551
Accessing top-level commands
552
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
553

    
554
When working in a context, it is often useful to access other contexts or
555
top-level commands. Kamaki offers access to top-level commands by using the
556
`/` prefix, as shown bellow::
557

    
558
    * access a command "anothercontext cmd1 cmd2 ... cmdN"
559
    [context]: /anothercontext cmd1 cmd2 ... cmdN
560

    
561
An example (4.3.1) that showcases how top-level access improves user experience
562
is the creation of a VM. A VM is created with the command server-create. This
563
command is called with three parameters:
564

    
565
* the name of the new VM
566
* the flavor id
567
* the image id
568

    
569
It is often the case that a user who works in the context command, needs to
570
create a new VM, but hasn't selected a flavor or an image id, or cannot recall
571
the id of that flavor or image. Therefore, it is necessary to list all
572
available flavors (flavor-list) or images (image-compute-list). Both commands
573
belong to different contexts.
574

    
575
.. code-block:: console
576
    :emphasize-lines: 1
577

    
578
    Example 4.3.1: Create a VM from server context
579

    
580
    [server]: create -h
581
    create <name> <flavor id> <image id> ...
582
    ...
583
    
584
    [server]: /flavor list
585
    ...
586
    43 AFLAVOR
587
        SNF:disk_template:  drbd
588
        cpu              :  4
589
        disk             :  10
590
        ram              :  2048
591
    
592
    [server]: /image compute list
593
    1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
594
    18a82962-43eb-8f8880af89d7 (Windows 7)
595
    531aa018-9a40-a4bfe6a0caff (Windows XP)
596
    6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
597
    
598
    [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
599
    ...
600

    
601
An other example (4.3.2) showcases how to acquire and modify configuration
602
settings from a different context. In this scenario, the user token expires at
603
server side while the user is working. When that happens, the system responds
604
with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid
605
for the Astakos identity manager of preference) which has to be set to kamaki.
606

    
607
.. code-block:: console
608
    :emphasize-lines: 1
609

    
610
    Example 4.3.2: Set a new token from file context
611

    
612

    
613
    [file]: list
614
    (401) UNAUTHORIZED Access denied
615

    
616
    [file]: /user authenticate
617
    (401) UNAUTHORIZED Invalid X-Auth-Token
618

    
619
    [file]: /config get cloud.default.token
620
    my3xp1r3dt0k3n==
621

    
622
    [file]: /config set cloud.default.token myfr35ht0k3n==
623

    
624
    [file]: /config get cloud.default
625
    cloud.default.url = https://astakos.example.com/astakos/identity/2.0/
626
    cloud.default.token = myfr35ht0k3n==
627

    
628
    [file]: list
629
    1.  pithos (10MB, 2 objects)
630
    2.  trash (0B, 0 objects)
631

    
632
.. note:: The error messages on this example where shortened for clarity.
633
    Actual kamaki error messages are more helpful and descriptive.
634

    
635
The following example compares some equivalent calls that run
636
*user-authenticate* after a *file-list* 401 failure.
637

    
638
.. code-block:: console
639
    :emphasize-lines: 1,3,10,17,26
640

    
641
    Example 4.3.3: Equivalent user-authenticate calls after a file-list 401
642

    
643
    * without kamaki interactive shell *
644
    $ kamaki file list
645
    (401) UNAUTHORIZED Access denied
646
    $ kamaki user authenticate
647
    ...
648
    $
649

    
650
    * from top-level context *
651
    [kamaki]: file list
652
    (401) UNAUTHORIZED Access denied
653
    [kamaki]: user authenticate
654
    ...
655
    [kamaki]
656

    
657
    * maximum typing *
658
    [file]: list
659
    (401) UNAUTHORIZED Access denied
660
    [file]: exit
661
    [kamaki]: user
662
    [user]: authenticate
663
    ...
664
    [user]:
665

    
666
    * minimum typing *
667
    [file]: list
668
    (401) UNAUTHORIZED Access denied
669
    [file]: /user authenticate
670
    ...
671
    [file]:
672

    
673
.. hint:: To exit kamaki shell while in a context, try */exit*
674

    
675
Using config
676
^^^^^^^^^^^^
677

    
678
The configuration mechanism of kamaki is detailed in the
679
`setup section <setup.html>`_ and it is common for both interaction modes. In
680
specific, the configuration mechanism is implemented as a command group, namely
681
`config`. Using the config commands is as straightforward as any other kamaki
682
commands.
683

    
684
It is often useful to set, delete or update a value. This can be managed either
685
inside the config context or from any command context by using the / prefix.
686

    
687
.. Note:: config updates in kamaki shell persist even after the session is over
688

    
689
All setting changes affect the physical kamaki config file. The config file is
690
created automatically at callers' home firectory the first time a config option
691
is set, and lives there as *.kamakirc* . It can be edited with any text editor
692
or managed with kamaki config commands.
693

    
694
In example 4.4.1 the user is going to work with only one storage container. The
695
file commands use the container:path syntax, but if the user sets a container
696
name as default, the container name can be omitted. This is possible by setting
697
a *file.container* setting.
698

    
699
.. code-block:: console
700
    :emphasize-lines: 1
701

    
702
    Example 4.4.1: Set default storage container (cloud: default)
703

    
704

    
705
    [file]: list
706
    1.  mycontainer (32MB, 2 objects)
707
    2.  pithos (0B, 0 objects)
708
    3.  trash (2MB, 1 objects)
709

    
710
    [file]: list mycontainer
711
    1.  D mydir/
712
    2.  20M mydir/rndm_local.file
713
    
714
    [file]: /config set cloud.default.pithos_container mycontainer
715

    
716
    [file]: list
717
    1.  D mydir/
718
    2.  20M mydir/rndm_local.file
719

    
720
After a while, the user needs to work with multiple containers, therefore a
721
default container is no longer needed. The *pithos_container* setting can be
722
deleted, as shown in example 4.4.2
723

    
724
.. code-block:: console
725
    :emphasize-lines: 1
726

    
727
    Example 4.4.2: Delete a setting option (cloud: default)
728

    
729

    
730
    [file]: /config delete cloud.default.pithos_container
731

    
732
    [file]: list
733
    1.  mycontainer (32MB, 2 objects)
734
    2.  pithos (0B, 0 objects)
735
    3.  trash (2MB, 1 objects)
736

    
737
Using history
738
^^^^^^^^^^^^^
739

    
740
There are two history modes: session and permanent. Session history keeps
741
record of all actions in a kamaki shell session, while permanent history
742
appends all commands to an accessible history file.
743

    
744
Session history is only available in interactive shell mode. Users can iterate
745
through past commands in the same session with the ↑ and ↓ keys. Session
746
history is not stored, although syntactically correct commands are recorded
747
through the permanent history mechanism.
748

    
749
Permanent history is implemented as a command group and is common to both the
750
one-command and shell interfaces. In specific, every syntactically correct
751
command is appended in a history file (configured as `history_file` in
752
settings, see `setup section <setup.html>`_ for details). Commands executed in
753
one-command mode are mixed with the ones run in kamaki shell (also
754
see :ref:`using-history-ref` section on this guide).
755

    
756
Scripting
757
^^^^^^^^^
758

    
759
The history-run feature allows the sequential run of previous command
760
executions in kamaki shell.
761

    
762
The following sequence copies and downloads a file from *mycontainer1* ,
763
uploads it to *mycontainer2* , then undo the proccess and repeats it with
764
history-run
765

    
766
.. code-block:: console
767
    :emphasize-lines: 1,12,19,32
768

    
769
    * Download mycontainer1:myfile and upload it to mycontainer2:myfile
770
    [kamaki]: file
771
    [file]: copy mycontainer1:somefile mycontainer1:myfile
772
    [file]: download mycontainer1:myfile mylocalfile
773
    Download completed
774
    [file]: upload mylocalfile mycontainer2:myfile
775
    Upload completed
776

    
777
    * undo the process *
778
    [file]: !rm mylocalfile
779
    [file]: delete mycontainer1:myfile
780
    [file]: delete mycontainer2:myfile
781

    
782
    * check history entries *
783
    [file]: exit
784
    [kamaki]: history
785
    [history]: show
786
    1.  file
787
    2.  file copy mycontainer1:somefile mycontainer1:myfile
788
    3.  file download mycontainer1:myfile mylocalfile
789
    4.  file upload mylocalfile mycontainer2:myfile
790
    5.  file delete mycontainer1:myfile
791
    6.  file delete mycontainer2:myfile
792
    7.  history
793
    8.  history show
794

    
795
    *repeat the process *
796
    [history]: run 2-4
797
    <file copy mycontainer1:somefile mycontainer1:myfile>
798
    <file download mycontainer1:myfile mylocalfile>
799
    Download completed
800
    <file upload mylocalfile mycontainer2:myfile>
801
    Upload completed
802

    
803
For powerfull scripting, users are advised to take advantage of their os shell
804
scripting capabilities and combine them with kamaki one-command. Still, the
805
history-run functionality might prove handy in many occasions.
806

    
807
Tab completion
808
^^^^^^^^^^^^^^
809

    
810
Kamaki shell features tab completion for the first level of command terms of
811
the current context. Tab completion pool changes dynamically when the context
812
is switched. Currently, tab completion is not supported when / is used
813
(see :ref:`accessing-top-level-commands-ref` ).
814

    
815
OS Shell integration
816
^^^^^^^^^^^^^^^^^^^^
817

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

    
821
    [kamaki_context]: !<OS shell command>
822
    ... OS shell command output ...
823

    
824
    [kamaki_context]: shell <OS shell command>
825
    ... OS shell command output ...
826

    
827
.. code-block:: console
828
    :emphasize-lines: 1
829

    
830
    Example 4.7.1: Run unix-style shell commands from kamaki shell
831

    
832

    
833
    [kamaki]: !ls -al
834
    total 16
835
    drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
836
    drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
837
    -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
838

    
839
    [kamaki]: shell cp kamaki-logo.png logo-copy.png
840

    
841
    [kamaki]: shell ls -al
842
    total 24
843
    drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
844
    drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
845
    -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
846
    -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png
847

    
848

    
849
Kamaki shell commits command strings to the outside shell and prints the
850
results, without interacting with it. After a command is finished, kamaki shell
851
returns to its initial state, which involves the current directory, as show in
852
example 4.8.2
853

    
854
.. code-block:: console
855
    :emphasize-lines: 1
856

    
857
    Example 4.8.2: Attempt (and fail) to change working directory
858

    
859

    
860
    [kamaki]: !pwd
861
    /home/username
862

    
863
    [kamaki]: !cd ..
864

    
865
    [kamaki]: shell pwd
866
    /home/username