Sirocco CIMI command-line tools
The Sirocco CIMI command-line tools module provides a command line interface to access a CIMI provider. You can use these tools to list resources (machines, volumes, images, systems etc.) and control their lifecycle (creation, deletion, start/stop...).
Download
A zip or tarball can be downloaded from here
Installation
Prerequisite: Java 1.6 or later. The java command must be accessible in your $PATH.
To install the tools you need to download the zip or the tarball and extract it to the folder of your choice.
The following environment variables must be set:
- CIMICLIENT_TOOLS_HOME
the directory path where you installed the command line tools - CIMICLIENT_ENDPOINT_URL
the endpoint of the CIMI provider - CIMICLIENT_USERNAME
the username of your account on the CIMI provider - CIMICLIENT_PASSWORD
the password of your account on the CIMI provider
Example set-up using bash:
export CIMICLIENT_USERNAME=guest
export CIMICLIENT_PASSWORD=guest
export CIMICLIENT_ENDPOINT_URL=http://cimiprovider:3421/cimi
Add $CIMICLIENT_TOOLS_HOME/bin to your $PATH to make the cimiclient command accessible.
Optionally, you can set the CIMICLIENT_OPTS variable to override the default authentication mechanism used by the tools (basic authentication):
- export CIMICLIENT_OPTS=-DCIMICLIENT_AUTH_PLUGIN_CLASS=org.ow2.sirocco.cimi.sdk.auth.NoAuthPlugin
No authentication (for debugging purposes mostly) - export CIMICLIENT_OPTS=-DCIMICLIENT_AUTH_PLUGIN_CLASS=org.ow2.sirocco.cimi.sdk.auth.OpenStackKeystoneAuthPlugin
Use OpenStack Keystone token-based authentication
Usage
The pattern to use the command line interface is as follows:
cimiclient [client-options] <resource>-<action> [options] [arguments]
where:
- resource: a CIMI resource: machine, machineconfig, machinetemplate, volume, volumeconfig, volumetemplate etc.
- action: list|create|delete|update|show
- options and arguments are generic or command-specific
The generic options are as follows:
- -first
(1-based) index of the first entity of the collection to return (valid for list commands only) - -last
(1-based) index of the last entity of the collection to return (valid for list commands only) - -select
subset of the resource to be returned or to be updated (valid for list, show and update commands only) - -expand
attributes of the resource to expand (valid for list and show commands only) - -filter
filter expression (valid for list commands only)
The client can be configured with the two following options:
- -debug
Turns on debugging: HTTP requests and responses are printed on standard output - -xml
Uses XML serialization (the default is JSON)
Examples
Return all my machines:
+-------------------------------------+-----------------+----------------------------+-------+
|id |name |created |state |
+-------------------------------------+-----------------+----------------------------+-------+
|http://myprovider.com/cimi/machines/7|MySQL |Tue Nov 20 18:50:22 CET 2012|STARTED|
|http://myprovider.com/cimi/machines/8|LoadBalancer |Tue Nov 20 18:50:39 CET 2012|STARTED|
|http://myprovider.com/cimi/machines/9|ApplicationServer|Tue Nov 20 18:50:20 CET 2012|STARTED|
+-------------------------------------+-----------------+----------------------------+-------+
Show detailed information about machine with identifier "http://myprovider.com/cimi/machines/8":
+-----------+---------------------------------------+
|Attribute |Value |
+-----------+---------------------------------------+
|id |http://myprovider.com/cimi/machines/8 |
|name |LoadBalancer |
|description|Apache front-end load-balancer |
|created |Tue Nov 20 18:50:39 CET 2012 |
|properties |(location,France) (provider,openstack) |
|state |STARTED |
|cpu |1 |
|memory |2 GB |
|disks |10 MB |
|private IP |172.16.0.12 |
|public IP |10.193.112.121 |
+-----------+---------------------------------------+
Return the id, name, cpu and memory attributes of all machine configurations:
+-------------------------------------------+--------+---+------+
|id |name |cpu|memory|
+-------------------------------------------+--------+---+------+
|http://myprovider.com/cimi/machineConfigs/1|micro |1 |630 MB|
|http://myprovider.com/cimi/machineConfigs/2|tiny |1 |512 MB|
|http://myprovider.com/cimi/machineConfigs/3|small |2 |2 GB |
+-------------------------------------------+--------+---+------+
Same request but return only machine configurations with a number of CPUs greater or equal to 2:
+-------------------------------------------+--------+---+------+
|id |name |cpu|memory|
+-------------------------------------------+--------+---+------+
|http://myprovider.com/cimi/machineConfigs/3|small |12 |2 GB |
+-------------------------------------------+--------+---+------+
Return the first four machine images from the catalog of images visible to me:
+------------------------------------------+-----------------------------------+
|id |description |
+------------------------------------------+-----------------------------------+
|http://myprovider.com/cimi/machineImages/1|Ubuntu Oneiric 11.10 Server 64 bits|
|http://myprovider.com/cimi/machineImages/2|Ubuntu 11.04 server 64bits |
|http://myprovider.com/cimi/machineImages/3|Debian 5.0 32 bits |
|http://myprovider.com/cimi/machineImages/4|LAMP stack on Debian 5.0 |
+------------------------------------------+-----------------------------------+
Create a machine named "myMachine" with a specific machine config and machine image id:
Job:
+---------+----------------------------------+
|Attribute|Value |
+---------+----------------------------------+
|id |http://myprovider.com/cimi/jobs/15|
+---------+----------------------------------+
Machine:
+---------+--------------------------------------+
|Attribute|Value |
+---------+--------------------------------------+
|id |http://myprovider.com/cimi/machines/18|
+---------+--------------------------------------+
Note that (assuming the CIMI provider supports Jobs), the identifier of the machine creation job is returned along with the identifier of the machine being-created.
The job can be consulted like this:
cimiclient job-show http://myprovider.com/cimi/jobs/15
+---------------------+--------------------------------------+
|Attribute |Value |
+---------------------+--------------------------------------+
|id |http://myprovider.com/cimi/jobs/15 |
|description |Machine Collection add |
|created |Wed Nov 21 14:58:45 CET 2012 |
|properties |(parent-machine,ok) |
|state |SUCCESS |
|action |add |
|target resource |http://myprovider.com/cimi/machines/18|
|affected resources |http://myprovider.com/cimi/machines/18|
|time of status change|Wed Nov 21 14:58:46 CET 2012 |
+---------------------+--------------------------------------+
Let's change the name of the machine and add a description:
Machine http://myprovider.com/cimi/machines/19 being updated
+---------+----------------------------------+
|Attribute|Value |
+---------+----------------------------------+
|id |http://myprovider.com/cimi/jobs/21|
+---------+----------------------------------+
Let's start the machine:
cimiclient machine-start http://myprovider.com/cimi/machines/18
Starting machine http://localhost:9000/cimi/machines/18
Job:
+---------+----------------------------------+
|Attribute|Value |
+---------+----------------------------------+
|id |http://myprovider.com/cimi/jobs/17|
+---------+----------------------------------+
Finally, let's delete the machine:
Machine http://myprovider.com/cimi/machines/18 being deleted
Job:
+---------+----------------------------------+
|Attribute|Value |
+---------+----------------------------------+
|id |http://myprovider.com/cimi/jobs/18|
+---------+----------------------------------+