Programmer Guide

This guide shows how to develop CloudStack, use the API for operation and integration, access the usage data and use CloudStack specific tools to ease development, testing and integration.

The CloudStack API

Getting Started

To get started using the CloudStack API, you should have the following:

  • URL of the CloudStack server you wish to integrate with.

  • Both the API Key and Secret Key for an Account. This should have been generated by the administrator of the cloud Instance and given to you.

  • Familiarity with HTTP GET/POST and query strings.

  • Knowledge of either XML or JSON.

  • Knowledge of a programming language that can generate HTTP requests; for example, Java or PHP.

Roles

The CloudStack API supports three access roles:

  1. Root Admin. Access to all features of the cloud, including both virtual and physical resource management.

  2. Domain Admin. Access to only the virtual resources of the clouds that belong to the administrator’s domain.

  3. User. Access to only the features that allow management of the User’s Instances, storage, and Network.

API Reference Documentation

You can find all the API reference documentation at the below site:

https://cloudstack.apache.org/api.html

Making API Requests

All CloudStack API requests are submitted in the form of a HTTP GET/POST with an associated command and any parameters. A request is composed of the following whether in HTTP or HTTPS:

  • CloudStack API URL: This is the web services API entry point(for example, http://www.example.com:8080/client/api)

  • Command: The web services command you wish to execute, such as start an Instance or create a disk volume

  • Parameters: Any additional required or optional parameters for the command

A sample API GET request looks like the following:

http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Or in a more readable format:

1. http://localhost:8080/client/api
2. ?command=deployVirtualMachine
3. &serviceOfferingId=1
4. &diskOfferingId=1
5. &templateId=2
6. &zoneId=4
7. &apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
8. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

The first line is the CloudStack API URL. This is the Cloud Instance you wish to interact with.

The second line refers to the command you wish to execute. In our example, we are attempting to deploy a fresh new Instance. It is preceded by a (?) to separate itself from the CloudStack API URL.

Lines 3-6 are the parameters for this given command. To see the command and its request parameters, please refer to the appropriate section in the CloudStack API documentation. Each parameter field-value pair (field=value) is preceded by an ampersand character (&).

Line 7 is the User API Key that uniquely identifies the Account. See Signing API Requests on page 7.

Line 8 is the signature hash created to authenticate the User Account executing the API command.

Signing API Requests

Whether you access the CloudStack API with HTTP or HTTPS, it must still be signed so that CloudStack can verify the caller has been authenticated and authorized to execute the command. Make sure that you have both the API Key and Secret Key provided by the CloudStack administrator for your Account before proceeding with the signing process.

To show how to sign a request, we will re-use the previous example.

http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Breaking this down, we have several distinct parts to this URL.

  • Base URL: This is the base URL to the CloudStack Management Server.

    http://localhost:8080
    
  • API Path: This is the path to the API Servlet that processes the incoming requests.

    /client/api?
    
  • Command String: This part of the query string comprises of the command, its parameters, and the API Key that identifies the Account.

    Note

    As with all query string parameters of field-value pairs, the “field” component is case insensitive while all “value” values are case sensitive.

  • Signature: This is the signature of the command string that is generated using a combination of the User’s Secret Key and the HMAC SHA-1 hashing algorithm.

    &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
    

Every API request has the format Base URL+API Path+Command String+Signature.

To generate the signature.

  1. For each field-value pair (as separated by a ‘&’) in the Command String, URL encode each value so that it can be safely sent via HTTP GET.

    Note

    Make sure all spaces are encoded as “%20” rather than “+”.

  2. Lower case the entire Command String and sort it alphabetically via the field for each field-value pair. The result of this step would look like the following.

    apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4
    
  3. Take the sorted Command String and run it through the HMAC SHA-1 hashing algorithm (most programming languages offer a utility method to do this) with the User’s Secret Key. Base64 encode the resulting byte array in UTF-8 so that it can be safely transmitted via HTTP. The final string produced after Base64 encoding should be “Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D”.

    By reconstructing the final URL in the format Base URL+API Path+Command String+Signature, the final URL should look like:

    http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
    

How to sign an API call with Python

To illustrate the procedure used to sign API calls we present a step by step interactive session using Python.

First import the required modules:

$python
Python 2.7.3 (default, Nov 17 2012, 19:54:34)
[GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import urllib2
>>> import urllib
>>> import hashlib
>>> import hmac
>>> import base64

Define the endpoint of the Cloud, the command that you want to execute and the keys of the User.

>>> baseurl='http://localhost:8080/client/api?'
>>> request={}
>>> request['command']='listUsers'
>>> request['response']='json'
>>> request['apikey']='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
>>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'

Build the request string:

>>> request_str='&'.join(['='.join([k,urllib.quote_plus(request[k])]) for k in request.keys()])
>>> request_str
'apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json'

Compute the signature with hmac, do a 64 bit encoding and a url encoding:

>>> sig_str='&'.join(['='.join([k.lower(),urllib.quote_plus(request[k]).lower().replace('+','%20')])for k in sorted(request.iterkeys())])
>>> sig_str 'apikey=plgwjfzk4gys3momtvmjuvg-x-jlwlnfauj9gabbbf9edm-kaymmailqzzq1elzlyq_u38zcm0bewzgudp66mg&command=listusers&response=json'
>>> sig=hmac.new(secretkey,sig_str,hashlib.sha1)
>>> sig
<hmac.HMAC instance at 0x10d91d680>
>>> sig=hmac.new(secretkey,sig_str,hashlib.sha1).digest()
>>> sig
'M:]x0exafxfbx8fxf2yxf1px91x1ex89x8axa1x05xc4Axdb'
>>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest())
>>> sig
'TTpdDq/7j/J58XCRHomKoQXEQds=n'
>>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip()
>>> sig
'TTpdDq/7j/J58XCRHomKoQXEQds='
>>> sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip())

Finally, build the entire string and do an http GET:

>>> req=baseurl+request_str+'&signature='+sig
>>> req
'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
>>> res=urllib2.urlopen(req)
>>> res.read()
'{ "listusersresponse" : { "count":3 ,"user" : [  {"id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a","username":"admin","firstname":"admin","lastname":"cloud","created":"2012-07-05T12:18:27-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg","secretkey":"VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"1fea6418-5576-4989-a21e-4790787bbee3","username":"runseb","firstname":"foobar","lastname":"goa","email":"joe@smith.com","created":"2013-04-10T16:52:06-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"Xhsb3MewjJQaXXMszRcLvQI9_NPy_UcbDj1QXikkVbDC9MDSPwWdtZ1bUY1H7JBEYTtDDLY3yuchCeW778GkBA","secretkey":"gIsgmi8C5YwxMHjX5o51pSe0kqs6JnKriw0jJBLceY5bgnfzKjL4aM6ctJX-i1ddQIHJLbLJDK9MRzsKk6xZ_w","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"52f65396-183c-4473-883f-a37e7bb93967","username":"toto","firstname":"john","lastname":"smith","email":"john@smith.com","created":"2013-04-23T04:27:22-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"THaA6fFWS_OmvU8od201omxFC8yKNL_Hc5ZCS77LFCJsRzSx48JyZucbUul6XYbEg-ZyXMl_wuEpECzK-wKnow","secretkey":"O5ywpqJorAsEBKR_5jEvrtGHfWL1Y_j1E4Z_iCr8OKCYcsPIOdVcfzjJQ8YqK0a5EzSpoRrjOFiLsG0hQrYnDA","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"} ] } }'

Enabling API Call Expiration

You can set an expiry timestamp on API calls to prevent replay attacks over non-secure channels, such as HTTP. The server tracks the expiry timestamp you have specified and rejects all the subsequent API requests that come in after this validity period.

To enable this feature, add the following parameters to the API request:

  • signatureVersion=3: If the signatureVersion parameter is missing or is not equal to 3, the expires parameter is ignored in the API request.

  • expires=YYYY-MM-DDThh:mm:ssZ: Specifies the date and time at which the signature included in the request is expired. The timestamp is expressed in the YYYY-MM-DDThh:mm:ssZ format, as specified in the ISO 8601 standard.

For example:

expires=2011-10-10T12:00:00+0530

A sample API request with expiration is given below:

http://<IPAddress>:8080/client/api?command=listZones&signatureVersion=3&expires=2011-10-10T12:00:00+0530&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Limiting the Rate of API Requests

You can limit the rate at which API requests can be placed for each account. This is useful to avoid malicious attacks on the Management Server, prevent performance degradation, and provide fairness to all accounts.

If the number of API calls exceeds the threshold, an error message is returned for any additional API calls. The caller will have to retry these API calls at another time.

Configuring the API Request Rate

To control the API request rate, use the following global configuration settings:

  • api.throttling.enabled - Enable/Disable API throttling. By default, this setting is false, so API throttling is not enabled.

  • api.throttling.interval (in seconds) - Time interval during which the number of API requests is to be counted. When the interval has passed, the API count is reset to 0.

  • api.throttling.max - Maximum number of APIs that can be placed within the api.throttling.interval period.

  • api.throttling.cachesize - Cache size for storing API counters. Use a value higher than the total number of accounts managed by the cloud. One cache entry is needed for each account, to store the running API total for that account.

Limitations on API Throttling

The following limitations exist in the current implementation of this feature.

Note

Even with these limitations, CloudStack is still able to effectively use API throttling to avoid malicious attacks causing denial of service.

  • In a deployment with multiple Management Servers, the cache is not synchronized across them. In this case, CloudStack might not be able to ensure that only the exact desired number of API requests are allowed. In the worst case, the number of API calls that might be allowed is (number of Management Servers) * (api.throttling.max).

  • The API commands resetApiLimit and getApiLimit are limited to the Management Server where the API is invoked.

API Responses

Response Formats: XML and JSON

CloudStack supports two formats as the response to an API call. The default response is XML. If you would like the response to be in JSON, add &response=json to the Command String.

The two response formats differ in how they handle blank fields. In JSON, if there is no value for a response field, it will not appear in the response. If all the fields were empty, there might be no response at all. In XML, even if there is no value to be returned, an empty field will be returned as a placeholder XML element.

Sample XML Response:

<listipaddressesresponse>
   <allocatedipaddress>
   <ipaddress>192.168.10.141</ipaddress>
   <allocated>2009-09-18T13:16:10-0700</allocated>
   <zoneid>4</zoneid>
      <zonename>WC</zonename>
      <issourcenat>true</issourcenat>
   </allocatedipaddress>
</listipaddressesresponse>

Sample JSON Response:

{ "listipaddressesresponse" :
  { "allocatedipaddress" :
    [
      {
        "ipaddress" : "192.168.10.141",
        "allocated" : "2009-09-18T13:16:10-0700",
        "zoneid" : "4",
        "zonename" : "WC",
        "issourcenat" : "true"
      }
    ]
  }
}

Maximum Result Pages Returned

For each cloud, there is a default upper limit on the number of results that any API command will return in a single page. This is to help prevent overloading the cloud servers and prevent DOS attacks. For example, if the page size limit is 500 and a command returns 10,000 results, the command will return 20 pages.

The default page size limit can be different for each cloud. It is set in the global configuration parameter default.page.size. If your cloud has many users with lots of Instances, you might need to increase the value of this parameter. At the same time, be careful not to set it so high that your site can be taken down by an enormous return from an API call. For more information about how to set global configuration parameters, see “Describe Your Deployment” in the Installation Guide.

To decrease the page size limit for an individual API command, override the global setting with the page and pagesize parameters, which are available in any list* command (listCapabilities, listDiskOfferings, etc.).

  • Both parameters must be specified together.

  • The value of the pagesize parameter must be smaller than the value of default.page.size. That is, you can not increase the number of possible items in a result page, only decrease it.

For syntax information on the list* commands, see the API Reference.

Error Handling

If an error occurs while processing an API request, the appropriate response in the format specified is returned. Each error response consists of an error code and an error text describing what possibly can go wrong. Below is a list of possible error codes:

You can now find the CloudStack-specific error code in the exception response for each type of exception. The following list of error codes is added to the new class named CSExceptionErrorCode.

4250 : “com.cloud.utils.exception.CloudRuntimeException”

4255 : “com.cloud.utils.exception.ExceptionUtil”

4260 : “com.cloud.utils.exception.ExecutionException”

4265 : “com.cloud.utils.exception.HypervisorVersionChangedException”

4270 : “com.cloud.utils.exception.RuntimeCloudException”

4275 : “com.cloud.exception.CloudException”

4280 : “com.cloud.exception.AccountLimitException”

4285 : “com.cloud.exception.AgentUnavailableException”

4290 : “com.cloud.exception.CloudAuthenticationException”

4295 : “com.cloud.exception.CloudExecutionException”

4300 : “com.cloud.exception.ConcurrentOperationException”

4305 : “com.cloud.exception.ConflictingNetworkSettingsException”

4310 : “com.cloud.exception.DiscoveredWithErrorException”

4315 : “com.cloud.exception.HAStateException”

4320 : “com.cloud.exception.InsufficientAddressCapacityException”

4325 : “com.cloud.exception.InsufficientCapacityException”

4330 : “com.cloud.exception.InsufficientNetworkCapacityException”

4335 : “com.cloud.exception.InsufficientServerCapacityException”

4340 : “com.cloud.exception.InsufficientStorageCapacityException”

4345 : “com.cloud.exception.InternalErrorException”

4350 : “com.cloud.exception.InvalidParameterValueException”

4355 : “com.cloud.exception.ManagementServerException”

4360 : “com.cloud.exception.NetworkRuleConflictException”

4365 : “com.cloud.exception.PermissionDeniedException”

4370 : “com.cloud.exception.ResourceAllocationException”

4375 : “com.cloud.exception.ResourceInUseException”

4380 : “com.cloud.exception.ResourceUnavailableException”

4385 : “com.cloud.exception.StorageUnavailableException”

4390 : “com.cloud.exception.UnsupportedServiceException”

4395 : “com.cloud.exception.VirtualMachineMigrationException”

4400 : “com.cloud.exception.AccountLimitException”

4405 : “com.cloud.exception.AgentUnavailableException”

4410 : “com.cloud.exception.CloudAuthenticationException”

4415 : “com.cloud.exception.CloudException”

4420 : “com.cloud.exception.CloudExecutionException”

4425 : “com.cloud.exception.ConcurrentOperationException”

4430 : “com.cloud.exception.ConflictingNetworkSettingsException”

4435 : “com.cloud.exception.ConnectionException”

4440 : “com.cloud.exception.DiscoveredWithErrorException”

4445 : “com.cloud.exception.DiscoveryException”

4450 : “com.cloud.exception.HAStateException”

4455 : “com.cloud.exception.InsufficientAddressCapacityException”

4460 : “com.cloud.exception.InsufficientCapacityException”

4465 : “com.cloud.exception.InsufficientNetworkCapacityException”

4470 : “com.cloud.exception.InsufficientServerCapacityException”

4475 : “com.cloud.exception.InsufficientStorageCapacityException”

4480 : “com.cloud.exception.InsufficientVirtualNetworkCapcityException”

4485 : “com.cloud.exception.InternalErrorException”

4490 : “com.cloud.exception.InvalidParameterValueException”

4495 : “com.cloud.exception.ManagementServerException”

4500 : “com.cloud.exception.NetworkRuleConflictException”

4505 : “com.cloud.exception.PermissionDeniedException”

4510 : “com.cloud.exception.ResourceAllocationException”

4515 : “com.cloud.exception.ResourceInUseException”

4520 : “com.cloud.exception.ResourceUnavailableException”

4525 : “com.cloud.exception.StorageUnavailableException”

4530 : “com.cloud.exception.UnsupportedServiceException”

4535 : “com.cloud.exception.VirtualMachineMigrationException”

9999 : “org.apache.cloudstack.api.ServerApiException”

An HTTP error code of 401 is always returned if API request was rejected due to bad signatures, missing API Keys, or the user simply did not have the permissions to execute the command.

Asynchronous Commands

Asynchronous commands were introduced in CloudStack 2.x. Commands are designated as asynchronous when they can potentially take a long period of time to complete such as creating a Snapshot or disk volume. They differ from synchronous commands by the following:

  • They are identified in the API Reference by an (A).

  • They will immediately return a job ID to refer to the job that will be responsible in processing the command.

  • If executed as a “create” resource command, it will return the resource ID as well as the job ID.

    You can periodically check the status of the job by making a simple API call to the command, queryAsyncJobResult and passing in the job ID.

Job Status

The key to using an asynchronous command is the job ID that is returned immediately once the command has been executed. With the job ID, you can periodically check the job status by making calls to queryAsyncJobResult command. The command will return three possible job status integer values:

  • 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 “jobresultcode” tag for failure reason code and “jobresult” for the failure reason.

Example

The following shows an example of using an asynchronous command. Assume the API command:

command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1

CloudStack will immediately return a job ID and any other additional data.

<deployvirtualmachineresponse>
   <jobid>1</jobid>
   <id>100</id>
</deployvirtualmachineresponse>

Using the job ID, you can periodically poll for the results by using the queryAsyncJobResult command.

command=queryAsyncJobResult&jobId=1

Three possible results could come from this query.

Job is still pending:

<queryasyncjobresult>
   <jobid>1</jobid>
   <jobstatus>0</jobstatus>
   <jobprocstatus>1</jobprocstatus>
</queryasyncjobresult>

Job has succeeded:

<queryasyncjobresultresponse cloud-stack-version="3.0.1.6">
   <jobid>1</jobid>
   <jobstatus>1</jobstatus>
   <jobprocstatus>0</jobprocstatus>
   <jobresultcode>0</jobresultcode>
   <jobresulttype>object</jobresulttype>
   <jobresult>
      <virtualmachine>
         <id>450</id>
         <name>i-2-450-VM</name>
         <displayname>i-2-450-VM</displayname>
         <account>admin</account>
         <domainid>1</domainid>
         <domain>ROOT</domain>
         <created>2011-03-10T18:20:25-0800</created>
         <state>Running</state>
         <haenable>false</haenable>
         <zoneid>1</zoneid>
         <zonename>San Jose 1</zonename>
         <hostid>2</hostid>
         <hostname>905-13.sjc.lab.vmops.com</hostname>
         <templateid>1</templateid>
         <templatename>CentOS 5.3 64bit LAMP</templatename>
         <templatedisplaytext>CentOS 5.3 64bit LAMP</templatedisplaytext>
         <passwordenabled>false</passwordenabled>
         <serviceofferingid>1</serviceofferingid>
         <serviceofferingname>Small Instance</serviceofferingname>
         <cpunumber>1</cpunumber>
         <cpuspeed>500</cpuspeed>
         <memory>512</memory>
         <guestosid>12</guestosid>
         <rootdeviceid>0</rootdeviceid>
         <rootdevicetype>NetworkFilesystem</rootdevicetype>
         <nic>
            <id>561</id>
            <networkid>205</networkid>
            <netmask>255.255.255.0</netmask>
            <gateway>10.1.1.1</gateway>
            <ipaddress>10.1.1.225</ipaddress>
            <isolationuri>vlan://295</isolationuri>
            <broadcasturi>vlan://295</broadcasturi>
            <traffictype>Guest</traffictype>
            <type>Virtual</type>
            <isdefault>true</isdefault>
         </nic>
         <hypervisor>XenServer</hypervisor>
      </virtualmachine>
   </jobresult>
</queryasyncjobresultresponse>

Job has failed:

<queryasyncjobresult>
   <jobid>1</jobid>
   <jobstatus>2</jobstatus>
   <jobprocstatus>0</jobprocstatus>
   <jobresultcode>551</jobresultcode>
   <jobresulttype>text</jobresulttype>
   <jobresult>Unable to deploy virtual machine id = 100 due to not enough capacity</jobresult>
</queryasyncjobresult>

Event Types

Types

Events

VM

VM.CREATE

VM.DESTROY

VM.START

VM.STOP

VM.REBOOT

VM.UPDATE

VM.UPGRADE

VM.DYNAMIC.SCALE

VM.RESETPASSWORD

VM.RESETSSHKEY

VM.MIGRATE

VM.MOVE

VM.RESTORE

Domain Router

ROUTER.CREATE

ROUTER.DESTROY

ROUTER.START

ROUTER.STOP

ROUTER.REBOOT

ROUTER.HA

ROUTER.UPGRADE

Console proxy

PROXY.CREATE

PROXY.DESTROY

PROXY.START

PROXY.STOP

PROXY.REBOOT

PROXY.HA

VNC Console Events

VNC.CONNECT

VNC.DISCONNECT

Network Events

NET.IPASSIGN

NET.IPRELEASE

PORTABLE.IPASSIGN

PORTABLE.IPRELEASE

NET.RULEADD

NET.RULEDELETE

NET.RULEMODIFY

NETWORK.CREATE

NETWORK.DELETE

NETWORK.UPDATE

FIREWALL.OPEN

FIREWALL.CLOSE

NIC Events

NIC.CREATE

NIC.DELETE

NIC.UPDATE

NIC.DETAIL.ADD

NIC.DETAIL.UPDATE

NIC.DETAIL.REMOVE

Load Balancers

LB.ASSIGN.TO.RULE

LB.REMOVE.FROM.RULE

LB.CREATE

LB.DELETE

LB.STICKINESSPOLICY.CREATE

LB.STICKINESSPOLICY.DELETE

LB.HEALTHCHECKPOLICY.CREATE

LB.HEALTHCHECKPOLICY.DELETE

LB.UPDATE

Global Load Balancer rules

GLOBAL.LB.ASSIGN

GLOBAL.LB.REMOVE

GLOBAL.LB.CREATE

GLOBAL.LB.DELETE

GLOBAL.LB.UPDATE

Account events

ACCOUNT.ENABLE

ACCOUNT.DISABLE

ACCOUNT.CREATE

ACCOUNT.DELETE

ACCOUNT.UPDATE

ACCOUNT.MARK.DEFAULT.ZONE

UserVO Events

USER.LOGIN

USER.LOGOUT

USER.CREATE

USER.DELETE

USER.DISABLE

USER.UPDATE

USER.ENABLE

USER.LOCK

Registering SSH keypair events

REGISTER.SSH.KEYPAIR

Register for user API and secret keys

REGISTER.USER.KEY

Template Events

TEMPLATE.CREATE

TEMPLATE.DELETE

TEMPLATE.UPDATE

TEMPLATE.DOWNLOAD.START

TEMPLATE.DOWNLOAD.SUCCESS

TEMPLATE.DOWNLOAD.FAILED

TEMPLATE.COPY

TEMPLATE.EXTRACT

TEMPLATE.UPLOAD

TEMPLATE.CLEANUP

Volume Events

VOLUME.CREATE

VOLUME.DELETE

VOLUME.ATTACH

VOLUME.DETACH

VOLUME.EXTRACT

VOLUME.UPLOAD

VOLUME.MIGRATE

VOLUME.RESIZE

VOLUME.DETAIL.UPDATE

VOLUME.DETAIL.ADD

VOLUME.DETAIL.REMOVE

Domains

DOMAIN.CREATE

DOMAIN.DELETE

DOMAIN.UPDATE

Snapshots

SNAPSHOT.CREATE

SNAPSHOT.DELETE

SNAPSHOTPOLICY.CREATE

SNAPSHOTPOLICY.UPDATE

SNAPSHOTPOLICY.DELETE

ISO

ISO.CREATE

ISO.DELETE

ISO.COPY

ISO.ATTACH

ISO.DETACH

ISO.EXTRACT

ISO.UPLOAD

SSVM

SSVM.CREATE

SSVM.DESTROY

SSVM.START

SSVM.STOP

SSVM.REBOOT

SSVM.HA

Service Offerings

SERVICE.OFFERING.CREATE

SERVICE.OFFERING.EDIT

SERVICE.OFFERING.DELETE

Disk Offerings

DISK.OFFERING.CREATE

DISK.OFFERING.EDIT

DISK.OFFERING.DELETE

Network offerings

NETWORK.OFFERING.CREATE

NETWORK.OFFERING.ASSIGN

NETWORK.OFFERING.EDIT

NETWORK.OFFERING.REMOVE

NETWORK.OFFERING.DELETE

Pods

POD.CREATE

POD.EDIT

POD.DELETE

Zones

ZONE.CREATE

ZONE.EDIT

ZONE.DELETE

VLANs/IP ranges

VLAN.IP.RANGE.CREATE

VLAN.IP.RANGE.DELETE

VLAN.IP.RANGE.DEDICATE

VLAN.IP.RANGE.RELEASE

STORAGE.IP.RANGE.CREATE

STORAGE.IP.RANGE.DELETE

STORAGE.IP.RANGE.UPDATE

Configuration Table

CONFIGURATION.VALUE.EDIT

Security Groups

SG.AUTH.INGRESS

SG.REVOKE.INGRESS

SG.AUTH.EGRESS

SG.REVOKE.EGRESS

SG.CREATE

SG.DELETE

SG.ASSIGN

SG.REMOVE

Host

HOST.RECONNECT

Maintenance

MAINT.CANCEL

MAINT.CANCEL.PS

MAINT.PREPARE

MAINT.PREPARE.PS

VPN

VPN.REMOTE.ACCESS.CREATE

VPN.REMOTE.ACCESS.DESTROY

VPN.USER.ADD

VPN.USER.REMOVE

VPN.S2S.VPN.GATEWAY.CREATE

VPN.S2S.VPN.GATEWAY.DELETE

VPN.S2S.CUSTOMER.GATEWAY.CREATE

VPN.S2S.CUSTOMER.GATEWAY.DELETE

VPN.S2S.CUSTOMER.GATEWAY.UPDATE

VPN.S2S.CONNECTION.CREATE

VPN.S2S.CONNECTION.DELETE

VPN.S2S.CONNECTION.RESET

Network

NETWORK.RESTART

Custom certificates

UPLOAD.CUSTOM.CERTIFICATE

OneToOnenat

STATICNAT.ENABLE

STATICNAT.DISABLE

ZONE.VLAN.ASSIGN

ZONE.VLAN.RELEASE

Projects

PROJECT.CREATE

PROJECT.UPDATE

PROJECT.DELETE

PROJECT.ACTIVATE

PROJECT.SUSPEND

PROJECT.ACCOUNT.ADD

PROJECT.INVITATION.UPDATE

PROJECT.INVITATION.REMOVE

PROJECT.ACCOUNT.REMOVE

Network as a Service

NETWORK.ELEMENT.CONFIGURE

Physical Network Events

PHYSICAL.NETWORK.CREATE

PHYSICAL.NETWORK.DELETE

PHYSICAL.NETWORK.UPDATE

Physical Network Service Provider Events

SERVICE.PROVIDER.CREATE

SERVICE.PROVIDER.DELETE

SERVICE.PROVIDER.UPDATE

Physical Network Traffic Type Events

TRAFFIC.TYPE.CREATE

TRAFFIC.TYPE.DELETE

TRAFFIC.TYPE.UPDATE

External Network device events

PHYSICAL.LOADBALANCER.ADD

PHYSICAL.LOADBALANCER.DELETE

PHYSICAL.LOADBALANCER.CONFIGURE

External switch management device events

For example: Cisco Nexus 1000v Virtual Supervisor Module.

SWITCH.MGMT.ADD

SWITCH.MGMT.DELETE

SWITCH.MGMT.CONFIGURE

SWITCH.MGMT.ENABLE

SWITCH.MGMT.DISABLE

PHYSICAL.FIREWALL.ADD

PHYSICAL.FIREWALL.DELETE

PHYSICAL.FIREWALL.CONFIGURE

VPC

VPC.CREATE

VPC.UPDATE

VPC.DELETE

VPC.RESTART

Network ACL

NETWORK.ACL.CREATE

NETWORK.ACL.DELETE

NETWORK.ACL.REPLACE

NETWORK.ACL.ITEM.CREATE

NETWORK.ACL.ITEM.UPDATE

NETWORK.ACL.ITEM.DELETE

VPC offerings

VPC.OFFERING.CREATE

VPC.OFFERING.UPDATE

VPC.OFFERING.DELETE

Private gateway

PRIVATE.GATEWAY.CREATE

PRIVATE.GATEWAY.DELETE

Static routes

STATIC.ROUTE.CREATE

STATIC.ROUTE.DELETE

Tag-related events

CREATE_TAGS

DELETE_TAGS

Meta data-related events

CREATE_RESOURCE_DETAILS

DELETE_RESOURCE_DETAILS

VM Snapshot events

VMSNAPSHOT.CREATE

VMSNAPSHOT.DELETE

VMSNAPSHOT.REVERTTO

External Network device events

PHYSICAL.NVPCONTROLLER.ADD

PHYSICAL.NVPCONTROLLER.DELETE

PHYSICAL.NVPCONTROLLER.CONFIGURE

AutoScale

COUNTER.CREATE

COUNTER.DELETE

CONDITION.CREATE

CONDITION.DELETE

AUTOSCALEPOLICY.CREATE

AUTOSCALEPOLICY.UPDATE

AUTOSCALEPOLICY.DELETE

AUTOSCALEVMPROFILE.CREATE

AUTOSCALEVMPROFILE.DELETE

AUTOSCALEVMPROFILE.UPDATE

AUTOSCALEVMGROUP.CREATE

AUTOSCALEVMGROUP.DELETE

AUTOSCALEVMGROUP.UPDATE

AUTOSCALEVMGROUP.ENABLE

AUTOSCALEVMGROUP.DISABLE

PHYSICAL.DHCP.ADD

PHYSICAL.DHCP.DELETE

PHYSICAL.PXE.ADD

PHYSICAL.PXE.DELETE

AG.CREATE

AG.DELETE

AG.ASSIGN

AG.REMOVE

VM.AG.UPDATE

INTERNALLBVM.START

INTERNALLBVM.STOP

HOST.RESERVATION.RELEASE

Dedicated guest vlan range

GUESTVLANRANGE.DEDICATE

GUESTVLANRANGE.RELEASE

PORTABLE.IP.RANGE.CREATE

PORTABLE.IP.RANGE.DELETE

PORTABLE.IP.TRANSFER

Dedicated Resources

DEDICATE.RESOURCE

DEDICATE.RESOURCE.RELEASE

VM.RESERVATION.CLEANUP

UCS.ASSOCIATEPROFILE

UCS.DISASSOCIATEPROFILE

Time Zones

The following time zone identifiers are accepted by CloudStack. There are several places that have a time zone as a required or optional parameter. These include scheduling recurring Snapshots, creating a user, and specifying the usage time zone in the Configuration table.

Etc/GMT+12

Etc/GMT+11

Pacific/Samoa

Pacific/Honolulu

US/Alaska

America/Los_Angeles

Mexico/BajaNorte

US/Arizona

US/Mountain

America/Chihuahua

America/Chicago

America/Costa_Rica

America/Mexico_City

Canada/Saskatchewan

America/Bogota

America/New_York

America/Caracas

America/Asuncion

America/Cuiaba

America/Halifax

America/La_Paz

America/Santiago

America/St_Johns

America/Araguaina

America/Argentina/Buenos_Aires

America/Cayenne

America/Godthab

America/Montevideo

Etc/GMT+2

Atlantic/Azores

Atlantic/Cape_Verde

Africa/Casablanca

Etc/UTC

Atlantic/Reykjavik

Europe/London

CET

Europe/Bucharest

Africa/Johannesburg

Asia/Beirut

Africa/Cairo

Asia/Jerusalem

Europe/Minsk

Europe/Moscow

Africa/Nairobi

Asia/Karachi

Asia/Kolkata

Asia/Bangkok

Asia/Shanghai

Asia/Kuala_Lumpur

Australia/Perth

Asia/Taipei

Asia/Tokyo

Asia/Seoul

Australia/Adelaide

Australia/Darwin

Australia/Brisbane

Australia/Canberra

Pacific/Guam

Pacific/Auckland