You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by se...@apache.org on 2014/02/24 18:31:01 UTC
[3/3] git commit: add usage guide, ipv6 and api
add usage guide, ipv6 and api
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/8f938c0d
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/8f938c0d
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/8f938c0d
Branch: refs/heads/master
Commit: 8f938c0d3eb584aa735b12fdc895dc5b5562c898
Parents: f4dcc1a
Author: Sebastien Goasguen <ru...@gmail.com>
Authored: Mon Feb 24 12:30:45 2014 -0500
Committer: Sebastien Goasguen <ru...@gmail.com>
Committed: Mon Feb 24 12:30:45 2014 -0500
----------------------------------------------------------------------
rtd/source/dev.rst | 1486 +++++++++++++++++++++++++++++++++++
rtd/source/index.rst | 3 +
rtd/source/networking/ipv6.rst | 224 ++++++
rtd/source/usage.rst | 693 ++++++++++++++++
4 files changed, 2406 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/8f938c0d/rtd/source/dev.rst
----------------------------------------------------------------------
diff --git a/rtd/source/dev.rst b/rtd/source/dev.rst
new file mode 100644
index 0000000..42ef179
--- /dev/null
+++ b/rtd/source/dev.rst
@@ -0,0 +1,1486 @@
+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:
+
+#.
+
+ Root Admin. Access to all features of the cloud, including both
+ virtual and physical resource management.
+
+#.
+
+ Domain Admin. Access to only the virtual resources of the clouds that
+ belong to the administrator’s domain.
+
+#.
+
+ User. Access to only the features that allow management of the user’s
+ virtual instances, storage, and network.
+
+API Reference Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can find all the API reference documentation at the below site:
+
+`http://cloudstack.apache.org/docs/api/ <http://cloudstack.apache.org/docs/api/>`__
+
+
+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.cloud.com:8080/client/api)
+
+-
+
+ Command: The web services command you wish to execute, such as start
+ a virtual machine 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:
+
+.. sourcecode:: bash
+
+ 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 virtual machine. 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://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.
+
+ .. sourcecode:: bash
+
+ http://localhost:8080
+
+-
+
+ API Path: This is the path to the API Servlet that processes the
+ incoming requests.
+
+ .. sourcecode:: bash
+
+ /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.
+
+ .. sourcecode: bash
+
+command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
+
+-
+
+ 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.
+
+ .. sourcecode:: bash
+
+ &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+
+Every API request has the format Base URL+API Path+Command
+String+Signature.
+
+To generate the signature.
+
+#.
+
+ 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 "+".
+
+#.
+
+ 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.
+
+ .. sourcecode:: bash
+ apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4
+
+#.
+
+ 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:
+
+.. sourcecode:: bash
+
+ $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.
+
+.. sourcecode:: bash
+
+ >>> 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:
+
+.. sourcecode:: bash
+
+ >>> 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:
+
+.. sourcecode:: bash
+
+ >>> 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:]\x0e\xaf\xfb\x8f\xf2y\xf1p\x91\x1e\x89\x8a\xa1\x05\xc4A\xdb'
+ >>> 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:
+
+.. sourcecode:: bash
+
+ >>> 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":"gIsgmi8C5YwxMHjX5o51pSe0kqs6JnKriw0jJBLc
eY5bgnfzKjL4aM6ctJX-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:
+
+.. sourcecode:: bash
+
+ expires=2011-10-10T12:00:00+0530
+
+A sample API request with expiration is given below:
+
+.. sourcecode:: bash
+
+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:
+
+.. sourcecode:: bash
+
+ <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:
+
+.. sourcecode:: bash
+
+ { "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 VMs, 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:
+
+.. sourcecode:: bash
+
+ command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1
+
+CloudStack will immediately return a job ID and any other additional
+data.
+
+.. sourcecode:: bash
+
+ <deployvirtualmachineresponse>
+ <jobid>1</jobid>
+ <id>100</id>
+ </deployvirtualmachineresponse>
+
+Using the job ID, you can periodically poll for the results by using the
+queryAsyncJobResult command.
+
+.. sourcecode:: bash
+
+ command=queryAsyncJobResult&jobId=1
+
+Three possible results could come from this query.
+
+Job is still pending:
+
+.. sourcecode:: bash
+
+ <queryasyncjobresult>
+ <jobid>1</jobid>
+ <jobstatus>0</jobstatus>
+ <jobprocstatus>1</jobprocstatus>
+ </queryasyncjobresult>
+
+Job has succeeded:
+
+.. sourcecode:: bash
+
+ <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:
+
+.. sourcecode:: bash
+
+ <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>
+
+
+Alerts
+------
+
+The following is the list of alert type numbers. The current alerts can
+be found by calling listAlerts.
+
+::
+
+ MEMORY = 0 // Available Memory below configured threshold
+
+::
+
+ CPU = 1 // Unallocated CPU below configured threshold
+
+::
+
+ STORAGE =2 // Available Storage below configured threshold
+
+::
+
+ STORAGE_ALLOCATED = 3 // Remaining unallocated Storage is below configured threshold
+
+::
+
+ PUBLIC_IP = 4 // Number of unallocated virtual network public IPs is below configured threshold
+
+::
+
+ PRIVATE_IP = 5 // Number of unallocated private IPs is below configured threshold
+
+::
+
+ SECONDARY_STORAGE = 6 // Available Secondary Storage in availability zone is below configured threshold
+
+::
+
+ HOST = 7 // Host related alerts like host disconnected
+
+::
+
+ USERVM = 8 // User VM stopped unexpectedly
+
+::
+
+ DOMAIN_ROUTER = 9 // Domain Router VM stopped unexpectedly
+
+::
+
+ CONSOLE_PROXY = 10 // Console Proxy VM stopped unexpectedly
+
+::
+
+ ROUTING = 11 // Lost connection to default route (to the gateway)
+
+::
+
+ STORAGE_MISC = 12 // Storage issue in system VMs
+
+::
+
+ USAGE_SERVER = 13 // No usage server process running
+
+::
+
+ MANAGMENT_NODE = 14 // Management network CIDR is not configured originally
+
+::
+
+ DOMAIN_ROUTER_MIGRATE = 15 // Domain Router VM Migration was unsuccessful
+
+::
+
+ CONSOLE_PROXY_MIGRATE = 16 // Console Proxy VM Migration was unsuccessful
+
+::
+
+ USERVM_MIGRATE = 17 // User VM Migration was unsuccessful
+
+::
+
+ VLAN = 18 // Number of unallocated VLANs is below configured threshold in availability zone
+
+::
+
+ SSVM = 19 // SSVM stopped unexpectedly
+
+::
+
+ USAGE_SERVER_RESULT = 20 // Usage job failed
+
+::
+
+ STORAGE_DELETE = 21 // Failed to delete storage pool
+
+::
+
+ UPDATE_RESOURCE_COUNT = 22 // Failed to update the resource count
+
+::
+
+ USAGE_SANITY_RESULT = 23 // Usage Sanity Check failed
+
+::
+
+ DIRECT_ATTACHED_PUBLIC_IP = 24 // Number of unallocated shared network IPs is low in availability zone
+
+::
+
+ LOCAL_STORAGE = 25 // Remaining unallocated Local Storage is below configured threshold
+
+::
+
+ RESOURCE_LIMIT_EXCEEDED = 26 //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots only
+
+
+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 | VNC.CONNECT |
+| Events | |
+| | 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 | GLOBAL.LB.ASSIGN |
+| Balancer rules | |
+| | 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 | REGISTER.SSH.KEYPAIR |
+| keypair events | |
++-------------------+--------------------------------------------------------+
+| Register for user | REGISTER.USER.KEY |
+| API and secret | |
+| keys | |
++-------------------+--------------------------------------------------------+
+| 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 | CONFIGURATION.VALUE.EDIT |
+| Table | |
++-------------------+--------------------------------------------------------+
+| 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 | UPLOAD.CUSTOM.CERTIFICATE |
+| certificates | |
++-------------------+--------------------------------------------------------+
+| 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 | NETWORK.ELEMENT.CONFIGURE |
+| Service | |
++-------------------+--------------------------------------------------------+
+| Physical Network | PHYSICAL.NETWORK.CREATE |
+| Events | |
+| | PHYSICAL.NETWORK.DELETE |
+| | |
+| | PHYSICAL.NETWORK.UPDATE |
++-------------------+--------------------------------------------------------+
+| Physical Network | SERVICE.PROVIDER.CREATE |
+| Service Provider | |
+| Events | SERVICE.PROVIDER.DELETE |
+| | |
+| | SERVICE.PROVIDER.UPDATE |
++-------------------+--------------------------------------------------------+
+| Physical Network | TRAFFIC.TYPE.CREATE |
+| Traffic Type | |
+| Events | TRAFFIC.TYPE.DELETE |
+| | |
+| | TRAFFIC.TYPE.UPDATE |
++-------------------+--------------------------------------------------------+
+| External network | PHYSICAL.LOADBALANCER.ADD |
+| device events | |
+| | PHYSICAL.LOADBALANCER.DELETE |
+| | |
+| | PHYSICAL.LOADBALANCER.CONFIGURE |
++-------------------+--------------------------------------------------------+
+| External switch | SWITCH.MGMT.ADD |
+| management device | |
+| events | SWITCH.MGMT.DELETE |
+| | |
+| For example: | SWITCH.MGMT.CONFIGURE |
+| Cisco Nexus 1000v | |
+| Virtual | SWITCH.MGMT.ENABLE |
+| Supervisor | |
+| Module. | 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 | CREATE\_TAGS |
+| events | |
+| | DELETE\_TAGS |
++-------------------+--------------------------------------------------------+
+| Meta data-related | CREATE\_RESOURCE\_DETAILS |
+| events | |
+| | DELETE\_RESOURCE\_DETAILS |
++-------------------+--------------------------------------------------------+
+| VM snapshot | VMSNAPSHOT.CREATE |
+| events | |
+| | VMSNAPSHOT.DELETE |
+| | |
+| | VMSNAPSHOT.REVERTTO |
++-------------------+--------------------------------------------------------+
+| External network | PHYSICAL.NVPCONTROLLER.ADD |
+| device events | |
+| | 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 | GUESTVLANRANGE.DEDICATE |
+| vlan range | |
+| | GUESTVLANRANGE.RELEASE |
+| | |
+| | PORTABLE.IP.RANGE.CREATE |
+| | |
+| | PORTABLE.IP.RANGE.DELETE |
+| | |
+| | PORTABLE.IP.TRANSFER |
++-------------------+--------------------------------------------------------+
+| Dedicated | DEDICATE.RESOURCE |
+| Resources | |
+| | DEDICATE.RESOURCE.RELEASE |
+| | |
+| | VM.RESERVATION.CLEANUP |
+| | |
+| | UCS.ASSOCIATEPROFILE |
+| | |
+| | UCS.DISASSOCIATEPROFILE |
++-------------------+--------------------------------------------------------+
+
+Time Zones
+----------
+
+The following time zone identifiers are accepted by PRODUCT. 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 | |
++-----------------------------------+-----------------------+------------------------+
+
+
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/8f938c0d/rtd/source/index.rst
----------------------------------------------------------------------
diff --git a/rtd/source/index.rst b/rtd/source/index.rst
index fce9255..bb17f97 100644
--- a/rtd/source/index.rst
+++ b/rtd/source/index.rst
@@ -19,6 +19,7 @@ Networking Guides
networking/midonet
networking/vxlan.rst
networking/ovs-plugin
+ networking/ipv6
networking/autoscale_without_netscaler.rst
networking/troubleshoot_internet_traffic.rst
@@ -37,6 +38,8 @@ Developer's Guide
:maxdepth: 2
developer_guide
+ dev
+ usage
plugins
ansible
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/8f938c0d/rtd/source/networking/ipv6.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/ipv6.rst b/rtd/source/networking/ipv6.rst
new file mode 100644
index 0000000..2e5a1b6
--- /dev/null
+++ b/rtd/source/networking/ipv6.rst
@@ -0,0 +1,224 @@
+IPv6 Support in CloudStack
+===========================
+
+CloudStack supports Internet Protocol version 6 (IPv6), the recent
+version of the Internet Protocol (IP) that defines routing the network
+traffic. IPv6 uses a 128-bit address that exponentially expands the
+current address space that is available to the users. IPv6 addresses
+consist of eight groups of four hexadecimal digits separated by colons,
+for example, 5001:0dt8:83a3:1012:1000:8s2e:0870:7454. CloudStack
+supports IPv6 for public IPs in shared networks. With IPv6 support, VMs
+in shared networks can obtain both IPv4 and IPv6 addresses from the DHCP
+server. You can deploy VMs either in a IPv6 or IPv4 network, or in a
+dual network environment. If IPv6 network is used, the VM generates a
+link-local IPv6 address by itself, and receives a stateful IPv6 address
+from the DHCPv6 server.
+
+IPv6 is supported only on KVM and XenServer hypervisors. The IPv6
+support is only an experimental feature.
+
+Here's the sequence of events when IPv6 is used:
+
+#.
+
+ The administrator creates an IPv6 shared network in an advanced zone.
+
+#.
+
+ The user deploys a VM in an IPv6 shared network.
+
+#.
+
+ The user VM generates an IPv6 link local address by itself, and gets
+ an IPv6 global or site local address through DHCPv6.
+
+
+Prerequisites and Guidelines
+----------------------------
+
+Consider the following:
+
+-
+
+ CIDR size must be 64 for IPv6 networks.
+
+-
+
+ The DHCP client of the guest VMs should support generating DUID based
+ on Link-layer Address (DUID- LL). DUID-LL derives from the MAC
+ address of guest VMs, and therefore the user VM can be identified by
+ using DUID. See `Dynamic Host Configuration Protocol for
+ IPv6 <http://tools.ietf.org/html/rfc3315>`__\ for more information.
+
+-
+
+ The gateway of the guest network generates Router Advisement and
+ Response messages to Router Solicitation. The M (Managed Address
+ Configuration) flag of Router Advisement should enable stateful IP
+ address configuration. Set the M flag to where the end nodes receive
+ their IPv6 addresses from the DHCPv6 server as opposed to the router
+ or switch.
+
+ .. note:: The M flag is the 1-bit Managed Address Configuration flag for Router
+ Advisement. When set, Dynamic Host Configuration Protocol (DHCPv6) is
+ available for address configuration in addition to any IPs set by
+ using stateless address auto-configuration.
+
+-
+
+ Use the System VM template exclusively designed to support IPv6.
+ Download the System VM template from
+ `http://cloudstack.apt-get.eu/systemvm/ <http://cloudstack.apt-get.eu/systemvm/>`__.
+
+-
+
+ The concept of Default Network applies to IPv6 networks. However,
+ unlike IPv4 CloudStack does not control the routing information of
+ IPv6 in shared network; the choice of Default Network will not affect
+ the routing in the user VM.
+
+-
+
+ In a multiple shared network, the default route is set by the rack
+ router, rather than the DHCP server, which is out of CloudStack
+ control. Therefore, in order for the user VM to get only the default
+ route from the default NIC, modify the configuration of the user VM,
+ and set non-default NIC's ``accept_ra`` to 0 explicitly. The
+ ``accept_ra`` parameter accepts Router Advertisements and
+ auto-configure ``/proc/sys/net/ipv6/conf/interface`` with received
+ data.
+
+Limitations of IPv6 in CloudStack
+---------------------------------
+
+The following are not yet supported:
+
+#.
+
+ Security groups
+
+#.
+
+ Userdata and metadata
+
+#.
+
+ Passwords
+
+Guest VM Configuration for DHCPv6
+---------------------------------
+
+For the guest VMs to get IPv6 address, run dhclient command manually on
+each of the VMs. Use DUID-LL to set up dhclient.
+
+.. note:: The IPv6 address is lost when a VM is stopped and started. Therefore,
+use the same procedure to get an IPv6 address when a VM is stopped and
+started.
+
+#.
+
+ Set up dhclient by using DUID-LL.
+
+ Perform the following for DHCP Client 4.2 and above:
+
+ #.
+
+ Run the following command on the selected VM to get the dhcpv6
+ offer from VR:
+
+ .. sourcecode:: bash
+
+ dhclient -6 -D LL <dev>
+
+ Perform the following for DHCP Client 4.1:
+
+ #.
+
+ Open the following to the dhclient configuration file:
+
+ .. sourcecode:: bash
+
+ vi /etc/dhcp/dhclient.conf
+
+ #.
+
+ Add the following to the dhclient configuration file:
+
+ .. sourcecode:: bash
+
+ send dhcp6.client-id = concat(00:03:00, hardware);
+
+#.
+
+ Get IPv6 address from DHCP server as part of the system or network
+ restart.
+
+ Based on the operating systems, perform the following:
+
+ On CentOS 6.2:
+
+ #.
+
+ Open the Ethernet interface configuration file:
+
+ .. sourcecode:: bash
+
+ vi /etc/sysconfig/network-scripts/ifcfg-eth0
+
+ The ``ifcfg-eth0`` file controls the first NIC in a system.
+
+ #.
+
+ Make the necessary configuration changes, as given below:
+
+ .. sourcecode:: bash
+
+ DEVICE=eth0
+ HWADDR=06:A0:F0:00:00:38
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ BOOTPROTO=dhcp6
+ TYPE=Ethernet
+ USERCTL=no
+ PEERDNS=yes
+ IPV6INIT=yes
+ DHCPV6C=yes
+
+ #.
+
+ Open the following:
+
+ .. sourcecode:: bash
+
+ vi /etc/sysconfig/network
+
+ #.
+
+ Make the necessary configuration changes, as given below:
+
+ .. sourcecode:: bash
+
+ NETWORKING=yes
+ HOSTNAME=centos62mgmt.lab.vmops.com
+ NETWORKING_IPV6=yes
+ IPV6_AUTOCONF=no
+
+ On Ubuntu 12.10
+
+ #.
+
+ Open the following:
+
+ .. sourcecode:: bash
+
+ etc/network/interfaces:
+
+ #.
+
+ Make the necessary configuration changes, as given below:
+
+ .. sourcecode:: bash
+
+ iface eth0 inet6 dhcp
+ autoconf 0
+ accept_ra 1