diff --git a/docs/installing.sgml b/docs/installing.sgml
index 2b11c75be3d65bbf757aad7c116cb7b5989a1fef..689fc935bcf2c07ebdd6b94b7fbbd7ce3a5a47f8 100644
--- a/docs/installing.sgml
+++ b/docs/installing.sgml
@@ -9,39 +9,46 @@
<sect1>
<title>Introduction</title>
- <para>Ganeti is a cluster virtualization management system. This document
- explains how to bootstrap a Ganeti node and create a running cluster. You
- need to repeat most of the steps in this document for every node you want to
- install, but of course we recommend creating some semi-automatic procedure
- if you plan to deploy Ganeti on a medium/large scale.
+ <para>
+ Ganeti is a cluster virtualization management system. This
+ document explains how to bootstrap a Ganeti node and create a
+ running cluster. You need to repeat most of the steps in this
+ document for every node you want to install, but of course we
+ recommend creating some semi-automatic procedure if you plan to
+ deploy Ganeti on a medium/large scale.
</para>
<para>This document is divided into two main sections:
<itemizedlist>
<listitem>
- <simpara>Installation of the core system and base components</simpara>
+ <simpara>Installation of the core system and base
+ components</simpara>
</listitem>
<listitem>
- <simpara>Configuration of the environment for Ganeti</simpara>
+ <simpara>Configuration of the environment for
+ Ganeti</simpara>
</listitem>
</itemizedlist>
- Each of these is divided into sub-sections. While a full Ganeti system will
- need all of the steps specified, some are not strictly required for every
- environment. Which ones they are, and why, is specified in the
- corresponding sections.
+ Each of these is divided into sub-sections. While a full Ganeti
+ system will need all of the steps specified, some are not strictly
+ required for every environment. Which ones they are, and why, is
+ specified in the corresponding sections.
</para>
- <para>While Ganeti itself is distribution-agnostic most of the examples in
- this document will be targeted at Debian or debian derived distributions.
- You are expected to be familiar with your distribution, its package
- management system, and Xen before trying to use Ganeti.
+ <para>
+ While Ganeti itself is distribution-agnostic most of the
+ examples in this document will be targeted at Debian or
+ Debian-derived distributions. You are expected to be familiar
+ with your distribution, its package management system, and Xen
+ before trying to use Ganeti.
</para>
- <para>A basic Ganeti terminology glossary is provided in the introductory
- section of the "admin guide". Please refer to that if you are uncertain
- about the terms we are using.
+ <para>
+ A basic Ganeti terminology glossary is provided in the
+ introductory section of the "admin guide". Please refer to that
+ if you are uncertain about the terms we are using.
</para>
</sect1>
@@ -52,16 +59,17 @@
<sect2>
<title>Installing the base system</title>
- <para>Mandatory.
- </para>
+ <para><emphasis role="strong">Mandatory.</emphasis></para>
- <para>Please install your operating system as you would normally do. The
- only requirement you need to be aware of at this stage is to partition
- leaving enough space for a big LVM volume group which will then host
- your instance file systems. You can even create the volume group at
- installation time, of course: the default volume group name Ganeti 1.2
- uses is "xenvg" but you may name it differently should you wish to, as
- long as the name is the same for all the nodes in the cluster.
+ <para>
+ Please install your operating system as you would normally
+ do. The only requirement you need to be aware of at this stage
+ is to partition leaving enough space for a big LVM volume
+ group which will then host your instance file systems. You can
+ even create the volume group at installation time, of course:
+ the default volume group name Ganeti 1.2 uses is "xenvg" but
+ you may name it differently should you wish to, as long as the
+ name is the same for all the nodes in the cluster.
</para>
</sect2>
@@ -69,25 +77,30 @@
<sect2>
<title>Installing Xen</title>
- <para>Mandatory: While Ganeti is developed with the ability to modularly
- run on different virtualization environments in mind the only one
- currently useable on a live system is Xen.
+ <para>
+ <emphasis role="strong">Mandatory:</emphasis> While Ganeti is
+ developed with the ability to modularly run on different
+ virtualization environments in mind the only one currently
+ useable on a live system is Xen.
</para>
- <para>Please follow your distribution's recommended way to install and set
- up Xen, or install Xen from the upstream source, if you wish, following
- their manual.
+ <para>
+ Please follow your distribution's recommended way to install
+ and set up Xen, or install Xen from the upstream source, if
+ you wish, following their manual.
</para>
- <para>For example under Debian 4.0 or 3.1+backports you can install the
- relevant xen-linux-system package, which will pull in both the hypervisor
- and the relevant kernel. On Ubuntu (from Gutsy on) the package is called
- ubuntu-xen-server.
+ <para>
+ For example under Debian 4.0 or 3.1+backports you can install
+ the relevant xen-linux-system package, which will pull in both
+ the hypervisor and the relevant kernel. On Ubuntu (from Gutsy
+ on) the package is called ubuntu-xen-server.
</para>
- <para>After installing Xen you need to reboot into your xenified dom0
- system. Again on some distributions this might involve configuring GRUB
- appropriately.
+ <para>
+ After installing Xen you need to reboot into your xenified
+ dom0 system. Again on some distributions this might involve
+ configuring GRUB appropriately.
</para>
</sect2>
@@ -95,35 +108,40 @@
<sect2>
<title>Installing DRBD</title>
- <para>Recommended: DRBD is required if you want to use the high
- availability (HA) features of Ganeti, but optional if you don't require
- HA or only run Ganeti on single-node clusters. You can upgrade a non-HA
- cluster to an HA one later, but you might need to export and reimport
- all your instances to take advantage of the new features.
+ <para>
+ Recommended: DRBD is required if you want to use the high
+ availability (HA) features of Ganeti, but optional if you
+ don't require HA or only run Ganeti on single-node
+ clusters. You can upgrade a non-HA cluster to an HA one later,
+ but you might need to export and reimport all your instances
+ to take advantage of the new features.
</para>
- <para>Now the bad news: unless your distribution already provides it
- installing DRBD might involve recompiling your kernel or anyway fiddling
- with it. Hopefully at least the xenified kernel source to start from will
- be provided.
+ <para>
+ Now the bad news: unless your distribution already provides it
+ installing DRBD might involve recompiling your kernel or
+ anyway fiddling with it. Hopefully at least the xenified
+ kernel source to start from will be provided.
</para>
- <para>Under Debian you can just install the drbd0.7-module-source and
- drbd0.7-utils packages, and your kernel source, and then run
- module-assistant to compile the drbd0.7 module. The commands:
+ <para>
+ Under Debian you can just install the drbd0.7-module-source
+ and drbd0.7-utils packages, and your kernel source, and then
+ run module-assistant to compile the drbd0.7 module. The
+ following commands should do it:
+ </para>
- <programlisting>
+ <screen>
m-a update
m-a a-i drbd0.7
- </programlisting>
-
- should do it for you.
- </para>
+ </screen>
- <para>The good news is that you don't need to configure DRBD at all.
- Ganeti will do it for you for every instance you set up. If you have the
- DRBD utils installed and the module in your kernel you're fine. Please
- check that your system is configured to load the module at every boot.
+ <para>
+ The good news is that you don't need to configure DRBD at all.
+ Ganeti will do it for you for every instance you set up. If
+ you have the DRBD utils installed and the module in your
+ kernel you're fine. Please check that your system is
+ configured to load the module at every boot.
</para>
</sect2>
@@ -144,35 +162,35 @@ m-a a-i drbd0.7
</para>
<para>
- In Debian, in order to enable the default Xen behaviour, you have to edit
- /etc/xen/xend-config.sxp and replace (network-script network-dummy) with
- (network-script network-bridge). The recommended Debian way to configure
- things, though, is to edit your /etc/network/interfaces file and
- substitute your normal ethernet stanza with something like:
-
- <programlisting>
+ In Debian, in order to enable the default Xen behaviour, you
+ have to edit <filename>/etc/xen/xend-config.sxp</filename> and
+ replace <computeroutput>(network-script
+ network-dummy)</computeroutput> with
+ <computeroutput>(network-script
+ network-bridge)</computeroutput>. The recommended Debian way to
+ configure things, though, is to edit your
+ <filename>/etc/network/interfaces</filename> file and substitute
+ your normal ethernet stanza with something like:</para>
+
+ <screen>
auto br0
iface br0 inet static
- address YOUR_IP_ADDRESS
- netmask YOUR_NETMASK
- network YOUR_NETWORK
- broadcast YOUR_BROADCAST_ADDRSS
- gateway YOUR_GATEWAY
- # dns-* options are implemented by the resolvconf package, if installed
- dns-nameservers YOUR_DNS_SERVERS
- dns-search YOUR_SEARCH_PATH
- bridge_ports eth0
+ address <replaceable>YOUR_IP_ADDRESS</replaceable>
+ netmask <replaceable>YOUR_NETMASK</replaceable>
+ network <replaceable>YOUR_NETWORK</replaceable>
+ broadcast <replaceable>YOUR_BROADCAST_ADDRESS</replaceable>
+ gateway <replaceable>YOUR_GATEWAY</replaceable>
+ bridge_ports <replaceable>eth0</replaceable>
bridge_stp off
bridge_fd 0
- </programlisting>
-
- </para>
+ </screen>
<para>
- Beware that the default name Ganeti uses is xen-br0 (which was used in
- Xen 2.0) while Xen 3.0 uses xenbr0 by default. The default bridge your
- cluster will use for new instances can be specified at cluster
- initialization time.
+ Beware that the default name Ganeti uses is
+ <hardware>xen-br0</hardware> (which was used in Xen 2.0)
+ while Xen 3.0 uses <hardware>xenbr0</hardware> by
+ default. The default bridge your cluster will use for new
+ instances can be specified at cluster initialization time.
</para>
</sect2>
@@ -181,28 +199,30 @@ iface br0 inet static
<title>Configuring LVM</title>
<para>
- If you haven't configured your LVM volume group at install time you need
- to do it before trying to initialize the Ganeti cluster. This is done by
- formatting the devices/partitions you want to use for it and then adding
- them to the relevant volume group:
-
- <programlisting>
+ If you haven't configured your LVM volume group at install
+ time you need to do it before trying to initialize the Ganeti
+ cluster. This is done by formatting the devices/partitions you
+ want to use for it and then adding them to the relevant volume
+ group:
+ </para>
+
+ <screen>
pvcreate /dev/sda4
pvcreate /dev/sdb
pvcreate /dev/sdc1
vgcreate xenvg /dev/sda4 /dev/sdb /dev/sdc1
- </programlisting>
- </para>
+ </screen>
<para>
- If you want to add a device later you can do so with the
+ If you want to add a device later you can do so with the
<citerefentry><refentrytitle>vgextend</refentrytitle>
- <manvolnum>8</manvolnum></citerefentry> command.
- <programlisting>
+ <manvolnum>8</manvolnum></citerefentry> command:
+ </para>
+
+ <screen>
pvcreate /dev/sdd
vgextend xenvg /dev/sdd
- </programlisting>
- </para>
+ </screen>
<para>
As said before you may choose a different name for the volume group,
@@ -213,27 +233,29 @@ vgextend xenvg /dev/sdd
<sect2>
<title>Installing Ganeti</title>
- <para>It's now time to install the Ganeti software itself if you haven't
- done it yet. You can do it from source, with the usual steps:
+ <para>It's now time to install the Ganeti software itself if you
+ haven't done it yet. You can do it from source, with the usual
+ steps (note that the <option>localstatedir</option> options must
+ be set to <filename class="directory">/var</filename>):
- <programlisting>
-./configure
+ <screen>
+./configure --localstatedir=/var
make
make install
- </programlisting>
+ </screen>
or you can install the package relevant to your distribution, for
example in Debian/Ubuntu:
- <programlisting>
+ <screen>
dpkg -i ganeti_VERSION_all.deb
- </programlisting>
+ </screen>
or, if you have a source repository that holds the Ganeti software:
- <programlisting>
+ <screen>
apt-get install ganeti
- </programlisting>
+ </screen>
</para>
</sect2>
@@ -251,48 +273,55 @@ apt-get install ganeti
<sect2>
<title>Initializing the cluster</title>
- <para>Mandatory: only on one node per cluster.
- </para>
+ <para><emphasis role="strong">Mandatory:</emphasis> only on one
+ node per cluster.</para>
<para>The last step is to initialize the cluster. After you've repeated
the above process or some semi-automatic form of it on all of your
nodes choose one as the master, and execute:
+ </para>
- <programlisting>
-gnt-cluster init CLUSTERNAME
- </programlisting>
+ <screen>
+gnt-cluster init <replaceable>CLUSTERNAME</replaceable>
+ </screen>
- Options you can pass to gnt-cluster init include the default bridge
- name (-b), the cluster-wide name for the volume group (-g) and the
- secondary ip address for the initial node should you wish to keep the
- data replication network separate. Invoke it with --help to see all the
- possibilities.
+ <para>
+ Options you can pass to <command>gnt-cluster init</command>
+ include the default bridge name (<option>-b</option>), the
+ cluster-wide name for the volume group (<option>-g</option>)
+ and the secondary ip address for the initial node should you
+ wish to keep the data replication network separate. Invoke it
+ with <option>--help</option> to see all the possibilities.
</para>
- <para>The cluster name must exist in DNS. You must choose a name
- different from any of the nodes names for a multi-node cluster. In
- general the best choice is to have a completely unique name for each
- cluster.
+ <para>
+ Note that the cluster name must exist in DNS. You must choose
+ a name different from any of the nodes names for a multi-node
+ cluster. In general the best choice is to have a unique name
+ for a cluster, even if it consists of only one machine.
</para>
</sect2>
<sect2>
<title>Joining the nodes to the cluster.</title>
- <para>Mandatory: for all the other nodes.
+ <para>
+ <emphasis role="strong">Mandatory:</emphasis> for all the
+ other nodes.
</para>
<para>
If you have already initialized your cluster you need to join the other
nodes to it. You can do so by executing the following command on the
master node:
- <programlisting>
-gnt-node add NODENAME
- </programlisting>
+ <screen>
+gnt-node add <replaceable>NODENAME</replaceable>
+ </screen>
- The only option is (-s), which sets the node's secondary ip address for
- replication purposes, if you are using a separate replication network.
+ The only option is <option>-s</option>, which sets the node's
+ secondary ip address for replication purposes, if you are
+ using a separate replication network.
</para>
</sect2>
@@ -301,7 +330,9 @@ gnt-node add NODENAME
<sect1>
<title>This is it!</title>
- <para>Now you can follow the "admin guide" to use your new Ganeti cluster.
+ <para>
+ Now you can follow the admin guide to use your new Ganeti
+ cluster.
</para>
</sect1>