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/20 18:15:40 UTC
[1/3] Create RTD docs
Repository: cloudstack-docs
Updated Branches:
refs/heads/master bcf67dd6f -> 5fddad01e
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/networking/troubleshoot_internet_traffic.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/troubleshoot_internet_traffic.rst b/rtd/source/networking/troubleshoot_internet_traffic.rst
new file mode 100644
index 0000000..b118e38
--- /dev/null
+++ b/rtd/source/networking/troubleshoot_internet_traffic.rst
@@ -0,0 +1,216 @@
+Troubleshooting Internet Traffic
+================================
+
+Below are a few troubleshooting steps to check whats going wrong with your
+network...
+
+Trouble Shooting Steps
+----------------------
+
+#. The switches have to be configured correctly to pass VLAN traffic. You can
+ verify if VLAN traffic is working by bringing up a tagged interface on the
+ hosts and pinging between them as below...
+
+ On *host1 (kvm1)*
+
+ ::
+
+ kvm1 ~$ vconfig add eth0 64
+ kvm1 ~$ ifconfig eth0.64 1.2.3.4 netmask 255.255.255.0 up
+ kvm1 ~$ ping 1.2.3.5
+
+ On *host2 (kvm2)*
+
+ ::
+
+ kvm2 ~$ vconfig add eth0 64
+ kvm2 ~$ ifconfig eth0.64 1.2.3.5 netmask 255.255.255.0 up
+ kvm2 ~$ ping 1.2.3.4
+
+ If the pings dont work, run *tcpdump(8)* all over the place to check
+ who is gobbling up the packets. Ultimately, if the switches are not
+ configured correctly, CloudStack networking wont work so fix the
+ physical networking issues before you proceed to the next steps
+
+#. Ensure `Traffic Labels <http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.2.0/html/Installation_Guide/about-physical-networks.html>`_ are set for the Zone.
+
+ Traffic labels need to be set for all hypervisors including
+ XenServer, KVM and VMware types. You can configure traffic labels when
+ you creating a new zone from the *Add Zone Wizard*.
+
+ .. image:: ../_static/images/networking-zone-traffic-labels.png
+
+ On an existing zone, you can modify the traffic labels by going to
+ *Infrastructure, Zones, Physical Network* tab.
+
+ .. image:: ../_static/images/networking-infra-traffic-labels.png
+
+ List labels using *CloudMonkey*
+
+ ::
+
+ acs-manager ~$ cloudmonkey list traffictypes physicalnetworkid=41cb7ff6-8eb2-4630-b577-1da25e0e1145
+ count = 4
+ traffictype:
+ id = cd0915fe-a660-4a82-9df7-34aebf90003e
+ kvmnetworklabel = cloudbr0
+ physicalnetworkid = 41cb7ff6-8eb2-4630-b577-1da25e0e1145
+ traffictype = Guest
+ xennetworklabel = MGMT
+ ========================================================
+ id = f5524b8f-6605-41e4-a982-81a356b2a196
+ kvmnetworklabel = cloudbr0
+ physicalnetworkid = 41cb7ff6-8eb2-4630-b577-1da25e0e1145
+ traffictype = Management
+ xennetworklabel = MGMT
+ ========================================================
+ id = 266bad0e-7b68-4242-b3ad-f59739346cfd
+ kvmnetworklabel = cloudbr0
+ physicalnetworkid = 41cb7ff6-8eb2-4630-b577-1da25e0e1145
+ traffictype = Public
+ xennetworklabel = MGMT
+ ========================================================
+ id = a2baad4f-7ce7-45a8-9caf-a0b9240adf04
+ kvmnetworklabel = cloudbr0
+ physicalnetworkid = 41cb7ff6-8eb2-4630-b577-1da25e0e1145
+ traffictype = Storage
+ xennetworklabel = MGMT
+ =========================================================
+
+#. KVM traffic labels require to be named as *"cloudbr0"*, *"cloudbr2"*,
+ *"cloudbrN"* etc and the corresponding bridge must exist on the KVM
+ hosts. If you create labels/bridges with any other names, CloudStack
+ (atleast earlier versions did) seems to ignore them. CloudStack does not
+ create the physical bridges on the KVM hosts, you need to create them
+ **before** before adding the host to Cloudstack.
+
+ ::
+
+ kvm1 ~$ ifconfig cloudbr0
+ cloudbr0 Link encap:Ethernet HWaddr 00:0C:29:EF:7D:78
+ inet addr:192.168.44.22 Bcast:192.168.44.255 Mask:255.255.255.0
+ inet6 addr: fe80::20c:29ff:feef:7d78/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:92435 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:50596 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:0
+ RX bytes:94985932 (90.5 MiB) TX bytes:61635793 (58.7 MiB)
+
+#. The Virtual Router, SSVM, CPVM *public* interface would be bridged to
+ a physical interface on the host. In the example below, *cloudbr0* is
+ the public interface and CloudStack has correctly created the virtual
+ interfaces bridge. This virtual interface to physical interface mapping
+ is done automatically by CloudStack using the traffic label settings for
+ the Zone. If you have provided correct settings and still dont have a
+ working working Internet, check the switching layer before you debug any
+ further. You can verify traffic using tcpdump on the virtual, physical
+ and bridge interfaces.
+
+ ::
+
+ kvm-host1 ~$ brctl show
+ bridge name bridge id STP enabled interfaces
+ breth0-64 8000.000c29ef7d78 no eth0.64
+ vnet2
+ cloud0 8000.fe00a9fe0219 no vnet0
+ cloudbr0 8000.000c29ef7d78 no eth0
+ vnet1
+ vnet3
+ virbr0 8000.5254008e321a yes virbr0-nic
+
+ ::
+
+ xenserver1 ~$ brctl show
+ bridge name bridge id STP enabled interfaces
+ xapi0 0000.e2b76d0a1149 no vif1.0
+ xenbr0 0000.000c299b54dc no eth0
+ xapi1
+ vif1.1
+ vif1.2
+
+#. Pre-create labels on the XenServer Hosts. Similar to KVM bridge
+ setup, traffic labels must also be pre-created on the XenServer hosts
+ before adding them to CloudStack.
+
+ ::
+
+ xenserver1 ~$ xe network-list
+ uuid ( RO) : aaa-bbb-ccc-ddd
+ name-label ( RW): MGMT
+ name-description ( RW):
+ bridge ( RO): xenbr0
+
+
+#. The Internet would be accessible from both the SSVM and CPVM
+ instances by default. Their public IPs will also be directly pingable
+ from the Internet. Please note that these test would work only if your
+ switches and traffic labels are configured correctly for your
+ environment. If your SSVM/CPVM cant reach the Internet, its very
+ unlikely that the Virtual Router (VR) can also the reach the Internet
+ suggesting that its either a switching issue or incorrectly assigned
+ traffic labels. Fix the SSVM/CPVM issues before you debug VR issues.
+
+ ::
+
+ root@s-1-VM:~# ping -c 3 google.com
+ PING google.com (74.125.236.164): 56 data bytes
+ 64 bytes from 74.125.236.164: icmp_seq=0 ttl=55 time=26.932 ms
+ 64 bytes from 74.125.236.164: icmp_seq=1 ttl=55 time=29.156 ms
+ 64 bytes from 74.125.236.164: icmp_seq=2 ttl=55 time=25.000 ms
+ --- google.com ping statistics ---
+ 3 packets transmitted, 3 packets received, 0% packet loss
+ round-trip min/avg/max/stddev = 25.000/27.029/29.156/1.698 ms
+
+ ::
+
+ root@v-2-VM:~# ping -c 3 google.com
+ PING google.com (74.125.236.164): 56 data bytes
+ 64 bytes from 74.125.236.164: icmp_seq=0 ttl=55 time=32.125 ms
+ 64 bytes from 74.125.236.164: icmp_seq=1 ttl=55 time=26.324 ms
+ 64 bytes from 74.125.236.164: icmp_seq=2 ttl=55 time=37.001 ms
+ --- google.com ping statistics ---
+ 3 packets transmitted, 3 packets received, 0% packet loss
+ round-trip min/avg/max/stddev = 26.324/31.817/37.001/4.364 ms
+
+
+#. The Virtual Router (VR) should also be able to reach the Internet
+ without having any Egress rules. The Egress rules only control forwarded
+ traffic and not traffic that originates on the VR itself.
+
+ ::
+
+ root@r-4-VM:~# ping -c 3 google.com
+ PING google.com (74.125.236.164): 56 data bytes
+ 64 bytes from 74.125.236.164: icmp_seq=0 ttl=55 time=28.098 ms
+ 64 bytes from 74.125.236.164: icmp_seq=1 ttl=55 time=34.785 ms
+ 64 bytes from 74.125.236.164: icmp_seq=2 ttl=55 time=69.179 ms
+ --- google.com ping statistics ---
+ 3 packets transmitted, 3 packets received, 0% packet loss
+ round-trip min/avg/max/stddev = 28.098/44.021/69.179/17.998 ms
+
+#. However, the Virtual Router's (VR) Source NAT Public IP address
+ **WONT** be reachable until appropriate Ingress rules are
+ in place. You can add *Ingress* rules under *Network, Guest Network, IP
+ Address, Firewall* setting page.
+
+ .. image:: ../_static/images/networking-ingress-rule.png
+
+#. The VM Instances by default wont be able to access the Internet. Add
+ Egress rules to permit traffic.
+
+ .. image:: ../_static/images/networking-egress-rule.png
+
+#. Some users have reported that flushing IPTables rules (or changing
+ routes) on the SSVM, CPVM or the Virtual Router makes the Internet work.
+ This is not expected behaviour and suggests that your networking
+ settings are incorrect. No IPtables/route changes are required on the
+ SSVM, CPVM or the VR. Go back and double check all your settings.
+
+
+In a vast majority of the cases, the problem has turned out to be at the
+switching layer where the L3 switches were configured incorrectly.
+
+This section was contibuted by Shanker Balan and was originally published
+at [here]_
+
+.. [here] http://shankerbalan.net/blog/internet-not-working-on-cloudstack-vms/
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/networking/vxlan.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/vxlan.rst b/rtd/source/networking/vxlan.rst
new file mode 100644
index 0000000..24520a3
--- /dev/null
+++ b/rtd/source/networking/vxlan.rst
@@ -0,0 +1,376 @@
+The VXLAN Plugin
+================
+
+System Requirements for VXLAN
+-----------------------------
+
+In PRODUCT 4.X.0, this plugin only supports the KVM hypervisor with the
+standard linux bridge.
+
+The following table lists the requirements for the hypervisor.
+
++----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+
+| Item | Requirement | Note |
++================+===============================================+================================================================================================================+
+| Hypervisor | KVM | OvsVifDriver is not supported by this plugin in PRODUCT 4.X, use BridgeVifDriver (default). |
++----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+
+| Linux kernel | version >= 3.7, VXLAN kernel module enabled | It is recommended to use kernel >=3.9, since Linux kernel categorizes the VXLAN driver as experimental <3.9. |
++----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+
+| iproute2 | matches kernel version | |
++----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+
+
+Table: Hypervisor Requirement for VXLAN
+
+Linux Distributions that meet the requirements
+----------------------------------------------
+
+The following table lists distributions which meet requirements.
+
++----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+
+| Distribution | Release Version | Kernel Version (Date confirmed) | Note |
++================+===================+===========================================+================================================================+
+| Ubuntu | 13.04 | 3.8.0 (2013/07/23) | |
++----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+
+| Fedora | >= 17 | 3.9.10 (2013/07/23) | Latest kernel packages are available in "update" repository. |
++----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+
+| CentOS | >= 6.5 | 2.6.32-431.3.1.el6.x86\_64 (2014/01/21) | |
++----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+
+
+Table: List of Linux distributions which meet the hypervisor
+requirements
+
+Check the capability of your system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To check the capability of your system, execute the following commands.
+
+::
+
+ $ sudo modprobe vxlan && echo $?
+ # Confirm the output is "0".
+ # If it's non-0 value or error message, your kernel doesn't have VXLAN kernel module.
+
+ $ ip link add type vxlan help
+ # Confirm the output is usage of the command and that it's for VXLAN.
+ # If it's not, your iproute2 utility doesn't support VXLAN.
+
+
+Advanced: Build kernel and iproute2
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Even if your system doesn't support VXLAN, you can compile the kernel
+and iproute2 by yourself. The following procedure is an example for
+CentOS 6.4.
+
+Build kernel
+^^^^^^^^^^^^
+
+::
+
+ $ sudo yum groupinstall "Development Tools"
+ $ sudo yum install ncurses-devel hmaccalc zlib-devel binutils-devel elfutils-libelf-devel bc
+
+ $ KERNEL_VERSION=3.10.4
+ # Declare the kernel version you want to build.
+
+ $ wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-${KERNEL_VERSION}.tar.xz
+ $ tar xvf linux-${KERNEL_VERSION}.tar.xz
+ $ cd linux-${KERNEL_VERSION}
+ $ cp /boot/config-`uname -r` .config
+ $ make oldconfig
+ # You may keep hitting enter and choose the default.
+
+ $ make menuconfig
+ # Dig into "Device Drivers" -> "Network device support",
+ # then select "Virtual eXtensible Local Area Network (VXLAN)" and hit space.
+ # Make sure it indicates "<M>" (build as module), then Save and Exit.
+
+ # You may also want to check "IPv4 NAT" and its child nodes in "IP: Netfilter Configuration"
+ # and "IPv6 NAT" and its child nodes in "IPv6: Netfilter Configuration".
+ # In 3.10.4, you can find the options in
+ # "Networking support" -> "Networking options"
+ # -> "Network packet filtering framework (Netfilter)".
+
+ $ make # -j N
+ # You may use -j N option to make the build process parallel and faster,
+ # generally N = 1 + (cores your machine have).
+
+ $ sudo make modules_install
+ $ sudo make install
+ # You would get an error like "ERROR: modinfo: could not find module XXXX" here.
+ # This happens mainly due to config structure changes between kernel versions.
+ # You can ignore this error, until you find you need the kernel module.
+ # If you feel uneasy, you can go back to make menuconfig,
+ # find module XXXX by using '/' key, enable the module, build and install the kernel again.
+
+ $ sudo vi /etc/grub.conf
+ # Make sure the new kernel isn't set as the default and the timeout is long enough,
+ # so you can select the new kernel during boot process.
+ # It's not a good idea to set the new kernel as the default until you confirm the kernel works fine.
+
+ $ sudo reboot
+ # Select the new kernel during the boot process.
+
+
+Build iproute2
+^^^^^^^^^^^^^^
+
+::
+
+ $ sudo yum install db4-devel
+
+ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git
+ $ cd iproute2
+ $ git tag
+ # Find the version that matches the kernel.
+ # If you built kernel 3.10.4 as above, it would be v3.10.0.
+
+ $ git checkout v3.10.0
+ $ ./configure
+ $ make # -j N
+ $ sudo make install
+
+
+.. note:: Please use rebuild kernel and tools at your own risk.
+
+Configure PRODUCT to use VXLAN Plugin
+-------------------------------------
+
+Configure hypervisor
+~~~~~~~~~~~~~~~~~~~~
+
+Configure hypervisor: KVM
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to "KVM Hypervisor Host Installation" in "PRODUCT
+Installation Guide", you have to configure the following item on the
+host.
+
+Create bridge interface with IPv4 address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This plugin requires an IPv4 address on the KVM host to terminate and
+originate VXLAN traffic. The address should be assinged to a physical
+interface or a bridge interface bound to a physical interface. Both a
+private address or a public address are fine for the purpose. It is not
+required to be in the same subnet for all hypervisors in a zone, but
+they should be able to reach each other via IP multicast with UDP/8472
+port. A name of a physical interface or a name of a bridge interface
+bound to a physical interface can be used as a traffic label. Physical
+interface name fits for almost all cases, but if physical interface name
+differs per host, you may use a bridge to set a same name. If you would
+like to use a bridge name as a traffic label, you may create a bridge in
+this way.
+
+Let ``cloudbr1`` be the bridge interface for the instances' private
+network.
+
+Configure in RHEL or CentOS
+'''''''''''''''''''''''''''
+
+When you configured the ``cloudbr1`` interface as below,
+
+::
+
+ $ sudo vi /etc/sysconfig/network-scripts/ifcfg-cloudbr1
+
+
+::
+
+ DEVICE=cloudbr1
+ TYPE=Bridge
+ ONBOOT=yes
+ BOOTPROTO=none
+ IPV6INIT=no
+ IPV6_AUTOCONF=no
+ DELAY=5
+ STP=yes
+
+
+you would change the configuration similar to below.
+
+::
+
+ DEVICE=cloudbr1
+ TYPE=Bridge
+ ONBOOT=yes
+ BOOTPROTO=static
+ IPADDR=192.0.2.X
+ NETMASK=255.255.255.0
+ IPV6INIT=no
+ IPV6_AUTOCONF=no
+ DELAY=5
+ STP=yes
+
+
+Configure in Ubuntu
+'''''''''''''''''''
+
+When you configured ``cloudbr1`` as below,
+
+::
+
+ $ sudo vi /etc/network/interfaces
+
+::
+
+ auto lo
+ iface lo inet loopback
+
+ # The primary network interface
+ auto eth0.100
+ iface eth0.100 inet static
+ address 192.168.42.11
+ netmask 255.255.255.240
+ gateway 192.168.42.1
+ dns-nameservers 8.8.8.8 8.8.4.4
+ dns-domain lab.example.org
+
+ # Public network
+ auto cloudbr0
+ iface cloudbr0 inet manual
+ bridge_ports eth0.200
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
+
+ # Private network
+ auto cloudbr1
+ iface cloudbr1 inet manual
+ bridge_ports eth0.300
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
+
+
+you would change the configuration similar to below.
+
+::
+
+ auto lo
+ iface lo inet loopback
+
+ # The primary network interface
+ auto eth0.100
+ iface eth0.100 inet static
+ address 192.168.42.11
+ netmask 255.255.255.240
+ gateway 192.168.42.1
+ dns-nameservers 8.8.8.8 8.8.4.4
+ dns-domain lab.example.org
+
+ # Public network
+ auto cloudbr0
+ iface cloudbr0 inet manual
+ bridge_ports eth0.200
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
+
+ # Private network
+ auto cloudbr1
+ iface cloudbr1 inet static
+ addres 192.0.2.X
+ netmask 255.255.255.0
+ bridge_ports eth0.300
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
+
+
+Configure iptables to pass XVLAN packets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since VXLAN uses UDP packet to forward encapsulated the L2 frames,
+UDP/8472 port must be opened.
+
+Configure in RHEL or CentOS
+'''''''''''''''''''''''''''
+
+RHEL and CentOS use iptables for firewalling the system, you can open
+extra ports by executing the following iptable commands:
+
+::
+
+ $ sudo iptables -I INPUT -p udp -m udp --dport 8472 -j ACCEPT
+
+
+These iptable settings are not persistent accross reboots, we have to
+save them first.
+
+::
+
+ $ sudo iptables-save > /etc/sysconfig/iptables
+
+
+With this configuration you should be able to restart the network,
+although a reboot is recommended to see if everything works properly.
+
+::
+
+ $ sudo service network restart
+ $ sudo reboot
+
+
+.. warning:: Make sure you have an alternative way like IPMI or ILO to reach the machine in case you made a configuration error and the network stops functioning!
+
+Configure in Ubuntu
+'''''''''''''''''''
+
+The default firewall under Ubuntu is UFW (Uncomplicated FireWall), which
+is a Python wrapper around iptables.
+
+To open the required ports, execute the following commands:
+
+::
+
+ $ sudo ufw allow proto udp from any to any port 8472
+
+
+.. note:: By default UFW is not enabled on Ubuntu. Executing these commands with the firewall disabled does not enable the firewall.
+
+With this configuration you should be able to restart the network,
+although a reboot is recommended to see if everything works properly.
+
+::
+
+ $ sudo service networking restart
+ $ sudo reboot
+
+
+.. warning:: Make sure you have an alternative way like IPMI or ILO to reach the machine in case you made a configuration error and the network stops functioning!
+
+Setup zone using VXLAN
+~~~~~~~~~~~~~~~~~~~~~~
+
+In almost all parts of zone setup, you can just follow the advanced zone
+setup istruction in "PRODUCT Installation Guide" to use this plugin. It
+is not required to add a network element nor to reconfigure the network
+offering. The only thing you have to do is configure the physical
+network to use VXLAN as the isolation method for Guest Network.
+
+Configure the physical network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /_static/images/vxlan-physicalnetwork.png
+
+CloudStack needs to have one physical network for Guest Traffic with the
+isolation method set to "VXLAN".
+
+.. figure:: /_static/images/vxlan-trafficlabel.png
+
+Guest Network traffic label should be the name of the physical interface
+or the name of the bridge interface and the bridge interface and they
+should have an IPv4 address. See ? for details.
+
+Configure the guest traffic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /_static/images/vxlan-vniconfig.png
+
+Specify a range of VNIs you would like to use for carrying guest network
+traffic.
+
+.. warning:: VNI must be unique per zone and no duplicate VNIs can exist in the zone. Exercise care when designing your VNI allocation policy.
+
+
[2/3] Create RTD docs
Posted by se...@apache.org.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/ansible.rst
----------------------------------------------------------------------
diff --git a/rtd/source/ansible.rst b/rtd/source/ansible.rst
new file mode 100644
index 0000000..7f0f9bd
--- /dev/null
+++ b/rtd/source/ansible.rst
@@ -0,0 +1,412 @@
+Deploying CloudStack with Ansible
+=================================
+
+In this article, `Paul Angus <https://twitter.com/CloudyAngus>`__ Cloud
+Architect at ShapeBlue takes a look at using Ansible to Deploy an
+Apache CloudStack cloud.
+
+What is Ansible
+---------------
+
+Ansible is a deployment and configuration management tool similar in
+intent to Chef and Puppet. It allows (usually) DevOps teams to
+orchestrate the deployment and configuration of their environments
+without having to re-write custom scripts to make changes.
+
+Like Chef and Puppet, Ansible is designed to be idempotent, these means
+that you determine the state you want a host to be in and Ansible will
+decide if it needs to act in order to achieve that state.
+
+There’s already Chef and Puppet, so what’s the fuss about Ansible?
+------------------------------------------------------------------
+
+Let’s take it as a given that configuration management makes life much
+easier (and is quite cool), Ansible only needs an SSH connection to the
+hosts that you’re going to manage to get started. While Ansible requires
+Python 2.4 or greater to on the host you’re going to manage in order to
+leverage the vast majority of its functionality, it is able to connect
+to hosts which don’t have Python installed in order to then install
+Python, so it’s not really a problem. This greatly simplifies the
+deployment procedure for hosts, avoiding the need to pre-install agents
+onto the clients before the configuration management can take over.
+
+Ansible will allow you to connect as any user to a managed host (with
+that user’s privileges) or by using public/private keys – allowing fully
+automated management.
+
+There also doesn’t need to be a central server to run everything, as
+long as your playbooks and inventories are in-sync you can create as
+many Ansible servers as you need (generally a bit of Git pushing and
+pulling will do the trick).
+
+Finally – its structure and language is pretty simple and clean. I’ve
+found it a bit tricky to get the syntax correct for variables in some
+circumstances, but otherwise I’ve found it one of the easier tools to
+get my head around.
+
+So let’s see something
+----------------------
+
+For this example we’re going to create an Ansible server which will then
+deploy a CloudStack server. Both of these servers will be CentOS 6.4
+virtual machines.
+
+Installing Ansible
+------------------
+
+Installing Ansible is blessedly easy. We generally prefer to use CentOS
+so to install Ansible you run the following commands on the Ansible
+server.
+
+::
+
+ # rpm -ivh http://www.mirrorservice.org/sites/dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
+ # yum install -y ansible
+
+And that’s it.
+
+*(There is a commercial version which has more features such as callback
+to request configurations and a RESTful API and also support. The
+installation of this is different)*
+
+By default Ansible uses /etc/ansible to store your playbooks, I tend to
+move it, but there’s no real problem with using the default location.
+Create yourself a little directory structure to get started with. The
+documentation recommends something like this:
+
+
+Playbooks
+---------
+
+Ansible uses playbooks to specify the state in which you wish the target
+host to be in to be able to accomplish its role. Ansible playbooks are
+written in YAML format.
+
+Modules
+-------
+
+To get Ansible to do things you specify the hosts a playbook will act
+upon and then call modules and supply arguments which determine what
+Ansible will do to those hosts.
+
+To keep things simple, this example is a cut-down version of a full
+deployment. This example creates a single management server with a local
+MySQL server and assumes you have your secondary storage already
+provisioned somewhere. For this example I’m also not going to include
+securing the MySQL server, configuring NTP or using Ansible to configure
+the networking on the hosts either. Although normally we’d use Ansible
+to do exactly that.
+
+The pre-requisites to this CloudStack build are:
+
+- A CentOS 6.4 host to install CloudStack on
+- An IP address already assigned on the ACS management host
+- The ACS management host should have a resolvable FQDN (either through
+ DNS or the host file on the ACS management host)
+- Internet connectivity on the ACS management host
+
+Planning
+--------
+
+The first step I use is to list all of the tasks I think I’ll need and
+group them or split them into logical blocks. So for this deployment of
+CloudStack I’d start with:
+
+- Configure selinux
+- (libselinux-python required for Ansible to work with selinux enabled
+ hosts)
+- Install and configure MySQL
+- (Python MySQL-DB required for Ansible MySQL module)
+- Install cloud-client
+- Seed secondary storage
+
+Ansible is built around the idea of hosts having roles, so generally you
+would group or manage your hosts by their roles. So now to create some
+roles for these tasks
+
+I’ve created:
+
+- cloudstack-manager
+- mysql
+
+First up we need to tell Ansible where to find our CloudStack management
+host. In the root Ansible directory there is a file called ‘hosts’
+(/etc/Ansible/hosts) add a section like this:
+
+::
+
+ [acs-manager]
+ xxx.xxx.xxx.xxx
+
+where xxx.xxx.xxx.xxx is the ip address of your ACS management host.
+
+MySQL
+-----
+
+So let’s start with the MySQL server. We’ll need to create a task
+within the mysql role directory called main.yml. The ‘task’ in this case
+to have MySQL running and configured on the target host. The contents of
+the file will look like this:
+
+::
+
+ -name: Ensure mysql server is installed
+
+ yum: name=mysql-server state=present
+
+ - name: Ensure mysql python is installed
+
+ yum: name=MySQL-python state=present
+
+
+ - name: Ensure selinux python bindings are installed
+
+ yum: name=libselinux-python state=present
+
+ - name: Ensure cloudstack specfic my.cnf lines are present
+
+ lineinfile: dest=/etc/my.cnf regexp=’$item’ insertafter=”symbolic-links=0″ line=’$item’
+
+ with\_items:
+
+ – skip-name-resolve
+
+ – default-time-zone=’+00:00′
+
+ – innodb\_rollback\_on\_timeout=1
+
+ – innodb\_lock\_wait\_timeout=600
+
+ – max\_connections=350
+
+ – log-bin=mysql-bin
+
+ – binlog-format = ‘ROW’
+
+
+ - name: Ensure MySQL service is started
+
+ service: name=mysqld state=started
+
+ - name: Ensure MySQL service is enabled at boot
+
+ service: name=mysqld enabled=yes
+
+
+
+ - name: Ensure root password is set
+
+ mysql\_user: user=root password=$mysql\_root\_password host=localhost
+
+ ignore\_errors: true
+
+ - name: Ensure root has sufficient privileges
+
+ mysql\_user: login\_user=root login\_password=$mysql\_root\_password user=root host=% password=$mysql\_root\_password priv=\*.\*:GRANT,ALL state=present
+
+This needs to be saved as `/etc/ansible/roles/mysql/tasks/main.yml`
+
+As explained earlier, this playbook in fact describes the state of the
+host rather than setting out commands to be run. For instance, we
+specify certain lines which must be in the my.cnf file and allow Ansible
+to decide whether or not it needs to add them.
+
+Most of the modules are self-explanatory once you see them, but to run
+through them briefly;
+
+The ‘yum’ module is used to specify which packages are required, the
+‘service’ module controls the running of services, while the
+‘mysql\_user’ module controls mysql user configuration. The ‘lineinfile’
+module controls the contents in a file.
+
+ We have a couple of variables which need declaring. You could do that
+within this playbook or its ‘parent’ playbook, or as a higher level
+variable. I’m going to declare them in a higher level playbook. More on
+this later.
+
+ That’s enough to provision a MySQL server. Now for the management
+server.
+
+
+CloudStack Management server service
+------------------------------------
+
+For the management server role we create a main.yml task like this:
+
+::
+
+ - name: Ensure selinux python bindings are installed
+
+ yum: name=libselinux-python state=present
+
+
+ - name: Ensure the Apache Cloudstack Repo file exists as per template
+
+ template: src=cloudstack.repo.j2 dest=/etc/yum.repos.d/cloudstack.repo
+
+
+ - name: Ensure selinux is in permissive mode
+
+ command: setenforce permissive
+
+
+ - name: Ensure selinux is set permanently
+
+ selinux: policy=targeted state=permissive
+
+
+ -name: Ensure CloudStack packages are installed
+
+ yum: name=cloud-client state=present
+
+
+ - name: Ensure vhdutil is in correct location
+
+ get\_url: url=http://download.cloud.com.s3.amazonaws.com/tools/vhd-util dest=/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/vhd-util mode=0755
+
+
+Save this as `/etc/ansible/roles/cloudstack-management/tasks/main.yml`
+
+Now we have some new elements to deal with. The Ansible template module
+uses Jinja2 based templating. As we’re doing a simplified example here,
+the Jinja template for the cloudstack.repo won’t have any variables in
+it, so it would simply look like this:
+
+::
+
+ [cloudstack]
+ name=cloudstack
+ baseurl=http://cloudstack.apt-get.eu/rhel/4.2/
+ enabled=1
+ gpgcheck=0
+
+This is saved in `/etc/ansible/roles/cloudstack-manager/templates/cloudstack.repo.j2`
+
+That gives us the packages installed, we need to set up the database. To
+do this I’ve created a separate task called setupdb.yml
+
+::
+
+ - name: cloudstack-setup-databases
+ command: /usr/bin/cloudstack-setup-databases cloud:{{mysql\_cloud\_password }}@localhost –deploy-as=root:{{mysql\_root\_password }}
+
+ - name: Setup CloudStack manager
+ command: /usr/bin/cloudstack-setup-management
+
+
+Save this as: `/etc/ansible/roles/cloudstack-management/tasks/setupdb.yml`
+
+As there isn’t (as yet) a CloudStack module, Ansible doesn’t inherently
+know whether or not the databases have already been provisioned,
+therefore this step is not currently idempotent and will overwrite any
+previously provisioned databases.
+
+There are some more variables here for us to declare later.
+
+
+System VM Templates:
+--------------------
+
+
+Finally we would want to seed the system VM templates into the secondary
+storage. The playbook for this would look as follows:
+
+::
+
+ - name: Ensure secondary storage mount exists
+ file: path={{ tmp\_nfs\_path }} state=directory
+
+
+ - name: Ensure NFS storage is mounted
+ mount: name={{ tmp\_nfs\_path }} src={{ sec\_nfs\_ip }}:{{sec\_nfs\_path }} fstype=nfs state=mounted opts=nolock
+
+
+ - name: Seed secondary storage
+ command:
+ /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-06-12-master-kvm.qcow2.bz2 -h kvm -F
+
+ command:
+ /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-07-12-master-xen.vhd.bz2 -h xenserver -F
+
+ command:
+ /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-4.2-vh7.ov -h vmware -F
+
+
+Save this as `/etc/ansible/roles/cloudstack-manager/tasks/seedstorage.yml`
+
+ Again, there isn’t a CloudStack module so Ansible will always run this
+even if the secondary storage already has the templates in it.
+
+
+Bringing it all together
+------------------------
+
+Ansible can use playbooks which run other playbooks, this allows us to
+group these playbooks together and declare variables across all of the
+individual playbooks. So in the Ansible playbook directory create a file
+called deploy-cloudstack.yml, which would look like this:
+
+::
+
+ -hosts: acs-manager
+
+ vars:
+
+ mysql\_root\_password: Cl0ud5tack
+ mysql\_cloud\_password: Cl0ud5tack
+ tmp\_nfs\_path: /mnt/secondary
+ sec\_nfs\_ip: IP\_OF\_YOUR\_SECONDARY\_STORAGE
+ sec\_nfs\_path: PATH\_TO\_YOUR\_SECONDARY\_STORAGE\_MOUNT
+
+
+ roles:
+
+ – mysql
+ – cloudstack-manager
+
+ tasks:
+
+ – include: /etc/ansible/roles/cloudstack-manager/tasks/setupdb.yml
+ – include: /etc/ansible/roles/cloudstack-manager/tasks/seedstorage.yml
+
+
+Save this as `/etc/ansible/deploy-cloudstack.yml` inserting the IP
+address and path for your secondary storage and changing the passwords
+if you wish to.
+
+
+
+To run this go to the Ansible directory (cd /etc/ansible ) and run:
+
+::
+
+ # ansible-playbook deploy-cloudstack.yml -k
+
+ ‘-k’ tells Ansible to ask you for the root password to connect to the
+remote host.
+
+ Now log in to the CloudStack UI on the new management server.
+
+
+
+How is this example different from a production deployment?
+-----------------------------------------------------------
+
+In a production deployment, the Ansible playbooks would configure
+multiple management servers connected to master/slave replicating MySQL
+databases along with any other infrastructure components required and
+deploy and configure the hypervisor hosts. We would also have a
+dedicated file describing the hosts in the environment and a dedicated
+file containing variables which describe the environment.
+
+The advantage of using a configuration management tool such as Ansible
+is that we can specify components like the MySQL database VIP once and
+use it multiple times when configuring the MySQL server itself and other
+components which need to use that information.
+
+
+Acknowledgements
+----------------
+
+Thanks to Shanker Balan for introducing me to Ansible and a load of
+handy hints along the way.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/conf.py
----------------------------------------------------------------------
diff --git a/rtd/source/conf.py b/rtd/source/conf.py
new file mode 100644
index 0000000..eb253ef
--- /dev/null
+++ b/rtd/source/conf.py
@@ -0,0 +1,344 @@
+# 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.
+
+# -*- coding: utf-8 -*-
+#
+# CloudStack Release Notes documentation build configuration file, created by
+# sphinx-quickstart on Fri Feb 7 16:00:59 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Apache CloudStack'
+copyright = u'2014, Apache CloudStack'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '4.3'
+# The full version, including alpha/beta/rc tags.
+release = '4.3.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'CloudStackReleaseNotesdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ ('index', 'CloudStackReleaseNotes.tex', u'CloudStack Release Notes Documentation',
+ u'Apache CloudStack', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'cloudstackreleasenotes', u'CloudStack Release Notes Documentation',
+ [u'Apache CloudStack'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'CloudStackReleaseNotes', u'CloudStack Release Notes Documentation',
+ u'Apache CloudStack', 'CloudStackReleaseNotes', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'CloudStack Release Notes'
+epub_author = u'Apache CloudStack'
+epub_publisher = u'Apache CloudStack'
+epub_copyright = u'2014, Apache CloudStack'
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = u'CloudStack Release Notes'
+
+# The HTML theme for the epub output. Since the default themes are not optimized
+# for small screen space, using the same theme for HTML and epub output is
+# usually not wise. This defaults to 'epub', a theme designed to save visual
+# space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the PIL.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/developer_guide.rst
----------------------------------------------------------------------
diff --git a/rtd/source/developer_guide.rst b/rtd/source/developer_guide.rst
new file mode 100644
index 0000000..7ccb6be
--- /dev/null
+++ b/rtd/source/developer_guide.rst
@@ -0,0 +1,653 @@
+CloudStack Installation from Source for Developers
+==================================================
+
+This book is aimed at CloudStack developers who need to build the code.
+These instructions are valid on a Ubuntu 12.04 and CentOS 6.4 systems
+and were tested with the 4.2 release of Apache CloudStack, please adapt
+them if you are on a different operating system or using a newer/older
+version of CloudStack. This book is composed of the following sections:
+
+1. Installation of the prerequisites
+2. Compiling and installation from source
+3. Using the CloudStack simulator
+4. Installation with DevCloud the CloudStack sandbox
+5. Building your own packages
+6. The CloudStack API
+7. Testing the AWS API interface
+
+
+Prerequisites
+-------------
+
+In this section we'll look at installing the dependencies you'll need
+for Apache CloudStack development.
+
+On Ubuntu 12.04
+~~~~~~~~~~~~~~~
+
+First update and upgrade your system:
+
+::
+
+ apt-get update
+ apt-get upgrade
+
+NTP might already be installed, check it with ``service ntp status``. If
+it's not then install NTP to synchronize the clocks:
+
+::
+
+ apt-get install openntpd
+
+Install ``openjdk``. As we're using Linux, OpenJDK is our first choice.
+
+::
+
+ apt-get install openjdk-6-jdk
+
+Install ``tomcat6``, note that the new version of tomcat on
+`Ubuntu <http://packages.ubuntu.com/precise/all/tomcat6>`__ is the
+6.0.35 version.
+
+::
+
+ apt-get install tomcat6
+
+Next, we'll install MySQL if it's not already present on the system.
+
+::
+
+ apt-get install mysql-server
+
+Remember to set the correct ``mysql`` password in the CloudStack
+properties file. Mysql should be running but you can check it's status
+with:
+
+::
+
+ service mysql status
+
+Developers wanting to build CloudStack from source will want to install
+the following additional packages. If you dont' want to build from
+source just jump to the next section.
+
+Install ``git`` to later clone the CloudStack source code:
+
+::
+
+ apt-get install git
+
+Install ``Maven`` to later build CloudStack
+
+::
+
+ apt-get install maven
+
+This should have installed Maven 3.0, check the version number with
+``mvn --version``
+
+A little bit of Python can be used (e.g simulator), install the Python
+package management tools:
+
+::
+
+ apt-get install python-pip python-setuptools
+
+Finally install ``mkisofs`` with:
+
+::
+
+ apt-get install genisoimage
+
+On centOS 6.4
+~~~~~~~~~~~~~
+
+First update and upgrade your system:
+
+::
+
+ yum -y update
+ yum -y upgrade
+
+If not already installed, install NTP for clock synchornization
+
+::
+
+ yum -y install ntp
+
+Install ``openjdk``. As we're using Linux, OpenJDK is our first choice.
+
+::
+
+ yum -y install java-1.6.0-openjdk
+
+Install ``tomcat6``, note that the version of tomcat6 in the default
+CentOS 6.4 repo is 6.0.24, so we will grab the 6.0.35 version. The
+6.0.24 version will be installed anyway as a dependency to cloudstack.
+
+::
+
+ wget https://archive.apache.org/dist/tomcat/tomcat-6/v6.0.35/bin/apache-tomcat-6.0.35.tar.gz
+ tar xzvf apache-tomcat-6.0.35.tar.gz -C /usr/local
+
+Setup tomcat6 system wide by creating a file
+``/etc/profile.d/tomcat.sh`` with the following content:
+
+::
+
+ export CATALINA_BASE=/usr/local/apache-tomcat-6.0.35
+ export CATALINA_HOME=/usr/local/apache-tomcat-6.0.35
+
+Next, we'll install MySQL if it's not already present on the system.
+
+::
+
+ yum -y install mysql mysql-server
+
+Remember to set the correct ``mysql`` password in the CloudStack
+properties file. Mysql should be running but you can check it's status
+with:
+
+::
+
+ service mysqld status
+
+Install ``git`` to later clone the CloudStack source code:
+
+::
+
+ yum -y install git
+
+Install ``Maven`` to later build CloudStack. Grab the 3.0.5 release from
+the Maven `website <http://maven.apache.org/download.cgi>`__
+
+::
+
+ wget http://mirror.cc.columbia.edu/pub/software/apache/maven/maven-3/3.0.5/binaries/apache-maven-3.0.5-bin.tar.gz
+ tar xzf apache-maven-3.0.5-bin.tar.gz -C /usr/local
+ cd /usr/local
+ ln -s apache-maven-3.0.5 maven
+
+Setup Maven system wide by creating a ``/etc/profile.d/maven.sh`` file
+with the following content:
+
+::
+
+ export M2_HOME=/usr/local/maven
+ export PATH=${M2_HOME}/bin:${PATH}
+
+Log out and log in again and you will have maven in your PATH:
+
+::
+
+ mvn --version
+
+This should have installed Maven 3.0, check the version number with
+``mvn --version``
+
+A little bit of Python can be used (e.g simulator), install the Python
+package management tools:
+
+::
+
+ yum -y install python-setuptools
+
+To install python-pip you might want to setup the Extra Packages for
+Enterprise Linux (EPEL) repo
+
+::
+
+ cd /tmp
+ wget http://mirror-fpt-telecom.fpt.net/fedora/epel/6/i386/epel-release-6-8.noarch.rpm
+ rpm -ivh epel-release-6-8.noarch.rpm
+
+Then update you repository cache ``yum update`` and install pip
+``yum -y install python-pip``
+
+Finally install ``mkisofs`` with:
+
+::
+
+ yum -y install genisoimage
+
+
+Installing from Source
+----------------------
+
+CloudStack uses git for source version control, if you know little about
+`git <http://book.git-scm.com/>`__ is a good start. Once you have git
+setup on your machine, pull the source with:
+
+::
+
+ git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git
+
+To build the latest stable release:
+
+::
+
+ git checkout 4.2
+
+To compile Apache CloudStack, go to the cloudstack source folder and
+run:
+
+::
+
+ mvn -Pdeveloper,systemvm clean install
+
+If you want to skip the tests add ``-DskipTests`` to the command above
+
+You will have made sure to set the proper db password in
+``utils/conf/db.properties``
+
+Deploy the database next:
+
+::
+
+ mvn -P developer -pl developer -Ddeploydb
+
+Run Apache CloudStack with jetty for testing. Note that ``tomcat`` maybe
+be running on port 8080, stop it before you use ``jetty``
+
+::
+
+ mvn -pl :cloud-client-ui jetty:run
+
+Log Into Apache CloudStack:
+
+Open your Web browser and use this URL to connect to CloudStack:
+
+::
+
+ http://localhost:8080/client/
+
+Replace ``localhost`` with the IP of your management server if need be.
+
+.. note:: If you have iptables enabled, you may have to open the ports used by CloudStack. Specifically, ports 8080, 8250, and 9090.
+
+You can now start configuring a Zone, playing with the API. Of course we
+did not setup any infrastructure, there is no storage, no
+hypervisors...etc. However you can run tests using the simulator. The
+following section shows you how to use the simulator so that you don't
+have to setup a physical infrastructure.
+
+Using the Simulator
+-------------------
+
+CloudStack comes with a simulator based on Python bindings called
+*Marvin*. Marvin is available in the CloudStack source code or on Pypi.
+With Marvin you can simulate your data center infrastructure by
+providing CloudStack with a configuration file that defines the number
+of zones/pods/clusters/hosts, types of storage etc. You can then develop
+and test the CloudStack management server *as if* it was managing your
+production infrastructure.
+
+Do a clean build:
+
+::
+
+ mvn -Pdeveloper -Dsimulator -DskipTests clean install
+
+Deploy the database:
+
+::
+
+ mvn -Pdeveloper -pl developer -Ddeploydb
+ mvn -Pdeveloper -pl developer -Ddeploydb-simulator
+
+Install marvin. Note that you will need to have installed ``pip``
+properly in the prerequisites step.
+
+::
+
+ pip install tools/marvin/dist/Marvin-0.1.0.tar.gz
+
+Stop jetty (from any previous runs)
+
+::
+
+ mvn -pl :cloud-client-ui jetty:stop
+
+Start jetty
+
+::
+
+ mvn -pl client jetty:run
+
+Setup a basic zone with Marvin. In a separate shell://
+
+::
+
+ mvn -Pdeveloper,marvin.setup -Dmarvin.config=setup/dev/basic.cfg -pl :cloud-marvin integration-test
+
+At this stage log in the CloudStack management server at
+http://localhost:8080/client with the credentials admin/password, you
+should see a fully configured basic zone infrastructure. To simulate an
+advanced zone replace ``basic.cfg`` with ``advanced.cfg``.
+
+You can now run integration tests, use the API etc...
+
+Using DevCloud
+--------------
+
+The Installing from source section will only get you to the point of
+runnign the management server, it does not get you any hypervisors. The
+simulator section gets you a simulated datacenter for testing. With
+DevCloud you can run at least one hypervisor and add it to your
+management server the way you would a real physical machine.
+
+`DevCloud <https://cwiki.apache.org/confluence/display/CLOUDSTACK/DevCloud>`__
+is the CloudStack sandbox, the standard version is a VirtualBox based
+image. There is also a KVM based image for it. Here we only show steps
+with the VirtualBox image. For KVM see the
+`wiki <https://cwiki.apache.org/confluence/display/CLOUDSTACK/devcloud-kvm>`__.
+
+\*\* DevCloud Pre-requisites
+
+1. Install `VirtualBox <http://www.virtualbox.org>`__ on your machine
+
+2. Run VirtualBox and under >Preferences create a *host-only interface*
+ on which you disable the DHCP server
+
+3. Download the DevCloud
+ `image <http://people.apache.org/~bhaisaab/cloudstack/devcloud/devcloud2.ova>`__
+
+4. In VirtualBox, under File > Import Appliance import the DevCloud
+ image.
+
+5. Verify the settings under > Settings and check the ``enable PAE``
+ option in the processor menu
+
+6. Once the VM has booted try to ``ssh`` to it with credentials:
+ ``root/password``
+
+ ssh root@192.168.56.10
+
+Adding DevCloud as an Hypervisor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Picking up from a clean build:
+
+::
+
+ mvn -Pdeveloper,systemvm clean install
+ mvn -P developer -pl developer,tools/devcloud -Ddeploydb
+
+At this stage install marvin similarly than with the simulator:
+
+::
+
+ pip install tools/marvin/dist/Marvin-0.1.0.tar.gz
+
+Start the management server
+
+::
+
+ mvn -pl client jetty:run
+
+Then you are going to configure CloudStack to use the running DevCloud
+instance:
+
+::
+
+ cd tools/devcloud
+ python ../marvin/marvin/deployDataCenter.py -i devcloud.cfg
+
+If you are curious, check the ``devcloud.cfg`` file and see how the data
+center is defined: 1 Zone, 1 Pod, 1 Cluster, 1 Host, 1 primary Storage,
+1 Seondary Storage, all provided by Devcloud.
+
+You can now log in the management server at
+``http://localhost:8080/client`` and start experimenting with the UI or
+the API.
+
+Do note that the management server is running in your local machine and
+that DevCloud is used only as a n Hypervisor. You could potentially run
+the management server within DevCloud as well, or memory granted, run
+multiple DevClouds.
+
+Building Packages
+-----------------
+
+Working from source is necessary when developing CloudStack. As
+mentioned earlier this is not primarily intended for users. However some
+may want to modify the code for their own use and specific
+infrastructure. The may also need to build their own packages for
+security reasons and due to network connectivity constraints. This
+section shows you the gist of how to build packages. We assume that the
+reader will know how to create a repository to serve this packages. The
+complete documentation is available on the
+`website <http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.2.0/html/Installation_Guide/sect-source-builddebs.html>`__
+
+To build debian packages you will need couple extra packages that we did
+not need to install for source compilation:
+
+::
+
+ apt-get install python-mysqldb
+ apt-get install debhelper
+
+Then build the packages with:
+
+::
+
+ dpkg-buildpackage -uc -us
+
+One directory up from the CloudStack root dir you will find:
+
+::
+
+ cloudstack_4.2.0_amd64.changes
+ cloudstack_4.2.0.dsc
+ cloudstack_4.2.0.tar.gz
+ cloudstack-agent_4.2.0_all.deb
+ cloudstack-awsapi_4.2.0_all.deb
+ cloudstack-cli_4.2.0_all.deb
+ cloudstack-common_4.2.0_all.deb
+ cloudstack-docs_4.2.0_all.deb
+ cloudstack-management_4.2.0_all.deb
+ cloudstack-usage_4.2.0_all.deb
+
+Of course the community provides a repository for these packages and you
+can use it instead of building your own packages and putting them in
+your own repo. Instructions on how to use this community repository are
+available in the installation book.
+
+The CloudStack API
+------------------
+
+The CloudStack API is a query based API using http that return results
+in XML or JSON. It is used to implement the default web UI. This API is
+not a standard like `OGF
+OCCI <http://www.ogf.org/gf/group_info/view.php?group=occi-wg>`__ or
+`DMTF CIMI <http://dmtf.org/standards/cloud>`__ but is easy to learn.
+Mapping exists between the AWS API and the CloudStack API as will be
+seen in the next section. Recently a Google Compute Engine interface was
+also developed that maps the GCE REST API to the CloudStack API
+described here. The API
+`docs <http://cloudstack.apache.org/docs/api/>`__ are a good start to
+learn the extent of the API. Multiple clients exist on
+`github <https://github.com/search?q=cloudstack+client&ref=cmdform>`__
+to use this API, you should be able to find one in your favorite
+language. The reference documentation for the API and changes that might
+occur from version to version is availble
+`on-line <http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.1.1/html/Developers_Guide/index.html>`__.
+This short section is aimed at providing a quick summary to give you a
+base understanding of how to use this API. As a quick start, a good way
+to explore the API is to navigate the dashboard with a firebug console
+(or similar developer console) to study the queries.
+
+In a succint statement, the CloudStack query API can be used via http
+GET requests made against your cloud endpoint (e.g
+http://localhost:8080/client/api). The API name is passed using the
+``command`` key and the various parameters for this API call are passed
+as key value pairs. The request is signed using the access key and
+secret key of the user making the call. Some calls are synchronous while
+some are asynchronous, this is documented in the API
+`docs <http://cloudstack.apache.org/docs/api/>`__. Asynchronous calls
+return a ``jobid``, the status and result of a job can be queried with
+the ``queryAsyncJobResult`` call. Let's get started and give an example
+of calling the ``listUsers`` API in Python.
+
+First you will need to generate keys to make requests. Going through the
+dashboard, go under ``Accounts`` select the appropriate account then
+click on ``Show Users`` select the intended users and generate keys
+using the ``Generate Keys`` icon. You will see an ``API Key`` and
+``Secret Key`` field being generated. The keys will be of the form:
+
+::
+
+ API Key : XzAz0uC0t888gOzPs3HchY72qwDc7pUPIO8LxC-VkIHo4C3fvbEBY_Ccj8fo3mBapN5qRDg_0_EbGdbxi8oy1A
+ Secret Key: zmBOXAXPlfb-LIygOxUVblAbz7E47eukDS_0JYUxP3JAmknOYo56T0R-AcM7rK7SMyo11Y6XW22gyuXzOdiybQ
+
+Open a Python shell and import the basic modules necessary to make the
+request. Do note that this request could be made many different ways,
+this is just a low level example. The ``urllib*`` modules are used to
+make the http request and do url encoding. The ``hashlib`` module gives
+us the sha1 hash function. It used to geenrate the ``hmac`` (Keyed
+Hashing for Message Authentication) using the secretkey. The result is
+encoded using the ``base64`` module.
+
+::
+
+ $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,
+the type of the response (i.e XML or JSON) and the keys of the user.
+Note that we do not put the secretkey in our request dictionary because
+it is only used to compute the hmac.
+
+::
+
+ >>> 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 base request string, the combination of all the key/pairs of
+the request, url encoded and joined with ampersand.
+
+::
+
+ >>> 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, the string used for the signature is similar to the base
+request string shown above but the keys/values are lower cased and
+joined in a sorted order
+
+::
+
+ >>> 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).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 by joining the baseurl, the request str
+and the signature. Then do an http GET:
+
+::
+
+ >>> req=baseurl+request_str+'&signature='+sig
+ >>> req
+ 'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
+ >>> res=urllib2.urlopen(req)
+ >>> res.read()
+ '{ "listusersresponse" : { "count":1 ,"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"}]}}
+
+
+All the clients that you will find on github will implement this
+signature technique, you should not have to do it by hand. Now that you
+have explored the API through the UI and that you understand how to make
+low level calls, pick your favorite client of use
+`CloudMonkey <https://pypi.python.org/pypi/cloudmonkey/>`__. CloudMonkey
+is a sub-project of Apache CloudStack and gives operators/developers the
+ability to use any of the API methods. It has nice auto-completion and
+help feature as well as an API discovery mechanism since 4.2.
+
+Testing the AWS API interface
+-----------------------------
+
+While the native CloudStack API is not a standard, CloudStack provides a
+AWS EC2 compatible interface. It has the great advantage that existing
+tools written with EC2 libraries can be re-used against a CloudStack
+based cloud. In the installation books we described how to run this
+interface from installing packages. In this section we show you how to
+compile the interface with ``maven`` and test it with Python boto
+module.
+
+Starting from a running management server (with DevCloud for instance),
+start the AWS API interface in a separate shell with:
+
+::
+
+ mvn -Pawsapi -pl :cloud-awsapi jetty:run
+
+Log into the CloudStack UI ``http://localhost:8080/client``, go to
+*Service Offerings* and edit one of the compute offerings to have the
+name ``m1.small`` or any of the other AWS EC2 instance types.
+
+With access and secret keys generated for a user you should now be able
+to use Python `Boto <http://docs.pythonboto.org/en/latest/>`__ module:
+
+::
+
+ import boto
+ import boto.ec2
+
+ accesskey="2IUSA5xylbsPSnBQFoWXKg3RvjHgsufcKhC1SeiCbeEc0obKwUlwJamB_gFmMJkFHYHTIafpUx0pHcfLvt-dzw"
+ secretkey="oxV5Dhhk5ufNowey7OVHgWxCBVS4deTl9qL0EqMthfPBuy3ScHPo2fifDxw1aXeL5cyH10hnLOKjyKphcXGeDA"
+
+ region = boto.ec2.regioninfo.RegionInfo(name="ROOT", endpoint="localhost")
+ conn = boto.connect_ec2(aws_access_key_id=accesskey, aws_secret_access_key=secretkey, is_secure=False, region=region, port=7080, path="/awsapi", api_version="2012-08-15")
+
+ images=conn.get_all_images()
+ print images
+
+ res = images[0].run(instance_type='m1.small',security_groups=['default'])
+
+Note the new ``api_version`` number in the connection object and also
+note that there was no user registration to make like in previous
+CloudStack releases.
+
+Conclusions
+-----------
+
+CloudStack is a mostly Java application running with Tomcat and Mysql.
+It consists of a management server and depending on the hypervisors
+being used, an agent installed on the hypervisor farm. To complete a
+Cloud infrastructure however you will also need some Zone wide storage
+a.k.a Secondary Storage and some Cluster wide storage a.k.a Primary
+storage. The choice of hypervisor, storage solution and type of Zone
+(i.e Basic vs. Advanced) will dictate how complex your installation can
+be. As a quick start, you might want to consider KVM+NFS and a Basic
+Zone.
+
+If you've run into any problems with this, please ask on the
+cloudstack-dev `mailing list </mailing-lists.html>`__.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/index.rst
----------------------------------------------------------------------
diff --git a/rtd/source/index.rst b/rtd/source/index.rst
new file mode 100644
index 0000000..8e61e62
--- /dev/null
+++ b/rtd/source/index.rst
@@ -0,0 +1,48 @@
+.. CloudStack Documentation documentation master file, created by
+ sphinx-quickstart on Sat Nov 2 11:17:30 2013.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to CloudStack Documentation !
+=======================================
+
+.. figure:: /_static/images/acslogo.png
+ :align: center
+
+Networking Guides
+------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ networking/nicira-plugin
+ networking/midonet
+ networking/ovs-plugin
+ networking/autoscale_without_netscaler.rst
+ networking/troubleshoot_internet_traffic.rst
+ networking/vxlan.rst
+
+Allocator Guide
+---------------
+
+.. toctree::
+ :maxdepth: 2
+
+ alloc.rst
+
+Developer's Guide
+------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ developer_guide
+ ansible
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/networking/autoscale_without_netscaler.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/autoscale_without_netscaler.rst b/rtd/source/networking/autoscale_without_netscaler.rst
new file mode 100644
index 0000000..2f8a1e3
--- /dev/null
+++ b/rtd/source/networking/autoscale_without_netscaler.rst
@@ -0,0 +1,85 @@
+Configuring AutoScale without using NetScaler
+=============================================
+
+What is AutoScaling?
+~~~~~~~~~~~~~~~~~~~~
+
+AutoScaling allows you to scale your back-end services or application VMs up or down seamlessly and automatically according to the conditions you define. With AutoScaling enabled, you can ensure that the number of VMs you are using seamlessly scale up when demand increases, and automatically decreases when demand subsides. Thus it helps you save compute costs by terminating underused VMs automatically and launching new VMs when you need them, without the need for manual intervention.
+
+Hypervisor support
+~~~~~~~~~~~~~~~~~~
+
+At that time, AutoScaling without NetScaler only supports for Xenserver. We are working to support KVM also.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before you configure an AutoScale rule, consider the following:
+
+* Ensure that the necessary template is prepared before configuring AutoScale. Firstly you must install the PV-driver, which helps Xenserver collect performance parameters (CPU and memory) into VMs. Beside, When a VM is deployed by using a template and when it comes up, the application should be up and running.
+
+Configuration
+~~~~~~~~~~~~~
+
+Specify the following:
+
+.. image:: ../_static/images/autoscale-config.png
+
+* Template: A template consists of a base OS image and application. A template is used to provision the new instance of an application on a scaleup action. When a VM is deployed from a template, the VM can start taking the traffic from the load balancer without any admin intervention. For example, if the VM is deployed for a Web service, it should have the Web server running, the database connected, and so on.
+
+* Compute offering: A predefined set of virtual hardware attributes, including CPU speed, number of CPUs, and RAM size, that the user can select when creating a new virtual machine instance. Choose one of the compute offerings to be used while provisioning a VM instance as part of scaleup action.
+
+* Min Instance: The minimum number of active VM instances that is assigned to a load balancing rule. The active VM instances are the application instances that are up and serving the traffic, and are being load balanced. This parameter ensures that a load balancing rule has at least the configured number of active VM instances are available to serve the traffic.
+
+* Max Instance: Maximum number of active VM instances that should be assigned to a load balancing rule. This parameter defines the upper limit of active VM instances that can be assigned to a load balancing rule.
+
+Specifying a large value for the maximum instance parameter might result in provisioning large number of VM instances, which in turn leads to a single load balancing rule exhausting the VM instances limit specified at the account or domain level.
+
+Specify the following scale-up and scale-down policies:
+
+* Duration: The duration, in seconds, for which the conditions you specify must be true to trigger a scaleup action. The conditions defined should hold true for the entire duration you specify for an AutoScale action to be invoked.
+
+* Counter: The performance counters expose the state of the monitored instances. We added two new counter to work with that feature:
+
+- Linux User CPU [native] - percentage
+- Linux User RAM [native] - percentage
+
+Remember to choose one of them. If you choose anything else, the autoscaling will not work.
+
+* Operator: The following five relational operators are supported in AutoScale feature: Greater than, Less than, Less than or equal to, Greater than or equal to, and Equal to.
+
+* Threshold: Threshold value to be used for the counter. Once the counter defined above breaches the threshold value, the AutoScale feature initiates a scaleup or scaledown action.
+
+* Add: Click Add to add the condition.
+
+Additionally, if you want to configure the advanced settings, click Show advanced settings, and specify the following:
+
+* Polling interval: Frequency in which the conditions, combination of counter, operator and threshold, are to be evaluated before taking a scale up or down action. The default polling interval is 30 seconds.
+
+* Quiet Time: This is the cool down period after an AutoScale action is initiated. The time includes the time taken to complete provisioning a VM instance from its template and the time taken by an application to be ready to serve traffic. This quiet time allows the fleet to come up to a stable state before any action can take place. The default is 300 seconds.
+
+* Destroy VM Grace Period: The duration in seconds, after a scaledown action is initiated, to wait before the VM is destroyed as part of scaledown action. This is to ensure graceful close of any pending sessions or transactions being served by the VM marked for destroy. The default is 120 seconds.
+
+* Apply: Click Apply to create the AutoScale configuration.
+
+Disabling and Enabling an AutoScale Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to perform any maintenance operation on the AutoScale VM instances, disable the AutoScale configuration. When the AutoScale configuration is disabled, no scaleup or scaledown action is performed. You can use this downtime for the maintenance activities. To disable the AutoScale configuration, click the Disable AutoScale button.
+
+The button toggles between enable and disable, depending on whether AutoScale is currently enabled or not. After the maintenance operations are done, you can enable the AutoScale configuration back. To enable, open the AutoScale configuration page again, then click the Enable AutoScale button.
+
+Updating an AutoScale Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can update the various parameters and add or delete the conditions in a scaleup or scaledown rule. Before you update an AutoScale configuration, ensure that you disable the AutoScale load balancer rule by clicking the Disable AutoScale button.
+After you modify the required AutoScale parameters, click Apply. To apply the new AutoScale policies, open the AutoScale configuration page again, then click the Enable AutoScale button.
+
+Runtime Considerations
+~~~~~~~~~~~~~~~~~~~~~~
+
+An administrator should not assign a VM to a load balancing rule which is configured for AutoScale.
+
+Making API calls outside the context of AutoScale, such as destroyVM, on an autoscaled VM leaves the load balancing configuration in an inconsistent state. Though VM is destroyed from the load balancer rule, it continues be showed as a service assigned to a rule inside the context of AutoScale.
+
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/networking/midonet.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/midonet.rst b/rtd/source/networking/midonet.rst
new file mode 100644
index 0000000..73d7ab2
--- /dev/null
+++ b/rtd/source/networking/midonet.rst
@@ -0,0 +1,143 @@
+The MidoNet Plugin
+==================
+
+Introduction to the MidoNet Plugin
+----------------------------------
+
+The MidoNet plugin allows CloudStack to use the MidoNet virtualized
+networking solution as a provider for CloudStack networks and services. For
+more information on MidoNet and how it works, see
+http://www.midokura.com/midonet/.
+
+Features of the MidoNet Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: In CloudStack 4.2.0 only the KVM hypervisor is supported for use in
+ combination with MidoNet.
+
+In CloudStack release 4.2.0 this plugin supports several services in the
+Advanced Isolated network mode.
+
+When tenants create new isolated layer 3 networks, instead of spinning
+up extra Virtual Router VMs, the relevant L3 elements (routers etc) are
+created in the MidoNet virtual topology by making the appropriate calls
+to the MidoNet API. Instead of using VLANs, isolation is provided by
+MidoNet.
+
+Aside from the above service (Connectivity), several extra features are
+supported in the 4.2.0 release:
+
+- DHCP
+
+- Firewall (ingress)
+
+- Source NAT
+
+- Static NAT
+
+- Port Forwarding
+
+The plugin has been tested with MidoNet version 12.12. (Caddo).
+
+Using the MidoNet Plugin
+------------------------
+
+Prerequisites
+~~~~~~~~~~~~~
+
+In order to use the MidoNet plugin, the compute hosts must be running
+the MidoNet Agent, and the MidoNet API server must be available. Please
+consult the MidoNet User Guide for more information. The following
+section describes the CloudStack side setup.
+
+1. CloudStack needs to have at least one physical network with the
+ isolation method set to "MIDO". This network should be enabled for
+ the Guest and Public traffic types.
+
+2. Next, we need to set the following CloudStack settings under "Global
+ Settings" in the UI:
+
+ +-----------------------------+------------------------------------------------------------------------+--------------------------------------------+
+ | Setting Name | Description | Example |
+ +=============================+========================================================================+============================================+
+ | midonet.apiserver.address | Specify the address at which the Midonet API server can be contacted | http://192.168.1.144:8081/midolmanj-mgmt |
+ +-----------------------------+------------------------------------------------------------------------+--------------------------------------------+
+ | midonet.providerrouter.id | Specifies the UUID of the Midonet provider router | d7c5e6a3-e2f4-426b-b728-b7ce6a0448e5 |
+ +-----------------------------+------------------------------------------------------------------------+--------------------------------------------+
+
+ Table: CloudStack settings
+
+3. We also want MidoNet to take care of public traffic, so in
+ *componentContext.xml* we need to replace this line:
+
+ ::
+
+ <bean id="PublicNetworkGuru" class="com.cloud.network.guru.PublicNetworkGuru">
+
+
+ With this:
+
+ ::
+
+ <bean id="PublicNetworkGuru" class="com.cloud.network.guru.MidoNetPublicNetworkGuru">
+
+
+.. note:: On the compute host, MidoNet takes advantage of per-traffic type VIF
+ driver support in CloudStack KVM.
+
+ In agent.properties, we set the following to make MidoNet take care
+ of Guest and Public traffic:
+
+ ::
+
+ libvirt.vif.driver.Guest=com.cloud.network.resource.MidoNetVifDriver
+ libvirt.vif.driver.Public=com.cloud.network.resource.MidoNetVifDriver
+
+ This is explained further in MidoNet User Guide.
+
+Enabling the MidoNet service provider via the UI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To allow CloudStack to use the MidoNet Plugin the network service provider
+needs to be enabled on the physical network.
+
+The steps to enable via the UI are as follows:
+
+1. In the left navbar, click Infrastructure
+
+2. In Zones, click View All
+
+3. Click the name of the Zone on which you are setting up MidoNet
+
+4. Click the Physical Network tab
+
+5. Click the Name of the Network on which you are setting up MidoNet
+
+6. Click Configure on the Network Service Providers box
+
+7. Click on the name MidoNet
+
+8. Click the Enable Provider button in the Network tab
+
+Enabling the MidoNet service provider via the API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable via the API, use the following API calls:
+
+*addNetworkServiceProvider*
+
+- name = "MidoNet"
+
+- physicalnetworkid = <the uuid of the physical network>
+
+*updateNetworkServiceProvider*
+
+- id = <the provider uuid returned by the previous call>
+
+- state = "Enabled"
+
+Revision History
+----------------
+
+0-0 Wed Mar 13 2013 Dave Cahill dcahill@midokura.com Documentation
+created for 4.2.0 version of the MidoNet Plugin
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/networking/nicira-plugin.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/nicira-plugin.rst b/rtd/source/networking/nicira-plugin.rst
new file mode 100644
index 0000000..b644f16
--- /dev/null
+++ b/rtd/source/networking/nicira-plugin.rst
@@ -0,0 +1,348 @@
+The Nicira NVP Plugin
+=====================
+
+Introduction to the Nicira NVP Plugin
+-------------------------------------
+
+The Nicira NVP plugin adds Nicira NVP as one of the available SDN
+implementations in CloudStack. With the plugin an exisiting Nicira NVP
+setup can be used by CloudStack to implement isolated guest networks and
+to provide additional services like routing and NAT.
+
+Features of the Nicira NVP Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following table lists the CloudStack network services provided by
+the Nicira NVP Plugin.
+
++----------------------+----------------------+---------------+
+| Network Service | CloudStack version | NVP version |
++======================+======================+===============+
+| Virtual Networking | >= 4.0 | >= 2.2.1 |
++----------------------+----------------------+---------------+
+| Source NAT | >= 4.1 | >= 3.0.1 |
++----------------------+----------------------+---------------+
+| Static NAT | >= 4.1 | >= 3.0.1 |
++----------------------+----------------------+---------------+
+| Port Forwarding | >= 4.1 | >= 3.0.1 |
++----------------------+----------------------+---------------+
+
+Table: Supported Services
+
+.. note:: The Virtual Networking service was originally called 'Connectivity'
+ in CloudStack 4.0
+
+The following hypervisors are supported by the Nicira NVP Plugin.
+
++--------------+----------------------+
+| Hypervisor | CloudStack version |
++==============+======================+
+| XenServer | >= 4.0 |
++--------------+----------------------+
+| KVM | >= 4.1 |
++--------------+----------------------+
+
+Table: Supported Hypervisors
+
+.. note:: Please refer to the Nicira NVP configuration guide on how to prepare
+ the hypervisors for Nicira NVP integration.
+
+Configuring the Nicira NVP Plugin
+---------------------------------
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before enabling the Nicira NVP plugin the NVP Controller needs to be
+configured. Please review the NVP User Guide on how to do that.
+
+Make sure you have the following information ready:
+
+- The IP address of the NVP Controller
+
+- The username to access the API
+
+- The password to access the API
+
+- The UUID of the Transport Zone that contains the hypervisors in this
+ Zone
+
+- The UUID of the Gateway Service used to provide router and NAT
+ services.
+
+
+.. note:: The gateway service uuid is optional and is used for Layer 3
+ services only (SourceNat, StaticNat and PortForwarding)
+
+Zone Configuration
+~~~~~~~~~~~~~~~~~~
+
+CloudStack needs to have at least one physical network with the isolation
+method set to "STT". This network should be enabled for the Guest
+traffic type.
+
+.. note:: The Guest traffic type should be configured with the traffic label
+ that matches the name of the Integration Bridge on the hypervisor.
+ See the Nicira NVP User Guide for more details on how to set this up
+ in XenServer or KVM.
+
+.. figure:: /_static/images/nvp-physical-network-stt.png
+ :align: center
+ :alt: a screenshot of a physical network with the STT isolation type
+
+Enabling the service provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Nicira NVP provider is disabled by default. Navigate to the "Network
+Service Providers" configuration of the physical network with the STT
+isolation type. Navigate to the Nicira NVP provider and press the
+"Enable Provider" button.
+
+.. note:: CloudStack 4.0 does not have the UI interface to configure the
+ Nicira NVP plugin. Configuration needs to be done using the API
+ directly.
+
+.. figure:: /_static/images/nvp-physical-network-stt.png
+ :align: center
+ :alt: a screenshot of an enabled Nicira NVP provider
+
+Device Management
+~~~~~~~~~~~~~~~~~
+
+In CloudStack a Nicira NVP setup is considered a "device" that can be added
+and removed from a physical network. To complete the configuration of
+the Nicira NVP plugin a device needs to be added to the physical
+network. Press the "Add NVP Controller" button on the provider panel and
+enter the configuration details.
+
+.. figure:: /_static/images/nvp-physical-network-stt.png
+ :align: center
+ :alt: a screenshot of the device configuration popup.
+
+Network Offerings
+~~~~~~~~~~~~~~~~~
+
+Using the Nicira NVP plugin requires a network offering with Virtual
+Networking enabled and configured to use the NiciraNvp element. Typical
+use cases combine services from the Virtual Router appliance and the
+Nicira NVP plugin.
+
++----------------------+-----------------+
+| Service | Provider |
++======================+=================+
+| VPN | VirtualRouter |
++----------------------+-----------------+
+| DHCP | VirtualRouter |
++----------------------+-----------------+
+| DNS | VirtualRouter |
++----------------------+-----------------+
+| Firewall | VirtualRouter |
++----------------------+-----------------+
+| Load Balancer | VirtualRouter |
++----------------------+-----------------+
+| User Data | VirtualRouter |
++----------------------+-----------------+
+| Source NAT | VirtualRouter |
++----------------------+-----------------+
+| Static NAT | VirtualRouter |
++----------------------+-----------------+
+| Post Forwarding | VirtualRouter |
++----------------------+-----------------+
+| Virtual Networking | NiciraNVP |
++----------------------+-----------------+
+
+Table: Isolated network offering with regular services from the Virtual
+Router.
+
+.. figure:: /_static/images/nvp-physical-network-stt.png
+ :align: center
+ :alt: a screenshot of a network offering.
+
+
+.. note:: The tag in the network offering should be set to the name of the
+ physical network with the NVP provider.
+
+Isolated network with network services. The virtual router is still
+required to provide network services like dns and dhcp.
+
++----------------------+-----------------+
+| Service | Provider |
++======================+=================+
+| DHCP | VirtualRouter |
++----------------------+-----------------+
+| DNS | VirtualRouter |
++----------------------+-----------------+
+| User Data | VirtualRouter |
++----------------------+-----------------+
+| Source NAT | NiciraNVP |
++----------------------+-----------------+
+| Static NAT | NiciraNVP |
++----------------------+-----------------+
+| Post Forwarding | NiciraNVP |
++----------------------+-----------------+
+| Virtual Networking | NiciraNVP |
++----------------------+-----------------+
+
+Table: Isolated network offering with network services
+
+Using the Nicira NVP plugin with VPC
+------------------------------------
+
+Supported VPC features
+~~~~~~~~~~~~~~~~~~~~~~
+
+The Nicira NVP plugin supports CloudStack VPC to a certain extent. Starting
+with CloudStack version 4.1 VPCs can be deployed using NVP isolated
+networks.
+
+It is not possible to use a Nicira NVP Logical Router for as a VPC
+Router
+
+It is not possible to connect a private gateway using a Nicira NVP
+Logical Switch
+
+VPC Offering with Nicira NVP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To allow a VPC to use the Nicira NVP plugin to provision networks, a new
+VPC offering needs to be created which allows the Virtual Networking
+service to be implemented by NiciraNVP.
+
+This is not currently possible with the UI. The API does provide the
+proper calls to create a VPC offering with Virtual Networking enabled.
+However due to a limitation in the 4.1 API it is not possible to select
+the provider for this network service. To configure the VPC offering
+with the NiciraNVP provider edit the database table
+'vpc\_offering\_service\_map' and change the provider to NiciraNvp for
+the service 'Connectivity'
+
+It is also possible to update the default VPC offering by adding a row
+to the 'vpc\_offering\_service\_map' with service 'Connectivity' and
+provider 'NiciraNvp'
+
+.. figure:: /_static/images/nvp-physical-network-stt.png
+ :align: center
+ :alt: a screenshot of the mysql table.
+
+
+.. note:: When creating a new VPC offering please note that the UI does not
+ allow you to select a VPC offering yet. The VPC needs to be created
+ using the API with the offering UUID.
+
+VPC Network Offerings
+~~~~~~~~~~~~~~~~~~~~~
+
+The VPC needs specific network offerings with the VPC flag enabled.
+Otherwise these network offerings are identical to regular network
+offerings. To allow VPC networks with a Nicira NVP isolated network the
+offerings need to support the Virtual Networking service with the
+NiciraNVP provider.
+
+In a typical configuration two network offerings need to be created. One
+with the loadbalancing service enabled and one without loadbalancing.
+
++----------------------+--------------------+
+| Service | Provider |
++======================+====================+
+| VPN | VpcVirtualRouter |
++----------------------+--------------------+
+| DHCP | VpcVirtualRouter |
++----------------------+--------------------+
+| DNS | VpcVirtualRouter |
++----------------------+--------------------+
+| Load Balancer | VpcVirtualRouter |
++----------------------+--------------------+
+| User Data | VpcVirtualRouter |
++----------------------+--------------------+
+| Source NAT | VpcVirtualRouter |
++----------------------+--------------------+
+| Static NAT | VpcVirtualRouter |
++----------------------+--------------------+
+| Post Forwarding | VpcVirtualRouter |
++----------------------+--------------------+
+| NetworkACL | VpcVirtualRouter |
++----------------------+--------------------+
+| Virtual Networking | NiciraNVP |
++----------------------+--------------------+
+
+Table: VPC Network Offering with Loadbalancing
+
+Troubleshooting the Nicira NVP Plugin
+-------------------------------------
+
+UUID References
+~~~~~~~~~~~~~~~
+
+The plugin maintains several references in the CloudStack database to items
+created on the NVP Controller.
+
+Every guest network that is created will have its broadcast type set to
+Lswitch and if the network is in state "Implemented", the broadcast URI
+will have the UUID of the Logical Switch that was created for this
+network on the NVP Controller.
+
+The Nics that are connected to one of the Logical Switches will have
+their Logical Switch Port UUID listed in the nicira\_nvp\_nic\_map table
+
+.. note:: All devices created on the NVP Controller will have a tag set to
+ domain-account of the owner of the network, this string can be used
+ to search for items in the NVP Controller.
+
+Database tables
+~~~~~~~~~~~~~~~
+
+The following tables are added to the cloud database for the Nicira NVP
+Plugin
+
++---------------------+--------------------------------------------------------------+
+| id | auto incrementing id |
++---------------------+--------------------------------------------------------------+
+| logicalswitch | uuid of the logical switch this port is connected to |
++---------------------+--------------------------------------------------------------+
+| logicalswitchport | uuid of the logical switch port for this nic |
++---------------------+--------------------------------------------------------------+
+| nic | the CloudStack uuid for this nic, reference to the nics table|
++---------------------+--------------------------------------------------------------+
+
+Table: nicira\_nvp\_nic\_map
+
++-------------------------+-------------------------------------------------------------+
+| id | auto incrementing id |
++-------------------------+-------------------------------------------------------------+
+| uuid | UUID identifying this device |
++-------------------------+-------------------------------------------------------------+
+| physical\_network\_id | the physical network this device is configured on |
++-------------------------+-------------------------------------------------------------+
+| provider\_name | NiciraNVP |
++-------------------------+-------------------------------------------------------------+
+| device\_name | display name for this device |
++-------------------------+-------------------------------------------------------------+
+| host\_id | reference to the host table with the device configuration |
++-------------------------+-------------------------------------------------------------+
+
+Table: external\_nicira\_nvp\_devices
+
++-----------------------+----------------------------------------------+
+| id | auto incrementing id |
++-----------------------+----------------------------------------------+
+| logicalrouter\_uuid | uuid of the logical router |
++-----------------------+----------------------------------------------+
+| network\_id | id of the network this router is linked to |
++-----------------------+----------------------------------------------+
+
+Table: nicira\_nvp\_router\_map
+
+.. note:: nicira\_nvp\_router\_map is only available in CloudStack 4.1 and above
+
+Revision History
+----------------
+
+0-0 Wed Oct 03 2012 Hugo Trippaers hugo@apache.org Documentation created
+for 4.0.0-incubating version of the NVP Plugin 1-0 Wed May 22 2013 Hugo
+Trippaers hugo@apache.org Documentation updated for CloudStack 4.1.0
+
+.. | nvp-physical-network-stt.png: a screenshot of a physical network with the STT isolation type | image:: ./images/nvp-physical-network-stt.png
+.. | nvp-physical-network-stt.png: a screenshot of an enabled Nicira NVP provider | image:: ./images/nvp-enable-provider.png
+.. | nvp-physical-network-stt.png: a screenshot of the device configuration popup. | image:: ./images/nvp-add-controller.png
+.. | nvp-physical-network-stt.png: a screenshot of a network offering. | image:: ./images/nvp-network-offering.png
+.. | nvp-physical-network-stt.png: a screenshot of the mysql table. | image:: ./images/nvp-vpc-offering-edit.png
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/networking/ovs-plugin.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/ovs-plugin.rst b/rtd/source/networking/ovs-plugin.rst
new file mode 100644
index 0000000..495b304
--- /dev/null
+++ b/rtd/source/networking/ovs-plugin.rst
@@ -0,0 +1,229 @@
+The OVS Plugin
+==============
+
+Introduction to the OVS Plugin
+------------------------------
+
+The OVS plugin is the native SDN
+implementations in CloudStack, using GRE isolation method. The plugin can be used by CloudStack to implement isolated guest networks and
+to provide additional services like NAT, port forwarding and load balancing.
+
+Features of the OVS Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following table lists the CloudStack network services provided by
+the OVS Plugin.
+
++----------------------+----------------------+
+| Network Service | CloudStack version |
++======================+======================+
+| Virtual Networking | >= 4.0 |
++----------------------+----------------------+
+| Static NAT | >= 4.3 |
++----------------------+----------------------+
+| Port Forwarding | >= 4.3 |
++----------------------+----------------------+
+| Load Balancing | >= 4.3 |
++----------------------+----------------------+
+
+Table: Supported Services
+
+.. note:: The Virtual Networking service was originally called 'Connectivity'
+ in CloudStack 4.0
+
+The following hypervisors are supported by the OVS Plugin.
+
++--------------+----------------------+
+| Hypervisor | CloudStack version |
++==============+======================+
+| XenServer | >= 4.0 |
++--------------+----------------------+
+| KVM | >= 4.3 |
++--------------+----------------------+
+
+Table: Supported Hypervisors
+
+
+Configuring the OVS Plugin
+--------------------------
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before enabling the OVS plugin the hypervisor needs to be install OpenvSwitch. Default, XenServer has already installed OpenvSwitch. However, you must install OpenvSwitch manually on KVM. CentOS 6.4 and OpenvSwitch 1.10 are recommended.
+
+KVM hypervisor:
+
+- CentOS 6.4 is recommended.
+- To make sure that the native bridge module will not interfere with openvSwitch the bridge module should be added to the blacklist. See the modprobe documentation for your distribution on where to find the blacklist. Make sure the module is not loaded either by rebooting or executing rmmod bridge before executing next steps.
+
+
+Zone Configuration
+~~~~~~~~~~~~~~~~~~
+
+CloudStack needs to have at least one physical network with the isolation
+method set to “GRE”. This network should be enabled for the Guest
+traffic type.
+
+.. note::
+ With KVM, the traffic type should be configured with the traffic label
+ that matches the name of the Integration Bridge on the hypervisor. For example, you should set the traffic label as following:
+ - Management & Storage traffic: cloudbr0
+ - Guest & Public traffic: cloudbr1
+ See KVM networking configuration guide for more detail.
+
+
+.. figure:: /_static/images/ovs-physical-network-gre.png
+ :align: center
+ :alt: a screenshot of a physical network with the GRE isolation type
+
+Agent Configuration
+~~~~~~~~~~~~~~~~~~~
+
+.. note:: Only for KVM hypervisor
+
+* Configure network interfaces:
+
+::
+
+ /etc/sysconfig/network-scripts/ifcfg-eth0
+ DEVICE=eth0
+ BOOTPROTO=none
+ IPV6INIT=no
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ TYPE=OVSPort
+ DEVICETYPE=ovs
+ OVS_BRIDGE=cloudbr0
+
+ /etc/sysconfig/network-scripts/ifcfg-eth1
+ DEVICE=eth1
+ BOOTPROTO=none
+ IPV6INIT=no
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ TYPE=OVSPort
+ DEVICETYPE=ovs
+ OVS_BRIDGE=cloudbr1
+
+ /etc/sysconfig/network-scripts/ifcfg-cloudbr0
+ DEVICE=cloudbr0
+ ONBOOT=yes
+ DEVICETYPE=ovs
+ TYPE=OVSBridge
+ BOOTPROTO=static
+ IPADDR=172.16.10.10
+ GATEWAY=172.16.10.1
+ NETMASK=255.255.255.0
+ HOTPLUG=no
+
+ /etc/sysconfig/network-scripts/ifcfg-cloudbr1
+ DEVICE=cloudbr1
+ ONBOOT=yes
+ DEVICETYPE=ovs
+ TYPE=OVSBridge
+ BOOTPROTO=none
+ HOTPLUG=no
+
+ /etc/sysconfig/network
+ NETWORKING=yes
+ HOSTNAME=testkvm1
+ GATEWAY=172.10.10.1
+
+* Edit /etc/cloudstack/agent/agent.properties
+
+::
+
+ network.bridge.type=openvswitch
+ libvirt.vif.driver=com.cloud.hypervisor.kvm.resource.OvsVifDriver
+
+Enabling the service provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The OVS provider is disabled by default. Navigate to the "Network
+Service Providers" configuration of the physical network with the GRE
+isolation type. Navigate to the OVS provider and press the
+"Enable Provider" button.
+
+.. figure:: /_static/images/ovs-physical-network-gre-enable.png
+ :align: center
+ :alt: a screenshot of an enabled OVS provider
+
+Network Offerings
+~~~~~~~~~~~~~~~~~
+
+Using the OVS plugin requires a network offering with Virtual
+Networking enabled and configured to use the OVS element. Typical
+use cases combine services from the Virtual Router appliance and the
+OVS plugin.
+
++----------------------+-----------------+
+| Service | Provider |
++======================+=================+
+| VPN | VirtualRouter |
++----------------------+-----------------+
+| DHCP | VirtualRouter |
++----------------------+-----------------+
+| DNS | VirtualRouter |
++----------------------+-----------------+
+| Firewall | VirtualRouter |
++----------------------+-----------------+
+| Load Balancer | OVS |
++----------------------+-----------------+
+| User Data | VirtualRouter |
++----------------------+-----------------+
+| Source NAT | VirtualRouter |
++----------------------+-----------------+
+| Static NAT | OVS |
++----------------------+-----------------+
+| Post Forwarding | OVS |
++----------------------+-----------------+
+| Virtual Networking | OVS |
++----------------------+-----------------+
+
+Table: Isolated network offering with regular services from the Virtual
+Router.
+
+.. figure:: /_static/images/ovs-network-offering.png
+ :align: center
+ :alt: a screenshot of a network offering.
+
+
+.. note:: The tag in the network offering should be set to the name of the
+ physical network with the OVS provider.
+
+Isolated network with network services. The virtual router is still
+required to provide network services like dns and dhcp.
+
++----------------------+-----------------+
+| Service | Provider |
++======================+=================+
+| DHCP | VirtualRouter |
++----------------------+-----------------+
+| DNS | VirtualRouter |
++----------------------+-----------------+
+| User Data | VirtualRouter |
++----------------------+-----------------+
+| Source NAT | VirtualRouter |
++----------------------+-----------------+
+| Static NAT | OVS |
++----------------------+-----------------+
+| Post Forwarding | OVS |
++----------------------+-----------------+
+| Load Balancing | OVS |
++----------------------+-----------------+
+| Virtual Networking | OVS |
++----------------------+-----------------+
+
+Table: Isolated network offering with network services
+
+Using the OVS plugin with VPC
+-----------------------------
+
+OVS plugin does not work with VPC at that time
+
+Revision History
+----------------
+
+0-0 Mon Dec 2 2013 Nguyen Anh Tu tuna@apache.org Documentation
+created for 4.3.0 version of the OVS Plugin
[3/3] git commit: Create RTD docs
Posted by se...@apache.org.
Create RTD docs
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/5fddad01
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/5fddad01
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/5fddad01
Branch: refs/heads/master
Commit: 5fddad01e28809206e75b2127b545822411dc1aa
Parents: bcf67dd
Author: Sebastien Goasguen <ru...@gmail.com>
Authored: Thu Feb 20 18:15:24 2014 +0100
Committer: Sebastien Goasguen <ru...@gmail.com>
Committed: Thu Feb 20 18:15:24 2014 +0100
----------------------------------------------------------------------
rtd/.gitignore | 17 +
rtd/LICENSE | 202 ++++++
rtd/Makefile | 193 ++++++
rtd/README.rst | 41 ++
rtd/source/_static/images/acslogo.png | Bin 0 -> 135394 bytes
rtd/source/_static/images/autoscale-config.png | Bin 0 -> 39379 bytes
rtd/source/_static/images/basic-deployment.png | Bin 0 -> 5892 bytes
.../_static/images/networking-egress-rule.png | Bin 0 -> 39649 bytes
.../images/networking-infra-traffic-labels.png | Bin 0 -> 92572 bytes
.../_static/images/networking-ingress-rule.png | Bin 0 -> 44719 bytes
.../images/networking-zone-traffic-labels.png | Bin 0 -> 247970 bytes
.../_static/images/nvp-add-controller.png | Bin 0 -> 35928 bytes
.../_static/images/nvp-enable-provider.png | Bin 0 -> 32158 bytes
.../_static/images/nvp-network-offering.png | Bin 0 -> 104060 bytes
.../_static/images/nvp-physical-network-stt.png | Bin 0 -> 27317 bytes
.../_static/images/nvp-vpc-offering-edit.png | Bin 0 -> 29279 bytes
.../_static/images/ovs-network-offering.png | Bin 0 -> 113750 bytes
.../images/ovs-physical-network-gre-enable.png | Bin 0 -> 41642 bytes
.../_static/images/ovs-physical-network-gre.png | Bin 0 -> 17354 bytes
rtd/source/_static/images/pod-overview.png | Bin 0 -> 6036 bytes
rtd/source/_static/images/region-overview.png | Bin 0 -> 22835 bytes
.../_static/images/vxlan-physicalnetwork.png | Bin 0 -> 68376 bytes
.../_static/images/vxlan-trafficlabel.png | Bin 0 -> 61473 bytes
rtd/source/_static/images/vxlan-vniconfig.png | Bin 0 -> 18161 bytes
rtd/source/_static/images/zone-overview.png | Bin 0 -> 11852 bytes
rtd/source/administration_guide.rst | 443 +++++++++++++
rtd/source/alloc.rst | 292 +++++++++
rtd/source/ansible.rst | 412 ++++++++++++
rtd/source/conf.py | 344 ++++++++++
rtd/source/developer_guide.rst | 653 +++++++++++++++++++
rtd/source/index.rst | 48 ++
.../networking/autoscale_without_netscaler.rst | 85 +++
rtd/source/networking/midonet.rst | 143 ++++
rtd/source/networking/nicira-plugin.rst | 348 ++++++++++
rtd/source/networking/ovs-plugin.rst | 229 +++++++
.../troubleshoot_internet_traffic.rst | 216 ++++++
rtd/source/networking/vxlan.rst | 376 +++++++++++
37 files changed, 4042 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/.gitignore
----------------------------------------------------------------------
diff --git a/rtd/.gitignore b/rtd/.gitignore
new file mode 100644
index 0000000..b885e35
--- /dev/null
+++ b/rtd/.gitignore
@@ -0,0 +1,17 @@
+# 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.
+
+/build
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/LICENSE
----------------------------------------------------------------------
diff --git a/rtd/LICENSE b/rtd/LICENSE
new file mode 100644
index 0000000..e06d208
--- /dev/null
+++ b/rtd/LICENSE
@@ -0,0 +1,202 @@
+Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "{}"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright {yyyy} {name of copyright owner}
+
+ Licensed 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.
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/Makefile
----------------------------------------------------------------------
diff --git a/rtd/Makefile b/rtd/Makefile
new file mode 100644
index 0000000..e1d6dd9
--- /dev/null
+++ b/rtd/Makefile
@@ -0,0 +1,193 @@
+# 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.
+#
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ApacheCloudStack.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ApacheCloudStack.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/ApacheCloudStack"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ApacheCloudStack"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/README.rst
----------------------------------------------------------------------
diff --git a/rtd/README.rst b/rtd/README.rst
new file mode 100644
index 0000000..9aa0887
--- /dev/null
+++ b/rtd/README.rst
@@ -0,0 +1,41 @@
+.. 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.
+
+Apache CloudStack
+=================
+
+Apache CloudStack is an Apache project, see <http://cloudstack.apache.org> for
+more information.
+
+Website
+=============
+
+These docs are on-line at <http://docs.cloudstack.apache.org/en/latest/>
+
+Feedback
+========
+
+Please send feedback to the mailing list at <de...@cloudstack.apache.org>,
+or the JIRA at <https://issues.apache.org/jira/browse/CLOUDSTACK>.
+
+Contributing
+============
+
+You can submit a pull request via github or submit patches via review board <https://reviews.apache.org>
+
+For information on how to contribute, please see the Contributing
+chapter in our documentation <http://cloudstack.apache.org/developers.html>
+
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/acslogo.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/acslogo.png b/rtd/source/_static/images/acslogo.png
new file mode 100644
index 0000000..a938231
Binary files /dev/null and b/rtd/source/_static/images/acslogo.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/autoscale-config.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/autoscale-config.png b/rtd/source/_static/images/autoscale-config.png
new file mode 100644
index 0000000..735ae96
Binary files /dev/null and b/rtd/source/_static/images/autoscale-config.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/basic-deployment.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/basic-deployment.png b/rtd/source/_static/images/basic-deployment.png
new file mode 100644
index 0000000..894a053
Binary files /dev/null and b/rtd/source/_static/images/basic-deployment.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/networking-egress-rule.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/networking-egress-rule.png b/rtd/source/_static/images/networking-egress-rule.png
new file mode 100644
index 0000000..edf1f6d
Binary files /dev/null and b/rtd/source/_static/images/networking-egress-rule.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/networking-infra-traffic-labels.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/networking-infra-traffic-labels.png b/rtd/source/_static/images/networking-infra-traffic-labels.png
new file mode 100644
index 0000000..e029d7d
Binary files /dev/null and b/rtd/source/_static/images/networking-infra-traffic-labels.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/networking-ingress-rule.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/networking-ingress-rule.png b/rtd/source/_static/images/networking-ingress-rule.png
new file mode 100644
index 0000000..8b1af22
Binary files /dev/null and b/rtd/source/_static/images/networking-ingress-rule.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/networking-zone-traffic-labels.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/networking-zone-traffic-labels.png b/rtd/source/_static/images/networking-zone-traffic-labels.png
new file mode 100644
index 0000000..1587c2b
Binary files /dev/null and b/rtd/source/_static/images/networking-zone-traffic-labels.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/nvp-add-controller.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/nvp-add-controller.png b/rtd/source/_static/images/nvp-add-controller.png
new file mode 100644
index 0000000..e02d31f
Binary files /dev/null and b/rtd/source/_static/images/nvp-add-controller.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/nvp-enable-provider.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/nvp-enable-provider.png b/rtd/source/_static/images/nvp-enable-provider.png
new file mode 100644
index 0000000..0f2d02d
Binary files /dev/null and b/rtd/source/_static/images/nvp-enable-provider.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/nvp-network-offering.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/nvp-network-offering.png b/rtd/source/_static/images/nvp-network-offering.png
new file mode 100644
index 0000000..c2d25c4
Binary files /dev/null and b/rtd/source/_static/images/nvp-network-offering.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/nvp-physical-network-stt.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/nvp-physical-network-stt.png b/rtd/source/_static/images/nvp-physical-network-stt.png
new file mode 100644
index 0000000..2ce7853
Binary files /dev/null and b/rtd/source/_static/images/nvp-physical-network-stt.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/nvp-vpc-offering-edit.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/nvp-vpc-offering-edit.png b/rtd/source/_static/images/nvp-vpc-offering-edit.png
new file mode 100644
index 0000000..ff235e2
Binary files /dev/null and b/rtd/source/_static/images/nvp-vpc-offering-edit.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/ovs-network-offering.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/ovs-network-offering.png b/rtd/source/_static/images/ovs-network-offering.png
new file mode 100644
index 0000000..750c5f0
Binary files /dev/null and b/rtd/source/_static/images/ovs-network-offering.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/ovs-physical-network-gre-enable.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/ovs-physical-network-gre-enable.png b/rtd/source/_static/images/ovs-physical-network-gre-enable.png
new file mode 100644
index 0000000..40c5418
Binary files /dev/null and b/rtd/source/_static/images/ovs-physical-network-gre-enable.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/ovs-physical-network-gre.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/ovs-physical-network-gre.png b/rtd/source/_static/images/ovs-physical-network-gre.png
new file mode 100644
index 0000000..1e8bb00
Binary files /dev/null and b/rtd/source/_static/images/ovs-physical-network-gre.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/pod-overview.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/pod-overview.png b/rtd/source/_static/images/pod-overview.png
new file mode 100644
index 0000000..c180060
Binary files /dev/null and b/rtd/source/_static/images/pod-overview.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/region-overview.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/region-overview.png b/rtd/source/_static/images/region-overview.png
new file mode 100644
index 0000000..528445c
Binary files /dev/null and b/rtd/source/_static/images/region-overview.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/vxlan-physicalnetwork.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/vxlan-physicalnetwork.png b/rtd/source/_static/images/vxlan-physicalnetwork.png
new file mode 100644
index 0000000..eb06fcd
Binary files /dev/null and b/rtd/source/_static/images/vxlan-physicalnetwork.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/vxlan-trafficlabel.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/vxlan-trafficlabel.png b/rtd/source/_static/images/vxlan-trafficlabel.png
new file mode 100644
index 0000000..916e944
Binary files /dev/null and b/rtd/source/_static/images/vxlan-trafficlabel.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/vxlan-vniconfig.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/vxlan-vniconfig.png b/rtd/source/_static/images/vxlan-vniconfig.png
new file mode 100644
index 0000000..c7372a0
Binary files /dev/null and b/rtd/source/_static/images/vxlan-vniconfig.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/_static/images/zone-overview.png
----------------------------------------------------------------------
diff --git a/rtd/source/_static/images/zone-overview.png b/rtd/source/_static/images/zone-overview.png
new file mode 100644
index 0000000..24aeecf
Binary files /dev/null and b/rtd/source/_static/images/zone-overview.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/administration_guide.rst
----------------------------------------------------------------------
diff --git a/rtd/source/administration_guide.rst b/rtd/source/administration_guide.rst
new file mode 100644
index 0000000..c79632a
--- /dev/null
+++ b/rtd/source/administration_guide.rst
@@ -0,0 +1,443 @@
+Apache CloudStack Administration Guide
+======================================
+
+Backups
+-------
+
+Monitoring
+----------
+
+SNMP
+____
+
+CloudStack will send alerts for a number of
+
+Syslog
+_______
+
+AMQP
+_____
+
+JMX
+____
+
+API Queries
+___________
+
+
+Usage
+-----
+
+Tuning
+------
+
+Configuration Parameters
+------------------------
+
+System Reliability and Availability
+-----------------------------------
+
+HA for Management Server
+_________________________
+
+The CloudStack Management Server should be deployed in a multi-node configuration such that it is not susceptible to individual server failures. The Management Server itself (as distinct from the MySQL database) is stateless and may be placed behind a load balancer.
+
+Normal operation of Hosts is not impacted by an outage of all Management Serves. All guest VMs will continue to work.
+
+When the Management Server is down, no new VMs can be created, and the end user and admin UI, API, dynamic load distribution, and HA will cease to work.
+
+Management Server Load Balancing
+________________________________
+
+CloudStack can use a load balancer to provide a virtual IP for multiple Management Servers. The administrator is responsible for creating the load balancer rules for the Management Servers. The application requires persistence or stickiness across multiple sessions. The following chart lists the ports that should be load balanced and whether or not persistence is required.
+
+============ ======================== ============== ======================
+Source port Destination port Protocol Persistence Required?
+============ ======================== ============== ======================
+80 or 443 8080 (or 20400 with AJP) HTTP (or AJP) Yes
+8250 8250 TCP Yes
+============ ======================== ============== ======================
+
+In addition to above settings, the administrator is responsible for setting the 'host' global config value from the management server IP to load balancer virtual IP address. If the 'host' value is not set to the VIP for Port 8250 and one of your management servers crashes, the UI is still available but the system VMs will not be able to contact the management server.
+
+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:
+
+* 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.
+
+HA-Enabled Virtual Machines
+___________________________
+
+The user can specify a virtual machine as HA-enabled. By default, all virtual router VMs and Elastic Load Balancing VMs are automatically configured as HA-enabled. When an HA-enabled VM crashes, CloudStack detects the crash and restarts the VM automatically within the same Availability Zone. HA is never performed across different Availability Zones. CloudStack has a conservative policy towards restarting VMs and ensures that there will never be two instances of the same VM running at the same time. The Management Server attempts to start the VM on another Host in the same cluster.
+
+VM HA is not supported when the VM is using local storage.
+
+Dedicated HA Hosts
+~~~~~~~~~~~~~~~~~~
+
+One or more hosts can be designated for use only by HA-enabled VMs that are restarting due to a host failure. Setting up a pool of such dedicated HA hosts as the recovery destination for all HA-enabled VMs is useful to:
+
+#. Make it easier to determine which VMs have been restarted as part of the CloudStack high-availability function. If a VM is running on a dedicated HA host, then it must be an HA-enabled VM whose original host failed. (With one exception: It is possible for an administrator to manually migrate any VM to a dedicated HA host.).
+#. Keep HA-enabled VMs from restarting on hosts which may be reserved for other purposes.
+
+The dedicated HA option is set through a special host tag when the host is created. To allow the administrator to dedicate hosts to only HA-enabled VMs, set the global configuration variable ha.tag to the desired tag (for example, "ha_host"), and restart the Management Server. Enter the value in the Host Tags field when adding the host(s) that you want to dedicate to HA-enabled VMs.
+
+Primary Storage Outage and Data Loss
+____________________________________
+
+When a primary storage outage occurs the hypervisor immediately stops all VMs stored on that storage device. Guests that are marked for HA will be restarted as soon as practical when the primary storage comes back on line. With NFS, the hypervisor may allow the virtual machines to continue running depending on the nature of the issue. For example, an NFS hang will cause the guest VMs to be suspended until storage connectivity is restored.Primary storage is not designed to be backed up. Individual volumes in primary storage can be backed up using snapshots.
+
+Secondary Storage Outage and Data Loss
+______________________________________
+
+For a Zone that has only one secondary storage server, a secondary storage outage will have feature level impact to the system but will not impact running guest VMs. It may become impossible to create a VM with the selected template for a user. A user may also not be able to save snapshots or examine/restore saved snapshots. These features will automatically be available when the secondary storage comes back online.
+
+Secondary storage data loss will impact recently added user data including templates, snapshots, and ISO images. Secondary storage should be backed up periodically. Multiple secondary storage servers can be provisioned within each zone to increase the scalability of the system.
+
+Managing System VMs
+-------------------
+
+CloudStack uses several types of system virtual machines to perform tasks in the cloud. In general CloudStack manages these system VMs and creates, starts, and stops them as needed based on scale and immediate needs. However, the administrator should be aware of them and their roles to assist in debugging issues.
+
+You can configure the system.vm.random.password parameter to create a random system VM password to ensure higher security. If you reset the value for system.vm.random.password to true and restart the Management Server, a random password is generated and stored encrypted in the database. You can view the decrypted password under the system.vm.password global parameter on the CloudStack UI or by calling the listConfigurations API.
+
+The System VM Template
+______________________
+
+The System VMs come from a single template. The System VM has the following characteristics:
+
+* Debian 6.0 ("Squeeze"), 2.6.32 kernel with the latest security patches from the Debian security APT repository
+* Has a minimal set of packages installed thereby reducing the attack surface
+* 32-bit for enhanced performance on Xen/VMWare
+* pvops kernel with Xen PV drivers, KVM virtio drivers, and VMware tools for optimum performance on all hypervisors
+* Xen tools inclusion allows performance monitoring
+* Latest versions of HAProxy, iptables, IPsec, and Apache from debian repository ensures improved security and speed
+* Latest version of JRE from Sun/Oracle ensures improved security and speed
+
+Accessing System VMs
+____________________
+
+It may sometimes be necessary to access System VMs for diagnostics of certain issues, for example if you are experiencing SSVM (Secondary Storage VM) connection issues. Use the steps below in order to connect to the SSH console of a running System VM.
+
+Accessing System VMs over the network requires the use of private keys and connecting to System VMs SSH Daemon on port 3922. XenServer/KVM Hypervisors store this key at /root/.ssh/id_rsa.cloud on each CloudStack agent. To access System VMs running on ESXi, the key is stored on the management server at /var/lib/cloudstack/management/.ssh/id_rsa.
+
+#. Find the details of the System VM
+ #. Log in with admin privileges to the CloudStack UI.
+ #. Click Infrastructure, then System VMs, and then click the name of a running VM.
+ #. Take a note of the 'Host', 'Private IP Address' and 'Link Local IP Address' of the System VM you wish to access.
+#. XenServer/KVM Hypervisors
+ #. Connect to the Host of which the System VM is running.
+ #. SSH to the 'Link Local IP Address' of the System VM from the Host on which the VM is running.
+ Format: ssh -i <path-to-private-key> <link-local-ip> -p 3922
+ Example: root@faith:~# ssh -i /root/.ssh/id_rsa.cloud 169.254.3.93 -p 3922
+#. ESXi Hypervisors
+ #. Connect to your CloudStack Management Server.
+ #. ESXi users should SSH to the private IP address of the System VM.
+ Format: ssh -i <path-to-private-key> <vm-private-ip> -p 3922
+ Example: root@management:~# ssh -i /var/lib/cloudstack/management/.ssh/id_rsa 172.16.0.250 -p 3922
+
+Multiple System VM Support for VMware
+______________________________________
+
+Every CloudStack zone has single System VM for template processing tasks such as downloading templates, uploading templates, and uploading ISOs. In a zone where VMware is being used, additional System VMs can be launched to process VMware-specific tasks such as taking snapshots and creating private templates. The CloudStack management server launches additional System VMs for VMware-specific tasks as the load increases. The management server monitors and weights all commands sent to these System VMs and performs dynamic load balancing and scaling-up of more System VMs.
+
+Console Proxy
+_____________
+
+The Console Proxy is a type of System Virtual Machine that has a role in presenting a console view via the web UI. It connects the user’s browser to the VNC port made available via the hypervisor for the console of the guest. Both the administrator and end user web UIs offer a console connection.
+
+Clicking a console icon brings up a new window. The AJAX code downloaded into that window refers to the public IP address of a console proxy VM. There is exactly one public IP address allocated per console proxy VM. The AJAX application connects to this IP. The console proxy then proxies the connection to the VNC port for the requested VM on the Host hosting the guest.
+
+The console proxy VM will periodically report its active session count to the Management Server. The default reporting interval is five seconds. This can be changed through standard Management Server configuration with the parameter consoleproxy.loadscan.interval.
+
+Assignment of guest VM to console proxy is determined by first determining if the guest VM has a previous session associated with a console proxy. If it does, the Management Server will assign the guest VM to the target Console Proxy VM regardless of the load on the proxy VM. Failing that, the first available running Console Proxy VM that has the capacity to handle new sessions is used.
+
+Console proxies can be restarted by administrators but this will interrupt existing console sessions for users.
+
+Using a SSL Certificate for the Console Proxy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The console viewing functionality uses a dynamic DNS service under the domain name realhostip.com to assist in providing SSL security to console sessions. The console proxy is assigned a public IP address. In order to avoid browser warnings for mismatched SSL certificates, the URL for the new console window is set to the form of https://aaa-bbb-ccc-ddd.realhostip.com. You will see this URL during console session creation. CloudStack includes the realhostip.com SSL certificate in the console proxy VM. Of course, CloudStack cannot know about the DNS A records for our customers' public IPs prior to shipping the software. CloudStack therefore runs a dynamic DNS server that is authoritative for the realhostip.com domain. It maps the aaa-bbb-ccc-ddd part of the DNS name to the IP address aaa.bbb.ccc.ddd on lookups. This allows the browser to correctly connect to the console proxy's public IP, where it then expects and receives a SSL certificate for realhostip.com, and SSL is set up withou
t browser warnings.
+
+Changing the Console Proxy SSL Certificate and Domain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the administrator prefers, it is possible for the URL of the customer's console session to show a domain other than realhostip.com. The administrator can customize the displayed domain by selecting a different domain and uploading a new SSL certificate and private key. The domain must run a DNS service that is capable of resolving queries for addresses of the form aaa-bbb-ccc-ddd.your.domain to an IPv4 IP address in the form aaa.bbb.ccc.ddd, for example, 202.8.44.1. To change the console proxy domain, SSL certificate, and private key:
+
+#. Set up dynamic name resolution or populate all possible DNS names in your public IP range into your existing DNS server with the format aaa-bbb-ccc-ddd.company.com -> aaa.bbb.ccc.ddd.
+#. Generate the private key and certificate signing request (CSR). When you are using openssl to generate private/public key pairs and CSRs, for the private key that you are going to paste into the CloudStack UI, be sure to convert it into PKCS#8 format.
+
+ 1. Generate a new 2048-bit private key::
+
+ openssl genrsa -des3 -out yourprivate.key 2048
+
+ 2. Generate a new certificate CSR::
+
+ openssl req -new -key yourprivate.key -out yourcertificate.csr
+
+ 3. Head to the website of your favorite trusted Certificate Authority, purchase an SSL certificate, and submit the CSR. You should receive a valid certificate in return
+ 4. Convert your private key format into PKCS#8 encrypted format.::
+
+ openssl pkcs8 -topk8 -in yourprivate.key -out yourprivate.pkcs8.encrypted.key
+
+ 5. Convert your PKCS#8 encrypted private key into the PKCS#8 format that is compliant with CloudStack::
+
+ openssl pkcs8 -in yourprivate.pkcs8.encrypted.key -out yourprivate.pkcs8.key
+
+3. In the Update SSL Certificate screen of the CloudStack UI, paste the following:
+ *. The certificate you've just generated.
+ *. The private key you've just generated.
+ *. The desired new domain name; for example, company.com
+
+4. The desired new domain name; for example, company.com
+This stops all currently running console proxy VMs, then restarts them with the new certificate and key. Users might notice a brief interruption in console availability.
+
+The Management Server generates URLs of the form "aaa-bbb-ccc-ddd.company.com" after this change is made. The new console requests will be served with the new DNS domain name, certificate, and key.
+
+Virtual Router
+_______________
+
+The virtual router is a type of System Virtual Machine. The virtual router is one of the most frequently used service providers in CloudStack. The end user has no direct access to the virtual router. Users can ping the virtual router and take actions that affect it (such as setting up port forwarding), but users do not have SSH access into the virtual router.
+
+Virtual routers can be restarted by administrators, but this will interrupt public network access and other services for end users. A basic test in debugging networking issues is to attempt to ping the virtual router from a guest VM. Some of the characteristics of the virtual router are determined by its associated system service offering..
+
+Configuring the Virtual Router
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can set the following:
+*. IP range
+*. Supported network services
+*. Default domain name for the network serviced by the virtual router
+*. Gateway IP address
+*. How often CloudStack fetches network usage statistics from CloudStack virtual routers. If you want to collect traffic metering data from the virtual router, set the global configuration parameter router.stats.interval. If you are not using the virtual router to gather network usage statistics, set it to 0.
+
+Upgrading a Virtual Router with System Service Offerings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When CloudStack creates a virtual router, it uses default settings which are defined in a default system service offering. See Section 8.2, “System Service Offerings”. All the virtual routers in a single guest network use the same system service offering. You can upgrade the capabilities of the virtual router by creating and applying a custom system service offering.
+Define your custom system service offering.
+Associate the system service offering with a network offering.
+Apply the network offering to the network where you want the virtual routers to use the new system service offering.
+
+Best Practices for Virtual Routers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Restarting a virtual router from a hypervisor console deletes all the iptables rules. To work around this issue, stop the virtual router and start it from the CloudStack UI.
+* Do not use the destroyRouter API when only one router is available in the network, because restartNetwork API with the cleanup=false parameter can't recreate it later. If you want to destroy and recreate the single router available in the network, use the restartNetwork API with the cleanup=true parameter.
+
+Secondary Storage VM
+_____________________
+
+In addition to the hosts, CloudStack’s Secondary Storage VM mounts and writes to secondary storage.
+Submissions to secondary storage go through the Secondary Storage VM. The Secondary Storage VM can retrieve templates and ISO images from URLs using a variety of protocols.
+The secondary storage VM provides a background task that takes care of a variety of secondary storage activities: downloading a new template to a Zone, copying templates between Zones, and snapshot backups.
+The administrator can log in to the secondary storage VM if needed.
+
+
+Storage Administration
+----------------------
+
+Hypervisor Host Management
+--------------------------
+
+Maintenance mode
+________________
+
+Maintenance mode makes a host unavailable to have new virtual machines allocated to it. It also starts a process by which running virtual machines are live migrated to other available hosts within the same cluster. It should be noted that the live migration is not universally perfect, and you may end up with recalcitrant virtual machines which are unable to be live migrated. This can be due to lack of hypervisor-specific tooling or other problems.
+
+vCenter and Maintenance mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enter maintenance mode on a vCenter host, both vCenter and CloudStack must be used in concert. CloudStack and vCenter have separate maintenance modes that work closely together.
+
+#. Place the host into CloudStack's "scheduled maintenance" mode. This does not invoke the vCenter maintenance mode, but only causes VMs to be migrated off the host When the CloudStack maintenance mode is requested, the host first moves into the Prepare for Maintenance state. In this state it cannot be the target of new guest VM starts. Then all VMs will be migrated off the server. Live migration will be used to move VMs off the host. This allows the guests to be migrated to other hosts with no disruption to the guests. After this migration is completed, the host will enter the Ready for Maintenance mode.
+#. Wait for the "Ready for Maintenance" indicator to appear in the UI.
+#. Now use vCenter to perform whatever actions are necessary to maintain the host. During this time, the host cannot be the target of new VM allocations.
+#. When the maintenance tasks are complete, take the host out of maintenance mode as follows:
+ a. First use vCenter to exit the vCenter maintenance mode. This makes the host ready for CloudStack to reactivate it.
+ b. Then use CloudStack's administrator UI to cancel the CloudStack maintenance mode When the host comes back online, the VMs that were migrated off of it may be migrated back to it manually and new VMs can be added.
+
+XenServer Maintenance Mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+XenServer, you can take a server offline temporarily by using the Maintenance Mode feature in XenCenter. When you place a server into Maintenance Mode, all running VMs are automatically migrated from it to another host in the same pool. If the server is the pool master, a new master will also be selected for the pool. While a server is Maintenance Mode, you cannot create or start any VMs on it.
+
+To place a XenServer host in Maintenace Mode
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+#. In the Resources pane, select the server, then do one of the following:
+ *. Right-click, then click Enter Maintenance Mode on the shortcut menu.
+ *. On the Server menu, click Enter Maintenance Mode.
+#. Click Enter Maintenance Mode.
+
+The server's status in the Resources pane shows when all running VMs have been successfully migrated off the server.
+
+To take a Xenserver host out of Maintenance mode
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+#. In the Resources pane, select the server, then do one of the following:
+ *Right-click, then click Exit Maintenance Mode on the shortcut menu.
+ *On the Server menu, click Exit Maintenance Mode.
+#. Click Exit Maintenance Mode.
+
+Disabling and enabling Zones, Pods, and Clusters
+________________________________________________
+
+You can enable or disable a zone, pod, or cluster without permanently removing it from the cloud. This is useful for maintenance or when there are problems that make a portion of the cloud infrastructure unreliable. No new allocations will be made to a disabled zone, pod, or cluster until its state is returned to Enabled. When a zone, pod, or cluster is first added to the cloud, it is Disabled by default.
+To disable and enable a zone, pod, or cluster:
+
+#. Log in to the CloudStack UI as administrator
+#. In the left navigation bar, click Infrastructure.
+#. In Zones, click View More.
+#. If you are disabling or enabling a zone, find the name of the zone in the list, and click the Enable/Disable button.
+#. If you are disabling or enabling a pod or cluster, click the name of the zone that contains the pod or cluster.
+#. Click the Compute tab.
+#. In the Pods or Clusters node of the diagram, click View All.
+#. Click the pod or cluster name in the list.
+#. Click the Enable/Disable button.
+
+Removing hypervisor hosts
+_________________________
+
+Hosts can be removed from the cloud as needed. The procedure to remove a host depends on the hypervisor type.
+
+Removing XenServer and KVM Hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A node cannot be removed from a cluster until it has been placed in maintenance mode. This will ensure that all of the VMs on it have been migrated to other Hosts. To remove a Host from CloudStack:
+
+#. Place the node in maintenance mode.
+#. For KVM, stop the cloud-agent service.
+#. Use the UI option to remove the node.
+#. Then you may power down the Host, re-use its IP address, re-install it, etc
+
+Removing vSphere Hosts
+~~~~~~~~~~~~~~~~~~~~~~
+To remove this type of host, first place it in maintenance mode, as described above. Then use CloudStack to remove the host. CloudStack will not direct commands to a host that has been removed using CloudStack. However, the host may still exist in the vCenter cluster.
+
+Changing hypervisor host password
+_________________________________
+The password for a XenServer Node, KVM Node, or vSphere Node may be changed in the database. Note that all Nodes in a Cluster must have the same password.
+To change a hosts password:
+
+#. Identify all hosts in the cluster.
+#. Change the password on all hosts in the cluster. Now the password for the host and the password known to CloudStack will not match. Operations on the cluster will fail until the two passwords match.
+#. Get the list of host IDs for the host in the cluster where you are changing the password. You will need to access the database to determine these host IDs. For each hostname "h" (or vSphere cluster) that you are changing the password for, execute: ::
+
+ mysql> select id from cloud.host where name like '%h%';
+
+4. Update the passwords for the host in the database. In this example, we change the passwords for hosts with IDs 5, 10, and 12 to "password".::
+
+ mysql> update cloud.host set password='password' where id=5 or id=10 or id=12;
+
+Overprovisioning and Service Offering Limits
+____________________________________________
+
+CPU and memory (RAM) over-provisioning factors can be set for each cluster to change the number of VMs that can run on each host in the cluster. This helps optimize the use of resources. By increasing the over-provisioning ratio, more resource capacity will be used. If the ratio is set to 1, no over-provisioning is done.
+
+The administrator can also set global default over-provisioning ratios in the cpu.overprovisioning.factor and mem.overprovisioning.factor global configuration variables. The default value of these variables is 1: over-provisioning is turned off by default.
+Over-provisioning ratios are dynamically substituted in CloudStack's capacity calculations. For example:::
+
+ Capacity = 2 GB
+ Over-provisioning factor = 2
+ Capacity after over-provisioning = 4 GB
+ With this configuration, suppose you deploy 3 VMs of 1 GB each:
+ Used = 3 GB
+ Free = 1 GB
+
+The administrator can specify a memory over-provisioning ratio, and can specify both CPU and memory over-provisioning ratios on a per-cluster basis.
+In any given cloud, the optimum number of VMs for each host is affected by such things as the hypervisor, storage, and hardware configuration. These may be different for each cluster in the same cloud. A single global over-provisioning setting can not provide the best utilization for all the different clusters in the cloud. It has to be set for the lowest common denominator. The per-cluster setting provides a finer granularity for better utilization of resources, no matter where the CloudStack placement algorithm decides to place a VM.
+
+The overprovisioning settings can be used along with dedicated resources (assigning a specific cluster to an account) to effectively offer different levels of service to different accounts. For example, an account paying for a more expensive level of service could be assigned to a dedicated cluster with an over-provisioning ratio of 1, and a lower-paying account to a cluster with a ratio of 2.
+
+When a new host is added to a cluster, CloudStack will assume the host has the capability to perform the CPU and RAM over-provisioning which is configured for that cluster. It is up to the administrator to be sure the host is actually suitable for the level of over-provisioning which has been set.
+
+Limitations on over-provisioning in KVM and XenServer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In XenServer, due to a constraint of this hypervisor, you can not use an over-provisioning factor greater than 4.
+
+KVM can not manage memory allocation to VMs dynamically. CloudStack sets the minimum and maximum amount of memory that a VM can use. The hypervisor adjusts the memory within the set limits based on the memory contention.
+
+Requirements for Over-Provisioning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Several prerequisites are required in order for over-provisioning to function properly. The feature is dependent on the OS type, hypervisor capabilities, and certain scripts. It is the administrator's responsibility to ensure that these requirements are met.
+
+Balloon Driver
+@@@@@@@@@@@@@@
+
+All VMs should have a balloon driver installed in them. The hypervisor communicates with the balloon driver to free up and make the memory available to a VM.
+
+XenServer
+#########
+
+The balloon driver can be found as a part of xen pv or PVHVM drivers. The xen pvhvm drivers are included in upstream linux kernels 2.6.36+.
+
+VMware
+######
+
+The balloon driver can be found as a part of the VMware tools. All the VMs that are deployed in a over-provisioned cluster should have the VMware tools installed.
+
+KVM
+####
+
+All VMs are required to support the virtio drivers. These drivers are installed in all Linux kernel versions 2.6.25 and greater. The administrator must set CONFIG_VIRTIO_BALLOON=y in the virtio configuration.
+
+Hypervisor capabilities
+@@@@@@@@@@@@@@@@@@@@@@@
+
+The hypervisor must be capable of using the memory ballooning.
+
+XenServer
+#########
+
+The DMC (Dynamic Memory Control) capability of the hypervisor should be enabled. Only XenServer Advanced and above versions have this feature.
+
+VMware, KVM
+###########
+
+Memory ballooning is supported by default.
+
+Setting Over-Provisioning Rations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two ways the root admin can set CPU and RAM over-provisioning ratios. First, the global configuration settings cpu.overprovisioning.factor and mem.overprovisioning.factor will be applied when a new cluster is created. Later, the ratios can be modified for an existing cluster.
+
+Only VMs deployed after the change are affected by the new setting. If you want VMs deployed before the change to adopt the new over-provisioning ratio, you must stop and restart the VMs. When this is done, CloudStack recalculates or scales the used and reserved capacities based on the new over-provisioning ratios, to ensure that CloudStack is correctly tracking the amount of free capacity.
+
+To change the over-provisioning ratios for an existing cluster:
+
+#. Log in as administrator to the CloudStack UI.
+#. In the left navigation bar, click Infrastructure.
+#. Under Clusters, click View All.
+#. Select the cluster you want to work with, and click the Edit button.
+#. Fill in your desired over-provisioning multipliers in the fields CPU overcommit ratio and RAM overcommit ratio. The value which is intially shown in these fields is the default value inherited from the global configuration settings.
+
+Service Offering Limits and Over-Provisioning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Service offering limits (e.g. 1 GHz, 1 core) are strictly enforced for core count. For example, a guest with a service offering of one core will have only one core available to it regardless of other activity on the Host.
+
+Service offering limits for gigahertz are enforced only in the presence of contention for CPU resources. For example, suppose that a guest was created with a service offering of 1 GHz on a Host that has 2 GHz cores, and that guest is the only guest running on the Host. The guest will have the full 2 GHz available to it. When multiple guests are attempting to use the CPU a weighting factor is used to schedule CPU resources. The weight is based on the clock speed in the service offering. Guests receive a CPU allocation that is proportionate to the GHz in the service offering. For example, a guest created from a 2 GHz service offering will receive twice the CPU allocation as a guest created from a 1 GHz service offering. CloudStack does not perform memory over-provisioning.
+
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/5fddad01/rtd/source/alloc.rst
----------------------------------------------------------------------
diff --git a/rtd/source/alloc.rst b/rtd/source/alloc.rst
new file mode 100644
index 0000000..ff56127
--- /dev/null
+++ b/rtd/source/alloc.rst
@@ -0,0 +1,292 @@
+Allocators
+==========
+
+PRODUCT enables administrators to write custom allocators that will
+choose the Host to place a new guest and the storage host from which to
+allocate guest virtual disk images.
+
+These are following categories of allocators currently supported:
+
+- HostAllocators - Allows you to create custom rules to determine which
+ physical host to allocate the guest virtual machines on.
+
+- StoragePoolAllocators - Allows you to create custom rules to
+ determine which storage pool to allocate the guest virtual machines
+ on.
+
+Implementing a custom HostAllocator
+-----------------------------------
+
+HostAllocators are written by extending
+com.cloud.agent.manager.allocator.HostAllocator interface.
+
+HostAllocator Interface
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The interface defines the following two methods.
+
+::
+
+ /**
+ * Checks if the VM can be upgraded to the specified ServiceOffering
+ * @param UserVm vm
+ * @param ServiceOffering offering
+ * @return boolean true if the VM can be upgraded
+ **/
+
+ publicboolean isVirtualMachineUpgradable(final UserVm vm, final ServiceOffering offering);
+
+ /**
+ * Determines which physical hosts are suitable to allocate the guest virtual machines on
+ *
+ * @paramVirtualMachineProfile vmProfile
+ * @paramDeploymentPlan plan
+ * @paramType type
+ * @paramExcludeList avoid
+ * @paramint returnUpTo
+ * @returnList<Host>List of hosts that are suitable for VM allocation
+ **/
+
+ publicList<Host> allocateTo( VirtualMachineProfile<?extendsVirtualMachine> vmProfile, DeploymentPlan plan, Type type, ExcludeList avoid, intreturnUpTo);
+
+
+A custom HostAllocator can be written by implementing the ‘allocateTo’
+method
+
+Input Parameters for the method ‘HostAllocator :: allocateTo’
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*com.cloud.vm.VirtualMachineProfile vmProfile*
+
+VirtualMachineProfile describes one virtual machine. This allows the
+adapters like Allocators to process the information in the virtual
+machine and make determinations on what the virtual machine profile
+should look like before it is actually started on the hypervisor.
+
+HostAllocators can make use of the following information present in the
+VirtualMachineProfile:
+
+- The ServiceOffering that specifies configuration like requested CPU
+ speed, RAM etc necessary for the guest VM.
+
+- The VirtualMachineTemplate, the template to be used to start the VM.
+
+*com.cloud.deploy.DeploymentPlan plan*
+
+DeploymentPlan should specify:
+
+- dataCenterId: The data center the VM should deploy in
+
+- podId: The pod the Vm should deploy in; null if no preference
+
+- clusterId: The cluster the VM should deploy in; null if no preference
+
+- poolId: The storage pool the VM should be created in; null if no
+ preference
+
+*com.cloud.host.Host.Type type*
+
+Type of the Host needed for this guest VM. Currently
+com.cloud.host.Host.Type interface defines the following Host types:
+
+- Storage
+
+- Routing
+
+- SecondaryStorage
+
+- ConsoleProxy
+
+- ExternalFirewall
+
+- ExternalLoadBalancer
+
+*com.cloud.deploy.DeploymentPlanner.ExcludeList avoid*
+
+The ExcludeList specifies what datacenters, pods, clusters, hosts,
+storagePools should not be considered for allocating this guest VM.
+HostAllocators should avoid the hosts that are mentioned in
+ExcludeList.hostIds.
+
+- Set Long dcIds;
+
+- Set Long podIds;
+
+- Set Long clusterIds;
+
+- Set Long hostIds;
+
+- Set Long poolIds;
+
+*int returnUpTo*
+
+This specifies return up to that many available hosts for this guest VM.
+
+To get all possible hosts, set this value to -1.
+
+Reference HostAllocator implementation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Refer com.cloud.agent.manager.allocator.impl.FirstFitAllocator that
+implements the HostAllocator interface. This allocator checks available
+hosts in the specified datacenter, Pod, Cluster and considering the
+given ServiceOffering requirements.
+
+If returnUpTo = 1, this allocator would return the first Host that fits
+the requirements of the guest VM.
+
+Loading a custom HostAllocator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Write a custom HostAllocator class, implementing the interface
+ described above.
+
+2. Package the code into a JAR file and make the JAR available in the
+ classpath of the Management Server/tomcat.
+
+3. Modify the components.xml and components-premium.xml files found in
+ /client/ tomcatconf as follows.
+
+4. Search for ‘HostAllocator’ in these files.
+
+ ::
+
+ <adapters key="com.cloud.agent.manager.allocator.HostAllocator">
+ <adapter name="FirstFit" class="com.cloud.agent.manager.allocator.impl.FirstFitAllocator"/>
+ </adapters>
+
+
+5. Replace the FirstFitAllocator with your class name. Optionally, you
+ can change the name of the adapter as well.
+
+6. Restart the Management Server.
+
+Implementing a custom StoragePoolAllocator
+------------------------------------------
+
+StoragePoolAllocators are written by extending
+com.cloud.storage.allocator. StoragePoolAllocator interface.
+
+StoragePoolAllocator Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A custom StoragePoolAllocator can be written by implementing the
+‘allocateTo’ method.
+
+::
+
+ /**
+ * Determines which storage pools are suitable for the guest virtual machine
+ * @param DiskProfile dskCh
+ * @param VirtualMachineProfile vmProfile
+ * @param DeploymentPlan plan
+ * @param ExcludeList avoid
+ * @param int returnUpTo
+ * @return List<StoragePool> List of storage pools that are suitable for the VM
+ **/
+
+ public List<StoragePool> allocateToPool(DiskProfile dskCh, VirtualMachineProfile<? extends VirtualMachine> vm, DeploymentPlan plan, ExcludeList avoid, int returnUpTo);
+
+
+This interface also contains some other methods to support some legacy
+code. However your custom allocator can extend the existing
+com.cloud.storage.allocator. AbstractStoragePoolAllocator. This class
+provides default implementation for all the other interface methods.
+
+Input Parameters for the method ‘StoragePoolAllocator :: allocateTo’
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*com.cloud.vm.DiskProfile dskCh*
+
+DiskCharacteristics describes a disk and what functionality is required
+from it. It specifies the storage pool tags if any to be used while
+searching for a storage pool.
+
+*com.cloud.vm.VirtualMachineProfile vmProfile*
+
+VirtualMachineProfile describes one virtual machine. This allows the
+adapters like Allocators to process the information in the virtual
+machine and make determinations on what the virtual machine profile
+should look like before it is actually started on the hypervisor.
+
+StoragePoolAllocators can make use of the following information present
+in the VirtualMachineProfile:
+
+- The VirtualMachine instance that specifies properties of the guest
+ VM.
+
+- The VirtualMachineTemplate, the template to be used to start the VM.
+
+*com.cloud.deploy.DeploymentPlan plan*
+
+DeploymentPlan should specify:
+
+- dataCenterId: The data center the VM should deploy in
+
+- podId: The pod the VM should deploy in; null if no preference
+
+- clusterId: The cluster the VM should deploy in; null if no preference
+
+- poolId: The storage pool the VM should be created in; null if no
+ preference
+
+*com.cloud.deploy.DeploymentPlanner.ExcludeList avoid*
+
+The ExcludeList specifies what datacenters, pods, clusters, hosts,
+storagePools should not be considered for allocating this guest VM.
+StoragePoolAllocators should avoid the pools that are mentioned in
+ExcludeList.poolIds
+
+- Set Long dcIds;
+
+- Set Long podIds;
+
+- Set Long clusterIds;
+
+- Set Long hostIds;
+
+- Set Long poolIds;
+
+*int returnUpTo*
+
+This specifies return up to that many available pools for this guest VM
+
+To get all possible pools, set this value to -1
+
+Reference StoragePoolAllocator implementation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Refer com.cloud.storage.allocator.FirstFitStoragePoolAllocator that
+implements the StoragePoolAllocator interface. This allocator checks
+available pools in the specified datacenter, Pod, Cluster and
+considering the given DiskProfile characteristics.
+
+If returnUpTo = 1, this allocator would return the first Storage Pool
+that fits the requirements of the guest VM.
+
+Loading a custom StoragePoolAllocator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Write a custom StoragePoolAllocator class, implementing the interface
+ described above.
+
+2. Package the code into a JAR file and make the JAR available in the
+ classpath of the Management Server/tomcat.
+
+3. Modify the components.xml and components-premium.xml files found in
+ /client/ tomcatconf as follows.
+
+4. Search for ‘StoragePoolAllocator’ in these files.
+
+ ::
+
+ <adapters key="com.cloud.storage.allocator.StoragePoolAllocator">
+ <adapter name="Storage" class="com.cloud.storage.allocator.FirstFitStoragePoolAllocator"/>
+ </adapters>
+
+5. Replace the FirstFitStoragePoolAllocator with your class name.
+ Optionally, you can change the name of the adapter as well.
+
+6. Restart the Management Server.
+
+