/ - Diff - ./kamaki - Greek Research and Technology Network's projects

Revision f6822a26

     .. warning:: The container:object/path syntax does not function if the
         container and / or the object path contain one or more : characters. To use
         containers and objects with : use the --container and --dst-container
         arguments, e.g. to copy test.py object from grnet:dev container to
         grnet:deploy ::
         arguments, e.g. to copy test.py object from example:dev container to
         example:deploy ::
             $ kamaki file copy --container=grnet:dev test.py --dst-container=grnet:deploy
             $ kamaki file copy --container=example:dev test.py --dst-container=example:deploy

     Configuration
     =============
     Since kamaki 0.9, the format of the configuration file has changed. In this
     scenario, we have an old configuration file at ${HOME}/.kamakirc that we need
     to convert. We also create a new one from scratch. In both cases, we have to
     set up one or more clouds in a single configuration and we also examine a case
     of multiple configurations.
     The following refers to the configuration version 0.9 or better. There is also
     information on how to convert from older configuration files.
     In this scenario, we start with an old configuration file at
     *${HOME}/.kamakirc* that we need to convert. We also create a new one from scratch. In both cases, the second step is the same: set up one or more clouds
     in a single configuration. Then we examine a case of multiple configuration
     files.
     Convert old configuration file
     ------------------------------
-...
         .     image.url = https://cyclades.example.com/plankton
         .     store.account = OldForgotenAccountName
         . Kamaki is ready to convert the config file
         . Create (overwrite) file .kamakirc.okeanos ? [y/N]
         . Create (overwrite) file .kamakirc ? [y/N]
+        .
         <y is pressed>
+        .
-...
     Failed or incomplete cloud configurations
     -----------------------------------------
     Now let kamaki use the default configuration ( ${HOME}/.kamakirc ). Let the old
     Now let kamaki use the default configuration (*${HOME}/.kamakirc*). Let the old
     token be `my0ld70k3n==` and let it be invalid.
     Check for clouds and attempt to authenticate
-...
         . |  UNAUTHORIZED unauthorized (Invalid token)
+        $
     After some searching at the deployments UI, you found out that the URL/token
     After some searching at the deployments UI, you find out that the URL/token
     pair you need is::
         URL: https://accounts.deploymentexample.com/identity/v2.0
-...
             URL: https://accounts.example.com/identity/v2.0/
             TOKEN: myt35t70k3n==
     As we can see, the default configuration handles only one cloud, aliased as
     Obviously the default configuration handles only one cloud, aliased as
     "default". We will add the second cloud as well.
     .. code-block:: console
-...
         . cloud.mytest.token = myt35t70k3n==
+        $
     Check if kamaki knows one of the clouds to be the default
     Check if kamaki is confused (is there a default cloud setup?)
     .. code-block:: console
-...
     Multiple configurations
     -----------------------
     In the following example, a user wants to experiment with upload and download
     for different number of threads. The plan is to contuct a set of tests with 3
     threads at most and another one with 5. All experiments will be run against the
     same Synnefo cloud (the "mytest" cloud from the previous example).
     In the following example, we experiment with the higher number of threads when
     uploading and downloading. The plan is to contact a set of tests with 3 threads
     at most and another one with 5. All experiments will be run against the same
     Synnefo cloud (the "mytest" cloud from the previous example).
     Let's create the 3-threaded configuration first

         pithos:debian_base3.diskdump
     The crussial element in an image location is the container (e.g. `pithos`) and
     the image object path (e.g. `debian_base3.diskdump`).
     .. note:: The image API requires the image location in the form
         *pithos://<user uuid>/<container>/<object path>*
         The translation between
         the two formats is handled internally by kamaki. The latest format is still
         acceptable by kamaki due to backward compatibility but it is going to be deprecated from kamaki 0.12 and on.
     Register an image
-...
     the image file and then register it as an image, and is equivalent to manually
     calling **/file upload** and **/image register**.
     In other words, the example that follows is equivalent to calling the two
     operations above.
     In other words, the preceding and following command sequences are equivalent.
     .. code-block:: console
-...
         OS: Linux
         user: someuser
     These properties can be added freely by the user, and they have no significance
     for the image server, but they could be used to help using the image more
     efficiently.
     These properties can be added freely by the user, and they are not required by
     the image server, but they can be used by many applications.
     Attempt to register with properties
     Attempt to register an image with custom properties
     .. code-block:: console
-...
         Metadata file pithos:debian_base3.diskdump.meta already exists
         [kamaki]:
     It's true that the metafile is already there, but we can override it (**-f**)
     It's true that a metafile with this name is already there, but we can override
     it (**-f**)
     .. code-block:: console
-...
         Done
         [kamaki]:
     The metadata file can be edited. Let's edit the file, by adding properties::
     The metadata file can be edited. Let's edit the file to add these properties::
         OS: Linux
         user: root
-...
         [kamaki]: image meta set 7h1rd-1m4g3-1d --name='Changed Name'
         [kamaki]:
     If we, now, get the image metadata, we will see that the name is changed:
     A look at the image metadata reveals that the name is changed:
     .. code-block:: console
-...
         [kamaki]: image meta set 7h1rd-1m4g3-1d --unpublish
         [kamaki]:
     The first call published the image (set is-public to True) and also restored
     the name to "Debian Base Gama". The second one unpublished the image (set
     The first call publishes the image (set is-public to True) and also restores
     the name to "Debian Base Gama". The second one unpublishes the image (set
     is-public to False).
     To delete metadata, use the image meta delete method:
     To delete metadata, use the image meta delete method. For example, the
     following will set the value of *status* to an empty string:
     .. code-block:: console
         [kamaki]: image meta delete 7h1rd-1m4g3-1d status
         [kamaki]:
     will empty the value of "status".
     These operations can be used for properties with the same semantics:
-...
     produced automatically at the server side, was the same. This is due to the
     fact that image ids are 1 to 1 related to image objects uploaded to Pithos+
     **An explicit name overrides the metafile**
     **An explicit image name overrides the metafile**
     Each image needs a name and this is given as the first argument of the
     `register` command. This name overrides the name in the metafile.
     **Reregistration is not update, but an override**
     **Reregistration is not an update, but an override**
     The property `user: root` won over `user: someuser`, because it was set last.
     Actually, all properties were replaced by the new ones, when the image was
-...
     images (all images will be named after their relative paths).
     Also, let the registered images be public (accessible to all users for creating
     VMs) by adding the **--public** flag argument when calling `image register`.
     VMs) by adding the **- - public** flag argument when calling `image register`.
     .. code-block:: console

     .. code-block:: console
         $ kamaki
         kamaki v0.9 - Interactive Shell
+        .
         kamaki v0.10 - Interactive Shell
         /exit       terminate kamaki
         exit or ^D  exit context
         ? or help   available commands
         ?command    help on command
         !<command>  execute OS shell command
+        .
         Session user is Tyler Durden <uuid: th3y-4r3-7h3-54m3-p3r50n>
         [kamaki]:
     Simple listing
     --------------
     List configuration options, whether in the file or in memory
     List configuration options, whether in the file or from defaults list
     .. code-block:: console
-...
         [kamaki]: network list
 public_network
 my_private)network
 my_private_network
         [kamaki]:
     List flavors
-...
         [kamaki]: image list
         f1r57-1m4g3-1d Debian Base Alpha
         .container_format: bare
         .disk_format:      diskdump
         .size:             474066944
         .status:           available
          container_format: bare
          disk_format:      diskdump
          size:             474066944
          status:           available
 c0nd-1m4g3-1d Beta Debian Base
         .container_format: bare
         .disk_format:      diskdump
         .size:             474066944
         .status:           available
          container_format: bare
          disk_format:      diskdump
          size:             474066944
          status:           available
         [kamaki]: image compute list
         f1r57-1m4g3-1d Debian Base Alpha
 c0nd-1m4g3-1d Beta Debian Base
-...
         count:    3
         modified: 2013-06-17T12:35:11.613124+00:00
         policy:
         .       quota:      0
         .       versioning: auto
                 quota:      0
                 versioning: auto
         trash
         bytes:    0 (0B)
         count:    0
         modified: 2013-06-06T14:24:23.675891+00:00
         policy:
         .       quota:      0
         .       versioning: auto
                 quota:      0
                 versioning: auto
         [file]:
     Create some more pithos container to experiment with
-...
         type:      plan-text/unicode
         uuid:      0493f1d9-9410-4f4b-a81f-fe42f9cefa70
         version:   1085
+        .
         video
         by:        s0m3-u53r-1d
         bytes:     0
-...
         type:      application/directory
         uuid:      80e719f5-9d68-4333-9846-9943972ef1fd
         version:   1086
+        .
         video/tk1.mpg
         by:        s0m3-u53r-1d
         bytes:     11000000 (11ΜΒB)
-...
         type:      video/mpeg
         uuid:      b0b46b39-c59a-4adc-a386-6a169cb9f8a5
         version:   1079
+        .
         video/tk2.mpg
         by:        s0m3-u53r-1d
         bytes:     12000000 (12MB)
-...
         type:      video/mpeg
         uuid:      12a81309-db3c-4e30-ae9a-4ac2b8289def
         version:   1081
+        .
         video/tk3.mpg
         by:        s0m3-u53r-1d
         bytes:     13000000 (13MB)
-...
         type:      video/mpeg
         uuid:      b0b46b39-c59a-4adc-a386-6a169cb9f8a5
         version:   1079
+        .
         video/tk2.mpg
         by:        s0m3-u53r-1d
         bytes:     12000000 (12MB)
-...
         type:      video/mpeg
         uuid:      12a81309-db3c-4e30-ae9a-4ac2b8289def
         version:   1081
+        .
         video/tk3.mpg
         by:        s0m3-u53r-1d
         bytes:     13000000 (13MB)
-...
                                OS-EXT-IPS:type: fixed
                                addr:            192.168.12.4
                                version:         4
                             . . . . . . .
                                OS-EXT-IPS:type: fixed
                                addr:            2001:648:2ffc:1222:a800:2ff:fee3:49f1
                                version:         6
-...
                         links:
                                 href: https://example.com/compute/v2.0/flavors/1
                                 rel:  bookmark
                              . . . . . . .
                                 href: https://example.com/compute/v2.0/flavors/1
                                 rel:  self
             hostId:
-...
                         links:
                                 href: https://example.com/compute/v2.0/images/f1r57-1m4g3-1d
                                 rel:  bookmark
                              . . . . . . .
                                 href: https://example.com/compute/v2.0/images/f1r57-1m4g3-1d
                                 rel:  self
                              . . . . . . .
                                 href: https:/example.com/image/v1.0/images/f1r57-1m4g3-1d
                                 rel:  alternate
             key_name:        None
             links:
                            href: https://example.com/compute/v2.0/servers/4201
                            rel:  bookmark
                         . . . . . . .
                            href: https://example.com/compute/v2.0/servers/4201
                            rel:  self
             metadata:
-...
                                OS-EXT-IPS:type: fixed
                                addr:            192.168.12.4
                                version:         4
                             . . . . . . .
                                OS-EXT-IPS:type: fixed
                                addr:            2002:648:2ffc:1222:a800:2ff:fee3:49f1
                                version:         6
-...
                         links:
                                 href: https://example.com/compute/v2.0/flavors/2
                                 rel:  bookmark
                              . . . . . . .
                                 href: https://example.com/compute/v2.0/flavors/2
                                 rel:  self
             hostId:
-...
                         links:
                                 href: https://example.com/compute/v2.0/images/53c0nd-1m4g3-1d
                                 rel:  bookmark
                              . . . . . . .
                                 href: https://example.com/compute/v2.0/images/53c0nd-1m4g3-1d
                                 rel:  self
                              . . . . . . .
                                 href: https:/example.com/image/v1.0/images/53c0nd-1m4g3-1d
                                 rel:  alternate
             key_name:        None
             links:
                            href: https://example.com/compute/v2.0/servers/4202
                            rel:  bookmark
                         . . . . . . .
                            href: https://example.com/compute/v2.0/servers/4202
                            rel:  self
             metadata:
-...
             links:
                  href: https://example.com/cyclades/compute/v2.0/images/f1r57-1m4g3-1d
                  rel:  bookmark
               . . . . . . .
                  href: https://example.com/cyclades/compute/v2.0/images/f1r57-1m4g3-1d
                  rel:  self
               . . . . . . .
                  href: https://example.com/cyclades/image/v1.0/images/f1r57-1m4g3-1d
                  rel:  alternate
             metadata:
-...
             links:
                  href: https://example.com/cyclades/compute/v2.0/images/53c0nd-1m4g3-1d
                  rel:  bookmark
               . . . . . . .
                  href: https://example.com/cyclades/compute/v2.0/images/53c0nd-1m4g3-1d
                  rel:  self
               . . . . . . .
                  href: https://example.com/cyclades/image/v1.0/images/53c0nd-1m4g3-1d
                  rel:  alternate
             metadata:

     Users can create private networks between Virtual Machines.
     In the following we assume that there are two active VMs (ids 141 and 142)
     connected to one public network with id 1 (default set up).
     In the following we assume that there are two active virtual servers (ids 141
     and 142) connected to one public network with id 1 (default set up).
     .. code-block:: console
-...
             network_id:      1
+        $
     .. note:: In Synnefo, each VM connects to a network through a NIC. The id of a
         nic is nic-<server id>-<increment> by convention.
     .. note:: In Synnefo, each virtual server connects to a network through a nic.
         The id of a nic is *nic-<server id>-<increment>* by convention.
     Let's load kamaki for networks and have a look at the current network state. We
     expect to find at least one public network (id: 1)
-...
         user_id:     s0m3-u53r-1d
         [network]:
     Let's create two more networks, one for VM 141 and one for Vm 142
     Let's create two more networks, one for virtual server 141 and one for virtual
     server 142
     .. code-block:: console
         [network]: create 'For VM 141'
         [network]: create 'For virtual server 141'
         ...
         id:         4
         ...
         [network]: create 'For VM 142'
         [network]: create 'For virtual server 142'
         ...
         id:         5
         ...
-...
     Connect and disconnect
     ----------------------
     To make a points, the networks should be connected to their respecting VMs
     To make a point, the networks should be connected to their respecting virtual
     servers
     .. code-block:: console
-...
         [network]:
     Now, let's check the current network state. We expect to see the servers
     connected to netowkrd with ids 4 and 5, but not 3.
     connected to networks with ids 4 and 5, but not 3.
     .. code-block:: console
-...
          type:        MAC_FILTERED
          updated:     2013-06-19T13:54:57.672744+00:00
          user_id:     s0m3-u53r-1d
 For VM 141
 For virtual server 141
          attachments:
                     nic-141-1
          cidr:        192.168.2.0/24
-...
          type:        MAC_FILTERED
          updated:     2013-06-19T13:54:57.672744+00:00
          user_id:     s0m3-u53r-1d
 For VM 142
 For virtual server 142
          attachments:
                     nic-141-2
          cidr:        192.168.3.0/24
-...
          user_id:     s0m3-u53r-1d
         [network]:
     It is time to make meaningful connections: connect two servers to a private
     It is time to make a meaningful connection: connect two servers to a private
     network
     .. code-block:: console
-...
         [network]: connect 142 3
         [network]:
     Now the servers can communicate with eachother through their shared private
     Now the servers can communicate with each other through their shared private
     network. Let's see the network details to confirm that
     .. code-block:: console
-...
     .. warning:: Public networks cannot be destroyed in Synnefo
     Attempt to destroy the useless `For VM 141` network
     Attempt to destroy the useless `For virtual server 141` network
     .. code-block:: console
-...
         (403) Network with id 4 is in use
         [network]:
     The attached VMs should be disconnected first (recall that the nic-141-1
     connects network with id 4 to VM with id 141)
     The attached virtual servers should be disconnected first (recall that the
     nic-141-1 connects network with id 4 to virtual server with id 141)
     .. code-block:: console
-...
         [network]: disconnect nic-142-2
         [network]: disconnect nic-141-2
         (404) No nic nic-141-2 on server(VM) with id 141
         |  * check server(VM) with id 142: /server info 141
         |  * list nics for server(VM) with id 141:
         (404) No nic nic-141-2 on server(virtual server) with id 141
         |  * check server(virtual server) with id 142: /server info 141
         |  * list nics for server(virtual server) with id 141:
         |        /server addr 141
         |  Network Interface nic-141-2 not found on server 141
         [network]:
     Strangely, kamaki did not find any nic-141-2 nics. Why?
     Answer: A listing of the 141 nics shows that the network connection to network
     with id 3 is now renamed as nic-141-1
     Answer: Get the addresses of server 141 to find out that the nic which connects
     the server to network 3 is automatically renamed (nic-141-2 --> nic-141-1)
     .. code-block:: console
-...
          network_id:      1
          [network]:
     .. warning:: Synnefo network server renames the nics of a VM whenever another
         nic is of the same server is deleted
     .. warning:: Synnefo network server may rename the nics of a virtual server if
         another nic on the same server is deleted
     Let's remove the correct nic, then, and check if any other nics are related to
     the network with id 3.

     ===================================
     A `server` (also known as `virtual machine`), is created based on a registered
     `image` and a reconfigured hardware setup (also known as `flavor`).
     `image` and a preconfigured hardware setup (also known as `flavor`).
     Create a virtual server
     -----------------------
-...
         [kamaki]:
     Let's pick the `C1R128D1drbd` (id: 1) flavor and the `Debian Base Alpha` (id:
     f1r57-1m4g3-1d) image to create a new VM called 'My First Server'
     f1r57-1m4g3-1d) image to create a new virtual server called 'My First Server'
     .. code-block:: console
-...
         [kamaki]:
     .. note:: The adminPass field is not stored anywhere, therefore users would
         rather write it down and change it the first time they use the VM
         rather write it down and change it the first time they use the virtual server
     Wait for the VM with id 141 to build (optional)
     Wait for the virtual server with id 141 to build (optional)
     .. code-block:: console
         [kamaki]: server wait 141
         <bar showing build progress, until 100%>
         Server 141 is not in ACTIVE mode
         Server 141 is now in ACTIVE mode
         [kamaki]:
     Destroy the VM (wait is still optional)
     Destroy the virtual server (wait is still optional)
     .. code-block:: console
         [kamaki]: server delete 141
         [kamaki]: server wait 141 ACTIVE
         <bar showing destruction progress, until 100%>
         Server 141 is not in DELETED mode
         Server 141 is now in DELETED mode
         [kamaki]:
     Inject ssh keys to a debian server
     ----------------------------------
     Assume that the servers build from the image `Debian Base Alpha` accept ssh
     connections. We need to build servers that can log us as roots without a
     connections. We need to build servers that can log us as root without a
     password. This can be achieved if the `/root/.ssh/authorized_keys` file exists
     and contains the public key of the current user.
-...
     `/root/.ssh/authorized_keys` while creating the virtual server.
     Luckily, Synnefo fully supports the OpenStack suggestion for file injections on
     VMs and kamaki allows it by using the **-p** argument (p stands for
     virtual servers and kamaki allows it by using the **-p** argument (p stands for
     `PERSONALITY` and is the term used in the
     `respective OpenStack <http://docs.openstack.org/api/openstack-compute/2/content/CreateServers.html>`_ description).
-...
         default behavior depends on the remote server, e.g. for a debian image we
         expect the file to have root ownership, if the ownership is not specified.
     Create a vm while injecting current users public key to root account
     Create a virtual server while injecting current user public key to root account
     .. code-block:: console
-...
         user_id:         s0m3-u53r-1d
         [server]:
     When the VM is ready, get the VMs external IP from the web UI. Let's assume the
     When the virtual server is ready, get the virtual servers external IP from the web UI. Let's assume the
     IP is 123.456.78.90 .
     .. code-block:: console
         [server]: /exit
         $ ssh 123.456.78.90
         Linux remote-vm-4241 2.6.32-5-amd64 #1 SMP XXXX x86_64
         Linux remote-virtual server-4241 2.6.32-5-amd64 #1 SMP XXXX x86_64
         The programs included with the Debian GNU/Linux system are free software;
         the exact distribution terms for each program are described in the
-...
         Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
         permitted by applicable law.
         root@remote-vm-4241:~# ls -l .ssh/
         root@remote-virtual server-4241:~# ls -l .ssh/
         total 4
         -rw-r--r-- 1 root root 399 Jun 19 12:34 authorized_keys
         root@remote-vm-4241:~#
         root@remote-virtual server-4241:~#
     You can now log to your remote VM as root, without a password. Well done!
     You can now log to your remote virtual server as root, without a password. Well done!
     .. note:: There is no reason to limit injections to ssh keys. Users with an
         adequate understanding of the remote OS are encouraged to prepare and

     Publish and unpublish
     ---------------------
     Check publishing for objects `info.txt` and `file2upload.txt`
     Get publishing information for objects `info.txt` and `file2upload.txt`
     .. code-block:: console
-...
         last-modified:              Mon, 17 Jun 2013 13:09:44 GMT
         server:                     gunicorn/0.14.5
         vary:                       X-Auth-Token,Accept-Language,Accept-Encoding
         x-object-hash:              e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
         x-object-hash:              e3b0c44298fc1c14....ca495991b7852b855
         x-object-modified-by:       s0m3-u53r-1d
         x-object-public:            https://example.com/pithos/public/14lhJnAhVU7
         x-object-uuid:              0493f1d9-9410-4f4b-a81f-fe42f9cefa70
-...
         last-modified:              Mon, 17 Jun 2013 13:09:44 GMT
         server:                     gunicorn/0.14.5
         vary:                       X-Auth-Token,Accept-Language,Accept-Encoding
         x-object-hash:              f3b0c44298fc1c149afbf4c8996df92427ae41e4649b934ca495991b7852b857
         x-object-hash:              f3b0c44298fc1c149af...a495991b7852b857
         x-object-modified-by:       s0m3-u53r-1d
         x-object-uuid:              0493f1d9-9410-4f4b-a81f-fe42f9cefa70
         x-object-version:           1085
         x-object-version-timestamp: Mon, 17 Jun 2013 13:09:44 GMT
         [file]:
     .. note:: The first object contains a "x-object-public" field, therefore is
     .. note:: The first object contains an "x-object-public" field, therefore is
         published
     Unpublish info.txt, publish file2upload.txt
-...
     Modify permissions
     ------------------
     Check current permissions. If none set, the object is unrestricted
     Get current permissions. If none set, the object inherits permissions from the
     container and account (in that order).
     .. code-block:: console

     ====================
     The operations of uploading files to pithos as objects, and downloading
     objects from pithos as a file are presented in this section.
     objects from pithos as files are presented in this section.
     Enter file context
-...
         [file]:
     .. note:: Try to reupload the files (use the -f option to override) and notice
         how much faster is the uploading now. Pithos can determine what parts of
         the file are already uploaded so that kamaki won't attempt to upload them
         again.
         how much faster is the uploading now. Pithos can determine what parts
         (blocks) of the file are already uploaded. Kamaki will, then, upload only
         the missing pars, if any.
     Download an object or a directory
     ---------------------------------
-...
         tk2.mpg 4MB
+        $
     Let's resume the download uperations (use -r)
     Let's resume the download (use -r)
     .. code-block:: console
-...
         Done
         [file]:
     .. note:: Kamaki calculated that all information is already uploaded, there was
         nothing to be done. If there is was a new or modified file, kamaki would
         detect and upload it.
     .. note:: In this case, all files were already uploaded, so kamaki didn't have
         to upload anything. If a file was modified, kamaki would sync it with its
         remote counterpart.
     Download all
     ------------
-...
         Done
         [file]:
     .. note:: Kamaki determined that all files have already been calculated. This
         operation examines all local files against the remote objects and
         downloads only missing data.
     .. note:: Kamaki determined that all remote objects already exist as local files
         too, so there is nothing to be done. If a new remote object was created or
         an old one was modified, kamaki would have sync it with a local file.
     Exit Context
     ------------

     Using help
     ^^^^^^^^^^
     Kamaki help is used to list available commands with description, syntax and
     corresponding optional arguments.
     Kamaki help provides information on available commands (description, syntax and
     corresponding optional arguments).
     To see the command groups, 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.
     To see the command groups, use -h or --help (example 1.3.1). The
     following examples demonstrate the help messages of kamaki, in the context of a
     command group (server) and of a command in that group (list).
     .. code-block:: console
         :emphasize-lines: 1
-...
         Options:
          - - - -
         config :  Kamaki configurations
         file   :  Pithos+/Storage API commands
         flavor :  Cyclades/Compute API flavor commands
         history:  Kamaki command history
         image  :  Cyclades/Plankton API image commands
         network: Cyclades/Compute API network commands
         user: Astakos API commands
         livetest: Client func. tests on live servers
         server: Cyclades/Compute API server commands
         project: Synnefo project management CLI
         file: Pithos+/Storage API commands
         flavor: Cyclades/Compute API flavor commands
         config: Kamaki configurations
         image: Cyclades/Plankton API image commands
         image compute:  Cyclades/Compute API image commands
         network:  Cyclades/Compute API network commands
         server :  Cyclades/Compute API server commands
         user   :  Astakos API commands
         history: Kamaki command history
     .. code-block:: console
         :emphasize-lines: 1,2
-...
         Options:
          - - - -
         addr    :  List the addresses of all network interfaces on a server (server)
         console :  Get a VNC console to access an existing server (server)
         create  :  Create a server (aka Virtual Machine)
         delete  :  Delete a server (server)
         firewall:  Manage server (server) firewall profiles for public networks
         ip      :  Manage floating IPs for the servers
         info    :  Detailed information on a Virtual Machine
         list    :  List Virtual Machines accessible by user
         metadata:  Manage Server metadata (key:value pairs of server attributes)
         reboot  :  Reboot a server (server)
         rename  :  Set/update a server (server) name
         shutdown:  Shutdown an active server (server)
         start   :  Start an existing server (server)
         stats   :  Get server (server) statistics
         resize  :  Set a different flavor for an existing server
         wait    :  Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
         info: Detailed information on a Virtual Machine
         rename: Set/update a virtual server name
         delete: Delete a virtual server
         console: Get a VNC console to access an existing virtual server
         addr: List the addresses of all network interfaces on a virtual server
         firewall: Manage virtual server firewall profiles for public networks
         ip: Manage floating IPs for the servers
         create: Create a server (aka Virtual Machine)
         list: List Virtual Machines accessible by user
         reboot: Reboot a virtual server
         start: Start an existing virtual server
         shutdown: Shutdown an active virtual server
         stats: Get virtual server statistics
         metadata: Manage Server metadata (key:value pairs of server attributes)
         resize: Set a different flavor for an existing server
         wait: Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
     .. code-block:: console
         :emphasize-lines: 1,2
-...
                                   [-l] [--more] [-n LIMIT] [-j]
         List Virtual Machines accessible by user
         User Authentication:
         * to check authentication: /user authenticate
         * to set authentication token: /config set cloud.default.token <token>
         optional arguments:
         -v, --verbose         More info at response
         -s, --silent          Do not output anything
         -V, --version         Print current version
         -d, --debug           Include debug output
         -i, --include         Include raw connection data in the output
         -c CONFIG, --config CONFIG
                               Path to configuration file
         -o OPTIONS, --options OPTIONS
                               Override a config value
         --cloud CLOUD         Chose a cloud to connect to
         -h, --help            Show help message
         --since SINCE         show only items since date (' d/m/Y H:M:S ')
         --enumerate           Enumerate results
         -l, --details         show detailed output
         --more                output results in pages (-n to set items per page,
                               default 10)
         -n LIMIT, --number LIMIT
                               limit number of listed servers
         -j, --json            show headers in json
           -v, --verbose         More info at response
           -s, --silent          Do not output anything
           -V, --version         Print current version
           -d, --debug           Include debug output
           -i, --include         Include raw connection data in the output
           -c CONFIG, --config CONFIG
                                 Path to config file
           -o OPTIONS, --options OPTIONS
                                 Override a config value
           --cloud CLOUD         Chose a cloud to connect to
           -h, --help            Show help message
           --status STATUS       filter by status (ACTIVE, STOPPED, REBOOT, ERROR,
                                 etc.)
           --enumerate           Enumerate results
           --name-suffix NAME_SUFF
                                 filter by name suffix (case insensitive)
           --image-id IMAGE_ID   filter by image id
           --metadata META       filter by metadata key=values
           -j, --json            show headers in json
           --id ID               filter by id
           --user-id USER_ID     filter by user id
           --id-like ID_LIKE     print only if id contains this (case insensitive)
           --id-suffix ID_SUFF   filter by id suffix (case insensitive)
           --since SINCE         show only items since date (' d/m/Y H:M:S ')
           -l, --details         show detailed output
           --name NAME           filter by name
           --more                output results in pages (-n to set items per page,
                                 default 10)
           --name-prefix NAME_PREF
                                 filter by name prefix (case insensitive)
           -n LIMIT, --number LIMIT
                                 limit number of listed virtual servers
           --id-prefix ID_PREF   filter by id prefix (case insensitive)
           --user-name USER_NAME
                                 filter by user name
           --name-like NAME_LIKE
                                 print only if name contains this (case insensitive)
           --metadata-like META_LIKE
                                 print only if in key=value, the value is part of
                                 actual value
           --flavor-id FLAVOR_ID
                                 filter by flavor id
         Details:
         Use filtering arguments (e.g. --name-like) to manage long server lists
     .. _using-history-ref:
-...
     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>`_).
     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:
     Every command is appended at the end of that file. In order to see how to use
     history, use the kamaki help system:
     .. code-block:: console
         :emphasize-lines: 1
-...
     Debug
     """""
     In case of errors, kamaki in debug mode shows useful debug information, like
     the stack trace. Kamaki in debug mode cancels suppression of warning messages.
     When in debug mode, kamaki outputs some useful debug information (stack trace
     and http logs). Kamaki in debug mode cancels suppression of warning messages.
     To run kamaki in debug mode use the -d or --debug option.
     Verbose
     """""""
     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 presents the HTTP
     Request details as well as the full server response.
     To run kamaki in verbose mode use the *-v/- - verbose* option
     Verbose mode outputs the request and response mode, address and
     headers as well as the size of the data block, if any. Sensitive information
     (x-auth-token header and data body) are omitted by default,. Users who need
     this information may enable it through the log_token and log_data configuration
     options (see next section)
     .. tip:: Use the -o runtime option to enable config options on the fly, e.g, to
         include http data:
         .. code-block:: console
             $ kamaki server list -v -o log_data=on
     To run kamaki in debug mode use the -d or --debug option (can be combined with
     any other parameters or options)
     Logging
     """""""
     Kamaki keeps its logs in a file specified as global.log_file and its value
     defaults to ${HOME}/.kamaki.log . This value may change with a config setting::
     Kamaki keeps its logs in a file specified by the *log_file* option and it
     defaults to *${HOME}/.kamaki.log*. This configuration option can be modified::
         kamaki config set log_file /new/log/file/path
     Kamaki logs mostly the http connection requests and responses, including http
     methods, urls, parameters and headers. There is some special handling in two
     cases:
     Kamaki logs http request and response information, namely the method, URL,
     headers and data size. Sensitive information (data and token header) are
     omitted by default. There are some configuration options that can switch them
     on, though:
     * HTTP bodies are not logged by default
     * HTTP data blocks are not logged by default
         to enable logging the full http bodies, set log_data to `on`::
             kamaki config set log_data on
-...
             kamaki config delete log_token
     Verbose and Include
     """""""""""""""""""
     * The information (pid, name, date) of the processes that handle http requests
         is not logged by default, because if they are, logs are difficult to read.
         Still, they are useful for resolving race condition problems, so to enable
         logging proccess information::
     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 presents the HTTP
     Request details as well as the full server response.
             kamaki config set log_pid on
         to disable it, set if to off::
     To run kamaki in verbose mode use the -v or --verbose option
             kamaki config set log_pid off
         or delete it::
     Be default, kamaki in verbose mode prints down only the headers and the address
     information, thus hiding the data body of the request or response. To see the
     data body, the -i option can be used.
             kamaki config delete log_pid
     One-command features
     ^^^^^^^^^^^^^^^^^^^^
-...
     configuration file (it works even if the user has not set the optional
     pithos_account config option).
     .. tip:: There are better ways to list the contents of a container. Example
 .4.1 is using this method for demonstration purposes only. The suggested
         method for listing container contents is *- - container=<container>*
     Interactive shell
     -----------------
-...
     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 successful, the kamaki shell prompt
     changes to present the new context ("file" in example 4.1.1).
     changes to present the new context ("*file*" in example 4.1.1).
     .. code-block:: console
         :emphasize-lines: 1
         Example 4.1.1: Enter file commands context / group
         Example 4.1.1: Start kamaki and switch to file context
         $ kamaki
-...
         * Show available commands in current context *
         [context]: help
         ...
         [context]: ?
         ...
         * Show help for command cmd *
         [context]: help cmd
         ...
         [context]: ?cmd
         ...
     The context-level help results may change from context to context
-...
         kamaki commands:
         ================
         user  config  flavor  history  image  network  server  file
         user  config  flavor  history  image  network  server  file ...
         interactive shell commands:
         ===========================
-...
     * the flavor id
     * the image id
     It is often the case that a user who works in the context command, needs to
     create a new server, but hasn't selected a flavor or an image id, or cannot recall
     the id of that flavor or image. Therefore, it is necessary to list all
     available flavors (flavor-list) or images (image-compute-list). Both commands
     belong to different contexts.
     An average user would enter the server context and type *create -h* to check the
     syntax of the command. In that point, it would be nice to have some easy way of
     accessing the *flavor* and *image* contexts, to list and pick a flavor id and an
     image id. This is achieved with the / notation, as demonstrated in the following
     example:
     .. code-block:: console
         :emphasize-lines: 1
-...
     .. code-block:: console
         :emphasize-lines: 1
         Example 4.3.2: Set a new token from file context
         Example 4.3.2: Token suddenly expires. Set a new token from file context
         [file]: list
-...
 .  pithos (10MB, 2 objects)
 .  trash (0B, 0 objects)
     .. note:: The error messages on this example where shortened for clarity.
         Actual kamaki error messages are more helpful and descriptive.
     .. note:: The error messages on examples are shortened for clarity. Actual error
         messages are more helpful and descriptive.
     The following example compares some equivalent calls that run
     *user-authenticate* after a *file-list* 401 failure.
-...
         Example 4.3.3: Equivalent user-authenticate calls after a file-list 401
         * without kamaki interactive shell *
         * I. without kamaki interactive shell *
         $ kamaki file list
         (401) UNAUTHORIZED Access denied
         $ kamaki user authenticate
         ...
+        $
         * from top-level context *
         * II. from top-level context *
         [kamaki]: file list
         (401) UNAUTHORIZED Access denied
         [kamaki]: user authenticate
         ...
         [kamaki]
         * maximum typing *
         * III. maximum typing *
         [file]: list
         (401) UNAUTHORIZED Access denied
         [file]: exit
-...
         ...
         [user]:
         * minimum typing *
         * IV. minimum typing *
         [file]: list
         (401) UNAUTHORIZED Access denied
         [file]: /user authenticate
-...
     ^^^^^^^^^^^^
     The configuration mechanism of kamaki is detailed in the
     `setup section <setup.html>`_ and it is common for both interaction modes. In
     specific, the configuration mechanism is implemented as a command group, namely
     `config`. Using the config commands is as straightforward as any other kamaki
     commands.
     `setup section <setup.html>`_, it is accessible as *config* and it is common for
     both interaction modes. In specific, the configuration mechanism is implemented
     as  `config`. Using the config commands is as straightforward as in any other
     group of commands.
     It is often useful to set, delete or update a value. This can be managed either
     inside the config context or from any command context by using the / prefix.
-...
     In example 4.4.1 the user is going to work with only one storage container. The
     file commands use the container:path syntax, but if the user sets a container
     name as default, the container name can be omitted. This is possible by setting
     a *file.container* setting.
     name as default, the container name can be omitted.
     .. code-block:: console
         :emphasize-lines: 1
         Example 4.4.1: Set default storage container (cloud: default)
         Example 4.4.1: Set default storage container (cloud alias: default)
         [file]: list
 .  mycontainer (32MB, 2 objects)
 .  pithos (0B, 0 objects)
 .  trash (2MB, 1 objects)
           mycontainer (32MB, 2 objects)
           pithos (0B, 0 objects)
           trash (2MB, 1 objects)
         [file]: list mycontainer
 .  D mydir/
 .  20M mydir/rndm_local.file
           D mydir/
 M mydir/rndm_local.file
         [file]: /config set cloud.default.pithos_container mycontainer
         [file]: list
 .  D mydir/
 .  20M mydir/rndm_local.file
           D mydir/
 M mydir/rndm_local.file
     After a while, the user needs to work with multiple containers, therefore a
     default container is no longer needed. The *pithos_container* setting can be
-...
         [file]: /config delete cloud.default.pithos_container
         [file]: list
 .  mycontainer (32MB, 2 objects)
 .  pithos (0B, 0 objects)
 .  trash (2MB, 1 objects)
           mycontainer (32MB, 2 objects)
           pithos (0B, 0 objects)
           trash (2MB, 1 objects)
     Using history
     History modes
     ^^^^^^^^^^^^^
     There are two history modes: session and permanent. Session history keeps
-...
     Session history is only available in interactive shell mode. Users can iterate
     through past commands in the same session with the ↑ and ↓ keys. Session
     history is not stored, although syntactically correct commands are recorded
     through the permanent history mechanism.
     history is not stored, although commands are recorded through the permanent
     history mechanism.
     Permanent history is implemented as a command group and is common to both the
     one-command and shell interfaces. In specific, every syntactically correct
     command is appended in a history file (configured as `history_file` in
     settings, see `setup section <setup.html>`_ for details). Commands executed in
     one-command mode are mixed with the ones run in kamaki shell (also
     see :ref:`using-history-ref` section on this guide).
     one-command and shell interfaces. In specific, every command is appended in a
     history file (configured as `history_file` in settings, see
     `setup section <setup.html>`_ for details). Commands executed in one-command
     mode are mixed with the ones run in kamaki shell (also see
     :ref:`using-history-ref` section on this guide).
     Scripting
     ^^^^^^^^^
-...
     .. code-block:: console
         :emphasize-lines: 1,12,19,32
         * Download mycontainer1:myfile and upload it to mycontainer2:myfile
         * Download mycontainer1:myfile and upload it to mycontainer2:myfile *
         [kamaki]: file
         [file]: copy mycontainer1:somefile mycontainer1:myfile
         [file]: download mycontainer1:myfile mylocalfile
         ...
         Download completed
         [file]: upload mylocalfile mycontainer2:myfile
         [file]: upload mylocalfile mycontainer2:myfile -f
         ...
         Upload completed
         * undo the process *
-...
 .  file
 .  file copy mycontainer1:somefile mycontainer1:myfile
 .  file download mycontainer1:myfile mylocalfile
 .  file upload mylocalfile mycontainer2:myfile
 .  file upload mylocalfile mycontainer2:myfile -f
 .  file delete mycontainer1:myfile
 .  file delete mycontainer2:myfile
 .  history
-...
     scripting capabilities and combine them with kamaki one-command. Still, the
     history-run functionality might prove handy in many occasions.
     Tab completion
     ^^^^^^^^^^^^^^
     Kamaki shell features tab completion for the first level of command terms of
     the current context. Tab completion pool changes dynamically when the context
     is switched. Currently, tab completion is not supported when / is used
     (see :ref:`accessing-top-level-commands-ref` ).
     OS Shell integration
     ^^^^^^^^^^^^^^^^^^^^
-...
     Kamaki shell commits command strings to the outside shell and prints the
     results, without interacting with it. After a command is finished, kamaki shell
     returns to its initial state, which involves the current directory, as show in
     returns to its initial state, which involves the current directory, as shown in
     example 4.8.2
     .. code-block:: console

     _help = False
     _debug = False
     _include = False
     _verbose = False
     _colors = False
     kloger = None
-...
     #  Generic init auxiliary functions
     def _setup_logging(silent=False, debug=False, verbose=False, include=False):
     def _setup_logging(silent=False, debug=False, verbose=False):
         """handle logging for clients package"""
         if silent:
-...
             logger.add_stream_logger('kamaki.clients.send', logging.INFO, sfmt)
             logger.add_stream_logger('kamaki.clients.recv', logging.INFO, rfmt)
             logger.add_stream_logger(__name__, logging.INFO)
         if include:
             logger.add_stream_logger('kamaki.clients.send', logging.INFO, sfmt)
             logger.add_stream_logger('kamaki.clients.recv', logging.INFO, rfmt)
         logger.add_stream_logger(__name__, logging.WARNING)
         global kloger
         kloger = logger.get_logger(__name__)
-...
         _help = arguments['help'].value
         global _debug
         _debug = arguments['debug'].value
         global _include
         _include = arguments['include'].value
         global _verbose
         _verbose = arguments['verbose'].value
         _cnf = arguments['config']
         _silent = arguments['silent'].value
         _setup_logging(_silent, _debug, _verbose, _include)
         _setup_logging(_silent, _debug, _verbose)
         if _help or is_non_API:
             return None

         cloud=ValueArgument('Chose a cloud to connect to', ('--cloud')),
         help=Argument(0, 'Show help message', ('-h', '--help')),
         debug=FlagArgument('Include debug output', ('-d', '--debug')),
         include=FlagArgument(
             'Include raw connection data in the output', ('-i', '--include')),
         #include=FlagArgument(
         #    'Include raw connection data in the output', ('-i', '--include')),
         silent=FlagArgument('Do not output anything', ('-s', '--silent')),
         verbose=FlagArgument('More info at response', ('-v', '--verbose')),
         version=VersionArgument('Print current version', ('-V', '--version')),

         @staticmethod
         def _create_help_method(cmd_name, args, descr, syntax):
             tmp_args = dict(args)
             tmp_args.pop('options', None)
             #tmp_args.pop('options', None)
             tmp_args.pop('cloud', None)
             tmp_args.pop('debug', None)
             tmp_args.pop('verbose', None)
             tmp_args.pop('include', None)
             tmp_args.pop('silent', None)
             tmp_args.pop('config', None)
             help_parser = ArgumentParseManager(cmd_name, tmp_args)

     @command(server_cmds)
     class server_list(_init_cyclades, _optional_json, _name_filter, _id_filter):
         """List Virtual Machines accessible by user"""
         """List virtual servers accessible by user
         Use filtering arguments (e.g. --name-like) to manage long server lists
         """
         PERMANENTS = ('id', 'name')
         __doc__ += about_authentication
         arguments = dict(
             detail=FlagArgument('show detailed output', ('-l', '--details')),
             since=DateArgument(

         def wait_network(
                 self, net_id,
                 current_status='LALA', delay=1, max_wait=100, wait_cb=None):
                 current_status='PENDING', delay=1, max_wait=100, wait_cb=None):
             """Wait for network while its status is current_status
             :param net_id: integer (str or int)

Also available in: Unified diff

Synnefo » ./kamaki

Revision f6822a26