Commit 5d6dd340 authored by Iustin Pop's avatar Iustin Pop
Browse files

Some changes to the installation manual.

The biggest change is that at configure time one must specify
--localstatedir=/var since the directories for ganeti (/var/log/ganeti,
/var/lib/ganeti) must be located here.

Reviewed-by: ultrotter
parent 3ecf6786
......@@ -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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment