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:30:59 UTC
[1/3] git commit: Adding plugin guide
Repository: cloudstack-docs
Updated Branches:
refs/heads/master 2542849fe -> 8f938c0d3
Adding plugin guide
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/f4dcc1aa
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/f4dcc1aa
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/f4dcc1aa
Branch: refs/heads/master
Commit: f4dcc1aa1738b76cebb1bb06ce09858e29dcab1e
Parents: 2542849
Author: Sebastien Goasguen <ru...@gmail.com>
Authored: Mon Feb 24 11:21:39 2014 -0500
Committer: Sebastien Goasguen <ru...@gmail.com>
Committed: Mon Feb 24 11:21:39 2014 -0500
----------------------------------------------------------------------
rtd/source/_static/images/plugin1.jpg | Bin 0 -> 32999 bytes
rtd/source/_static/images/plugin2.jpg | Bin 0 -> 35149 bytes
rtd/source/_static/images/plugin3.jpg | Bin 0 -> 41983 bytes
rtd/source/_static/images/plugin4.jpg | Bin 0 -> 32125 bytes
rtd/source/_static/images/plugin_intro.jpg | Bin 0 -> 22247 bytes
rtd/source/index.rst | 3 +-
rtd/source/plugins.rst | 695 ++++++++++++++++++++++++
7 files changed, 697 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/f4dcc1aa/rtd/source/_static/images/plugin1.jpg
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/plugin1.jpg b/rtd/source/_static/images/plugin1.jpg
new file mode 100644
index 0000000..970233d
Binary files /dev/null and b/rtd/source/_static/images/plugin1.jpg differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/f4dcc1aa/rtd/source/_static/images/plugin2.jpg
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/plugin2.jpg b/rtd/source/_static/images/plugin2.jpg
new file mode 100644
index 0000000..9c8a610
Binary files /dev/null and b/rtd/source/_static/images/plugin2.jpg differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/f4dcc1aa/rtd/source/_static/images/plugin3.jpg
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/plugin3.jpg b/rtd/source/_static/images/plugin3.jpg
new file mode 100644
index 0000000..07fae79
Binary files /dev/null and b/rtd/source/_static/images/plugin3.jpg differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/f4dcc1aa/rtd/source/_static/images/plugin4.jpg
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/plugin4.jpg b/rtd/source/_static/images/plugin4.jpg
new file mode 100644
index 0000000..2bcec9f
Binary files /dev/null and b/rtd/source/_static/images/plugin4.jpg differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/f4dcc1aa/rtd/source/_static/images/plugin_intro.jpg
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/plugin_intro.jpg b/rtd/source/_static/images/plugin_intro.jpg
new file mode 100644
index 0000000..113ffb3
Binary files /dev/null and b/rtd/source/_static/images/plugin_intro.jpg differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/f4dcc1aa/rtd/source/index.rst
----------------------------------------------------------------------
diff --git a/rtd/source/index.rst b/rtd/source/index.rst
index 8e61e62..fce9255 100644
--- a/rtd/source/index.rst
+++ b/rtd/source/index.rst
@@ -17,10 +17,10 @@ Networking Guides
networking/nicira-plugin
networking/midonet
+ networking/vxlan.rst
networking/ovs-plugin
networking/autoscale_without_netscaler.rst
networking/troubleshoot_internet_traffic.rst
- networking/vxlan.rst
Allocator Guide
---------------
@@ -37,6 +37,7 @@ Developer's Guide
:maxdepth: 2
developer_guide
+ plugins
ansible
Indices and tables
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/f4dcc1aa/rtd/source/plugins.rst
----------------------------------------------------------------------
diff --git a/rtd/source/plugins.rst b/rtd/source/plugins.rst
new file mode 100644
index 0000000..6e365a1
--- /dev/null
+++ b/rtd/source/plugins.rst
@@ -0,0 +1,695 @@
+Plugins
+=======
+
+
+Storage Plugins
+---------------
+
+This section gives an outline of how to implement a plugin to integrate
+a third-party storage provider. For details and an example, you will
+need to read the code.
+
+.. note:: Example code is available at: `plugins/storage/volume/sample`
+
+Third party storage providers can integrate with CloudStack to provide
+either primary storage or secondary storage. For example, CloudStack
+provides plugins for Amazon Simple Storage Service (S3) or OpenStack
+Object Storage (Swift). The S3 plugin can be used for any object storage
+that supports the Amazon S3 interface.
+
+Additional third party object storages that do not support the S3
+interface can be integrated with CloudStack by writing plugin software that
+uses the object storage plugin framework. Several new interfaces are
+available so that storage providers can develop vendor-specific plugins
+based on well-defined contracts that can be seamlessly managed by
+CloudStack.
+
+Artifacts such as templates, ISOs and snapshots are kept in storage
+which CloudStack refers to as secondary storage. To improve scalability and
+performance, as when a number of hosts access secondary storage
+concurrently, object storage can be used for secondary storage. Object
+storage can also provide built-in high availability capability. When
+using object storage, access to secondary storage data can be made
+available across multiple zones in a region. This is a huge benefit, as
+it is no longer necessary to copy templates, snapshots etc. across zones
+as would be needed in an environment using only zone-based NFS storage.
+
+The user enables a storage plugin through the UI. A new dialog box
+choice is offered to select the storage provider. Depending on which
+provider is selected, additional input fields may appear so that the
+user can provide the additional details required by that provider, such
+as a user name and password for a third-party storage account.
+
+Overview of How to Write a Storage Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add a third-party storage option to CloudStack, follow these general
+steps (explained in more detail later in this section):
+
+1. Implement the following interfaces in Java:
+
+ - DataStoreDriver
+
+ - DataStoreLifecycle
+
+ - DataStoreProvider
+
+ - VMSnapshotStrategy (if you want to customize the VM snapshot
+ functionality)
+
+2. Hardcode your plugin's required additional input fields into the code
+ for the Add Secondary Storage or Add Primary Storage dialog box.
+
+3. Place your .jar file in `plugins/storage/volume/` or `plugins/storage/image/`.
+
+4. Edit `/client/tomcatconf/componentContext.xml.in`.
+
+5. Edit `client/pom.xml`.
+
+Implementing DataStoreDriver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DataStoreDriver contains the code that CloudStack will use to provision the
+object store, when needed.
+
+You must implement the following methods:
+
+- getTO()
+
+- getStoreTO()
+
+- createAsync()
+
+- deleteAsync()
+
+The following methods are optional:
+
+- resize()
+
+- canCopy() is optional. If you set it to true, then you must implement
+ copyAsync().
+
+Implementing DataStoreLifecycle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DataStoreLifecycle contains the code to manage the storage operations
+for ongoing use of the storage. Several operations are needed, like
+create, maintenance mode, delete, etc.
+
+You must implement the following methods:
+
+- initialize()
+
+- maintain()
+
+- cancelMaintain()
+
+- deleteDataStore()
+
+- Implement one of the attach\*() methods depending on what scope you
+ want the storage to have: attachHost(), attachCluster(), or
+ attachZone().
+
+Implementing DataStoreProvider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DataStoreProvider contains the main code of the data store.
+
+You must implement the following methods:
+
+- getDatastoreLifeCycle()
+
+- getDataStoreDriver()
+
+- getTypes(). Returns one or more types of storage for which this data
+ store provider can be used. For secondary object storage, return
+ IMAGE, and for a Secondary Staging Store, return ImageCache.
+
+- configure(). First initialize the lifecycle implementation and the
+ driver implementation, then call registerDriver() to register the new
+ object store provider instance with CloudStack.
+
+- getName(). Returns the unique name of your provider; for example,
+ this can be used to get the name to display in the UI.
+
+The following methods are optional:
+
+- getHostListener() is optional; it's for monitoring the status of the
+ host.
+
+Implementing VMSnapshotStrategy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+VMSnapshotStrategy has the following methods:
+
+- takeVMSnapshot()
+
+- deleteVMSnapshot()
+
+- revertVMSnapshot()
+
+- canHandle(). For a given VM snapshot, tells whether this
+ implementation of VMSnapshotStrategy can handle it.
+
+Place the .jar File in the Right Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a secondary storage plugin, place your .jar file here:
+
+::
+
+ plugins/storage/image/
+
+For a primary storage plugin, place your .jar file here:
+
+::
+
+ plugins/storage/volume/
+
+Edit Configuration Files
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, edit the following file tell CloudStack to include your .jar file.
+Add a line to this file to tell the CloudStack Management Server that it
+now has a dependency on your code:
+
+::
+
+ client/pom.xml
+
+Place some facts about your code in the following file so CloudStack can
+run it:
+
+::
+
+ /client/tomcatconf/componentContext.xml.in
+
+In the section “Deployment configurations of various adapters,” add
+this:
+
+::
+
+ <bean>id=”some unique ID” class=”package name of your implementation of DataStoreProvider”</bean>
+
+In the section “Storage Providers,” add this:
+
+::
+
+ <property name=”providers”>
+ <ref local=”same ID from the bean tag's id attribute”>
+ </property>
+
+Minimum Required Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The classes, interfaces, and methods used by CloudStack from the Amazon Web
+Services (AWS) Java SDK are listed in this section. An object storage
+that supports the S3 interface is minimally required to support the
+below in order to be compatible with CloudStack.
+
+Interface AmazonS3
+^^^^^^^^^^^^^^^^^^
+
+http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3.html
+
++------------------+---------------------------------------------------------+
+| Modifier and | Method and Description |
+| Type | |
++==================+=========================================================+
+| Bucket | createBucket(String bucketName) |
+| | |
+| | Creates a new Amazon S3 bucket with the specified name |
+| | in the default (US) region, Region.US\_Standard. |
++------------------+---------------------------------------------------------+
+| void | deleteObject(String bucketName, String key) |
+| | |
+| | Deletes the specified object in the specified bucket. |
++------------------+---------------------------------------------------------+
+| ObjectMetadata | getObject(GetObjectRequest getObjectRequest, |
+| | File destinationFile) |
+| | |
+| | Gets the object metadata for the object stored in |
+| | Amazon S3 under the specified bucket and key, and saves |
+| | the object contents to the specified file. |
++------------------+---------------------------------------------------------+
+| S3Object | getObject(String bucketName, String key) |
+| | |
+| | Gets the object stored in Amazon S3 under the specified |
+| | bucket and key. |
++------------------+---------------------------------------------------------+
+| URL | generatePresignedUrl(String bucketName, String key, |
+| | Date expiration, HttpMethod method) |
+| | |
+| | Returns a pre-signed URL for accessing an Amazon S3 |
+| | resource. |
++------------------+---------------------------------------------------------+
+| void | deleteBucket(String bucketName) |
+| | |
+| | Deletes the specified bucket. |
++------------------+---------------------------------------------------------+
+| List<Bucket> | listBuckets() |
+| | |
+| | Returns a list of all Amazon S3 buckets that the |
+| | authenticated sender of the request owns. |
++------------------+---------------------------------------------------------+
+| ObjectListing | listObjects(String bucketName, String prefix) |
+| | |
+| | Returns a list of summary information about the objects |
+| | in the specified bucket. |
++------------------+---------------------------------------------------------+
+| PutObjectResult | putObject(PutObjectRequest putObjectRequest) |
+| | |
+| | Uploads a new object to the specified Amazon S3 bucket. |
++------------------+---------------------------------------------------------+
+| PutObjectResult | putObject(String bucketName, String key, File file) |
+| | |
+| | Uploads the specified file to Amazon S3 under the |
+| | specified bucket and key name. |
++------------------+---------------------------------------------------------+
+| PutObjectResult | putObject(String bucketName, String key, |
+| | InputStream input, ObjectMetadata metadata) |
+| | |
+| | Uploads the specified input stream and object metadata |
+| | to Amazon S3 under the specified bucket and key name. |
++------------------+---------------------------------------------------------+
+| void | setEndpoint(String endpoint) |
+| | |
+| | Overrides the default endpoint for this client. |
++------------------+---------------------------------------------------------+
+| void | setObjectAcl(String bucketName, String key, |
+| | CannedAccessControlList acl) |
+| | |
+| | Sets the CannedAccessControlList for the specified |
+| | object in Amazon S3 using one of the pre-configured |
+| | CannedAccessControlLists. |
++------------------+---------------------------------------------------------+
+
+*Class TransferManager*
+
+http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/transfer/TransferManager.html
+
++------------------+---------------------------------------------------------+
+| Modifier and | Method and Description |
+| Type | |
++==================+=========================================================+
+| Upload | upload(PutObjectRequest putObjectRequest) |
+| | |
+| | Schedules a new transfer to upload data to Amazon S3. |
++------------------+---------------------------------------------------------+
+
+*Class PutObjectRequest*
+
+http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/PutObjectRequest.html
+
++------------------+---------------------------------------------------------+
+| Modifier and | Method and Description |
+| Type | |
++==================+=========================================================+
+| Upload | upload(PutObjectRequest putObjectRequest) |
+| | |
+| | Schedules a new transfer to upload data to Amazon S3. |
++------------------+---------------------------------------------------------+
+
+
+Third Party UI Plugins
+----------------------
+
+Using the new third-party plugin framework, you can write and install
+extensions to CloudStack. The installed and enabled plugins will appear in
+the UI alongside the other features. The code for the plugin is simply
+placed in a special directory within CloudStack’s installed code at any
+time after CloudStack installation. The new plugin appears only when it is
+enabled by the cloud administrator.
+
+.. figure:: /_static/images/plugin_intro.jpg
+ :align: center
+ :alt: New plugin button in CloudStack navbar
+
+The left navigation bar of the CloudStack UI has a new Plugins button to
+help you work with UI plugins.
+
+How to Write a Plugin: Overview
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The basic procedure for writing a plugin is:
+
+1. Write the code and create the other files needed. You will need the
+ plugin code itself (in Javascript), a thumbnail image, the plugin
+ listing, and a CSS file.
+
+ .. figure:: /_static/images/plugin1.jpg
+ :align: center
+ :alt: Write the plugin code
+
+ All UI plugins have the following set of files:
+
+ ::
+
+ +-- cloudstack/
+ +-- ui/
+ +-- plugins/
+ +-- csMyFirstPlugin/
+ +-- config.js --> Plugin metadata (title, author, vendor URL, etc.)
+ +-- icon.png --> Icon, shown on side nav bar and plugin listing
+ (should be square, and ~50x50px)
+ +-- csMyFirstPlugin.css --> CSS file, loaded automatically when plugin loads
+ +-- csMyFirstPlugin.js --> Main JS file, containing plugin code
+
+
+ The same files must also be present at
+ `/tomcat/webapps/client/plugins`.
+
+2. The CloudStack administrator adds the folder containing your plugin code
+ under the CloudStack PLUGINS folder.
+
+ .. figure:: /_static/images/plugin2.jpg
+ :align: center
+ :alt: The plugin code is placed in the PLUGINS folder
+
+3. The administrator also adds the name of your plugin to the plugin.js
+ file in the PLUGINS folder.
+
+ .. figure:: /_static/images/plugin3.jpg
+ :align: center
+ :alt: The plugin name is added to `plugin.js` in the PLUGINS folder
+
+4. The next time the user refreshes the UI in the browser, your plugin
+ will appear in the left navigation bar.
+
+ .. figure:: /_static/images/plugin4.jpg
+ :align: center
+ :alt: The plugin appears in the UI
+
+How to Write a Plugin: Implementation Details
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section requires an understanding of JavaScript and the CloudStack
+API. You don't need knowledge of specific frameworks for this tutorial
+(jQuery, etc.), since the CloudStack UI handles the front-end rendering for
+you.
+
+There is much more to the CloudStack UI framework than can be described
+here. The UI is very flexible to handle many use cases, so there are
+countless options and variations. The best reference right now is to
+read the existing code for the main UI, which is in the /ui folder.
+Plugins are written in a very similar way to the main UI.
+
+1. **Create the directory to hold your plugin.**
+
+ All plugins are composed of set of required files in the directory
+ /ui/plugins/pluginID, where pluginID is a short name for your
+ plugin. It's recommended that you prefix your folder name (for
+ example, bfMyPlugin) to avoid naming conflicts with other people's
+ plugins.
+
+ In this example, the plugin is named csMyFirstPlugin.
+
+ ::
+
+ $ cd cloudstack/ui/plugins
+ $ mkdir csMyFirstPlugin
+ $ ls -l
+
+ total 8
+ drwxr-xr-x 2 bgregory staff 68 Feb 11 14:44 csMyFirstPlugin
+ -rw-r--r-- 1 bgregory staff 101 Feb 11 14:26 plugins.js
+
+
+2. **Change to your new plugin directory.**
+
+ ::
+
+ $ cd csMyFirstPlugin
+
+
+3. **Set up the listing.**
+
+ Add the file `config.js`, using your favorite editor.
+
+ ::
+
+ $ vi config.js
+
+ Add the following content to config.js. This information will be
+ displayed on the plugin listing page in the UI:
+
+ ::
+
+ (function (cloudStack) {
+ cloudStack.plugins.csMyFirstPlugin.config = {
+ title: 'My first plugin',
+ desc: 'Tutorial plugin',
+ externalLink: 'http://www.cloudstack.org/',
+ authorName: 'Test Plugin Developer',
+ authorEmail: 'plugin.developer@example.com'
+ };
+ }(cloudStack));
+
+
+4. **Add a new main section.**
+
+ Add the file csMyFirstPlugin.js, using your favorite editor.
+
+ ::
+
+ $ vi csMyFirstPlugin.js
+
+ Add the following content to csMyFirstPlugin.js:
+
+ ::
+
+ (function (cloudStack) {
+ cloudStack.plugins.csMyFirstPlugin = function(plugin) {
+ plugin.ui.addSection({
+ id: 'csMyFirstPlugin',
+ title: 'My Plugin',
+ preFilter: function(args) {
+ return isAdmin();
+ },
+ show: function() {
+ return $('<div>').html('Content will go here');
+ }
+ });
+ };
+ }(cloudStack));
+
+
+5. **Register the plugin.**
+
+ You now have the minimal content needed to run the plugin, so you
+ can activate the plugin in the UI by adding it to plugins.js. First,
+ edit the file:
+
+ ::
+
+ $ cd cloudstack/ui/plugins
+ $ vi plugins.js
+
+
+ Now add the following to plugins.js:
+
+ ::
+
+ (function($, cloudStack) {
+ cloudStack.plugins = [
+ 'csMyFirstPlugin'
+ ];
+ }(jQuery, cloudStack));
+
+
+6. **Check the plugin in the UI.**
+
+ First, copy all the plugin code that you have created so far to
+ `/tomcat/webapps/client/plugins`. Then refresh the browser and click
+ Plugins in the side navigation bar. You should see your new plugin.
+
+7. **Make the plugin do something.**
+
+ Right now, you just have placeholder content in the new plugin. It's
+ time to add real code. In this example, you will write a basic list
+ view, which renders data from an API call. You will list all virtual
+ machines owned by the logged-in user. To do this, replace the 'show'
+ function in the plugin code with a 'listView' block, containing the
+ required syntax for a list view. To get the data, use the
+ listVirtualMachines API call. Without any parameters, it will return
+ VMs only for your active user. Use the provided 'apiCall' helper
+ method to handle the server call. Of course, you are free to use any
+ other method for making the AJAX call (for example, jQuery's $.ajax
+ method).
+
+ First, open your plugin's JavaScript source file in your favorite
+ editor:
+
+ ::
+
+ $ cd csMyFirstPlugin
+ $ vi csMyFirstPlugin.js
+
+
+ Add the following code in csMyFirstPlugin.js:
+
+ ::
+
+ (function (cloudStack) {
+ cloudStack.plugins.csMyFirstPlugin = function(plugin) {
+ plugin.ui.addSection({
+ id: 'csMyFirstPlugin',
+ title: 'My Plugin',
+ preFilter: function(args) {
+ return isAdmin();
+ },
+
+ // Render page as a list view
+ listView: {
+ id: 'testPluginInstances',
+ fields: {
+ name: { label: 'label.name' },
+ instancename: { label: 'label.internal.name' },
+ displayname: { label: 'label.display.name' },
+ zonename: { label: 'label.zone.name' }
+ },
+ dataProvider: function(args) {
+ // API calls go here, to retrive the data asynchronously
+ //
+ // On successful retrieval, call
+ // args.response.success({ data: [data array] });
+ plugin.ui.apiCall('listVirtualMachines', {
+ success: function(json) {
+ var vms = json.listvirtualmachinesresponse.virtualmachine;
+
+ args.response.success({ data: vms });
+ },
+ error: function(errorMessage) {
+ args.response.error(errorMessage)
+ }
+ });
+ }
+ }
+ });
+ };
+ }(cloudStack));
+
+
+8. **Test the plugin.**
+
+ First, copy all the plugin code that you have created so far to
+ `/tomcat/webapps/client/plugins`. Then refresh the browser. You can
+ see that your placeholder content was replaced with a list table,
+ containing 4 columns of virtual machine data.
+
+9. **Add an action button.**
+
+ Let's add an action button to the list view, which will reboot the
+ VM. To do this, add an actions block under listView. After
+ specifying the correct format, the actions will appear automatically
+ to the right of each row of data.
+
+ ::
+
+ $ vi csMyFirstPlugin.js
+
+
+ Now add the following new code in csMyFirstPlugin.js. (The dots ...
+ show where we have omitted some existing code for the sake of space.
+ Don't actually cut and paste that part):
+
+ ::
+
+ ...
+ listView: {
+ id: 'testPluginInstances',
+ ...
+
+ actions: {
+ // The key/ID you specify here will determine what icon is
+ // shown in the UI for this action,
+ // and will be added as a CSS class to the action's element
+ // (i.e., '.action.restart')
+ //
+ // -- here, 'restart' is a predefined name in CloudStack that will
+ // automatically show a 'reboot' arrow as an icon;
+ // this can be changed in csMyFirstPlugin.css
+ restart: {
+ label: 'Restart VM',
+ messages: {
+ confirm: function() { return 'Are you sure you want to restart this VM?' },
+ notification: function() { return 'Rebooted VM' }
+ },
+ action: function(args) {
+ // Get the instance object of the selected row from context
+ //
+ // -- all currently loaded state is stored in 'context' as objects,
+ // such as the selected list view row,
+ // the selected section, and active user
+ //
+ // -- for list view actions, the object's key will be the same as
+ // listView.id, specified above;
+ // always make sure you specify an 'id' for the listView,
+ // or else it will be 'undefined!'
+ var instance = args.context.testPluginInstances[0];
+
+ plugin.ui.apiCall('rebootVirtualMachine', {
+ // These will be appended to the API request
+ //
+ // i.e., rebootVirtualMachine&id=...
+ data: {
+ id: instance.id
+ },
+ success: function(json) {
+ args.response.success({
+ // This is an async job, so success here only indicates
+ // that the job was initiated.
+ //
+ // To pass the job ID to the notification UI
+ // (for checking to see when action is completed),
+ // '_custom: { jobID: ... }' needs to always be passed on success,
+ // in the same format as below
+ _custom: { jobId: json.rebootvirtualmachineresponse.jobid }
+ });
+ },
+
+
+ error: function(errorMessage) {
+ args.response.error(errorMessage); // Cancel action, show error message returned
+ }
+ });
+ },
+
+ // Because rebootVirtualMachine is an async job, we need to add
+ // a poll function, which will perodically check
+ // the management server to see if the job is ready
+ // (via pollAsyncJobResult API call)
+ //
+ // The plugin API provides a helper function, 'plugin.ui.pollAsyncJob',
+ / which will work for most jobs
+ // in CloudStack
+ notification: {
+ poll: plugin.ui.pollAsyncJob
+ }
+ }
+ },
+
+ dataProvider: function(args) {
+ ...
+ ...
+
+
+10. **Add the thumbnail icon.**
+
+ Create an icon file; it should be square, about 50x50 pixels, and
+ named `icon.png`. Copy it into the same directory with your plugin
+ code: `cloudstack/ui/plugins/csMyFirstPlugin/icon.png`.
+
+11. **Add the stylesheet.**
+
+ Create a CSS file, with the same name as your `.js` file. Copy it into
+ the same directory with your plugin code:
+ `cloudstack/ui/plugins/csMyFirstPlugin/csMyFirstPlugin.css`.
+
+.. | plugin_intro.jpg: New plugin button in CloudStack navbar | image:: _static/images/plugin_intro.jpg
+.. | plugin1.jpg: Write the plugin code | image:: _static/images/plugin1.jpg
+.. | plugin2.jpg: The plugin code is placed in the PLUGINS folder | image:: _static/images/plugin2.jpg
+.. | plugin3.jpg: The plugin name is added to plugin.js in the PLUGINS folder | image:: _static/images/plugin3.jpg
+.. | plugin4.jpg: The plugin appears in the UI | image:: _static/images/plugin4.jpg
+
+
[3/3] git commit: add usage guide, ipv6 and api
Posted by se...@apache.org.
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
[2/3] add usage guide, ipv6 and api
Posted by se...@apache.org.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/8f938c0d/rtd/source/usage.rst
----------------------------------------------------------------------
diff --git a/rtd/source/usage.rst b/rtd/source/usage.rst
new file mode 100644
index 0000000..10f7e9f
--- /dev/null
+++ b/rtd/source/usage.rst
@@ -0,0 +1,693 @@
+Working with usage data
+=======================
+
+The Usage Server provides aggregated usage records which you can use to
+create billing integration for the CloudStack platform. The Usage Server
+works by taking data from the events log and creating summary usage
+records that you can access using the listUsageRecords API call.
+
+The usage records show the amount of resources, such as VM run time or
+template storage space, consumed by guest instances. In the special case
+of bare metal instances, no template storage resources are consumed, but
+records showing zero usage are still included in the Usage Server's
+output.
+
+The Usage Server runs at least once per day. It can be configured to run
+multiple times per day. Its behavior is controlled by configuration
+settings as described in the CloudStack Administration Guide.
+
+Usage Record Format
+-------------------
+
+Virtual Machine Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For running and allocated virtual machine usage, the following fields
+exist in a usage record:
+
+-
+
+ account – name of the account
+
+-
+
+ accountid – ID of the account
+
+-
+
+ domainid – ID of the domain in which this account resides
+
+-
+
+ zoneid – Zone where the usage occurred
+
+-
+
+ description – A string describing what the usage record is tracking
+
+-
+
+ usage – String representation of the usage, including the units of
+ usage (e.g. 'Hrs' for VM running time)
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage – A number representing the actual usage in hours
+
+-
+
+ virtualMachineId – The ID of the virtual machine
+
+-
+
+ name – The name of the virtual machine
+
+-
+
+ offeringid – The ID of the service offering
+
+-
+
+ templateid – The ID of the template or the ID of the parent template.
+ The parent template value is present when the current template was
+ created from a volume.
+
+-
+
+ usageid – Virtual machine
+
+-
+
+ type – Hypervisor
+
+-
+
+ startdate, enddate – The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+Network Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For network usage (bytes sent/received), the following fields exist in a
+usage record.
+
+-
+
+ account – name of the account
+
+-
+
+ accountid – ID of the account
+
+-
+
+ domainid – ID of the domain in which this account resides
+
+-
+
+ zoneid – Zone where the usage occurred
+
+-
+
+ description – A string describing what the usage record is tracking
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage – A number representing the actual usage in hours
+
+-
+
+ usageid – Device ID (virtual router ID or external device ID)
+
+-
+
+ type – Device type (domain router, external load balancer, etc.)
+
+-
+
+ startdate, enddate – The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+IP Address Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For IP address usage the following fields exist in a usage record.
+
+-
+
+ account - name of the account
+
+-
+
+ accountid - ID of the account
+
+-
+
+ domainid - ID of the domain in which this account resides
+
+-
+
+ zoneid - Zone where the usage occurred
+
+-
+
+ description - A string describing what the usage record is tracking
+
+-
+
+ usage - String representation of the usage, including the units of
+ usage
+
+-
+
+ usagetype - A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage - A number representing the actual usage in hours
+
+-
+
+ usageid - IP address ID
+
+-
+
+ startdate, enddate - The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+-
+
+ issourcenat - Whether source NAT is enabled for the IP address
+
+-
+
+ iselastic - True if the IP address is elastic.
+
+Disk Volume Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For disk volumes, the following fields exist in a usage record.
+
+-
+
+ account – name of the account
+
+-
+
+ accountid – ID of the account
+
+-
+
+ domainid – ID of the domain in which this account resides
+
+-
+
+ zoneid – Zone where the usage occurred
+
+-
+
+ description – A string describing what the usage record is tracking
+
+-
+
+ usage – String representation of the usage, including the units of
+ usage (e.g. 'Hrs' for hours)
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage – A number representing the actual usage in hours
+
+-
+
+ usageid – The volume ID
+
+-
+
+ offeringid – The ID of the disk offering
+
+-
+
+ type – Hypervisor
+
+-
+
+ templateid – ROOT template ID
+
+-
+
+ size – The amount of storage allocated
+
+-
+
+ startdate, enddate – The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+Template, ISO, and Snapshot Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-
+
+ account – name of the account
+
+-
+
+ accountid – ID of the account
+
+-
+
+ domainid – ID of the domain in which this account resides
+
+-
+
+ zoneid – Zone where the usage occurred
+
+-
+
+ description – A string describing what the usage record is tracking
+
+-
+
+ usage – String representation of the usage, including the units of
+ usage (e.g. 'Hrs' for hours)
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage – A number representing the actual usage in hours
+
+-
+
+ usageid – The ID of the the template, ISO, or snapshot
+
+-
+
+ offeringid – The ID of the disk offering
+
+-
+
+ templateid – – Included only for templates (usage type 7). Source
+ template ID.
+
+-
+
+ size – Size of the template, ISO, or snapshot
+
+-
+
+ startdate, enddate – The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+Load Balancer Policy or Port Forwarding Rule Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-
+
+ account - name of the account
+
+-
+
+ accountid - ID of the account
+
+-
+
+ domainid - ID of the domain in which this account resides
+
+-
+
+ zoneid - Zone where the usage occurred
+
+-
+
+ description - A string describing what the usage record is tracking
+
+-
+
+ usage - String representation of the usage, including the units of
+ usage (e.g. 'Hrs' for hours)
+
+-
+
+ usagetype - A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage - A number representing the actual usage in hours
+
+-
+
+ usageid - ID of the load balancer policy or port forwarding rule
+
+-
+
+ usagetype - A number representing the usage type (see Usage Types)
+
+-
+
+ startdate, enddate - The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+Network Offering Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-
+
+ account – name of the account
+
+-
+
+ accountid – ID of the account
+
+-
+
+ domainid – ID of the domain in which this account resides
+
+-
+
+ zoneid – Zone where the usage occurred
+
+-
+
+ description – A string describing what the usage record is tracking
+
+-
+
+ usage – String representation of the usage, including the units of
+ usage (e.g. 'Hrs' for hours)
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage – A number representing the actual usage in hours
+
+-
+
+ usageid – ID of the network offering
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ offeringid – Network offering ID
+
+-
+
+ virtualMachineId – The ID of the virtual machine
+
+-
+
+ virtualMachineId – The ID of the virtual machine
+
+-
+
+ startdate, enddate – The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+VPN User Usage Record Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-
+
+ account – name of the account
+
+-
+
+ accountid – ID of the account
+
+-
+
+ domainid – ID of the domain in which this account resides
+
+-
+
+ zoneid – Zone where the usage occurred
+
+-
+
+ description – A string describing what the usage record is tracking
+
+-
+
+ usage – String representation of the usage, including the units of
+ usage (e.g. 'Hrs' for hours)
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ rawusage – A number representing the actual usage in hours
+
+-
+
+ usageid – VPN user ID
+
+-
+
+ usagetype – A number representing the usage type (see Usage Types)
+
+-
+
+ startdate, enddate – The range of time for which the usage is
+ aggregated; see Dates in the Usage Record
+
+
+Usage Types
+-----------
+
+The following table shows all usage types.
+
++------------------+-----------------------------------+-----------------------+
+| Type ID | Type Name | Description |
++==================+===================================+=======================+
+| 1 | RUNNING\_VM | Tracks the total |
+| | | running time of a VM |
+| | | per usage record |
+| | | period. If the VM is |
+| | | upgraded during the |
+| | | usage period, you |
+| | | will get a separate |
+| | | Usage Record for the |
+| | | new upgraded VM. |
++------------------+-----------------------------------+-----------------------+
+| 2 | ALLOCATED\_VM | Tracks the total time |
+| | | the VM has been |
+| | | created to the time |
+| | | when it has been |
+| | | destroyed. This usage |
+| | | type is also useful |
+| | | in determining usage |
+| | | for specific |
+| | | templates such as |
+| | | Windows-based |
+| | | templates. |
++------------------+-----------------------------------+-----------------------+
+| 3 | IP\_ADDRESS | Tracks the public IP |
+| | | address owned by the |
+| | | account. |
++------------------+-----------------------------------+-----------------------+
+| 4 | NETWORK\_BYTES\_SENT | Tracks the total |
+| | | number of bytes sent |
+| | | by all the VMs for an |
+| | | account. Cloud.com |
+| | | does not currently |
+| | | track network traffic |
+| | | per VM. |
++------------------+-----------------------------------+-----------------------+
+| 5 | NETWORK\_BYTES\_RECEIVED | Tracks the total |
+| | | number of bytes |
+| | | received by all the |
+| | | VMs for an account. |
+| | | Cloud.com does not |
+| | | currently track |
+| | | network traffic per |
+| | | VM. |
++------------------+-----------------------------------+-----------------------+
+| 6 | VOLUME | Tracks the total time |
+| | | a disk volume has |
+| | | been created to the |
+| | | time when it has been |
+| | | destroyed. |
++------------------+-----------------------------------+-----------------------+
+| 7 | TEMPLATE | Tracks the total time |
+| | | a template (either |
+| | | created from a |
+| | | snapshot or uploaded |
+| | | to the cloud) has |
+| | | been created to the |
+| | | time it has been |
+| | | destroyed. The size |
+| | | of the template is |
+| | | also returned. |
++------------------+-----------------------------------+-----------------------+
+| 8 | ISO | Tracks the total time |
+| | | an ISO has been |
+| | | uploaded to the time |
+| | | it has been removed |
+| | | from the cloud. The |
+| | | size of the ISO is |
+| | | also returned. |
++------------------+-----------------------------------+-----------------------+
+| 9 | SNAPSHOT | Tracks the total time |
+| | | from when a snapshot |
+| | | has been created to |
+| | | the time it have been |
+| | | destroyed. |
++------------------+-----------------------------------+-----------------------+
+| 11 | LOAD\_BALANCER\_POLICY | Tracks the total time |
+| | | a load balancer |
+| | | policy has been |
+| | | created to the time |
+| | | it has been removed. |
+| | | Cloud.com does not |
+| | | track whether a VM |
+| | | has been assigned to |
+| | | a policy. |
++------------------+-----------------------------------+-----------------------+
+| 12 | PORT\_FORWARDING\_RULE | Tracks the time from |
+| | | when a port |
+| | | forwarding rule was |
+| | | created until the |
+| | | time it was removed. |
++------------------+-----------------------------------+-----------------------+
+| 13 | NETWORK\_OFFERING | The time from when a |
+| | | network offering was |
+| | | assigned to a VM |
+| | | until it is removed. |
++------------------+-----------------------------------+-----------------------+
+| 14 | VPN\_USERS | The time from when a |
+| | | VPN user is created |
+| | | until it is removed. |
++------------------+-----------------------------------+-----------------------+
+
+
+Example response from listUsageRecords
+--------------------------------------
+
+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:
+
+::
+
+ <listusagerecordsresponse>
+ <count>1816</count>
+ <usagerecord>
+ <account>user5</account>
+ <accountid>10004</accountid>
+ <domainid>1</domainid>
+ <zoneid>1</zoneid>
+ <description>i-3-4-WC running time (ServiceOffering: 1) (Template: 3)</description>
+ <usage>2.95288 Hrs</usage>
+ <usagetype>1</usagetype>
+ <rawusage>2.95288</rawusage>
+ <virtualmachineid>4</virtualmachineid>
+ <name>i-3-4-WC</name>
+ <offeringid>1</offeringid>
+ <templateid>3</templateid>
+ <usageid>245554</usageid>
+ <type>XenServer</type>
+ <startdate>2009-09-15T00:00:00-0700</startdate>
+ <enddate>2009-09-18T16:14:26-0700</enddate>
+ </usagerecord>
+
+ … (1,815 more usage records)
+ </listusagerecordsresponse>
+
+Dates in the Usage Record
+-------------------------
+
+Usage records include a start date and an end date. These dates define
+the period of time for which the raw usage number was calculated. If
+daily aggregation is used, the start date is midnight on the day in
+question and the end date is 23:59:59 on the day in question (with one
+exception; see below). A virtual machine could have been deployed at
+noon on that day, stopped at 6pm on that day, then started up again at
+11pm. When usage is calculated on that day, there will be 7 hours of
+running VM usage (usage type 1) and 12 hours of allocated VM usage
+(usage type 2). If the same virtual machine runs for the entire next
+day, there will 24 hours of both running VM usage (type 1) and allocated
+VM usage (type 2).
+
+Note: The start date is not the time a virtual machine was started, and
+the end date is not the time when a virtual machine was stopped. The
+start and end dates give the time range within which usage was
+calculated.
+
+For network usage, the start date and end date again define the range in
+which the number of bytes transferred was calculated. If a user
+downloads 10 MB and uploads 1 MB in one day, there will be two records,
+one showing the 10 megabytes received and one showing the 1 megabyte
+sent.
+
+There is one case where the start date and end date do not correspond to
+midnight and 11:59:59pm when daily aggregation is used. This occurs only
+for network usage records. When the usage server has more than one day's
+worth of unprocessed data, the old data will be included in the
+aggregation period. The start date in the usage record will show the
+date and time of the earliest event. For other types of usage, such as
+IP addresses and VMs, the old unprocessed data is not included in daily
+aggregation.
+
+Globally Configured Limits
+--------------------------
+
+In a zone, the guest virtual network has a 24 bit CIDR by default. This
+limits the guest virtual network to 254 running instances. It can be
+adjusted as needed, but this must be done before any instances are
+created in the zone. For example, 10.1.1.0/22 would provide for ~1000
+addresses.
+
+The following table lists limits set in the Global Configuration:
+
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Parameter Name | Definition |
++===========================+==================================================================================================================================================================================================================================================================================================+
+| max.account.public.ips | Number of public IP addresses that can be owned by an account |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| max.account.snapshots | Number of snapshots that can exist for an account |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| max.account.templates | Number of templates that can exist for an account |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| max.account.user.vms | Number of virtual machine instances that can exist for an account |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| max.account.volumes | Number of disk volumes that can exist for an account |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| max.template.iso.size | Maximum size for a downloaded template or ISO in GB |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| max.volume.size.gb | Maximum size for a volume in GB |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| network.throttling.rate | Default data transfer rate in megabits per second allowed per user (supported on XenServer) |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| snapshot.max.hourly | Maximum recurring hourly snapshots to be retained for a volume. If the limit is reached, early snapshots from the start of the hour are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring hourly snapshots can not be scheduled |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| snapshot.max.daily | Maximum recurring daily snapshots to be retained for a volume. If the limit is reached, snapshots from the start of the day are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring daily snapshots can not be scheduled |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| snapshot.max.weekly | Maximum recurring weekly snapshots to be retained for a volume. If the limit is reached, snapshots from the beginning of the week are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring weekly snapshots can not be scheduled |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| snapshot.max.monthly | Maximum recurring monthly snapshots to be retained for a volume. If the limit is reached, snapshots from the beginning of the month are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring monthly snapshots can not be scheduled. |
++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+To modify global configuration parameters, use the global configuration
+screen in the CloudStack UI. See Setting Global Configuration Parameters
+