Update Xen documentation in install.rst
[ganeti-github.git] / doc / install.rst
1 Ganeti installation tutorial
2 ============================
3
4 Documents Ganeti version |version|
5
6 .. contents::
7
8 .. highlight:: shell-example
9
10 Introduction
11 ------------
12
13 Ganeti is a cluster virtualization management system based on Xen or
14 KVM. This document explains how to bootstrap a Ganeti node (Xen *dom0*,
15 the host Linux system for KVM), create a running cluster and install
16 virtual instances (Xen *domUs*, KVM guests).  You need to repeat most of
17 the steps in this document for every node you want to install, but of
18 course we recommend creating some semi-automatic procedure if you plan
19 to deploy Ganeti on a medium/large scale.
20
21 A basic Ganeti terminology glossary is provided in the introductory
22 section of the :doc:`admin`. Please refer to that document if you are
23 uncertain about the terms we are using.
24
25 Ganeti has been developed for Linux and should be distribution-agnostic.
26 This documentation will use Debian Squeeze as an example system but the
27 examples can be translated to any other distribution. You are expected
28 to be familiar with your distribution, its package management system,
29 and Xen or KVM before trying to use Ganeti.
30
31 This document is divided into two main sections:
32
33 - Installation of the base system and base components
34
35 - Configuration of the environment for Ganeti
36
37 Each of these is divided into sub-sections. While a full Ganeti system
38 will need all of the steps specified, some are not strictly required for
39 every environment. Which ones they are, and why, is specified in the
40 corresponding sections.
41
42 Installing the base system and base components
43 ----------------------------------------------
44
45 Hardware requirements
46 +++++++++++++++++++++
47
48 Any system supported by your Linux distribution is fine. 64-bit systems
49 are better as they can support more memory.
50
51 Any disk drive recognized by Linux (``IDE``/``SCSI``/``SATA``/etc.) is
52 supported in Ganeti. Note that no shared storage (e.g. ``SAN``) is
53 needed to get high-availability features (but of course, one can be used
54 to store the images). Whilte it is highly recommended to use more than
55 one disk drive in order to improve speed, Ganeti also works with one
56 disk per machine.
57
58 Installing the base system
59 ++++++++++++++++++++++++++
60
61 **Mandatory** on all nodes.
62
63 It is advised to start with a clean, minimal install of the operating
64 system. The only requirement you need to be aware of at this stage is to
65 partition leaving enough space for a big (**minimum** 20GiB) LVM volume
66 group which will then host your instance filesystems, if you want to use
67 all Ganeti features. The volume group name Ganeti uses (by default) is
68 ``xenvg``.
69
70 You can also use file-based storage only, without LVM, but this setup is
71 not detailed in this document.
72
73 If you choose to use RBD-based instances, there's no need for LVM
74 provisioning. However, this feature is experimental, and is not yet
75 recommended for production clusters.
76
77 While you can use an existing system, please note that the Ganeti
78 installation is intrusive in terms of changes to the system
79 configuration, and it's best to use a newly-installed system without
80 important data on it.
81
82 Also, for best results, it's advised that the nodes have as much as
83 possible the same hardware and software configuration. This will make
84 administration much easier.
85
86 Hostname issues
87 ~~~~~~~~~~~~~~~
88
89 Note that Ganeti requires the hostnames of the systems (i.e. what the
90 ``hostname`` command outputs to be a fully-qualified name, not a short
91 name. In other words, you should use *node1.example.com* as a hostname
92 and not just *node1*.
93
94 .. admonition:: Debian
95
96    Debian usually configures the hostname differently than you need it
97    for Ganeti. For example, this is what it puts in ``/etc/hosts`` in
98    certain situations::
99
100      127.0.0.1       localhost
101      127.0.1.1       node1.example.com node1
102
103    but for Ganeti you need to have::
104
105      127.0.0.1       localhost
106      192.0.2.1       node1.example.com node1
107
108    replacing ``192.0.2.1`` with your node's address. Also, the file
109    ``/etc/hostname`` which configures the hostname of the system
110    should contain ``node1.example.com`` and not just ``node1`` (you
111    need to run the command ``/etc/init.d/hostname.sh start`` after
112    changing the file).
113
114 .. admonition:: Why a fully qualified host name
115
116    Although most distributions use only the short name in the
117    /etc/hostname file, we still think Ganeti nodes should use the full
118    name. The reason for this is that calling 'hostname --fqdn' requires
119    the resolver library to work and is a 'guess' via heuristics at what
120    is your domain name. Since Ganeti can be used among other things to
121    host DNS servers, we don't want to depend on them as much as
122    possible, and we'd rather have the uname() syscall return the full
123    node name.
124
125    We haven't ever found any breakage in using a full hostname on a
126    Linux system, and anyway we recommend to have only a minimal
127    installation on Ganeti nodes, and to use instances (or other
128    dedicated machines) to run the rest of your network services. By
129    doing this you can change the /etc/hostname file to contain an FQDN
130    without the fear of breaking anything unrelated.
131
132
133 Installing The Hypervisor
134 +++++++++++++++++++++++++
135
136 **Mandatory** on all nodes.
137
138 While Ganeti is developed with the ability to modularly run on different
139 virtualization environments in mind the only two currently useable on a
140 live system are Xen and KVM. Supported Xen versions are: 3.0.3 and later
141 3.x versions, and 4.x (tested up to 4.1).  Supported KVM versions are 72
142 and above.
143
144 Please follow your distribution's recommended way to install and set up
145 Xen, or install Xen from the upstream source, if you wish, following
146 their manual. For KVM, make sure you have a KVM-enabled kernel and the
147 KVM tools.
148
149 After installing Xen, you need to reboot into your new system. On some
150 distributions this might involve configuring GRUB appropriately, whereas
151 others will configure it automatically when you install the respective
152 kernels. For KVM no reboot should be necessary.
153
154 .. admonition:: Xen on Debian
155
156    Under Debian you can install the relevant ``xen-linux-system``
157    package, which will pull in both the hypervisor and the relevant
158    kernel. Also, if you are installing a 32-bit system, you should
159    install the ``libc6-xen`` package (run ``apt-get install
160    libc6-xen``).
161
162 Xen settings
163 ~~~~~~~~~~~~
164
165 Depending on which toolstack you are using, the hypervisor parameter
166 ``xen_cmd`` has to be set to the matching value, either ``xm`` or
167 ``xl``.
168
169 Some useful best practices for Xen are to restrict the amount of memory
170 dom0 has available, and pin the dom0 to a limited number of CPUs.
171 Instructions for how to achieve this for various toolstacks can be found
172 on the Xen wiki_.
173
174 .. _wiki: http://wiki.xenproject.org/wiki/Xen_Project_Best_Practices
175
176 It is recommended that you disable Xen's automatic save of virtual
177 machines at system shutdown and subsequent restore of them at reboot.
178 To obtain this make sure the variable ``XENDOMAINS_SAVE`` in the file
179 ``/etc/default/xendomains`` is set to an empty value.
180
181 You may need to restart the Xen daemon for some of these settings to
182 take effect. The best way to do this depends on your distribution.
183
184 Selecting the instance kernel
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
186
187 After you have installed Xen, you need to tell Ganeti exactly what
188 kernel to use for the instances it will create. This is done by creating
189 a symlink from your actual kernel to ``/boot/vmlinuz-3-xenU``, and one
190 from your initrd to ``/boot/initrd-3-xenU`` [#defkernel]_. Note that
191 if you don't use an initrd for the domU kernel, you don't need to create
192 the initrd symlink.
193
194 .. admonition:: Debian
195
196    After installation of the ``xen-linux-system`` package, you need to
197    run (replace the exact version number with the one you have)::
198
199      $ cd /boot
200      $ ln -s vmlinuz-%2.6.26-1%-xen-amd64 vmlinuz-3-xenU
201      $ ln -s initrd.img-%2.6.26-1%-xen-amd64 initrd-3-xenU
202
203    By default, the initrd doesn't contain the Xen block drivers needed
204    to mount the root device, so it is recommended to update the initrd
205    by following these two steps:
206
207    - edit ``/etc/initramfs-tools/modules`` and add ``xen_blkfront``
208    - run ``update-initramfs -u``
209
210 Installing DRBD
211 +++++++++++++++
212
213 Recommended on all nodes: DRBD_ is required if you want to use the high
214 availability (HA) features of Ganeti, but optional if you don't require
215 them or only run Ganeti on single-node clusters. You can upgrade a
216 non-HA cluster to an HA one later, but you might need to convert all
217 your instances to DRBD to take advantage of the new features.
218
219 .. _DRBD: http://www.drbd.org/
220
221 Supported DRBD versions: 8.0-8.4. It's recommended to have at least
222 version 8.0.12. Note that for version 8.2 and newer it is needed to pass
223 the ``usermode_helper=/bin/true`` parameter to the module, either by
224 configuring ``/etc/modules`` or when inserting it manually. When using
225 Xen and DRBD 8.3.2 or higher, it is recommended_ to use the
226 ``disable_sendpage=1`` setting as well.
227
228 .. _recommended: https://drbd.linbit.com/users-guide/s-xen-drbd-mod-params.html
229
230 Now the bad news: unless your distribution already provides it
231 installing DRBD might involve recompiling your kernel or anyway fiddling
232 with it. Hopefully at least the Xen-ified kernel source to start from
233 will be provided (if you intend to use Xen).
234
235 The good news is that you don't need to configure DRBD at all. Ganeti
236 will do it for you for every instance you set up.  If you have the DRBD
237 utils installed and the module in your kernel you're fine. Please check
238 that your system is configured to load the module at every boot, and
239 that it passes the following option to the module:
240 ``minor_count=NUMBER``. We recommend that you use 128 as the value of
241 the minor_count - this will allow you to use up to 64 instances in total
242 per node (both primary and secondary, when using only one disk per
243 instance). You can increase the number up to 255 if you need more
244 instances on a node.
245
246
247 .. admonition:: Debian
248
249    On Debian, you can just install (build) the DRBD module with the
250    following commands, making sure you are running the target (Xen or
251    KVM) kernel::
252
253      $ apt-get install drbd8-source drbd8-utils
254      $ m-a update
255      $ m-a a-i drbd8
256
257    Or on newer versions, if the kernel already has modules:
258
259      $ apt-get install drbd8-utils
260
261    Then to configure it for Ganeti::
262
263      $ echo "options drbd minor_count=128 usermode_helper=/bin/true" \
264         > /etc/modprobe.d/drbd.conf
265      $ echo "drbd" >> /etc/modules
266      $ depmod -a
267      $ modprobe drbd
268
269    It is also recommended that you comment out the default resources (if any)
270    in the ``/etc/drbd.conf`` file, so that the init script doesn't try to
271    configure any drbd devices. You can do this by prefixing all
272    *resource* lines in the file with the keyword *skip*, like this:
273
274    .. code-block:: text
275
276      skip {
277        resource r0 {
278          ...
279        }
280      }
281
282      skip {
283        resource "r1" {
284          ...
285        }
286      }
287
288 Installing RBD
289 ++++++++++++++
290
291 Recommended on all nodes: RBD_ is required if you want to create
292 instances with RBD disks residing inside a RADOS cluster (make use of
293 the rbd disk template). RBD-based instances can failover or migrate to
294 any other node in the ganeti cluster, enabling you to exploit of all
295 Ganeti's high availabilily (HA) features.
296
297 .. attention::
298    Be careful though: rbd is still experimental! For now it is
299    recommended only for testing purposes.  No sensitive data should be
300    stored there.
301
302 .. _RBD: http://ceph.newdream.net/
303
304 You will need the ``rbd`` and ``libceph`` kernel modules, the RBD/Ceph
305 userspace utils (ceph-common Debian package) and an appropriate
306 Ceph/RADOS configuration file on every VM-capable node.
307
308 You will also need a working RADOS Cluster accessible by the above
309 nodes.
310
311 RADOS Cluster
312 ~~~~~~~~~~~~~
313
314 You will need a working RADOS Cluster accesible by all VM-capable nodes
315 to use the RBD template. For more information on setting up a RADOS
316 Cluster, refer to the `official docs <http://ceph.newdream.net/>`_.
317
318 If you want to use a pool for storing RBD disk images other than the
319 default (``rbd``), you should first create the pool in the RADOS
320 Cluster, and then set the corresponding rbd disk parameter named
321 ``pool``.
322
323 Kernel Modules
324 ~~~~~~~~~~~~~~
325
326 Unless your distribution already provides it, you might need to compile
327 the ``rbd`` and ``libceph`` modules from source. You will need Linux
328 Kernel 3.2 or above for the kernel modules. Alternatively you will have
329 to build them as external modules (from Linux Kernel source 3.2 or
330 above), if you want to run a less recent kernel, or your kernel doesn't
331 include them.
332
333 Userspace Utils
334 ~~~~~~~~~~~~~~~
335
336 The RBD template has been tested with ``ceph-common`` v0.38 and
337 above. We recommend using the latest version of ``ceph-common``.
338
339 .. admonition:: Debian
340
341    On Debian, you can just install the RBD/Ceph userspace utils with
342    the following command::
343
344       $ apt-get install ceph-common
345
346 KVM userspace access
347 ~~~~~~~~~~~~~~~~~~~~
348
349 If your cluster uses a sufficiently new version of KVM (you will need at
350 least QEMU 0.14 with RBD support compiled in), you can take advantage of
351 KVM's native support for ceph in order to have better performance and
352 avoid potential deadlocks_ in low memory scenarios.
353
354 .. _deadlocks: http://tracker.ceph.com/issues/3076
355
356 To initialize a cluster with support for this feature, use a command
357 like the following. Note, that you possibly need to follow the more
358 general installation instructions before invoking this command (see
359 `Initializing the cluster`_ ).
360
361   $ gnt-cluster init \
362       --enabled-disk-templates=rbd \
363       --ipolicy-disk-templates=rbd \
364       --enabled-hypervisors=kvm \
365       -D rbd:access=userspace
366
367 (You may want to enable more templates than just ``rbd``.)
368
369 You can also change this setting on a live cluster by giving the same
370 switches to ``gnt-cluster modify``, or change those settings at the node
371 group level with ``gnt-group modify``.
372
373 Configuration file
374 ~~~~~~~~~~~~~~~~~~
375
376 You should also provide an appropriate configuration file
377 (``ceph.conf``) in ``/etc/ceph``. For the rbd userspace utils, you'll
378 only need to specify the IP addresses of the RADOS Cluster monitors.
379
380 .. admonition:: ceph.conf
381
382    Sample configuration file:
383
384    .. code-block:: text
385
386     [mon.a]
387            host = example_monitor_host1
388            mon addr = 1.2.3.4:6789
389     [mon.b]
390            host = example_monitor_host2
391            mon addr = 1.2.3.5:6789
392     [mon.c]
393            host = example_monitor_host3
394            mon addr = 1.2.3.6:6789
395
396 For more information, please see the `Ceph Docs
397 <http://ceph.newdream.net/docs/latest/>`_
398
399 Installing Gluster
400 ++++++++++++++++++
401
402 For Gluster integration, Ganeti requires that ``mount.glusterfs`` is
403 installed on each and every node. On Debian Wheezy and newer, you can
404 satisfy this requirement with the ``glusterfs-client`` package; see
405 `this guide
406 <http://gluster.org/community/documentation/index.php/Gluster_3.2:_Installing_the_Gluster_Native_Client>`_
407 for details.
408
409 KVM userspace access
410 ~~~~~~~~~~~~~~~~~~~~
411
412 If your cluster uses a sufficiently new version of KVM (you will need at
413 least QEMU 1.3 with Gluster support compiled in), you can take advantage
414 of KVM's native support for gluster in order to have better performance
415 and avoid potential deadlocks in low memory scenarios.
416
417 Please be aware that QEMU 1.3 was released in December 3, 2012, and as
418 such this feature is not available out of the box in any distribution
419 older than Ubuntu 13.04; this excludes Ubuntu 12.04 LTS and Debian
420 Wheezy.
421
422 Other required software
423 +++++++++++++++++++++++
424
425 Please install all software requirements mentioned in :doc:`install-quick`.
426 If you want to build Ganeti from source, don't forget to follow the steps
427 required for that as well.
428
429 Setting up the environment for Ganeti
430 -------------------------------------
431
432 Configuring the network
433 +++++++++++++++++++++++
434
435 **Mandatory** on all nodes.
436
437 You can run Ganeti either in "bridged mode", "routed mode" or
438 "openvswitch mode". In bridged mode, the default, the instances network
439 interfaces will be attached to a software bridge running in dom0. Xen by
440 default creates such a bridge at startup, but your distribution might
441 have a different way to do things, and you'll definitely need to
442 manually set it up under KVM.
443
444 Beware that the default name Ganeti uses is ``xen-br0`` (which was used
445 in Xen 2.0) while Xen 3.0 uses ``xenbr0`` by default. See the
446 `Initializing the cluster`_ section to learn how to choose a different
447 bridge, or not to use one at all and use "routed mode".
448
449 In order to use "routed mode" under Xen, you'll need to change the
450 relevant parameters in the Xen config file. Under KVM instead, no config
451 change is necessary, but you still need to set up your network
452 interfaces correctly.
453
454 By default, under KVM, the "link" parameter you specify per-nic will
455 represent, if non-empty, a different routing table name or number to use
456 for your instances. This allows isolation between different instance
457 groups, and different routing policies between node traffic and instance
458 traffic.
459
460 You will need to configure your routing table basic routes and rules
461 outside of ganeti. The vif scripts will only add /32 routes to your
462 instances, through their interface, in the table you specified (under
463 KVM, and in the main table under Xen).
464
465 Also for "openvswitch mode" under Xen a custom network script is needed.
466 Under KVM everything should work, but you'll need to configure your
467 switches outside of Ganeti (as for bridges).
468
469 .. admonition:: Bridging issues with certain kernels
470
471     Some kernel versions (e.g. 2.6.32) have an issue where the bridge
472     will automatically change its ``MAC`` address to the lower-numbered
473     slave on port addition and removal. This means that, depending on
474     the ``MAC`` address of the actual NIC on the node and the addresses
475     of the instances, it could be that starting, stopping or migrating
476     instances will lead to timeouts due to the address of the bridge
477     (and thus node itself) changing.
478
479     To prevent this, it's enough to set the bridge manually to a
480     specific ``MAC`` address, which will disable this automatic address
481     change. In Debian, this can be done as follows in the bridge
482     configuration snippet::
483
484       up ip link set addr $(cat /sys/class/net/$IFACE/address) dev $IFACE
485
486     which will "set" the bridge address to the initial one, disallowing
487     changes.
488
489 .. admonition:: Bridging under Debian
490
491    The recommended way to configure the Xen bridge is to edit your
492    ``/etc/network/interfaces`` file and substitute your normal
493    Ethernet stanza with the following snippet::
494
495      auto xen-br0
496      iface xen-br0 inet static
497         address %YOUR_IP_ADDRESS%
498         netmask %YOUR_NETMASK%
499         network %YOUR_NETWORK%
500         broadcast %YOUR_BROADCAST_ADDRESS%
501         gateway %YOUR_GATEWAY%
502         bridge_ports eth0
503         bridge_stp off
504         bridge_fd 0
505         # example for setting manually the bridge address to the eth0 NIC
506         up ip link set addr $(cat /sys/class/net/eth0/address) dev $IFACE
507
508 The following commands need to be executed on the local console::
509
510   $ ifdown eth0
511   $ ifup xen-br0
512
513 To check if the bridge is setup, use the ``ip`` and ``brctl show``
514 commands::
515
516   $ ip a show xen-br0
517   9: xen-br0: <BROADCAST,MULTICAST,UP,10000> mtu 1500 qdisc noqueue
518       link/ether 00:20:fc:1e:d5:5d brd ff:ff:ff:ff:ff:ff
519       inet 10.1.1.200/24 brd 10.1.1.255 scope global xen-br0
520       inet6 fe80::220:fcff:fe1e:d55d/64 scope link
521          valid_lft forever preferred_lft forever
522
523   $ brctl show xen-br0
524   bridge name     bridge id               STP enabled     interfaces
525   xen-br0         8000.0020fc1ed55d       no              eth0
526
527 In order to have a custom and more advanced networking configuration in Xen
528 which can vary among instances, after having successfully installed Ganeti
529 you have to create a symbolic link to the vif-script provided by Ganeti
530 inside /etc/xen/scripts (assuming you installed Ganeti under /usr/lib)::
531
532   $ ln -s /usr/lib/ganeti/vif-ganeti /etc/xen/scripts/vif-ganeti
533
534 This has to be done on all nodes. Afterwards you can set the ``vif_script``
535 hypervisor parameter to point to that script by::
536
537   $ gnt-cluster modify -H xen-pvm:vif_script=/etc/xen/scripts/vif-ganeti
538
539 Having this hypervisor parameter you are able to create your own scripts
540 and create instances with different networking configurations.
541
542 .. _configure-lvm-label:
543
544 Configuring LVM
545 +++++++++++++++
546
547 **Mandatory** on all nodes.
548
549 The volume group is required to be at least 20GiB.
550
551 If you haven't configured your LVM volume group at install time you need
552 to do it before trying to initialize the Ganeti cluster. This is done by
553 formatting the devices/partitions you want to use for it and then adding
554 them to the relevant volume group::
555
556   $ pvcreate /dev/%sda3%
557   $ vgcreate xenvg /dev/%sda3%
558
559 or::
560
561   $ pvcreate /dev/%sdb1%
562   $ pvcreate /dev/%sdc1%
563   $ vgcreate xenvg /dev/%sdb1% /dev/%sdc1%
564
565 If you want to add a device later you can do so with the *vgextend*
566 command::
567
568   $ pvcreate /dev/%sdd1%
569   $ vgextend xenvg /dev/%sdd1%
570
571 Optional: it is recommended to configure LVM not to scan the DRBD
572 devices for physical volumes. This can be accomplished by editing
573 ``/etc/lvm/lvm.conf`` and adding the ``/dev/drbd[0-9]+`` regular
574 expression to the ``filter`` variable, like this:
575
576 .. code-block:: text
577
578   filter = ["r|/dev/cdrom|", "r|/dev/drbd[0-9]+|" ]
579
580 Note that with Ganeti a helper script is provided - ``lvmstrap`` which
581 will erase and configure as LVM any not in-use disk on your system. This
582 is dangerous and it's recommended to read its ``--help`` output if you
583 want to use it.
584
585 Installing Ganeti
586 +++++++++++++++++
587
588 **Mandatory** on all nodes.
589
590 It's now time to install the Ganeti software itself.  Download the
591 source from the project page at `<http://downloads.ganeti.org/releases/>`_,
592 and install it (replace 2.6.0 with the latest version)::
593
594   $ tar xvzf ganeti-%2.6.0%.tar.gz
595   $ cd ganeti-%2.6.0%
596   $ ./configure --localstatedir=/var --sysconfdir=/etc
597   $ make
598   $ make install
599   $ mkdir /srv/ganeti/ /srv/ganeti/os /srv/ganeti/export
600
601 You also need to copy the file ``doc/examples/ganeti.initd`` from the
602 source archive to ``/etc/init.d/ganeti`` and register it with your
603 distribution's startup scripts, for example in Debian::
604
605   $ chmod +x /etc/init.d/ganeti
606   $ update-rc.d ganeti defaults 20 80
607
608 In order to automatically restart failed instances, you need to setup a
609 cron job run the *ganeti-watcher* command. A sample cron file is
610 provided in the source at ``doc/examples/ganeti.cron`` and you can copy
611 that (eventually altering the path) to ``/etc/cron.d/ganeti``. Finally,
612 a sample logrotate snippet is provided in the source at
613 ``doc/examples/ganeti.logrotate`` and you can copy it to
614 ``/etc/logrotate.d/ganeti`` to have Ganeti's logs rotated automatically.
615
616 What gets installed
617 ~~~~~~~~~~~~~~~~~~~
618
619 The above ``make install`` invocation, or installing via your
620 distribution mechanisms, will install on the system:
621
622 - a set of python libraries under the *ganeti* namespace (depending on
623   the python version this can be located in either
624   ``lib/python-$ver/site-packages`` or various other locations)
625 - a set of programs under ``/usr/local/sbin`` or ``/usr/sbin``
626 - if the htools component was enabled, a set of programs under
627   ``/usr/local/bin`` or ``/usr/bin/``
628 - man pages for the above programs
629 - a set of tools under the ``lib/ganeti/tools`` directory
630 - an example iallocator script (see the admin guide for details) under
631   ``lib/ganeti/iallocators``
632 - a cron job that is needed for cluster maintenance
633 - an init script for automatic startup of Ganeti daemons
634 - provided but not installed automatically by ``make install`` is a bash
635   completion script that hopefully will ease working with the many
636   cluster commands
637
638 Installing the Operating System support packages
639 ++++++++++++++++++++++++++++++++++++++++++++++++
640
641 **Mandatory** on all nodes.
642
643 To be able to install instances you need to have an Operating System
644 installation script. An example OS that works under Debian and can
645 install Debian and Ubuntu instace OSes is provided on the project web
646 site.  Download it from the project page and follow the instructions in
647 the ``README`` file.  Here is the installation procedure (replace 0.14
648 with the latest version that is compatible with your ganeti version)::
649
650   $ cd /usr/local/src/
651   $ wget http://ganeti.googlecode.com/files/ganeti-instance-debootstrap-%0.14%.tar.gz
652   $ tar xzf ganeti-instance-debootstrap-%0.14%.tar.gz
653   $ cd ganeti-instance-debootstrap-%0.14%
654   $ ./configure --with-os-dir=/srv/ganeti/os
655   $ make
656   $ make install
657
658 In order to use this OS definition, you need to have internet access
659 from your nodes and have the *debootstrap*, *dump* and *restore*
660 commands installed on all nodes. Also, if the OS is configured to
661 partition the instance's disk in
662 ``/etc/default/ganeti-instance-debootstrap``, you will need *kpartx*
663 installed.
664
665 .. admonition:: Debian
666
667    Use this command on all nodes to install the required packages::
668
669      $ apt-get install debootstrap dump kpartx
670
671    Or alternatively install the OS definition from the Debian package::
672
673      $ apt-get install ganeti-instance-debootstrap
674
675 .. admonition:: KVM
676
677    In order for debootstrap instances to be able to shutdown cleanly
678    they must install have basic ACPI support inside the instance. Which
679    packages are needed depend on the exact flavor of Debian or Ubuntu
680    which you're installing, but the example defaults file has a
681    commented out configuration line that works for Debian Lenny and
682    Squeeze::
683
684      EXTRA_PKGS="acpi-support-base,console-tools,udev"
685
686    ``kbd`` can be used instead of ``console-tools``, and more packages
687    can be added, of course, if needed.
688
689 Please refer to the ``README`` file of ``ganeti-instance-debootstrap`` for
690 further documentation.
691
692 Alternatively, you can create your own OS definitions. See the manpage
693 :manpage:`ganeti-os-interface(7)`.
694
695 Initializing the cluster
696 ++++++++++++++++++++++++
697
698 **Mandatory** once per cluster, on the first node.
699
700 The last step is to initialize the cluster. After you have repeated the
701 above process on all of your nodes and choose one as the master. Make sure
702 there is a SSH key pair on the master node (optionally generating one using
703 ``ssh-keygen``). Finally execute::
704
705   $ gnt-cluster init %CLUSTERNAME%
706
707 The *CLUSTERNAME* is a hostname, which must be resolvable (e.g. it must
708 exist in DNS or in ``/etc/hosts``) by all the nodes in the cluster. You
709 must choose a name different from any of the nodes names for a
710 multi-node cluster. In general the best choice is to have a unique name
711 for a cluster, even if it consists of only one machine, as you will be
712 able to expand it later without any problems. Please note that the
713 hostname used for this must resolve to an IP address reserved
714 **exclusively** for this purpose, and cannot be the name of the first
715 (master) node.
716
717 If you want to use a bridge which is not ``xen-br0``, or no bridge at
718 all, change it with the ``--nic-parameters`` option. For example to
719 bridge on br0 you can add::
720
721   --nic-parameters link=br0
722
723 Or to not bridge at all, and use a separate routing table::
724
725   --nic-parameters mode=routed,link=100
726
727 If you don't have a ``xen-br0`` interface you also have to specify a
728 different network interface which will get the cluster IP, on the master
729 node, by using the ``--master-netdev <device>`` option.
730
731 You can use a different name than ``xenvg`` for the volume group (but
732 note that the name must be identical on all nodes). In this case you
733 need to specify it by passing the *--vg-name <VGNAME>* option to
734 ``gnt-cluster init``.
735
736 To set up the cluster as an Xen HVM cluster, use the
737 ``--enabled-hypervisors=xen-hvm`` option to enable the HVM hypervisor
738 (you can also add ``,xen-pvm`` to enable the PVM one too). You will also
739 need to create the VNC cluster password file
740 ``/etc/ganeti/vnc-cluster-password`` which contains one line with the
741 default VNC password for the cluster.
742
743 To setup the cluster for KVM-only usage (KVM and Xen cannot be mixed),
744 pass ``--enabled-hypervisors=kvm`` to the init command.
745
746 You can also invoke the command with the ``--help`` option in order to
747 see all the possibilities.
748
749 Hypervisor/Network/Cluster parameters
750 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
751
752 Please note that the default hypervisor/network/cluster parameters may
753 not be the correct one for your environment. Carefully check them, and
754 change them either at cluster init time, or later with ``gnt-cluster
755 modify``.
756
757 Your instance types, networking environment, hypervisor type and version
758 may all affect what kind of parameters should be used on your cluster.
759
760 .. admonition:: KVM
761
762   Instances are by default configured to use a host kernel, and to be
763   reached via serial console, which works nice for Linux paravirtualized
764   instances. If you want fully virtualized instances you may want to
765   handle their kernel inside the instance, and to use VNC.
766
767   Some versions of KVM have a bug that will make an instance hang when
768   configured to use the serial console (which is the default) unless a
769   connection is made to it within about 2 seconds of the instance's
770   startup. For such case it's recommended to disable the
771   ``serial_console`` option.
772
773
774 Joining the nodes to the cluster
775 ++++++++++++++++++++++++++++++++
776
777 **Mandatory** for all the other nodes.
778
779 After you have initialized your cluster you need to join the other nodes
780 to it. You can do so by executing the following command on the master
781 node::
782
783   $ gnt-node add %NODENAME%
784
785 Separate replication network
786 ++++++++++++++++++++++++++++
787
788 **Optional**
789
790 Ganeti uses DRBD to mirror the disk of the virtual instances between
791 nodes. To use a dedicated network interface for this (in order to
792 improve performance or to enhance security) you need to configure an
793 additional interface for each node.  Use the *-s* option with
794 ``gnt-cluster init`` and ``gnt-node add`` to specify the IP address of
795 this secondary interface to use for each node. Note that if you
796 specified this option at cluster setup time, you must afterwards use it
797 for every node add operation.
798
799 Testing the setup
800 +++++++++++++++++
801
802 Execute the ``gnt-node list`` command to see all nodes in the cluster::
803
804   $ gnt-node list
805   Node              DTotal  DFree MTotal MNode MFree Pinst Sinst
806   node1.example.com 197404 197404   2047  1896   125     0     0
807
808 The above shows a couple of things:
809
810 - The various Ganeti daemons can talk to each other
811 - Ganeti can examine the storage of the node (DTotal/DFree)
812 - Ganeti can talk to the selected hypervisor (MTotal/MNode/MFree)
813
814 Cluster burnin
815 ~~~~~~~~~~~~~~
816
817 With Ganeti a tool called :command:`burnin` is provided that can test
818 most of the Ganeti functionality. The tool is installed under the
819 ``lib/ganeti/tools`` directory (either under ``/usr`` or ``/usr/local``
820 based on the installation method). See more details under
821 :ref:`burnin-label`.
822
823 Further steps
824 -------------
825
826 You can now proceed either to the :doc:`admin`, or read the manpages of
827 the various commands (:manpage:`ganeti(7)`, :manpage:`gnt-cluster(8)`,
828 :manpage:`gnt-node(8)`, :manpage:`gnt-instance(8)`,
829 :manpage:`gnt-job(8)`).
830
831 .. rubric:: Footnotes
832
833 .. [#defkernel] The kernel and initrd paths can be changed at either
834    cluster level (which changes the default for all instances) or at
835    instance level.
836
837 .. vim: set textwidth=72 :
838 .. Local Variables:
839 .. mode: rst
840 .. fill-column: 72
841 .. End: