<?xml version='1.0' encoding='utf-8' ?>

<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">

]>

<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="https://cwiki.apache.org/CLOUDSTACK/cloudstack-cloudmonkey-cli.html">https://cwiki.apache.org/CLOUDSTACK/cloudstack-cloudmonkey-cli.html</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 4.1).</para>

<programlisting>

<![CDATA[

</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 prompt</para>

<programlisting>

$ 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

</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>

</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 administrator.</para>

</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>

</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>

</programlisting>

<para>To get additional help on that specific api call you can use the following:</para>

<programlisting>

</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>

</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>

</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>

</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>

</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; cloud.</para></note>

</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>

</section>

<imagedata fileref="./images/DevCloud.png" scale="50"/>

<imagedata fileref="./images/DevCloud-hostonly.png" scale="50"/>

<xi:include href="cloudmonkey.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />