Commit 0ea31480 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Update docs, rename kamaki.cli.commands/*

Documentation updates: reflect the changes in command groups
    astakos --> user, store --> file

File renaming: remove the _cli suffix from modules in kamaki.cli.commands

Feature #3566
parent 3ae60112
......@@ -4,8 +4,8 @@ List of commands
The commands described bellow are grouped by service. The examples showcase a sample set of group commands. The kamaki interactive shell (check `Usage section <usage.html#interactive-shell>`_ for details) is chosen as the execution environment.
astakos (Identity Manager)
--------------------------
user (Identity Manager)
-----------------------
.. code-block:: text
......@@ -19,11 +19,11 @@ In the following, the token has been set in a previous step (see `setup section
.. code-block:: console
:emphasize-lines: 1,4
* Enter astakos context *
[kamaki]:astakos
* Enter user context *
[kamaki]: user
* Authenticate user *
[astakos]:authenticate
[user]: authenticate
auth_token_created: 2012-11-13T14:12:40.917034
auth_token_expires: 2012-12-13T14:12:40.917035
email :
......@@ -88,10 +88,10 @@ Showcase: Pick an image and list the properties
:emphasize-lines: 1,4,18
* Enter image context *
[kamaki]:image
[kamaki]: image
* list all available images *
[image]:list
[image]: list
1. Windows Server 2008
container_format: bare
disk_format : diskdump
......@@ -118,7 +118,7 @@ Showcase: Pick an image and list the properties
status : available
* Get properties of image with id 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe *
[image]:compute properties 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
[image]: compute properties 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
description : Debian 6.0.6 (Squeeze) Base System
gui : No GUI
kernel : 2.6.32
......@@ -158,10 +158,10 @@ Showcase: Create a server
:emphasize-lines: 1,4,21,35,44,62
* Enter server context *
[kamaki]:server
[kamaki]: server
* See server-create help *
[server]:create -h
[server]: create -h
usage: create <name> <flavor id> <image id>
[--personality PERSONALITY] [-h] [--config CONFIG]
......@@ -178,7 +178,7 @@ Showcase: Create a server
-s, --silent Do not output anything
* List all available images *
[server]:/image compute list
[server]: /image compute list
1395fdfb-51b4-419f-bb02-f7d632860611 Ubuntu Desktop LTS
1580deb4-edb3-4496-a27f-7a246c4c0528 Ubuntu Desktop
18a82962-43eb-4b32-8e28-8f8880af89d7 Kubuntu LTS
......@@ -192,7 +192,7 @@ Showcase: Create a server
c1d27b46-d875-4f5c-b7f1-f39b5af62905 Kubuntu
* See details of flavor with id 1 *
[server]:/flavor info 1
[server]: /flavor info 1
SNF:disk_template: drbd
cpu : 1
disk : 20
......@@ -201,7 +201,7 @@ Showcase: Create a server
ram : 1024
* Create a debian server named 'My Small Debian Server'
[server]:create 'My Small Debian Server' 1 b2dffe52-64a4-48c3-8a4c-8214cc3165cf
[server]: create 'My Small Debian Server' 1 b2dffe52-64a4-48c3-8a4c-8214cc3165cf
adminPass: L8gu2wbZ94
created : 2012-11-23T16:56:04.190813+00:00
flavorRef: 1
......@@ -219,7 +219,7 @@ Showcase: Create a server
updated : 2012-11-23T16:56:04.761962+00:00
* wait for server to build (optional) *
[server]:wait 11687
[server]: wait 11687
Server 11687 still in BUILD mode ||||||||||||||||| | 80%
Server 11687 is now in ACTIVE mode
......@@ -245,15 +245,15 @@ Showcase: Connect a network to a VM
:emphasize-lines: 1,4,9,24,27,44
* Enter network context *
[kamaki]:network
[kamaki]: network
* List user-owned VMs *
[network]:/server list
[network]: /server list
11687 (My Small Debian Server)
11688 (An Ubuntu server)
* Try network-connect (to get help) *
[network]:connect
[network]: connect
Syntax error
usage: connect <server id> <network id> [-s] [-h] [-i] [--config CONFIG]
......@@ -271,7 +271,7 @@ Showcase: Connect a network to a VM
[network]: connect 11687 1409
* Get details on network with id 1409
[network]:info 1409
[network]: info 1409
attachments:
nic-11687-1
cidr : 192.168.1.0/24
......@@ -288,7 +288,7 @@ Showcase: Connect a network to a VM
updated : 2012-11-23T17:18:25.095225+00:00
* Get connectivity details on VM with id 11687 *
[network]:/server addr 11687
[network]: /server addr 11687
id: nic-11687-1
ipv4 : 192.168.1.1
ipv6 : None
......@@ -303,8 +303,8 @@ Showcase: Connect a network to a VM
.. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
store (Storage/Pithos+)
-----------------------
file (Storage/Pithos+)
----------------------
.. code-block:: text
......@@ -350,27 +350,27 @@ Showcase: Upload and download a file
:emphasize-lines: 1,7,11,16,21,29,33,37,41,44,51,55,60,64
* Create a random binarry file at current OS path *
[kamaki]:!dd bs=4M if=/dev/zero of=rndm_local.file count=5
[kamaki]: !dd bs=4M if=/dev/zero of=rndm_local.file count=5
5+0 records in
5+0 records out
20971520 bytes (21 MB) copied, 0.016162 s, 1.3 GB/s
* Enter store context *
[kamaki]:store
* Enter file context *
[kamaki]: file
* Check local file *
[store]:!ls -lh rndm_local.file
[file]: !ls -lh rndm_local.file
-rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
* Create two containers *
[store]:create mycont1
[store]:create mycont2
[file]: create mycont1
[file]: create mycont2
* List accessible containers *
[store]:list
[file]: list
1. mycont1 (0B, 0 objects)
2. mycont2 (0B, 0 objects)
3. pithos (0B, 0 objects)
......@@ -378,48 +378,48 @@ Showcase: Upload and download a file
* Upload local file to 1st container *
[store]:upload rndm_local.file mycont1
[file]: upload rndm_local.file mycont1
* Check if file has been uploaded *
[store]:list mycont1
[file]: list mycont1
1. 20M rndm_local.file
* Create directory mydir on second container *
[store]:mkdir mycont2:mydir
[file]: mkdir mycont2:mydir
* Move file from 1st to 2nd container (and in the directory) *
[store]:move mycont1:rndm_local.file mycont2:mydir/rndm_local.file
[file]: move mycont1:rndm_local.file mycont2:mydir/rndm_local.file
* Check contents of both containers *
[store]:list mycont1
[store]:list mycont2
[file]: list mycont1
[file]: list mycont2
1. D mydir/
2. 20M mydir/rndm_local.file
* Copy file from 2nd to 1st container, with a new name *
[store]:copy mycont2:mydir/rndm_local.file mycont1:rndm_remote.file
[file]: copy mycont2:mydir/rndm_local.file mycont1:rndm_remote.file
* Check pasted file *
[store]:list mycont1
[file]: list mycont1
1. 20M rndm_remote.file
* Download pasted file to local file system *
[store]:download mycont1:rndm_remote.file rndm_remote.file
[file]: download mycont1:rndm_remote.file rndm_remote.file
* Check if file is downloaded and if it is the same to original *
[store]:!ls -lh *.file
[file]: !ls -lh *.file
-rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
-rw-rw-r-- 1 ******** ******** 20M Nov 26 15:42 rndm_remote.file
[store]:!diff rndm_local.file rndm_remote.file
[file]: !diff rndm_local.file rndm_remote.file
.. Note:: In kamaki shell, ! is used to execute OS shell commands (bash in the above)
.. 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 ::
$ kamaki store copy --container=grnet:dev test.py --dst-container=grnet:deploy
$ kamaki file copy --container=grnet:dev test.py --dst-container=grnet:deploy
......@@ -42,9 +42,9 @@ The above example will be used throughout the present guide for clarification pu
The CommandTree structure
-------------------------
CommandTree manages a command by its path. Each command is stored in multiple nodes on the tree, so that the last term is a leaf and the route from root to that leaf represents the command path. For example the commands *store upload*, *store list* and *store info* are stored together as shown bellow::
CommandTree manages a command by its path. Each command is stored in multiple nodes on the tree, so that the last term is a leaf and the route from root to that leaf represents the command path. For example the commands *file upload*, *file list* and *file info* are stored together as shown bellow::
- store
- file
''''''''|- info
|- list
|- upload
......@@ -125,7 +125,7 @@ The description of each command is the first line of the class commend. The foll
Declare run-time argument
-------------------------
The argument mechanism allows the definition of run-time arguments. Some basic argument types are defined at the `argument module <code.html#module-kamaki.cli.argument>`_, but it is not uncommon to extent these classes in order to achieve specialized type checking and syntax control (e.g. at `pithos_cli module <code.html#module-kamaki.cli.commands.pithos_cli>`_).
The argument mechanism allows the definition of run-time arguments. Some basic argument types are defined at the `argument module <code.html#module-kamaki.cli.argument>`_, but it is not uncommon to extent these classes in order to achieve specialized type checking and syntax control (e.g. at `pithos cli module <code.html#module-kamaki.cli.commands.pithos>`_).
To declare a run-time argument on a specific command, the object class should initialize a dict called *arguments* , where Argument objects are stored. Each argument object is a possible run-time argument. Syntax checking happens at client level, while the type checking is implemented in the Argument code (thus, many different Argument types might be needed).
......
......@@ -6,7 +6,7 @@ Kamaki features a clients API for building third-party client applications that
A good example of an application build on kamaki.clients is kamaki.cli, the command line interface of kamaki.
Since synnefo services are build as OpenStack extensions, an inheritance approach has been chosen for implementing clients for both. In specific, the *compute*, *storage* and *image* modules are clients of the OS compute, OS storage, respectively. On the contrary, all the other modules are Synnefo extensions (*cyclades* extents *compute*, *pithos* and *pithos_rest_api* extent *storage*) or novel synnefo services (e.g. *astakos*, *image* for *plankton*).
Since synnefo services are build as OpenStack extensions, an inheritance approach has been chosen for implementing clients for both. In specific, the *compute*, *storage* and *image* modules are clients of the OS compute, OS storage, respectively. On the contrary, all the other modules are Synnefo extensions (*cyclades* extents *compute*, *pithos* and *pithos_rest_api* extent *storage*) or novel synnefo services (e.g. *astakos* for IM, *image* for *plankton*).
Setup a client instance
-----------------------
......@@ -27,7 +27,7 @@ External applications may instantiate one or more kamaki clients.
.. note:: *cyclades* and *pithos* clients inherit all methods of *compute* and *storage* clients respectively. Separate compute or storage objects should be used only when implementing applications for strict OS Compute or OS Storage services.
.. note:: *account* variable is usually acquired by the following astakos call
.. note:: *account* variable is usually acquired by the following user call
.. code-block:: python
......
......@@ -6,31 +6,31 @@ APIs code
Command Specifications
----------------------
astakos
^^^^^^^
user
^^^^
.. automodule:: kamaki.cli.commands.astakos_cli
.. automodule:: kamaki.cli.commands.user
:members:
:undoc-members:
cyclades (server, flavor, network)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: kamaki.cli.commands.cyclades_cli
.. automodule:: kamaki.cli.commands.cyclades
:members:
:undoc-members:
pithos (store)
^^^^^^^^^^^^^^
pithos (file)
^^^^^^^^^^^^^
.. automodule:: kamaki.cli.commands.pithos_cli
.. automodule:: kamaki.cli.commands.pithos
:members:
:undoc-members:
image
^^^^^
.. automodule:: kamaki.cli.commands.image_cli
.. automodule:: kamaki.cli.commands.image
:members:
:undoc-members:
......@@ -40,14 +40,14 @@ Kamaki commands
config
""""""
.. automodule:: kamaki.cli.commands.config_cli
.. automodule:: kamaki.cli.commands.config
:members:
:undoc-members:
history
"""""""
.. automodule:: kamaki.cli.commands.history_cli
.. automodule:: kamaki.cli.commands.history
:members:
:undoc-members:
......
......@@ -36,9 +36,9 @@ history
Access kamaki user history, which is stored in ~/.kamaki.history file.
astakos
user
Get information from astakos API
Get information from Astakos API
server
......@@ -56,9 +56,9 @@ image
Manage images on Plankton (and Compute).
store
file
Manage store API.
Manage Pithos+ API.
Hidden command groups
......@@ -67,13 +67,13 @@ Hidden command groups
quotaholder
A client for quotaholder API. to enable:
kamaki config set quotaholder.cli hotaholder_cli
kamaki config set quotaholder.cli hotaholder
kamaki config set quotaholder.url <quotaholder server url>
livetest
LIve tests that check kamaki against running services. To enable:
kamaki config set livetest.cli livetest_cli
kamaki config set livetest.cli livetest
Options
......@@ -109,8 +109,8 @@ Command user history, as stored in ~/.kamaki.history
* run run/show previously executed command(s)
astakos commands
****************
user commands
*************
* authenticate Authenticate a user, show user information
......@@ -181,7 +181,7 @@ network commands
* rename Set the name of a network
store commands
file commands
**************
* append Append local file to (existing) remote object
......@@ -230,7 +230,7 @@ test commands (hidden)
**********************
* all test all clients
* args Test how arguments are treated by kamaki
* args test how arguments are treated by kamaki
* astakos test Astakos client
* cyclades test Cyclades client
* error Create an error message with optional message
......
......@@ -62,13 +62,13 @@ All kamaki commands can be used with the -o option in order to override configur
.. code-block:: console
$ kamaki store list -o global.account=anotheraccount -o global.token=aT0k3n==
$ kamaki file list -o global.account=anotheraccount -o global.token=aT0k3n==
will invoke *kamaki store list* with the specified options, but the initial global.account and global.token values will be restored to initial values afterwards.
will invoke *kamaki file list* with the specified options, but the initial global.account and global.token values will be restored to initial values afterwards.
.. note:: on-the-fly calls to store require users to explicetely provide the account uuid corresponding to this token. The account is actually the uuid field at the response of the following call::
.. note:: on-the-fly calls to file require users to explicetely provide the account uuid corresponding to this token. The account is actually the uuid field at the response of the following call::
$kamaki astakos authenticate aT0k3n==
$kamaki user authenticate aT0k3n==
Editing options
^^^^^^^^^^^^^^^
......@@ -104,11 +104,11 @@ In the above example, if the kamaki configuration file does not exist, it will b
The configuration file is formatted so that it can be parsed by the python ConfigParser module. It consists of command sections that are denoted with brackets. Every section contains variables with values. For example::
[store]
[file]
url=https://okeanos.grnet.gr/pithos
token=my0th3rT0k3n==
two configuration options are created: *store.url* and *store.token*. These values will be loaded at every future kamaki execution.
two configuration options are created: *file.url* and *file.token*. These values will be loaded at every future kamaki execution.
Available options
^^^^^^^^^^^^^^^^^
......@@ -129,14 +129,14 @@ The [global] group is treated by kamaki as a generic group for arbitrary options
* global.log_data <on|off>
allow kamaki to log http data (by default, it logs only method, URL and headers)
* store.cli <UI command specifications for store>
* file.cli <UI command specifications for file>
a special package that is used to load storage commands to kamaki UIs. Don't touch this unless if you know what you are doing.
* store.url <OOS storage or Pithos+ service url>
* file.url <OOS storage or Pithos+ service url>
the url of the OOS storage or Pithos+ service. Set to Okeanos.grnet.gr Pithos+ storage service by default. Users should set a different value if they need to use a different storage service.
* store.token <token>
it set, it overrides possible global.token option for store level commands
* file.token <token>
it set, it overrides possible global.token option for file level commands
* compute.url <OOS compute or Cyclades service url>
the url of the OOS compute or Cyclades service. Set to Okeanos.grnet.gr Cyclades IaaS service by default. Users should set a different value if they need to use a different IaaS service.
......@@ -156,10 +156,10 @@ The [global] group is treated by kamaki as a generic group for arbitrary options
* image.cli <UI command specifications for Plankton (and Compute) image service>
a special package that is used to load image-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
* astakos.url <Astakos authentication service url>
* user.url <Astakos authentication service url>
the url of the Astakos authentication service. Set to the Okeanos.grnet.gr Astakos service by default. Users should set a different value if they need to use a different service.
* astakos.cli <UI command specifications for Astakos authentication service>
* user.cli <UI command specifications for Astakos authentication service>
a special package that is used to load astakos-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
* history.file <history file path>
......@@ -213,7 +213,7 @@ Kamaki contains a live test suite for the kamaki.clients API, where "live" means
The livetest suite can be activated with the following option on the configuration file::
[livetest]
cli=livetest_cli
cli=livetest
In most tests, livetest will run as long as an Astakos identity manager service is accessible and kamaki is set up to authenticate a valid token on this server.
......@@ -221,14 +221,14 @@ In specific, a setup file needs at least the following mandatory settings in the
* If authentication information is used for default kamaki clients::
[astakos]
[user]
url=<Astakos Identity Manager URL>
token=<A valid user token>
* else if this authentication information is only for testing add this under [livetest]::
astakos_url=<Astakos Identity Manager URL>
astakos_token=<A valid user token>
user_url=<Astakos Identity Manager URL>
user_token=<A valid user token>
Each service tested in livetest might need some more options under the [livetest] label, as shown bellow:
......@@ -301,7 +301,7 @@ The quotaholder client
A quotaholder client is introduced as an advanced feature. Quotaholder client is mostly used as a client library for accessing a synnefo quota service, but it can also be allowed as a kamaki command set, but setting the quotaholder.cli and quotaholder.url methods::
[quotaholder]
cli=quotaholder_cli
cli=quotaholder
url=<URL of quotaholder service>
Quotaholder is not tested in livetest
......
......@@ -114,14 +114,14 @@ To see the command groups, use -h or --help like in example 1.3.1. In the same w
Options:
- - - -
astakos: Astakos API commands
config : Configuration commands
flavor : Compute/Cyclades API flavor commands
history: Command history
image : Plankton (and Compute) Image API commands
network: Compute/Cyclades API network commands
server : Compute/Cyclades API server commands
store : Pithos+ storage commands
user: Astakos API commands
config: Configuration commands
flavor: Compute/Cyclades API flavor commands
history: Command history
image: Plankton (and Compute) Image API commands
network: Compute/Cyclades API network commands
server: Compute/Cyclades API server commands
file: Pithos+ storage commands
.. code-block:: console
:emphasize-lines: 1
......@@ -254,12 +254,12 @@ Kamaki commands can be used along with advanced shell features.
Example 3.4.1: Print username for token us3rt0k3n== using grep
$ kamaki astakos authenticate -o token=us3rt0k3n== | grep userame
$ kamaki user authenticate -o token=us3rt0k3n== | grep userame
userame : user@synnefo.org
The -o argument can be used to temporarily override various (set or unset) options. In one command, all -o option sets are forgotten just after the command has been completed, and the previous settings are restored (a.k.a. the configuration file is not modified).
The astakos-authenticate command in example 3.4.1 runs with an explicitly provided token, which temporarily overrides the token provided in the configuration file.
The user-authenticate command in example 3.4.1 runs with an explicitly provided token, which temporarily overrides the token provided in the configuration file.
Interactive shell
-----------------
......@@ -267,26 +267,26 @@ Interactive shell
Command Contexts
^^^^^^^^^^^^^^^^
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 ("store" in example 4.1.1).
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).
.. code-block:: console
:emphasize-lines: 1
Example 4.1.1: Enter store commands context / group
Example 4.1.1: Enter file commands context / group
$ kamaki
[kamaki]: store
[store]:
[kamaki]: file
[file]:
Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in Windows) to exit a context and return to the context of origin. If already at the top context (kamaki), an exit is equivalent to exiting the program.
.. code-block:: console
:emphasize-lines: 1
Example 4.1.2: Exit store context and then exit kamaki
Example 4.1.2: Exit file context and then exit kamaki
[store]: exit
[file]: exit
[kamaki]: exit
$
......@@ -302,10 +302,10 @@ A user might **browse** through different contexts during one session.
[config]: list
... (configuration options listing) ...
[config]: exit
[kamaki]: store
[store]: list
[kamaki]: file
[file]: list
... (storage containers listing) ...
[store]: exit
[file]: exit
[kamaki]: server
[server]: list
... (VMs listing) ...
......@@ -322,7 +322,7 @@ Users have the option to avoid switching between contexts: all commands can run
[kamaki]: config list
... (configuration options listing) ...
[kamaki]: store list
[kamaki]: file list
... (storage container listing) ...
[kamaki]: server list
... (VMs listing) ...
......@@ -357,7 +357,7 @@ The context-level help results change from context to context
kamaki commands:
================
astakos config flavor history image network server store
user config flavor history image network server file
interactive shell commands:
===========================
......@@ -437,7 +437,7 @@ There are many ways of producing a help message, as shown in example 4.2.3
[config]: set --help
[kamaki]: config set -h
[kamaki]: config set --help
[store]: /config set -h
[file]: /config set -h
[server]: /config set --help
.. _accessing-top-level-commands-ref:
......@@ -484,70 +484,70 @@ It is often the case that a user who works in the context command, needs to crea
[server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
...
An other example (4.3.2) showcases how to acquire and modify configuration settings from a different context. In this scenario, the user token expires at server side while the user is working. When that happens, the system responds with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid for the astakos identity manager of preference) which has to be set to kamaki.
An other example (4.3.2) showcases how to acquire and modify configuration settings from a different context. In this scenario, the user token expires at server side while the user is working. When that happens, the system responds with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid for the Astakos identity manager of preference) which has to be set to kamaki.
.. code-block:: console
:emphasize-lines: 1
Example 4.3.2: Set a new token from store context
Example 4.3.2: Set a new token from file context
[store]: list
[file]: list
(401) UNAUTHORIZED Access denied
[store]: /astakos authenticate
[file]: /user authenticate
(401) UNAUTHORIZED Invalid X-Auth-Token
[store]: /config get token
[file]: /config get token
my3xp1r3dt0k3n==
[store]: /config set token myfr35ht0k3n==
[file]: /config set token myfr35ht0k3n==
[store]: /config get token
[file]: /config get token
myfr35ht0k3n==
[store]: list
[file]: list
1. pithos (10MB, 2 objects)
2. trash (0B, 0 objects)
.. note:: The error messages on this example where shortened for clarity. Actual kamaki error messages are more helpful and descriptive.
The following example compares some equivalent calls that run *astakos-authenticate* after a *store-list* 401 failure.
The following example compares some equivalent calls that run *user-authenticate* after a *file-list* 401 failure.
.. code-block:: console
:emphasize-lines: 1,3,10,17,26
Example 4.3.3: Equivalent astakos-authenticate calls after a store-list 401 failure
Example 4.3.3: Equivalent user-authenticate calls after a file-list 401 failure
* without kamaki interactive shell *
$ kamaki store list
$ kamaki file list
(401) UNAUTHORIZED Access denied
$ kamaki astakos authenticate
$ kamaki user authenticate
...
$
* from top-level context *
[kamaki]: store list
[kamaki]: file list
(401) UNAUTHORIZED Access denied