cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From seb...@apache.org
Subject [3/3] git commit: add usage guide, ipv6 and api
Date Mon, 24 Feb 2014 17:31:01 GMT
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 <runseb@gmail.com>
Authored: Mon Feb 24 12:30:45 2014 -0500
Committer: Sebastien Goasguen <runseb@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


Mime
View raw message