Statistics
| Branch: | Tag: | Revision:

root / docs / install.sgml @ 958c8f40

History | View | Annotate | Download (28 kB)

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