Page History

...

Usable as a command line tool and interactive shell
Management server profiles: select, customize and use different server profiles using
All commands are lowercase unlike API
Api Discovery using sync feature, with build time api precaching for failsafe sync
Raw api execution support
Auto-completion via double <tab>
Reverse search using Ctrl+R
Emacs compatible keybindings
Pipeable output
Unix shell execution
Support to handle async jobs using user defined blocking or non-blocking way
Tabular or JSON output with filtering of table columns
Colored output
Unicode support
Api parameter value completion (based on predication, fuzzy results may fail sometimes)

Installation

Requirements

cloudmonkey requires Python 2.5 or above and has following dependencies:

Code Block
readline Pygments prettytable

NOTE: Version 6.x+ wiki has moved here https://github.com/apache/cloudstack-cloudmonkey/wiki, for usage see https://github.com/apache/cloudstack-cloudmonkey/wiki/Usage

Installation

Requirements

cloudmonkey 5.x requires Python 2.6 or above and has following dependencies:

Code Block
readline requests Pygments prettytable argcomplete

Platform independent installation

...

Code Block
$ apt-get install python-setuptools $ easy_install cloudmonkey

Building from source code

...

cloudmonkey is moved to a separate git repo

more info @ https://git-wip-us.apache.org/repos/asf?p=cloudstack.git;a=commit;h=6f84e74a68d78705a06fe58f7927f42f61453a16

Code Block

$ git

Code Block

$ git clone https://git-wip-us.apache.org/repos/asf/cloudstack-cloudmonkey.git
# Run mgmt server and run "cloudmonkey sync", this is only for build time cache generation using cachemaker.py
$ python setup.py build 
$ python setup.py install

...

Typical ~/.cloudmonkey/config for version 5.2.0 and above:

Code Block

[core]
log_fileprofile = /Users/bhaisaab/.cloudmonkey/loglocal
asyncblock = true
paramcompletion = falsetrue
history_file = /Users/bhaisaab/.cloudmonkey/history

[ui]
color = log_file = /Users/bhaisaab/.cloudmonkey/log
cache_file = /Users/bhaisaab/.cloudmonkey/cache

[ui]
color = true
prompt = >
display = default

[userlocal]
secretkeyurl = "enter your developer secret key" "enter your developer secret key"
apikey = "enter API key" "enter API key"

[server]
path = /client/api
host = localhost
protocol = http
port = 8080
timeout = 3600
http://localhost:8080/client/api
username = admin
password = password
apikey =
secretkey =
timeout = 3600
expires = 600

The following configuration parameters can be configured by using the 'set' command in cloudmonkey:

Key

Purpose

Default

host

IP or resolvable domain of management server

localhost

port

Api server port, 8080 is encouraged over 8096

8080

protocol

Specifies http or https

http

path

Specifies the absolute path to the api on the specified host

profile	Management server profile name	local
url	Management server API url (it should contain full url with protocol, port etc and paths)	http://localhost:8080/client/api
timeout	Timeout interval for polling async commands	3600
apikey	User api key	""
secretkey	User secret key	""

color

Enable coloured output, set to false

verifysslcert	Enables/Disables SSL certification verification when making HTTP calls (per server profile)	true
username	CloudStack user name	admin
password	CloudStack user password	password
color	Enable coloured output, set to false to disable	true
prompt	cloudmonkey prompt	>
display	Line based, JSON, or tabular output, set to default or json or table	default
log_file	Log file	~/.cloudmonkey/log
history_file	History file	~/.cloudmonkey/history
asyncblock	Poll for async commands, making it false will cause cloudmonkey to return jobid	true
paramcompletion	Tries to predict api for listing a parameter value for an api, experimental may fail

false

Usage

Getting started

true

Note: If both username/password and apikey/secretkey are set (i.e. have non-empty values), apikey and secretkey are used while making HTTP API calls.

Usage

Getting started

By default cloudmonkey will create 'local' server profile when it will start.

First set the management server API url, apikey and secretkey etc.

First set your host, port, apikey and secretkey using set. Api and Secret keys can be created via CloudStack management server UI, Accounts->Users->Generate keys. One can also use username and password though use of keys is recommended. CloudMonkey first tries to authenticate using apikey/secret key if provided, then if port specified in the URL is 8096 cloudmonkey assumes user is trying to use integration port and if both of them don't qualify i.e. keys are not provided and port is not 8096 we try to authenticate with username and password.

Code Block

> set url https://api.exoscale.ch:443/compute
> set apikey <put

Code Block

> set host 192.168.56.1
> set port 8080
> set apikey <put-your-api-key-for-your-user>
> set secretkey <put-your-secret-key-for-your-user>
> set prompt mycloudmonkey>

Make sure your management server is running, discover and sync/pull latest apis:

Code Block
> sync 324500 APIs discovered and cached

...

Code Block

> help list users
(listUsers) Lists user accounts
Parameters
==========
id = (uuid) List user by ID.
keyword = (string) List by keyword
accounttype = (long) List users by account type. Valid types include admin, domain-admin, read-only-admin, or user.
username = (string) List user by the username
domainid = (uuid) list only resources belonging to the domain specified
page = (integer)
pagesize = (integer)
listall = (boolean) If set to false, list only resources belonging to the command's caller; if set to true - list resources that the caller is authorized to see. Default value is false
state = (string) List users by state of the user account.
isrecursive = (boolean) defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves.
account = (string) list resources by account. Must be used with the domainId parameter.

Tabular output

You may enable tabular listing and even choose set of column fields, this allows you to create your own field using the filter param which takes in comma separated argument. If argument has a space, put them under double quotes. The create table will have the same sequence of field filters provided. If your present cli does not have this, pl. upgrade cloudmonkey: pip install --upgrade cloudmonkey
To enable tabular output:

Code Block
> set display table

Examples:

Management server profiles

CloudMonkey version 5.2.0 and above will support multiple (management) server profiles, so one can use the tool on the fly toggling between different CloudStack server in the interpreter mode. If cloudmonkey starts for the first time, it will create a default server profile by the name [local] and use the following default values which one can then override using the `set` command. The profile in use is set in the [core] section's profile parameter which is read at the time cloudmonkey loads.

Code Block
[core] profile = local ... [local] url = http://localhost:8080/client/api username = admin password = password apikey = secretkey = timeout = 3600 expires = 600

To create a new server profile, one can use: set profile <profile-name> and this will create a new server profile config section in ~/.cloudmonkey/config and use the above default values. Using set command on params such as url, username, password etc. will set these values for the currently selected profile only. Note: profile names cannot be whitespace/blank '', core or ui.

Tabular output

You may enable tabular listing and even choose set of column fields, this allows you to create your own field using the filter param which takes in comma separated argument. If argument has a space, put them under double quotes. The create table will have the same sequence of field filters provided. If your present cli does not have this, pl. upgrade cloudmonkey: pip install --upgrade cloudmonkey
To enable tabular output:

Code Block
> set display table

Examples:

Code Block

> list users account=admin username=admin filter=account,accountid,accounttype,created,domain
count = 1
user:
+---------+---------------

Code Block

> list users account=admin username=admin filter=account,accountid,accounttype,created,domain
count = 1
user:
+---------+--------------------------------------+-------------+--------------------------+--------+
| account |              accountid               | accounttype |         created          | domain |
+---------+--------------+-------------+-----------+-------------+--+------------------------+--------+
|  admin  | dc8ece35-9f03-401f-95f1-2db99c467e1c |+
| account |              accountid         1      | 2013-04-03T02:13:25-0500accounttype |  ROOT  |
+       created          | domain |
+---------+--------------------------------------+-------------+--------------------------+--------+

Tabular output comes with filtering, using filter parameter you can ask cloudmonkey to filter particular columns (like select field of mysql).

JSON output

JSON output formats cloudmonkey's output into pretty generated JSON documents. Filtering may also be used to limit the result set. Even with filtering, a valid JSON document is generated and may be saved into an external file and processed with your favorite programming language. If your present cli does not have this, pl. upgrade cloudmonkey: pip install --upgrade cloudmonkey
To enable json output:

Code Block
> set display json

Examples:

|  admin  | dc8ece35-9f03-401f-95f1-2db99c467e1c |      1      | 2013-04-03T02:13:25-0500 |  ROOT  |
+---------+--------------------------------------+-------------+--------------------------+--------+

Tabular output comes with filtering, using filter parameter you can ask cloudmonkey to filter particular columns (like select field of mysql).

JSON output

JSON output formats cloudmonkey's output into pretty generated JSON documents. Filtering may also be used to limit the result set. Even with filtering, a valid JSON document is generated and may be saved into an external file and processed with your favorite programming language. If your present cli does not have this, pl. upgrade cloudmonkey: pip install --upgrade cloudmonkey
To enable json output:

Code Block
> set display json

Examples:

Code Block

> list users account=admin username=admin filter=account,accountid,accounttype,created,domain
{
  "count": 1,
  "

Code Block

> list users account=admin username=admin filter=account,accountid,accounttype,created,domain
{
  "count": 1,
  "user": [
    {
      "account": "admin",
      "accountid": "dc8ece35-9f03-401f-95f1-2db99c467e1c",
      "accounttype": 1,
      "created": "2013-04-03T02:13:25-0500",
      "domain": "ROOT"
    }
  ]
}
",
      "accounttype": 1,
      "created": "2013-04-03T02:13:25-0500",
      "domain": "ROOT"
    }
  ]
}

Filtering output

CloudMonkey can filter output based on keys. Starting 5.3.0, filter is supported for all display outputs (json, default and table) and autocompletion works as well.

Code Block

> list users filter=<tab><tab>
account,             accounttype,         created,             domainid,            firstname,           iscallerchilddomain, lastname,            state,               username,           
accountid,           apikey,              domain,              email,               id,                  isdefault,           secretkey,           timezone,           
> list users filter=id,username,firstname,lastname,

id = ef33f4a0-e7cf-11e3-a8a4-005056867a67
firstname = admin
lastname = cloud
username = admin
================================================================================
id = d052dfb3-828c-4fa3-9e72-75f4795bb554
firstname = रोहित
lastname = यादव
username = रोहित

Emacs style key handling

Ctrl+a (start of the line)
Ctrl+e (end of the line)
Ctlr+w (remove one word from back)
Ctrl+u (remove whole line) etc.

...

Code Block
> list accounts listall=true \| grep '^id\ =' > list users \| wc -l > list routers \| more

...

This causes an async command in cloudmonkey to return a jobid which can be used to poll the completion of that command. This is particularly useful if one wants to starts a lot of VMs without having to wait for the commands to complete. The job can be polled using query async job command, like:

Code Block
> query asyncjobresult jobid=<job-id>

Parameter completion

complete. The job can be polled using query async job command, like:

Code Block
> query asyncjobresult jobid=<job-id>

Parameter completion

Starting 5.3.0 version, parameter implementation works well for api arguments which are of uuid and boolean types. It can be enabled by setting paramcompletion to true. To automatically find out how to get values for a api arg it uses two heuristics (list apis and most likely related list api) so it is quite possible there are corner cases where this may fail. Whenever a list api is called or when parameter completion calls a list api in background, those results (pair of uuid and name strings) are cached by CloudMonkey to speed up rendering. The cache is kept for next 10-15 mins, after which a list api is called again in the backgroundA fuzzy implementation of parameter completion for an api is an experimental feature (a full proof feature would require annotations on each api cmd), this lets user complete a param on tabbing. It can be enabled by setting paramcompletion to true. At present it only works for only those params which accept a uuid.
Example:

Code Block
> list users id= cd58ff50-8642-11e2-9a8b-37057334a9b2 user1

TODOs

0. Unicode support
1. Bash/zsh completion (example: https://github.com/bobthecow/git-flow-completion/)

About

cloudmonkey was named after the beloved mascot of Apache CloudStack.
AuthorDev ML: The Apache CloudStack Team <cloudstack-dev@incubator<dev@cloudstack.apache.org>
Maintainer: Rohit Yadav <bhaisaab@apache.org>

Space shortcuts

Child pages

Versions Compared

Old Version 29

New Version Current

Key

Installation

Requirements

NOTE: Version 6.x+ wiki has moved here https://github.com/apache/cloudstack-cloudmonkey/wiki, for usage see https://github.com/apache/cloudstack-cloudmonkey/wiki/Usage

Installation

Requirements

Platform independent installation

Building from source code

Usage

Getting started

Usage

Getting started

Tabular output

Management server profiles

Tabular output

JSON output

JSON output

Filtering output

Emacs style key handling

Parameter completion

Parameter completion

TODOs

About