--- /dev/null
+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.
+
+Convert old configuration file
+------------------------------
+
+First, back up the old file
+
+.. code-block:: console
+
+ $ cp ~/.kamakirc ~/backups/.kamakirc
+
+Now, let kamaki do the conversion
+
+.. code-block:: console
+
+ $ kamaki user authenticate
+ . Config file format version >= 9.0 is required
+ . Configuration file: /home/someuser/.kamakirc
+ . Attempting to fix this:
+ . Calculating changes while preserving information
+ . ... rescue global.token => cloud.default.token
+ . ... rescue user.cli => global.user_cli
+ . ... rescue network.cli => global.network_cli
+ . ... rescue file.cli => global.file_cli
+ . ... rescue flavor.cli => global.flavor_cli
+ . ... rescue config.cli => global.config_cli
+ . ... rescue image.cli => global.image_cli
+ . ... rescue server.cli => global.server_cli
+ . ... rescue history.file => global.history_file
+ . ... rescue history.cli => global.history_cli
+ . ... DONE
+ . The following information will NOT be preserved:
+ . global.account = AccountName
+ . user.url = https://accounts.example.com
+ . user.account = UserAccountName
+ . compute.url = https://cyclades.example.com/api/v1.1
+ . file.url = https://pithos.example.com/v1
+ . 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]
+ .
+ <y is pressed>
+ .
+ . No cloud "default" is configured
+ . | To configure a new cloud "default", find and set the
+ . | single authentication URL and token:
+ . | kamaki config set cloud.default.url <URL>
+ . | kamaki config set cloud.default.token <t0k3n>
+ $
+
+.. warning:: A new cloud configuration with the name "default" is created. The
+ global token that was set in the old configuration file, is preserved as
+ the token of the "default" cloud. Still, kamaki needs a url for the cloud
+ and it encourages you to reset the token as well.
+
+.. note:: Some options are discarded. Among them, are the service urls, like
+ user.url, compute.url, image.url and file.url . These settings are obsolete
+ since Synnefo 0.14 and kamaki 0.9 so you do not need to recover them. The
+ same is true for user accounts (retrieved automatically)
+
+.. note:: You can safely remove the global.XXX_cli options from kamaki
+ configuration file. Kamaki can automatically resolve the default values for
+ these internal options. These options are usefull when overloading the
+ default command behaviors, but are not needed otherwise.
+
+Attempt to create a new configuration
+-------------------------------------
+
+Ask kamaki to load from a non-existing configuration file
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf user authenticate
+ . No cloud is configured
+ . | To configure a new cloud "<cloud name>", find and set the
+ . | single authentication URL and token:
+ . | kamaki config set cloud.<cloud name>.url <URL>
+ . | kamaki config set cloud.<cloud name>.token <t0k3n>
+ $ ls -l nonexisting.cnf
+ . ls: cannot access nonexisting.cnf: No such file or directory
+ $
+
+.. note:: configuration file is not created, but it will be when we set the
+ first configuration value in it, as shown in the following subsection.
+
+Configure a cloud and create a new configuration
+------------------------------------------------
+
+Set the URL for new cloud "mytest"
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
+
+Try to connect
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf user authenticate
+ . No authentication token provided for cloud "mytest"
+ . | Set a token for cloud mytest:
+ . | kamaki config set cloud.mytest.token <token>
+
+Set token to cloud "mytest"
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf config set cloud.mytest.token myt35t70k3n==
+
+Check that the file is created, everything is set up correctly and working
+
+.. code-block:: console
+
+ $ ls -l nonexisting.cnf
+ . -rw======- 1 someuser someuser 491 Jun 17 13:39 nonexisting.cnf
+ $ kamaki -c nonexisting.cnf config get cloud
+ . cloud.mytest.url = https://accounts.example.com/identity/v2.0/
+ . cloud.mytest.token = myt35t70k3n==
+ $ kamaki -c nonexisting.cnf user autenticate
+ . ...
+ . user:
+ . id: s0me-3x4mp13-u53r-1d
+ . name: Some User
+ . roles:
+ . id: 1
+ . name: default
+ . roles_links:
+ $
+
+Failed or incomplete cloud configurations
+-----------------------------------------
+
+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
+
+.. code-block:: console
+
+ $ kamaki config get cloud
+ . cloud.default.token = my0ld70k3n==
+ $ kamaki user authenticate
+ . No authentication URL provided for cloud "mytest"
+ . | Set a URL for cloud mytest:
+ . | kamaki config set cloud.mytest.url <URL>
+ $
+
+Set a non-existing URL for cloud.default and attempt authentication
+
+.. code-block:: console
+
+ $ kamaki config set cloud.default.url https://nonexisting.example.com
+ $ kamaki user authenticate
+ . Failed while http-connecting to https://nonexisting.example.com
+ $
+
+Set the URL from the previous example and attempt authentication
+
+.. code-block:: console
+
+ $ kamaki config set cloud.default.url https://accounts.example.com/identity/v2.0/
+ $ kamaki user authenticate
+ . (401) Authorization failed for token gZH99orgkfYHmGksZKvHJw==
+ . | UNAUTHORIZED unauthorized (Invalid token)
+ $
+
+After some searching at the deployments UI, you found out that the URL/token
+pair you need is::
+
+ URL: https://accounts.deploymentexample.com/identity/v2.0
+ TOKEN: myd3pl0ym3nt70k3n==
+
+Set up the correct values and attempt authentication
+
+.. code-block:: console
+
+ $ kamaki config set cloud.default.url https://accounts.deploymentexample.com/identity/v2.0
+ $ kamaki config set cloud.default.token myd3pl0ym3nt70k3n==
+ $ kamaki user authenticate
+ . ...
+ . user:
+ . id: my-d3pl0ym3nt-u53r-1d
+ . name: Example Username
+ $
+
+Multiple clouds in a single configuration
+-----------------------------------------
+
+We now have two configurations::
+
+ Configuration file: ${HOME}/.kamakirc (default)
+ Clouds:
+ ALIAS: default
+ URL: https://accounts.deploymentexample.com/identity/v2.0
+ TOKEN: myd3pl0ym3nt70k3n==
+
+ Copnfiguration file: nonexisting.cnf
+ Clouds:
+ ALIAS: mytest
+ URL: https://accounts.example.com/identity/v2.0/
+ TOKEN: myt35t70k3n==
+
+As we can see, the default configuration handles only one cloud, aliased as
+"default". We will add the second cloud as well.
+
+.. code-block:: console
+
+ $ kamaki config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
+ $ kamaki config set cloud.mytest.token myt35t70k3n==
+ $
+
+Check all clouds
+
+.. code-block:: console
+
+ $ kamaki config get cloud
+ . cloud.default.url = https://accounts.deploymentexample.com/identity/v2.0/
+ . cloud.default.token = myd3pl0ym3nt70k3n==
+ . cloud.mytest.url = https://accounts.example.com/identity/v2.0/
+ . cloud.mytest.token = myt35t70k3n==
+ $
+
+Check if kamaki knows one of the clouds to be the default
+
+.. code-block:: console
+
+ $ kamaki config get default_cloud
+ . default
+ $
+
+Authenticate against different clouds
+
+.. code-block:: console
+
+ $ kamaki user authenticate
+ . ...
+ . <response from deploymentexample.com>
+ . ...
+ $ kamaki ==cloud=mytest user authenticate
+ . ...
+ . <response from example.com>
+ . ...
+ $ kamaki ==cloud=default user authenticate
+ . ...
+ . <response from deploymentexample.com, same as default behavior>
+ . ...
+ $ kamaki ==cloud=nonexistingcloud user authenticate
+ . No cloud "nonexistingcloud" is configured
+ . | To configure a new cloud "nonexistingcloud", find and set the
+ . | single authentication URL and token:
+ . | kamaki config set cloud.nonexistingcloud.url <URL>
+ . | kamaki config set cloud.nonexistingcloud.token <t0k3n>
+ $
+
+Confuse kamaki by removing the default_cloud option, set mytest as default
+
+.. code-block:: console
+
+ $ kamaki config delete default_cloud
+ $ kamaki user authenticate
+ . Found 2 clouds but none of them is set as default
+ . | Please, choose one of the following cloud names:
+ . | default, mytest
+ . | To set a default cloud:
+ . | kamaki config set default_cloud <cloud name>
+ $ kamaki config set default_cloud mytest
+ $ kamaki user authenticate
+ . ...
+ . <response from example.com>
+ . ...
+ $
+
+`Question`: What will happen if the "default" cloud alias **and** the
+default_cloud option are removed?
+
+.. code-block:: console
+
+ $ kamaki config delete cloud.default
+ $ kamaki config delete default_cloud
+ $ kamaki user authenticate
+ . ...
+ . <response from example.com>
+ . ...
+ $
+
+`Answer`: kamaki doesn't have a default_cloud option, but there is only one
+cloud configuration (`mytest`), therefore there is no ambiguity in resolving
+the default cloud.
+
+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).
+
+Let's create the 3-threaded configuration first
+
+.. code-block:: console
+
+ $ kamaki -c 3thread config set cloud.test.url https://accounts.example.com/identity/v2.0/
+ $ kamaki -c 3thread config set cloud.test.token myt35t70k3n==
+ $
+
+Let's set the max_thread option to 3 as well as a seperate file for logs.
+
+.. code-block:: console
+
+ $ kamaki -c 3thread config set max_thread 3
+ $ kamaki -c 3thread config log_file ./logs/kamaki.3threads.log
+ $
+
+Now, let's create the 5-threaded configuration by modifying a copy of 3thread
+
+.. code-block:: console
+
+ $ cp 3thread 5thread
+ $ kamaki -c 5thread config set max_thread 5
+ $ kamaki -c 5thread config log_file ./logs/kamaki.5threads.log
+ $
+
+Use kamaki to upload with 3 threads and 5 threads respectively
+
+.. code-block:: console
+
+ $ kamaki -c 3thread file upload testfiles/test1 testcontainer
+ $ kamaki -c 5thread file upload testfiles/test1 testcontainer
+ $
--- /dev/null
+Examples
+========
+
+This section contains a collection of the most common operations with kamaki.
+
+.. note:: all examples bellow use `bash` in a linux enviroment, but they can be
+ replicated in a reasonable command line shell in any popular platform.
+
+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.
+
+Convert old configuration file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First, back up the old file
+
+.. code-block:: console
+
+ $ cp ~/.kamakirc ~/backups/.kamakirc
+
+Now, let kamaki do the conversion
+
+.. code-block:: console
+
+ $ kamaki user authenticate
+ . Config file format version >= 9.0 is required
+ . Configuration file: /home/someuser/.kamakirc
+ . Attempting to fix this:
+ . Calculating changes while preserving information
+ . ... rescue global.token => cloud.default.token
+ . ... rescue user.cli => global.user_cli
+ . ... rescue network.cli => global.network_cli
+ . ... rescue file.cli => global.file_cli
+ . ... rescue flavor.cli => global.flavor_cli
+ . ... rescue config.cli => global.config_cli
+ . ... rescue image.cli => global.image_cli
+ . ... rescue server.cli => global.server_cli
+ . ... rescue history.file => global.history_file
+ . ... rescue history.cli => global.history_cli
+ . ... DONE
+ . The following information will NOT be preserved:
+ . global.account = AccountName
+ . user.url = https://accounts.example.com
+ . user.account = UserAccountName
+ . compute.url = https://cyclades.example.com/api/v1.1
+ . file.url = https://pithos.example.com/v1
+ . 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]
+ .
+ <y is pressed>
+ .
+ . No cloud "default" is configured
+ . | To configure a new cloud "default", find and set the
+ . | single authentication URL and token:
+ . | kamaki config set cloud.default.url <URL>
+ . | kamaki config set cloud.default.token <t0k3n>
+ $
+
+.. warning:: A new cloud configuration with the name "default" is created. The
+ global token that was set in the old configuration file, is preserved as
+ the token of the "default" cloud. Still, kamaki needs a url for the cloud
+ and it encourages you to reset the token as well.
+
+.. note:: Some options are discarded. Among them, are the service urls, like
+ user.url, compute.url, image.url and file.url . These settings are obsolete
+ since Synnefo 0.14 and kamaki 0.9 so you do not need to recover them. The
+ same is true for user accounts (retrieved automatically)
+
+.. note:: You can safely remove the global.XXX_cli options from kamaki
+ configuration file. Kamaki can automatically resolve the default values for
+ these internal options. These options are usefull when overloading the
+ default command behaviors, but are not needed otherwise.
+
+Attempt to create a new configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Ask kamaki to load from a non-existing configuration file
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf user authenticate
+ . No cloud is configured
+ . | To configure a new cloud "<cloud name>", find and set the
+ . | single authentication URL and token:
+ . | kamaki config set cloud.<cloud name>.url <URL>
+ . | kamaki config set cloud.<cloud name>.token <t0k3n>
+ $ ls -l nonexisting.cnf
+ . ls: cannot access nonexisting.cnf: No such file or directory
+ $
+
+.. note:: configuration file is not created, but it will be when we set the
+ first configuration value in it, as shown in the following subsection.
+
+Configure a cloud and create a new configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set the URL for new cloud "mytest"
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
+
+Try to connect
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf user authenticate
+ . No authentication token provided for cloud "mytest"
+ . | Set a token for cloud mytest:
+ . | kamaki config set cloud.mytest.token <token>
+
+Set token to cloud "mytest"
+
+.. code-block:: console
+
+ $ kamaki -c nonexisting.cnf config set cloud.mytest.token myt35t70k3n==
+
+Check that the file is created, everything is set up correctly and working
+
+.. code-block:: console
+
+ $ ls -l nonexisting.cnf
+ . -rw------- 1 someuser someuser 491 Jun 17 13:39 nonexisting.cnf
+ $ kamaki -c nonexisting.cnf config get cloud
+ . cloud.mytest.url = https://accounts.example.com/identity/v2.0/
+ . cloud.mytest.token = myt35t70k3n==
+ $ kamaki -c nonexisting.cnf user autenticate
+ . ...
+ . user:
+ . id: s0me-3x4mp13-u53r-1d
+ . name: Some User
+ . roles:
+ . id: 1
+ . name: default
+ . roles_links:
+ $
+
+Failed or incomplete cloud configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+
+.. code-block:: console
+
+ $ kamaki config get cloud
+ . cloud.default.token = my0ld70k3n==
+ $ kamaki user authenticate
+ . No authentication URL provided for cloud "mytest"
+ . | Set a URL for cloud mytest:
+ . | kamaki config set cloud.mytest.url <URL>
+ $
+
+Set a non-existing URL for cloud.default and attempt authentication
+
+.. code-block:: console
+
+ $ kamaki config set cloud.default.url https://nonexisting.example.com
+ $ kamaki user authenticate
+ . Failed while http-connecting to https://nonexisting.example.com
+ $
+
+Set the URL from the previous example and attempt authentication
+
+.. code-block:: console
+
+ $ kamaki config set cloud.default.url https://accounts.example.com/identity/v2.0/
+ $ kamaki user authenticate
+ . (401) Authorization failed for token gZH99orgkfYHmGksZKvHJw==
+ . | UNAUTHORIZED unauthorized (Invalid token)
+ $
+
+After some searching at the deployments UI, you found out that the URL/token
+pair you need is::
+
+ URL: https://accounts.deploymentexample.com/identity/v2.0
+ TOKEN: myd3pl0ym3nt70k3n==
+
+Set up the correct values and attempt authentication
+
+.. code-block:: console
+
+ $ kamaki config set cloud.default.url https://accounts.deploymentexample.com/identity/v2.0
+ $ kamaki config set cloud.default.token myd3pl0ym3nt70k3n==
+ $ kamaki user authenticate
+ . ...
+ . user:
+ . id: my-d3pl0ym3nt-u53r-1d
+ . name: Example Username
+ $
+
+Multiple clouds in a single configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We now have two configurations::
+
+ Configuration file: ${HOME}/.kamakirc (default)
+ Clouds:
+ ALIAS: default
+ URL: https://accounts.deploymentexample.com/identity/v2.0
+ TOKEN: myd3pl0ym3nt70k3n==
+
+ Copnfiguration file: nonexisting.cnf
+ Clouds:
+ ALIAS: mytest
+ URL: https://accounts.example.com/identity/v2.0/
+ TOKEN: myt35t70k3n==
+
+As we can see, the default configuration handles only one cloud, aliased as
+"default". We will add the second cloud as well.
+
+.. code-block:: console
+
+ $ kamaki config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
+ $ kamaki config set cloud.mytest.token myt35t70k3n==
+ $
+
+Check all clouds
+
+.. code-block:: console
+
+ $ kamaki config get cloud
+ . cloud.default.url = https://accounts.deploymentexample.com/identity/v2.0/
+ . cloud.default.token = myd3pl0ym3nt70k3n==
+ . cloud.mytest.url = https://accounts.example.com/identity/v2.0/
+ . cloud.mytest.token = myt35t70k3n==
+ $
+
+Check if kamaki knows one of the clouds to be the default
+
+.. code-block:: console
+
+ $ kamaki config get default_cloud
+ . default
+ $
+
+Authenticate against different clouds
+
+.. code-block:: console
+
+ $ kamaki user authenticate
+ . ...
+ . <response from deploymentexample.com>
+ . ...
+ $ kamaki --cloud=mytest user authenticate
+ . ...
+ . <response from example.com>
+ . ...
+ $ kamaki --cloud=default user authenticate
+ . ...
+ . <response from deploymentexample.com, same as default behavior>
+ . ...
+ $ kamaki --cloud=nonexistingcloud user authenticate
+ . No cloud "nonexistingcloud" is configured
+ . | To configure a new cloud "nonexistingcloud", find and set the
+ . | single authentication URL and token:
+ . | kamaki config set cloud.nonexistingcloud.url <URL>
+ . | kamaki config set cloud.nonexistingcloud.token <t0k3n>
+ $
+
+Confuse kamaki by removing the default_cloud option, set mytest as default
+
+.. code-block:: console
+
+ $ kamaki config delete default_cloud
+ $ kamaki user authenticate
+ . Found 2 clouds but none of them is set as default
+ . | Please, choose one of the following cloud names:
+ . | default, mytest
+ . | To set a default cloud:
+ . | kamaki config set default_cloud <cloud name>
+ $ kamaki config set default_cloud mytest
+ $ kamaki user authenticate
+ . ...
+ . <response from example.com>
+ . ...
+ $
+
+`Question`: What will happen if the "default" cloud alias **and** the
+default_cloud option are removed?
+
+.. code-block:: console
+
+ $ kamaki config delete cloud.default
+ $ kamaki config delete default_cloud
+ $ kamaki user authenticate
+ . ...
+ . <response from example.com>
+ . ...
+ $
+
+`Answer`: kamaki doesn't have a default_cloud option, but there is only one
+cloud configuration (`mytest`), therefore there is no ambiguity in resolving
+the default cloud.
+
+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).
+
+Let's create the 3-threaded configuration first
+
+.. code-block:: console
+
+ $ kamaki -c 3thread config set cloud.test.url https://accounts.example.com/identity/v2.0/
+ $ kamaki -c 3thread config set cloud.test.token myt35t70k3n==
+ $
+
+Let's set the max_thread option to 3 as well as a seperate file for logs.
+
+.. code-block:: console
+
+ $ kamaki -c 3thread config set max_thread 3
+ $ kamaki -c 3thread config log_file ./logs/kamaki.3threads.log
+ $
+
+Now, let's create the 5-threaded configuration by modifying a copy of 3thread
+
+.. code-block:: console
+
+ $ cp 3thread 5thread
+ $ kamaki -c 5thread config set max_thread 5
+ $ kamaki -c 5thread config log_file ./logs/kamaki.5threads.log
+ $
+
+Use kamaki to upload with 3 threads and 5 threads respectively
+
+.. code-block:: console
+
+ $ kamaki -c 3thread file upload testfiles/test1 testcontainer
+ $ kamaki -c 5thread file upload testfiles/test1 testcontainer
+ $
+
+List
+----
+
+Simple listing
+^^^^^^^^^^^^^^
+
+Detailed listing
+^^^^^^^^^^^^^^^^
+
+Filtered listing
+^^^^^^^^^^^^^^^^
+
+Upload and download
+-------------------
+
+Upload a file, download an object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Recursive upload (directory)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Recursive download (path prefix)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Publish and share
+-----------------
+
+Check permissions
+^^^^^^^^^^^^^^^^^
+
+Publish
+^^^^^^^
+
+Share with users and groups
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Share with all
+^^^^^^^^^^^^^^
+
+Shared with me
+--------------
+
+Users who share objects with me
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+List shared objects
+^^^^^^^^^^^^^^^^^^^
+
+Copy shared objects
+^^^^^^^^^^^^^^^^^^^
+
+Image register
+--------------
+
+Upload and register image
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Register with metadata template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Upload and register multiple images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+virtual machines
+----------------
+
+Create a server
+^^^^^^^^^^^^^^^
+
+Inject ssh keys
+^^^^^^^^^^^^^^^
+
+Inject user profiles
+^^^^^^^^^^^^^^^^^^^^
+
+Connect and disconnect to a network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Networks
+--------
+
+Create a private network
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Connect VMs on it
+^^^^^^^^^^^^^^^^^
+
+Destroy a private network
+^^^^^^^^^^^^^^^^^^^^^^^^^
--- /dev/null
+Listing
+=======
+
+In this section we present the ways of kamaki for listing, an operation that is
+common to most command groups.
+
+The examples of this section run in a kamaki interactive shell.
+
+.. code-block:: console
+
+ $ kamaki
+ kamaki v0.9 - Interactive Shell
+ .
+ /exit terminate kamaki
+ exit or ^D exit context
+ ? or help available commands
+ ?command help on command
+ !<command> execute OS shell command
+ .
+ [kamaki]:
+
+Simple listing
+--------------
+
+List configuration options, whether in the file or in memory
+
+.. code-block:: console
+
+ [kamaki]: config list
+ cloud.default.url = https://astakos.example.com/identity/v2.0/
+ cloud.default.token = my70k3n==
+ global.default_cloud = default
+ global.colors = on
+ global.config_cli = config
+ global.file_cli = pithos
+ global.flavor_cli = cyclades
+ global.history_cli = history
+ global.history_file = /home/saxtouri/.kamaki.history
+ global.image_cli = image
+ global.log_file = /home/saxtouri/.kamaki.log
+ global.log_token = one
+ global.max_threads = 5
+ global.network_cli = cyclades
+ global.server_cli = cyclades
+ global.user_cli = astakos
+ [kamaki]:
+
+List stored containers and then objects in container "pithos"
+
+.. code-block:: console
+
+ [kamaki]: file list
+ pithos (36MB, 4 objects)
+ trash (0B, 0 objects)
+ [kamaki]: file list pithos
+ . 2KB info.txt
+ . D video/
+ . 11MB video/tk1.mpg
+ . 12MB video/tk2.mpg
+ . 13MB video/tk3.mpg
+ [kamaki]:
+
+List virtual machines (servers)
+
+.. code-block:: console
+
+ [kamaki]: server list
+ 4201 example server 1
+ 4202 example server 2
+
+List networks
+
+.. code-block:: console
+
+ [kamaki]: network list
+ 1 public_network
+ 42 my_private)network
+ [kamaki]:
+
+List flavors
+
+.. code-block:: console
+
+ [kamaki]: flavor list
+ 1 C1R1024D20drbd
+ 2 C1R1024D30drbd
+ [kamaki]:
+
+List images from Image API and from Compute APIs
+
+.. code-block:: console
+
+ [kamaki]: image list
+ cde9858c-0656-4da1-8cbd-33481b29a8bd Debian Base
+ .container_format: bare
+ .disk_format: diskdump
+ .size: 474066944
+ .status: available
+ a5ca5997-c580-4d62-b012-05c5329f8e2d Debian Base
+ .container_format: bare
+ .disk_format: diskdump
+ .size: 474066944
+ .status: available
+ [kamaki]: image compute list
+ a5ca5997-c580-4d62-b012-05c5329f8e2d Debian Base
+ cde9858c-0656-4da1-8cbd-33481b29a8bd Debian Base
+ [kamaki]:
+
+Detailed pithos listing
+-----------------------
+
+List pithos containers with details
+
+.. code-block:: console
+
+ [kamaki]: file
+ [file]: list -l
+ pithos
+ bytes: 0 (0B)
+ count: 3
+ modified: 2013-06-17T12:35:11.613124+00:00
+ policy:
+ . quota: 0
+ . versioning: auto
+ trash
+ bytes: 0 (0B)
+ count: 0
+ modified: 2013-06-06T14:24:23.675891+00:00
+ policy:
+ . quota: 0
+ . versioning: auto
+ [file]:
+
+Create some more pithos container to experiment with
+
+.. code-block:: console
+
+ [file]: create cont1
+ [file]: create cont2
+ [file]: create cont3
+ [file]: create cont4
+ [file]: list
+ cont1 (0B, 0 objects)
+ cont2 (0B, 0 objects)
+ cont3 (0B, 0 objects)
+ cont4 (0B, 0 objects)
+ pithos (36B, 5 objects)
+ trash (0B, 0 objects)
+ [file]:
+
+List only 3, then list three by three
+
+.. code-block:: console
+
+ [file]: list -n 3
+ cont1 (0B, 0 objects)
+ cont2 (0B, 0 objects)
+ cont3 (0B, 0 objects)
+ [file]: list -n 3 --more
+ cont1 (0B, 0 objects)
+ cont2 (0B, 0 objects)
+ cont3 (0B, 0 objects)
+ (3 listed - 3 more - "enter" to continue)
+ <enter is pressed>
+ cont4 (0B, 0 objects)
+ pithos (36B, 4 objects)
+ trash (0B, 0 objects)
+ [file]:
+
+List contents of container `pithos`
+
+.. code-block:: console
+
+ [file]: list -l pithos
+ info.txt
+ by: s0m3-u53r-1d
+ bytes: 2000 (2ΚB)
+ hash: 427ae41e4649b934ca495991b7852b855e3b0c44298fc1c149afbf4c8996fb92
+ modified: 2013-06-17T13:09:44.529579+00:00
+ timestamp: 1371474584.5295789
+ type: plan-text/unicode
+ uuid: 0493f1d9-9410-4f4b-a81f-fe42f9cefa70
+ version: 1085
+ .
+ video
+ by: s0m3-u53r-1d
+ bytes: 0
+ hash: e3b0c44298fc1c149afbf44ca495991b7852b855c8996fb92427ae41e4649b93
+ modified: 2013-06-17T13:11:39.050090+00:00
+ timestamp: 1371474699.0500901
+ type: application/directory
+ uuid: 80e719f5-9d68-4333-9846-9943972ef1fd
+ version: 1086
+ .
+ video/tk1.mpg
+ by: s0m3-u53r-1d
+ bytes: 11000000 (11ΜΒB)
+ hash: fbf4c8996fb92427ae41e464e3b0c44298fc1c5991b7852b855149a9b934ca49
+ modified: 2013-06-17T13:09:15.866515+00:00
+ timestamp: 1371474555.8665149
+ type: video/mpeg
+ uuid: b0b46b39-c59a-4adc-a386-6a169cb9f8a5
+ version: 1079
+ .
+ video/tk2.mpg
+ by: s0m3-u53r-1d
+ bytes: 12000000 (12MB)
+ hash: 44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b78e3b0c52b855
+ modified: 2013-06-17T13:09:23.898652+00:00
+ timestamp: 1371474563.8986521
+ type: video/mpeg
+ uuid: 12a81309-db3c-4e30-ae9a-4ac2b8289def
+ version: 1081
+ .
+ video/tk3.mpg
+ by: s0m3-u53r-1d
+ bytes: 13000000 (13MB)
+ hash: 1e4649b934ca495991b7852b855e3b0c44298fc1c149afbf4c8996fb92427ae4
+ modified: 2013-06-17T13:09:28.222536+00:00
+ timestamp: 1371474568.2225361
+ type: video/mpeg
+ uuid: 4195e8c3-9b9a-4e97-8c20-fdfef34892fe
+ version: 1083
+ [kamaki]:
+
+List only videos and exit "file" context
+
+.. code-block:: console
+
+ [file]: list -l pithos:video/
+ video/tk1.mpg
+ by: s0m3-u53r-1d
+ bytes: 11000000 (11ΜΒB)
+ hash: fbf4c8996fb92427ae41e464e3b0c44298fc1c5991b7852b855149a9b934ca49
+ modified: 2013-06-17T13:09:15.866515+00:00
+ timestamp: 1371474555.8665149
+ type: video/mpeg
+ uuid: b0b46b39-c59a-4adc-a386-6a169cb9f8a5
+ version: 1079
+ .
+ video/tk2.mpg
+ by: s0m3-u53r-1d
+ bytes: 12000000 (12MB)
+ hash: 44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b78e3b0c52b855
+ modified: 2013-06-17T13:09:23.898652+00:00
+ timestamp: 1371474563.8986521
+ type: video/mpeg
+ uuid: 12a81309-db3c-4e30-ae9a-4ac2b8289def
+ version: 1081
+ .
+ video/tk3.mpg
+ by: s0m3-u53r-1d
+ bytes: 13000000 (13MB)
+ hash: 1e4649b934ca495991b7852b855e3b0c44298fc1c149afbf4c8996fb92427ae4
+ modified: 2013-06-17T13:09:28.222536+00:00
+ timestamp: 1371474568.2225361
+ type: video/mpeg
+ uuid: 4195e8c3-9b9a-4e97-8c20-fdfef34892fe
+ version: 1083
+ [kamaki]:
--- /dev/null
+Examples
+========
+
+.. toctree::
+ :numbered:
+ :glob:
+
+ collection_of_examples/configuration
+ collection_of_examples/listing
setup
usage
commands
- scenarios
+ examples
devguide
+++ /dev/null
-Scenarios
-=========
-
-Configuration
--------------
-
-Create a new configuration file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Convert an old configuration file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Configure a cloud
-^^^^^^^^^^^^^^^^^
-
-Multiple clouds in single configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Multiple configurations
-^^^^^^^^^^^^^^^^^^^^^^^
-
-List
-----
-
-Simple listing
-^^^^^^^^^^^^^^
-
-Detailed listing
-^^^^^^^^^^^^^^^^
-
-Filtered listing
-^^^^^^^^^^^^^^^^
-
-Upload and download
--------------------
-
-Upload a file, download an object
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Recursive upload (directory)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Recursive download (path prefix)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Publish and share
------------------
-
-Check permissions
-^^^^^^^^^^^^^^^^^
-
-Publish
-^^^^^^^
-
-Share with users and groups
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Share with all
-^^^^^^^^^^^^^^
-
-Shared with me
---------------
-
-Users who share objects with me
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-List shared objects
-^^^^^^^^^^^^^^^^^^^
-
-Copy shared objects
-^^^^^^^^^^^^^^^^^^^
-
-Image register
---------------
-
-Upload and register image
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Register with metadata template
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Upload and register multiple images
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Servers (virtual machines)
---------------------------
-
-Create a server
-^^^^^^^^^^^^^^^
-
-Inject ssh keys
-^^^^^^^^^^^^^^^
-
-Inject user profiles
-^^^^^^^^^^^^^^^^^^^^
-
-Connect and disconnect to a network
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Networks
---------
-
-Create a private network
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Connect VMs on it
-^^^^^^^^^^^^^^^^^
auth_args[term] = ''
if not auth_args[term]:
raise CLIError(
- 'No authentication %s provided for cloud "%s"' % (term, cloud),
+ 'No authentication %s provided for cloud "%s"' % (
+ term.upper(), cloud),
importance=3, details=[
- 'Set a %s for cloud %s:' % (term, cloud),
+ 'Set a %s for cloud %s:' % (term.upper(), cloud),
' kamaki config set cloud.%s.%s <%s>' % (
- cloud, term, term)])
+ cloud, term, term.upper())])
from kamaki.clients.astakos import AstakosClient as AuthCachedClient
try: