projects / kamaki / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Merge branch 'feature-adjust-docs' into develop
[kamaki] / docs / commands.rst
diff --git a/docs/commands.rst b/docs/commands.rst
index facf678..63a2263 100644 (file)
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -1,11 +1,14 @@
 List of commands
 ================
 
 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.
+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
 
 
 .. code-block:: text
 
@@ -14,24 +17,25 @@ astakos (Identity Manager)
 Showcase: get user information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Showcase: get user information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In the following, the token has been set in a previous step (see `setup section <setup.html>`_ or the `quick setup guide <usage.html#quick-setup>`_)
+In the following, the token has been set in a previous step (see
+`setup section <setup.html>`_ or the
+`quick setup guide <usage.html#quick-setup>`_)
 
 .. code-block:: console
     :emphasize-lines: 1,4
 
 
 .. code-block:: console
     :emphasize-lines: 1,4
 
-    * Enter astakos context *
-    [kamaki]:astakos
+    * Enter user context *
+    [kamaki]: user
 
     * Authenticate user *
 
     * Authenticate user *
-    [astakos]:authenticate
-    auth_token_created:  2012-11-13T14:12:40.917034
-    auth_token_expires:  2012-12-13T14:12:40.917035
-    email             :  
-                       myaccount@grnet.gr
-                       myotheraccount@grnet.gr
-    name              :  My Real Name
-    username          :  usually@an.email.org
-    uuid              :  ab1cde23-45fg-6h7i-8j9k-10l1m11no2pq
+    [user]: authenticate
+    ...
+    user:
+        name:  My Real Name
+        uuid:  ab1cde23-45fg-6h7i-8j9k-10l1m11no2pq
+
+.. note:: actual call returns a full list of service endpoints accessible to
+    the user with a specific token
 
 flavor (Compute/Cyclades)
 -------------------------
 
 flavor (Compute/Cyclades)
 -------------------------
@@ -53,33 +57,37 @@ Showcase: show details for flavor with id 43
     * Get details about flavor with id 43 *
     [flavor]: info 43
     SNF:disk_template:  drbd
     * Get details about flavor with id 43 *
     [flavor]: info 43
     SNF:disk_template:  drbd
-    cpu              :  4
-    disk             :  10
-    id               :  43
-    name             :  C4R2048D10
-    ram              :  2048
+    cpu :  4
+    disk:  10
+    id  :  43
+    name:  C4R2048D10
+    ram :  2048
 
 image (Plankton commands + Compute Image subcommands)
 -----------------------------------------------------
 
 .. code-block:: text
 
 
 image (Plankton commands + Compute Image subcommands)
 -----------------------------------------------------
 
 .. code-block:: text
 
-    addmember  :  Add a member to an image
-    addproperty:  Add an image property
-    delmember  :  Remove a member from an image
-    list       :  List images accessible by user
-    members    :  Get image members
-    meta       :  Get image metadata
-    register   :  (Re)Register an image
-    setmembers :  Set the members of an image
-    shared     :  List shared images
-    compute    :  Compute Image API commands
-        list       :  List images
-        delete     :  Delete image
-        info       :  Get image details
-        properties :  Get image properties
-        delproperty:  Delete an image property
-        setproperty:  Update an image property
+    list      :  List images accessible by user
+    meta      :  Get image metadata
+    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
+            add   :  Add a property to 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
 
 Showcase: Pick an image and list the properties
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Showcase: Pick an image and list the properties
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -88,29 +96,29 @@ Showcase: Pick an image and list the properties
     :emphasize-lines: 1,4,18
 
     * Enter image context *
     :emphasize-lines: 1,4,18
 
     * Enter image context *
-    [kamaki]:image
+    [kamaki]: image
 
     * list all available images *
 
     * list all available images *
-    [image]:list
-    1. Windows Server 2008
+    [image]: list
+    926ab1c5-2d85-49d4-aebe-0fce712789b9 Windows Server 2008
      container_format:  bare
      disk_format     :  diskdump
      id              :  926ab1c5-2d85-49d4-aebe-0fce712789b9
      size            :  11917066240
      status          :  available
      container_format:  bare
      disk_format     :  diskdump
      id              :  926ab1c5-2d85-49d4-aebe-0fce712789b9
      size            :  11917066240
      status          :  available
-    2. Windows Server 2012
+    78262ee7-949e-4d70-af3a-85360c3de57a Windows Server 2012
      container_format:  bare
      disk_format     :  diskdump
      id              :  78262ee7-949e-4d70-af3a-85360c3de57a
      size            :  11697913856
      status          :  available
      container_format:  bare
      disk_format     :  diskdump
      id              :  78262ee7-949e-4d70-af3a-85360c3de57a
      size            :  11697913856
      status          :  available
-    3. ubuntu
+    5ed5a29b-292c-4fe0-b32c-2e2b65628635 ubuntu
      container_format:  bare
      disk_format     :  diskdump
      id              :  5ed5a29b-292c-4fe0-b32c-2e2b65628635
      size            :  2578100224
      status          :  available
      container_format:  bare
      disk_format     :  diskdump
      id              :  5ed5a29b-292c-4fe0-b32c-2e2b65628635
      size            :  2578100224
      status          :  available
-    4. Debian_Wheezy_Base
+    1f8454f0-8e3e-4b6c-ab8e-5236b728dffe Debian_Wheezy_Base
      container_format:  bare
      disk_format     :  diskdump
      id              :  1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
      container_format:  bare
      disk_format     :  diskdump
      id              :  1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
@@ -118,7 +126,7 @@ Showcase: Pick an image and list the properties
      status          :  available
 
     * Get properties of image with id 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe *
      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
     description   :  Debian 6.0.6 (Squeeze) Base System
     gui           :  No GUI
     kernel        :  2.6.32
@@ -133,19 +141,22 @@ server (Compute/Cyclades)
 
 .. code-block:: text
 
 
 .. code-block:: text
 
-    addmeta :  Add server metadata
     addr    :  List a server's nic address
     console :  Get a VNC console
     create  :  Create a server
     delete  :  Delete a server
     addr    :  List a server's nic address
     console :  Get a VNC console
     create  :  Create a server
     delete  :  Delete a server
-    delmeta :  Delete server metadata
-    firewall:  Set the server's firewall profile
+    firewall:  Manage server's firewall profile
+        set :  Set the server's firewall profile
+        get :  Get the server's firewall profile
     info    :  Get server details
     list    :  List servers
     info    :  Get server details
     list    :  List servers
+    metadata:  Manage Server Metadata
+        list  :  List server metadata
+        set   :  Add / update server metadata
+        delete:  Delete a piece of server metadata
     meta    :  Get a server's metadata
     reboot  :  Reboot a server
     rename  :  Update a server's name
     meta    :  Get a server's metadata
     reboot  :  Reboot a server
     rename  :  Update a server's name
-    setmeta :  Update server's metadata
     shutdown:  Shutdown a server
     start   :  Start a server
     stats   :  Get server statistics
     shutdown:  Shutdown a server
     start   :  Start a server
     stats   :  Get server statistics
@@ -158,12 +169,12 @@ Showcase: Create a server
     :emphasize-lines: 1,4,21,35,44,62
 
     * Enter server context *
     :emphasize-lines: 1,4,21,35,44,62
 
     * Enter server context *
-    [kamaki]:server
+    [kamaki]: server
 
     * See server-create help *
 
     * See server-create help *
-    [server]:create -h
+    [server]: create -h
     usage: create <name> <flavor id> <image id>
     usage: create <name> <flavor id> <image id>
-            [--personality PERSONALITY] [-h] [--config CONFIG]
+            [--personality PERSONALITY] [-h] [--config CONFIG] [--cloud CLOUD]
 
     Create a server
 
 
     Create a server
 
@@ -176,9 +187,10 @@ Showcase: Create a server
       -i, --include         Include protocol headers in the output
       --config CONFIG       Path to configuration file
       -s, --silent          Do not output anything
       -i, --include         Include protocol headers in the output
       --config CONFIG       Path to configuration file
       -s, --silent          Do not output anything
+      --cloud CLOUD         Chose a cloud to connect to
 
     * List all available images *
 
     * 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
     1395fdfb-51b4-419f-bb02-f7d632860611 Ubuntu Desktop LTS
     1580deb4-edb3-4496-a27f-7a246c4c0528 Ubuntu Desktop
     18a82962-43eb-4b32-8e28-8f8880af89d7 Kubuntu LTS
@@ -192,7 +204,7 @@ Showcase: Create a server
     c1d27b46-d875-4f5c-b7f1-f39b5af62905 Kubuntu
 
     * See details of flavor with id 1 *
     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
     SNF:disk_template:  drbd
     cpu              :  1
     disk             :  20
@@ -201,7 +213,7 @@ Showcase: Create a server
     ram              :  1024
 
     * Create a debian server named 'My Small Debian 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
     adminPass:  L8gu2wbZ94
     created  :  2012-11-23T16:56:04.190813+00:00
     flavorRef:  1
@@ -209,9 +221,8 @@ Showcase: Create a server
     id       :  11687
     imageRef :  b2dffe52-64a4-48c3-8a4c-8214cc3165cf
     metadata : 
     id       :  11687
     imageRef :  b2dffe52-64a4-48c3-8a4c-8214cc3165cf
     metadata : 
-             values: 
-                   os   :  debian
-                   users:  root
+               os   :  debian
+               users:  root
     name     :  My Small Debian Server
     progress :  0
     status   :  BUILD
     name     :  My Small Debian Server
     progress :  0
     status   :  BUILD
@@ -219,7 +230,7 @@ Showcase: Create a server
     updated  :  2012-11-23T16:56:04.761962+00:00
 
     * wait for server to build (optional) *
     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
 
     Server 11687 still in BUILD mode |||||||||||||||||    | 80%
     Server 11687 is now in ACTIVE mode
 
@@ -245,15 +256,15 @@ Showcase: Connect a network to a VM
     :emphasize-lines: 1,4,9,24,27,44
 
     * Enter network context *
     :emphasize-lines: 1,4,9,24,27,44
 
     * Enter network context *
-    [kamaki]:network
+    [kamaki]: network
 
     * List user-owned VMs *
 
     * 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) *
     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]
 
     Syntax error
     usage: connect <server id> <network id> [-s] [-h] [-i] [--config CONFIG]
 
@@ -271,24 +282,24 @@ Showcase: Connect a network to a VM
     [network]: connect 11687 1409
 
     * Get details on network with id 1409
     [network]: connect 11687 1409
 
     * Get details on network with id 1409
-    [network]:info 1409
+    [network]: info 1409
       attachments: 
                  nic-11687-1
       attachments: 
                  nic-11687-1
-      cidr       :  192.168.1.0/24
-      cidr6      :  None
-      created    :  2012-11-23T17:17:20.560098+00:00
-      dhcp       :  True
-      gateway    :  None
-      gateway6   :  None
-      id         :  1409
-      name       :  my network
-      public     :  False
-      status     :  ACTIVE
-      type       :  PRIVATE_MAC_FILTERED
-      updated    :  2012-11-23T17:18:25.095225+00:00
+      cidr    :  192.168.1.0/24
+      cidr6   :  None
+      created :  2012-11-23T17:17:20.560098+00:00
+      dhcp    :  True
+      gateway :  None
+      gateway6:  None
+      id      :  1409
+      name    :  my network
+      public  :  False
+      status  :  ACTIVE
+      type    :  MAC_FILTERED
+      updated :  2012-11-23T17:18:25.095225+00:00
 
     * Get connectivity details on VM with id 11687 *
 
     * 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
     id:  nic-11687-1
         ipv4       :  192.168.1.1
         ipv6       :  None
@@ -303,44 +314,50 @@ 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
 
 
 .. 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
 
     append        :  Append local file to remote
     cat           :  Print a file to console
     copy          :  Copy an object
 
 .. code-block:: text
 
     append        :  Append local file to remote
     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]
     create        :  Create a container
     delete        :  Delete a container [or an object]
-    delgroup      :  Delete a user group
-    delmeta       :  Delete an existing metadatum for an account [, container [or object]]
-    delpermissions:  Delete all sharing permissions
-    download      :  Download a file
-    group         :  Get user groups details
+    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
     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
-    meta          :  Get custom meta-content for account [, container [or object]]
+    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
     mkdir         :  Create a directory
     move          :  Copy an object
     overwrite     :  Overwrite part (from start to end) of a remote file
-    permissions   :  Get object read/write permissions
+    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
     publish       :  Publish an object
     purge         :  Purge a container
-    quota         :  Get  quota for account [or container]
-    setgroup      :  Create/update a new user group
-    setmeta       :  Set a new metadatum for account [, container [or object]]
-    setpermissions:  Set sharing permissions
-    setquota      :  Set new quota (in KB) for account [or container]
-    setversioning :  Set new versioning (auto, none) for account [or 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
     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
-    versioning    :  Get  versioning for account [or container ]
+    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
 
 Showcase: Upload and download a file
     versions      :  Get the version list of an object
 
 Showcase: Upload and download a file
@@ -350,27 +367,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 *
     :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
 
     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 *
 
 
     * 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 *
     -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 *    
 
 
     * List accessible containers *    
-    [store]:list
+    [file]: list
     1. mycont1 (0B, 0 objects)
     2. mycont2 (0B, 0 objects)
     3. pithos (0B, 0 objects)
     1. mycont1 (0B, 0 objects)
     2. mycont2 (0B, 0 objects)
     3. pithos (0B, 0 objects)
@@ -378,48 +395,52 @@ Showcase: Upload and download a file
 
 
     * Upload local file to 1st container *
 
 
     * Upload local file to 1st container *
-    [store]:upload rndm_local.file mycont1
+    [file]: upload rndm_local.file mycont1
 
 
     * Check if file has been uploaded *
 
 
     * Check if file has been uploaded *
-    [store]:list mycont1
+    [file]: list mycont1
     1.    20M rndm_local.file
 
     * Create directory mydir on second container *
     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) *
 
 
     * 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 *
 
     * 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 *
     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 *
 
 
     * Check pasted file *
-    [store]:list mycont1
+    [file]: list mycont1
     1.    20M rndm_remote.file
 
 
     * Download pasted file to local file system *
     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 *
 
 
     * 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
     -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)
+.. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g. bash)
 
 
-.. 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 ::
+.. 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
Kamaki