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