You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ke...@apache.org on 2013/10/02 16:23:26 UTC
[25/51] [partial] Adding documents from 4.2
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/storage-overview.xml
----------------------------------------------------------------------
diff --git a/en-US/storage-overview.xml b/en-US/storage-overview.xml
new file mode 100644
index 0000000..bebf441
--- /dev/null
+++ b/en-US/storage-overview.xml
@@ -0,0 +1,27 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<section id="storage-overview">
+ <title>Storage Overview</title>
+ <para>&PRODUCT; defines two types of storage: primary and secondary. Primary storage can be
+ accessed by either iSCSI or NFS. Additionally, direct attached storage may be used for primary
+ storage. Secondary storage is always accessed using NFS.</para>
+ <para>There is no ephemeral storage in &PRODUCT;. All volumes on all nodes are persistent.</para>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/storage-plugins.xml
----------------------------------------------------------------------
diff --git a/en-US/storage-plugins.xml b/en-US/storage-plugins.xml
new file mode 100644
index 0000000..e6612c1
--- /dev/null
+++ b/en-US/storage-plugins.xml
@@ -0,0 +1,144 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///C:/Program%20Files%20(x86)/Publican/DocBook_DTD/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<chapter id="storage-plugins">
+ <title>Writing a Storage Plugin</title>
+ <para>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.</para>
+ <note>
+ <para>Example code is available at:
+ plugins/storage/volume/sample</para>
+ </note>
+ <para/>
+ <para>Third party storage providers can integrate with &PRODUCT; to provide
+ either primary storage or secondary storage.
+ For example, &PRODUCT; provides plugins for
+ Amazon Simple Storage Service (S3) or OpenStack
+ Object Storage (Swift). Additional third party object storages can be integrated with &PRODUCT;
+ 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 &PRODUCT;.</para>
+ <para>Artifacts such as templates, ISOs and snapshots are kept in storage which &PRODUCT;
+ 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.</para>
+ <para>The user enables a storage plugin through the UI.
+ A new dialog box choice is offered to select the storage
+ provider. Depending on the provider you select, additional input fields may appear so that
+ you can provide the additional details required by that provider, such as a user name and
+ password for a third-party storage account.
+ </para>
+ <section id="storage-plugin-steps">
+ <title>Overview of How to Write a Storage Plugin</title>
+ <para>To add a third-party storage option to &PRODUCT;, implement the following interfaces in Java:</para>
+ <itemizedlist>
+ <listitem><para>DataStoreDriver</para></listitem>
+ <listitem><para>DataStoreLifecycle</para></listitem>
+ <listitem><para>DataStoreProvider</para></listitem>
+ <listitem><para>In addition to implementing the interfaces, you have to hardcode your plugin's required additional
+ input fields into the code for the Add Secondary Storage
+ or Add Primary Storage dialog box.</para></listitem>
+ <listitem><para>Place your .jar file in plugins/storage/volume/ or plugins/storage/image/.</para></listitem>
+ <listitem><para>Edit /client/tomcatconf/componentContext.xml.in.</para></listitem>
+ <listitem><para>Edit client/pom.xml.</para></listitem>
+ </itemizedlist>
+ </section>
+ <section id="datastoredriver">
+ <title>Implementing DataStoreDriver</title>
+ <para>DataStoreDriver contains the code that &PRODUCT; will use to provision the object store, when needed.</para>
+ <para>You must implement the following methods:</para>
+ <itemizedlist>
+ <listitem><para>getTO()</para></listitem>
+ <listitem><para>getStoreTO()</para></listitem>
+ <listitem><para>createAsync()</para></listitem>
+ <listitem><para>deleteAsync()</para></listitem>
+ </itemizedlist>
+ <para>The following methods are optional:</para>
+ <itemizedlist>
+ <listitem><para>resize()</para></listitem>
+ <listitem><para>canCopy() is optional. If you set it to true, then you must implement copyAsync().</para></listitem>
+ </itemizedlist>
+ </section>
+ <section id="datastorelifecycle">
+ <title>Implementing DataStoreLifecycle</title>
+ <para>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.</para>
+ <para>You must implement the following methods:</para>
+ <itemizedlist>
+ <listitem><para>initialize()</para></listitem>
+ <listitem><para>maintain()</para></listitem>
+ <listitem><para>cancelMaintain()</para></listitem>
+ <listitem><para>deleteDataStore()</para></listitem>
+ <listitem><para>Implement one of the attach*() methods depending on what scope you want the storage to have: attachHost(), attachCluster(), or attachZone().</para></listitem>
+ </itemizedlist>
+ </section>
+ <section id="datastoreprovider">
+ <title>Implementing DataStoreProvider</title>
+ <para>DataStoreProvider contains the main code of the data store.</para>
+ <para>You must implement the following methods:</para>
+ <itemizedlist>
+ <listitem><para>getDatastoreLifeCycle()</para></listitem>
+ <listitem><para>getDataStoreDriver()</para></listitem>
+ <listitem><para>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.</para></listitem>
+ <listitem><para>configure(). First initialize the lifecycle implementation and the driver implementation,
+ then call registerDriver() to register the new object store provider instance with &PRODUCT;.</para></listitem>
+ <listitem><para>getName(). Returns the unique name of your provider; for example,
+ this can be used to get the name to display in the UI.</para></listitem>
+ </itemizedlist>
+ <para>The following methods are optional:</para>
+ <itemizedlist>
+ <listitem><para>getHostListener() is optional; it's for monitoring the status of the host.</para></listitem>
+ </itemizedlist>
+ </section>
+ <section id="storage-plugin-code-location">
+ <title>Place the .jar File in the Right Directory</title>
+ <para>For a secondary storage plugin, place your .jar file here:</para>
+ <programlisting>plugins/storage/image/</programlisting>
+ <para>For a primary storage plugin, place your .jar file here:</para>
+ <programlisting>plugins/storage/volume/</programlisting>
+ </section>
+ <section id="storage-plugin-componentcontext-xml">
+ <title>Edit Configuration Files</title>
+ <para>First, edit the following file tell &PRODUCT; to include your .jar file.
+ Add a line to this file to tell the &PRODUCT; Management Server that it now has a dependency on your code:</para>
+ <programlisting>client/pom.xml</programlisting>
+ <para>Place some facts about your code in the following file so &PRODUCT; can run it:</para>
+ <programlisting>/client/tomcatconf/componentContext.xml.in</programlisting>
+ <para>In the section “Deployment configurations of various adapters,” add this:</para>
+ <programlisting><bean>id=”some unique ID” class=”package name of your implementation of DataStoreProvider”</bean></programlisting>
+ <para>In the section “Storage Providers,” add this:</para>
+ <programlisting><property name=”providers”>
+ <ref local=”same ID from the bean tag's id attribute”>
+</property></programlisting>
+
+ </section>
+
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/storage-setup.xml
----------------------------------------------------------------------
diff --git a/en-US/storage-setup.xml b/en-US/storage-setup.xml
new file mode 100644
index 0000000..dee2f4c
--- /dev/null
+++ b/en-US/storage-setup.xml
@@ -0,0 +1,192 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="storage-setup">
+ <title>Storage Setup</title>
+ <para>&PRODUCT; is designed to work with a wide variety of commodity and enterprise-grade storage. Local disk may be used as well, if supported by the selected hypervisor. Storage type support for guest virtual disks differs based on hypervisor selection.</para>
+ <informaltable>
+ <tgroup cols="4" align="left" colsep="1" rowsep="1">
+ <thead>
+ <row>
+ <entry><para></para></entry>
+ <entry><para>XenServer</para></entry>
+ <entry><para>vSphere</para></entry>
+ <entry><para>KVM</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>NFS</para></entry>
+ <entry><para>Supported</para></entry>
+ <entry><para>Supported</para></entry>
+ <entry><para>Supported</para></entry>
+ </row>
+ <row>
+ <entry><para>iSCSI</para></entry>
+ <entry><para>Supported</para></entry>
+ <entry><para>Supported via VMFS</para></entry>
+ <entry><para>Supported via Clustered Filesystems</para></entry>
+ </row>
+ <row>
+ <entry><para>Fiber Channel</para></entry>
+ <entry><para>Supported via Pre-existing SR</para></entry>
+ <entry><para>Supported</para></entry>
+ <entry><para>Supported via Clustered Filesystems</para></entry>
+ </row>
+ <row>
+ <entry><para>Local Disk</para></entry>
+ <entry><para>Supported</para></entry>
+ <entry><para>Supported</para></entry>
+ <entry><para>Supported</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>The use of the Cluster Logical Volume Manager (CLVM) for KVM is not officially supported with &PRODUCT;.</para>
+ <section id="storage-set-small-scale">
+ <title>Small-Scale Setup</title>
+ <para>In a small-scale setup, a single NFS server can function as both primary and secondary storage. The NFS server just needs to export two separate shares, one for primary storage and the other for secondary storage.</para>
+ </section>
+ <section id="storage-set-secondary">
+ <title>Secondary Storage</title>
+ <para>&PRODUCT; is designed to work with any scalable secondary storage system. The only requirement is the secondary storage system supports the NFS protocol.</para>
+ <note>
+ <para>The storage server should be a machine with a large number of disks. The disks should ideally be managed by a hardware RAID controller. Modern hardware RAID controllers support hot plug functionality independent of the operating system so you can replace faulty disks without impacting the running operating system.</para>
+ </note>
+ </section>
+ <section id="storage-set-example-config">
+ <title>Example Configurations</title>
+ <para>In this section we go through a few examples of how to set up storage to work properly on a few types of NFS and iSCSI storage systems.</para>
+ <section id="storage-set-example-config-local-das">
+ <title>Linux NFS on Local Disks and DAS</title>
+ <para>This section describes how to configure an NFS export on a standard Linux installation. The exact commands might vary depending on the operating system version.</para>
+ <orderedlist>
+ <listitem><para>Install the RHEL/CentOS distribution on the storage server.</para></listitem>
+ <listitem><para>If the root volume is more than 2 TB in size, create a smaller boot volume to install RHEL/CentOS. A root volume of 20 GB should be sufficient.</para></listitem>
+ <listitem><para>After the system is installed, create a directory called /export. This can each be a directory in the root partition itself or a mount point for a large disk volume.</para></listitem>
+ <listitem><para>If you have more than 16TB of storage on one host, create multiple EXT3 file systems and multiple NFS exports. Individual EXT3 file systems cannot exceed 16TB.</para></listitem>
+ <listitem>
+ <para>After /export directory is created, run the following command to configure it as an NFS export.</para>
+ <programlisting># echo "/export <CIDR>(rw,async,no_root_squash)" >> /etc/exports</programlisting>
+ <para>Adjust the above command to suit your deployment needs.</para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Limiting NFS export.</emphasis> It is highly recommended that you limit the NFS export to a particular subnet by specifying a subnet mask (e.g.,”192.168.1.0/24”). By allowing access from only within the expected cluster, you avoid having non-pool member mount the storage. The limit you place must include the management network(s) and the storage network(s). If the two are the same network then one CIDR is sufficient. If you have a separate storage network you must provide separate CIDR’s for both or one CIDR that is broad enough to span both.</para>
+ <para>The following is an example with separate CIDRs:</para>
+ <programlisting>/export 192.168.1.0/24(rw,async,no_root_squash) 10.50.1.0/24(rw,async,no_root_squash)</programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Removing the async flag.</emphasis> The async flag improves performance by allowing the NFS server to respond before writes are committed to the disk. Remove the async flag in your mission critical production deployment.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Run the following command to enable NFS service.</para>
+ <programlisting># chkconfig nfs on</programlisting>
+ </listitem>
+ <listitem>
+ <para>Edit the /etc/sysconfig/nfs file and uncomment the following lines.</para>
+ <programlisting>LOCKD_TCPPORT=32803
+LOCKD_UDPPORT=32769
+MOUNTD_PORT=892
+RQUOTAD_PORT=875
+STATD_PORT=662
+STATD_OUTGOING_PORT=2020</programlisting>
+ </listitem>
+ <listitem>
+ <para>Edit the /etc/sysconfig/iptables file and add the following lines at the beginning of the INPUT chain.</para>
+ <programlisting>
+-A INPUT -m state --state NEW -p udp --dport 111 -j ACCEPT
+-A INPUT -m state --state NEW -p tcp --dport 111 -j ACCEPT
+-A INPUT -m state --state NEW -p tcp --dport 2049 -j ACCEPT
+-A INPUT -m state --state NEW -p tcp --dport 32803 -j ACCEPT
+-A INPUT -m state --state NEW -p udp --dport 32769 -j ACCEPT
+-A INPUT -m state --state NEW -p tcp --dport 892 -j ACCEPT
+-A INPUT -m state --state NEW -p udp --dport 892 -j ACCEPT
+-A INPUT -m state --state NEW -p tcp --dport 875 -j ACCEPT
+-A INPUT -m state --state NEW -p udp --dport 875 -j ACCEPT
+-A INPUT -m state --state NEW -p tcp --dport 662 -j ACCEPT
+-A INPUT -m state --state NEW -p udp --dport 662 -j ACCEPT
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>Reboot the server.</para>
+ <para>An NFS share called /export is now set up.</para>
+ </listitem>
+ </orderedlist>
+ <note><para>When copying and pasting a command, be sure the command has pasted as a single line before executing. Some document viewers may introduce unwanted line breaks in copied text.</para></note>
+ </section>
+ <section id="storage-set-example-config-iscsi">
+ <title>Linux NFS on iSCSI</title>
+ <para>Use the following steps to set up a Linux NFS server export on an iSCSI volume. These steps apply to RHEL/CentOS 5 distributions.</para>
+ <orderedlist>
+ <listitem>
+ <para>Install iscsiadm.</para>
+ <programlisting>
+# yum install iscsi-initiator-utils
+# service iscsi start
+# chkconfig --add iscsi
+# chkconfig iscsi on
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>Discover the iSCSI target.</para>
+ <programlisting># iscsiadm -m discovery -t st -p <iSCSI Server IP address>:3260</programlisting>
+ <para>For example:</para>
+ <programlisting># iscsiadm -m discovery -t st -p 172.23.10.240:3260
+ 172.23.10.240:3260,1 iqn.2001-05.com.equallogic:0-8a0906-83bcb3401-16e0002fd0a46f3d-rhel5-test </programlisting>
+ </listitem>
+ <listitem>
+ <para>Log in.</para>
+ <programlisting># iscsiadm -m node -T <Complete Target Name> -l -p <Group IP>:3260</programlisting>
+ <para>For example:</para>
+ <programlisting># iscsiadm -m node -l -T iqn.2001-05.com.equallogic:83bcb3401-16e0002fd0a46f3d-rhel5-test -p 172.23.10.240:3260 </programlisting>
+ </listitem>
+ <listitem>
+ <para>Discover the SCSI disk. For example:</para>
+ <programlisting>
+# iscsiadm -m session -P3 | grep Attached
+Attached scsi disk sdb State: running
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>Format the disk as ext3 and mount the volume.</para>
+ <programlisting># mkfs.ext3 /dev/sdb
+# mkdir -p /export
+# mount /dev/sdb /export
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>Add the disk to /etc/fstab to make sure it gets mounted on boot.</para>
+ <programlisting>/dev/sdb /export ext3 _netdev 0 0</programlisting>
+ </listitem>
+ </orderedlist>
+ <para>Now you can set up /export as an NFS share.</para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Limiting NFS export.</emphasis> In order to avoid data loss, it is highly recommended that you limit the NFS export to a particular subnet by specifying a subnet mask (e.g.,”192.168.1.0/24”). By allowing access from only within the expected cluster, you avoid having non-pool member mount the storage and inadvertently delete all its data. The limit you place must include the management network(s) and the storage network(s). If the two are the same network then one CIDR is sufficient. If you have a separate storage network you must provide separate CIDRs for both or one CIDR that is broad enough to span both. </para>
+ <para>The following is an example with separate CIDRs:</para>
+ <programlisting>/export 192.168.1.0/24(rw,async,no_root_squash) 10.50.1.0/24(rw,async,no_root_squash)</programlisting>
+ </listitem>
+ <listitem><para><emphasis role="bold">Removing the async flag.</emphasis> The async flag improves performance by allowing the NFS server to respond before writes are committed to the disk. Remove the async flag in your mission critical production deployment.</para></listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/storage-tags.xml
----------------------------------------------------------------------
diff --git a/en-US/storage-tags.xml b/en-US/storage-tags.xml
new file mode 100644
index 0000000..39b55a6
--- /dev/null
+++ b/en-US/storage-tags.xml
@@ -0,0 +1,29 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="storage-tags">
+ <title>Storage Tags</title>
+ <para>Storage may be "tagged". A tag is a text string attribute associated with primary storage, a Disk Offering, or a Service Offering. Tags allow administrators to provide additional information about the storage. For example, that is a "SSD" or it is "slow". Tags are not interpreted by &PRODUCT;. They are matched against tags placed on service and disk offerings. &PRODUCT; requires all tags on service and disk offerings to exist on the primary storage before it allocates root or data disks on the primary storage. Service and disk offering tags are used to identify the requirements of the storage that those offerings have. For example, the high end service offering may require "fast" for its root disk volume.</para>
+ <para>The interaction between tags, allocation, and volume copying across clusters and pods can be complex. To simplify the situation, use the same set of tags on the primary storage for all clusters in a pod. Even if different devices are used to present those tags, the set of exposed tags can be the same.</para>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/storage.xml
----------------------------------------------------------------------
diff --git a/en-US/storage.xml b/en-US/storage.xml
new file mode 100644
index 0000000..3ef7324
--- /dev/null
+++ b/en-US/storage.xml
@@ -0,0 +1,31 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="storage">
+ <title>Working With Storage</title>
+ <xi:include href="storage-overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="primary-storage.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="secondary-storage.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="working-with-volumes.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="working-with-snapshots.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/suspend-project.xml
----------------------------------------------------------------------
diff --git a/en-US/suspend-project.xml b/en-US/suspend-project.xml
new file mode 100644
index 0000000..b4f821b
--- /dev/null
+++ b/en-US/suspend-project.xml
@@ -0,0 +1,52 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="suspend-project">
+ <title>Suspending or Deleting a Project</title>
+ <para>When a project is suspended, it retains the resources it owns, but they can no longer be used. No new resources or members can be added to a suspended project.</para>
+ <para>When a project is deleted, its resources are destroyed, and member accounts are removed from the project. The project’s status is shown as Disabled pending final deletion.</para>
+ <para>A project can be suspended or deleted by the project administrator, the domain administrator of the domain the project belongs to or of its parent domain, or the &PRODUCT; root administrator.</para>
+ <orderedlist>
+ <listitem><para>Log in to the &PRODUCT; UI.</para></listitem>
+ <listitem><para>In the left navigation, click Projects.</para></listitem>
+ <listitem><para>In Select View, choose Projects.</para></listitem>
+ <listitem><para>Click the name of the project.</para></listitem>
+ <listitem><para>Click one of the buttons:</para><para>To delete, use <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="./images/delete-button.png" />
+ </imageobject>
+ <textobject>
+ <phrase>deletebutton.png: Removes a project</phrase>
+ </textobject>
+ </inlinemediaobject></para>
+ <para>To suspend, use<inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="./images/suspend-icon.png" />
+ </imageobject>
+ <textobject>
+ <phrase>deletebutton.png: suspends a project</phrase>
+ </textobject>
+ </inlinemediaobject></para></listitem>
+ </orderedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/sys-offering-sysvm.xml
----------------------------------------------------------------------
diff --git a/en-US/sys-offering-sysvm.xml b/en-US/sys-offering-sysvm.xml
new file mode 100644
index 0000000..563dd6f
--- /dev/null
+++ b/en-US/sys-offering-sysvm.xml
@@ -0,0 +1,75 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<section id="sys-offering-sysvm">
+ <title>Changing the Default System Offering for System VMs</title>
+ <para>You can manually change the system offering for a particular System VM. Additionally, as a
+ &PRODUCT; administrator, you can also change the default system offering used for System
+ VMs.</para>
+ <orderedlist>
+ <listitem>
+ <para>Create a new system offering.</para>
+ <para>For more information, see <phrase condition="install"><xref
+ linkend="creating-system-service-offerings"/></phrase>
+ <phrase condition="admin">Creating a New System Service Offering</phrase>. </para>
+ </listitem>
+ <listitem>
+ <para>Back up the database:</para>
+ <programlisting>mysqldump -u root -p cloud | bzip2 > cloud_backup.sql.bz2</programlisting>
+ </listitem>
+ <listitem>
+ <para>Open an MySQL prompt:</para>
+ <programlisting>mysql -u cloud -p cloud</programlisting>
+ </listitem>
+ <listitem>
+ <para>Run the following queries on the cloud database.</para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>In the disk_offering table, identify the original default offering and the new
+ offering you want to use by default. </para>
+ <para>Take a note of the ID of the new offering.</para>
+ <programlisting>select id,name,unique_name,type from disk_offering;</programlisting>
+ </listitem>
+ <listitem>
+ <para>For the original default offering, set the value of unique_name to NULL.</para>
+ <programlisting># update disk_offering set unique_name = NULL where id = 10;</programlisting>
+ <para>Ensure that you use the correct value for the ID.</para>
+ </listitem>
+ <listitem>
+ <para>For the new offering that you want to use by default, set the value of unique_name
+ as follows:</para>
+ <para>For the default Console Proxy VM (CPVM) offering,set unique_name to
+ 'Cloud.com-ConsoleProxy'. For the default Secondary Storage VM (SSVM) offering, set
+ unique_name to 'Cloud.com-SecondaryStorage'. For example:</para>
+ <programlisting>update disk_offering set unique_name = 'Cloud.com-ConsoleProxy' where id = 16;</programlisting>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>Restart &PRODUCT; Management Server. Restarting is required because the default
+ offerings are loaded into the memory at startup.</para>
+ <programlisting>service cloudstack-management restart</programlisting>
+ </listitem>
+ <listitem>
+ <para>Destroy the existing CPVM or SSVM offerings and wait for them to be recreated. The new
+ CPVM or SSVM are configured with the new offering. </para>
+ </listitem>
+ </orderedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/sys-reliability-and-ha.xml
----------------------------------------------------------------------
diff --git a/en-US/sys-reliability-and-ha.xml b/en-US/sys-reliability-and-ha.xml
new file mode 100644
index 0000000..e3c1cd9
--- /dev/null
+++ b/en-US/sys-reliability-and-ha.xml
@@ -0,0 +1,34 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<chapter id="sys-reliability-and-ha">
+ <title>System Reliability and High Availability</title>
+ <xi:include href="ha-management-server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="management-server-lb.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="ha-enabled-vm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="ha-for-hosts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="primary-storage-outage-and-data-loss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="secondary-storage-outage-and-data-loss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="api-throttling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/sysprep-for-windows-server-2003R2.xml
----------------------------------------------------------------------
diff --git a/en-US/sysprep-for-windows-server-2003R2.xml b/en-US/sysprep-for-windows-server-2003R2.xml
new file mode 100644
index 0000000..5f8a389
--- /dev/null
+++ b/en-US/sysprep-for-windows-server-2003R2.xml
@@ -0,0 +1,57 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<section id="sysprep-for-windows-server-2003R2">
+ <title>System Preparation for Windows Server 2003 R2</title>
+ <para>Earlier versions of Windows have a different sysprep tool. Follow these steps for Windows Server 2003 R2.</para>
+ <orderedlist>
+ <listitem><para>Extract the content of \support\tools\deploy.cab on the Windows installation CD into a directory called c:\sysprep on the Windows 2003 R2 VM.</para></listitem>
+ <listitem><para>Run c:\sysprep\setupmgr.exe to create the sysprep.inf file.</para>
+ <orderedlist numeration="loweralpha">
+ <listitem><para>Select Create New to create a new Answer File.</para></listitem>
+ <listitem><para>Enter “Sysprep setup” for the Type of Setup.</para></listitem>
+ <listitem><para>Select the appropriate OS version and edition.</para></listitem>
+ <listitem><para>On the License Agreement screen, select “Yes fully automate the installation”.</para></listitem>
+ <listitem><para>Provide your name and organization.</para></listitem>
+ <listitem><para>Leave display settings at default.</para></listitem>
+ <listitem><para>Set the appropriate time zone.</para></listitem>
+ <listitem><para>Provide your product key.</para></listitem>
+ <listitem><para>Select an appropriate license mode for your deployment</para></listitem>
+ <listitem><para>Select “Automatically generate computer name”.</para></listitem>
+ <listitem><para>Type a default administrator password. If you enable the password reset feature, the users will not actually use this password. This password will be reset by the instance manager after the guest boots up.</para></listitem>
+ <listitem><para>Leave Network Components at “Typical Settings”.</para></listitem>
+ <listitem><para>Select the “WORKGROUP” option.</para></listitem>
+ <listitem><para>Leave Telephony options at default.</para></listitem>
+ <listitem><para>Select appropriate Regional Settings.</para></listitem>
+ <listitem><para>Select appropriate language settings.</para></listitem>
+ <listitem><para>Do not install printers.</para></listitem>
+ <listitem><para>Do not specify “Run Once commands”.</para></listitem>
+ <listitem><para>You need not specify an identification string.</para></listitem>
+ <listitem><para>Save the Answer File as c:\sysprep\sysprep.inf.</para></listitem>
+
+ </orderedlist>
+ </listitem>
+ <listitem><para>Run the following command to sysprep the image:</para><programlisting>c:\sysprep\sysprep.exe -reseal -mini -activated</programlisting>
+ <para>After this step the machine will automatically shut down</para></listitem>
+ </orderedlist>
+ </section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/sysprep-windows-server-2008R2.xml
----------------------------------------------------------------------
diff --git a/en-US/sysprep-windows-server-2008R2.xml b/en-US/sysprep-windows-server-2008R2.xml
new file mode 100644
index 0000000..49e7477
--- /dev/null
+++ b/en-US/sysprep-windows-server-2008R2.xml
@@ -0,0 +1,71 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<section id="sysprep-windows-server-2008R2">
+ <title>System Preparation for Windows Server 2008 R2</title>
+ <para>For Windows 2008 R2, you run Windows System Image Manager to create a custom sysprep response XML file. Windows System Image Manager is installed as part of the Windows Automated Installation Kit (AIK). Windows AIK can be downloaded from <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=9085">Microsoft Download Center</ulink>.</para>
+ <para>Use the following steps to run sysprep for Windows 2008 R2:</para><note><para>The steps outlined here are derived from the excellent guide by Charity Shelbourne, originally published at <ulink url="http://blogs.technet.com/askcore/archive/2008/10/31/automating-the-oobe-process-during-windows-server-2008-sysprep-mini-setup.aspx">Windows Server 2008 Sysprep Mini-Setup.</ulink></para>
+ </note>
+ <para></para>
+ <orderedlist>
+ <listitem><para>Download and install the Windows AIK</para><note><para>Windows AIK should not be installed on the Windows 2008 R2 VM you just created. Windows AIK should not be part of the template you create. It is only used to create the sysprep answer file.</para></note></listitem>
+ <listitem><para>Copy the install.wim file in the \sources directory of the Windows 2008 R2 installation DVD to the hard disk. This is a very large file and may take a long time to copy. Windows AIK requires the WIM file to be writable.</para></listitem>
+ <listitem><para>Start the Windows System Image Manager, which is part of the Windows AIK.</para></listitem>
+ <listitem><para>In the Windows Image pane, right click the Select a Windows image or catalog file option to
+ load the install.wim file you just copied.</para></listitem>
+ <listitem><para>Select the Windows 2008 R2 Edition.</para><para>You may be prompted with a warning that the catalog file cannot be opened. Click Yes to create a new catalog file.</para></listitem>
+ <listitem><para>In the Answer File pane, right click to create a new answer file.</para></listitem>
+ <listitem><para>Generate the answer file from the Windows System Image Manager using the following steps:</para>
+ <orderedlist numeration="loweralpha">
+ <listitem><para>The first page you need to automate is the Language and Country or Region Selection page. To automate this, expand Components in your Windows Image pane, right-click and add the Microsoft-Windows-International-Core setting to Pass 7 oobeSystem. In your Answer File pane, configure the InputLocale, SystemLocale, UILanguage, and UserLocale with the appropriate settings for your language and country or region. Should you have a question about any of these settings, you can right-click on the specific setting and select Help. This will open the appropriate CHM help file with more information, including examples on the setting you are attempting to configure.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/sysmanager.png" />
+ </imageobject>
+ <textobject><phrase>sysmanager.png: System Image Manager</phrase></textobject>
+ </mediaobject></listitem>
+ <listitem><para>You need to automate the Software License Terms Selection page, otherwise known as the End-User License Agreement (EULA). To do this, expand the Microsoft-Windows-Shell-Setup component. High-light the OOBE setting, and add the setting to the Pass 7 oobeSystem. In Settings, set HideEULAPage true.</para> <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/software-license.png" />
+ </imageobject>
+ <textobject><phrase>software-license.png: Depicts hiding the EULA page.</phrase></textobject>
+ </mediaobject></listitem>
+ <listitem><para>Make sure the license key is properly set. If you use MAK key, you can just enter the MAK key on the Windows 2008 R2 VM. You need not input the MAK into the Windows System Image Manager. If you use KMS host for activation you need not enter the Product Key. Details of Windows Volume Activation can be found at <ulink url="http://technet.microsoft.com/en-us/library/bb892849.aspx"></ulink></para></listitem>
+ <listitem><para>You need to automate is the Change Administrator Password page. Expand the Microsoft-Windows-Shell-Setup component (if it is not still expanded), expand UserAccounts, right-click on AdministratorPassword, and add the setting to the Pass 7 oobeSystem configuration pass of your answer file. Under Settings, specify a password next to Value.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/change-admin-password.png" />
+ </imageobject>
+ <textobject><phrase>change-admin-password.png: Depicts changing the administrator password</phrase></textobject>
+ </mediaobject><para>You may read the AIK documentation and set many more options that suit your deployment. The steps above are the minimum needed to make Windows unattended setup work.</para></listitem></orderedlist></listitem>
+ <listitem><para>Save the answer file as unattend.xml. You can ignore the warning messages that appear in the validation window.</para></listitem>
+ <listitem><para>Copy the unattend.xml file into the c:\windows\system32\sysprep directory of the Windows 2008 R2 Virtual Machine</para></listitem>
+ <listitem><para>Once you place the unattend.xml file in c:\windows\system32\sysprep directory, you run the sysprep tool as follows:</para>
+ <programlisting>cd c:\Windows\System32\sysprep
+sysprep.exe /oobe /generalize /shutdown
+</programlisting><para>The Windows 2008 R2 VM will automatically shut down after sysprep is complete.</para></listitem>
+
+
+ </orderedlist>
+
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/system-reserved-ip-addresses.xml
----------------------------------------------------------------------
diff --git a/en-US/system-reserved-ip-addresses.xml b/en-US/system-reserved-ip-addresses.xml
new file mode 100644
index 0000000..7ae9fa8
--- /dev/null
+++ b/en-US/system-reserved-ip-addresses.xml
@@ -0,0 +1,41 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<section id="system-reserved-ip-addresses">
+ <title>System Reserved IP Addresses</title>
+ <para>In each zone, you need to configure a range of reserved IP addresses for the management network. This network carries communication between the &PRODUCT; Management Server and various system VMs, such as Secondary Storage VMs, Console Proxy VMs, and DHCP. </para>
+ <para>The reserved IP addresses must be unique across the cloud. You cannot, for example, have a host in one zone which has the same private IP address as a host in another zone.</para>
+ <para>The hosts in a pod are assigned private IP addresses. These are typically RFC1918 addresses. The Console Proxy and Secondary Storage system VMs are also allocated private IP addresses in the CIDR of the pod that they are created in.</para>
+ <para>Make sure computing servers and Management Servers use IP addresses outside of the System Reserved IP range. For example, suppose the System Reserved IP range starts at 192.168.154.2 and ends at 192.168.154.7. &PRODUCT; can use .2 to .7 for System VMs. This leaves the rest of the pod CIDR, from .8 to .254, for the Management Server and hypervisor hosts.</para>
+ <para><emphasis role="bold">In all zones:</emphasis></para>
+ <para>Provide private IPs for the system in each pod and provision them in &PRODUCT;.</para>
+ <para>For KVM and XenServer, the recommended number of private IPs per pod is one per host. If you expect a pod to grow, add enough private IPs now to accommodate the growth.</para>
+ <para><emphasis role="bold">In a zone that uses advanced networking:</emphasis></para>
+ <para>For zones with advanced networking, we recommend provisioning enough private IPs for your total number of customers, plus enough for the required &PRODUCT; System VMs. Typically, about 10 additional IPs are required for the System VMs. For more information about System VMs, see Working with System Virtual Machines in the Administrator's Guide.</para>
+ <para>When advanced networking is being used, the number of private IP addresses available in each pod varies depending on which hypervisor is running on the nodes in that pod. Citrix XenServer and KVM use link-local addresses, which in theory provide more than 65,000 private IP addresses within the address block. As the pod grows over time, this should be more than enough for any reasonable number of hosts as well as IP addresses for guest virtual routers. VMWare ESXi, by contrast uses any administrator-specified subnetting scheme, and the typical administrator provides only 255 IPs per pod. Since these are shared by physical machines, the guest virtual router, and other entities, it is possible to run out of private IPs when scaling up a pod whose nodes are running ESXi.</para>
+ <para>To ensure adequate headroom to scale private IP space in an ESXi pod that uses advanced networking, use one or both of the following techniques:</para>
+ <itemizedlist>
+ <listitem><para>Specify a larger CIDR block for the subnet. A subnet mask with a /20 suffix will provide more than 4,000 IP addresses.</para></listitem>
+ <listitem><para>Create multiple pods, each with its own subnet. For example, if you create 10 pods and each pod has 255 IPs, this will provide 2,550 IP addresses.</para></listitem>
+ </itemizedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/system-service-offerings.xml
----------------------------------------------------------------------
diff --git a/en-US/system-service-offerings.xml b/en-US/system-service-offerings.xml
new file mode 100644
index 0000000..84d5f7a
--- /dev/null
+++ b/en-US/system-service-offerings.xml
@@ -0,0 +1,30 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="system-service-offerings">
+ <title>System Service Offerings</title>
+ <para>System service offerings provide a choice of CPU speed, number of CPUs, tags, and RAM size, just as other service offerings do. But rather than being used for virtual machine instances and exposed to users, system service offerings are used to change the default properties of virtual routers, console proxies, and other system VMs. System service offerings are visible only to the &PRODUCT; root administrator. &PRODUCT; provides default system service offerings. The &PRODUCT; root administrator can create additional custom system service offerings.</para>
+ <para>When &PRODUCT; creates a virtual router for a guest network, it uses default settings which are defined in the system service offering associated with the network offering. You can upgrade the capabilities of the virtual router by applying a new network offering that contains a different system service offering. All virtual routers in that network will begin using the settings from the new service offering.</para>
+ <xi:include href="creating-system-service-offerings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/system-vm-template.xml
----------------------------------------------------------------------
diff --git a/en-US/system-vm-template.xml b/en-US/system-vm-template.xml
new file mode 100644
index 0000000..a9477f3
--- /dev/null
+++ b/en-US/system-vm-template.xml
@@ -0,0 +1,37 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="system-vm-template">
+ <title>The System VM Template</title>
+ <para>The System VMs come from a single template. The System VM has the following characteristics:</para>
+ <itemizedlist>
+ <listitem><para>Debian 6.0 ("Squeeze"), 2.6.32 kernel with the latest security patches from the Debian security APT repository</para></listitem>
+ <listitem><para>Has a minimal set of packages installed thereby reducing the attack surface</para></listitem>
+ <listitem><para>32-bit for enhanced performance on Xen/VMWare</para></listitem>
+ <listitem><para>pvops kernel with Xen PV drivers, KVM virtio drivers, and VMware tools for optimum performance on all hypervisors</para></listitem>
+ <listitem><para>Xen tools inclusion allows performance monitoring</para></listitem>
+ <listitem><para>Latest versions of HAProxy, iptables, IPsec, and Apache from debian repository ensures improved security and speed</para></listitem>
+ <listitem><para>Latest version of JRE from Sun/Oracle ensures improved security and speed</para></listitem>
+ </itemizedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/tagging-resources.xml
----------------------------------------------------------------------
diff --git a/en-US/tagging-resources.xml b/en-US/tagging-resources.xml
new file mode 100644
index 0000000..31ee382
--- /dev/null
+++ b/en-US/tagging-resources.xml
@@ -0,0 +1,69 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///C:/Program%20Files%20(x86)/Publican/DocBook_DTD/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="tagging-resources">
+ <title>Using Tags to Organize Resources in the Cloud</title>
+ <para>A tag is a key-value pair that stores metadata about a resource in the cloud. Tags are
+ useful for categorizing resources. For example, you can tag a user VM with a
+ value that indicates the user's city of residence. In this case, the key would
+ be "city" and the value might be "Toronto" or "Tokyo." You can then request
+ &PRODUCT; to find all resources that have a given tag; for example, VMs for
+ users in a given city.</para>
+ <para>You can tag a user virtual machine, volume, snapshot, guest network, template,
+ ISO, firewall rule, port forwarding rule, public IP address, security group,
+ load balancer rule, project, VPC, network ACL, or static route. You can not tag
+ a remote access VPN.</para>
+ <para>You can work with tags through the UI or through the API commands createTags,
+ deleteTags, and listTags. You can define multiple tags for each resource. There
+ is no limit on the number of tags you can define. Each tag can be up to 255
+ characters long. Users can define tags on the resources they own, and
+ administrators can define tags on any resources in the cloud.</para>
+ <para>An optional input parameter, "tags," exists on many of the list* API commands.
+ The following example shows how to use this new parameter to find all the volumes
+ having tag region=canada OR tag city=Toronto:</para>
+ <programlisting>command=listVolumes
+ &listAll=true
+ &tags[0].key=region
+ &tags[0].value=canada
+ &tags[1].key=city
+ &tags[1].value=Toronto</programlisting>
+ <para>The following API commands have the "tags" input parameter:</para>
+ <itemizedlist>
+ <listitem><para>listVirtualMachines</para></listitem>
+ <listitem><para>listVolumes</para></listitem>
+ <listitem><para>listSnapshots</para></listitem>
+ <listitem><para>listNetworks</para></listitem>
+ <listitem><para>listTemplates</para></listitem>
+ <listitem><para>listIsos</para></listitem>
+ <listitem><para>listFirewallRules</para></listitem>
+ <listitem><para>listPortForwardingRules</para></listitem>
+ <listitem><para>listPublicIpAddresses</para></listitem>
+ <listitem><para>listSecurityGroups</para></listitem>
+ <listitem><para>listLoadBalancerRules</para></listitem>
+ <listitem><para>listProjects</para></listitem>
+ <listitem><para>listVPCs</para></listitem>
+ <listitem><para>listNetworkACLs</para></listitem>
+ <listitem><para>listStaticRoutes</para></listitem>
+ </itemizedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/template-iso-snapshot-usage-record-format.xml
----------------------------------------------------------------------
diff --git a/en-US/template-iso-snapshot-usage-record-format.xml b/en-US/template-iso-snapshot-usage-record-format.xml
new file mode 100644
index 0000000..3f34f36
--- /dev/null
+++ b/en-US/template-iso-snapshot-usage-record-format.xml
@@ -0,0 +1,42 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="template-iso-snapshot-usage-record-format">
+ <title>Template, ISO, and Snapshot Usage Record Format</title>
+ <itemizedlist>
+ <listitem><para>account – name of the account</para></listitem>
+ <listitem><para>accountid – ID of the account</para></listitem>
+ <listitem><para>domainid – ID of the domain in which this account resides</para></listitem>
+ <listitem><para>zoneid – Zone where the usage occurred</para></listitem>
+ <listitem><para>description – A string describing what the usage record is tracking</para></listitem>
+ <listitem><para>usage – String representation of the usage, including the units of usage (e.g. 'Hrs' for hours)</para></listitem>
+ <listitem><para>usagetype – A number representing the usage type (see Usage Types)</para></listitem>
+ <listitem><para>rawusage – A number representing the actual usage in hours</para></listitem>
+ <listitem><para>usageid – The ID of the the template, ISO, or snapshot</para></listitem>
+ <listitem><para>offeringid – The ID of the disk offering</para></listitem>
+ <listitem><para>templateid – – Included only for templates (usage type 7). Source template ID.</para></listitem>
+ <listitem><para>size – Size of the template, ISO, or snapshot</para></listitem>
+ <listitem><para>startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record</para></listitem>
+ </itemizedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/templates.xml
----------------------------------------------------------------------
diff --git a/en-US/templates.xml b/en-US/templates.xml
new file mode 100644
index 0000000..faecf1b
--- /dev/null
+++ b/en-US/templates.xml
@@ -0,0 +1,29 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="templates">
+ <title>Templates</title>
+ <xi:include href="working-with-iso.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="working-with-templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/third-party-ui-plugin.xml
----------------------------------------------------------------------
diff --git a/en-US/third-party-ui-plugin.xml b/en-US/third-party-ui-plugin.xml
new file mode 100644
index 0000000..297fdaa
--- /dev/null
+++ b/en-US/third-party-ui-plugin.xml
@@ -0,0 +1,364 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///C:/Program%20Files%20(x86)/Publican/DocBook_DTD/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <chapter id="third-party-ui-plugin">
+ <!-- CLOUDSTACK-883 -->
+ <title>Third-Party UI Plugin Framework</title>
+ <para>Using the new third-party plugin framework, you can write and install extensions to
+ &PRODUCT;. 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 &PRODUCT;’s installed code at any time after &PRODUCT; installation. The new plugin
+ appears only when it is enabled by the cloud administrator.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/plugin_intro.jpg"/>
+ </imageobject>
+ <textobject>
+ <phrase>plugin_intro.jpg: New plugin button in product navbar</phrase>
+ </textobject>
+ </mediaobject>
+ <para>The left navigation bar of the &PRODUCT; UI has a new Plugins button to help you work with UI plugins.</para>
+ <section id="plugin-howto-overview">
+ <title>How to Write a Plugin: Overview</title>
+ <para>The basic procedure for writing a plugin is:</para>
+ <orderedlist>
+ <listitem>
+ <para>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.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/plugin1.jpg"/>
+ </imageobject>
+ <textobject>
+ <phrase>plugin1.jpg: Write the plugin code</phrase>
+ </textobject>
+ </mediaobject>
+ <para>All UI plugins have the following set of files:</para>
+ <programlisting>+-- 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
+ </programlisting>
+ <para>The same files must also be present at /tomcat/webapps/client/plugins.</para>
+ </listitem>
+ <listitem>
+ <para>The &PRODUCT; administrator adds the folder containing your plugin code under the
+ &PRODUCT; PLUGINS folder.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/plugin2.jpg"/>
+ </imageobject>
+ <textobject>
+ <phrase>plugin2.jpg: The plugin code is placed in the PLUGINS folder</phrase>
+ </textobject>
+ </mediaobject>
+ </listitem>
+ <listitem>
+ <para>The administrator also adds the name of your plugin to the plugin.js file in the
+ PLUGINS folder.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/plugin3.jpg"/>
+ </imageobject>
+ <textobject>
+ <phrase>plugin3.jpg: The plugin name is added to plugin.js in the PLUGINS
+ folder</phrase>
+ </textobject>
+ </mediaobject>
+ </listitem>
+ <listitem>
+ <para>The next time the user refreshes the UI in the browser, your plugin will appear in
+ the left navigation bar.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/plugin4.jpg"/>
+ </imageobject>
+ <textobject>
+ <phrase>plugin4.jpg: The plugin appears in the UI</phrase>
+ </textobject>
+ </mediaobject>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="plugin-howto-details">
+ <title>How to Write a Plugin: Implementation Details</title>
+ <para>This section requires an understanding of JavaScript and the &PRODUCT; API. You don't
+ need knowledge of specific frameworks for this tutorial (jQuery, etc.), since the
+ &PRODUCT; UI handles the front-end rendering for you.</para>
+ <para>There is much more to the &PRODUCT; 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.</para>
+ <orderedlist>
+ <listitem>
+ <para><emphasis role="bold">Create the directory to hold your plugin.</emphasis></para>
+ <para>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.</para>
+ <para>In this example, the plugin is named csMyFirstPlugin.</para>
+ <programlisting>$ 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
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Change to your new plugin directory.</emphasis></para>
+ <programlisting>$ cd csMyFirstPlugin
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Set up the listing.</emphasis></para>
+ <para>Add the file config.js, using your favorite editor.</para>
+ <programlisting>$ vi config.js</programlisting>
+ <para>Add the following content to config.js. This information will be displayed on the
+ plugin listing page in the UI:</para>
+ <programlisting>(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));
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Add a new main section.</emphasis></para>
+ <para>Add the file csMyFirstPlugin.js, using your favorite editor.</para>
+ <programlisting>$ vi csMyFirstPlugin.js</programlisting>
+ <para>Add the following content to csMyFirstPlugin.js:</para>
+ <programlisting>(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));
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Register the plugin.</emphasis></para>
+ <para>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:</para>
+ <programlisting>$ cd cloudstack/ui/plugins
+$ vi plugins.js
+ </programlisting>
+ <para>Now add the following to plugins.js:</para>
+ <programlisting>(function($, cloudStack) {
+ cloudStack.plugins = [
+ 'csMyFirstPlugin'
+ ];
+}(jQuery, cloudStack));
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Check the plugin in the UI.</emphasis></para>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Make the plugin do something.</emphasis></para>
+ <para>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).</para>
+ <para>First, open your plugin's JavaScript source file in your favorite editor:</para>
+ <programlisting>$ cd csMyFirstPlugin
+$ vi csMyFirstPlugin.js
+ </programlisting>
+ <para>Add the following code in csMyFirstPlugin.js:</para>
+ <programlisting>(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));
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Test the plugin.</emphasis></para>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Add an action button.</emphasis></para>
+ <para>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.</para>
+ <programlisting>$ vi csMyFirstPlugin.js
+ </programlisting>
+ <para>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):</para>
+ <programlisting>...
+ 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 &PRODUCT; 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 &PRODUCT;
+ notification: {
+ poll: plugin.ui.pollAsyncJob
+ }
+ }
+ },
+
+ dataProvider: function(args) {
+ ...
+...
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Add the thumbnail icon.</emphasis></para>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Add the stylesheet.</emphasis></para>
+ <para>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.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ </chapter>