Statistics
| Branch: | Tag: | Revision:

root / docs / usage.rst @ 4067cdaf

History | View | Annotate | Download (19.8 kB)

1
Usage
2
=====
3

    
4
Kamaki offers command line interfaces that implement specific command specifications. A detailed list of the command specifications can be found in `Commands <commands.html>`_ section. This guide covers the generic usage of both interfaces.
5

    
6
What's more, kamaki offers a clients API that allows the developement of external applications for synnefo. The clients API is listed in the `Clients lib <clients.html>`_ section. The recomended method of utilizing this API is explained in the present.
7

    
8
Setup
9
-----
10

    
11
Kamaki interfaces rely on a list of configuration options. In the initial state, kamaki is configured to communicate with the Okenos IaaS. A detailed guide for setting up kamaki can be found in the `Setup <setup.html>`_ section.
12

    
13
Quick guide
14
^^^^^^^^^^^
15

    
16
It is essential for users to get a configuration token (to get in Okeanos.grnet.gr log `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
17

    
18
.. code-block:: console
19

    
20
    $ kamaki set token myt0k3n==
21

    
22

    
23
    Example 1.1.1: Set user token to myt0k3n==
24

    
25
To use the storage service, a user should also provide the corresponding username:
26

    
27
.. code-block:: console
28

    
29
    $ kamaki set account user@domain.com
30

    
31

    
32
    Example 1.1.2: Set user name to user@domain.com
33

    
34
Command line interfaces
35
-----------------------
36
Kamaki users can access synnefo services through either the interactive shell or the one-command behaviors. In practice, both systems relly on the same command set implementations and API clients, with identical responses and error messages. Still, there are some differenses.
37

    
38
Shell vs one-command
39
^^^^^^^^^^^^^^^^^^^^
40
In favor of interactive shell behavior:
41

    
42
* tab completion for commands
43
* session history with "up"/"down" keys
44
* shorter commants with command namespace switching
45

    
46
In favor of one-command behavior:
47

    
48
* can be used along with advanced shell features (pipelines, redirection, etc.)
49
* can be used in shell scripts
50
* prints debug and verbose messages if needed
51

    
52
Run as shell
53
""""""""""""
54
To use kamaki as a shell, run:
55

    
56
* without any parameters or arguments
57

    
58
.. code-block:: console
59

    
60
    $ kamaki
61

    
62

    
63
    Example 2.2.1: Running kamaki shell
64

    
65

    
66
* with any kind of '-' prefixed arguments, except '-h', '--help'.
67

    
68
.. code-block:: console
69

    
70
    $ kamaki --config myconfig.file
71

    
72
   
73
    Example 2.2.2: Running kamaki shell with custom configuration file
74

    
75

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

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

    
82
.. code-block:: console
83

    
84
    $kamaki -h
85

    
86

    
87
    Example 2.3.1: Kamaki help
88

    
89
* with one or more command parameters:
90

    
91
.. code-block:: console
92

    
93
    $ kamaki server list
94

    
95

    
96
    Example 2.3.2: List VMs managed by user
97

    
98
Commands
99
^^^^^^^^
100

    
101
Client commands are grouped by service (see example 3.1.1 on how to list available groups). Commands behavior is as uniform as possible, but there are still differences between groups due to the special nature of each service and server-side implementation.
102

    
103
Typically, commands consist of a group name (e.g. store for storage commands) one or more terms (e.g. list for listing) and the command specific parameters (e.g. the name of the container), if any.
104

    
105
.. code-block:: console
106

    
107
    $ kamaki store list mycontainer
108

    
109

    
110
    Example 3.1.1: List stored files in container mycontainer.
111

    
112
Example 2.3.2 showcases a command without parameters (the group is "server", the command is "list").
113

    
114
The "server" command group is also refered in the following example.
115

    
116
.. code-block:: console
117

    
118
    $ kamaki server info 42
119

    
120

    
121
    Example 3.1.2 Show information about a user-managed VM with id 42
122

    
123
Client commands can feature an arbitarry number of terms:
124

    
125
.. code-block:: text
126

    
127
    kamaki <group> <cmd term 1> <cmd term 2> ... <cmd term N> [arguments]
128

    
129
Although there are no multi-termed client commands until version 0.6.1 , the feature is supported and might be used in feature extentions.
130

    
131
The following pattern applies to all client commands up to version 0.6.1:
132

    
133
.. code-block:: text
134

    
135
    kamaki <group> <command> [arguments]
136

    
137
The commands supported in version 0.6.1 are described bellow, grouped by service. The examples showcase a sample set of group commands. The kamaki interactive shell has been chosen as the execution enviroment:
138

    
139
astakos (Identity Manager)
140
""""""""""""""""""""""""""
141

    
142
.. code-block:: text
143

    
144
    authenticate:  Authenticate a user
145

    
146
Showcase: get user information, provided the token was set
147

    
148
.. code-block:: console
149
    :emphasize-lines: 3-11
150

    
151
    [kamaki]:astakos
152
    [astakos]:authenticate
153
    auth_token        :  s0m3t0k3nth@t1sr3m0v3d==
154
    auth_token_created:  2012-11-13T14:12:40.917034
155
    auth_token_expires:  2012-12-13T14:12:40.917035
156
    groups            : 
157
                      default
158
    has_credits       :  False
159
    has_signed_terms  :  True
160
    uniq              :  myaccount@grnet.gr
161
    username          :  4215th3b357num9323v32
162
    [astakos]:
163

    
164
flavor (Compute/Cyclades)
165
"""""""""""""""""""""""""
166

    
167
.. code-block:: text
168

    
169
    info:  Get flavor details
170
    list:  List flavors
171

    
172
Showcase: show details for flavor with id 43
173

    
174
.. code-block:: console
175
    :emphasize-lines: 3-8
176

    
177
    [kamaki]: flavor
178
    [flavor]: info 43
179
    SNF:disk_template:  drbd
180
    cpu              :  4
181
    disk             :  10
182
    id               :  43
183
    name             :  C4R2048D10
184
    ram              :  2048
185
    [flavor]:
186

    
187
image (Compute/Cyclades + Glance)
188
""""""""""""""""""""""""""""""""""
189

    
190
.. code-block:: text
191

    
192
    addmember  :  Add a member to an image
193
    addproperty:  Add an image property
194
    delete     :  Delete image
195
    delmember  :  Remove a member from an image
196
    delproperty:  Delete an image property
197
    info       :  Get image details
198
    list       :  List images
199
    members    :  Get image members
200
    meta       :  Get image metadata
201
    properties :  Get image properties
202
    public     :  List public images
203
    register   :  (Re)Register an image
204
    setmembers :  Set the members of an image
205
    setproperty:  Update an image property
206
    shared     :  List shared images
207

    
208
Showcase: show a list of public images, list the properties of Debian Base
209

    
210
.. code-block:: console
211
    :emphasize-lines: 3-13,15-22
212

    
213
    [kamaki]:image
214
    [image]:list
215
    1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS (Long Term Support))
216
    1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
217
    18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS (Long Term Support))
218
    6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
219
    6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
220
    78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
221
    86bc2414-0fb3-4898-a637-240292243302 (Fedora)
222
    926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
223
    b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
224
    baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
225
    c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
226
    [image]:properties b2dffe52-64a4-48c3-8a4c-8214cc3165cf
227
    description   :  Debian 6.0.6 (Squeeze) Base System
228
    gui           :  No GUI
229
    kernel        :  2.6.32
230
    os            :  debian
231
    osfamily      :  linux
232
    root_partition:  1
233
    sortorder     :  1
234
    users         :  root
235
    [image]:
236

    
237
server (Compute/Cyclades)
238
"""""""""""""""""""""""""
239

    
240
.. code-block:: text
241

    
242
    addmeta :  Add server metadata
243
    addr    :  List a server's nic address
244
    console :  Get a VNC console
245
    create  :  Create a server
246
    delete  :  Delete a server
247
    delmeta :  Delete server metadata
248
    firewall:  Set the server's firewall profile
249
    info    :  Get server details
250
    list    :  List servers
251
    meta    :  Get a server's metadata
252
    reboot  :  Reboot a server
253
    rename  :  Update a server's name
254
    setmeta :  Update server's metadata
255
    shutdown:  Shutdown a server
256
    start   :  Start a server
257
    stats   :  Get server statistics
258
    wait    :  Wait for server to finish
259

    
260
Showcase: Create a server: Show create help, find a flavor and an image make a server. Wait for server to be build, get server details. Note that the progress bar feature is optional (see )
261

    
262
.. code-block:: console
263
    :emphasize-lines: 3-16,18-33,35-40,42-56,58,59,61-66
264

    
265
    [kamaki]:server
266
    [server]:create -h
267
    usage: create <name> <flavor id> <image id>
268
            [--personality PERSONALITY] [-h] [--config CONFIG]
269

    
270
    Create a server
271

    
272
    optional arguments:
273
      -v, --verbose         More info at response
274
      --personality PERSONALITY
275
                            add a personality file
276
      -d, --debug           Include debug output
277
      -h, --help            Show help message
278
      -i, --include         Include protocol headers in the output
279
      --config CONFIG       Path to configuration file
280
      -s, --silent          Do not output anything
281
    [server]:/image list
282
    1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)
283
    1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
284
    |18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)
285
    |6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
286
    |6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
287
    |78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
288
    |86bc2414-0fb3-4898-a637-240292243302 (Fedora)
289
    |926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
290
    |b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
291
    |baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
292
    |c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
293
    [server]:/flavor info 1
294
    SNF:disk_template:  drbd
295
    cpu              :  1
296
    disk             :  20
297
    id               :  1
298
    name             :  C1R1024D20
299
    ram              :  1024
300
    [server]:create 'My Small Debian Server' 1 b2dffe52-64a4-48c3-8a4c-8214cc3165cf
301
    adminPass:  L8gu2wbZ94
302
    created  :  2012-11-23T16:56:04.190813+00:00
303
    flavorRef:  1
304
    hostId   :  
305
    id       :  11687
306
    imageRef :  b2dffe52-64a4-48c3-8a4c-8214cc3165cf
307
    metadata : 
308
             values: 
309
                   os   :  debian
310
                   users:  root
311
    name     :  My Small Debian Server
312
    progress :  0
313
    status   :  BUILD
314
    suspended:  False
315
    updated  :  2012-11-23T16:56:04.761962+00:00
316
    [server]:wait 11687
317
    Server 11687 still in BUILD mode |||||||||||||||||    | 80% - 3s
318
    Server 11687 is now in ACTIVE mode
319
    [server]:
320

    
321
network (Compute/Cyclades)
322
""""""""""""""""""""""""""
323

    
324
.. code-block:: text
325

    
326
    connect   :  Connect a server to a network
327
    create    :  Create a network
328
    delete    :  Delete a network
329
    disconnect:  Disconnect a nic of a server to a network
330
    info      :  Get network details
331
    list      :  List networks
332
    rename    :  Update network name
333

    
334
Showcase: Connect a network to a VM: create a network, list available VMs, connect to 'My Small Debian Server', check network info and server connectivity.
335

    
336
.. code-block:: console
337
    :emphasize-lines: 1, 2, 5, 14, 15, 30, 42
338

    
339
    [kamaki]:network
340
    [network]:/server list
341
    11687 (My Small Debian Server)
342
    11688 (An Ubuntu server)
343
    [network]:connect 
344
    Connect a server to a network
345
    Syntax: connect  <server id> <network id>
346
      --config    :  Path to configuration file
347
      -d,--debug  :  Include debug output
348
      -h,--help   :  Show help message
349
      -i,--include:  Include protocol headers in the output
350
      -s,--silent :  Do not output anything
351
      -v,--verbose:  More info at response
352
    [network]: connect 11687 1409
353
    [network]:info 1409
354
      attachments: 
355
                 nic-11687-1
356
      cidr       :  192.168.1.0/24
357
      cidr6      :  None
358
      created    :  2012-11-23T17:17:20.560098+00:00
359
      dhcp       :  True
360
      gateway    :  None
361
      gateway6   :  None
362
      id         :  1409
363
      name       :  my network
364
      public     :  False
365
      status     :  ACTIVE
366
      type       :  PRIVATE_MAC_FILTERED
367
      updated    :  2012-11-23T17:18:25.095225+00:00
368
    [network]:/server addr 11687
369
    id:  nic-11687-1
370
        ipv4       :  192.168.1.1
371
        ipv6       :  None
372
        mac_address:  aa:0f:c2:0b:0e:85
373
        network_id :  1409
374
        firewallProfile:  DISABLED
375
    id:  nic-11687-0
376
        ipv4           :  83.212.106.111
377
        ipv6           :  2001:648:2ffc:1116:a80c:f2ff:fe12:a9e
378
        mac_address    :  aa:0c:f2:12:0a:9e
379
        network_id     :  1369
380
    [network]:
381

    
382

    
383

    
384
store (Storage/Pithos+)
385
"""""""""""""""""""""""
386

    
387
.. code-block:: text
388

    
389
    append        :  Append local file to remote
390
    cat           :  Print a file to console
391
    copy          :  Copy an object
392
    create        :  Create a container or a directory object
393
    delete        :  Delete a container [or an object]
394
    delgroup      :  Delete a user group on an account
395
    delmeta       :  Delete an existing metadatum of account [, container [or object]]
396
    delpermissions:  Delete all sharing permissions
397
    download      :  Download a file
398
    group         :  Get user groups details for account
399
    hashmap       :  Get the hashmap of an object
400
    info          :  Get information for account [, container [or object]]
401
    list          :  List containers, object trees or objects in a directory
402
    manifest      :  Create a remote file with uploaded parts by manifestation
403
    meta          :  Get custom meta-content for account [, container [or object]]
404
    mkdir         :  Create a directory
405
    move          :  Copy an object
406
    overwrite     :  Overwrite part (from start to end) of a remote file
407
    permissions   :  Get object read/write permissions
408
    publish       :  Publish an object
409
    purge         :  Purge a container
410
    quota         :  Get  quota for account [or container]
411
    setgroup      :  Create/update a new user group on account
412
    setmeta       :  Set a new metadatum for account [, container [or object]]
413
    setpermissions:  Set sharing permissions
414
    setquota      :  Set new quota (in KB) for account [or container]
415
    setversioning :  Set new versioning (auto, none) for account [or container]
416
    sharers       :  List the accounts that share objects with default account
417
    truncate      :  Truncate remote file up to a size
418
    unpublish     :  Unpublish an object
419
    upload        :  Upload a file
420
    versioning    :  Get  versioning for account [or container ]
421
    versions      :  Get the version list of an object
422

    
423
One-command interface
424
^^^^^^^^^^^^^^^^^^^^^
425

    
426
Kamaki usage as a one-command tool is detailed in this section
427

    
428
Using help
429
""""""""""
430

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

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

    
435
.. code-block:: console
436

    
437
    $ kamaki -h
438
    usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd> [-v] [-s] [-V] [-d] [-i]
439
                                                     [--config CONFIG]
440
                                                     [-o OPTIONS] [-h]
441

    
442
    optional arguments:
443
      -v, --verbose         More info at response
444
      -s, --silent          Do not output anything
445
      -V, --version         Print current version
446
      -d, --debug           Include debug output
447
      -i, --include         Include protocol headers in the output
448
      --config CONFIG       Path to configuration file
449
      -o OPTIONS, --options OPTIONS
450
                            Override a config value
451
      -h, --help            Show help message
452

    
453
    Options:
454
     - - - -
455
    astakos:  Astakos API commands
456
    config :  Configuration commands
457
    flavor :  Compute/Cyclades API flavor commands
458
    history:  Command history
459
    image  :  Compute/Cyclades or Glance API image commands
460
    network:  Compute/Cyclades API network commands
461
    server :  Compute/Cyclades API server commands
462
    store  :  Pithos+ storage commands
463

    
464

    
465
    Example 4.1.1: kamaki help shows available parameters and command groups
466

    
467
.. code-block:: console
468

    
469
    $ kamaki cyclades -h
470
    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
471
                               [-o OPTIONS] [-h]
472

    
473
    optional arguments:
474
      -v, --verbose         More info at response
475
      -s, --silent          Do not output anything
476
      -V, --version         Print current version
477
      -d, --debug           Include debug output
478
      -i, --include         Include protocol headers in the output
479
      --config CONFIG       Path to configuration file
480
      -o OPTIONS, --options OPTIONS
481
                            Override a config value
482
      -h, --help            Show help message
483

    
484
    Options:
485
     - - - -
486
    addmeta :  Add server metadata
487
    addr    :  List a server's nic address
488
    console :  Get a VNC console
489
    create  :  Create a server
490
    delete  :  Delete a server
491
    delmeta :  Delete server metadata
492
    firewall:  Set the server's firewall profile
493
    info    :  Get server details
494
    list    :  List servers
495
    meta    :  Get a server's metadata
496
    reboot  :  Reboot a server
497
    rename  :  Update a server's name
498
    setmeta :  Update server's metadata
499
    shutdown:  Shutdown a server
500
    start   :  Start a server
501
    stats   :  Get server statistics
502
    wait    :  Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
503

    
504

    
505
    Example 4.1.2: Cyclades help contains all first-level commands of cyclades command group
506

    
507
.. code-block:: console
508

    
509
    $ kamaki server list -h
510
    usage: kamaki server list  [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
511
                               [-o OPTIONS] [-h] [-l]
512

    
513
    List servers
514

    
515
    optional arguments:
516
      -v, --verbose         More info at response
517
      -s, --silent          Do not output anything
518
      -V, --version         Print current version
519
      -d, --debug           Include debug output
520
      -i, --include         Include protocol headers in the output
521
      --config CONFIG       Path to configuration file
522
      -o OPTIONS, --options OPTIONS
523
                            Override a config value
524
      -h, --help            Show help message
525
      -l                    show detailed output
526

    
527

    
528
      Example 4.1.3: Help for command "server list" with syntax, description and avaiable user options
529

    
530
Using history
531
"""""""""""""
532

    
533
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>`_).
534

    
535
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:
536

    
537
.. code-block:: console
538

    
539
    $ kamaki history -h
540
    ...
541
    clean:  Clean up history
542
    show :  Show history
543

    
544

    
545
    Example 4.2.1: Available history options
546

    
547
The following example showcases how to use history in kamaki
548

    
549
.. code-block:: console
550

    
551
    $ kamaki history clean --match clean
552
    $ kamaki server list
553
    ...
554
    $ kamaki history show
555
    1.  kamaki server list
556
    2.  kamaki history show
557
    $ kamaki history show --match server
558
    1. kamaki server list
559
    3. kamaki history show --match server
560

    
561

    
562
    Example 4.2.2: Clean up everything, run a kamaki command, show full and filtered history
563

    
564
Debug
565
"""""
566

    
567
In case of errors, kamaki in debug mode shows usefull debug information, like the stack trace, instead of a user-friendly error message. Kamaki also suppresses various warning messages that are also allowed in debug mode.
568

    
569
To run kamaki in debug mode use the -d or --debug option
570

    
571
Verbose
572
"""""""
573

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

    
576
To run kamaki in verbose mode use the -v or --verbose option
577

    
578
Client commands
579
"""""""""""""""
580

    
581

    
582
Kamaki commands can be used along with advanced shell features.
583

    
584
.. code-block:: console
585

    
586
    $ kamaki server list -l > vmlist.txt
587

    
588

    
589
    Example 4.4.1: Store a vm list in file vmlist.txt in a unix shell
590

    
591
Interactive shell
592
^^^^^^^^^^^^^^^^^
593

    
594

    
595

    
596
Creating applications over the Clients API
597
------------------------------------------