Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.sgml @ 6605411d

History | View | Annotate | Download (47.7 kB)

1
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2

    
3
  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
4
  <!-- Please adjust the date whenever revising the manpage. -->
5
  <!ENTITY dhdate      "<date>May 29, 2008</date>">
6
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
7
       allowed: see man(7), man(1). -->
8
  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
9
  <!ENTITY dhucpackage "<refentrytitle>gnt-instance</refentrytitle>">
10
  <!ENTITY dhpackage   "gnt-instance">
11

    
12
  <!ENTITY debian      "<productname>Debian</productname>">
13
  <!ENTITY gnu         "<acronym>GNU</acronym>">
14
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
15
  <!ENTITY footer SYSTEM "footer.sgml">
16
]>
17

    
18
<refentry>
19
  <refentryinfo>
20
    <copyright>
21
      <year>2006</year>
22
      <year>2007</year>
23
      <year>2008</year>
24
      <holder>Google Inc.</holder>
25
    </copyright>
26
    &dhdate;
27
  </refentryinfo>
28
  <refmeta>
29
    &dhucpackage;
30

    
31
    &dhsection;
32
    <refmiscinfo>ganeti 1.2</refmiscinfo>
33
  </refmeta>
34
  <refnamediv>
35
    <refname>&dhpackage;</refname>
36

    
37
    <refpurpose>ganeti instance administration</refpurpose>
38
  </refnamediv>
39
  <refsynopsisdiv>
40
    <cmdsynopsis>
41
      <command>&dhpackage; </command>
42

    
43
      <arg choice="req">command</arg>
44
      <arg>arguments...</arg>
45
    </cmdsynopsis>
46
  </refsynopsisdiv>
47
  <refsect1>
48
    <title>DESCRIPTION</title>
49

    
50
    <para>
51
      The <command>&dhpackage;</command> is used for instance
52
      administration in the ganeti system.
53
    </para>
54

    
55
  </refsect1>
56
  <refsect1>
57
    <title>COMMANDS</title>
58

    
59
    <refsect2>
60
      <title>Creation/removal/querying</title>
61

    
62
      <refsect3>
63
        <title>ADD</title>
64
        <cmdsynopsis>
65
          <command>add</command>
66
          <arg>-s <replaceable>disksize</replaceable></arg>
67
          <arg>--swap-size <replaceable>disksize</replaceable></arg>
68
          <arg>-m <replaceable>memsize</replaceable></arg>
69
          <sbr>
70

    
71
          <arg>-b <replaceable>bridge</replaceable></arg>
72
          <arg>--mac <replaceable>MAC-address</replaceable></arg>
73
          <sbr>
74

    
75
          <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
76
          <arg>--hvm-acpi <replaceable>ACPI-support</replaceable></arg>
77
          <sbr>
78

    
79
          <arg>--hvm-pae <replaceable>PAE-support</replaceable></arg>
80
          <sbr>
81

    
82
          <arg>--hvm-cdrom-image-path
83
            <replaceable>cdrom-image-path</replaceable></arg>
84
          <sbr>
85

    
86
          <arg>--hvm-nic-type <replaceable>NICTYPE</replaceable></arg>
87
          <sbr>
88

    
89
          <arg>--hvm-disk-type
90
          <replaceable>DISKTYPE</replaceable></arg>
91
          <sbr>
92

    
93
          <arg>--vnc-bind-address
94
            <replaceable>vnc-bind-address</replaceable></arg>
95
          <sbr>
96

    
97
          <arg>--kernel<group choice="req">
98
              <arg>default</arg>
99
              <arg><replaceable>kernel_path</replaceable></arg>
100
            </group></arg>
101
          <sbr>
102

    
103
          <arg>--initrd<group choice="req">
104
              <arg>default</arg>
105
              <arg>none</arg>
106
              <arg><replaceable>initrd_path</replaceable></arg>
107
            </group></arg>
108
          <sbr>
109

    
110
          <arg>--file-storage-dir <replaceable>dir_path</replaceable></arg>
111
          <arg>--file-driver<group choice="req">
112
              <arg>loop</arg>
113
              <arg>blktap</arg>
114
            </group></arg>
115
          <sbr>
116

    
117
          <arg choice="req">-t<group choice="req">
118
              <arg>diskless</arg>
119
              <arg>file</arg>
120
              <arg>plain</arg>
121
              <arg>drbd</arg>
122
            </group></arg>
123
          <sbr>
124

    
125
          <group choice="req">
126
            <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
127
            <arg>--iallocator <replaceable>name</replaceable></arg>
128
          </group>
129
          <sbr>
130

    
131
          <arg choice="req">-o <replaceable>os-type</replaceable></arg>
132
          <sbr>
133

    
134
          <arg choice="req"><replaceable>instance</replaceable></arg>
135
        </cmdsynopsis>
136

    
137
        <para>
138
          Creates a new instance on the specified
139
          host. <replaceable>instance</replaceable> must be in DNS and
140
          resolve to a IP in the same network as the nodes in the
141
          cluster.
142
        </para>
143

    
144
        <para>
145
          The <option>-s</option> option specifies the disk size for
146
          the instance, in mebibytes (defaults to
147
          <constant>20480MiB</constant> =
148
          <constant>20GiB</constant>). You can also use one of the
149
          suffixes <literal>m</literal>, <literal>g</literal> or
150
          <literal>t</literal> to specificy the exact the units used;
151
          these suffixes map to mebibytes, gibibytes and tebibytes.
152
        </para>
153

    
154
        <para>
155
          The <option>--swap-size</option> option specifies the swap
156
          disk size (in mebibytes) for the instance (the one presented
157
          as <filename class="devicefile">/dev/sdb</filename>). The
158
          default is <constant>4096MiB</constant>. As for the disk
159
          size, you can specify other suffixes.
160
        </para>
161

    
162
        <para>
163
          The <option>-m</option> option specifies the memory size for
164
          the instance, in mebibytes (defaults to 128 MiB). Again, you
165
          can use other suffixes (e.g. <userinput>2g</userinput>).
166
        </para>
167

    
168
        <para>
169
          The <option>-o</option> options specifies the operating
170
          system to be installed. The available operating systems can
171
          be listed with <command>gnt-os list</command>.
172
        </para>
173

    
174
        <para>
175
          The <option>-b</option> option specifies the bridge to which the
176
          instance will be connected. (defaults to the cluster-wide default
177
          bridge specified at cluster initialization time).
178
        </para>
179

    
180
        <para>
181
          The <option>--mac</option> option specifies the MAC address
182
          of the ethernet interface for the instance. If this option
183
          is not specified, a new MAC address is generated randomly with
184
          the configured MAC prefix. The randomly generated MAC
185
          address is guaranteed to be unique among the instances of
186
          this cluster.
187
        </para>
188

    
189
        <para>
190
          The <option>--hvm-boot-order</option> option specifies the
191
          boot device order for Xen HVM instances. The boot order is a
192
          string of letters listing the boot devices, with valid
193
          device letters being:
194
        </para>
195

    
196
        <para>
197
          <variablelist>
198
            <varlistentry>
199
              <term>a</term>
200
              <listitem>
201
                <para>
202
                  floppy drive
203
                </para>
204
              </listitem>
205
            </varlistentry>
206
            <varlistentry>
207
              <term>c</term>
208
              <listitem>
209
                <para>
210
                  hard disk
211
                </para>
212
              </listitem>
213
            </varlistentry>
214
            <varlistentry>
215
              <term>d</term>
216
              <listitem>
217
                <para>
218
                  CDROM drive
219
                </para>
220
              </listitem>
221
            </varlistentry>
222
            <varlistentry>
223
              <term>n</term>
224
              <listitem>
225
                <para>
226
                  network boot (PXE)
227
                </para>
228
              </listitem>
229
            </varlistentry>
230
          </variablelist>
231
        </para>
232

    
233
        <para>
234
          The default is not to set an HVM boot order which is
235
          interpreted as 'dc'. This option, like all options starting
236
          with 'hvm', is only relevant for Xen HVM instances and
237
          ignored by all other instance types.
238
        </para>
239

    
240
        <para>
241
          The <option>--hvm-acpi</option> option specifies if Xen
242
          should enable ACPI support for this HVM instance. Valid
243
          values are true or false. The default value is false,
244
          disabling ACPI support for this instance.
245
        </para>
246

    
247
        <para>
248
          The <option>--hvm-pae</option> option specifies if Xen
249
          should enabled PAE support for this HVM instance. Valid
250
          values are true or false. The default is false, disabling
251
          PAE support for this instance.
252
        </para>
253

    
254
        <para>
255
          The <option>--hvm-cdrom-image-path</option> option specifies the
256
          path to the file Xen uses to emulate a virtual CDROM drive
257
          for this HVM instance. Valid values are either an
258
          absolute path to an existing file or None, which disables
259
          virtual CDROM support for this instance. The default is
260
          None, disabling virtual CDROM support.
261
        </para>
262

    
263
        <para>
264
          The <option>--hvm-nic-type</option> specifies the NIC type
265
          Xen should use for this HVM instance. Valid choices are
266
          rtl8139, ne2k_pci, ne2k_isa and paravirtual with rtl8139
267
          as the default. The paravirtual setting is intended for use
268
          with the GPL PV drivers inside HVM Windows instances.
269
        </para>
270

    
271
        <para>
272
          The <option>--hvm-disk-type</option> specifies the disk type
273
          Xen should use for the HVM instance. Valid choices are ioemu
274
          and paravirtual with ioemu as the default. The paravirtual
275
          setting is intended for use with the GPL PV drivers inside
276
          HVM Windows instances.
277
        </para>
278

    
279
        <para>
280
          The <option>--vnc-bind-address</option> option specifies the
281
          address that the VNC listener for this instance should bind
282
          to. Valid values are IPv4 addresses. Use the address 0.0.0.0
283
          to bind to all available interfaces (this is the default)
284
          or specify the address of one of the interfaces on the node
285
          to restrict listening to that interface.
286
        </para>
287

    
288
        <para>
289
          The <option>--iallocator</option> option specifies the instance
290
          allocator plugin to use. If you pass in this option the allocator
291
          will select nodes for this instance automatically, so you don't need
292
          to pass them with the <option>-n</option> option. For more
293
          information please refer to the instance allocator documentation.
294
        </para>
295

    
296
        <para>
297
          The <option>--kernel</option> option allows the instance to
298
          use a custom kernel (if a filename is passed) or to use the
299
          default kernel (<filename>@CUSTOM_XEN_KERNEL@</filename>), if the
300
          string <constant>default</constant> is passed.
301
        </para>
302

    
303
        <para>
304
          The <option>--initrd</option> option is similar: it allows
305
          the instance to use a custom initrd (if a filename is
306
          passed) or to use the default initrd
307
          (<filename>@CUSTOM_XEN_INITRD@</filename>), if the string
308
          <constant>default</constant> is passed, or to disable the
309
          use of an initrd, if the string <constant>none</constant> is
310
          passed. Note that in the case the instance is set to use the
311
          default initrd and it doesn't exist, it will be silently
312
          ignored; if the instance is set to use a custom initrd and
313
          it doesn't exist, this will be treated as an error and will
314
          prevent the startup of the instance.
315
        </para>
316

    
317
        <para>
318
          The <option>-t</option> options specifies the disk layout type for
319
          the instance. The available choices are:
320
          <variablelist>
321
            <varlistentry>
322
              <term>diskless</term>
323
              <listitem>
324
                <para>
325
                  This creates an instance with no disks. Its useful for
326
                  testing only (or other special cases).
327
                </para>
328
              </listitem>
329
            </varlistentry>
330
            <varlistentry>
331
              <term>file</term>
332
              <listitem>
333
                <para>Disk devices will be regular files.</para>
334
              </listitem>
335
            </varlistentry>
336
            <varlistentry>
337
              <term>plain</term>
338
              <listitem>
339
                <para>Disk devices will be logical volumes.</para>
340
              </listitem>
341
            </varlistentry>
342
            <varlistentry>
343
              <term>drbd</term>
344
              <listitem>
345
                <para>
346
                  Disk devices will be drbd (version 8.x) on top of
347
                  lvm volumes.
348
                </para>
349
              </listitem>
350
            </varlistentry>
351
          </variablelist>
352
        </para>
353

    
354
        <para>
355
          The optional second value of the <option>--node</option> is used for
356
          the drbd template type and specifies the remote node.
357
        </para>
358

    
359
        <para>
360
          If you do not want gnt-instance to wait for the disk mirror
361
          to be synced, use the <option>--no-wait-for-sync</option>
362
          option.
363
        </para>
364

    
365
        <para>
366
          The <option>--file-storage-dir</option> specifies the relative path
367
          under the cluster-wide file storage directory to store file-based
368
          disks. It is useful for having different subdirectories for
369
          different instances. The full path of the directory where the disk
370
          files are stored will consist of cluster-wide file storage directory
371
          + optional subdirectory + instance name. Example:
372
          /srv/ganeti/file-storage/mysubdir/instance1.example.com. This option
373
          is only relevant for instances using the file storage backend.
374
        </para>
375

    
376
        <para>
377
          The <option>--file-driver</option> specifies the driver to use for
378
          file-based disks. Note that currently these drivers work with the
379
          xen hypervisor only. This option is only relevant for instances using
380
          the file storage backend. The available choices are:
381
          <variablelist>
382
            <varlistentry>
383
              <term>loop</term>
384
              <listitem>
385
                <para>Kernel loopback driver.</para>
386
              </listitem>
387
            </varlistentry>
388
            <varlistentry>
389
              <term>blktap</term>
390
              <listitem>
391
                <para>blktap driver.</para>
392
              </listitem>
393
            </varlistentry>
394
          </variablelist>
395
        </para>
396

    
397
        <para>
398
          The loop driver uses loopback devices to access the filesystem
399
          within the file. However, running I/O intensive applications
400
          in your instance using the loop driver might result in slowdowns.
401
          Furthermore, if you use the loopback driver consider increasing
402
          the maximum amount of loopback devices (on most systems it's 8)
403
          using the max_loop param.
404
        </para>
405

    
406
        <para>
407
          In order to be able to use the blktap driver you should check
408
          if the 'blktapctrl' user space disk agent is running (usually
409
          automatically started via xend). This user-level disk I/O
410
          interface has the advantage of better performance. Especially
411
          if you use a network file system (e.g. NFS) to store your instances
412
          this is the recommended choice.
413
        </para>
414

    
415
        <para>
416
          Example:
417
          <screen>
418
# gnt-instance add -t file -s 30g -m 512 -o debian-etch \
419
  -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
420
# gnt-instance add -t plain -s 30g -m 512 -o debian-etch \
421
  -n node1.example.com instance1.example.com
422
# gnt-instance add -t drbd -s 30g -m 512 -o debian-etch \
423
  -n node1.example.com:node2.example.com instance2.example.com
424
          </screen>
425
        </para>
426
      </refsect3>
427

    
428
      <refsect3>
429
        <title>REMOVE</title>
430

    
431
        <cmdsynopsis>
432
          <command>remove</command>
433
          <arg>--ignore-failures</arg>
434
          <arg choice="req"><replaceable>instance</replaceable></arg>
435
        </cmdsynopsis>
436

    
437
        <para>
438
          Remove an instance. This will remove all data from the
439
          instance and there is <emphasis>no way back</emphasis>. If
440
          you are not sure if you use an instance again, use
441
          <command>shutdown</command> first and leave it in the
442
          shutdown state for a while.
443

    
444
        </para>
445

    
446
        <para>
447
          The <option>--ignore-failures</option> option will cause the
448
          removal to proceed even in the presence of errors during the
449
          removal of the instance (e.g. during the shutdown or the
450
          disk removal). If this option is not given, the command will
451
          stop at the first error.
452
        </para>
453

    
454
        <para>
455
          Example:
456
          <screen>
457
# gnt-instance remove instance1.example.com
458
          </screen>
459
        </para>
460
      </refsect3>
461

    
462
      <refsect3>
463
        <title>LIST</title>
464

    
465
        <cmdsynopsis>
466
          <command>list</command>
467
          <arg>--no-headers</arg>
468
          <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
469
          <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
470
        </cmdsynopsis>
471

    
472
        <para>
473
          Shows the currently configured instances with memory usage,
474
          disk usage, the node they are running on, and the CPU time,
475
          counted in seconds, used by each instance since its latest
476
          restart.
477
        </para>
478

    
479
        <para>
480
          The <option>--no-headers</option> option will skip the
481
          initial header line. The <option>--separator</option> option
482
          takes an argument which denotes what will be used between
483
          the output fields. Both these options are to help scripting.
484
        </para>
485

    
486
        <para>
487
          The <option>-o</option> option takes a comma-separated list
488
          of output fields. The available fields and their meaning
489
          are:
490
          <variablelist>
491
            <varlistentry>
492
              <term>name</term>
493
              <listitem>
494
                <simpara>the instance name</simpara>
495
              </listitem>
496
            </varlistentry>
497
            <varlistentry>
498
              <term>os</term>
499
              <listitem>
500
                <simpara>the OS of the instance</simpara>
501
              </listitem>
502
            </varlistentry>
503
            <varlistentry>
504
              <term>pnode</term>
505
              <listitem>
506
                <simpara>the primary node of the instance</simpara>
507
              </listitem>
508
            </varlistentry>
509
            <varlistentry>
510
              <term>snodes</term>
511
              <listitem>
512
                <simpara>comma-separated list of secondary nodes for the
513
                  instance; usually this will be just one node</simpara>
514
              </listitem>
515
            </varlistentry>
516
            <varlistentry>
517
              <term>admin_state</term>
518
              <listitem>
519
                <simpara>the desired state of the instance (either "yes"
520
                  or "no" denoting the instance should run or
521
                  not)</simpara>
522
              </listitem>
523
            </varlistentry>
524
            <varlistentry>
525
              <term>admin_ram</term>
526
              <listitem>
527
                <simpara>the desired memory for the instance</simpara>
528
              </listitem>
529
            </varlistentry>
530
            <varlistentry>
531
              <term>disk_template</term>
532
              <listitem>
533
                <simpara>the disk template of the instance</simpara>
534
              </listitem>
535
            </varlistentry>
536
            <varlistentry>
537
              <term>oper_state</term>
538
              <listitem>
539
                <simpara>the actual state of the instance; can be
540
                one of the values "running", "stopped", "(node
541
                down)"</simpara>
542
              </listitem>
543
            </varlistentry>
544
            <varlistentry>
545
              <term>status</term>
546
              <listitem>
547
                <simpara>combined form of admin_state and oper_stat;
548
                this can be one of:
549
                <computeroutput>ERROR_nodedown</computeroutput> if the
550
                node of the instance is down,
551
                <computeroutput>ERROR_down</computeroutput> if the
552
                instance should run but is down,
553
                <computeroutput>ERROR_up</computeroutput> if the
554
                instance should be stopped but is actually running,
555
                <computeroutput>ADMIN_down</computeroutput> if the
556
                instance has been stopped (and is stopped) and
557
                <computeroutput>running</computeroutput> if the
558
                instance is set to be running (and is
559
                running)</simpara>
560
              </listitem>
561
            </varlistentry>
562
            <varlistentry>
563
              <term>oper_ram</term>
564
              <listitem>
565
                <simpara>the actual memory usage of the instance as seen
566
                  by the hypervisor</simpara>
567
              </listitem>
568
            </varlistentry>
569
            <varlistentry>
570
              <term>ip</term>
571
              <listitem>
572
                <simpara>the ip address ganeti recognizes as associated with
573
                the instance interface</simpara>
574
              </listitem>
575
            </varlistentry>
576
            <varlistentry>
577
              <term>mac</term>
578
              <listitem>
579
                <simpara>the instance interface MAC address</simpara>
580
              </listitem>
581
            </varlistentry>
582
            <varlistentry>
583
              <term>bridge</term>
584
              <listitem>
585
                <simpara>bridge the instance is connected to
586
                </simpara>
587
              </listitem>
588
            </varlistentry>
589
            <varlistentry>
590
              <term>sda_size</term>
591
              <listitem>
592
                <simpara>the size of the instance's first disk</simpara>
593
              </listitem>
594
            </varlistentry>
595
            <varlistentry>
596
              <term>sdb_size</term>
597
              <listitem>
598
                <simpara>the size of the instance's second disk</simpara>
599
              </listitem>
600
            </varlistentry>
601
            <varlistentry>
602
              <term>vcpus</term>
603
              <listitem>
604
                <simpara>the number of VCPUs allocated to the
605
                instance</simpara>
606
              </listitem>
607
            </varlistentry>
608
            <varlistentry>
609
              <term>tags</term>
610
              <listitem>
611
                <simpara>comma-separated list of the instances's
612
                tags</simpara>
613
              </listitem>
614
            </varlistentry>
615
            <varlistentry>
616
              <term>serial_no</term>
617
              <listitem>
618
                <simpara>the so called 'serial number' of the
619
                instance; this is a numeric field that is incremented
620
                each time the instance is modified, and it can be used
621
                to detect modifications</simpara>
622
              </listitem>
623
            </varlistentry>
624
          </variablelist>
625
        </para>
626

    
627
        <para>
628
          If the value of the option starts with the character
629
          <constant>+</constant>, the new fields will be added to the
630
          default list. This allows to quickly see the default list
631
          plus a few other fields, instead of retyping the entire list
632
          of fields.
633
        </para>
634

    
635
        <para>
636
          There is a subtle grouping about the available output
637
          fields: all fields except for <option>oper_state</option>,
638
          <option>oper_ram</option> and <option>status</option> are
639
          configuration value and not run-time values. So if you don't
640
          select any of the these fields, the query will be satisfied
641
          instantly from the cluster configuration, without having to
642
          ask the remote nodes for the data. This can be helpful for
643
          big clusters when you only want some data and it makes sense
644
          to specify a reduced set of output fields.
645
        </para>
646

    
647
        <para>The default output field list is:
648
          <simplelist type="inline">
649
            <member>name</member>
650
            <member>os</member>
651
            <member>pnode</member>
652
            <member>admin_state</member>
653
            <member>oper_state</member>
654
            <member>oper_ram</member>
655
          </simplelist>.
656
        </para>
657
      </refsect3>
658

    
659
      <refsect3>
660
        <title>INFO</title>
661

    
662
        <cmdsynopsis>
663
          <command>info</command>
664
          <group>
665
            <arg>-s</arg>
666
            <arg>--static</arg>
667
          </group>
668
          <arg rep="repeat"><replaceable>instance</replaceable></arg>
669
        </cmdsynopsis>
670

    
671
        <para>
672
          Show detailed information about the (given) instances. This
673
          is different from <command>list</command> as it shows
674
          detailed data about the instance's disks (especially useful
675
          for drbd disk template).
676
        </para>
677

    
678
        <para>
679
          If the option <option>-s</option> is used, only information
680
          available in the configuration file is returned, without
681
          querying nodes, making the operation faster.
682
        </para>
683
      </refsect3>
684

    
685
      <refsect3>
686
        <title>MODIFY</title>
687

    
688
        <cmdsynopsis>
689
          <command>modify</command>
690
          <arg choice="opt">-m <replaceable>memsize</replaceable></arg>
691
          <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>
692
          <arg choice="opt">-i <replaceable>ip</replaceable></arg>
693
          <arg choice="opt">-b <replaceable>bridge</replaceable></arg>
694
          <arg choice="opt">--mac <replaceable>MAC-address</replaceable></arg>
695
          <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
696
          <arg>--hvm-acpi <replaceable>ACPI-support</replaceable></arg>
697
          <arg>--hvm-pae <replaceable>PAE-support</replaceable></arg>
698
          <arg>--hvm-cdrom-image-path
699
            <replaceable>cdrom-image-path</replaceable></arg>
700
          <arg>--hvm-nic-type <replaceable>NICTYPE</replaceable></arg>
701
          <arg>--hvm-disk-type <replaceable>DISKTYPE</replaceable></arg>
702
          <arg>--vnc-bind-address
703
            <replaceable>vnc-bind-address</replaceable></arg>
704

    
705
          <sbr>
706
          <arg>--kernel <group choice="req">
707
              <arg>default</arg>
708
              <arg><replaceable>kernel_path</replaceable></arg>
709
            </group></arg>
710
          <sbr>
711
          <arg>--initrd <group choice="req">
712
              <arg>default</arg>
713
              <arg>none</arg>
714
              <arg><replaceable>initrd_path</replaceable></arg>
715
            </group> </arg>
716
          <sbr>
717
          <arg choice="req"><replaceable>instance</replaceable></arg>
718
        </cmdsynopsis>
719

    
720
        <para>
721
          Modify the memory size, number of vcpus, ip address, MAC
722
          address and/or bridge for an instance.
723
        </para>
724

    
725
        <para>
726
          The memory size is given in MiB. Note that you need to give
727
          at least one of the arguments, otherwise the command
728
          complains.
729
        </para>
730

    
731
        <para>
732
          The <option>--kernel</option>, <option>--initrd</option>
733
          and <option>--hvm-boot-order</option>
734
          options are described in the <command>add</command> command.
735
        </para>
736

    
737
        <para>
738
          Additionally, the HVM boot order can be reset to the default
739
          values by using <option>--hvm-boot-order=default</option>.
740
        </para>
741

    
742
        <para>
743
          The <option>--hvm-acpi</option> option specifies if Xen
744
          should enable ACPI support for this HVM instance. Valid
745
          values are true or false.
746
        </para>
747

    
748
        <para>
749
          The <option>--hvm-pae</option> option specifies if Xen
750
          should enabled PAE support for this HVM instance. Valid
751
          values are true or false.
752
        </para>
753

    
754
        <para>
755
          The <option>--hvm-cdrom-image-path</option> specifies the
756
          path to the file xen uses to emulate a virtual CDROM drive
757
          for this HVM instance. Valid values are either an
758
          absolute path to an existing file or None, which disables
759
          virtual CDROM support for this instance.
760
        </para>
761

    
762
        <para>
763
          The <option>--hvm-nic-type</option> specifies the NIC type
764
          Xen should use for this HVM instance. Valid choices are
765
          rtl8139, ne2k_pci, ne2k_isa and paravirtual with rtl8139
766
          as the default. The paravirtual setting is intended for use
767
          with the GPL PV drivers inside HVM Windows instances.
768
        </para>
769

    
770
        <para>
771
          The <option>--hvm-disk-type</option> specifies the disk type
772
          Xen should use for the HVM instance. Valid choices are ioemu
773
          and paravirtual with ioemu as the default. The paravirtual
774
          setting is intended for use with the GPL PV drivers inside
775
          HVM Windows instances.
776
        </para>
777

    
778
        <para>
779
          The <option>--vnc-bind-address</option> specifies the
780
          address that the VNC listener for this instance should bind
781
          to. Valid values are IPv4 addresses. Use the address 0.0.0.0
782
          to bind to all available interfaces.
783
        </para>
784

    
785
        <para>
786
          All the changes take effect at the next restart. If the
787
          instance is running, there is no effect on the instance.
788
        </para>
789
      </refsect3>
790

    
791
      <refsect3>
792
        <title>REINSTALL</title>
793

    
794
        <cmdsynopsis>
795
          <command>reinstall</command>
796
          <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
797
          <arg choice="opt">-f <replaceable>force</replaceable></arg>
798
          <arg>--select-os</arg>
799
          <arg choice="req"><replaceable>instance</replaceable></arg>
800
        </cmdsynopsis>
801

    
802
        <para>
803
          Reinstalls the operating system on the given instance. The instance
804
          must be stopped when running this command. If the
805
          <option>--os-type</option> is specified, the operating system is
806
          changed.
807
        </para>
808

    
809
        <para>
810
          The <option>--select-os</option> option switches to an
811
          interactive OS reinstall. The user is prompted to select the OS
812
          template from the list of available OS templates.
813
        </para>
814
      </refsect3>
815

    
816
      <refsect3>
817
        <title>RENAME</title>
818

    
819
        <cmdsynopsis>
820
          <command>rename</command>
821
          <arg>--no-ip-check</arg>
822
          <arg choice="req"><replaceable>instance</replaceable></arg>
823
          <arg choice="req"><replaceable>new_name</replaceable></arg>
824
        </cmdsynopsis>
825

    
826
        <para>
827
          Renames the given instance. The instance must be stopped
828
          when running this command. The requirements for the new name
829
          are the same as for adding an instance: the new name must be
830
          resolvable and the IP it resolves to must not be reachable
831
          (in order to prevent duplicate IPs the next time the
832
          instance is started). The IP test can be skipped if the
833
          <option>--no-ip-check</option> option is passed.
834
        </para>
835
      </refsect3>
836

    
837
    </refsect2>
838

    
839
    <refsect2>
840
      <title>Starting/stopping/connecting to console</title>
841

    
842
      <refsect3>
843
        <title>STARTUP</title>
844

    
845
        <cmdsynopsis>
846
          <command>startup</command>
847
          <arg>--extra=<replaceable>PARAMS</replaceable></arg>
848
          <arg>--force</arg>
849
          <sbr>
850
          <group choice="opt">
851
            <arg>--instance</arg>
852
            <arg>--node</arg>
853
            <arg>--primary</arg>
854
            <arg>--secondary</arg>
855
            <arg>--all</arg>
856
          </group>
857
          <sbr>
858
          <arg choice="opt"
859
          rep="repeat"><replaceable>name</replaceable></arg>
860
        </cmdsynopsis>
861

    
862
        <para>
863
          Starts one or more instances, depending on the following
864
          options. The four available modes are:
865
          <variablelist>
866
            <varlistentry>
867
              <term><option>--instance</option></term>
868
              <listitem>
869
                <simpara>will start the instances given as arguments
870
                (at least one argument required); this is the default
871
                selection</simpara>
872
              </listitem>
873
            </varlistentry>
874
            <varlistentry>
875
              <term>--node</term>
876
              <listitem>
877
                <simpara>will start the instances who have the given
878
                node as either primary or secondary</simpara>
879
              </listitem>
880
            </varlistentry>
881
            <varlistentry>
882
              <term><option>--primary</option></term>
883
              <listitem>
884
                <simpara>will start all instances whose primary node
885
                is in the list of nodes passed as arguments (at least
886
                one node required)</simpara>
887
              </listitem>
888
            </varlistentry>
889
            <varlistentry>
890
              <term><option>--secondary</option></term>
891
              <listitem>
892
                <simpara>will start all instances whose secondary node
893
                is in the list of nodes passed as arguments (at least
894
                one node required)</simpara>
895
              </listitem>
896
            </varlistentry>
897
            <varlistentry>
898
              <term>--all</term>
899
              <listitem>
900
                <simpara>will start all instances in the cluster (no
901
                arguments accepted)</simpara>
902
              </listitem>
903
            </varlistentry>
904
          </variablelist>
905
        </para>
906

    
907
        <para>
908
          Note that although you can pass more than one selection
909
          option, the last one wins, so in order to guarantee the
910
          desired result, don't pass more than one such option.
911
        </para>
912

    
913
        <para>
914
          The <option>--extra</option> option is used to pass
915
          additional argument to the instance's kernel for this start
916
          only. Currently there is no way to specify a persistent set
917
          of arguments (beside the one hardcoded). Note that this may
918
          not apply to all virtualization types.
919
        </para>
920

    
921
        <para>
922
          Use <option>--force</option> to start even if secondary disks are
923
          failing.
924
        </para>
925

    
926
        <para>
927
          Example:
928
          <screen>
929
# gnt-instance start instance1.example.com
930
# gnt-instance start --extra single test1.example.com
931
# gnt-instance start --node node1.example.com node2.example.com
932
# gnt-instance start --all
933
          </screen>
934
        </para>
935
      </refsect3>
936

    
937
      <refsect3>
938
        <title>SHUTDOWN</title>
939

    
940
        <cmdsynopsis>
941
          <command>shutdown</command>
942
          <sbr>
943
          <group choice="opt">
944
            <arg>--instance</arg>
945
            <arg>--node</arg>
946
            <arg>--primary</arg>
947
            <arg>--secondary</arg>
948
            <arg>--all</arg>
949
          </group>
950
          <sbr>
951

    
952
          <arg choice="opt"
953
          rep="repeat"><replaceable>name</replaceable></arg>
954
        </cmdsynopsis>
955

    
956
        <para>
957
          Stops one or more instances. If the instance cannot be
958
          cleanly stopped during a hardcoded interval (currently 2
959
          minutes), it will forcibly stop the instance (equivalent to
960
          switching off the power on a physical machine).
961
        </para>
962

    
963
        <para>
964
          The <option>--instance</option>, <option>--node</option>,
965
          <option>--primary</option>, <option>--secondary</option> and
966
          <option>--all</option> options are similar as for the
967
          <command>startup</command> command and they influence the
968
          actual instances being shutdown.
969
        </para>
970

    
971
        <para>
972
          Example:
973
          <screen>
974
# gnt-instance shutdown instance1.example.com
975
# gnt-instance shutdown --all
976
          </screen>
977
        </para>
978
      </refsect3>
979

    
980
      <refsect3>
981
        <title>REBOOT</title>
982

    
983
        <cmdsynopsis>
984
          <command>reboot</command>
985
          <sbr>
986
          <arg>--extra=<replaceable>PARAMS</replaceable></arg>
987
          <sbr>
988
          <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
989
          <sbr>
990
          <arg>--ignore-secondaries</arg>
991
          <sbr>
992
          <arg>--force-multiple</arg>
993
          <sbr>
994
          <group choice="opt">
995
            <arg>--instance</arg>
996
            <arg>--node</arg>
997
            <arg>--primary</arg>
998
            <arg>--secondary</arg>
999
            <arg>--all</arg>
1000
          </group>
1001
          <sbr>
1002

    
1003
          <arg choice="opt"
1004
          rep="repeat"><replaceable>name</replaceable></arg>
1005
        </cmdsynopsis>
1006

    
1007
        <para>
1008
          Reboots one or more instances. The type of reboot depends on
1009
          the value of <option>--type</option>. A soft reboot does a
1010
          hypervisor reboot, a hard reboot does a instance stop,
1011
          recreates the hypervisor config for the instance and
1012
          starts the instance. A full reboot does the equivalent
1013
          of <command>gnt-instance shutdown &amp;&amp; gnt-instance
1014
          startup</command>. The default is hard reboot.
1015
        </para>
1016

    
1017
        <para>
1018
          For the hard reboot the option
1019
          <option>--ignore-secondaries</option> ignores errors for the
1020
          secondary node while re-assembling the instance disks.
1021
        </para>
1022

    
1023
        <para>
1024
          The <option>--instance</option>, <option>--node</option>,
1025
          <option>--primary</option>, <option>--secondary</option> and
1026
          <option>--all</option> options are similar as for the
1027
          <command>startup</command> command and they influence the
1028
          actual instances being rebooted.
1029
        </para>
1030

    
1031
        <para>
1032
          Use the <option>--force-multiple</option> option to keep
1033
          gnt-instance from asking for confirmation when more than one
1034
          instance is affected.
1035
        </para>
1036

    
1037
        <para>
1038
          Example:
1039
          <screen>
1040
# gnt-instance reboot instance1.example.com
1041
# gnt-instance reboot --type=full instance1.example.com
1042
          </screen>
1043
        </para>
1044
      </refsect3>
1045

    
1046
      <refsect3>
1047
        <title>CONSOLE</title>
1048
        <cmdsynopsis>
1049
          <command>console</command>
1050
          <arg choice="opt">--show-cmd</arg>
1051
          <arg choice="req"><replaceable>instance</replaceable></arg>
1052
        </cmdsynopsis>
1053

    
1054
        <para>
1055
          Connects to the console of the given instance. If the instance
1056
          is not up, an error is returned. Use the <option>--show-cmd</option>
1057
          option to display the command instead of executing it.
1058
        </para>
1059

    
1060
        <para>
1061
          For HVM instances, this will attempt to connect to the serial
1062
          console of the instance. To connect to the virtualized
1063
          "physical" console of a HVM instance, use a VNC client with
1064
          the connection info from gnt-instance info.
1065
        </para>
1066

    
1067
        <para>
1068
          Example:
1069
          <screen>
1070
# gnt-instance console instance1.example.com
1071
          </screen>
1072
        </para>
1073
      </refsect3>
1074

    
1075
    </refsect2>
1076

    
1077
    <refsect2>
1078
      <title>Disk management</title>
1079

    
1080
      <refsect3>
1081
        <title>REPLACE-DISKS</title>
1082

    
1083
        <cmdsynopsis>
1084
          <command>replace-disks</command>
1085

    
1086
          <group choice="req">
1087
            <arg>--iallocator <replaceable>name</replaceable></arg>
1088
            <arg>--new-secondary <replaceable>NODE</replaceable></arg>
1089
          </group>
1090
          <sbr>
1091

    
1092
          <arg choice="opt">-s</arg>
1093
          <arg choice="req"><replaceable>instance</replaceable></arg>
1094
        </cmdsynopsis>
1095

    
1096
        <cmdsynopsis>
1097
          <command>replace-disks</command>
1098

    
1099
          <group>
1100
          <arg choice="req">-s</arg>
1101
          <arg choice="req">-p</arg>
1102
          </group>
1103
          <arg choice="req"><replaceable>instance</replaceable></arg>
1104
        </cmdsynopsis>
1105

    
1106
        <para>
1107
          This command is a generalized form for adding and replacing
1108
          disks. It is currently only valid for the mirrored (DRBD)
1109
          disk template.
1110
        </para>
1111

    
1112
        <para>
1113
          The first form will do a secondary node change, while the
1114
          second form will replace the disks on either the primary
1115
          (<option>-p</option>) or the secondary (<option>-s</option>)
1116
          node of the instance only, without changing the node.
1117
        </para>
1118

    
1119
        <para>
1120
          Specifying <option>--iallocator</option> enables secondary node
1121
          replacement and and makes the new secondary be selected automatically
1122
          by the specified allocator plugin.
1123
        </para>
1124
      </refsect3>
1125

    
1126
      <refsect3>
1127
        <title>ACTIVATE-DISKS</title>
1128

    
1129
        <cmdsynopsis>
1130
          <command>activate-disks</command>
1131
          <arg choice="req"><replaceable>instance</replaceable></arg>
1132
        </cmdsynopsis>
1133
        <para>
1134
          Activates the block devices of the given instance. If
1135
          successful, the command will show the location and name of
1136
          the block devices:
1137
          <screen>
1138
node1.example.com:sda:/dev/drbd0
1139
node1.example.com:sdb:/dev/drbd1
1140
          </screen>
1141

    
1142
          In this example, <emphasis>node1.example.com</emphasis> is
1143
          the name of the node on which the devices have been
1144
          activated. The <emphasis>sda</emphasis> and
1145
          <emphasis>sdb</emphasis> are the names of the block devices
1146
          inside the instance. <emphasis>/dev/drbd0</emphasis> and
1147
          <emphasis>/dev/drbd1</emphasis> are the names of the block
1148
          devices as visible on the node.
1149
        </para>
1150

    
1151
        <para>
1152
          Note that it is safe to run this command while the instance
1153
          is already running.
1154
        </para>
1155
      </refsect3>
1156

    
1157
      <refsect3>
1158
        <title>DEACTIVATE-DISKS</title>
1159

    
1160
        <cmdsynopsis>
1161
          <command>deactivate-disks</command>
1162
          <arg choice="req"><replaceable>instance</replaceable></arg>
1163
        </cmdsynopsis>
1164
        <para>
1165
          De-activates the block devices of the given instance. Note
1166
          that if you run this command for an instance with a drbd
1167
          disk template, while it is running, it will not be able to
1168
          shutdown the block devices on the primary node, but it will
1169
          shutdown the block devices on the secondary nodes, thus
1170
          breaking the replication.
1171
        </para>
1172

    
1173
      </refsect3>
1174

    
1175
      <refsect3>
1176
        <title>GROW-DISK</title>
1177
        <cmdsynopsis>
1178
          <command>grow-disk</command>
1179
          <arg>--no-wait-for-sync</arg>
1180
          <arg choice="req"><replaceable>instance</replaceable></arg>
1181
          <arg choice="req"><replaceable>disk</replaceable></arg>
1182
          <arg choice="req"><replaceable>amount</replaceable></arg>
1183
        </cmdsynopsis>
1184

    
1185
        <para>
1186
          Grows an instance's disk. This is only possible for
1187
          instances having a <literal>plain</literal> or
1188
          <literal>drbd</literal> disk template.
1189
        </para>
1190

    
1191
        <para>
1192
          Note that this command only change the block device size; it
1193
          will not grow the actual filesystems, partitions, etc. that
1194
          live on that disk. Usually, you will need to:
1195
          <orderedlist>
1196
            <listitem>
1197
              <simpara>use <command>gnt-instance grow-disk</command></simpara>
1198
            </listitem>
1199
            <listitem>
1200
              <simpara>reboot the instance (later, at a convenient
1201
              time)</simpara>
1202
            </listitem>
1203
            <listitem>
1204
              <simpara>use a filesystem resizer, such as
1205
              <citerefentry> <refentrytitle>ext2online</refentrytitle>
1206
              <manvolnum>8</manvolnum> </citerefentry> or
1207
              <citerefentry> <refentrytitle>xfs_growfs</refentrytitle>
1208
              <manvolnum>8</manvolnum> </citerefentry> to resize the
1209
              filesystem, or use <citerefentry>
1210
              <refentrytitle>fdisk</refentrytitle>
1211
              <manvolnum>8</manvolnum> </citerefentry> to change the
1212
              partition table on the disk
1213
              </simpara>
1214
            </listitem>
1215
          </orderedlist>
1216
        </para>
1217

    
1218

    
1219
        <para>
1220
          The <replaceable>disk</replaceable> argument is either
1221
          <literal>sda</literal> or <literal>sdb</literal>. The
1222
          <replaceable>amount</replaceable> argument is given either
1223
          as a number (and it represents the amount to increase the
1224
          disk with in mebibytes) or can be given similar to the
1225
          arguments in the create instance operation, with a suffix
1226
          denoting the unit.
1227
        </para>
1228

    
1229
        <para>
1230
          Note that the disk grow operation might complete on one node
1231
          but fail on the other; this will leave the instance with
1232
          different-sized LVs on the two nodes, but this will not
1233
          create problems (except for unused space).
1234
        </para>
1235

    
1236
        <para>
1237
          If you do not want gnt-instance to wait for the new disk
1238
          region to be synced, use the
1239
          <option>--no-wait-for-sync</option> option.
1240
        </para>
1241

    
1242

    
1243
        <para>Example (increase sda for instance1 by 16GiB):
1244
          <screen>
1245
# gnt-instance grow-disk instance1.example.com sda 16g
1246
          </screen>
1247
        </para>
1248

    
1249
        <para>
1250
          Also note that disk shrinking will not be supported; use
1251
          <command>gnt-backup export</command> and then
1252
          <command>gnt-backup import</command> to reduce the disk size
1253
          of an instance.
1254
        </para>
1255
      </refsect3>
1256

    
1257
    </refsect2>
1258

    
1259
    <refsect2>
1260
      <title>Recovery</title>
1261

    
1262
      <refsect3>
1263
        <title>FAILOVER</title>
1264

    
1265
        <cmdsynopsis>
1266
          <command>failover</command>
1267
          <arg>-f</arg>
1268
          <arg>--ignore-consistency</arg>
1269
          <arg choice="req"><replaceable>instance</replaceable></arg>
1270
        </cmdsynopsis>
1271

    
1272
        <para>
1273
          Failover will fail the instance over its secondary
1274
          node. This works only for instances having a drbd disk
1275
          template.
1276
        </para>
1277

    
1278
        <para>
1279
          Normally the failover will check the consistency of the
1280
          disks before failing over the instance. If you are trying to
1281
          migrate instances off a dead node, this will fail. Use the
1282
          <option>--ignore-consistency</option> option for this
1283
          purpose. Note that this option can be dangerous as errors in
1284
          shutting down the instance will be ignored, resulting in
1285
          possibly having the instance running on two machines in
1286
          parallel (on disconnected DRBD drives).
1287
        </para>
1288

    
1289
        <para>
1290
          Example:
1291
          <screen>
1292
# gnt-instance failover instance1.example.com
1293
          </screen>
1294
        </para>
1295
      </refsect3>
1296

    
1297
    </refsect2>
1298

    
1299
    <refsect2>
1300
      <title>TAGS</title>
1301

    
1302
    <refsect3>
1303
        <title>ADD-TAGS</title>
1304

    
1305
        <cmdsynopsis>
1306
          <command>add-tags</command>
1307
          <arg choice="opt">--from <replaceable>file</replaceable></arg>
1308
          <arg choice="req"><replaceable>instancename</replaceable></arg>
1309
          <arg choice="req"
1310
            rep="repeat"><replaceable>tag</replaceable></arg>
1311
        </cmdsynopsis>
1312

    
1313
        <para>
1314
          Add tags to the given instance. If any of the tags contains
1315
          invalid characters, the entire operation will abort.
1316
        </para>
1317
        <para>
1318
          If the <option>--from</option> option is given, the list of
1319
          tags will be extended with the contents of that file (each
1320
          line becomes a tag). In this case, there is not need to pass
1321
          tags on the command line (if you do, both sources will be
1322
          used). A file name of - will be interpreted as stdin.
1323
        </para>
1324
      </refsect3>
1325

    
1326
      <refsect3>
1327
        <title>LIST-TAGS</title>
1328

    
1329
        <cmdsynopsis>
1330
          <command>list-tags</command>
1331
          <arg choice="req"><replaceable>instancename</replaceable></arg>
1332
        </cmdsynopsis>
1333

    
1334
        <para>List the tags of the given instance.</para>
1335
      </refsect3>
1336

    
1337
      <refsect3>
1338
        <title>REMOVE-TAGS</title>
1339
        <cmdsynopsis>
1340
          <command>remove-tags</command>
1341
          <arg choice="opt">--from <replaceable>file</replaceable></arg>
1342
          <arg choice="req"><replaceable>instancename</replaceable></arg>
1343
          <arg choice="req"
1344
            rep="repeat"><replaceable>tag</replaceable></arg>
1345
        </cmdsynopsis>
1346

    
1347
        <para>
1348
          Remove tags from the given instance. If any of the tags are
1349
          not existing on the node, the entire operation will abort.
1350
        </para>
1351

    
1352
        <para>
1353
          If the <option>--from</option> option is given, the list of
1354
          tags will be extended with the contents of that file (each
1355
          line becomes a tag). In this case, there is not need to pass
1356
          tags on the command line (if you do, both sources will be
1357
          used). A file name of - will be interpreted as stdin.
1358
        </para>
1359
      </refsect3>
1360

    
1361
    </refsect2>
1362

    
1363
  </refsect1>
1364

    
1365
  &footer;
1366

    
1367
</refentry>
1368

    
1369
<!-- Keep this comment at the end of the file
1370
Local variables:
1371
mode: sgml
1372
sgml-omittag:t
1373
sgml-shorttag:t
1374
sgml-minimize-attributes:nil
1375
sgml-always-quote-attributes:t
1376
sgml-indent-step:2
1377
sgml-indent-data:t
1378
sgml-parent-document:nil
1379
sgml-default-dtd-file:nil
1380
sgml-exposed-tags:nil
1381
sgml-local-catalogs:nil
1382
sgml-local-ecat-files:nil
1383
End:
1384
-->