CLOUDSTACK-1814: Add LXC documentation Signed-off-by: Joe Brockmeier <[email protected]>
Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/c5228417 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/c5228417 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/c5228417 Branch: refs/heads/vmsync Commit: c522841716e77066f387410ca42d0e8132f96459 Parents: 301c683 Author: Phong Nguyen <[email protected]> Authored: Mon Apr 1 14:56:58 2013 -0400 Committer: Joe Brockmeier <[email protected]> Committed: Mon Apr 8 20:03:37 2013 -0500 ---------------------------------------------------------------------- docs/en-US/hypervisor-host-install-firewall.xml | 4 +- docs/en-US/hypervisor-host-install-network.xml | 8 +- docs/en-US/hypervisor-installation.xml | 1 + docs/en-US/lxc-install.xml | 110 ++++++++++++++++ docs/en-US/lxc-topology-req.xml | 24 ++++ docs/en-US/management-server-install-systemvm.xml | 4 + docs/en-US/minimum-system-requirements.xml | 1 + docs/en-US/prepare-system-vm-template.xml | 4 + docs/en-US/topology-req.xml | 3 +- 9 files changed, 152 insertions(+), 7 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/hypervisor-host-install-firewall.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/hypervisor-host-install-firewall.xml b/docs/en-US/hypervisor-host-install-firewall.xml index ae82fc4..c665873 100644 --- a/docs/en-US/hypervisor-host-install-firewall.xml +++ b/docs/en-US/hypervisor-host-install-firewall.xml @@ -34,7 +34,7 @@ <listitem><para>49152 - 49216 (libvirt live migration)</para></listitem> </orderedlist> <para>It depends on the firewall you are using how to open these ports. Below you'll find examples how to open these ports in RHEL/CentOS and Ubuntu.</para> - <section id="hypervisor-host-install-firewall-rhel"> + <section> <title>Open ports in RHEL/CentOS</title> <para>RHEL and CentOS use iptables for firewalling the system, you can open extra ports by executing the following iptable commands:</para> <programlisting language="Bash"><command>$ iptables -I INPUT -p tcp -m tcp --dport 22 -j ACCEPT</command></programlisting> @@ -45,7 +45,7 @@ <para>These iptable settings are not persistent accross reboots, we have to save them first.</para> <programlisting language="Bash"><command>$ iptables-save > /etc/sysconfig/iptables</command></programlisting> </section> - <section id="hypervisor-host-install-firewall-ubuntu"> + <section> <title>Open ports in Ubuntu</title> <para>The default firewall under Ubuntu is UFW (Uncomplicated FireWall), which is a Python wrapper around iptables.</para> <para>To open the required ports, execute the following commands:</para> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/hypervisor-host-install-network.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/hypervisor-host-install-network.xml b/docs/en-US/hypervisor-host-install-network.xml index 3a6dfac..54cdc27 100644 --- a/docs/en-US/hypervisor-host-install-network.xml +++ b/docs/en-US/hypervisor-host-install-network.xml @@ -29,7 +29,7 @@ <para>In order to forward traffic to your instances you will need at least two bridges: <emphasis>public</emphasis> and <emphasis>private</emphasis>.</para> <para>By default these bridges are called <emphasis>cloudbr0</emphasis> and <emphasis>cloudbr1</emphasis>, but you do have to make sure they are available on each hypervisor.</para> <para>The most important factor is that you keep the configuration consistent on all your hypervisors.</para> - <section id="hypervisor-host-install-network-vlan"> + <section> <title>Network example</title> <para>There are many ways to configure your network. In the Basic networking mode you should have two (V)LAN's, one for your private network and one for the public network.</para> <para>We assume that the hypervisor has one NIC (eth0) with three tagged VLAN's:</para> @@ -41,11 +41,11 @@ <para>On VLAN 100 we give the Hypervisor the IP-Address 192.168.42.11/24 with the gateway 192.168.42.1</para> <note><para>The Hypervisor and Management server don't have to be in the same subnet!</para></note> </section> - <section id="hypervisor-host-install-network-configure"> + <section> <title>Configuring the network bridges</title> <para>It depends on the distribution you are using how to configure these, below you'll find examples for RHEL/CentOS and Ubuntu.</para> <note><para>The goal is to have two bridges called 'cloudbr0' and 'cloudbr1' after this section. This should be used as a guideline only. The exact configuration will depend on your network layout.</para></note> - <section id="hypervisor-host-install-network-configure-rhel"> + <section> <title>Configure in RHEL or CentOS</title> <para>The required packages were installed when libvirt was installed, we can proceed to configuring the network.</para> <para>First we configure eth0</para> @@ -111,7 +111,7 @@ STP=yes]]></programlisting> <para>With this configuration you should be able to restart the network, although a reboot is recommended to see if everything works properly.</para> <warning><para>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!</para></warning> </section> - <section id="hypervisor-host-install-network-configure-ubuntu"> + <section> <title>Configure in Ubuntu</title> <para>All the required packages were installed when you installed libvirt, so we only have to configure the network.</para> <programlisting language="Bash">vi /etc/network/interfaces</programlisting> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/hypervisor-installation.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/hypervisor-installation.xml b/docs/en-US/hypervisor-installation.xml index b0fc9f4..5ee7dea 100644 --- a/docs/en-US/hypervisor-installation.xml +++ b/docs/en-US/hypervisor-installation.xml @@ -28,4 +28,5 @@ <xi:include href="citrix-xenserver-installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> <xi:include href="vmware-install.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> <!-- <xi:include href="ovm-install.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> --> + <xi:include href="lxc-install.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> </chapter> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/lxc-install.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/lxc-install.xml b/docs/en-US/lxc-install.xml new file mode 100644 index 0000000..a80c18a --- /dev/null +++ b/docs/en-US/lxc-install.xml @@ -0,0 +1,110 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ + <!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> + %BOOK_ENTITIES; + ]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +<section id="lxc-install"> + <title>LXC Installation and Configuration</title> + <section id="lxc-requirements"> + <title>System Requirements for LXC Hosts</title> + <para>LXC requires the Linux kernel cgroups functionality which is available starting 2.6.24. Although you are not required to run these distributions, the following are recommended:</para> + <itemizedlist> + <listitem><para>CentOS / RHEL: 6.3</para></listitem> + <listitem><para>Ubuntu: 12.04(.1)</para></listitem> + </itemizedlist> + <para>The main requirement for LXC hypervisors is the libvirt and Qemu version. No matter what + Linux distribution you are using, make sure the following requirements are met:</para> + <itemizedlist> + <listitem><para>libvirt: 1.0.0 or higher</para></listitem> + <listitem><para>Qemu/KVM: 1.0 or higher</para></listitem> + </itemizedlist> + <para>The default bridge in &PRODUCT; is the Linux native bridge implementation (bridge module). &PRODUCT; includes an option to work with OpenVswitch, the requirements are listed below</para> + <itemizedlist> + <listitem><para>libvirt: 1.0.0 or higher</para></listitem> + <listitem><para>openvswitch: 1.7.1 or higher</para></listitem> + </itemizedlist> + <para>In addition, the following hardware requirements apply:</para> + <itemizedlist> + <listitem><para>Within a single cluster, the hosts must be of the same distribution version.</para></listitem> + <listitem><para>All hosts within a cluster must be homogenous. The CPUs must be of the same type, count, and feature flags.</para></listitem> + <listitem><para>Must support HVM (Intel-VT or AMD-V enabled)</para></listitem> + <listitem><para>64-bit x86 CPU (more cores results in better performance)</para></listitem> + <listitem><para>4 GB of memory</para></listitem> + <listitem><para>At least 1 NIC</para></listitem> + <listitem><para>When you deploy &PRODUCT;, the hypervisor host must not have any VMs already running</para></listitem> + </itemizedlist> + </section> + <section id="lxc-install-overview"> + <title>LXC Installation Overview</title> + <para>LXC does not have any native system VMs, instead KVM will be used to run system VMs. This means that your host will need to support both LXC and KVM, thus most of the installation and configuration will be identical to the KVM installation. The material in this section doesn't duplicate KVM installation docs. It provides the &PRODUCT;-specific steps that are needed to prepare a KVM host to work with &PRODUCT;.</para> + <warning><para>Before continuing, make sure that you have applied the latest updates to your host.</para></warning> + <warning><para>It is NOT recommended to run services on this host not controlled by &PRODUCT;.</para></warning> + <para>The procedure for installing an LXC Host is:</para> + <orderedlist> + <listitem><para>Prepare the Operating System</para></listitem> + <listitem><para>Install and configure libvirt</para></listitem> + <listitem><para>Configure Security Policies (AppArmor and SELinux)</para></listitem> + <listitem><para>Install and configure the Agent</para></listitem> + </orderedlist> + </section> + <section id="lxc-install-prepare-os"> + <xi:include href="hypervisor-host-install-prepare-os.xml#xpointer(/section/*)" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </section> + <section id="lxc-install-agent"> + <title>Install and configure the Agent</title> + <para>To manage LXC instances on the host &PRODUCT; uses a Agent. This Agent communicates with the Management server and controls all the instances on the host.</para> + <para>First we start by installing the agent:</para> + <para>In RHEL or CentOS:</para> + <programlisting language="Bash"><command>$ yum install cloud-agent</command></programlisting> + <para>In Ubuntu:</para> + <programlisting language="Bash"><command>$ apt-get install cloud-agent</command></programlisting> + <para>Next step is to update the Agent configuration setttings. The settings are in <filename>/etc/cloudstack/agent/agent.properties</filename></para> + <orderedlist> + <listitem> + <para>Set the Agent to run in LXC mode:</para> + <programlisting>hypervisor.type=lxc</programlisting> + </listitem> + <listitem> + <para>Optional: If you would like to use direct networking (instead of the default bridge networking), configure these lines:</para> + <programlisting>libvirt.vif.driver=com.cloud.hypervisor.kvm.resource.DirectVifDriver</programlisting> + <programlisting>network.direct.source.mode=private</programlisting> + <programlisting>network.direct.device=eth0</programlisting> + </listitem> + </orderedlist> + <para>The host is now ready to be added to a cluster. This is covered in a later section, see <xref linkend="host-add" />. It is recommended that you continue to read the documentation before adding the host!</para> + </section> + <section id="lxc-install-libvirt"> + <xi:include href="hypervisor-host-install-libvirt.xml#xpointer(/section/*)" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </section> + <section id="lxc-install-security-policies"> + <xi:include href="hypervisor-host-install-security-policies.xml#xpointer(/section/*)" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </section> + <section id="lxc-install-network"> + <xi:include href="hypervisor-host-install-network.xml#xpointer(/section/*)" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </section> + <section id="lxc-install-firewall"> + <xi:include href="hypervisor-host-install-firewall.xml#xpointer(/section/*)" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </section> + <section id="lxc-install-finish"> + <xi:include href="hypervisor-host-install-finish.xml#xpointer(/section/*)" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </section> +</section> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/lxc-topology-req.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/lxc-topology-req.xml b/docs/en-US/lxc-topology-req.xml new file mode 100644 index 0000000..315863d --- /dev/null +++ b/docs/en-US/lxc-topology-req.xml @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> +<section id="lxc-topology-req"> + <title>LXC Topology Requirements</title> + <para>The Management Servers communicate with LXC hosts on port 22 (ssh).</para> +</section> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/management-server-install-systemvm.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/management-server-install-systemvm.xml b/docs/en-US/management-server-install-systemvm.xml index 8dc73de..928b956 100644 --- a/docs/en-US/management-server-install-systemvm.xml +++ b/docs/en-US/management-server-install-systemvm.xml @@ -53,6 +53,10 @@ <para>For KVM:</para> <programlisting># /usr/lib64/cloud/common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloud.com/templates/acton/acton-systemvm-02062012.qcow2.bz2 -h kvm -s <optional-management-server-secret-key> -F</programlisting> </listitem> + <listitem> + <para>For LXC:</para> + <programlisting># /usr/lib64/cloud/common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloud.com/templates/acton/acton-systemvm-02062012.qcow2.bz2 -h lxc -s <optional-management-server-secret-key> -F</programlisting> + </listitem> </itemizedlist> <para>On Ubuntu, use the following path instead:</para> <programlisting># /usr/lib/cloud/common/scripts/storage/secondary/cloud-install-sys-tmplt</programlisting> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/minimum-system-requirements.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/minimum-system-requirements.xml b/docs/en-US/minimum-system-requirements.xml index 0e497dd..de1bc22 100644 --- a/docs/en-US/minimum-system-requirements.xml +++ b/docs/en-US/minimum-system-requirements.xml @@ -68,6 +68,7 @@ <listitem><para><xref linkend="system-requirements-xenserver-hosts"/></para></listitem> <listitem><para><xref linkend="vmware-requirements"/></para></listitem> <!-- <listitem><para><xref linkend="ovm-requirements"/></para></listitem> --> + <listitem><para><xref linkend="lxc-requirements"/></para></listitem> </itemizedlist> </section> </section> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/prepare-system-vm-template.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/prepare-system-vm-template.xml b/docs/en-US/prepare-system-vm-template.xml index b53a509..35cc7e9 100644 --- a/docs/en-US/prepare-system-vm-template.xml +++ b/docs/en-US/prepare-system-vm-template.xml @@ -60,6 +60,10 @@ <para>For KVM:</para> <programlisting># /usr/lib64/cloud/common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloud.com/templates/acton/acton-systemvm-02062012.qcow2.bz2 -h kvm -s <optional-management-server-secret-key> -F</programlisting> </listitem> + <listitem> + <para>For LXC:</para> + <programlisting># /usr/lib64/cloud/common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloud.com/templates/acton/acton-systemvm-02062012.qcow2.bz2 -h lxc -s <optional-management-server-secret-key> -F</programlisting> + </listitem> </itemizedlist> </listitem> <listitem> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c5228417/docs/en-US/topology-req.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/topology-req.xml b/docs/en-US/topology-req.xml index 65c9c2e..75fe69b 100644 --- a/docs/en-US/topology-req.xml +++ b/docs/en-US/topology-req.xml @@ -28,4 +28,5 @@ <xi:include href="xenserver-topology-req.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> <xi:include href="vmware-topology-req.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> <xi:include href="kvm-topology-req.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> - </section> + <xi:include href="lxc-topology-req.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> +</section>
