code.grnet.gr Git - kamaki/blob - docs/usage.rst

   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     :emphasize-lines: 1
  20
  21     Example 1.1.1: Set user token to myt0k3n==
  22
  23     $ kamaki set token myt0k3n==
  24
  25 To use the storage service, a user should also provide the corresponding username:
  26
  27 .. code-block:: console
  28     :emphasize-lines: 1
  29
  30     Example 1.1.2: Set user name to user@domain.com
  31
  32     $ kamaki set account 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     :emphasize-lines: 1
  60
  61     Example 2.2.1: Run kamaki shell
  62
  63     $ kamaki
  64
  65 * with any kind of '-' prefixed arguments, except '-h', '--help'.
  66
  67 .. code-block:: console
  68     :emphasize-lines: 1
  69
  70     Example 2.2.2: Run kamaki shell with custom configuration file
  71
  72     $ kamaki --config myconfig.file
  73
  74
  75 Run as one-command
  76 """"""""""""""""""
  77 To use kamaki as an one-command tool, run:
  78
  79 * with the '-h' or '--help' arguments (help for kamaki one-command)
  80
  81 .. code-block:: console
  82     :emphasize-lines: 1
  83
  84     Example 2.3.1: Kamaki help
  85
  86     $kamaki -h
  87
  88 * with one or more command parameters:
  89
  90 .. code-block:: console
  91     :emphasize-lines: 1
  92
  93     Example 2.3.2: List VMs managed by user
  94
  95     $ kamaki server list
  96
  97 Commands
  98 ^^^^^^^^
  99
 100 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.
 101
 102 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.
 103
 104 .. code-block:: console
 105     :emphasize-lines: 1
 106
 107     Example 3.1.1: List stored files in container mycontainer.
 108
 109     $ kamaki store list mycontainer
 110
 111 Example 2.3.2 showcases a command without parameters (the group is "server", the command is "list").
 112
 113 The "server" command group is also refered in the following example.
 114
 115 .. code-block:: console
 116     :emphasize-lines: 1
 117
 118     Example 3.1.2 Show information about a user-managed VM with id 42
 119
 120     $ kamaki server info 42
 121
 122 Client commands can feature an arbitarry number of terms:
 123
 124 .. code-block:: text
 125
 126     kamaki <group> <cmd term 1> <cmd term 2> ... <cmd term N> [arguments]
 127
 128 Although there are no multi-termed client commands until version 0.6.1 , the feature is supported and might be used in feature extentions.
 129
 130 The following pattern applies to all client commands up to version 0.6.1:
 131
 132 .. code-block:: text
 133
 134     kamaki <group> <command> [arguments]
 135
 136 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:
 137
 138 astakos (Identity Manager)
 139 """"""""""""""""""""""""""
 140
 141 .. code-block:: text
 142
 143     authenticate:  Authenticate a user
 144
 145 Showcase: get user information, provided the token was set
 146
 147 .. code-block:: console
 148     :emphasize-lines: 1,4
 149
 150     * Enter astakos context *
 151     [kamaki]:astakos
 152
 153     * Authenticate user *
 154     [astakos]:authenticate
 155     auth_token        :  s0m3t0k3nth@t1sr3m0v3d==
 156     auth_token_created:  2012-11-13T14:12:40.917034
 157     auth_token_expires:  2012-12-13T14:12:40.917035
 158     groups            :
 159                       default
 160     has_credits       :  False
 161     has_signed_terms  :  True
 162     uniq              :  myaccount@grnet.gr
 163     username          :  4215th3b357num9323v32
 164
 165 flavor (Compute/Cyclades)
 166 """""""""""""""""""""""""
 167
 168 .. code-block:: text
 169
 170     info:  Get flavor details
 171     list:  List flavors
 172
 173 Showcase: show details for flavor with id 43
 174
 175 .. code-block:: console
 176     :emphasize-lines: 1,4
 177
 178     * Enter flavor context *
 179     [kamaki]: flavor
 180
 181     * Get details about flavor with id 43 *
 182     [flavor]: info 43
 183     SNF:disk_template:  drbd
 184     cpu              :  4
 185     disk             :  10
 186     id               :  43
 187     name             :  C4R2048D10
 188     ram              :  2048
 189
 190 image (Compute/Cyclades + Glance)
 191 """"""""""""""""""""""""""""""""""
 192
 193 .. code-block:: text
 194
 195     addmember  :  Add a member to an image
 196     addproperty:  Add an image property
 197     delete     :  Delete image
 198     delmember  :  Remove a member from an image
 199     delproperty:  Delete an image property
 200     info       :  Get image details
 201     list       :  List images
 202     members    :  Get image members
 203     meta       :  Get image metadata
 204     properties :  Get image properties
 205     public     :  List public images
 206     register   :  (Re)Register an image
 207     setmembers :  Set the members of an image
 208     setproperty:  Update an image property
 209     shared     :  List shared images
 210
 211 Showcase: Pick an image and list the properties
 212
 213 .. code-block:: console
 214     :emphasize-lines: 1,4,18
 215
 216     * Enter image context *
 217     [kamaki]:image
 218
 219     * list all available images *
 220     [image]:list
 221     1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)
 222     1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
 223     18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)
 224     6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
 225     6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
 226     78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
 227     86bc2414-0fb3-4898-a637-240292243302 (Fedora)
 228     926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
 229     b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
 230     baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
 231     c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
 232
 233     * Get properties of image with id b2dffe52-64a4-48c3-8a4c-8214cc3165cf *
 234     [image]:properties b2dffe52-64a4-48c3-8a4c-8214cc3165cf
 235     description   :  Debian 6.0.6 (Squeeze) Base System
 236     gui           :  No GUI
 237     kernel        :  2.6.32
 238     os            :  debian
 239     osfamily      :  linux
 240     root_partition:  1
 241     sortorder     :  1
 242     users         :  root
 243
 244 server (Compute/Cyclades)
 245 """""""""""""""""""""""""
 246
 247 .. code-block:: text
 248
 249     addmeta :  Add server metadata
 250     addr    :  List a server's nic address
 251     console :  Get a VNC console
 252     create  :  Create a server
 253     delete  :  Delete a server
 254     delmeta :  Delete server metadata
 255     firewall:  Set the server's firewall profile
 256     info    :  Get server details
 257     list    :  List servers
 258     meta    :  Get a server's metadata
 259     reboot  :  Reboot a server
 260     rename  :  Update a server's name
 261     setmeta :  Update server's metadata
 262     shutdown:  Shutdown a server
 263     start   :  Start a server
 264     stats   :  Get server statistics
 265     wait    :  Wait for server to finish
 266
 267 Showcase: Create a server.
 268
 269 .. code-block:: console
 270     :emphasize-lines: 1,4,21,35,44,62
 271
 272     * Enter server context *
 273     [kamaki]:server
 274
 275     * See server-create help *
 276     [server]:create -h
 277     usage: create <name> <flavor id> <image id>
 278             [--personality PERSONALITY] [-h] [--config CONFIG]
 279
 280     Create a server
 281
 282     optional arguments:
 283       -v, --verbose         More info at response
 284       --personality PERSONALITY
 285                             add a personality file
 286       -d, --debug           Include debug output
 287       -h, --help            Show help message
 288       -i, --include         Include protocol headers in the output
 289       --config CONFIG       Path to configuration file
 290       -s, --silent          Do not output anything
 291
 292     * List all available images *
 293     [server]:/image list
 294     1395fdfb-51b4-419f-bb02-f7d632860611 (Ubuntu Desktop LTS)
 295     1580deb4-edb3-4496-a27f-7a246c4c0528 (Ubuntu Desktop)
 296     18a82962-43eb-4b32-8e28-8f8880af89d7 (Kubuntu LTS)
 297     6aa6eafd-dccb-422d-a904-67fe2bdde87e (Debian Desktop)
 298     6b5681e4-7502-46ae-b1e9-9fd837932095 (maelstrom)
 299     78262ee7-949e-4d70-af3a-85360c3de57a (Windows Server 2012)
 300     86bc2414-0fb3-4898-a637-240292243302 (Fedora)
 301     926ab1c5-2d85-49d4-aebe-0fce712789b9 (Windows Server 2008)
 302     b2dffe52-64a4-48c3-8a4c-8214cc3165cf (Debian Base)
 303     baf2321c-57a0-4a69-825d-49f49cea163a (CentOS)
 304     c1d27b46-d875-4f5c-b7f1-f39b5af62905 (Kubuntu)
 305
 306     * See details of flavor with id 1 *
 307     [server]:/flavor info 1
 308     SNF:disk_template:  drbd
 309     cpu              :  1
 310     disk             :  20
 311     id               :  1
 312     name             :  C1R1024D20
 313     ram              :  1024
 314
 315     * Create a debian server named 'My Small Debian Server'
 316     [server]:create 'My Small Debian Server' 1 b2dffe52-64a4-48c3-8a4c-8214cc3165cf
 317     adminPass:  L8gu2wbZ94
 318     created  :  2012-11-23T16:56:04.190813+00:00
 319     flavorRef:  1
 320     hostId   :
 321     id       :  11687
 322     imageRef :  b2dffe52-64a4-48c3-8a4c-8214cc3165cf
 323     metadata :
 324              values:
 325                    os   :  debian
 326                    users:  root
 327     name     :  My Small Debian Server
 328     progress :  0
 329     status   :  BUILD
 330     suspended:  False
 331     updated  :  2012-11-23T16:56:04.761962+00:00
 332
 333     * wait for server to build (optional) *
 334     [server]:wait 11687
 335     Server 11687 still in BUILD mode |||||||||||||||||    | 80% - 3s
 336     Server 11687 is now in ACTIVE mode
 337
 338 .. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
 339
 340 network (Compute/Cyclades)
 341 """"""""""""""""""""""""""
 342
 343 .. code-block:: text
 344
 345     connect   :  Connect a server to a network
 346     create    :  Create a network
 347     delete    :  Delete a network
 348     disconnect:  Disconnect a nic of a server to a network
 349     info      :  Get network details
 350     list      :  List networks
 351     rename    :  Update network name
 352
 353 Showcase: Connect a network to a VM
 354
 355 .. code-block:: console
 356     :emphasize-lines: 1,4,9,24,27,44
 357
 358     * Enter network context *
 359     [kamaki]:network
 360
 361     * List user-owned VMs *
 362     [network]:/server list
 363     11687 (My Small Debian Server)
 364     11688 (An Ubuntu server)
 365
 366     * Try network-connect (to get help) *
 367     [network]:connect
 368     Syntax error
 369     usage: connect <server id> <network id> [-s] [-h] [-i] [--config CONFIG]
 370
 371     Connect a server to a network
 372
 373     Syntax: connect  <server id> <network id>
 374       --config    :  Path to configuration file
 375       -d,--debug  :  Include debug output
 376       -h,--help   :  Show help message
 377       -i,--include:  Include protocol headers in the output
 378       -s,--silent :  Do not output anything
 379       -v,--verbose:  More info at response
 380
 381     * Connect VM with id 11687 to network with id 1409
 382     [network]: connect 11687 1409
 383
 384     * Get details on network with id 1409
 385     [network]:info 1409
 386       attachments:
 387                  nic-11687-1
 388       cidr       :  192.168.1.0/24
 389       cidr6      :  None
 390       created    :  2012-11-23T17:17:20.560098+00:00
 391       dhcp       :  True
 392       gateway    :  None
 393       gateway6   :  None
 394       id         :  1409
 395       name       :  my network
 396       public     :  False
 397       status     :  ACTIVE
 398       type       :  PRIVATE_MAC_FILTERED
 399       updated    :  2012-11-23T17:18:25.095225+00:00
 400
 401     * Get connectivity details on VM with id 11687 *
 402     [network]:/server addr 11687
 403     id:  nic-11687-1
 404         ipv4       :  192.168.1.1
 405         ipv6       :  None
 406         mac_address:  aa:0f:c2:0b:0e:85
 407         network_id :  1409
 408         firewallProfile:  DISABLED
 409     id:  nic-11687-0
 410         ipv4           :  83.212.106.111
 411         ipv6           :  2001:648:2ffc:1116:a80c:f2ff:fe12:a9e
 412         mac_address    :  aa:0c:f2:12:0a:9e
 413         network_id     :  1369
 414
 415 .. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
 416
 417 store (Storage/Pithos+)
 418 """""""""""""""""""""""
 419
 420 .. code-block:: text
 421
 422     append        :  Append local file to remote
 423     cat           :  Print a file to console
 424     copy          :  Copy an object
 425     create        :  Create a container or a directory object
 426     delete        :  Delete a container [or an object]
 427     delgroup      :  Delete a user group on an account
 428     delmeta       :  Delete an existing metadatum of account [, container [or object]]
 429     delpermissions:  Delete all sharing permissions
 430     download      :  Download a file
 431     group         :  Get user groups details for account
 432     hashmap       :  Get the hashmap of an object
 433     info          :  Get information for account [, container [or object]]
 434     list          :  List containers, object trees or objects in a directory
 435     manifest      :  Create a remote file with uploaded parts by manifestation
 436     meta          :  Get custom meta-content for account [, container [or object]]
 437     mkdir         :  Create a directory
 438     move          :  Copy an object
 439     overwrite     :  Overwrite part (from start to end) of a remote file
 440     permissions   :  Get object read/write permissions
 441     publish       :  Publish an object
 442     purge         :  Purge a container
 443     quota         :  Get  quota for account [or container]
 444     setgroup      :  Create/update a new user group on account
 445     setmeta       :  Set a new metadatum for account [, container [or object]]
 446     setpermissions:  Set sharing permissions
 447     setquota      :  Set new quota (in KB) for account [or container]
 448     setversioning :  Set new versioning (auto, none) for account [or container]
 449     sharers       :  List the accounts that share objects with default account
 450     truncate      :  Truncate remote file up to a size
 451     unpublish     :  Unpublish an object
 452     upload        :  Upload a file
 453     versioning    :  Get  versioning for account [or container ]
 454     versions      :  Get the version list of an object
 455
 456 Showcase: Upload and download a file.
 457
 458 .. code-block:: console
 459     :emphasize-lines: 1,7,11,16,21,29,33,37,41,44,51,55,60,64
 460
 461     * Create a random binarry file at current OS path *
 462     [kamaki]:!dd bs=4M if=/dev/zero of=rndm_local.file count=5
 463     5+0 records in
 464     5+0 records out
 465     20971520 bytes (21 MB) copied, 0.016162 s, 1.3 GB/s
 466
 467     * Enter store context *
 468     [kamaki]:store
 469
 470
 471     * Check local file *
 472     [store]:!ls -lh rndm_local.file
 473     -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
 474
 475
 476     * Create two containers *
 477     [store]:create mycont1
 478     [store]:create mycont2
 479
 480
 481     * List accessible containers *
 482     [store]:list
 483     1. mycont1 (0B, 0 objects)
 484     2. mycont2 (0B, 0 objects)
 485     3. pithos (0B, 0 objects)
 486     4. trash (0B, 0 objects)
 487
 488
 489     * Upload local file to 1st container *
 490     [store]:upload rndm_local.file mycont1
 491
 492
 493     * Check if file has been uploaded *
 494     [store]:list mycont1
 495     1.    20M rndm_local.file
 496
 497     * Create director mydir on second container *
 498     [store]:mkdir mycont2:mydir
 499
 500
 501     * Move file from 1st to 2nd container (and in the directory) *
 502     [store]:move mycont1:rndm_local.file mycont2:mydir/rndm_local.file
 503
 504     * Check the container of both containers *
 505     [store]:list mycont1
 506     [store]:list mycont2
 507     1.      D mydir/
 508     2.    20M mydir/rndm_local.file
 509
 510
 511     * Copy file from 2nd to 1st container, with a new name *
 512     [store]:copy mycont2:mydir/rndm_local.file mycont1:rndm_remote.file
 513
 514
 515     * Check pasted file *
 516     [store]:list mycont1
 517     1.    20M rndm_remote.file
 518
 519
 520     * Download pasted file to local filesystem *
 521     [store]:download mycont1:rndm_remote.file rndm_remote.file
 522
 523
 524     * Check if file is downloaded and if it is the same to original *
 525     [store]:!ls -lh *.file
 526     -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
 527     -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:42 rndm_remote.file
 528     [store]:!diff rndm_local.file rndm_remote.file
 529
 530 .. Note:: In kamaki shell, ! is used to execute OS shell commands (bash in the above)
 531
 532 One-command interface
 533 ^^^^^^^^^^^^^^^^^^^^^
 534
 535 Kamaki usage as a one-command tool is detailed in this section
 536
 537 Using help
 538 """"""""""
 539
 540 Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments.
 541
 542 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.
 543
 544 .. code-block:: console
 545     :emphasize-lines: 1
 546
 547     Example 4.1.1: kamaki help shows available parameters and command groups
 548
 549
 550     $ kamaki -h
 551     usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
 552         [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h]
 553
 554     optional arguments:
 555       -v, --verbose         More info at response
 556       -s, --silent          Do not output anything
 557       -V, --version         Print current version
 558       -d, --debug           Include debug output
 559       -i, --include         Include protocol headers in the output
 560       --config CONFIG       Path to configuration file
 561       -o OPTIONS, --options OPTIONS
 562                             Override a config value
 563       -h, --help            Show help message
 564
 565     Options:
 566      - - - -
 567     astakos:  Astakos API commands
 568     config :  Configuration commands
 569     flavor :  Compute/Cyclades API flavor commands
 570     history:  Command history
 571     image  :  Compute/Cyclades or Glance API image commands
 572     network:  Compute/Cyclades API network commands
 573     server :  Compute/Cyclades API server commands
 574     store  :  Pithos+ storage commands
 575
 576 .. code-block:: console
 577     :emphasize-lines: 1
 578
 579     Example 4.1.2: Cyclades help contains all first-level commands of cyclades command group
 580
 581
 582     $ kamaki cyclades -h
 583     usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
 584                                [-o OPTIONS] [-h]
 585
 586     optional arguments:
 587       -v, --verbose         More info at response
 588       -s, --silent          Do not output anything
 589       -V, --version         Print current version
 590       -d, --debug           Include debug output
 591       -i, --include         Include protocol headers in the output
 592       --config CONFIG       Path to configuration file
 593       -o OPTIONS, --options OPTIONS
 594                             Override a config value
 595       -h, --help            Show help message
 596
 597     Options:
 598      - - - -
 599     addmeta :  Add server metadata
 600     addr    :  List a server's nic address
 601     console :  Get a VNC console
 602     create  :  Create a server
 603     delete  :  Delete a server
 604     delmeta :  Delete server metadata
 605     firewall:  Set the server's firewall profile
 606     info    :  Get server details
 607     list    :  List servers
 608     meta    :  Get a server's metadata
 609     reboot  :  Reboot a server
 610     rename  :  Update a server's name
 611     setmeta :  Update server's metadata
 612     shutdown:  Shutdown a server
 613     start   :  Start a server
 614     stats   :  Get server statistics
 615     wait    :  Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
 616
 617 .. code-block:: console
 618     :emphasize-lines: 1
 619
 620     Example 4.1.3: Help for command "server list" with syntax, description and avaiable user options
 621
 622
 623     $ kamaki server list -h
 624     usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l]
 625
 626     List servers
 627
 628     optional arguments:
 629       -v, --verbose         More info at response
 630       -s, --silent          Do not output anything
 631       -V, --version         Print current version
 632       -d, --debug           Include debug output
 633       -i, --include         Include protocol headers in the output
 634       --config CONFIG       Path to configuration file
 635       -o OPTIONS, --options OPTIONS
 636                             Override a config value
 637       -h, --help            Show help message
 638       -l                    show detailed output
 639
 640 Using history
 641 """""""""""""
 642
 643 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>`_).
 644
 645 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:
 646
 647 .. code-block:: console
 648     :emphasize-lines: 1
 649
 650     Example 4.2.1: Available history options
 651
 652
 653     $ kamaki history -h
 654     ...
 655     clean:  Clean up history
 656     show :  Show history
 657
 658 The following example showcases how to use history in kamaki
 659
 660 .. code-block:: console
 661     :emphasize-lines: 1
 662
 663     Example 4.2.2: Clean up everything, run a kamaki command, show full and filtered history
 664
 665
 666     $ kamaki history clean --match clean
 667     $ kamaki server list
 668     ...
 669     $ kamaki history show
 670     1.  kamaki server list
 671     2.  kamaki history show
 672     $ kamaki history show --match server
 673     1. kamaki server list
 674     3. kamaki history show --match server
 675
 676 Debug
 677 """""
 678
 679 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.
 680
 681 To run kamaki in debug mode use the -d or --debug option
 682
 683 Verbose
 684 """""""
 685
 686 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.
 687
 688 To run kamaki in verbose mode use the -v or --verbose option
 689
 690 One-command features
 691 """"""""""""""""""""
 692
 693 Kamaki commands can be used along with advanced shell features.
 694
 695 .. code-block:: console
 696     :emphasize-lines: 1
 697
 698     Example 4.4.1: Print username for token us3rt0k3n== using grep
 699
 700
 701     $ kamaki astakos authenticate -o token=us3rt0k3n== | grep uniq
 702     uniq        : user@synnefo.org
 703
 704 The -o argument can be used to overide temporarily various (set or unset) options. In one command, all -o options are forgoten just after the command had been completed, and the previous settings are restored (the configuration file is not modified).
 705
 706 The astakos-authenticate command in example 4.4.1 run against an explicitly provided token, which temporarily overode the token provided in the configuration file.
 707
 708 Interactive shell
 709 ^^^^^^^^^^^^^^^^^
 710
 711 Kamaki interactive shell is details in this section
 712
 713 Command Contexts
 714 """"""""""""""""
 715
 716 The kamaki interactive shell implements the notion of command contexts. Each command group is also a context where the users can **enter** by typing the group name. If the context switch is succesful, the kamaki shell prompt changes to present the new context ("store" in example 5.1.1).
 717
 718 .. code-block:: console
 719     :emphasize-lines: 1
 720
 721     Example 5.1.1: Enter store commands context/group
 722
 723
 724     $ kamaki
 725     [kamaki]:store
 726     [store]:
 727
 728 Type **exit** or **ctrl-D** to exit a context and return to the context of origin. If already at the top context (kamaki), an exit is equivalent to exiting the programm.
 729
 730 .. code-block:: console
 731     :emphasize-lines: 1
 732
 733     Example 5.1.2: Exit store context and then exit kamaki
 734
 735     [store]: exit
 736     [kamaki]: exit
 737     $
 738
 739 A user might **browse** through different contexts during one session.
 740
 741 .. code-block:: console
 742     :emphasize-lines: 1
 743
 744     Example 5.1.3: Execute list command in different contexts
 745
 746     $ kamaki
 747     [kamaki]:config
 748     [config]:list
 749     ... (configuration options listing) ...
 750     [config]:exit
 751     [kamaki]:store
 752     [store]:list
 753     ... (storage containers listing) ...
 754     [store]:exit
 755     [kamaki]:server
 756     [server]:list
 757     ... (VMs listing) ...
 758     [server]: exit
 759     [kamaki]:
 760
 761 Users have the option to avoid switching between contexts: all commands can run from the **top context**. As a result, examples 5.1.3 and 5.1.4 are equivalent.
 762
 763 .. code-block:: console
 764     :emphasize-lines: 1
 765
 766     Example 5.1.4: Execute different "list" commands from top context
 767
 768
 769     [kamaki]:config list
 770     ... (configuration options listing) ...
 771     [kamaki]:store list
 772     ... (storage container listing) ...
 773     [kamaki]:server list
 774     ... (VMs listing) ...
 775     [kamaki]:
 776
 777 Help
 778 """"
 779
 780 There are two help mechanisms: a context-level and a command-level.
 781
 782 **Context-level help** lists the available commands in a context and can also offer a short description for each command.
 783
 784 Context-level help syntax::
 785
 786     * Show available commands in current context *
 787     [context]:help
 788     [context]:?
 789
 790     * Show help for command cmd *
 791     [context]:help cmd
 792     [context]:?cmd
 793
 794 The context-level help results change from context to context
 795
 796 .. code-block:: console
 797     :emphasize-lines: 1
 798
 799     Example 5.2.1: Get available commands, pick a context and get help there as well
 800
 801
 802     [kamaki]:help
 803
 804     kamaki commands:
 805     ================
 806     astakos  config  flavor  history  image  network  server  store
 807
 808     interactive shell commands:
 809     ===========================
 810     exit  help  shell
 811
 812     [kamaki]:?config
 813     Configuration commands (config -h for more options)
 814
 815     [kamaki]:config
 816
 817     [config]:?
 818
 819     config commands:
 820     ================
 821     delete  get  list  set
 822
 823     interactive shell commands:
 824     ===========================
 825     exit  help  shell
 826
 827     [config]:help set
 828     Set a configuration option (set -h for more options)
 829
 830 In context-level, there is a distinction between kamaki-commands and interactive shell commands. The former are available in one-command mode and are releated to the cloud client setup and use, while the later are context-shell functions.
 831
 832 **Command-level help** prints the syntax, arguments and description of a specific (terminal) command
 833
 834 Command-level help syntax::
 835
 836     * Get help for command cmd1 cmd2 ... cmdN *
 837     [context]:cmd1 cmd2 ... cmdN -h
 838     <syntax>
 839
 840     <description>
 841
 842     <arguments and possible extentions>
 843
 844 Command-level help mechanism is exactly the same as the one used in one-command mode. For example, it is invoked by using the -h or --help parameter at any point.
 845
 846 .. code-block:: console
 847     :emphasize-lines: 1
 848
 849     Example 5.2.2: Get command-level help for config and config-set
 850
 851
 852     [kamaki]:config --help
 853     config: Configuration commands
 854     delete:  Delete a configuration option (and use the default value)
 855     get   :  Show a configuration option
 856     list  :  List configuration options
 857     set   :  Set a configuration option
 858
 859     [kamaki]:config
 860
 861     [config]:set -h
 862     usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
 863
 864     Set a configuration option
 865
 866     optional arguments:
 867       -v, --verbose    More info at response
 868       -d, --debug      Include debug output
 869       -h, --help       Show help message
 870       -i, --include    Include protocol headers in the output
 871       --config CONFIG  Path to configuration file
 872       -s, --silent     Do not output anything
 873
 874 There are many ways of producing a help message, as shown in example 5.2.3
 875
 876 .. code-block:: console
 877     :emphasize-lines: 1
 878
 879     Example 5.2.3: Equivalent calls of command-level help for config-set
 880
 881
 882     [config]:set -h
 883     [config]:set -help
 884     [kamaki]:config set -h
 885     [kamaki]:config set --help
 886     [store]:/config set -h
 887     [server]:/config set --help
 888
 889 Accessing top-level commands
 890 """"""""""""""""""""""""""""
 891
 892 When working in a context, it is often usefull to access other contexts or top-level commands. Kamaki offers access to top-level commands by using the / prefix, as shown bellow::
 893
 894     * access a command "anothercontext cmd1 cmd2 ... cmdN"
 895     [context]:/anothercontext cmd1 cmd2 ... cmdN
 896
 897 An example (5.3.1) that showcases how top-level access improves user experience is the creation of a VM. A VM is created with the command server-create. This command is called with three parameters:
 898
 899 * the name of the new VM
 900 * the flavor id
 901 * the image id
 902
 903 It is often the case that a user who works in the context command, needs to create a new VM, but doesn't know the flavor or image id of preference. Therefore, it is nessecary to list all available flavors (flavor-list) or images (image-list. Both commands belong to different contexts.
 904
 905 .. code-block:: console
 906     :emphasize-lines: 1
 907
 908     Example 5.3.1: Create a VM from server context
 909
 910     [server]:create -h
 911     create <name> <flavor id> <image id> ...
 912     ...
 913
 914     [server]:/flavor list
 915     ...
 916     20. AFLAVOR
 917         SNF:disk_template:  drbd
 918         cpu              :  4
 919         disk             :  10
 920         id               :  43
 921         ram              :  2048
 922
 923     [server]:/image list
 924     1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
 925     18a82962-43eb-8f8880af89d7 (Windows 7)
 926     531aa018-9a40-a4bfe6a0caff (Windows XP)
 927     6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
 928
 929     [server]:create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
 930     ...
 931
 932 An other example (5.3.2) showcases how to aquire and modify configuration settings from a different context. In this scenario, the user token expires at server side while the user is working. When that happens, the system responds with an *(401) UNAUTHORIZED* message. The user can aquires a new token (with a browser) which has to be set to kamaki.
 933
 934 .. code-block:: console
 935     :emphasize-lines: 1
 936
 937     Example 5.3.2: Set a new token from store context
 938
 939
 940     [store]:list
 941     (401) UNAUTHORIZED Access denied
 942
 943     [store]:/astakos authenticate
 944     (401) UNAUTHORIZED Invalid X-Auth-Token
 945
 946     [store]:/config get token
 947     my3xp1r3dt0k3n==
 948
 949     [store]:/config set token myfr35ht0k3n==
 950
 951     [store]:/config get token
 952     myfr35ht0k3n==
 953
 954     [store]:list
 955     1.  pithos (10MB, 2 objects)
 956     2.  trash (0B, 0 objects)
 957
 958 The following example compares some equivalent calls that run *astakos-authenticate* after a *store-list* 401 failure.
 959
 960 .. code-block:: console
 961     :emphasize-lines: 1,3,10,17,28
 962
 963     Example 5.3.3: Equivalent astakos-authenticate calls after a store-list 401 failure
 964
 965     * without kamaki interactive shell *
 966     $ kamaki store list
 967     (401) UNAUTHORIZED Access denied
 968     $ kamaki astakos authenticate
 969     ...
 970     $
 971
 972     * from top-level context *
 973     [kamaki]:store list
 974     (401) UNAUTHORIZED Access denied
 975     [kamaki]:astakos authenticate
 976     ...
 977     [kamaki]
 978
 979     * maximum typing *
 980     [store]:list
 981     (401) UNAUTHORIZED Access denied
 982     [store]:exit
 983     [kamaki]:astakos
 984     [astakos]:authenticate
 985     ...
 986     [astakos]:
 987
 988     * minimum typing *
 989     [store]: list
 990     (401) UNAUTHORIZED Access denied
 991     [store]:/astakos authenticate
 992     ...
 993     [store]:
 994
 995 Config
 996 """"""
 997
 998 History
 999 """""""
1000
1001 Tab completion
1002 """"""""""""""
1003
1004 OS Shell integration
1005 """"""""""""""""""""
1006
1007 Creating applications with the Clients API
1008 ------------------------------------------