This is an automated email from the ASF dual-hosted git repository.

rohit pushed a commit to branch master
in repository 
https://gitbox.apache.org/repos/asf/cloudstack-cloudmonkey.wiki.git


The following commit(s) were added to refs/heads/master by this push:
     new c974335  Updated Usage (markdown)
c974335 is described below

commit c9743356af5cb19d5b173e9ab94ca88294c81b07
Author: Rohit Yadav <ro...@apache.org>
AuthorDate: Thu Mar 14 13:19:41 2019 +0530

    Updated Usage (markdown)
---
 Usage.md | 233 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 231 insertions(+), 2 deletions(-)

diff --git a/Usage.md b/Usage.md
index ece53c7..63445fb 100644
--- a/Usage.md
+++ b/Usage.md
@@ -1,3 +1,232 @@
-Refer to old docs: 
https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI
+Link to old docs: 
https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI
 
-Updates usage docs will be added soon.
\ No newline at end of file
+## Server profiles
+
+CloudMonkey supports multiple (management) server profiles, using which one 
can use to make API requests to different CloudStack servers. If cloudmonkey 
starts for the first time, it will create a default server profile by the name 
`[localcloud]` and use the following default values which one can then override 
using the `set` command. The default `cmk` config file at `~/.cmk/config` looks 
as follows:
+
+```
+prompt          = 🐱
+asyncblock      = true
+timeout         = 1800
+output          = json
+paramcompletion = true
+verifycert      = true
+profile         = localcloud
+
+[localcloud]
+url       = http://localhost:8080/client/api
+username  = admin
+password  = password
+domain    = /
+apikey    = 
+secretkey = 
+```
+
+To create a new server profile, one can use `set profile <profile-name>` and 
this will create a new server profile config section in `~/.cmk/config` and use 
the above default values. You can `set` parameters of a server profile such as 
the url, username, password and it will set the passed values for the current 
server profile.
+
+These are the various options you can configure in `cmk` using `set`:
+
+Option | Description | Default
+---|---|---
+prompt | The CLI prompt | 🐱
+asyncblock | Whether to block and poll for async API job result, valid 
options: true and false | true
+timeout | The API timeout in seconds | 1800
+output | The API response output format, valid options: json, table, text, 
column, csv | json
+verifycert | Whether to verify X509/TLS certificate if URL is https enabled | 
true
+profile | The server profile name, `set` will switch to an existing profile or 
create a new profile with default if it does not exist | localcloud
+url* | The CloudStack server API url | http://localhost:8080/client/api
+username* | The user's username | admin
+password* | The user's password | password
+domain* | The user's domain | /
+apikey* | The user's API key | 
+secretkey* | The user's secret key | 
+
+Notes:
+- Options marked with `*` are settings server profile settings, other settings 
are core/global settings.
+- When both api/secret key and username/passwords are provided, the api/secret 
keys take precedence for API authentication over username/password.
+- An additional setting `debug` exists when can be turned on to enable console 
based debugging.
+
+## Shell and Interactive Usage
+
+`cmk` implements readline compliant shell and most of the emacs/readline 
bindings are honoured. For example:
+Ctrl+r (reverse search), 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.
+
+The command history can be accessed by using up/down arrow keys as well and it 
is saved at `~/.cmk/history`.
+
+## Debugging
+
+Debugging in log is disabled, but you can enable debugging on console by 
starting CloudMonkey with `cmk -d` or use `set debug [true|false]`.
+
+## Argument passing
+
+Arguments can be passed to an api command using the syntax `<cmd> <verb> 
key1=value1 ...`. CloudMonkey's shell input parsing is similar to `shlex` and 
arguments are split by spaces. Arguments/values with space in them can be 
wrapped instead double/single quotes such as `list api arg1="some value with 
spaces" arg2='example input'`.
+
+If values have spaces, one can put them under quotes, like:
+
+```
+> create project name="my unique name" displaytext="my lengthy description"
+```
+
+Some APIs accept array or maps as their arguments, in that case use 
`arg0.key=value` syntax. For example, while creating network offering:
+
+```
+> create networkoffering supportedservices=Dhcp,Dns 
serviceproviderlist[0].service=Dhcp 
serviceproviderlist[0].provider=VirtualRouter 
serviceproviderlist[1].service=Dns serviceproviderlist[1].provider=VirtualRouter
+```
+
+## Text processing using pipes
+
+Text processing is very easy, one can pipe the output to other terminal tools 
such as awk, sed, grep, jq etc. Examples:
+
+```
+$ cmk list users | jq -r '.user[].id'
+$ cmk ...
+> list accounts listall=true | grep 'id'
+> list users | wc -l
+```
+
+## Raw API execution
+
+You may directly call the API on the shell or command-line to execute it, for 
example:
+```
+> listUsers
+> uploadVolume url=xxx format=yyy name=zzz zoneid=aaa
+```
+
+## Async Job execution
+
+There are two kinds of APIs in CloudStack; blocking or synchronous, and 
non-blocking or asynchronous. By default, CloudMonkey will poll and wait for 
async APIs to finish and return a response. This behaviour can be changed by 
seting `asyncblock` to false:
+```
+> set asyncblock false
+```
+
+When `asynblock` is false, CloudMonkey will return a `jobid` which can be used 
to poll the result of the API using the `query asyncjobresult` API request. For 
example:
+```
+> query asyncjobresult jobid=<job-id>
+```
+
+## Output
+
+Irrespective of the configured output, the `filter` argument can be clubbed 
with an API request to filter the API response based on the provided list of 
comma-separated response keys.
+
+The `JSON` output is the default output. For example:
+
+```
+(mycloud) 🐱 > set output json
+(mycloud) 🐱 > list users account=admin filter=
+account,             accountid,           accounttype,         apikey,         
     created,             domain,              domainid,            email,      
         
+firstname,           id,                  iscallerchilddomain, isdefault,      
     lastname,            roleid,              rolename,            roletype,   
         
+secretkey,           state,               timezone,            username,       
     usersource, 
+(mycloud) 🐱 > list users account=admin filter=account,id,domain,username,
+{
+  "count": 1,
+  "user": [
+    {
+      "account": "admin",
+      "domain": "ROOT",
+      "id": "7966afa9-3cd4-11e9-bf33-f4d1082409e6",
+      "username": "admin"
+    }
+  ]
+}
+(mycloud) 🐱 > set output table
+(mycloud) 🐱 > list users account=admin filter=account,id,domain,username
+user:
+count = 1
++---------+--------+--------------------------------------+----------+
+| ACCOUNT | DOMAIN |                  ID                  | USERNAME |
++---------+--------+--------------------------------------+----------+
+| admin   | ROOT   | 7966afa9-3cd4-11e9-bf33-f4d1082409e6 | admin    |
++---------+--------+--------------------------------------+----------+
+(mycloud) 🐱 > set output text
+(mycloud) 🐱 > list users account=admin filter=account,id,domain,username
+count = 1
+user:
+account = admin
+id = 7966afa9-3cd4-11e9-bf33-f4d1082409e6
+domain = ROOT
+username = admin
+(mycloud) 🐱 > set output column
+(mycloud) 🐱 > list users account=admin filter=account,id,domain,username
+ACCOUNT   DOMAIN   ID                                     USERNAME
+admin     ROOT     7966afa9-3cd4-11e9-bf33-f4d1082409e6   admin
+(mycloud) 🐱 > list users account=admin filter=account,id,domain,username
+account,domain,id,username
+admin,ROOT,7966afa9-3cd4-11e9-bf33-f4d1082409e6,admin
+```
+
+## Shell Script Usage
+
+The modern CloudMonkey is backwards compatible with `legacy` cloudmonkey and 
can be used as a drop-in replacement for shell script and automation related 
usage. The follow example illustrates how one can use `cmk` to automate their 
deployments, this one deploys a basic zone:
+
+```
+#!/bin/bash
+ 
+cli=cmk
+dns_ext=8.8.8.8
+dns_int=10.147.28.6
+gw=10.147.28.1
+nmask=255.255.255.0
+hpvr=XenServer
+pod_start=10.147.28.225
+pod_end=10.147.28.234
+vlan_start=10.147.28.235
+vlan_end=10.147.28.254
+ 
+#Put space separated host ips in following
+host_ips=10.147.28.60
+host_user=root
+host_passwd=password
+sec_storage=nfs://10.147.28.7/export/home/rohit/secondary
+prm_storage=nfs://10.147.28.7/export/home/rohit/primary
+ 
+zone_id=`$cli create zone dns1=$dns_ext internaldns1=$dns_int name=MyZone 
networktype=Basic | grep ^id\ = | awk '{print $3}'`
+echo "Created zone" $zone_id
+ 
+phy_id=`$cli create physicalnetwork name=phy-network zoneid=$zone_id | grep 
^id\ = | awk '{print $3}'`
+echo "Created physical network" $phy_id
+$cli add traffictype traffictype=Guest physicalnetworkid=$phy_id
+echo "Added guest traffic"
+$cli add traffictype traffictype=Management physicalnetworkid=$phy_id
+echo "Added mgmt traffic"
+$cli update physicalnetwork state=Enabled id=$phy_id
+echo "Enabled physicalnetwork"
+ 
+nsp_id=`$cli list networkserviceproviders name=VirtualRouter 
physicalnetworkid=$phy_id | grep ^id\ = | awk '{print $3}'`
+vre_id=`$cli list virtualrouterelements nspid=$nsp_id | grep ^id\ = | awk 
'{print $3}'`
+$cli api configureVirtualRouterElement enabled=true id=$vre_id
+$cli update networkserviceprovider state=Enabled id=$nsp_id
+echo "Enabled virtual router element and network service provider"
+ 
+nsp_sg_id=`$cli list networkserviceproviders name=SecurityGroupProvider 
physicalnetworkid=$phy_id | grep ^id\ = | awk '{print $3}'`
+$cli update networkserviceprovider state=Enabled id=$nsp_sg_id
+echo "Enabled security group provider"
+ 
+netoff_id=`$cli list networkofferings 
name=DefaultSharedNetworkOfferingWithSGService | grep ^id\ = | awk '{print $3}'`
+net_id=`$cli create network zoneid=$zone_id name=guestNetworkForBasicZone 
displaytext=guestNetworkForBasicZone networkofferingid=$netoff_id | grep ^id\ = 
| awk '{print $3}'`
+echo "Created network $net_id for zone" $zone_id
+ 
+pod_id=`$cli create pod name=MyPod zoneid=$zone_id gateway=$gw netmask=$nmask 
startip=$pod_start endip=$pod_end | grep ^id\ = | awk '{print $3}'`
+echo "Created pod"
+ 
+$cli create vlaniprange podid=$pod_id networkid=$net_id gateway=$gw 
netmask=$nmask startip=$vlan_start endip=$vlan_end forvirtualnetwork=false
+echo "Created IP ranges for instances"
+ 
+cluster_id=`$cli add cluster zoneid=$zone_id hypervisor=$hpvr 
clustertype=CloudManaged podid=$pod_id clustername=MyCluster | grep ^id\ = | 
awk '{print $3}'`
+echo "Created cluster" $cluster_id
+ 
+#Put loop here if more than one
+for host_ip in $host_ips;
+do
+  $cli add host zoneid=$zone_id podid=$pod_id clusterid=$cluster_id 
hypervisor=$hpvr username=$host_user password=$host_passwd url=http://$host_ip;
+  echo "Added host" $host_ip;
+done;
+ 
+#$cli create storagepool zoneid=$zone_id podid=$pod_id clusterid=$cluster_id 
name=MyNFSPrimary url=$prm_storage
+#echo "Added primary storage"
+ 
+$cli add secondarystorage zoneid=$zone_id url=$sec_storage
+echo "Added secondary storage"
+ 
+$cli update zone allocationstate=Enabled id=$zone_id
+echo "Basic zone deloyment completed!"
+```
\ No newline at end of file

Reply via email to