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
  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 ------------------------------------------