satis egitimisatis


Discussion on the state of cloud computing and open source software that helps build, manage, and deliver everything-as-a-service.

  • Home
    Home This is where you can find all the blog posts throughout the site.
  • Categories
    Categories Displays a list of categories from this blog.
  • Tags
    Tags Displays a list of tags that has been used in the blog.
  • Bloggers
    Bloggers Search for your favorite blogger from this site.
  • Login
Posted by on in CloudStack Tips
  • Font size: Larger Smaller
  • Hits: 53199
  • Print
  • Report this post

Beginners guide to interacting with the CloudStack API

CloudStack has a nice (and ever improving) UI, and sometimes the robust API gets ignored. I recently had to help another open source project that wants to interact with CloudStack via the API and figured I'd post some of that experience here. I should note that there is also CloudBridge which permits you to use the EC2 API to interface with CloudStack, so you can make use of the ec2 and euca client tools to interface with CloudStack, but this post talks only about the native CloudStack API


Lets first talk about access - there are two API interfaces. The first is unauthenticated and listens on port 8096. This is really designed to be called from localhost, and if you aren't using it we advise ensuring that it stays firewalled off or is disabled. It is pretty simple to query

So you can for instance run the following from your management server:

$ curl http://localhost:8096/?command=listHosts

The above will return a list of physical compute nodes. You'll notice I used curl in this example and in the ones to follow to call the API, you could do this equally well with wget or even a web browser.

The second, more 'public' interface that runs on the same port as the UI, which is port 8080 for most people. This requires authentication, and is a 'bit' more work to generate requests. The additional work comes from the fact that you must specify your API key, and you must 'sign' your request using your Secret Key. We'll talk more about that in a bit when we talk about forming requests, but here is what the above request would like on the authenticated interface:

$ curl


If you tried the above requests you likely saw an XML response, which is pretty useful, but many prefer JSON, so you can append &response=json to your command and it will provide you with a response in JSON

Forming requests

The above examples has been pretty simple, listing all the hosts. Well that makes for a simplistic view of getting information out, but there are plenty of things that can be done from the API, we'll initially stick with a few examples of getting information but we'll add some examples of making CloudStack do work as well. We'll be doing this using the local unauthenticated API interface till we discuss more properly forming the requests.

$ curl http://localhost:8096/?command=listCapacity

The above will tell you about the capacity of your cloud, certainly interesting, but rather generic.

$ curl http://localhost:8096/?command=listVirtualMachines&domainId=1&account=admin

This shows all of the VM instances owned by the Admin user.

Lets move on to making CloudStack do something.

$ curl http://localhost:8096/?command=stopVirtualMachine&id=6

The above stops one of the virtual machines I listed earlier. If you try this you'll notice the response is a bit different. That's because this is an asynchronous call. It will give you the job id, but because the response might actually take a few seconds or even a few minutes it provides an immediate response with the job id. For me it provided job id 33, so I can use the following to check on the status:

$ curl http://localhost:8096/?command=queryAsyncJobResult&jobid=33

This is going to provide a set of result codes, which are pretty simple and as follows:

0 - Job is still in progress. Continue to periodically poll for any status changes.
1 - Job has successfully completed. The job will return any successful response values associated with command that was originally executed.
2 - Job has failed to complete.  Please check the tag for failure reason code and for the failure reason.

$ curl http://localhost:8096/?command=deployVirtualMachine&serviceofferingid=1&zoneid=1&templateid=4

The above deploys a virtual machine in my first zone. I can of course specify a veritable plethora of other configuration items. The API is pretty robust.

Now as promised I said we'd talk about sending API requests to the 'public' API interface. I could describe the process of generating these requests, but figure you could read the official documentation if you are really interested in the mechanics. Instead I'll get you up and firing off API requests in short order.

You'll need to acquire two pieces of information from the UI, and that's the API and Secret Key for the user you are wanting to use. I should add in here, that all of these commands have assumed that the user is an admin - domain admins and users have fewer permissions, and smaller default scopes. You can find the your keys by going to Accounts, locating your account, click on the Users tab, find your user and you should see fields for API key and Secret Key. If these aren't populated, click on 'Generate Keys' from the Actions drop down menu.

For the purpose of this documentation, the API key is:


and the Secret key is:


I tend to be a bit lazy, and found a nice perl script from shugonumano on github that makes this process a bit easier (and to be fair, there's some java code in CloudStack's API documentation, but this is a bit smaller and easier to use, in my opinion) You can grab a copy of that script at:

So I provide the inputs that requests: -u "command=" -a -s

$ -u "command=listcapacity"
-a TEBBqfXkV-9blsxpkjFLAxNUmnvMsFEq7WKwPOMT_nuce69bmcElXz1izsN1qJFK58ye5U5hWWN2ckscsysodg
-s 7VJx0QfxvJQZBYZbLdct2QFck8lV6hwLMvo9YCJ97pVou8f_aDSHdhEqBaY2CtFI6_MULP0eYqr_Z7D2Jon8nQ

A couple of things that you should note, the command isn't using camelcase or studly caps, instead it's all lowercase.

That spits out the url:


You'll note that this doesn't work, you'll need to reintroduce the appropriate caps into the command like:


And that's really all there is to it, which makes it relatively easy to integrate CloudStack with your monitoring system, configuration management, etc. You'll certainly want to make CloudStack's API documentation readily available:

If you have questions don't hesitate to ask on on of the mailing lists or in IRC

Rate this blog entry:
Trackback URL for this blog entry.
David Nalley is currently employed by Citrix as the Community Manager for the CloudStack project. In addition he's a long time contributor to the Fedora Project, where among other things he is currently serving on the Fedora Project Board. He's also contributed to in various forms to Cobbler, Zenoss,, OLPC Math4, and Sahana. He is a frequent speaker at Free Software conferences around the nation, and writes for a number of technical and open source media publications including Linux Pro Magazine and
  • Peter
    Peter Thursday, 29 March 2012 Dependencies

    Could you please add some instructions for how to install the dependencies for the generate-url script? I'm using Centos 6 for my management server, and it's driving me nuts trying to get this script to work. I am not finding many of the dependencies when I do a "yum search". I really wish the Linux community had some sense about standardizing the names of packages!! Thanks!

  • Nguyen Anh Tu
    Nguyen Anh Tu Monday, 20 August 2012

    RE: Dependencies

    using cpan will help.

    cpan -i

  • Raghav
    Raghav Thursday, 23 August 2012

    Yesterday, i have successfully utilized the by resolved the dependencies

    Use the below steps
    perl -e shell -MCPAN
    cpan>> install ... (required modules for the perl script)
    apt-get (or) yum install libjson-perl

    will solve your issue :D

Leave your comment

Guest Saturday, 19 July 2014


Citrix supports the open source community via developer support and evangeslism. We have a number of developers and evangelists that participate actively in the open source community in Apache Cloudstack, OpenDaylight, Xen Project and XenServer. We also conduct educational activities via the Build A Cloud events held all over the world.