Revision c4f606c0 docs/commands.rst

b/docs/commands.rst
1 1
List of commands
2 2
================
3 3

  
4
The commands described bellow are grouped by service. The examples showcase a
5
sample set of group commands. The kamaki interactive shell (check
4
Kamaki commands follow this scheme::
5

  
6
    [kamaki] <object> <action> [identifiers] [non-positional arguments]
7

  
8
In this context, objects are not services, but virtual objects like a server, a
9
file or an image. The action concerns objects of the specified type. Some
10
actions (e.g. "delete" or "info") need to operate on an existing object. The
11
identifiers strictly identify this object and they can have the form of an id 
12
(e.g., `server delete <SERVER_ID>`) or a foreign key (e.g., 
13
`port create <NETWORK_ID> <DEVICE_ID>`)
14

  
15
The examples bellow showcase some commands. The kamaki-shell (check
6 16
`Usage section <usage.html#interactive-shell>`_ for details) is chosen as the
7 17
execution environment.
8 18

  
9 19

  
10
user (Identity Manager)
20
user (Identity/Astakos)
11 21
-----------------------
12 22

  
13 23
.. code-block:: text
14 24

  
15
    authenticate:  Authenticate a user
25
    info          Get info for (current) session user
26
    uuid2name     Get user name(s) from uuid(s)
27
    authenticate  Authenticate a user and get all authentication information
28
    list          List (cached) session users
29
    add           Authenticate user by token and add to kamaki session (cache)
30
    name2uuid     Get user uuid(s) from name(s)
31
    select        Select user from the (cached) list as current session user
32
    delete        Delete user (token) from the (cached) list of session users
16 33

  
17 34
Showcase: get user information
18 35
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
19 36

  
20
In the following, the token has been set in a previous step (see
37
In the following, cloud URL and TOKEN were set in a previous step (see
21 38
`setup section <setup.html>`_ or the
22 39
`quick setup guide <usage.html#quick-setup>`_)
23 40

  
......
28 45
    [kamaki]: user
29 46

  
30 47
    * Authenticate user *
31
    [user]: authenticate
48
    [user]: info
32 49
    ...
33
    user:
34
        name:  My Real Name
35
        uuid:  ab1cde23-45fg-6h7i-8j9k-10l1m11no2pq
50
    name:  My Real Name
51
    id:  ab1cde23-45fg-6h7i-8j9k-10l1m11no2pq
52

  
53
    [user]: exit
54
    [kamaki]:
55

  
56
project (Astakos)
57
-----------------
58

  
59
.. code-block:: text
60

  
61
    info          Get details for a project
62
    unsuspend     Resume a suspended project (special privileges needed)
63
    suspend       Suspend a project (special privileges needed)
64
    list          List all projects
65
    create        Apply for a new project
66
    modify        Modify a project
67
    terminate     Terminate a project (special privileges needed)
68
    application   Application management commands
69
    membership    Project membership management commands
70
    reinstate     Reinstate a terminated project (special privileges needed)
71

  
72
quota (Account/Astakos)
73
-----------------------
74

  
75
.. code-block:: text
36 76

  
37
.. note:: actual call returns a full list of service endpoints accessible to
38
    the user with a specific token
77
    list          Get user quotas
78
    info          Get quota for a service (cyclades, pithos, astakos)
79

  
80
resource (Astakos)
81
------------------
82

  
83
.. code-block:: text
84

  
85
    list          List user resources
39 86

  
40 87
flavor (Compute/Cyclades)
41 88
-------------------------
......
57 104
    * Get details about flavor with id 43 *
58 105
    [flavor]: info 43
59 106
    SNF:disk_template:  drbd
60
    cpu :  4
107
    cpu:  4
61 108
    disk:  10
62
    id  :  43
109
    id:  43
63 110
    name:  C4R2048D10
64
    ram :  2048
111
    ram:  2048
65 112

  
66
image (Plankton commands + Compute Image subcommands)
67
-----------------------------------------------------
113
image (Image/Plankton)
114
----------------------
68 115

  
69 116
.. code-block:: text
70 117

  
71
    list      :  List images accessible by user
72
    info      :  Get image metadata
73
    meta      :  Manage image metadata
74
        set     :   Add / update metadata and properties for an image
75
        delete  :   Remove/empty image metadata and/or custom properties
76
    register  :  (Re)Register an image
77
    unregister:  Unregister an image (does not delete the image file)
78
    shared    :  List shared images
79
    compute   :  Compute Image API commands
80
        list      :  List images
81
        delete    :  Delete image
82
        info      :  Get image details
83
        properties:  Manage properties related to OS installation in an image
84
            delete:  Delete a property from an image
85
            get   :  Get an image property
86
            list  :  List all image properties
87
            set   :  Add / update a set of properties for an image
88
    members   :  Manage members (users who can modify an image)
89
        add   :  Add a member to an image
90
        delete:  Remove a member from an image
91
        list  :  List members of an image
92
        set   :  Set the members of an image
118
    info          Get image metadata
119
    list          List images accessible by user
120
    register      (Re)Register an image file to an Image service
121
    modify        Add / update metadata and properties for an image
122
    unregister    Unregister an image (does not delete the image file)
93 123

  
94 124
Showcase: Pick an image and list the properties
95 125
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
104 134
    [image]: list
105 135
    926ab1c5-2d85-49d4-aebe-0fce712789b9 Windows Server 2008
106 136
     container_format:  bare
107
     disk_format     :  diskdump
108
     id              :  926ab1c5-2d85-49d4-aebe-0fce712789b9
109
     size            :  11917066240
110
     status          :  available
137
     disk_format:  diskdump
138
     id:  926ab1c5-2d85-49d4-aebe-0fce712789b9
139
     size:  11917066240
140
     status:  available
111 141
    78262ee7-949e-4d70-af3a-85360c3de57a Windows Server 2012
112 142
     container_format:  bare
113
     disk_format     :  diskdump
114
     id              :  78262ee7-949e-4d70-af3a-85360c3de57a
115
     size            :  11697913856
116
     status          :  available
143
     disk_format:  diskdump
144
     id:  78262ee7-949e-4d70-af3a-85360c3de57a
145
     size:  11697913856
146
     status:  available
117 147
    5ed5a29b-292c-4fe0-b32c-2e2b65628635 ubuntu
118 148
     container_format:  bare
119
     disk_format     :  diskdump
120
     id              :  5ed5a29b-292c-4fe0-b32c-2e2b65628635
121
     size            :  2578100224
122
     status          :  available
149
     disk_format:  diskdump
150
     id:  5ed5a29b-292c-4fe0-b32c-2e2b65628635
151
     size:  2578100224
152
     status:  available
123 153
    1f8454f0-8e3e-4b6c-ab8e-5236b728dffe Debian_Wheezy_Base
124 154
     container_format:  bare
125
     disk_format     :  diskdump
126
     id              :  1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
127
     size            :  795107328
128
     status          :  available
129

  
130
    * Get properties of image with id 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe *
131
    [image]: compute properties 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
132
    description   :  Debian 6.0.6 (Squeeze) Base System
133
    gui           :  No GUI
134
    kernel        :  2.6.32
135
    os            :  debian
136
    osfamily      :  linux
137
    root_partition:  1
138
    sortorder     :  1
139
    users         :  root
155
     disk_format:  diskdump
156
     id:  1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
157
     size:  795107328
158
     status:  available
159

  
160
    * Get details for image with id 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe *
161
    [image]: info 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
162
     name: Debian_Wheezy_Base
163
     container_format:  bare
164
     disk_format:  diskdump
165
     id:  1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
166
     size:  795107328
167
     status:  available
168
     owner:  s0m3-u53r-1d (user@example.com)
169
        DESCRIPTION:  Debian Wheezy Base (Stable)
170
        GUI:  No GUI
171
        KERNEL:  2.6.32
172
        OS:  debian
173
        OSFAMILY:  linux
174
        ROOT_PARTITION:  1
175
        SORTORDER:  1
176
        USERS:  root
177

  
178
imagecompute (Compute/Cyclades)
179
-------------------------------
180

  
181
.. code-block:: text
182

  
183
    info      Get detailed information on an image
184
    list      List images
185
    modify    Modify image properties (metadata)
186
    delete    Delete an image (WARNING: image file is also removed)
140 187

  
141 188
server (Compute/Cyclades)
142 189
-------------------------
143 190

  
144 191
.. code-block:: text
145 192

  
146
    addr    :  List a server nic address
147
    console :  Get a VNC console
148
    create  :  Create a server
149
    delete  :  Delete a server
150
    firewall:  Manage server firewall profile
151
        set :  Set the server firewall profile
152
        get :  Get the server firewall profile
153
    ip      :  Manage floating IPs for the servers
154
        attach:  Attach a floating ip to a server with server_id
155
        info  :  A floating IP details
156
        detach:  Detach floating ip from server
157
        list  :  List all floating ips
158
        create:  Create a new floating IP
159
        delete:  Delete a floating ip
160
        pools :  List all floating pools of floating ips
161
    info    :  Get server details
162
    list    :  List servers
163
    metadata:  Manage Server Metadata
164
        list  :  List server metadata
165
        set   :  Add / update server metadata
166
        delete:  Delete a piece of server metadata
167
    reboot  :  Reboot a server
168
    rename  :  Update a server name
169
    shutdown:  Shutdown a server
170
    start   :  Start a server
171
    stats   :  Get server statistics
172
    resize  :  Set a different flavor for an existing server
173
    wait    :  Wait for server to finish
193
    info      Detailed information on a Virtual Machine
194
    modify    Modify attributes of a virtual server
195
    create    Create a server (aka Virtual Machine)
196
    list      List virtual servers accessible by user
197
    reboot    Reboot a virtual server
198
    start     Start an existing virtual server
199
    shutdown  Shutdown an active virtual server
200
    delete    Delete a virtual server
201
    wait      Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
174 202

  
175 203
Showcase: Create a server
176 204
^^^^^^^^^^^^^^^^^^^^^^^^^
......
178 206
.. code-block:: console
179 207
    :emphasize-lines: 1,4,21,35,44,62
180 208

  
181
    * Enter server context *
182 209
    [kamaki]: server
183 210

  
184
    * See server-create help *
185 211
    [server]: create -h
186
    usage: create <name> <flavor id> <image id>
212
    usage: create --name NAME --flavor-id FLAVOR_ID --image-id IMAGE_ID
187 213
            [--personality PERSONALITY] [-h] [--config CONFIG] [--cloud CLOUD]
188 214

  
189 215
    Create a server
......
223 249
    ram              :  1024
224 250

  
225 251
    * Create a debian server named 'My Small Debian Server'
226
    [server]: create 'My Small Debian Server' 1 b2dffe52-64a4-48c3-8a4c-8214cc3165cf
252
    [server]: create --name='My Small Debian Server' --flavor-id=1 --image-id=b2dffe52-64a4-48c3-8a4c-8214cc3165cf
227 253
    adminPass:  L8gu2wbZ94
228 254
    created  :  2012-11-23T16:56:04.190813+00:00
229 255
    flavorRef:  1
......
244 270
    Server 11687 still in BUILD mode |||||||||||||||||    | 80%
245 271
    Server 11687 is now in ACTIVE mode
246 272

  
247
.. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
273
.. Note:: In kamaki shell, / is used to access commands from top-level
248 274

  
249

  
250
ip (Compute/Cyclades)
275
ip (Network/Cyclades)
251 276
---------------------
252 277

  
253 278
.. code-block:: text
254 279

  
255
    info:    Details for an IP
256
    list:    List reserved floating IPs
257
    attach:  Attach a floating IP to a server
258
    pools:   List pools of floating IPs
259
    release: Release a floating IP
260
    detach:  Detach a floating IP from a server
261
    reserve: Reserve a floating IP
280
    info      Get details on a floating IP
281
    create    Reserve an IP on a network
282
    list      List reserved floating IPs
283
    delete    Unreserve an IP (also delete the port, if attached)
284

  
285
port (Network/Cyclades)
286
-----------------------
287

  
288
.. code-block:: text
289

  
290
    info      Get details about a port
291
    list      List all ports
292
    create    Create a new port (== connect server to network)
293
    modify    Modify the attributes of a port
294
    delete    Delete a port (== disconnect server from network)
295
    wait      Wait for port to finish [ACTIVE, DOWN, BUILD, ERROR]
262 296

  
263 297
Showcase: Reserve and attach IP to server
264
-----------------------------------------
298
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
265 299

  
266 300
.. code-block:: text
267 301

  
268
    * Enter IP context *
269
    [kamaki]: ip
302
    * Enter port context *
303
    [kamaki]: port
270 304

  
271
    * Reserve an IP and see servers *
272
    [kamaki]: reserve
305
    * Reserve an IP and see servers and networks*
306
    [port]: /ip create
273 307
    123.456.78.9
274
    [kamaki]: /server list
308
    [port]: /server list
275 309
    42   My Windows Server
276 310
    43   My Linux Server
311
    [port]: /network list
312
    101  My Network 1
313
    102  My Network 2
277 314

  
278 315
    * Attach IP to server
279
    [kamaki]: attach 43 123.456.78.9
316
    [port]: port create --device-id=43 --network-id=101 --ip-address=123.456.78.9 --wait
317
    Creating new port 7 between server 43 and network 101
318
    Port 7 still in BUILD mode |||||||||||||||||    | 80%
319
    Port 7 is now in ACTIVE mode
280 320

  
281 321
.. Note:: In kamaki shell, / is used to access top-level command groups while
282 322
    working in command group contexts
......
286 326

  
287 327
.. code-block:: text
288 328

  
289
    connect   :  Connect a server to a network
290
    create    :  Create a network
291
    delete    :  Delete a network
292
    disconnect:  Disconnect a nic of a server to a network
293
    info      :  Get network details
294
    list      :  List networks
295
    rename    :  Update network name
329
    info        Get details about a network
330
    disconnect  Disconnect a network from a device
331
    modify      Modify network attributes
332
    create      Create a new network
333
    list        List networks
334
    connect     Connect a network with a device (server or router)
335
    delete      Delete a network
296 336

  
297 337
Showcase: Connect a network to a VM
298 338
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
311 351
    * Try network-connect (to get help) *
312 352
    [network]: connect 
313 353
    Syntax error
314
    usage: connect <server id> <network id> [-s] [-h] [-i] [--config CONFIG]
354
    usage: connect <network id> <device id> [-s] [-h] [-i] [--config CONFIG]
315 355

  
316 356
    Connect a server to a network
317 357

  
......
324 364
      -v,--verbose:  More info at response
325 365

  
326 366
    * Connect VM with id 11687 to network with id 1409
327
    [network]: connect 11687 1409
367
    [network]: connect 11687 1409 --wait
368
    Creating port between network 1409 and server 11687
369
    New port: 8
328 370

  
329 371
    * Get details on network with id 1409
330 372
    [network]: info 1409
331
      attachments: 
332
                 nic-11687-1
373
      attachments:
374
                8
333 375
      cidr    :  192.168.1.0/24
334 376
      cidr6   :  None
335 377
      created :  2012-11-23T17:17:20.560098+00:00
......
344 386
      updated :  2012-11-23T17:18:25.095225+00:00
345 387

  
346 388
    * Get connectivity details on VM with id 11687 *
347
    [network]: /server addr 11687
348
    id:  nic-11687-1
389
    [network]: /server info 11687 --nics 
390
    nic-11687-1
349 391
        ipv4       :  192.168.1.1
350 392
        ipv6       :  None
351 393
        mac_address:  aa:0f:c2:0b:0e:85
352 394
        network_id :  1409
353 395
        firewallProfile:  DISABLED
354
    id:  nic-11687-0
396
    nic-11687-0
355 397
        ipv4           :  83.212.106.111
356 398
        ipv6           :  2001:648:2ffc:1116:a80c:f2ff:fe12:a9e
357 399
        mac_address    :  aa:0c:f2:12:0a:9e
......
359 401

  
360 402
.. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
361 403

  
404
container (Storage/Pithos+)
405
---------------------------
406

  
407
    info      Get information about a container
408
    modify    Modify the properties of a container
409
    create    Create a new container
410
    list      List all containers, or their contents
411
    empty     Empty a container
412
    delete    Delete a container
413

  
414
group (Storage/Pithos+)
415
-----------------------
416

  
417
    create    Create a group of users
418
    list      List all groups and group members
419
    delete    Delete a user group
420

  
421
sharer (Storage/Pithos+)
422
------------------------
423

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

  
362 427
file (Storage/Pithos+)
363 428
----------------------
364 429

  
365 430
.. code-block:: text
366 431

  
367
    append        :  Append local file to remote
368
    cat           :  Print a file to console
369
    copy          :  Copy an object
370
    containerlimit:  Container size limit commands
371
        set       :  Set container data limit
372
        get       :  Get container data limit
373
    create        :  Create a container
374
    delete        :  Delete a container [or an object]
375
    download      :  Download a file or directory
376
    group         :  Manage access groups and group members
377
        delete:  Delete a user group
378
        list  :  List groups and group members
379
        set   :  Set a user group
380
    hashmap       :  Get the hashmap of an object
381
    info          :  Get information for account [, container [or object]]
382
    list          :  List containers, object trees or objects in a directory
383
    manifest      :  Create a remote file with uploaded parts by manifestation
384
    metadata      :  Metadata are attached on objects (key:value pairs)
385
        delete:  Delete metadata with given key
386
        get   :  Get metadatum
387
        set   :  Set a piece of metadata
388
    mkdir         :  Create a directory
389
    move          :  Copy an object
390
    overwrite     :  Overwrite part (from start to end) of a remote file
391
    permissions   :  Manage user and group accessibility for objects
392
        delete:  Delete all permissions set on object
393
        get   :  Get read and write permissions of an object
394
        set   :  Set permissions for an object
395
    publish       :  Publish an object
396
    purge         :  Purge a container
397
    quota         :  Get  quota for account
398
    sharers       :  List the accounts that share objects with default account
399
    touch         :  Create an empty object (file)
400
    truncate      :  Truncate remote file up to a size
401
    unpublish     :  Unpublish an object
402
    upload        :  Upload a file or directory
403
    versioning    :  Manage the versioning scheme of current pithos user account
404
        get:  Get  versioning for account or container
405
        set:  Set versioning mode (auto, none) for account or container
406
    versions      :  Get the version list of an object
432
    info      Get information/details about a file
433
    truncate  Truncate remote file up to size
434
    mkdir     Create a directory
435
    create    Create an empty file
436
    move      Move objects, even between different accounts or containers
437
    list      List all objects in a container or a directory object
438
    upload    Upload a file
439
    cat       Fetch remote file contents
440
    modify    Modify the attributes of a file or directory object
441
    append    Append local file to (existing) remote object
442
    download  Download a remove file or directory object to local file system
443
    copy      Copy objects, even between different accounts or containers
444
    overwrite Overwrite part of a remote file
445
    delete    Delete a file or directory object
407 446

  
408 447
Showcase: Upload and download a file
409 448
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
427 466

  
428 467

  
429 468
    * Create two containers *
430
    [file]: create mycont1
431
    [file]: create mycont2
469
    [file]: /container create mycont1
470
    [file]: /container create mycont2
432 471

  
433 472

  
434 473
    * List accessible containers *    
435
    [file]: list
474
    [file]: /container list
436 475
    1. mycont1 (0B, 0 objects)
437 476
    2. mycont2 (0B, 0 objects)
438 477
    3. pithos (0B, 0 objects)
......
440 479

  
441 480

  
442 481
    * Upload local file to 1st container *
443
    [file]: upload rndm_local.file mycont1
482
    [file]: upload /mycont1/rndm_local.file
444 483

  
445 484

  
446 485
    * Check if file has been uploaded *
447
    [file]: list mycont1
486
    [file]: list /mycont1
448 487
    1.    20M rndm_local.file
449 488

  
450 489
    * Create directory mydir on second container *
451
    [file]: mkdir mycont2:mydir
452

  
490
    [file]: mkdir /mycont2/mydir
453 491

  
454 492
    * Move file from 1st to 2nd container (and in the directory) *
455
    [file]: move mycont1:rndm_local.file mycont2:mydir/rndm_local.file
493
    [file]: move /mycont1/rndm_local.file /mycont2/mydir/rndm_local.file
456 494

  
457 495
    * Check contents of both containers *
458
    [file]: list mycont1
459
    [file]: list mycont2
496
    [file]: list /mycont1
497
    [file]: list /mycont2
460 498
    1.      D mydir/
461 499
    2.    20M mydir/rndm_local.file
462 500

  
463

  
464 501
    * Copy file from 2nd to 1st container, with a new name *
465
    [file]: copy mycont2:mydir/rndm_local.file mycont1:rndm_remote.file
466

  
502
    [file]: copy /mycont2/mydir/rndm_local.file /mycont1/rndm_remote.file
467 503

  
468 504
    * Check pasted file *
469
    [file]: list mycont1
505
    [file]: list /mycont1
470 506
    1.    20M rndm_remote.file
471 507

  
472

  
473 508
    * Download pasted file to local file system *
474
    [file]: download mycont1:rndm_remote.file rndm_remote.file
475

  
509
    [file]: download /mycont1/rndm_remote.file
510
    Downloading: |||||||||||||||||   | 72%
476 511

  
477 512
    * Check if file is downloaded and if it is the same to original *
478 513
    [file]: !ls -lh *.file
......
481 516
    [file]: !diff rndm_local.file rndm_remote.file
482 517

  
483 518
.. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g., bash)
484

  
485
.. warning:: The container:object/path syntax does not function if the
486
    container and / or the object path contain one or more : characters. To use
487
    containers and objects with : use the --container and --dst-container
488
    arguments, e.g., to copy test.py object from example:dev container to
489
    example:deploy ::
490

  
491
        $ kamaki file copy --container=example:dev test.py --dst-container=example:deploy

Also available in: Unified diff