cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject git commit: refs/heads/4.1 - Docs: CLOUDSTACk-825 cloudmonkey docs
Date Tue, 05 Mar 2013 21:34:27 GMT
Updated Branches:
  refs/heads/4.1 bf40ab48f -> fbf300334

Docs: CLOUDSTACk-825 cloudmonkey docs


Branch: refs/heads/4.1
Commit: fbf300334d617babdfc4d944c8ab5e4c0548245e
Parents: bf40ab4
Author: Sebastien Goasguen <>
Authored: Tue Mar 5 16:33:23 2013 -0500
Committer: Sebastien Goasguen <>
Committed: Tue Mar 5 16:34:15 2013 -0500

 docs/en-US/cloudmonkey.xml         |  224 +++++++++++++++++++++++++++++++
 docs/en-US/devcloud-usage-mode.xml |    4 +-
 docs/en-US/tools.xml               |    1 +
 3 files changed, 227 insertions(+), 2 deletions(-)
diff --git a/docs/en-US/cloudmonkey.xml b/docs/en-US/cloudmonkey.xml
new file mode 100644
index 0000000..0057562
--- /dev/null
+++ b/docs/en-US/cloudmonkey.xml
@@ -0,0 +1,224 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" ""
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+<section id="cloudmonkey">
+    <title>CloudMonkey</title>
+    <para>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.</para>
+    <warning>
+        <para>CloudMonkey is still under development and should be considered a Work
In Progress (WIP), the wiki is the most up to date documentation:</para>
+        <para><ulink url=""></ulink></para>
+    </warning>
+    <section id="gettingcloudmonkey">
+    <title>Installing CloudMonkey</title>
+        <para>There are two ways to get CloudMonkey:</para>
+        <para><itemizedlist>
+            <listitem>
+                <para>Via the official Apache &PRODUCT; releases (starting with
+                    <programlisting>
+    <![CDATA[
+$ git clone
+$ mvn clean install -P developer
+$ cd tools/cli # cloudmonkey-x.x.x.tar.gz will be built in dist
+$ python build
+$ python install
+    ]]>
+                    </programlisting>
+            </listitem>
+            <listitem>
+                <para>Via a community maintained package on Cheese Shop</para>
+                <para><programlisting>pip install cloudmonkey</programlisting></para>
+            </listitem>
+        </itemizedlist>
+        </para>
+    </section>
+    <section id="configuringcloudmonkey">
+    <title>Configuration</title>
+    <para>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
+    <programlisting>
+$ cat .cloudmonkey_config 
+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
+    </programlisting>
+    <para>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.</para>
+    <programlisting>
+$ cloudmonkey
+☁ Apache CloudStack cloudmonkey 4.0.0. Type help or ? to list commands.
+cloudmonkey> set prompt myprompt>
+myprompt> set host localhost
+myprompt> set port 8080
+myprompt> set apikey <your api key>
+myprompt> set secretkey <your secret key>
+    </programlisting>
+    <para>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
+    </section>
+    <section id="interactivecli">
+    <title>Interactive Shell Usage</title>
+    <para>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.</para>
+    <para>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</para>
+    <programlisting>
+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    
+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
+    </programlisting>
+    <para>Picking one action and entering a space plus the tab key, you will obtain
the list of parameters for that specific api call.</para>
+    <programlisting>
+cloudmonkey>create network 
+account=            domainid=           isAsync=            networkdomain=      projectid=
+acltype=            endip=              name=               networkofferingid=  startip=
+displaytext=        gateway=            netmask=            physicalnetworkid=  subdomainaccess=
+    </programlisting>
+    <para>To get additional help on that specific api call you can use the following:</para>
+    <programlisting>
+cloudmonkey>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
+    </programlisting>
+    <para>Note the required arguments necessary for the calls.</para>
+    <note><para>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.</para></note>
+    </section>
+    <section id="startingavmexample">
+    <title>Starting a Virtual Machine instance with CloudMonkey</title>
+    <para>To start a virtual machine instance we will use the <emphasis>deploy
virtualmachine</emphasis> call.</para>
+    <programlisting>
+cloudmonkey>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
+    </programlisting>
+    <para>The required arguments are <emphasis>serviceofferingid, templateid
and zoneid</emphasis></para>
+    <para>In order to specify the template that we want to use, we can list all available
templates with the following call:</para>
+    <programlisting>
+cloudmonkey>list templates templatefilter=all
+count = 2
+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
+    </programlisting>
+    <para>In this snippet, I used DevCloud and only showed the beginning output of
the first template, the SystemVM template</para>
+    <para>Similarly to get the <emphasis>serviceofferingid</emphasis> you
would do:</para>
+    <programlisting>
+cloudmonkey>list serviceofferings | grep id
+id = ef2537ad-c70f-11e1-821b-0800277e749c
+id = c66c2557-12a7-4b32-94f4-48837da3fa84
+id = 3d8b82e5-d8e7-48d5-a554-cf853111bc50
+    </programlisting>
+    <para>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:</para>
+    <programlisting>
+cloudmonkey>deploy virtualmachine templateid=13ccff62-132b-4caf-b456-e8ef20cbff0e zoneid=e1bfdfaf-3d9b-43d4-9aea-2c9f173a1ae7
+jobprocstatus = 0
+created = 2013-03-05T13:04:51-0800
+cmd =
+userid = 7ed6d5da-93b2-4545-a502-23d20b48ef2a
+jobstatus = 1
+jobid = c441d894-e116-402d-aa36-fdb45adb16b7
+jobresultcode = 0
+jobresulttype = object
+domain = ROOT
+domainid = 8a111e58-e155-4482-93ce-84efff3c7c77
+haenable = False
+templatename = tiny Linux
+    </programlisting>
+    <para>The instance would be stopped with:</para>
+    <programlisting>
+cloudmonkey>stop virtualmachine id=7efe0377-4102-4193-bff8-c706909cc2d2
+    </programlisting>
+    <note><para>The <emphasis>ids</emphasis> that you will use will
differ from this example. Make sure you use the ones that corresponds to your &PRODUCT;
+    </section>
+    <section id="scriptingcli">
+    <title>Scripting with CloudMonkey</title>
+    <para>All previous examples use CloudMonkey via the interactive shell, however
it can be used as a straightfoward CLI, passing the commands to the <emphasis>cloudmonkey</emphasis>
command like shown below.</para>
+    <para><programlisting>$cloudmonkey list users</programlisting></para>
+    <para>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.</para>
+    </section>
diff --git a/docs/en-US/devcloud-usage-mode.xml b/docs/en-US/devcloud-usage-mode.xml
index bb65f90..bc211ce 100644
--- a/docs/en-US/devcloud-usage-mode.xml
+++ b/docs/en-US/devcloud-usage-mode.xml
@@ -32,7 +32,7 @@
             <para>The following diagram shows the architecture of the SandBox mode.</para>
-                    <imagedata fileref="./images/DevCloud.png" />
+                    <imagedata fileref="./images/DevCloud.png" scale="50"/>
                     <phrase>DevCloud.png: Schematic of the DevCloud SandBox architecture</phrase>
@@ -49,7 +49,7 @@
             <para>The following schematic shows the architecture of the Host-Only mode.</para>
-                    <imagedata fileref="./images/DevCloud-hostonly.png" />
+                    <imagedata fileref="./images/DevCloud-hostonly.png" scale="50"/>
                     <phrase>DevCloud-hostonly.png: Schematic of the DevCloud host-only
architecture </phrase>
diff --git a/docs/en-US/tools.xml b/docs/en-US/tools.xml
index 66fe894..db6a510 100644
--- a/docs/en-US/tools.xml
+++ b/docs/en-US/tools.xml
@@ -26,4 +26,5 @@
   <xi:include href="devcloud.xml" xmlns:xi="" />
   <xi:include href="marvin.xml" xmlns:xi="" />
+  <xi:include href="cloudmonkey.xml" xmlns:xi="" />

View raw message