Commit 68d68112 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Merge branch 'feature-docs' into develop

parents ec6c3949 f084bdc8
This diff is collapsed.
......@@ -130,7 +130,7 @@ copyright = u'2013, GRNET'
# built documents.
#
# The short X.Y version.
version = '0.10'
version = '0.12'
# The full version, including alpha/beta/rc tags.
try:
import kamaki
......
Configuration
=============
The following refers to the configuration version 0.9 or better. There is also
The following refers to the configuration version 0.12 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
......@@ -22,8 +22,8 @@ Now, let kamaki do the conversion
.. code-block:: console
$ kamaki user authenticate
. Config file format version >= 9.0 is required
$ kamaki user info
. Config file format version >= 0.12 is required
. Configuration file: /home/someuser/.kamakirc
. Attempting to fix this:
. Calculating changes while preserving information
......@@ -37,6 +37,7 @@ Now, let kamaki do the conversion
. ... rescue server.cli => global.server_cli
. ... rescue history.file => global.history_file
. ... rescue history.cli => global.history_cli
. ... change network_cli value: cyclades => network
. ... DONE
. The following information will NOT be preserved:
. global.account = AccountName
......@@ -80,7 +81,7 @@ Ask kamaki to load from a non-existing configuration file
.. code-block:: console
$ kamaki -c nonexisting.cnf user authenticate
$ kamaki -c nonexisting.cnf user info
. No cloud is configured
. | To configure a new cloud "<cloud name>", find and set the
. | single authentication URL and token:
......@@ -106,7 +107,7 @@ Try to connect
.. code-block:: console
$ kamaki -c nonexisting.cnf user authenticate
$ kamaki -c nonexisting.cnf user info
. No authentication token provided for cloud "mytest"
. | Set a token for cloud mytest:
. | kamaki config set cloud.mytest.token <token>
......@@ -149,7 +150,7 @@ Check for clouds and attempt to authenticate
$ kamaki config get cloud
. cloud.default.token = my0ld70k3n==
$ kamaki user authenticate
$ kamaki user info
. No authentication URL provided for cloud "mytest"
. | Set a URL for cloud mytest:
. | kamaki config set cloud.mytest.url <URL>
......@@ -160,7 +161,7 @@ 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
$ kamaki user info
. Failed while http-connecting to https://nonexisting.example.com
$
......@@ -169,7 +170,7 @@ 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
$ kamaki user info
. (401) Authorization failed for token gZH99orgkfYHmGksZKvHJw==
. | UNAUTHORIZED unauthorized (Invalid token)
$
......@@ -186,7 +187,7 @@ Set up the correct values and attempt authentication
$ kamaki config set cloud.default.url https://accounts.deploymentexample.com/identity/v2.0
$ kamaki config set cloud.default.token myd3pl0ym3nt70k3n==
$ kamaki user authenticate
$ kamaki user info
. ...
. user:
. id: my-d3pl0ym3nt-u53r-1d
......@@ -242,19 +243,19 @@ Authenticate against different clouds
.. code-block:: console
$ kamaki user authenticate
$ kamaki user info
. ...
. <response from deploymentexample.com>
. ...
$ kamaki --cloud=mytest user authenticate
$ kamaki --cloud=mytest user info
. ...
. <response from example.com>
. ...
$ kamaki --cloud=default user authenticate
$ kamaki --cloud=default user info
. ...
. <response from deploymentexample.com, same as default behavior>
. ...
$ kamaki --cloud=nonexistingcloud user authenticate
$ kamaki --cloud=nonexistingcloud user info
. No cloud "nonexistingcloud" is configured
. | To configure a new cloud "nonexistingcloud", find and set the
. | single authentication URL and token:
......@@ -267,14 +268,14 @@ Confuse kamaki by removing the default_cloud option, set mytest as default
.. code-block:: console
$ kamaki config delete default_cloud
$ kamaki user authenticate
$ kamaki user info
. 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
$ kamaki user info
. ...
. <response from example.com>
. ...
......@@ -287,7 +288,7 @@ default_cloud option are removed?
$ kamaki config delete cloud.default
$ kamaki config delete default_cloud
$ kamaki user authenticate
$ kamaki user info
. ...
. <response from example.com>
. ...
......@@ -296,44 +297,3 @@ default_cloud option are removed?
`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, 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
.. 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
$
This diff is collapsed.
......@@ -6,73 +6,103 @@ kamaki tool manual page
Synopsis
--------
**kamaki** [*group*] [*command*] [...] [*options*]
**kamaki** [*group*] [*command*] [...] [*options*] [*arguments*]
**kamaki-shell** [*group*] [*command*] [...] [*arguments*]
Description
-----------
:program:`kamaki` is a simple, yet intuitive, command-line tool for managing
clouds. It can be used in three forms: as an interactive shell, as a command line tool or as a clients API for other applications.
clouds. It can be used in three forms: as an interactive shell
(`kamaki-shell`), as a command line tool (`kamaki`) or as a clients API for
other applications (`kamaki.clients`).
To run kamaki as an interactive shell, type
To run `kamaki` as an interactive shell, type
kamaki
kamaki-shell
To run kamaki as tool type
To run `kamaki` as tool type
kamaki <group> <command> [...] [options]
The kamaki clients API can be imported in python applications as kamaki.clients
The kamaki clients API can be imported in python applications as
`kamaki.clients`
List of available command groups:
config
user
Astakos/Identity API commands
Edit configuration options. Config options are stored in ~/.kamakirc file.
project
Astakos project API commands
history
quota
Astakos/Account API commands for quotas
Access kamaki user history, which is stored in ~/.kamaki.history file.
resource
Astakos/Account API commands for resources
user
file
Pithos+/Storage object level API commands
Get information from Astakos API
container
Pithos+/Storage container level API commands
server
group
Pithos+/Storage user groups
sharer
Pithos+/Storage sharer accounts
Manage compute API virtual machines.
server
Cyclades/Compute API server commands
flavor
Cyclades/Compute API flavor commands
Manage compute API flavors.
image
Cyclades/Plankton API image commands
imagecompute
Cyclades/Compute API image commands
network
Networking API network commands
Manage compute API networks.
subnet
Networking API network commands
ip
Networking API floatingip commands
Manage compute API floating IP commands
image
port
Networking API network Commands
Manage images on Plankton (and Compute).
file
config
Kamaki option and cloud configuration
Manage Pithos+ API.
history
Kamaki command history
Hidden command groups
---------------------
livetest
LIve tests that check kamaki against running services. To enable:
Live tests that check kamaki against running services. To enable:
kamaki config set livetest.cli livetest
service
Astakos API service commands
endpoint
Astakos API endpoints commands
commission
Astakos API commission commands
Options
-------
......@@ -82,110 +112,149 @@ Options
--help, -h Show help message and exit.
-v Use verbose output.
-d Use debug output.
-o KEY=VAL Override a config value (can be used multiple times)
-o KEY=VAL Override a config value (can be repeated)
--cloud CLOUD Choose a cloud to connect to
Commands
--------
config commands
***************
* list list configuration options
* get get a configuration option
* set set a configuration option
* del delete a configuration option
history commands
****************
Command user history, as stored in ~/.kamaki.history
* show show intersession history
* clean clean up history
* run run/show previously executed command(s)
user commands
*************
* authenticate Authenticate a user, show user information
user
****
* authenticate Authenticate a user, show user information
* info Get info for (current) session user
* uuid2name Get user name(s) from uuid(s)
* authenticate Authenticate a user and get all authentication information
* list List (cached) session users
* add Authenticate a user by token and add to kamaki session (cache)
* name2uuid Get user uuid(s) from name(s)
* select Select a user from the (cached) list as the current session user
* delete Delete a user (token) from the (cached) list of session users
project
*******
* info Get details for a project
* unsuspend Resume a suspended project (special privileges needed)
* suspend Suspend a project (special privileges needed)
* list List all projects
* create Apply for a new project
* modify Modify a project
* terminate Terminate a project (special privileges needed)
* application Application management commands
* membership Project membership management commands
* reinstate Reinstate a terminated project (special privileges needed)
quota
*****
* list Get user quotas
* info Get quota for a service (cyclades, pithos, astakos)
resource
********
* list List user resources
file
****
* info Get information/details about a file
* truncate Truncate remote file up to size
* mkdir Create a directory ( create --content-type='applcation/directory' )
* create Create an empty file
* move Move objects, even between different accounts or containers
* list List all objects in a container or a directory object
* upload Upload a file
* cat Fetch remote file contents
* modify Modify the attributes of a file or directory object
* append Append local file to (existing) remote object
* download Download a remove file or directory object to local file system
* copy Copy objects, even between different accounts or containers
* overwrite Overwrite part of a remote file
* delete Delete a file or directory object
container
*********
* info Get information about a container
* modify Modify the properties of a container
* create Create a new container
* list List all containers, or their contents
* empty Empty a container
* delete Delete a container
group
*****
* create Create a group of users
* list List all groups and group members
* delete Delete a user group
sharer
******
* info Details on a Pithos+ sharer account (default: current account)
* list List accounts who share file objects with current user
server commands
***************
server
******
* addr List the addresses of all network interfaces on a server (VM)
* console Get a VNC console to access an existing server (VM)
* create Create a server (aka Virtual Machine)
* delete Delete a server (VM)
* firewall Set the server (VM) firewall profile for public networks
* set Set the firewall profile
* get Get the firewall profile
* info Detailed information on a Virtual Machine
* list List Virtual Machines accessible by user
* metadata Manage a server metadata
* list List server metadata
* set Add or update server metadata
* delete Delete a piece of server metadata
* reboot Reboot a server (VM)
* rename Set/update a server (VM) name
* shutdown Shutdown an active server (VM)
* start Start an existing server (VM)
* stats Get server (VM) statistics
* resize Set a different flavor for an existing server
* modify Modify attributes of a virtual server
* create Create a server (aka Virtual Machine)
* list List virtual servers accessible by user
* reboot Reboot a virtual server
* start Start an existing virtual server
* shutdown Shutdown an active virtual server
* delete Delete a virtual server
* wait Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
flavor commands
***************
flavor
******
* list list flavors
* info get flavor details
image
*****
image commands
**************
* list List images accessible by user
* info Get image metadata
* meta Manage image metadata
* set Add / update metadata and properties for an image
* delete Remove/empty image metadata and/or custom properties
* register (Re)Register an image
* unregister Unregister an image (does not delete the image file)
* shared List shared images
* compute Compute Image API commands
* list List images
* delete Delete image
* info Get image details
* properties Manage properties related to OS installation in an image
* delete Delete a property from an image
* get Get an image property
* list List all image properties
* set Add / update a set of properties for an image
* members Manage members (users who can modify an image)
* add Add a member to an image
* delete Remove a member from an image
* list List members of an image
* set Set the members of an image
network commands
****************
* info Get image metadata
* list List images accessible by user
* register (Re)Register an image file to an Image service
* modify Add / update metadata and properties for an image
* unregister Unregister an image (does not delete the image file)
imagecompute
************
* info Get detailed information on an image
* list List images
* modify Modify image properties (metadata)
* delete Delete an image (WARNING: image file is also removed)
network
*******
* connect Connect a server to a network
* create Create an (unconnected) network
* delete Delete a network
* disconnect Disconnect a nic that connects a server to a network
* info Detailed information on a network
* list List networks
* rename Set the name of a network
* info: Get details about a network
* disconnect: Disconnect a network from a device
* modify: Modify network attributes
* create: Create a new network
* list: List networks
* connect: Connect a network with a device (server or router)
* delete: Delete a network
subnet
******
ip commands
***********
* info Get details about a subnet
* list List subnets
* create Create a new subnet
* modify Modify the attributes of a subnet
ip
**
* info Details for an IP
* list List reserved floating IPs
......@@ -195,53 +264,36 @@ ip commands
* detach Detach a floating IP from a server
* reserve Reserve a floating IP
file commands
**************
* append Append local file to remote file
* cat Print a file to console
* copy Copy an object
* containerlimit Container size limit commands
* set Set container data limit
* get Get container data limit
* create Create a container
* delete Delete a container [or an object]
* download Download a file or directory
* group Manage access groups and group members
* delete Delete a user group
* list List groups and group members
* set Set a user group
* hashmap Get the hashmap of an object
* info Get information for account [, container [or object]]
* list List containers, object trees or objects in a directory
* manifest Create a remote file with uploaded parts by manifestation
* metadata Metadata are attached on objects (key:value pairs)
* delete Delete metadata with given key
* get Get metadatum
* set Set a piece of metadata
* mkdir Create a directory
* move Copy an object
* overwrite Overwrite part (from start to end) of a remote file
* permissions Manage user and group accessibility for objects
* delete Delete all permissions set on object
* get Get read and write permissions of an object
* set Set permissions for an object
* publish Publish an object
* purge Purge a container
* quota Get quota for account
* sharers List the accounts that share objects with default account
* touch Create an empty object (file)
* truncate Truncate remote file up to a size
* unpublish Unpublish an object
* upload Upload a file or directory
* versioning Manage the versioning scheme of current pithos user account
* get Get versioning for account or container
* set Set versioning mode (auto, none) for account or container
* versions Get the version list of an object
test commands (hidden)
**********************
port
****
* info Get details about a port
* list List all ports
* create Create a new port (== connect server to network)
* modify Modify the attributes of a port
* delete Delete a port (== disconnect server from network)
* wait Wait for port to finish [ACTIVE, DOWN, BUILD, ERROR]
config
******
* list list configuration options
* get get a configuration option
* set set a configuration option
* del delete a configuration option
history
*******
Command user history, as stored in ~/.kamaki.history
* show show intersession history
* clean clean up history
* run run/show previously executed command(s)
livetest (hidden)
*****************
* all test all clients
* args test how arguments are treated by kamaki
......@@ -252,6 +304,29 @@ test commands (hidden)
* pithos test Pithos client
* prints user-test print methods for lists and dicts
service (hidden)
****************
* list List available services
* uuid2username Get service username(s) from uuid(s)
* quotas Get service quotas
* username2uuid Get service uuid(s) from username(s)
endpoint (hidden)
*****************
* list Get endpoints service endpoints
commission (hidden)
*******************
* info Get commission info (special privileges required)
* resolve Resolve multiple commissions (special privileges required)
* accept Accept a pending commission (special privileges required)
* reject Reject a pending commission (special privileges required)
* issue Issue commissions as a json string (special privileges required)
* pending List pending commissions (special privileges required)
Author
------
......