Revision 76769d2f

b/docs/commands.rst
321 321
.. Note:: In kamaki shell, / is used to access top-level command groups while
322 322
    working in command group contexts
323 323

  
324
network (Compute/Cyclades)
324
network (Network/Cyclades)
325 325
--------------------------
326 326

  
327 327
.. code-block:: text
......
404 404
container (Storage/Pithos+)
405 405
---------------------------
406 406

  
407
.. code-block:: text
408

  
407 409
    info      Get information about a container
408 410
    modify    Modify the properties of a container
409 411
    create    Create a new container
......
414 416
group (Storage/Pithos+)
415 417
-----------------------
416 418

  
419
.. code-block:: text
420

  
417 421
    create    Create a group of users
418 422
    list      List all groups and group members
419 423
    delete    Delete a user group
......
421 425
sharer (Storage/Pithos+)
422 426
------------------------
423 427

  
428
.. code-block:: text
429

  
424 430
    info      Details on a Pithos+ sharer account (default: current account)
425 431
    list      List accounts who share file objects with current user
426 432

  
b/docs/setup.rst
552 552
    $ kamaki livetest cyclades create_server
553 553

  
554 554

  
555
The unit tests
556
""""""""""""""
555
Unit tests
556
""""""""""
557 557

  
558 558
Kamaki features a set of unit tests for the kamaki.clients package. This set is
559 559
not used when kamaki is running. Instead, it is aimed to developers who debug
b/docs/usage.rst
1 1
Usage
2 2
=====
3 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.
4
Kamaki features commands of the form::
8 5

  
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.
6
  [kamaki] <object> <action> [identifier(s)] <non-positional arguments>
7
  e.g., 
8
  kamaki user info --username=user@example.com
9

  
10
A detailed list of the command specifications can be found in
11
`Commands <commands.html>`_ section.
12

  
13
All commands can run either from the host shell or through the kamaki
14
interactive shell:
15

  
16
.. code-block:: console
17

  
18
  #  Run from host shell
19
  $ kamaki user info
20
  ... RESULTS ...
21

  
22
  #  Run from kamaki interactive shell
23
  $ kamaki-shell
24
  [kamaki]: user info
25
  ... RESULTS ...
26

  
27
In the later, the term "one-command" will be user to refer to running kamaki
28
commands from host shell, while the term "shell" will refer to the kamaki's own
29
interactive shell
30

  
31
.. note:: This section refers to the kamaki CLI. Developers and people who write
32
  scripts, should rather use the the
33
  `Clients lib <developers/code.html#the-clients-api>`_ instead of the kamaki
34
  CLI.
12 35

  
13 36
Quick Setup
14 37
-----------
15 38

  
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.
39
Kamaki interfaces rely on a list of configuration options. Check the
40
`Setup <setup.html>`_ guide for a full list.
18 41

  
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:
42
As rule of the thump, it is enough to set a cloud authentication URL and TOKEN:
21 43

  
22 44
.. code-block:: console
23 45
    :emphasize-lines: 1
24 46

  
25
    Example 1.1: Set authentication URL, user token and cloud alias "default"
47
    Example 1.1: Set authentication URL, user token for cloud alias "default"
26 48

  
27 49
    $ kamaki config set cloud.default.url <authentication URL>
28 50
    $ kamaki config set cloud.default.token myt0k3n==
29 51

  
30 52
.. 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.
53
    the user.
33 54

  
34 55
Shell vs one-command
35 56
--------------------
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.
57

  
58
Kamaki users can access Synnefo services through either the kamaki shell or the
59
one-command interface. Both systems feature identical responses and error
60
messages, since they rely on the same internal command and library API
61
implementation. However, there are some minor differences.
40 62

  
41 63
In favor of interactive shell:
42 64

  
43
* tab completion for commands (if supported by the user shell)
44
* session history with ↑ or ↓ keys (if supported by the user shell)
45
* shorter commands with command context switching
65
* shorter commands (context switching)
66
* tab completion for commands (if supported by host shell)
67
* kamaki-specific history with ↑ or ↓ keys (if supported by host shell)
46 68
* re-run old commands with /history
47 69

  
48 70
In favor of one-command:
49 71

  
50
* can be used along with advanced shell features (pipelines, redirection, etc.)
72
* users take advantage of host shell features (pipelines, redirection, etc.)
51 73
* can be used in shell scripts
52
* prints debug and verbose messages if needed
53 74

  
54 75
Run as shell
55 76
^^^^^^^^^^^^
56 77
To use kamaki as a shell, run:
57 78

  
58
* without any parameters or arguments
59

  
60 79
.. code-block:: console
61 80
    :emphasize-lines: 1
62 81

  
63 82
    Example 2.2.1: Run kamaki shell
64 83

  
65
    $ kamaki
84
    $ kamaki-shell
66 85

  
67 86
* with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
68 87
    '- - version'.
......
72 91

  
73 92
    Example 2.2.2: Run kamaki shell with custom configuration file
74 93

  
75
    $ kamaki -c myconfig.file
94
    $ kamaki-shell -c myconfig.file
95

  
96
    Example 2.2.3: Run kamaki shell so as to use a specific cloud
97

  
98
    $ kamaki-shell --cloud=my_demo_cloud
99

  
100
    Example 2.2.4: Run kamaki shell with verbosity (shows HTTP requests)
101

  
102
    $ kamaki-shell -v
76 103

  
104
.. note:: Valid arguments can be combined e.g., it is ok to run a shell with
105
  verbosity and a specific cloud::
106

  
107
    $ kamaki-shell -v --cloud=my_demo_cloud
77 108

  
78 109
Run as one-command
79 110
^^^^^^^^^^^^^^^^^^
......
88 119

  
89 120
    $kamaki -h
90 121

  
91
* with one or more command parameters:
122
* with one or more command parameters (object and, maybe, action):
92 123

  
93 124
.. code-block:: console
94 125
    :emphasize-lines: 1
......
103 134
Using help
104 135
^^^^^^^^^^
105 136

  
106
Kamaki help provides information on available commands (description, syntax and
107
corresponding optional arguments).
137
Kamaki help provides information on commands (description, syntax).
108 138

  
109
To see the command groups, use -h or --help (example 1.3.1). The
139
To see the command groups (objects), use -h or --help (example 1.3.1). The
110 140
following examples demonstrate the help messages of kamaki, in the context of a
111 141
command group (server) and of a command in that group (list).
112 142

  
......
118 148

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

  
123 153
    optional arguments:
124 154
      -v, --verbose         More info at response
125 155
      -s, --silent          Do not output anything
126 156
      -V, --version         Print current version
127 157
      -d, --debug           Include debug output
128
      -i, --include         Include protocol headers in the output
129 158
      -c CONFIG, --config CONFIG
130 159
                            Path to configuration file
131 160
      -o OPTIONS, --options OPTIONS
......
135 164

  
136 165
    Options:
137 166
     - - - -
138
    network: Cyclades/Compute API network commands
139
    user: Astakos API commands
140
    livetest: Client func. tests on live servers
141
    server: Cyclades/Compute API server commands
142
    project: Synnefo project management CLI
143
    file: Pithos+/Storage API commands
167
    resource: Astakos/Account API commands for resources
168
    group: Pithos+/Storage user groups
169
    network: Networking API network commands
170
    subnet: Networking API network commands
171
    ip: Networking API floatingip commands
172
    image: Cyclades/Plankton API image commands
173
    imagecompute: Cyclades/Compute API image commands
174
    quota: Astakos/Account API commands for quotas
175
    sharer: Pithos+/Storage sharers
176
    project: Astakos project API commands
177
    user: Astakos/Identity API commands
178
    file: Pithos+/Storage object level API commands
179
    container: Pithos+/Storage container level API commands
144 180
    flavor: Cyclades/Compute API flavor commands
181
    server: Cyclades/Compute API server commands
145 182
    config: Kamaki configurations
146
    image: Cyclades/Plankton API image commands
147
    image compute:  Cyclades/Compute API image commands
183
    port: Networking API network commands
148 184
    history: Kamaki command history
149

  
185
    kamaki-shell: An interactive command line shell
150 186

  
151 187
.. code-block:: console
152 188
    :emphasize-lines: 1,2
......
155 191
    command group
156 192

  
157 193
    $ kamaki server -h
158
    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG]
194
    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-c CONFIG]
159 195
                               [-o OPTIONS] [--cloud CLOUD] [-h]
160 196

  
161 197
    optional arguments:
......
163 199
      -s, --silent          Do not output anything
164 200
      -V, --version         Print current version
165 201
      -d, --debug           Include debug output
166
      -i, --include         Include protocol headers in the output
167 202
      -c CONFIG, --config CONFIG
168 203
                            Path to configuration file
169 204
      -o OPTIONS, --options OPTIONS
......
174 209
    Options:
175 210
     - - - -
176 211
    info: Detailed information on a Virtual Machine
177
    rename: Set/update a virtual server name
178
    delete: Delete a virtual server
179
    console: Get a VNC console to access an existing virtual server
180
    addr: List the addresses of all network interfaces on a virtual server
181
    firewall: Manage virtual server firewall profiles for public networks
212
    modify: Modify attributes of a virtual server
182 213
    create: Create a server (aka Virtual Machine)
183
    list: List Virtual Machines accessible by user
214
    list: List virtual servers accessible by user
184 215
    reboot: Reboot a virtual server
185 216
    start: Start an existing virtual server
186 217
    shutdown: Shutdown an active virtual server
187
    stats: Get virtual server statistics
188
    metadata: Manage Server metadata (key:value pairs of server attributes)
189
    resize: Set a different flavor for an existing server
190
    wait: Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
218
    delete: Delete a virtual server
191 219

  
192 220
.. code-block:: console
193 221
    :emphasize-lines: 1,2
......
196 224
    available user options
197 225

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

  
......
207 235
      -s, --silent          Do not output anything
208 236
      -V, --version         Print current version
209 237
      -d, --debug           Include debug output
210
      -i, --include         Include raw connection data in the output
211 238
      -c CONFIG, --config CONFIG
212 239
                            Path to config file
213 240
      -o OPTIONS, --options OPTIONS
......
254 281
Using history
255 282
^^^^^^^^^^^^^
256 283

  
257
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>`_).
284
Kamaki command history is stored in '${HOME}/.kamaki.history' by default). To
285
set a custom history file path users must set the history.file config option
286
(more on config options `here <setup.html#editing-options>`_).
258 287

  
259 288
Every command is appended at the end of that file. In order to see how to use
260 289
history, use the kamaki help system:
......
264 293

  
265 294
    Example 3.2.1: Available history options
266 295

  
267

  
268 296
    $ kamaki history -h
269 297
    Options:
270 298
     - - - -
......
272 300
    run  :  Run previously executed command(s)
273 301
    show :  Show intersession command history
274 302

  
275
The following example showcases how to use history in kamaki
276

  
277
.. code-block:: console
278
    :emphasize-lines: 1
279 303

  
280 304
    Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
281
    
282 305

  
283 306
    $ kamaki history clean
284 307
    $ kamaki server list
......
297 320
"""""
298 321

  
299 322
When in debug mode, kamaki outputs some useful debug information (stack trace
300
and http logs). Kamaki in debug mode cancels suppression of warning messages.
323
and http logs). Kamaki in debug mode cancels the suppression of warning
324
messages too.
301 325

  
302 326
To run kamaki in debug mode use the -d or --debug option.
303 327

  
......
306 330
"""""""
307 331

  
308 332
Most kamaki commands are translated into http requests. Kamaki clients API
309
translated the semantics to REST and handles the response. Users who need to
310
have access to these commands can use the verbose mode that presents the HTTP
311
Request details as well as the full server response.
333
translates command semantics to REST and handles the response. Users who need
334
to have access to these commands can use the verbose mode that outputs the
335
HTTP Request and Response details along with the (possibly modified) regular
336
command output.
312 337

  
313
To run kamaki in verbose mode use the *-v/- - verbose* option
338
To run kamaki in verbose mode use the *-v/- - verbose* argument, it goes with
339
everything.
314 340

  
315 341
Verbose mode outputs the request and response mode, address and
316 342
headers as well as the size of the data block, if any. Sensitive information
317 343
(x-auth-token header and data body) are omitted by default,. Users who need
318 344
this information may enable it through the log_token and log_data configuration
319
options (see next section)
345
options
320 346

  
321
.. tip:: Use the -o runtime option to enable config options on the fly, e.g, to
322
    include http data:
347
.. tip:: Use the -o argument to include http data in the output:
323 348

  
324 349
    .. code-block:: console
325 350

  
......
329 354
Logging
330 355
"""""""
331 356

  
332
Kamaki keeps its logs in a file specified by the *log_file* option and it
333
defaults to *${HOME}/.kamaki.log*. This configuration option can be modified::
357
Kamaki logs in a file specified by the *log_file* option which defaults to
358
*${HOME}/.kamaki.log*. This configuration option can be modified::
334 359

  
335 360
    kamaki config set log_file /new/log/file/path
336 361

  
......
383 408
One-command features
384 409
^^^^^^^^^^^^^^^^^^^^
385 410

  
386
Kamaki commands can be used along with advanced shell features.
387

  
388 411
.. code-block:: console
389 412
    :emphasize-lines: 1
390 413

  
391 414
    Example 3.4.1: List the trash container contents, containing c1_
392 415
    
393

  
394
    $ kamaki file list -o cloud.default.pithos_container=trash| grep c1_
395
    c1_1370859409.0 20KB
396
    c1_1370859414.0 9MB
397
    c1_1370859409.1 110B
416
    $ kamaki file list -v -o log_token=on
417
    ...
418
    X-Auth-Token: s0m3-3x4mp1e-70k3n
419
    ...
398 420

  
399 421
The -o argument can be used to temporarily override various (set or unset)
400 422
options. In one command, all -o option sets are forgotten just after the
401 423
command has been completed, and the previous settings are restored (the
402 424
configuration file is not modified).
403 425

  
404
The file-list command in example 3.4.1 runs with an explicitly provided
405
pithos_account, which temporarily overrides the one probably provided in the
406
configuration file (it works even if the user has not set the optional
407
pithos_account config option).
426
For security reasons, all commands hide the authentication token from outputs
427
and the logs. In example 3.4.1 the token is not hided, because of the
428
*log_token=on* config option.
408 429

  
409
.. tip:: There are better ways to list the contents of a container. Example
410
    3.4.1 is using this method for demonstration purposes only. The suggested
411
    method for listing container contents is *- - container=<container>*
430
.. warning:: Complimentary output i.e., http logs and informative messages are
431
  printed to standard error stream
412 432

  
413 433
Interactive shell
414 434
-----------------
......
416 436
Command Contexts
417 437
^^^^^^^^^^^^^^^^
418 438

  
419
The kamaki interactive shell implements the notion of command contexts. Each
420
command group is also a context where the users can **enter** by typing the
421
group name. If the context switch is successful, the kamaki shell prompt
439
The command namespaces in kamaki interactive shell are called **contexts**.
440

  
441
Each command group is also a context where the users can **enter** by typing
442
the group name. If the context switch is successful, the kamaki shell prompt
422 443
changes to present the new context ("*file*" in example 4.1.1).
423 444

  
424 445
.. code-block:: console
......
458 479
    [config]: exit
459 480
    [kamaki]: file
460 481
    [file]: list
461
    ... (storage containers listing) ...
482
    ... (file listing) ...
462 483
    [file]: exit
463 484
    [kamaki]: server
464 485
    [server]: list
......
466 487
    [server]: exit
467 488
    [kamaki]:
468 489

  
469
Users have the option to avoid switching between contexts: all commands can run
470
from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent.
490
Users can avoid switching between contexts: all commands can run from the
491
**top context** e.g., examples 4.1.3 and 4.1.4 are equivalent.
471 492

  
472 493
.. code-block:: console
473 494
    :emphasize-lines: 1
474 495

  
475 496
    Example 4.1.4: Execute different "list" commands from top context
476 497

  
477

  
478 498
    [kamaki]: config list
479 499
    ... (configuration options listing) ...
480 500
    [kamaki]: file list
481
    ... (storage container listing) ...
501
    ... (file listing) ...
482 502
    [kamaki]: server list
483 503
    ... (servers listing) ...
484 504
    [kamaki]:
485 505

  
506
While in a context, other contexts are accessible by using a **/** as shown in
507
the following example:
508

  
509
.. code-block:: console
510

  
511
  Example 4.1.5: Execute different "list" commands from the config context
512

  
513
  [kamaki]: config
514
  [config]: list
515
  ... (configuration option listing) ...
516
  [config]: /file list
517
  ... (file listing) ...
518
  [config]: /server list
519
  ... (servers listing) ...
520
  [config]:
521

  
486 522
Using Help
487 523
^^^^^^^^^^
488 524

  
......
512 548

  
513 549
    Example 4.2.1: Get available commands and then get help in a context
514 550

  
515

  
516 551
    [kamaki]: help
517 552

  
518 553
    kamaki commands:
......
543 578

  
544 579
In context-level, there is a distinction between kamaki-commands and
545 580
interactive shell commands. The former are available in one-command mode and
546
are related to the cloud client setup and use, while the later are
547
context-shell functions.
581
are the main functionality of kamaki, while the later are used to manage the
582
kamaki-shell.
548 583

  
549 584
**Command-level help** prints the syntax, arguments and description of a
550 585
specific (terminal) command
......
606 641
    [file]: /config set -h
607 642
    [server]: /config set --help
608 643

  
609
.. _accessing-top-level-commands-ref:
610

  
611
Accessing top-level commands
612
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
613

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

  
618
    * access a command "anothercontext cmd1 cmd2 ... cmdN"
619
    [context]: /anothercontext cmd1 cmd2 ... cmdN
620

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

  
625
* the name of the new server
626
* the flavor id
627
* the image id
628

  
629
An average user would enter the server context and type *create -h* to check the
630
syntax of the command. In that point, it would be nice to have some easy way of
631
accessing the *flavor* and *image* contexts, to list and pick a flavor id and an
632
image id. This is achieved with the / notation, as demonstrated in the following
633
example:
634

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

  
638
    Example 4.3.1: Create a server from server context
639

  
640
    [server]: create -h
641
    create <name> <flavor id> <image id> ...
642
    ...
643
    
644
    [server]: /flavor list
645
    ...
646
    43 AFLAVOR
647
        SNF:disk_template:  drbd
648
        cpu              :  4
649
        disk             :  10
650
        ram              :  2048
651
    
652
    [server]: /image compute list
653
    1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
654
    18a82962-43eb-8f8880af89d7 (Windows 7)
655
    531aa018-9a40-a4bfe6a0caff (Windows XP)
656
    6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
657
    
658
    [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
659
    ...
660

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

  
667
.. code-block:: console
668
    :emphasize-lines: 1
669

  
670
    Example 4.3.2: Token suddenly expires. Set a new token from file context
671

  
672

  
673
    [file]: list
674
    (401) UNAUTHORIZED Access denied
675

  
676
    [file]: /user authenticate
677
    (401) UNAUTHORIZED Invalid X-Auth-Token
678

  
679
    [file]: /config get cloud.default.token
680
    my3xp1r3dt0k3n==
681

  
682
    [file]: /config set cloud.default.token myfr35ht0k3n==
683

  
684
    [file]: /config get cloud.default
685
    cloud.default.url = https://astakos.example.com/astakos/identity/2.0/
686
    cloud.default.token = myfr35ht0k3n==
687

  
688
    [file]: list
689
    1.  pithos (10MB, 2 objects)
690
    2.  trash (0B, 0 objects)
691

  
692
.. note:: The error messages on examples are shortened for clarity. Actual error
693
    messages are more helpful and descriptive.
694

  
695
The following example compares some equivalent calls that run
696
*user-authenticate* after a *file-list* 401 failure.
697

  
698
.. code-block:: console
699
    :emphasize-lines: 1,3,10,17,26
700

  
701
    Example 4.3.3: Equivalent user-authenticate calls after a file-list 401
702

  
703
    * I. without kamaki interactive shell *
704
    $ kamaki file list
705
    (401) UNAUTHORIZED Access denied
706
    $ kamaki user authenticate
707
    ...
708
    $
709

  
710
    * II. from top-level context *
711
    [kamaki]: file list
712
    (401) UNAUTHORIZED Access denied
713
    [kamaki]: user authenticate
714
    ...
715
    [kamaki]
716

  
717
    * III. maximum typing *
718
    [file]: list
719
    (401) UNAUTHORIZED Access denied
720
    [file]: exit
721
    [kamaki]: user
722
    [user]: authenticate
723
    ...
724
    [user]:
725

  
726
    * IV. minimum typing *
727
    [file]: list
728
    (401) UNAUTHORIZED Access denied
729
    [file]: /user authenticate
730
    ...
731
    [file]:
732

  
733
.. hint:: To exit kamaki shell while in a context, try */exit*
734

  
735
Using config
736
^^^^^^^^^^^^
737

  
738
The configuration mechanism of kamaki is detailed in the
739
`setup section <setup.html>`_, it is accessible as *config* and it is common for
740
both interaction modes. In specific, the configuration mechanism is implemented
741
as  `config`. Using the config commands is as straightforward as in any other
742
group of commands.
743

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

  
747
.. Note:: config updates in kamaki shell persist even after the session is over
748

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

  
754
In example 4.4.1 the user is going to work with only one storage container. The
755
file commands use the container:path syntax, but if the user sets a container
756
name as default, the container name can be omitted.
757

  
758
.. code-block:: console
759
    :emphasize-lines: 1
760

  
761
    Example 4.4.1: Set default storage container (cloud alias: default)
762

  
763

  
764
    [file]: list
765
      mycontainer (32MB, 2 objects)
766
      pithos (0B, 0 objects)
767
      trash (2MB, 1 objects)
768

  
769
    [file]: list mycontainer
770
      D mydir/
771
      20M mydir/rndm_local.file
772
    
773
    [file]: /config set cloud.default.pithos_container mycontainer
774

  
775
    [file]: list
776
      D mydir/
777
      20M mydir/rndm_local.file
778

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

  
783
.. code-block:: console
784
    :emphasize-lines: 1
785

  
786
    Example 4.4.2: Delete a setting option (cloud: default)
787

  
788

  
789
    [file]: /config delete cloud.default.pithos_container
790

  
791
    [file]: list
792
      mycontainer (32MB, 2 objects)
793
      pithos (0B, 0 objects)
794
      trash (2MB, 1 objects)
795

  
796 644
History modes
797 645
^^^^^^^^^^^^^
798 646

  
......
827 675

  
828 676
    * Download mycontainer1:myfile and upload it to mycontainer2:myfile *
829 677
    [kamaki]: file
830
    [file]: copy mycontainer1:somefile mycontainer1:myfile
831
    [file]: download mycontainer1:myfile mylocalfile
678
    [file]: copy /mycontainer1/somefile /mycontainer1/myfile
679
    [file]: download /mycontainer1/myfile mylocalfile
832 680
    ...
833 681
    Download completed
834
    [file]: upload mylocalfile mycontainer2:myfile -f
682
    [file]: upload mylocalfile /mycontainer2/myfile -f
835 683
    ...
836 684
    Upload completed
837 685

  
838 686
    * undo the process *
839 687
    [file]: !rm mylocalfile
840
    [file]: delete mycontainer1:myfile
841
    [file]: delete mycontainer2:myfile
688
    [file]: delete /mycontainer1/myfile
689
    [file]: delete /mycontainer2/myfile
842 690

  
843 691
    * check history entries *
844 692
    [file]: exit
845 693
    [kamaki]: history
846 694
    [history]: show
847 695
    1.  file
848
    2.  file copy mycontainer1:somefile mycontainer1:myfile
849
    3.  file download mycontainer1:myfile mylocalfile
850
    4.  file upload mylocalfile mycontainer2:myfile -f
851
    5.  file delete mycontainer1:myfile
852
    6.  file delete mycontainer2:myfile
696
    2.  file copy /mycontainer1/somefile /mycontainer1/myfile
697
    3.  file download /mycontainer1/myfile mylocalfile
698
    4.  file upload mylocalfile /mycontainer2/myfile -f
699
    5.  file delete /mycontainer1/myfile
700
    6.  file delete /mycontainer2/myfile
853 701
    7.  history
854 702
    8.  history show
855 703

  
856 704
    *repeat the process *
857 705
    [history]: run 2-4
858
    <file copy mycontainer1:somefile mycontainer1:myfile>
859
    <file download mycontainer1:myfile mylocalfile>
706
    <file copy /mycontainer1/somefile /mycontainer1/myfile>
707
    <file download /mycontainer1/myfile mylocalfile>
860 708
    Download completed
861
    <file upload mylocalfile mycontainer2:myfile>
709
    <file upload mylocalfile /mycontainer2/myfile>
862 710
    Upload completed
863 711

  
864
For powerfull scripting, users are advised to take advantage of their os shell
865
scripting capabilities and combine them with kamaki one-command. Still, the
866
history-run functionality might prove handy in many occasions.
712
The suggested best practice for scripting is python scripts that import the
713
`kamaki.clients` library. Another option is host shell scripting (e.g., bash)
714
with kamaki one-command. Still, the history-run functionality might prove handy
715
in many occasions.
867 716

  
868 717
OS Shell integration
869 718
^^^^^^^^^^^^^^^^^^^^
b/kamaki/cli/commands/cyclades.py
708 708

  
709 709
@command(server_cmds)
710 710
class server_addr(_init_cyclades):
711
    """DEPRECATED, use: [kamaki] server info <SERVER_ID> --nics"""
711
    """DEPRECATED, use: [kamaki] server info SERVER_ID --nics"""
712 712

  
713 713
    def main(self, *args):
714 714
        raiseCLIError('DEPRECATED since v0.12', importance=3, details=[
......
718 718

  
719 719
@command(server_cmds)
720 720
class server_console(_init_cyclades, _optional_json):
721
    """DEPRECATED, use: [kamaki] server info <SERVER_ID> --vnc-credentials"""
721
    """DEPRECATED, use: [kamaki] server info SERVER_ID --vnc-credentials"""
722 722

  
723 723
    def main(self, *args):
724 724
        raiseCLIError('DEPRECATED since v0.12', importance=3, details=[
......
727 727

  
728 728

  
729 729
@command(server_cmds)
730
class server_rename(_init_cyclades, _optional_json):
731
    """DEPRECATED, use: [kamaki] server modify SERVER_ID --name=NEW_NAME"""
732

  
733
    def main(self, *args):
734
        raiseCLIError('DEPRECATED since v0.12', importance=3, details=[
735
            'Replaced by',
736
            '  [kamaki] server info <SERVER_ID> --stats'])
737

  
738

  
739
@command(server_cmds)
730 740
class server_stats(_init_cyclades, _optional_json):
731
    """DEPRECATED, use: [kamaki] server info <SERVER_ID> --stats"""
741
    """DEPRECATED, use: [kamaki] server info SERVER_ID --stats"""
732 742

  
733 743
    def main(self, *args):
734 744
        raiseCLIError('DEPRECATED since v0.12', importance=3, details=[

Also available in: Unified diff