code.grnet.gr Git - ganeti-local/blob - doc/install.sgml

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
   2 ]>
   3   <article class="specification">
   4   <articleinfo>
   5     <title>Ganeti installation tutorial</title>
   6   </articleinfo>
   7   <para>Documents Ganeti version 1.2</para>
   8
   9   <sect1>
  10     <title>Introduction</title>
  11
  12     <para>
  13       Ganeti is a cluster virtualization management system based on
  14       Xen. This document explains how to bootstrap a Ganeti node (Xen
  15       <literal>dom0</literal>), create a running cluster and install
  16       virtual instance (Xen <literal>domU</literal>).  You need to
  17       repeat most of the steps in this document for every node you
  18       want to install, but of course we recommend creating some
  19       semi-automatic procedure if you plan to deploy Ganeti on a
  20       medium/large scale.
  21     </para>
  22
  23     <para>
  24       A basic Ganeti terminology glossary is provided in the
  25       introductory section of the <emphasis>Ganeti administrator's
  26       guide</emphasis>. Please refer to that document if you are
  27       uncertain about the terms we are using.
  28     </para>
  29
  30     <para>
  31       Ganeti has been developed for Linux and is
  32       distribution-agnostic.  This documentation will use Debian Etch
  33       as an example system but the examples can easily be translated
  34       to any other distribution.  You are expected to be familiar with
  35       your distribution, its package management system, and Xen before
  36       trying to use Ganeti.
  37     </para>
  38
  39     <para>This document is divided into two main sections:
  40
  41       <itemizedlist>
  42         <listitem>
  43           <simpara>Installation of the base system and base
  44           components</simpara>
  45         </listitem>
  46         <listitem>
  47           <simpara>Configuration of the environment for
  48           Ganeti</simpara>
  49         </listitem>
  50       </itemizedlist>
  51
  52     Each of these is divided into sub-sections. While a full Ganeti
  53     system will need all of the steps specified, some are not strictly
  54     required for every environment. Which ones they are, and why, is
  55     specified in the corresponding sections.
  56     </para>
  57
  58   </sect1>
  59
  60   <sect1>
  61     <title>Installing the base system and base components</title>
  62
  63     <sect2>
  64       <title>Hardware requirements</title>
  65
  66       <para>
  67          Any system supported by your Linux distribution is fine.
  68          64-bit systems are better as they can support more memory.
  69       </para>
  70
  71       <para>
  72          Any disk drive recognized by Linux
  73          (<literal>IDE</literal>/<literal>SCSI</literal>/<literal>SATA</literal>/etc.)
  74          is supported in Ganeti. Note that no shared storage
  75          (e.g. <literal>SAN</literal>) is needed to get high-availability features. It is
  76          highly recommended to use more than one disk drive to improve
  77          speed. But Ganeti also works with one disk per machine.
  78       </para>
  79
  80     <sect2>
  81       <title>Installing the base system</title>
  82
  83       <para>
  84         <emphasis role="strong">Mandatory</emphasis> on all nodes.
  85       </para>
  86
  87       <para>
  88         It is advised to start with a clean, minimal install of the
  89         operating system. The only requirement you need to be aware of
  90         at this stage is to partition leaving enough space for a big
  91         (<emphasis role="strong">minimum
  92         <constant>20GiB</constant></emphasis>) LVM volume group which
  93         will then host your instance filesystems. The volume group
  94         name Ganeti 1.2 uses (by default) is
  95         <emphasis>xenvg</emphasis>.
  96       </para>
  97
  98       <para>
  99         While you can use an existing system, please note that the
 100         Ganeti installation is intrusive in terms of changes to the
 101         system configuration, and it's best to use a newly-installed
 102         system without important data on it.
 103       </para>
 104
 105       <para>
 106         Also, for best results, it's advised that the nodes have as
 107         much as possible the same hardware and software
 108         configuration. This will make administration much easier.
 109       </para>
 110
 111       <sect3>
 112         <title>Hostname issues</title>
 113         <para>
 114           Note that Ganeti requires the hostnames of the systems
 115           (i.e. what the <computeroutput>hostname</computeroutput>
 116           command outputs to be a fully-qualified name, not a short
 117           name. In other words, you should use
 118           <literal>node1.example.com</literal> as a hostname and not
 119           just <literal>node1</literal>.
 120         </para>
 121
 122         <formalpara>
 123           <title>Debian</title>
 124           <para>
 125             Note that Debian Etch configures the hostname differently
 126             than you need it for Ganeti. For example, this is what
 127             Etch puts in <filename>/etc/hosts</filename> in certain
 128             situations:
 129 <screen>
 130 127.0.0.1       localhost
 131 127.0.1.1       node1.example.com node1
 132 </screen>
 133
 134           but for Ganeti you need to have:
 135 <screen>
 136 127.0.0.1       localhost
 137 192.168.1.1     node1.example.com node1
 138 </screen>
 139             replacing <literal>192.168.1.1</literal> with your node's
 140             address. Also, the file <filename>/etc/hostname</filename>
 141             which configures the hostname of the system should contain
 142             <literal>node1.example.com</literal> and not just
 143             <literal>node1</literal> (you need to run the command
 144             <computeroutput>/etc/init.d/hostname.sh
 145             start</computeroutput> after changing the file).
 146           </para>
 147         </formalpara>
 148       </sect3>
 149
 150     </sect2>
 151
 152     <sect2>
 153       <title>Installing Xen</title>
 154
 155       <para>
 156         <emphasis role="strong">Mandatory</emphasis> on all nodes.
 157       </para>
 158
 159       <para>
 160         While Ganeti is developed with the ability to modularly run on
 161         different virtualization environments in mind the only one
 162         currently useable on a live system is <ulink
 163         url="http://xen.xensource.com/">Xen</ulink>. Supported
 164         versions are: <simplelist type="inline">
 165         <member><literal>3.0.3</literal></member>
 166         <member><literal>3.0.4</literal></member>
 167         <member><literal>3.1</literal></member> </simplelist>.
 168       </para>
 169
 170       <para>
 171         Please follow your distribution's recommended way to install
 172         and set up Xen, or install Xen from the upstream source, if
 173         you wish, following their manual.
 174       </para>
 175
 176       <para>
 177         After installing Xen you need to reboot into your Xen-ified
 178         dom0 system. On some distributions this might involve
 179         configuring GRUB appropriately, whereas others will configure
 180         it automatically when you install Xen from a package.
 181       </para>
 182
 183       <formalpara><title>Debian</title>
 184       <para>
 185         Under Debian Etch or Sarge+backports you can install the
 186         relevant <literal>xen-linux-system</literal> package, which
 187         will pull in both the hypervisor and the relevant
 188         kernel. Also, if you are installing a 32-bit Etch, you should
 189         install the <computeroutput>libc6-xen</computeroutput> package
 190         (run <computeroutput>apt-get install
 191         libc6-xen</computeroutput>).
 192       </para>
 193       </formalpara>
 194
 195       <sect3>
 196         <title>Xen settings</title>
 197
 198         <para>
 199           It's recommended that dom0 is restricted to a low amount of
 200           memory (<constant>512MiB</constant> is reasonable) and that
 201           memory ballooning is disabled in the file
 202           <filename>/etc/xen/xend-config.sxp</filename> by setting the
 203           value <literal>dom0-min-mem</literal> to
 204           <constant>0</constant>, like this:
 205           <computeroutput>(dom0-min-mem 0)</computeroutput>
 206         </para>
 207
 208         <para>
 209           For optimum performance when running both CPU and I/O
 210           intensive instances, it's also recommended that the dom0 is
 211           restricted to one CPU only, for example by booting with the
 212           kernel parameter <literal>nosmp</literal>.
 213         </para>
 214
 215         <formalpara>
 216           <title>Debian</title>
 217           <para>
 218             Besides the ballooning change which you need to set in
 219             <filename>/etc/xen/xend-config.sxp</filename>, you need to
 220             set the memory and nosmp parameters in the file
 221             <filename>/boot/grub/menu.lst</filename>. You need to
 222             modify the variable <literal>xenhopt</literal> to add
 223             <userinput>dom0_mem=512M</userinput> like this:
 224 <screen>
 225 ## Xen hypervisor options to use with the default Xen boot option
 226 # xenhopt=dom0_mem=512M
 227 </screen>
 228             and the <literal>xenkopt</literal> needs to include the
 229             <userinput>nosmp</userinput> option like this:
 230 <screen>
 231 ## Xen Linux kernel options to use with the default Xen boot option
 232 # xenkopt=nosmp
 233 </screen>
 234
 235           Any existing parameters can be left in place: it's ok to
 236           have <computeroutput>xenkopt=console=tty0
 237           nosmp</computeroutput>, for example. After modifying the
 238           files, you need to run:
 239 <screen>
 240 /sbin/update-grub
 241 </screen>
 242           </para>
 243         </formalpara>
 244
 245       </sect3>
 246
 247       <sect3>
 248         <title>Selecting the instance kernel</title>
 249
 250         <para>
 251           After you have installed Xen, you need to tell Ganeti
 252           exactly what kernel to use for the instances it will
 253           create. This is done by creating a
 254           <emphasis>symlink</emphasis> from your actual kernel to
 255           <filename>/boot/vmlinuz-2.6-xenU</filename>, and one from
 256           your initrd to
 257           <filename>/boot/initrd-2.6-xenU</filename>. Note that if you
 258           don't use an initrd for the <literal>domU</literal> kernel,
 259           you don't need to create the initrd symlink.
 260         </para>
 261
 262         <formalpara>
 263           <title>Debian</title>
 264           <para>
 265             After installation of the
 266             <literal>xen-linux-system</literal> package, you need to
 267             run (replace the exact version number with the one you
 268             have):
 269             <screen>
 270 cd /boot
 271 ln -s vmlinuz-2.6.18-5-xen-686 vmlinuz-2.6-xenU
 272 ln -s initrd.img-2.6.18-5-xen-686 initrd-2.6-xenU
 273             </screen>
 274           </para>
 275         </formalpara>
 276       </sect3>
 277
 278     </sect2>
 279
 280     <sect2>
 281       <title>Installing DRBD</title>
 282
 283       <para>
 284         Recommended on all nodes: <ulink
 285         url="http://www.drbd.org/">DRBD</ulink> is required if you
 286         want to use the high availability (HA) features of Ganeti, but
 287         optional if you don't require HA or only run Ganeti on
 288         single-node clusters. You can upgrade a non-HA cluster to an
 289         HA one later, but you might need to export and re-import all
 290         your instances to take advantage of the new features.
 291       </para>
 292
 293       <para>
 294         Supported DRBD version: the <literal>0.7</literal>
 295         series. It's recommended to have at least version
 296         <literal>0.7.24</literal> if you use <command>udev</command>
 297         since older versions have a bug related to device discovery
 298         which can be triggered in cases of hard drive failure.
 299       </para>
 300
 301       <para>
 302         Now the bad news: unless your distribution already provides it
 303         installing DRBD might involve recompiling your kernel or
 304         anyway fiddling with it. Hopefully at least the Xen-ified
 305         kernel source to start from will be provided.
 306       </para>
 307
 308       <para>
 309         The good news is that you don't need to configure DRBD at all.
 310         Ganeti will do it for you for every instance you set up.  If
 311         you have the DRBD utils installed and the module in your
 312         kernel you're fine. Please check that your system is
 313         configured to load the module at every boot, and that it
 314         passes the following option to the module:
 315         <computeroutput>minor_count=64</computeroutput> (this will
 316         allow you to use up to 32 instances per node).
 317       </para>
 318
 319       <formalpara><title>Debian</title>
 320         <para>
 321          You can just install (build) the DRBD 0.7 module with the
 322          following commands (make sure you are running the Xen
 323          kernel):
 324         </para>
 325       </formalpara>
 326
 327       <screen>
 328 apt-get install drbd0.7-module-source drbd0.7-utils
 329 m-a update
 330 m-a a-i drbd0.7
 331 echo drbd minor_count=64 >> /etc/modules
 332 modprobe drbd minor_count=64
 333       </screen>
 334
 335       <para>
 336         It is also recommended that you comment out the default
 337         resources in the <filename>/etc/dbrd.conf</filename> file, so
 338         that the init script doesn't try to configure any drbd
 339         devices. You can do this by prefixing all
 340         <literal>resource</literal> lines in the file with the keyword
 341         <literal>skip</literal>, like this:
 342       </para>
 343
 344       <screen>
 345 skip resource r0 {
 346 ...
 347 }
 348
 349 skip resource "r1" {
 350 ...
 351 }
 352       </screen>
 353
 354     </sect2>
 355
 356     <sect2>
 357       <title>Other required software</title>
 358
 359       <para>Besides Xen and DRBD, you will need to install the
 360       following (on all nodes):</para>
 361
 362       <itemizedlist>
 363         <listitem>
 364           <simpara><ulink url="http://sourceware.org/lvm2/">LVM
 365           version 2</ulink></simpara>
 366         </listitem>
 367         <listitem>
 368           <simpara><ulink
 369           url="http://www.openssl.org/">OpenSSL</ulink></simpara>
 370         </listitem>
 371         <listitem>
 372           <simpara><ulink
 373           url="http://www.openssh.com/portable.html">OpenSSH</ulink></simpara>
 374         </listitem>
 375         <listitem>
 376           <simpara><ulink url="http://bridge.sourceforge.net/">Bridge
 377           utilities</ulink></simpara>
 378         </listitem>
 379         <listitem>
 380           <simpara><ulink
 381           url="http://developer.osdl.org/dev/iproute2">iproute2</ulink></simpara>
 382         </listitem>
 383         <listitem>
 384           <simpara><ulink
 385           url="ftp://ftp.inr.ac.ru/ip-routing/iputils-current.tar.gz">arping</ulink>
 386           (part of iputils package)</simpara>
 387         </listitem>
 388         <listitem>
 389           <simpara><ulink
 390           url="http://www.kernel.org/pub/linux/utils/raid/mdadm/">mdadm</ulink>
 391           (Linux Software Raid tools)</simpara>
 392         </listitem>
 393         <listitem>
 394           <simpara><ulink url="http://www.python.org">Python 2.4</ulink></simpara>
 395         </listitem>
 396         <listitem>
 397           <simpara><ulink url="http://twistedmatrix.com/">Python
 398           Twisted library</ulink> - the core library is
 399           enough</simpara>
 400         </listitem>
 401         <listitem>
 402           <simpara><ulink
 403           url="http://pyopenssl.sourceforge.net/">Python OpenSSL
 404           bindings</ulink></simpara>
 405         </listitem>
 406         <listitem>
 407           <simpara><ulink
 408           url="http://www.undefined.org/python/#simplejson">simplejson Python
 409           module</ulink></simpara>
 410         </listitem>
 411       </itemizedlist>
 412
 413       <para>
 414         These programs are supplied as part of most Linux
 415         distributions, so usually they can be installed via apt or
 416         similar methods. Also many of them will already be installed
 417         on a standard machine.
 418       </para>
 419
 420
 421       <formalpara><title>Debian</title>
 422
 423       <para>You can use this command line to install all of them:</para>
 424
 425       </formalpara>
 426       <screen>
 427 # apt-get install lvm2 ssh bridge-utils iproute iputils-arping \
 428   python2.4 python-twisted-core python-pyopenssl openssl \
 429   mdadm
 430       </screen>
 431
 432     </sect2>
 433
 434   </sect1>
 435
 436
 437   <sect1>
 438     <title>Setting up the environment for Ganeti</title>
 439
 440     <sect2>
 441       <title>Configuring the network</title>
 442
 443       <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>
 444
 445       <para>
 446         Ganeti relies on Xen running in "bridge mode", which means the
 447         instances network interfaces will be attached to a software bridge
 448         running in dom0. Xen by default creates such a bridge at startup, but
 449         your distribution might have a different way to do things.
 450       </para>
 451
 452       <para>
 453         Beware that the default name Ganeti uses is
 454         <hardware>xen-br0</hardware> (which was used in Xen 2.0)
 455         while Xen 3.0 uses <hardware>xenbr0</hardware> by
 456         default. The default bridge your Ganeti cluster will use for new
 457         instances can be specified at cluster initialization time.
 458       </para>
 459
 460       <formalpara><title>Debian</title>
 461         <para>
 462           The recommended Debian way to configure the Xen bridge is to
 463           edit your <filename>/etc/network/interfaces</filename> file
 464           and substitute your normal Ethernet stanza with the
 465           following snippet:
 466
 467         <screen>
 468 auto xen-br0
 469 iface xen-br0 inet static
 470         address <replaceable>YOUR_IP_ADDRESS</replaceable>
 471         netmask <replaceable>YOUR_NETMASK</replaceable>
 472         network <replaceable>YOUR_NETWORK</replaceable>
 473         broadcast <replaceable>YOUR_BROADCAST_ADDRESS</replaceable>
 474         gateway <replaceable>YOUR_GATEWAY</replaceable>
 475         bridge_ports eth0
 476         bridge_stp off
 477         bridge_fd 0
 478         </screen>
 479         </para>
 480       </formalpara>
 481
 482      <para>
 483 The following commands need to be executed on the local console
 484      </para>
 485       <screen>
 486 ifdown eth0
 487 ifup xen-br0
 488       </screen>
 489
 490       <para>
 491         To check if the bridge is setup, use <command>ip</command>
 492         and <command>brctl show</command>:
 493       <para>
 494
 495       <screen>
 496 # ip a show xen-br0
 497 9: xen-br0: &lt;BROADCAST,MULTICAST,UP,10000&gt; mtu 1500 qdisc noqueue
 498     link/ether 00:20:fc:1e:d5:5d brd ff:ff:ff:ff:ff:ff
 499     inet 10.1.1.200/24 brd 10.1.1.255 scope global xen-br0
 500     inet6 fe80::220:fcff:fe1e:d55d/64 scope link
 501        valid_lft forever preferred_lft forever
 502
 503 # brctl show xen-br0
 504 bridge name     bridge id               STP enabled     interfaces
 505 xen-br0         8000.0020fc1ed55d       no              eth0
 506       </screen>
 507
 508
 509     </sect2>
 510
 511     <sect2>
 512       <title>Configuring LVM</title>
 513
 514
 515       <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>
 516
 517       <note>
 518         <simpara>The volume group is required to be at least
 519         <constant>20GiB</constant>.</simpara>
 520       </note>
 521       <para>
 522         If you haven't configured your LVM volume group at install
 523         time you need to do it before trying to initialize the Ganeti
 524         cluster. This is done by formatting the devices/partitions you
 525         want to use for it and then adding them to the relevant volume
 526         group:
 527
 528        <screen>
 529 pvcreate /dev/sda3
 530 vgcreate xenvg /dev/sda3
 531        </screen>
 532 or
 533        <screen>
 534 pvcreate /dev/sdb1
 535 pvcreate /dev/sdc1
 536 vgcreate xenvg /dev/sdb1 /dev/sdc1
 537        </screen>
 538       </para>
 539
 540       <para>
 541         If you want to add a device later you can do so with the
 542         <citerefentry><refentrytitle>vgextend</refentrytitle>
 543         <manvolnum>8</manvolnum></citerefentry> command:
 544       </para>
 545
 546       <screen>
 547 pvcreate /dev/sdd1
 548 vgextend xenvg /dev/sdd1
 549       </screen>
 550
 551       <formalpara>
 552         <title>Optional</title>
 553         <para>
 554           It is recommended to configure LVM not to scan the DRBD
 555           devices for physical volumes. This can be accomplished by
 556           editing <filename>/etc/lvm/lvm.conf</filename> and adding
 557           the <literal>/dev/drbd[0-9]+</literal> regular expression to
 558           the <literal>filter</literal> variable, like this:
 559 <screen>
 560     filter = [ "r|/dev/cdrom|", "r|/dev/drbd[0-9]+|" ]
 561 </screen>
 562         </para>
 563       </formalpara>
 564
 565     </sect2>
 566
 567     <sect2>
 568       <title>Installing Ganeti</title>
 569
 570       <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>
 571
 572       <para>
 573         It's now time to install the Ganeti software itself.  Download
 574         the source from <ulink
 575         url="http://code.google.com/p/ganeti/"></ulink>.
 576       </para>
 577
 578         <screen>
 579 tar xvzf ganeti-1.2b1.tar.gz
 580 cd ganeti-1.2b1
 581 ./configure --localstatedir=/var --sysconfdir=/etc
 582 make
 583 make install
 584 mkdir /srv/ganeti/ /srv/ganeti/os /srv/ganeti/export
 585         </screen>
 586
 587       <para>
 588         You also need to copy the file
 589         <filename>doc/examples/ganeti.initd</filename>
 590         from the source archive to
 591         <filename>/etc/init.d/ganeti</filename> and register it with
 592         your distribution's startup scripts, for example in Debian:
 593       </para>
 594       <screen>update-rc.d ganeti defaults 20 80</screen>
 595
 596       <para>
 597         In order to automatically restart failed instances, you need
 598         to setup a cron job run the
 599         <computeroutput>ganeti-watcher</computeroutput> program. A
 600         sample cron file is provided in the source at
 601         <filename>doc/examples/ganeti.cron</filename> and you can
 602         copy that (eventually altering the path) to
 603         <filename>/etc/cron.d/ganeti</filename>
 604       </para>
 605
 606     </sect2>
 607
 608     <sect2>
 609       <title>Installing the Operating System support packages</title>
 610
 611       <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>
 612
 613       <para>
 614         To be able to install instances you need to have an Operating
 615         System installation script. An example for Debian Etch is
 616         provided on the project web site.  Download it from <ulink
 617         url="http://code.google.com/p/ganeti/"></ulink> and follow the
 618         instructions in the <filename>README</filename> file.  Here is
 619         the installation procedure:
 620       </para>
 621
 622       <screen>
 623 cd /srv/ganeti/os
 624 tar xvf instance-debian-etch-0.1.tar
 625 mv instance-debian-etch-0.1 debian-etch
 626       </screen>
 627
 628       <para>
 629         In order to use this OS definition, you need to have internet
 630         access from your nodes and have the <citerefentry>
 631         <refentrytitle>debootstrap</refentrytitle>
 632         <manvolnum>8</manvolnum></citerefentry>, <citerefentry>
 633         <refentrytitle>dump</refentrytitle><manvolnum>8</manvolnum>
 634         </citerefentry> and <citerefentry>
 635         <refentrytitle>restore</refentrytitle>
 636         <manvolnum>8</manvolnum> </citerefentry> commands installed on
 637         all nodes.
 638       </para>
 639       <formalpara>
 640         <title>Debian</title>
 641         <para>
 642           Use this command on all nodes to install the required
 643           packages:
 644
 645           <screen>apt-get install debootstrap dump</screen>
 646         </para>
 647       </formalpara>
 648
 649       <para>
 650         Alternatively, you can create your own OS definitions. See the
 651         manpage
 652         <citerefentry>
 653         <refentrytitle>ganeti-os-interface</refentrytitle>
 654         <manvolnum>8</manvolnum>
 655         </citerefentry>.
 656       </para>
 657
 658     </sect2>
 659
 660     <sect2>
 661       <title>Initializing the cluster</title>
 662
 663       <para><emphasis role="strong">Mandatory:</emphasis> only on one
 664       node per cluster.</para>
 665
 666
 667       <para>The last step is to initialize the cluster. After you've repeated
 668         the above process on all of your nodes, choose one as the master, and execute:
 669       </para>
 670
 671       <screen>
 672 gnt-cluster init <replaceable>CLUSTERNAME</replaceable>
 673       </screen>
 674
 675       <para>
 676         The <replaceable>CLUSTERNAME</replaceable> is a hostname,
 677         which must be resolvable (e.g. it must exist in DNS or in
 678         <filename>/etc/hosts</filename>) by all the nodes in the
 679         cluster. You must choose a name different from any of the
 680         nodes names for a multi-node cluster. In general the best
 681         choice is to have a unique name for a cluster, even if it
 682         consists of only one machine, as you will be able to expand it
 683         later without any problems.
 684       </para>
 685
 686       <para>
 687         If the bridge name you are using is not
 688         <literal>xen-br0</literal>, use the <option>-b
 689         <replaceable>BRIDGENAME</replaceable></option> option to
 690         specify the bridge name. In this case, you should also use the
 691         <option>--master-netdev
 692         <replaceable>BRIDGENAME</replaceable></option> option with the
 693         same <replaceable>BRIDGENAME</replaceable> argument.
 694       </para>
 695
 696       <para>
 697         You can use a different name than <literal>xenvg</literal> for
 698         the volume group (but note that the name must be identical on
 699         all nodes). In this case you need to specify it by passing the
 700         <option>-g <replaceable>VGNAME</replaceable></option> option
 701         to <computeroutput>gnt-cluster init</computeroutput>.
 702       </para>
 703
 704       <para>
 705         You can also invoke the command with the
 706         <option>--help</option> option in order to see all the
 707         possibilities.
 708       </para>
 709
 710     </sect2>
 711
 712     <sect2>
 713       <title>Joining the nodes to the cluster</title>
 714
 715       <para>
 716         <emphasis role="strong">Mandatory:</emphasis> for all the
 717         other nodes.
 718       </para>
 719
 720       <para>
 721         After you have initialized your cluster you need to join the
 722         other nodes to it. You can do so by executing the following
 723         command on the master node:
 724       </para>
 725         <screen>
 726 gnt-node add <replaceable>NODENAME</replaceable>
 727         </screen>
 728     </sect2>
 729
 730     <sect2>
 731       <title>Separate replication network</title>
 732
 733       <para><emphasis role="strong">Optional</emphasis></para>
 734       <para>
 735         Ganeti uses DRBD to mirror the disk of the virtual instances
 736         between nodes. To use a dedicated network interface for this
 737         (in order to improve performance or to enhance security) you
 738         need to configure an additional interface for each node.  Use
 739         the <option>-s</option> option with
 740         <computeroutput>gnt-cluster init</computeroutput> and
 741         <computeroutput>gnt-node add</computeroutput> to specify the
 742         IP address of this secondary interface to use for each
 743         node. Note that if you specified this option at cluster setup
 744         time, you must afterwards use it for every node add operation.
 745       </para>
 746     </sect2>
 747
 748     <sect2>
 749       <title>Testing the setup</title>
 750
 751       <para>
 752
 753         Execute the <computeroutput>gnt-node list</computeroutput>
 754         command to see all nodes in the cluster:
 755       <screen>
 756 # gnt-node list
 757 Node              DTotal  DFree MTotal MNode MFree Pinst Sinst
 758 node1.example.com 197404 197404   2047  1896   125     0     0
 759       </screen>
 760     </para>
 761   </sect2>
 762
 763   <sect1>
 764     <title>Setting up and managing virtual instances</title>
 765     <sect2>
 766       <title>Setting up virtual instances</title>
 767       <para>
 768         This step shows how to setup a virtual instance with either
 769         non-mirrored disks (<computeroutput>plain</computeroutput>) or
 770         with network mirrored disks
 771         (<computeroutput>remote_raid1</computeroutput>).  All commands
 772         need to be executed on the Ganeti master node (the one on
 773         which <computeroutput>gnt-cluster init</computeroutput> was
 774         run).  Verify that the OS scripts are present on all cluster
 775         nodes with <computeroutput>gnt-os list</computeroutput>.
 776       </para>
 777       <para>
 778         To create a virtual instance, you need a hostname which is
 779         resolvable (DNS or <filename>/etc/hosts</filename> on all
 780         nodes). The following command will create a non-mirrored
 781         instance for you:
 782       </para>
 783       <screen>
 784 gnt-instance add --node=node1 -o debian-etch -t plain inst1.example.com
 785 * creating instance disks...
 786 adding instance inst1.example.com to cluster config
 787 Waiting for instance inst1.example.com to sync disks.
 788 Instance inst1.example.com's disks are in sync.
 789 creating os for instance inst1.example.com on node node1.example.com
 790 * running the instance OS create scripts...
 791       </screen>
 792
 793       <para>
 794         The above instance will have no network interface enabled.
 795         You can access it over the virtual console with
 796         <computeroutput>gnt-instance console
 797         <literal>inst1</literal></computeroutput>. There is no
 798         password for root.  As this is a Debian instance, you can
 799         modify the <filename>/etc/network/interfaces</filename> file
 800         to setup the network interface (<literal>eth0</literal> is the
 801         name of the interface provided to the instance).
 802       </para>
 803
 804       <para>
 805         To create a network mirrored instance, change the argument to
 806         the <option>-t</option> option from <literal>plain</literal>
 807         to <literal>remote_raid1</literal> and specify the node on
 808         which the mirror should reside with the
 809         <option>--secondary-node</option> option, like this:
 810       </para>
 811
 812       <screen>
 813 # gnt-instance add -t remote_raid1 --secondary-node node1 \
 814   -n node2 -o debian-etch instance2
 815 * creating instance disks...
 816 adding instance instance2 to cluster config
 817 Waiting for instance instance1 to sync disks.
 818 - device sdb:  3.50% done, 304 estimated seconds remaining
 819 - device sdb: 21.70% done, 270 estimated seconds remaining
 820 - device sdb: 39.80% done, 247 estimated seconds remaining
 821 - device sdb: 58.10% done, 121 estimated seconds remaining
 822 - device sdb: 76.30% done, 72 estimated seconds remaining
 823 - device sdb: 94.80% done, 18 estimated seconds remaining
 824 Instance instance2's disks are in sync.
 825 creating os for instance instance2 on node node2.example.com
 826 * running the instance OS create scripts...
 827 * starting instance...
 828       </screen>
 829
 830     </sect2>
 831
 832     <sect2>
 833       <title>Managing virtual instances</title>
 834       <para>
 835         All commands need to be executed on the Ganeti master node
 836       </para>
 837
 838       <para>
 839         To access the console of an instance, use
 840         <computeroutput>gnt-instance console
 841         <replaceable>INSTANCENAME</replaceable></computeroutput>.
 842       </para>
 843
 844       <para>
 845         To shutdown an instance, use <computeroutput>gnt-instance
 846         shutdown
 847         <replaceable>INSTANCENAME</replaceable></computeroutput>. To
 848         startup an instance, use <computeroutput>gnt-instance startup
 849         <replaceable>INSTANCENAME</replaceable></computeroutput>.
 850       </para>
 851
 852       <para>
 853         To failover an instance to its secondary node (only possible
 854         in <literal>remote_raid1</literal> setup), use
 855         <computeroutput>gnt-instance failover
 856         <replaceable>INSTANCENAME</replaceable></computeroutput>.
 857       </para>
 858
 859       <para>
 860         For more instance and cluster administration details, see the
 861         <emphasis>Ganeti administrator's guide</emphasis>.
 862       </para>
 863
 864     </sect2>
 865
 866   </sect1>
 867
 868   </article>