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.
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.
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.
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:
18 .. code-block:: console
20 $ kamaki set token myt0k3n==
23 Example 1.1.1: Set user token to myt0k3n==
25 To use the storage service, a user should also provide the corresponding username:
27 .. code-block:: console
29 $ kamaki set account user@domain.com
32 Example 1.1.2: Set user name to user@domain.com
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.
40 In favor of interactive shell behavior:
42 * tab completion for commands
43 * session history with "up"/"down" keys
44 * shorter commants with command namespace switching
46 In favor of one-command behavior:
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
54 To use kamaki as a shell, run:
56 * without any parameters or arguments
58 .. code-block:: console
63 Example 2.2.1: Running kamaki shell
66 * with any kind of '-' prefixed arguments, except '-h', '--help'.
68 .. code-block:: console
70 $ kamaki --config myconfig.file
73 Example 2.2.2: Running kamaki shell with custom configuration file
78 To use kamaki as an one-command tool, run:
80 * with the '-h' or '--help' arguments (help for kamaki one-command)
82 .. code-block:: console
87 Example 2.3.1: Kamaki help
89 * with one or more command parameters:
91 .. code-block:: console
96 Example 2.3.2: List VMs managed by user
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.
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.
105 .. code-block:: console
107 $ kamaki store list mycontainer
110 Example 3.1.1: List stored files in container mycontainer.
112 Example 2.3.2 showcases a command without parameters (the group is "server", the command is "list").
114 The "server" command group is also refered in the following example.
116 .. code-block:: console
118 $ kamaki server info 42
121 Example 3.1.2 Show information about a user-managed VM with id 42
123 Client commands can feature an arbitarry number of terms:
127 kamaki <group> <cmd term 1> <cmd term 2> ... <cmd term N> [arguments]
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.
131 The following pattern applies to all client commands up to version 0.6.1:
135 kamaki <group> <command> [arguments]
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:
139 astakos (Identity Manager)
140 """"""""""""""""""""""""""
144 authenticate: Authenticate a user
146 Showcase: get user information, provided the token was set
148 .. code-block:: console
149 :emphasize-lines: 3-11
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
159 has_signed_terms : True
160 uniq : myaccount@grnet.gr
161 username : 4215th3b357num9323v32
164 flavor (Compute/Cyclades)
165 """""""""""""""""""""""""
169 info: Get flavor details
172 Showcase: show details for flavor with id 43
174 .. code-block:: console
175 :emphasize-lines: 3-8
179 SNF:disk_template: drbd
187 image (Compute/Cyclades + Glance)
188 """"""""""""""""""""""""""""""""""
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
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
208 Showcase: show a list of public images, list the properties of Debian Base
210 .. code-block:: console
211 :emphasize-lines: 3-13,15-22
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
237 server (Compute/Cyclades)
238 """""""""""""""""""""""""
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
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
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 )
262 .. code-block:: console
263 :emphasize-lines: 3-16,18-33,35-40,42-56,58,59,61-66
267 usage: create <name> <flavor id> <image id>
268 [--personality PERSONALITY] [-h] [--config CONFIG]
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
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
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
306 imageRef : b2dffe52-64a4-48c3-8a4c-8214cc3165cf
311 name : My Small Debian Server
315 updated : 2012-11-23T16:56:04.761962+00:00
317 Server 11687 still in BUILD mode ||||||||||||||||| | 80% - 3s
318 Server 11687 is now in ACTIVE mode
321 network (Compute/Cyclades)
322 """"""""""""""""""""""""""
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
332 rename : Update network name
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.
336 .. code-block:: console
337 :emphasize-lines: 1, 2, 5, 14, 15, 30, 42
340 [network]:/server list
341 11687 (My Small Debian Server)
342 11688 (An Ubuntu server)
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
356 cidr : 192.168.1.0/24
358 created : 2012-11-23T17:17:20.560098+00:00
366 type : PRIVATE_MAC_FILTERED
367 updated : 2012-11-23T17:18:25.095225+00:00
368 [network]:/server addr 11687
372 mac_address: aa:0f:c2:0b:0e:85
374 firewallProfile: DISABLED
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
384 store (Storage/Pithos+)
385 """""""""""""""""""""""
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
423 One-command interface
424 ^^^^^^^^^^^^^^^^^^^^^
426 Kamaki usage as a one-command tool is detailed in this section
431 Kamaki help is used to see available commands, with description, syntax and their corresponding optional arguments.
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.
435 .. code-block:: console
438 usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd> [-v] [-s] [-V] [-d] [-i]
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
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
465 Example 4.1.1: kamaki help shows available parameters and command groups
467 .. code-block:: console
470 usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
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
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
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]
505 Example 4.1.2: Cyclades help contains all first-level commands of cyclades command group
507 .. code-block:: console
509 $ kamaki server list -h
510 usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
511 [-o OPTIONS] [-h] [-l]
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
528 Example 4.1.3: Help for command "server list" with syntax, description and avaiable user options
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>`_).
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:
537 .. code-block:: console
541 clean: Clean up history
545 Example 4.2.1: Available history options
547 The following example showcases how to use history in kamaki
549 .. code-block:: console
551 $ kamaki history clean --match clean
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
562 Example 4.2.2: Clean up everything, run a kamaki command, show full and filtered history
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.
569 To run kamaki in debug mode use the -d or --debug option
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.
576 To run kamaki in verbose mode use the -v or --verbose option
582 Kamaki commands can be used along with advanced shell features.
584 .. code-block:: console
586 $ kamaki server list -l > vmlist.txt
589 Example 4.4.1: Store a vm list in file vmlist.txt in a unix shell
596 Creating applications over the Clients API
597 ------------------------------------------