Statistics
| Branch: | Tag: | Revision:

root / docs / usage.rst @ 2bd23362

History | View | Annotate | Download (26.3 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 is used to list available commands with description, syntax and
107
corresponding optional arguments.
108

    
109
To see the command groups, use -h or --help like in example 1.3.1. In the same
110
way, help information for command groups and commands is printed. In the
111
following examples, the help messages of kamaki, of a command group (server)
112
and of a command in that group (list) are shown.
113

    
114
.. code-block:: console
115
    :emphasize-lines: 1
116

    
117
    Example 3.1.1: kamaki help shows available parameters and command groups
118

    
119

    
120
    $ kamaki -h
121
    usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
122
        [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
123

    
124
    optional arguments:
125
      -v, --verbose         More info at response
126
      -s, --silent          Do not output anything
127
      -V, --version         Print current version
128
      -d, --debug           Include debug output
129
      -i, --include         Include protocol headers in the output
130
      -c CONFIG, --config CONFIG
131
                            Path to configuration file
132
      -o OPTIONS, --options OPTIONS
133
                            Override a config value
134
      --cloud CLOUD         Chose a cloud to connect to
135
      -h, --help            Show help message
136

    
137
    Options:
138
     - - - -
139
    config :  Kamaki configurations
140
    file   :  Pithos+/Storage API commands
141
    flavor :  Cyclades/Compute API flavor commands
142
    history:  Kamaki command history
143
    image  :  Cyclades/Plankton API image commands
144
    image compute:  Cyclades/Compute API image commands
145
    network:  Cyclades/Compute API network commands
146
    server :  Cyclades/Compute API server commands
147
    user   :  Astakos API commands
148

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

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

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

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

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

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

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

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

    
202
    List Virtual Machines accessible by user
203
    User Authentication:    
204
    * to check authentication: /user authenticate    
205
    * to set authentication token: /config set cloud.default.token <token>
206

    
207
    optional arguments:
208
    -v, --verbose         More info at response
209
    -s, --silent          Do not output anything
210
    -V, --version         Print current version
211
    -d, --debug           Include debug output
212
    -i, --include         Include raw connection data in the output
213
    -c CONFIG, --config CONFIG
214
                          Path to configuration file
215
    -o OPTIONS, --options OPTIONS
216
                          Override a config value
217
    --cloud CLOUD         Chose a cloud to connect to
218
    -h, --help            Show help message
219
    --since SINCE         show only items since date (' d/m/Y H:M:S ')
220
    --enumerate           Enumerate results
221
    -l, --details         show detailed output
222
    --more                output results in pages (-n to set items per page,
223
                          default 10)
224
    -n LIMIT, --number LIMIT
225
                          limit number of listed servers
226
    -j, --json            show headers in json
227

    
228
.. _using-history-ref:
229

    
230
Using history
231
^^^^^^^^^^^^^
232

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

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

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

    
240
    Example 3.2.1: Available history options
241

    
242

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

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

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

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

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

    
268
Debug and logging
269
^^^^^^^^^^^^^^^^^
270

    
271
Debug
272
"""""
273

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

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

    
280
Logging
281
"""""""
282

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

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

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

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

    
295
        kamaki config set log_data on
296

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

    
299
        kamaki config set log_data off
300

    
301
    or delete it::
302

    
303
        kamaki config delete log_data
304

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

    
308
        kamaki config set log_token on
309

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

    
312
        kamaki config set log_token off
313

    
314
    or delete it::
315

    
316
        kamaki config delete log_token
317

    
318
Verbose and Include
319
"""""""""""""""""""
320

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

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

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

    
332
One-command features
333
^^^^^^^^^^^^^^^^^^^^
334

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

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

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

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

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

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

    
358
Interactive shell
359
-----------------
360

    
361
Command Contexts
362
^^^^^^^^^^^^^^^^
363

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

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

    
372
    Example 4.1.1: Enter file commands context / group
373

    
374

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

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

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

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

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

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

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

    
397
    Example 4.1.3: Execute list command in different contexts
398

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

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

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

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

    
422

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

    
431
Using Help
432
^^^^^^^^^^
433

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

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

    
439
Context-level help syntax::
440

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

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

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

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

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

    
456

    
457
    [kamaki]: help
458

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

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

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

    
470
    [kamaki]: config
471

    
472
    [config]: ?
473

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

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

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

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

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

    
493
Command-level help syntax::
494

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

    
499
    <description>
500

    
501
    <arguments and possible extensions>
502

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

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

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

    
512

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

    
520
    [kamaki]: config
521

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

    
525
    Set a configuration option
526

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

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

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

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

    
542

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

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

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

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

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

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

    
566
* the name of the new server
567
* the flavor id
568
* the image id
569

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

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

    
579
    Example 4.3.1: Create a server from server context
580

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

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

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

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

    
613

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
676
Using config
677
^^^^^^^^^^^^
678

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

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

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

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

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

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

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

    
705

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

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

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

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

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

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

    
730

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

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

    
738
Using history
739
^^^^^^^^^^^^^
740

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

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

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

    
757
Scripting
758
^^^^^^^^^
759

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

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

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

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

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

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

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

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

    
808
Tab completion
809
^^^^^^^^^^^^^^
810

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

    
816
OS Shell integration
817
^^^^^^^^^^^^^^^^^^^^
818

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

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

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

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

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

    
833

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

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

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

    
849

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

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

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

    
860

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

    
864
    [kamaki]: !cd ..
865

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