%BOOK_ENTITIES; ]>

CloudMonkey is the &PRODUCT; Command Line Interface (CLI). It is written in Python and leverages Marvin. CloudMonkey can be used both as an interactive shell and as a command line tool which simplifies &PRODUCT; configuration and management. CloudMonkey is still under development and should be considered a Work In Progress (WIP), the wiki is the most up to date documentation: https://cwiki.apache.org/CLOUDSTACK/cloudstack-cloudmonkey-cli.html

There are two ways to get CloudMonkey: Via the official Apache &PRODUCT; releases (starting with 4.1). Via a community maintained package on Cheese Shop pip install cloudmonkey

To configure CloudMonkey you can edit the .cloudmonkey_config file in the user's home directory as shown below. The values can also be set interactively at the cloudmonkey prompt $ cat .cloudmonkey_config [CLI] protocol = http asyncblock = true color = true prompt = cloudmonkey> history_file = /Users/sebastiengoasguen/.cloudmonkey_history host = localhost path = /client/api port = 8080 apikey = plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg secretkey = VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ timeout = 600 log_file = /Users/sebastiengoasguen/.cloudmonkey_log The values can also be set at the cloudmonkey prompt. The API and secret keys are obtained via the &PRODUCT; UI or via a raw api call. set prompt myprompt> myprompt> set host localhost myprompt> set port 8080 myprompt> set apikey myprompt> set secretkey ]]> You can use cloudmonkey to interact with a local cloud, and even with a remote public cloud. You just need to set the host value properly and obtain the keys from the cloud administrator.

To start learning cloudmonkey, the best is to use the interactive shell. Simply type cloudmonkey at the prompt and you should get the interactive shell. At the cloudmonkey prompt press the tab key twice, you will see all potential verbs available. Pick on, enter a space and then press tab twice. You will see all actions available for that verb EOF assign cancel create detach extract ldap prepare reconnect restart shell update activate associate change delete disable generate list query register restore start upload add attach configure deploy enable get mark quit remove revoke stop api authorize copy destroy exit help migrate reboot reset set suspend cloudmonkey>create account diskoffering loadbalancerrule portforwardingrule snapshot tags vpc autoscalepolicy domain network privategateway snapshotpolicy template vpcoffering autoscalevmgroup firewallrule networkacl project sshkeypair user vpnconnection autoscalevmprofile instancegroup networkoffering remoteaccessvpn staticroute virtualrouterelement vpncustomergateway condition ipforwardingrule physicalnetwork securitygroup storagenetworkiprange vlaniprange vpngateway counter lbstickinesspolicy pod serviceoffering storagepool volume zone ]]> Picking one action and entering a space plus the tab key, you will obtain the list of parameters for that specific api call. create network account= domainid= isAsync= networkdomain= projectid= vlan= acltype= endip= name= networkofferingid= startip= vpcid= displaytext= gateway= netmask= physicalnetworkid= subdomainaccess= zoneid= ]]> To get additional help on that specific api call you can use the following: create network -h Creates a network Required args: displaytext name networkofferingid zoneid Args: account acltype displaytext domainid endip gateway isAsync name netmask networkdomain networkofferingid physicalnetworkid projectid startip subdomainaccess vlan vpcid zoneid cloudmonkey>create network -help Creates a network Required args: displaytext name networkofferingid zoneid Args: account acltype displaytext domainid endip gateway isAsync name netmask networkdomain networkofferingid physicalnetworkid projectid startip subdomainaccess vlan vpcid zoneid cloudmonkey>create network --help Creates a network Required args: displaytext name networkofferingid zoneid Args: account acltype displaytext domainid endip gateway isAsync name netmask networkdomain networkofferingid physicalnetworkid projectid startip subdomainaccess vlan vpcid zoneid cloudmonkey> ]]> Note the required arguments necessary for the calls. To find out the required parameters value, using a debugger console on the &PRODUCT; UI might be very useful. For instance using Firebug on Firefox, you can navigate the UI and check the parameters values for each call you are making as you navigate the UI.

To start a virtual machine instance we will use the deploy virtualmachine call. deploy virtualmachine -h Creates and automatically starts a virtual machine based on a service offering, disk offering, and template. Required args: serviceofferingid templateid zoneid Args: account diskofferingid displayname domainid group hostid hypervisor ipaddress iptonetworklist isAsync keyboard keypair name networkids projectid securitygroupids securitygroupnames serviceofferingid size startvm templateid userdata zoneid ]]> The required arguments are serviceofferingid, templateid and zoneid In order to specify the template that we want to use, we can list all available templates with the following call: list templates templatefilter=all count = 2 template: ======== domain = ROOT domainid = 8a111e58-e155-4482-93ce-84efff3c7c77 zoneid = e1bfdfaf-3d9b-43d4-9aea-2c9f173a1ae7 displaytext = SystemVM Template (XenServer) ostypeid = 849d7d0a-9fbe-452a-85aa-70e0a0cbc688 passwordenabled = False id = 6d360f79-4de9-468c-82f8-a348135d298e size = 2101252608 isready = True templatetype = SYSTEM zonename = devcloud ... ]]> In this snippet, I used DevCloud and only showed the beginning output of the first template, the SystemVM template Similarly to get the serviceofferingid you would do: list serviceofferings | grep id id = ef2537ad-c70f-11e1-821b-0800277e749c id = c66c2557-12a7-4b32-94f4-48837da3fa84 id = 3d8b82e5-d8e7-48d5-a554-cf853111bc50 ]]> Note that we can use the linux pipe as well as standard linux commands within the interactive shell. Finally we would start an instance with the following call: deploy virtualmachine templateid=13ccff62-132b-4caf-b456-e8ef20cbff0e zoneid=e1bfdfaf-3d9b-43d4-9aea-2c9f173a1ae7 serviceofferingid=ef2537ad-c70f-11e1-821b-0800277e749c jobprocstatus = 0 created = 2013-03-05T13:04:51-0800 cmd = com.cloud.api.commands.DeployVMCmd userid = 7ed6d5da-93b2-4545-a502-23d20b48ef2a jobstatus = 1 jobid = c441d894-e116-402d-aa36-fdb45adb16b7 jobresultcode = 0 jobresulttype = object jobresult: ========= virtualmachine: ============== domain = ROOT domainid = 8a111e58-e155-4482-93ce-84efff3c7c77 haenable = False templatename = tiny Linux ... ]]> The instance would be stopped with: cloudmonkey>stop virtualmachine id=7efe0377-4102-4193-bff8-c706909cc2d2 The ids that you will use will differ from this example. Make sure you use the ones that corresponds to your &PRODUCT; cloud.

All previous examples use CloudMonkey via the interactive shell, however it can be used as a straightfoward CLI, passing the commands to the cloudmonkey command like shown below. $cloudmonkey list users As such it can be used in shell scripts, it can received commands via stdin and its output can be parsed like any other unix commands as mentioned before.