ACS4.1_Quick_install_guide
Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/676d8744 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/676d8744 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/676d8744 Branch: refs/heads/vmsync Commit: 676d8744ef6801cf3fcf6425d37ba27a149e5615 Parents: bd784fb Author: Meng Han <meng...@ufl.edu> Authored: Sat Jun 29 11:32:36 2013 -0400 Committer: Sebastien Goasguen <run...@gmail.com> Committed: Sat Jun 29 15:40:12 2013 -0400 ---------------------------------------------------------------------- docs/qig/en-US/Author_Group.xml | 32 ++++ docs/qig/en-US/Book_Info.xml | 52 +++++++ docs/qig/en-US/Chapter.xml | 53 +++++++ docs/qig/en-US/Environment.xml | 258 +++++++++++++++++++++++++++++++ docs/qig/en-US/Management.xml | 99 ++++++++++++ docs/qig/en-US/Overview.xml | 93 +++++++++++ docs/qig/en-US/Preface.xml | 33 ++++ docs/qig/en-US/Revision_History.xml | 42 +++++ docs/qig/en-US/config.xml | 177 +++++++++++++++++++++ docs/qig/en-US/kvm.xml | 142 +++++++++++++++++ docs/qig/en-US/qig.ent | 22 +++ docs/qig/en-US/qig.xml | 36 +++++ 12 files changed, 1039 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Author_Group.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Author_Group.xml b/docs/qig/en-US/Author_Group.xml new file mode 100644 index 0000000..432ef6f --- /dev/null +++ b/docs/qig/en-US/Author_Group.xml @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.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. +--> + + +<authorgroup> + <author> + <firstname>Apache</firstname> + <surname>CloudStack</surname> + </author> +</authorgroup> + http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Book_Info.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Book_Info.xml b/docs/qig/en-US/Book_Info.xml new file mode 100644 index 0000000..e356de4 --- /dev/null +++ b/docs/qig/en-US/Book_Info.xml @@ -0,0 +1,52 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Runbook.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. +--> + + +<bookinfo id="book-qig-qig"> + <title>Quick Install Guide</title> + <subtitle>Prescriptive instructions for deploying Apache CloudStack</subtitle> + <productname>Apache CloudStack</productname> + <productnumber>4.0.2</productnumber> + <edition>0</edition> + <pubsnumber>0</pubsnumber> + <abstract> + <para> + This guide is designed to provide a strict environment to guarantee + a higher degree of success in initial deployments of Apache CloudStack. + All of the elements of the environment will be provided to you. + Apache CloudStack is capable of much more complex configurations, + but they are beyond the scope of this document. + </para> + </abstract> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> + </imageobject> + </inlinemediaobject> + </corpauthor> + <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> +</bookinfo> + http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Chapter.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Chapter.xml b/docs/qig/en-US/Chapter.xml new file mode 100644 index 0000000..4adf63c --- /dev/null +++ b/docs/qig/en-US/Chapter.xml @@ -0,0 +1,53 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Runbook.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + + +<chapter id="chap-Runbook-Test_Chapter"> + <title>Test Chapter</title> + <para> + This is a test paragraph + </para> + <section id="sect-Runbook-Test_Chapter-Test_Section_1"> + <title>Test Section 1</title> + <para> + This is a test paragraph in a section + </para> + </section> + + <section id="sect-Runbook-Test_Chapter-Test_Section_2"> + <title>Test Section 2</title> + <para> + This is a test paragraph in Section 2 + <orderedlist> + <listitem> + <para> + listitem text + </para> + </listitem> + </orderedlist> + </para> + </section> + +</chapter> + http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Environment.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Environment.xml b/docs/qig/en-US/Environment.xml new file mode 100644 index 0000000..e48b405 --- /dev/null +++ b/docs/qig/en-US/Environment.xml @@ -0,0 +1,258 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + + +<chapter id="chap-qig-Environment"> + <title>Environment</title> + <para> + Before you begin, you need to prepare the environment before you install CloudStack. + We will go over the steps to prepare now. + </para> + <section id="sect-qig-Environment-operatingsys"> + <title>Operating System</title> + <para> + Using the CentOS 6.4 x86_64 minimal install ISO, you'll need to install CentOS + on your hardware. The defaults will generally be acceptable for this installation. + </para> + <para> + Once this installation is complete, you'll want to connect to your freshly + installed machine via SSH as the root user. Note that you should not allow root + logins in a production environment, so be sure to turn off remote logins once you + have finished the installation and configuration. + </para> + <section id="sect-qig-Environment-operatingsys-network"> + <title>Configuring the network</title> + <para> + By default the network will not come up on your hardware and you + will need to configure it to work in your environment. Since we + specified that there will be no DHCP server in this environment + we will be manually configuring your network interface. We will + assume, for the purposes of this exercise, that eth0 is the only network + interface that will be connected and used. + </para> + <para> + Connecting via the console you should login as root. Check the + file <filename>/etc/sysconfig/network-scripts/ifcfg-eth0</filename>, + it will look like this by default: + <screen> +DEVICE="eth0" +HWADDR="52:54:00:B9:A6:C0" +NM_CONTROLLED="yes" +ONBOOT="no" + </screen> + </para> + <para> + Unfortunately, this configuration will not permit you to connect to the network, + and is also unsuitable for our purposes with CloudStack. We want to + configure that file so that it specifies the IP address, netmask, etc., as shown + in the following example: + </para> + <important> + <title>Hardware Addresses</title> + <para>You should not use the hardware address (aka MAC address) from our example + for your configuration. It is network interface specific, so you should keep the + address already provided in the HWADDR directive. + </para> + </important> + <screen> +DEVICE=eth0 +HWADDR=52:54:00:B9:A6:C0 +NM_CONTROLLED=no +ONBOOT=yes +BOOTPROTO=none +IPADDR=172.16.10.2 +NETMASK=255.255.255.0 +GATEWAY=172.16.10.1 +DNS1=8.8.8.8 +DNS2=8.8.4.4 + </screen> + <note> + <title>IP Addressing</title> + <para>Throughout this document we are assuming that you will + have a /24 network for your CloudStack implementation. This can be any + RFC 1918 network. However, we are assuming that you will match the + machine address that we are using. Thus we may use + <userinput><replaceable>172.16.10</replaceable>.2</userinput> and because + you might be using the 192.168.55.0/24 network you would use + <userinput><replaceable>192.168.55</replaceable>.2</userinput> + </para> + </note> + <para> Now that we have the configuration files properly set up, we need to run a + few commands to start up the network</para> + <screen><prompt># </prompt><userinput><command>chkconfig</command> network on</userinput></screen> + <screen><prompt># </prompt><userinput><command>service</command> network start</userinput></screen> + </section> + <section id="sect-qig-Environment-operatingsys-hostname"> + <title>Hostname</title> + <para> + Cloudstack requires that the hostname be properly set. If you used the default + options in the installation, then your hostname is currently set to + localhost.localdomain. To test this we will run: </para> + <screen><prompt># </prompt><userinput>hostname --fqdn</userinput></screen> + <para>At this point it will likely return:</para> + <screen>localhost</screen> + <para>To rectify this situation - we'll set the hostname by editing the + <filename>/etc/hosts</filename> file so that it follows a similar format to this example:<screen> +127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 +::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 +172.16.10.2 srvr1.cloud.priv +</screen> + </para> + <para>After you've modified that file, go ahead and restart the network using:</para> +<screen><prompt># </prompt><userinput><command>service</command> network restart</userinput></screen> + <para>Now recheck with the <command>hostname --fqdn</command> command and ensure that it returns + a FQDN response</para> + </section> + <section id="sect-qig-Environment-operatingsys-selinux"> + <title>SELinux</title> + <para>At the moment, for CloudStack to work properly SELinux must be + set to permissive. We want to both configure this for future boots and modify it + in the current running system. + </para> + <para>To configure SELinux to be permissive in the running system we need to run + the following command:</para> + <screen><prompt># </prompt><userinput><command>setenforce</command> 0</userinput></screen> + <para> + To ensure that it remains in that state we need to configure the file + <filename>/etc/selinux/config</filename> to reflect the permissive state, + as shown in this example: </para> + <screen> + +# This file controls the state of SELinux on the system. +# SELINUX= can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +SELINUX=permissive +# SELINUXTYPE= can take one of these two values: +# targeted - Targeted processes are protected, +# mls - Multi Level Security protection. +SELINUXTYPE=targeted + </screen> + + </section> + <section id="sect-qig-Environment-operatingsys-ntp"> + <title>NTP</title> + <para>NTP configuration is a necessity for keeping all of the clocks in your cloud + servers in sync. However, NTP is not installed by default. So we'll install and + and configure NTP at this stage. Installation is accomplished as follows: + </para> + <screen><prompt># </prompt><userinput><command>yum</command> -y install ntp</userinput></screen> + <para>The actual default configuration is fine for our purposes, so we merely need to + enable it and set it to start on boot as follows:</para> + <screen><prompt># </prompt><userinput><command>chkconfig</command> ntpd on</userinput></screen> + <screen><prompt># </prompt><userinput><command>service</command> ntpd start</userinput></screen> + </section> + <section id="sect-qig-Environment-operatingsys-repoconfig"> + <title>Configuring the CloudStack Package Repository</title> + <para> + We need to configure the machine to use a CloudStack package repository. + <important> + <title>The below repository is not an official Apache CloudStack project repository</title> + <para> + The Apache CloudStack official releases are source code. As such there are no + 'official' binaries available. The full installation guide describes how to take + the source release and generate RPMs and and yum repository. This guide attempts + to keep things as simple as possible, and thus we are using one of the + community-provided yum repositories. + </para> + </important> + </para> + <para>To add the CloudStack repository, create <filename>/etc/yum.repos.d/cloudstack.repo</filename> and insert the following information.</para> + <programlisting> +[cloudstack] +name=cloudstack +baseurl=http://cloudstack.apt-get.eu/rhel/4.1/ +enabled=1 +gpgcheck=0 + </programlisting> + </section> + </section> + <section id="sect-qig-Environment-nfs"> + <title>NFS</title> + <para> + Our configuration is going to use NFS for both primary and secondary + storage. We are going to go ahead and setup two NFS shares for those + purposes. We'll start out by installing + <application>nfs-utils</application>. + </para> + <screen><prompt># </prompt><userinput><command>yum</command> install nfs-utils</userinput></screen> + <para> + We now need to configure NFS to serve up two different shares. This is handled comparatively easily + in the <filename>/etc/exports</filename> file. You should ensure that it has the following content: + </para> + <screen> +/secondary *(rw,async,no_root_squash) +/primary *(rw,async,no_root_squash) + </screen> + <para> + You will note that we specified two directories that don't exist (yet) on the system. + We'll go ahead and create those directories and set permissions appropriately on them with the following commands: + </para> + <screen> +<prompt># </prompt><userinput><command>mkdir</command> /primary</userinput> +<prompt># </prompt><userinput><command>mkdir</command> /secondary</userinput> + </screen> + <para>CentOS 6.x releases use NFSv4 by default. NFSv4 requires that domain setting matches on all clients. + In our case, the domain is cloud.priv, so ensure that the domain setting in <filename>/etc/idmapd.conf</filename> + is uncommented and set as follows:</para> + <screen>Domain = cloud.priv</screen> + <para>Now you'll need uncomment the configuration values in the file <filename>/etc/sysconfig/nfs</filename></para> + <screen> +LOCKD_TCPPORT=32803 +LOCKD_UDPPORT=32769 +MOUNTD_PORT=892 +RQUOTAD_PORT=875 +STATD_PORT=662 +STATD_OUTGOING_PORT=2020 + </screen> + <para> Now we need to configure the firewall to permit incoming NFS connections. + Edit the file <filename>/etc/sysconfig/iptables</filename> + </para> + <screen> +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p udp --dport 111 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p tcp --dport 111 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p tcp --dport 2049 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p tcp --dport 32803 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p udp --dport 32769 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p tcp --dport 892 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p udp --dport 892 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p tcp --dport 875 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p udp --dport 875 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p tcp --dport 662 -j ACCEPT +-A INPUT -s 172.16.10.0/24 -m state --state NEW -p udp --dport 662 -j ACCEPT + </screen> + <para>Now you can restart the iptables service with the following command: + </para> + <screen><prompt># </prompt><userinput><command>service</command> iptables restart</userinput></screen> + <para>We now need to configure nfs service to start on boot and actually start it on the host by + executing the following commands:</para> + <screen> +<prompt># </prompt><userinput><command>service</command> rpcbind start</userinput> +<prompt># </prompt><userinput><command>service</command> nfs start</userinput> +<prompt># </prompt><userinput><command>chkconfig</command> rpcbind on</userinput> +<prompt># </prompt><userinput><command>chkconfig</command> nfs on</userinput> + </screen> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Management.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Management.xml b/docs/qig/en-US/Management.xml new file mode 100644 index 0000000..8c6040f --- /dev/null +++ b/docs/qig/en-US/Management.xml @@ -0,0 +1,99 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + + +<chapter id="chap-qig-Management"> + <title>Installation of the management server</title> + <para> + Now it is time to start installing CloudStack's management server + and some of the related components. + </para> + <section id="sect-qig-Management-database"> + <title>Database Installation and Configuration</title> + <para> + We'll start out by installing <application>MySQL</application> and configuring + some options to ensure CloudStack runs well. + </para> + <para> + To install <application>MySQL</application> run the following command: + <screen><prompt># </prompt><userinput><command>yum</command> -y install mysql-server</userinput></screen> + </para> + <para>With <application>MySQL</application> installed we need to make + a few configuration changes to <filename>/etc/my.cnf</filename>. + Specifically we need to add the following options to the [mysqld] section: + <screen> +innodb_rollback_on_timeout=1 +innodb_lock_wait_timeout=600 +max_connections=350 +log-bin=mysql-bin +binlog-format = 'ROW' + </screen> + </para> + <para> + Now that <application>MySQL</application> is properly configured we can + start it and configure it to start on boot as follows: + <screen> +<prompt># </prompt><userinput><command>service</command> mysqld start</userinput> +<prompt># </prompt><userinput><command>chkconfig</command> mysqld on</userinput> + </screen> + </para> + + </section> + + <section id="sect-qig-Management-installation"> + <title>Installation</title> + <para>We are now going to install the management server. We do that by executing the following command: + <screen><prompt># </prompt><userinput><command>yum</command> -y install cloud-client</userinput></screen> + </para> + <para>With the application itself installed we can now setup the database, we'll do that with the following command + and options: + </para> + <screen><prompt># </prompt><userinput><command>cloudstack-setup-databases</command> cloud:<replaceable>password</replaceable>@localhost --deploy-as=root</userinput></screen> + <para>When this process is finished, you should see a message like "CloudStack has successfully initialized the database." + </para> + <para>Now that the database has been created, we can take the final step in setting up the management server by issuing the following command:</para> + <screen><prompt># </prompt><userinput><command>cloudstack-setup-management</command></userinput></screen> + </section> + <section id="sect-qig-Management-templatesetup"> + <title>System Template Setup</title> + <para>CloudStack uses a number of system VMs to provide functionality for + accessing the console of virtual machines, providing various networking + services, and managing various aspects of storage. This step will + acquire those system images ready for deployment when we bootstrap + your cloud. + </para> + <para> + Now we need to download the system VM template and deploy that to the + share we just mounted. The management server includes a script to properly + manipulate the system VMs images. + </para> + <screen><prompt># </prompt><userinput><command>/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt</command> -m /secondary -u http://download.cloud.com/templates/acton/acton-systemvm-02062012.qcow2.bz2 -h kvm -F</userinput> + </screen> + <para> + That concludes our setup of the management server. We still need to + configure CloudStack, but we will do that after we get our hypervisor + set up. + </para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Overview.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Overview.xml b/docs/qig/en-US/Overview.xml new file mode 100644 index 0000000..31915f5 --- /dev/null +++ b/docs/qig/en-US/Overview.xml @@ -0,0 +1,93 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + + +<chapter id="chap-qig-Overview"> + <title>Overview</title> + <para> + Infrastructure-as-a-Service (IaaS) clouds can be a complex thing to build, + and by definition they have a plethora of options, which often lead to confusion + for even experienced admins who are newcomers to building cloud platforms. + The goal for this runbook is to provide a straightforward set of instructions + to get you up and running with CloudStack with a minimum amount of trouble. + </para> + <section id="sect-qig-Overview-What_building"> + <title>What exactly are we building?</title> + <para> + This runbook will focus on building a CloudStack cloud using KVM with + CentOS 6.4 with NFS storage on a flat layer-2 network utilizing + layer-3 network isolation (aka Security Groups), and doing it all + on a single piece of hardware. + </para> + <para> + KVM, or Kernel-based Virtual Machine is a virtualization technology + for the Linux kernel. KVM supports native virtualization atop + processors with hardware virtualization extensions. + </para> + <para> + Security Groups act as distributed firewalls that control access + to a group of virtual machines. + </para> + </section> + <section id="sect-qig-Overview-hilevel"> + <title>High level overview of the process</title> + <para> + Before we actually get to installing CloudStack, we'll start with + installing our base operating system, and then configuring that to act + as an NFS server for several types of storage. We'll install the + management server, download the systemVMs, and finally install the agent + software. Finally we'll spend a good deal of time configuring the entire + cloud in the CloudStack web interface. + </para> + </section> + <section id="sect-qig-Overview-prereqs"> + <title>Prerequisites</title> + <para> + To complete this runbook you'll need the following items: + <orderedlist> + <listitem> + <para> + At least one computer which supports hardware virtualization. + </para> + </listitem> + <listitem> + <para> + The + <ulink url="http://mirror.stanford.edu/yum/pub/centos/6.4/isos/x86_64/CentOS-6.4-x86_64-minimal.iso";> + CentOS 6.4 x86_64 minimal install CD + </ulink> + </para> + </listitem> + <listitem> + <para> + A /24 network with the gateway being at xxx.xxx.xxx.1, no DHCP should be on this network and + none of the computers running CloudStack will have a dynamic address. Again this is done for + the sake of simplicity. + </para> + </listitem> + </orderedlist> + </para> + </section> + +</chapter> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Preface.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Preface.xml b/docs/qig/en-US/Preface.xml new file mode 100644 index 0000000..d6ba80e --- /dev/null +++ b/docs/qig/en-US/Preface.xml @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.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. +--> + + +<preface id="pref-qig-Preface"> + <title>Preface</title> + <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude";><xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude";><xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + </xi:fallback> + </xi:include> +</preface> + http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/Revision_History.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/Revision_History.xml b/docs/qig/en-US/Revision_History.xml new file mode 100644 index 0000000..1ff4d77 --- /dev/null +++ b/docs/qig/en-US/Revision_History.xml @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.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. +--> + + +<appendix id="appe-qig-Revision_History"> + <title>Revision History</title> + <simpara> + <revhistory> + <revision> + <revnumber>0-0</revnumber> + <date>Fri Jun 28 2013</date> + <revdescription> + <simplelist> + <member>Initial creation of book by publican</member> + </simplelist> + </revdescription> + </revision> + </revhistory> + </simpara> +</appendix> + http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/config.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/config.xml b/docs/qig/en-US/config.xml new file mode 100644 index 0000000..7ff7a72 --- /dev/null +++ b/docs/qig/en-US/config.xml @@ -0,0 +1,177 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + + +<chapter id="chap-qig-Config"> + <title>Configuration</title> + <para> + As we noted before we will be using security groups to provide isolation + and by default that implies that we'll be using a flat layer-2 network. + It also means that the simplicity of our setup means that we can use the + quick installer. + </para> + <section id="sect-qig-Config-UI_Access"> + <title>UI Access</title> + <para> + To get access to CloudStack's web interface, merely point your + browser to http://<replaceable>172.16.10.</replaceable>2:8080/client + The default username is 'admin', and the default password is 'password'. + You should see a splash screen that allows you to choose several options + for setting up CloudStack. You should choose the + <option>Continue with Basic Setup</option> option. + </para> + <para> + You should now see a prompt requiring you to change the password for + the admin user. Please do so. + </para> + </section> + <section id="sect-qig-Config-Zone"> + <title>Setting up a Zone</title> + <para> + A zone is the largest organization entity in CloudStack - and we'll be creating one, this + should be the screen that you see in front of you now. And for us there are 5 pieces of + information that we need. + <orderedlist> + <listitem> + <para>Name - we will set this to the ever-descriptive 'Zone1' for our cloud.</para> + </listitem> + <listitem> + <para>Public DNS 1 - we will set this to '8.8.8.8' for our cloud.</para> + </listitem> + <listitem> + <para>Public DNS 2 - we will set this to '8.8.4.4' for our cloud.</para> + </listitem> + <listitem> + <para>Internal DNS1 - we will also set this to '8.8.8.8' for our cloud.</para> + </listitem> + <listitem> + <para>Internal DNS2 - we will also set this to '8.8.8.4' for our cloud.</para> + </listitem> + </orderedlist> + </para> + <note> + <title>Notes about DNS settings</title> + <para> + CloudStack distinguishes between internal and public DNS. Internal + DNS is assumed to be capable of resolving internal-only + hostnames, such as your NFS serverâs DNS name. Public DNS is + provided to the guest VMs to resolve public IP addresses. You can + enter the same DNS server for both types, but if you do so, you + must make sure that both internal and public IP addresses can + route to the DNS server. In our specific case we will not use any + names for resources internally, and we have indeed them set to look + to the same external resource so as to not add a namerserver setup + to our list of requirements. + </para> + </note> + </section> + <section id="sect-qig-Config-Pod"> + <title>Pod Configuration</title> + <para>Now that we've added a Zone, the next step that comes up is a prompt + for information regading a pod. Which is looking for 4 items. + <orderedlist> + <listitem> + <para>Name - We'll use Pod1 for our cloud.</para> + </listitem> + <listitem> + <para>Gateway - We'll use <replaceable>172.16.10</replaceable>.1 as our gateway</para> + </listitem> + <listitem> + <para>Netmask - We'll use 255.255.255.0</para> + </listitem> + <listitem> + <para>Start/end reserved system IPs - we will use 172.16.10.10-172.16.10.20 </para> + </listitem> + <listitem> + <para>Guest gateway - We'll use <replaceable>172.16.10</replaceable>.1</para> + </listitem> + <listitem> + <para>Guest netmask - We'll use 255.255.255.0</para> + </listitem> + <listitem> + <para>Guest start/end IP - We'll use <replaceable>172.16.10.</replaceable>30-<replaceable>172.16.10.</replaceable>200</para> + </listitem> + </orderedlist> + </para> + </section> + <section id="Runbook-config-cluster"> + <title>Cluster</title> + <para> Now that we've added a Zone, we need only add a few more items for configuring the cluster. + <orderedlist> + <listitem> + <para>Name - We'll use Cluster1</para> + </listitem> + <listitem> + <para>Hypervisor - Choose KVM</para> + </listitem> + </orderedlist> + </para> + <para> You should be prompted to add the first host to your cluster at this point. Only a few bits of information are needed. + <orderedlist> + <listitem> + <para>Hostname - we'll use the IP address <replaceable>172.16.10.</replaceable>2 since we didn't set up a DNS server.</para> + </listitem> + <listitem> + <para>Username - we'll use 'root' </para> + </listitem> + <listitem> + <para>Password - enter the operating system password for the root user</para> + </listitem> + </orderedlist> + </para> + <section id="Runbook-config-cluster-pristorage"> + <title>Primary Storage</title> + <para>With your cluster now setup - you should be prompted for primary storage information. Choose NFS as the storage type and then enter the following values in the fields: + <orderedlist> + <listitem> + <para>Name - We'll use 'Primary1'</para> + </listitem> + <listitem> + <para>Server - We'll be using the IP address <replaceable>172.16.10.</replaceable>2</para> + </listitem> + <listitem> + <para>Path - Well define /primary as the path we are using </para> + </listitem> + </orderedlist> + </para> + </section> + <section id="Runbook-config-cluster-secstorage"> + <title>Secondary Storage</title> + <para> If this is a new zone, you'll be prompted for secondary storage information - populate it as follows: + <orderedlist> + <listitem> + <para>NFS server - We'll use the IP address <replaceable>172.16.10.</replaceable>2</para> + </listitem> + <listitem> + <para>Path - We'll use /secondary</para> + </listitem> + </orderedlist> + </para> + <para> Now, click Launch and your cloud should begin setup - it may take several minutes depending on your internet connection speed for setup to finalize.</para> + </section> + </section> + + +</chapter> + http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/kvm.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/kvm.xml b/docs/qig/en-US/kvm.xml new file mode 100644 index 0000000..91ed9d5 --- /dev/null +++ b/docs/qig/en-US/kvm.xml @@ -0,0 +1,142 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "qig.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + + +<chapter id="chap-qig-KVM"> + <title>KVM Setup and installation</title> + <para> + KVM is the hypervisor we'll be using - we will recover the initial setup + which has already been done on the hypervisor host and cover installation + of the agent software, you can use the same steps to add additional KVM + nodes to your CloudStack environment. + </para> + <section id="sect-qig-KVM-Prerequisites"> + <title>Prerequisites</title> + <para> + We explicitly are using the management server as a compute node as well, + which means that we have already performed many of the prerequisite steps + when setting up the management server, but we will list them here for + clarity. Those steps are: + <orderedlist> + <listitem> + <para> + <xref linkend="sect-qig-Environment-operatingsys-network" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-qig-Environment-operatingsys-hostname" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-qig-Environment-operatingsys-selinux" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-qig-Environment-operatingsys-ntp" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-qig-Environment-operatingsys-repoconfig" /> + </para> + </listitem> + </orderedlist> + </para> + <para> + You shouldn't need to do that for the management server, of course, but + any additional hosts will need for you to complete the above steps. + </para> + </section> + + <section id="sect-qig-KVM-Installation"> + <title>Installation</title> + <para>Installation of the KVM agent is trivial with just a single command, but afterwards we'll need to configure a few things.</para> + <screen><prompt># </prompt><userinput><command>yum</command> -y install cloud-agent</userinput></screen> + <section id="sect-qig-KVM-Configuration"> + <title>KVM Configuration</title> + <para>We have two different parts of KVM to configure, libvirt, and QEMU.</para> + <section id="sect-qig-KVM-Configuration-qemu"> + <title>QEMU Configuration</title> + <para> + KVM configuration is relatively simple at only a single item. We need to + edit the QEMU VNC configuration. This is done by editing + <filename>/etc/libvirt/qemu.conf</filename> and ensuring the following + line is present and uncommented. + <screen>vnc_listen=0.0.0.0</screen> + </para> + </section> + <section id="sect-qig-KVM-Configuration-libvirt"> + <title>Libvirt Configuration</title> + <para> + CloudStack uses libvirt for managing virtual machines. Therefore it + is vital that libvirt is configured correctly. Libvirt is a dependency + of cloud-agent and should already be installed. + </para> + <orderedlist> + <listitem> + <para>In order to have live migration working libvirt has to listen + for unsecured TCP connections. We also need to turn off libvirts + attempt to use Multicast DNS advertising. Both of these settings + are in <filename>/etc/libvirt/libvirtd.conf</filename> + </para> + <para>Set the following paramaters:</para> + <programlisting>listen_tls = 0</programlisting> + <programlisting>listen_tcp = 1</programlisting> + <programlisting>tcp_port = "16059"</programlisting> + <programlisting>auth_tcp = "none"</programlisting> + <programlisting>mdns_adv = 0</programlisting> + </listitem> + <listitem> + <para>Turning on "listen_tcp" in libvirtd.conf is not enough, we have to change the parameters as well:</para> + <para>On RHEL or CentOS modify <filename>/etc/sysconfig/libvirtd</filename>:</para> + <para>Uncomment the following line:</para> + <programlisting>#LIBVIRTD_ARGS="--listen"</programlisting> + <para>On Ubuntu: modify <filename>/etc/init/libvirt-bin.conf</filename></para> + <para>Change the following line (at the end of the file):</para> + <programlisting>exec /usr/sbin/libvirtd -d</programlisting> + <para>to (just add -l)</para> + <programlisting>exec /usr/sbin/libvirtd -d -l</programlisting> + </listitem> + <listitem> + <para>Restart libvirt</para> + <para>In RHEL or CentOS:</para> + <programlisting><command>$ service libvirtd restart</command></programlisting> + <para>In Ubuntu:</para> + <programlisting><command>$ service libvirt-bin restart</command></programlisting> + </listitem> + </orderedlist> + </section> + <section id="sect-qig-KVM-Configuration-finish"> + <title>KVM configuration complete</title> + <para> + That concludes our installation and configuration of KVM, and we'll now move to using the CloudStack UI + for the actual configuration of our cloud. + </para> + </section> + </section> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/qig.ent ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/qig.ent b/docs/qig/en-US/qig.ent new file mode 100644 index 0000000..3b1649a --- /dev/null +++ b/docs/qig/en-US/qig.ent @@ -0,0 +1,22 @@ +<!-- 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. +--> + +<!ENTITY PRODUCT "Apache CloudStack"> +<!ENTITY BOOKID "Quick Install Guide"> +<!ENTITY YEAR "2013"> +<!ENTITY HOLDER "Apache Software Foundation"> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/676d8744/docs/qig/en-US/qig.xml ---------------------------------------------------------------------- diff --git a/docs/qig/en-US/qig.xml b/docs/qig/en-US/qig.xml new file mode 100644 index 0000000..00dd2e4 --- /dev/null +++ b/docs/qig/en-US/qig.xml @@ -0,0 +1,36 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Runbook.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. +--> + + +<book> + <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="Environment.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="kvm.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="config.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> +<!-- <index /> --> +</book>
