Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.sgml @ bbf74a76

History | View | Annotate | Download (89.8 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>January 22, 2010</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
      <year>2009</year>
25
      <year>2010</year>
26
      <holder>Google Inc.</holder>
27
    </copyright>
28
    &dhdate;
29
  </refentryinfo>
30
  <refmeta>
31
    &dhucpackage;
32

    
33
    &dhsection;
34
    <refmiscinfo>ganeti 2.0</refmiscinfo>
35
  </refmeta>
36
  <refnamediv>
37
    <refname>&dhpackage;</refname>
38

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

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

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

    
57
  </refsect1>
58
  <refsect1>
59
    <title>COMMANDS</title>
60

    
61
    <refsect2>
62
      <title>Creation/removal/querying</title>
63

    
64
      <refsect3>
65
        <title>ADD</title>
66
        <cmdsynopsis>
67
          <command>add</command>
68
          <sbr>
69
          <arg choice="req">-t<group choice="req">
70
              <arg>diskless</arg>
71
              <arg>file</arg>
72
              <arg>plain</arg>
73
              <arg>drbd</arg>
74
            </group></arg>
75
          <sbr>
76

    
77
          <group choice="req">
78
            <arg rep="repeat">--disk=<replaceable>N</replaceable>:<group choice="req">
79
                <arg>size=<replaceable>VAL</replaceable></arg>
80
                <arg>adopt=<replaceable>LV</replaceable></arg>
81
              </group>,mode=<replaceable>ro|rw</replaceable></arg>
82
            <arg>-s <replaceable>SIZE</replaceable></arg>
83
          </group>
84
          <sbr>
85
          <arg>--no-ip-check</arg>
86
          <arg>--no-name-check</arg>
87
          <arg>--no-start</arg>
88
          <sbr>
89
          <group>
90
            <arg rep="repeat">--net=<replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>
91
            <arg>--no-nics</arg>
92
          </group>
93
          <sbr>
94
          <arg>-B <replaceable>BEPARAMS</replaceable></arg>
95
          <sbr>
96

    
97
          <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>
98
          <sbr>
99

    
100
          <arg>--file-storage-dir <replaceable>dir_path</replaceable></arg>
101
          <arg>--file-driver<group choice="req">
102
              <arg>loop</arg>
103
              <arg>blktap</arg>
104
            </group></arg>
105
          <sbr>
106

    
107
          <group choice="req">
108
            <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
109
            <arg>--iallocator <replaceable>name</replaceable></arg>
110
          </group>
111
          <sbr>
112

    
113
          <arg choice="req">-o <replaceable>os-type</replaceable></arg>
114
          <sbr>
115
          <arg>--submit</arg>
116
          <sbr>
117

    
118
          <arg choice="req"><replaceable>instance</replaceable></arg>
119
        </cmdsynopsis>
120

    
121
        <para>
122
          Creates a new instance on the specified host. The
123
          <replaceable>instance</replaceable> argument must be in DNS,
124
          but depending on the bridge/routing setup, need not be in
125
          the same network as the nodes in the cluster.
126
        </para>
127

    
128
        <para>
129
          The <option>disk</option> option specifies the parameters
130
          for the disks of the instance. The numbering of disks starts
131
          at zero, and at least one disk needs to be passed. For each
132
          disk, either the size or the adoption source needs to be
133
          given, and optionally the access mode (read-only or the
134
          default of read-write) can also be specified.  The size is
135
          interpreted (when no unit is given) in mebibytes. You can
136
          also use one of the suffixes
137
          <literal>m</literal>, <literal>g</literal> or
138
          <literal>t</literal> to specificy the exact the units used;
139
          these suffixes map to mebibytes, gibibytes and tebibytes.
140
        </para>
141

    
142
        <para>
143
          When using the <option>adopt</option> key in the disk
144
          definition, Ganeti will reuse those volumes (instead of
145
          creating new ones) as the instance's disks. Ganeti will
146
          rename these volumes to the standard format, and (without
147
          installing the OS) will use them as-is for the
148
          instance. This allows migrating instances from non-managed
149
          mode (e.q. plain KVM with LVM) to being managed via
150
          Ganeti. Note that this works only for the `plain' disk
151
          template (see below for template details).
152
        </para>
153

    
154
        <para>
155
          Alternatively, a single-disk instance can be created via the
156
          <option>-s</option> option which takes a single argument,
157
          the size of the disk. This is similar to the Ganeti 1.2
158
          version (but will only create one disk).
159
        </para>
160

    
161
        <para>
162
          The minimum disk specification is therefore
163
          <userinput>--disk 0:size=20G</userinput> (or <userinput>-s
164
          20G</userinput> when using the <option>-s</option> option),
165
          and a three-disk instance can be specified as
166
          <userinput>--disk 0:size=20G --disk 1:size=4G --disk
167
          2:size=100G</userinput>.
168
        </para>
169

    
170
        <para>
171
          The <option>--no-ip-check</option> skips the checks that are
172
          done to see if the instance's IP is not already alive
173
          (i.e. reachable from the master node).
174
        </para>
175

    
176
        <para>
177
          The <option>--no-name-check</option> skips the check for the
178
          instance name via the resolver (e.g. in DNS or /etc/hosts,
179
          depending on your setup). Since the name check is used to
180
          compute the IP address, if you pass this option you must
181
          also pass the <option>--no-ip-check</option> option.
182
        </para>
183

    
184
        <para>
185
          If you don't wat the instance to automatically start after
186
          creation, this is possible via the
187
          <option>--no-start</option> option. This will leave the
188
          instance down until a subsequent <command>gnt-instance
189
          start</command> command.
190
        </para>
191

    
192
        <para>
193
          The NICs of the instances can be specified via the
194
          <option>--net</option> option. By default, one NIC is
195
          created for the instance, with a random MAC, and set
196
          up according the the cluster level nic parameters.
197
          Each NIC can take these parameters (all optional):
198
          <variablelist>
199
            <varlistentry>
200
              <term>mac</term>
201
              <listitem>
202
                <simpara>either a value or <constant>GENERATE</constant>
203
                  to generate a new unique MAC</simpara>
204
              </listitem>
205
            </varlistentry>
206
            <varlistentry>
207
              <term>ip</term>
208
              <listitem>
209
                <simpara>specifies the IP address assigned to the
210
                  instance from the Ganeti side (this is not necessarily
211
                  what the instance will use, but what the node expects
212
                  the instance to use)</simpara>
213
              </listitem>
214
            </varlistentry>
215
            <varlistentry>
216
              <term>mode</term>
217
              <listitem>
218
                <simpara>specifies the connection mode for this nic:
219
                  routed or bridged.</simpara>
220
              </listitem>
221
            </varlistentry>
222
            <varlistentry>
223
              <term>link</term>
224
              <listitem>
225
                <simpara>in bridged mode specifies the bridge to attach
226
                  this NIC to, in routed mode it's intended to
227
                  differentiate between different routing tables/instance
228
                  groups (but the meaning is dependent on the network
229
                  script, see gnt-cluster(8) for more details)</simpara>
230
              </listitem>
231
            </varlistentry>
232
          </variablelist>
233
          Of these "mode" and "link" are nic parameters, and inherit their
234
          default at cluster level.
235
        </para>
236

    
237
        <para>
238
          Alternatively, if no network is desired for the instance, you
239
          can prevent the default of one NIC with the
240
          <option>--no-nics</option> option.
241
        </para>
242

    
243
        <para>
244
          The <option>-o</option> options specifies the operating
245
          system to be installed. The available operating systems can
246
          be listed with <command>gnt-os list</command>.
247
        </para>
248

    
249
        <para>
250
          The <option>-B</option> option specifies the backend
251
          parameters for the instance. If no such parameters are
252
          specified, the values are inherited from the cluster. Possible
253
          parameters are:
254
          <variablelist>
255
            <varlistentry>
256
              <term>memory</term>
257
              <listitem>
258
                <simpara>the memory size of the instance; as usual,
259
                  suffixes can be used to denote the unit, otherwise the
260
                  value is taken in mebibites</simpara>
261
              </listitem>
262
            </varlistentry>
263
            <varlistentry>
264
              <term>vcpus</term>
265
              <listitem>
266
                <simpara>the number of VCPUs to assign to the instance
267
                  (if this value makes sense for the hypervisor)</simpara>
268
              </listitem>
269
            </varlistentry>
270
            <varlistentry>
271
              <term>auto_balance</term>
272
              <listitem>
273
                <simpara>whether the instance is considered in the N+1
274
                  cluster checks (enough redundancy in the cluster to
275
                  survive a node failure)</simpara>
276
              </listitem>
277
            </varlistentry>
278
          </variablelist>
279
        </para>
280

    
281
        <para>
282
          The <option>-H</option> option specified the hypervisor to
283
          use for the instance (must be one of the enabled hypervisors
284
          on the cluster) and optionally custom parameters for this
285
          instance. If not other options are used (i.e. the invocation
286
          is just <userinput>-H
287
          <replaceable>NAME</replaceable></userinput>) the instance
288
          will inherit the cluster options. The defaults below show
289
          the cluster defaults at cluster creation time.
290
        </para>
291

    
292
        <para>
293
          The possible hypervisor options are as follows:
294
          <variablelist>
295
            <varlistentry>
296
              <term>boot_order</term>
297
              <listitem>
298
                <simpara>Valid for the Xen HVM and KVM
299
                hypervisors.</simpara>
300

    
301
                <simpara>A string value denoting the boot order. This
302
                has different meaning for the Xen HVM hypervisor and
303
                for the KVM one.</simpara>
304

    
305
                <simpara>
306
                  For Xen HVM, The boot order is a string of letters
307
                  listing the boot devices, with valid device letters
308
                  being:
309
                </simpara>
310
                  <variablelist>
311
                    <varlistentry>
312
                      <term>a</term>
313
                      <listitem>
314
                        <para>
315
                          floppy drive
316
                        </para>
317
                      </listitem>
318
                    </varlistentry>
319
                    <varlistentry>
320
                      <term>c</term>
321
                      <listitem>
322
                        <para>
323
                          hard disk
324
                        </para>
325
                      </listitem>
326
                    </varlistentry>
327
                    <varlistentry>
328
                      <term>d</term>
329
                      <listitem>
330
                        <para>
331
                          CDROM drive
332
                        </para>
333
                      </listitem>
334
                    </varlistentry>
335
                    <varlistentry>
336
                      <term>n</term>
337
                      <listitem>
338
                        <para>
339
                          network boot (PXE)
340
                        </para>
341
                      </listitem>
342
                    </varlistentry>
343
                  </variablelist>
344
                <simpara>
345
                  The default is not to set an HVM boot order which is
346
                  interpreted as 'dc'.
347
                </simpara>
348

    
349
                <simpara>
350
                  For KVM the boot order is either
351
                  <quote>cdrom</quote>, <quote>disk</quote> or
352
                  <quote>network</quote>. Please note that older
353
                  versions of KVM couldn't netboot from virtio
354
                  interfaces. This has been fixed in more recent
355
                  versions and is confirmed to work at least with
356
                  qemu-kvm 0.11.1.
357
                </simpara>
358

    
359
              </listitem>
360
            </varlistentry>
361
            <varlistentry>
362
              <term>cdrom_image_path</term>
363
              <listitem>
364
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
365

    
366
                <simpara>The path to a CDROM image to attach to the
367
                instance.</simpara>
368

    
369
              </listitem>
370
            </varlistentry>
371
            <varlistentry>
372
              <term>nic_type</term>
373
              <listitem>
374
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
375

    
376
                <para>
377
                  This parameter determines the way the network cards
378
                  are presented to the instance. The possible options are:
379
                  <simplelist>
380
                    <member>rtl8139 (default for Xen HVM) (HVM & KVM)</member>
381
                    <member>ne2k_isa (HVM & KVM)</member>
382
                    <member>ne2k_pci (HVM & KVM)</member>
383
                    <member>i82551 (KVM)</member>
384
                    <member>i82557b (KVM)</member>
385
                    <member>i82559er (KVM)</member>
386
                    <member>pcnet (KVM)</member>
387
                    <member>e1000 (KVM)</member>
388
                    <member>paravirtual (default for KVM) (HVM & KVM)</member>
389
                  </simplelist>
390
                </para>
391
              </listitem>
392
            </varlistentry>
393
            <varlistentry>
394
              <term>disk_type</term>
395
              <listitem>
396
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
397

    
398
                <para>
399
                  This parameter determines the way the disks are
400
                  presented to the instance. The possible options are:
401
                  <simplelist>
402
                    <member>ioemu (default for HVM & KVM) (HVM & KVM)</member>
403
                    <member>ide (HVM & KVM)</member>
404
                    <member>scsi (KVM)</member>
405
                    <member>sd (KVM)</member>
406
                    <member>mtd (KVM)</member>
407
                    <member>pflash (KVM)</member>
408
                  </simplelist>
409
                </para>
410
              </listitem>
411
            </varlistentry>
412
            <varlistentry>
413
              <term>vnc_bind_address</term>
414
              <listitem>
415
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
416

    
417
                <para>Specifies the address that the VNC listener for
418
                this instance should bind to. Valid values are IPv4
419
                addresses. Use the address 0.0.0.0 to bind to all
420
                available interfaces (this is the default) or specify
421
                the address of one of the interfaces on the node to
422
                restrict listening to that interface.</para>
423
              </listitem>
424
            </varlistentry>
425

    
426
            <varlistentry>
427
              <term>vnc_tls</term>
428
              <listitem>
429
                <simpara>Valid for the KVM hypervisor.</simpara>
430

    
431
                <simpara>A boolean option that controls whether the
432
                VNC connection is secured with TLS.</simpara>
433
              </listitem>
434
            </varlistentry>
435

    
436
            <varlistentry>
437
              <term>vnc_x509_path</term>
438
              <listitem>
439
                <simpara>Valid for the KVM hypervisor.</simpara>
440

    
441
                <para>If <option>vnc_tls</option> is enabled, this
442
                options specifies the path to the x509 certificate to
443
                use.</para>
444
              </listitem>
445
            </varlistentry>
446

    
447
            <varlistentry>
448
              <term>vnc_x509_verify</term>
449
              <listitem>
450
                <simpara>Valid for the KVM hypervisor.</simpara>
451
              </listitem>
452
            </varlistentry>
453

    
454
            <varlistentry>
455
              <term>acpi</term>
456
              <listitem>
457
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
458

    
459
                <para>
460
                  A boolean option that specifies if the hypervisor
461
                  should enable ACPI support for this instance. By
462
                  default, ACPI is disabled.
463
                </para>
464
              </listitem>
465
            </varlistentry>
466

    
467
            <varlistentry>
468
              <term>pae</term>
469
              <listitem>
470
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
471

    
472
                <para>
473
                  A boolean option that specifies if the hypervisor
474
                  should enabled PAE support for this instance. The
475
                  default is false, disabling PAE support.
476
                </para>
477
              </listitem>
478
            </varlistentry>
479

    
480
            <varlistentry>
481
              <term>use_localtime</term>
482
              <listitem>
483
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
484

    
485
                <para>
486
                  A boolean option that specifies if the instance
487
                  should be started with its clock set to the
488
                  localtime of the machine (when true) or to the UTC
489
                  (When false). The default is false, which is useful
490
                  for Linux/Unix machines; for Windows OSes, it is
491
                  recommended to enable this parameter.
492
                </para>
493
              </listitem>
494
            </varlistentry>
495

    
496
            <varlistentry>
497
              <term>kernel_path</term>
498
              <listitem>
499
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
500

    
501
                <para>
502
                  This option specifies the path (on the node) to the
503
                  kernel to boot the instance with. Xen PVM instances
504
                  always require this, while for KVM if this option is
505
                  empty, it will cause the machine to load the kernel
506
                  from its disks.
507
                </para>
508
              </listitem>
509
            </varlistentry>
510

    
511
            <varlistentry>
512
              <term>kernel_args</term>
513
              <listitem>
514
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
515

    
516
                <para>
517
                  This options specifies extra arguments to the kernel
518
                  that will be loaded.  device. This is always used
519
                  for Xen PVM, while for KVM it is only used if the
520
                  <option>kernel_path</option> option is also
521
                  specified.
522
                </para>
523

    
524
                <para>
525
                  The default setting for this value is simply
526
                  <constant>"ro"</constant>, which mounts the root
527
                  disk (initially) in read-only one. For example,
528
                  setting this to <userinput>single</userinput> will
529
                  cause the instance to start in single-user mode.
530
                </para>
531
              </listitem>
532
            </varlistentry>
533

    
534
            <varlistentry>
535
              <term>initrd_path</term>
536
              <listitem>
537
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
538

    
539
                <para>
540
                  This option specifies the path (on the node) to the
541
                  initrd to boot the instance with. Xen PVM instances
542
                  can use this always, while for KVM if this option is
543
                  only used if the <option>kernel_path</option> option
544
                  is also specified. You can pass here either an
545
                  absolute filename (the path to the initrd) if you
546
                  want to use an initrd, or use the format
547
                  <userinput>no_initrd_path</userinput> for no initrd.
548
                </para>
549
              </listitem>
550
            </varlistentry>
551

    
552
            <varlistentry>
553
              <term>root_path</term>
554
              <listitem>
555
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
556

    
557
                <para>
558
                  This options specifies the name of the root
559
                  device. This is always needed for Xen PVM, while for
560
                  KVM it is only used if the
561
                  <option>kernel_path</option> option is also
562
                  specified.
563
                </para>
564
              </listitem>
565
            </varlistentry>
566

    
567
            <varlistentry>
568
              <term>serial_console</term>
569
              <listitem>
570
                <simpara>Valid for the KVM hypervisor.</simpara>
571

    
572
                <simpara>This boolean option specifies whether to
573
                emulate a serial console for the instance.</simpara>
574
              </listitem>
575
            </varlistentry>
576

    
577
            <varlistentry>
578
              <term>disk_cache</term>
579
              <listitem>
580
                <simpara>Valid for the KVM hypervisor.</simpara>
581

    
582
                <simpara>The disk cache mode. It can be either
583
                <userinput>default</userinput> to not pass any cache
584
                option to KVM, or one of the KVM cache modes: none
585
                (for direct I/O), writethrough (to use the host cache
586
                but report completion to the guest only when the host
587
                has commited the changes to disk) or writeback (to use
588
                the host cache and report completion as soon as the
589
                data is in the host cache). Note that there are
590
                special considerations for the cache mode depending on
591
                version of KVM used and disk type (always raw file
592
                under Ganeti), please refer to the KVM documentation
593
                for more details.
594
                </simpara>
595
              </listitem>
596
            </varlistentry>
597

    
598
            <varlistentry>
599
              <term>security_model</term>
600
              <listitem>
601
                <simpara>Valid for the KVM hypervisor.</simpara>
602

    
603
                <simpara>The security model for kvm. Currently one of
604
                <quote>none</quote>, <quote>user</quote> or
605
                <quote>pool</quote>. Under <quote>none</quote>, the
606
                default, nothing is done and instances are run as
607
                the ganeti daemon user (normally root).
608
                </simpara>
609

    
610
                <simpara>Under <quote>user</quote> kvm will drop
611
                privileges and become the user specified by the
612
                security_domain parameter.
613
                </simpara>
614

    
615
                <simpara>Under <quote>pool</quote> a global cluster
616
                pool of users will be used, making sure no two
617
                instances share the same user on the same node.
618
                (this mode is not implemented yet)
619
                </simpara>
620

    
621
              </listitem>
622
            </varlistentry>
623

    
624
            <varlistentry>
625
              <term>security_domain</term>
626
              <listitem>
627
                <simpara>Valid for the KVM hypervisor.</simpara>
628

    
629
                <simpara>Under security model <quote>user</quote> the username to
630
                run the instance under. It must be a valid username
631
                existing on the host.
632
                </simpara>
633
                <simpara>Cannot be set under security model <quote>none</quote>
634
                or <quote>pool</quote>.
635
                </simpara>
636

    
637
              </listitem>
638
            </varlistentry>
639

    
640
          </variablelist>
641

    
642
        </para>
643

    
644
        <para>
645
          The <option>--iallocator</option> option specifies the instance
646
          allocator plugin to use. If you pass in this option the allocator
647
          will select nodes for this instance automatically, so you don't need
648
          to pass them with the <option>-n</option> option. For more
649
          information please refer to the instance allocator documentation.
650
        </para>
651

    
652
        <para>
653
          The <option>-t</option> options specifies the disk layout type for
654
          the instance. The available choices are:
655
          <variablelist>
656
            <varlistentry>
657
              <term>diskless</term>
658
              <listitem>
659
                <para>
660
                  This creates an instance with no disks. Its useful for
661
                  testing only (or other special cases).
662
                </para>
663
              </listitem>
664
            </varlistentry>
665
            <varlistentry>
666
              <term>file</term>
667
              <listitem>
668
                <para>Disk devices will be regular files.</para>
669
              </listitem>
670
            </varlistentry>
671
            <varlistentry>
672
              <term>plain</term>
673
              <listitem>
674
                <para>Disk devices will be logical volumes.</para>
675
              </listitem>
676
            </varlistentry>
677
            <varlistentry>
678
              <term>drbd</term>
679
              <listitem>
680
                <para>
681
                  Disk devices will be drbd (version 8.x) on top of
682
                  lvm volumes.
683
                </para>
684
              </listitem>
685
            </varlistentry>
686
          </variablelist>
687
        </para>
688

    
689
        <para>
690
          The optional second value of the <option>--node</option> is used for
691
          the drbd template type and specifies the remote node.
692
        </para>
693

    
694
        <para>
695
          If you do not want gnt-instance to wait for the disk mirror
696
          to be synced, use the <option>--no-wait-for-sync</option>
697
          option.
698
        </para>
699

    
700
        <para>
701
          The <option>--file-storage-dir</option> specifies the relative path
702
          under the cluster-wide file storage directory to store file-based
703
          disks. It is useful for having different subdirectories for
704
          different instances. The full path of the directory where the disk
705
          files are stored will consist of cluster-wide file storage directory
706
          + optional subdirectory + instance name. Example:
707
          /srv/ganeti/file-storage/mysubdir/instance1.example.com. This option
708
          is only relevant for instances using the file storage backend.
709
        </para>
710

    
711
        <para>
712
          The <option>--file-driver</option> specifies the driver to use for
713
          file-based disks. Note that currently these drivers work with the
714
          xen hypervisor only. This option is only relevant for instances using
715
          the file storage backend. The available choices are:
716
          <variablelist>
717
            <varlistentry>
718
              <term>loop</term>
719
              <listitem>
720
                <para>
721
                  Kernel loopback driver. This driver uses loopback
722
                  devices to access the filesystem within the
723
                  file. However, running I/O intensive applications in
724
                  your instance using the loop driver might result in
725
                  slowdowns.  Furthermore, if you use the loopback
726
                  driver consider increasing the maximum amount of
727
                  loopback devices (on most systems it's 8) using the
728
                  max_loop param.
729
                </para>
730
              </listitem>
731
            </varlistentry>
732
            <varlistentry>
733
              <term>blktap</term>
734
              <listitem>
735
                <para>The blktap driver (for Xen hypervisors). In
736
                order to be able to use the blktap driver you should
737
                check if the 'blktapctrl' user space disk agent is
738
                running (usually automatically started via xend). This
739
                user-level disk I/O interface has the advantage of
740
                better performance. Especially if you use a network
741
                file system (e.g. NFS) to store your instances this is
742
                the recommended choice.
743
                </para>
744
              </listitem>
745
            </varlistentry>
746
          </variablelist>
747
        </para>
748

    
749
        <para>
750
          The <option>--submit</option> option is used to send the job to
751
          the master daemon but not wait for its completion. The job
752
          ID will be shown so that it can be examined via
753
          <command>gnt-job info</command>.
754
        </para>
755

    
756
        <para>
757
          Example:
758
          <screen>
759
# gnt-instance add -t file --disk 0:size=30g -B memory=512 -o debian-etch \
760
  -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
761
# gnt-instance add -t plain --disk 0:size=30g -B memory=512 -o debian-etch \
762
  -n node1.example.com instance1.example.com
763
# gnt-instance add -t drbd --disk 0:size=30g -B memory=512 -o debian-etch \
764
  -n node1.example.com:node2.example.com instance2.example.com
765
          </screen>
766
        </para>
767
      </refsect3>
768

    
769
      <refsect3>
770
        <title>BATCH-CREATE</title>
771
        <cmdsynopsis>
772
          <command>batch-create</command>
773
          <arg choice="req">instances_file.json</arg>
774
        </cmdsynopsis>
775

    
776
        <para>
777
          This command (similar to the Ganeti 1.2
778
          <command>batcher</command> tool) submits multiple instance
779
          creation jobs based on a definition file. The instance
780
          configurations do not encompass all the possible options for
781
          the <command>add</command> command, but only a subset.
782
        </para>
783

    
784
        <para>
785
          The instance file should be a valid-formed JSON file,
786
          containing a dictionary with instance name and instance
787
          parameters. The accepted parameters are:
788

    
789
          <variablelist>
790
            <varlistentry>
791
              <term>disk_size</term>
792
              <listitem>
793
                <simpara>The size of the disks of the instance.</simpara>
794
              </listitem>
795
            </varlistentry>
796
            <varlistentry>
797
              <term>disk_templace</term>
798
              <listitem>
799
                <simpara>The disk template to use for the instance,
800
                the same as in the <command>add</command>
801
                command.</simpara>
802
              </listitem>
803
            </varlistentry>
804
            <varlistentry>
805
              <term>backend</term>
806
              <listitem>
807
                <simpara>A dictionary of backend parameters.</simpara>
808
              </listitem>
809
            </varlistentry>
810
            <varlistentry>
811
              <term>hypervisor</term>
812
              <listitem>
813
                <simpara>A dictionary with a single key (the
814
                hypervisor name), and as value the hypervisor
815
                options. If not passed, the default hypervisor and
816
                hypervisor options will be inherited.</simpara>
817
              </listitem>
818
            </varlistentry>
819
            <varlistentry>
820
              <term>mac, ip, mode, link</term>
821
              <listitem>
822
                <simpara>Specifications for the one NIC that will be
823
                created for the instance. 'bridge' is also accepted
824
                as a backwards compatibile key.</simpara>
825
              </listitem>
826
            </varlistentry>
827
            <varlistentry>
828
              <term>nics</term>
829
              <listitem>
830
                <simpara>List of nics that will be created for the
831
                instance. Each entry should be a dict, with mac, ip, mode
832
                and link as possible keys. Please don't provide the "mac,
833
                ip, mode, link" parent keys if you use this method for
834
                specifying nics.</simpara>
835
              </listitem>
836
            </varlistentry>
837
            <varlistentry>
838
              <term>primary_node, secondary_node</term>
839
              <listitem>
840
                <simpara>The primary and optionally the secondary node
841
                to use for the instance (in case an iallocator script
842
                is not used).</simpara>
843
              </listitem>
844
            </varlistentry>
845
            <varlistentry>
846
              <term>iallocator</term>
847
              <listitem>
848
                <simpara>Instead of specifying the nodes, an
849
                iallocator script can be used to automatically compute
850
                them.</simpara>
851
              </listitem>
852
            </varlistentry>
853
            <varlistentry>
854
              <term>start</term>
855
              <listitem>
856
                <simpara>whether to start the instance</simpara>
857
              </listitem>
858
            </varlistentry>
859
            <varlistentry>
860
              <term>ip_check</term>
861
              <listitem>
862
                <simpara>Skip the check for already-in-use instance;
863
                see the description in the <command>add</command>
864
                command for details.</simpara>
865
              </listitem>
866
            </varlistentry>
867
            <varlistentry>
868
              <term>name_check</term>
869
              <listitem>
870
                <simpara>Skip the name check for instances;
871
                see the description in the <command>add</command>
872
                command for details.</simpara>
873
              </listitem>
874
            </varlistentry>
875
            <varlistentry>
876
              <term>file_storage_dir, file_driver</term>
877
              <listitem>
878
                <simpara>Configuration for the <literal>file</literal>
879
                disk type, see the <command>add</command> command for
880
                details.</simpara>
881
              </listitem>
882
            </varlistentry>
883
          </variablelist>
884
        </para>
885

    
886
        <para>
887
          A simple definition for one instance can be (with most of
888
          the parameters taken from the cluster defaults):
889
          <screen>
890
{
891
  "instance3": {
892
    "template": "drbd",
893
    "os": "debootstrap",
894
    "disk_size": ["25G"],
895
    "iallocator": "dumb"
896
  },
897
  "instance5": {
898
    "template": "drbd",
899
    "os": "debootstrap",
900
    "disk_size": ["25G"],
901
    "iallocator": "dumb",
902
    "hypervisor": "xen-hvm",
903
    "hvparams": {"acpi": true},
904
    "backend": {"memory": 512}
905
  }
906
}
907
</screen>
908
        </para>
909

    
910
        <para>
911
          The command will display the job id for each submitted instance, as follows:
912
          <screen>
913
# gnt-instance batch-create instances.json
914
instance3: 11224
915
instance5: 11225
916
</screen>
917
        </para>
918

    
919
      </refsect3>
920

    
921
      <refsect3>
922
        <title>REMOVE</title>
923

    
924
        <cmdsynopsis>
925
          <command>remove</command>
926
          <arg>--ignore-failures</arg>
927
          <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
928
          <arg>--submit</arg>
929
          <arg choice="req"><replaceable>instance</replaceable></arg>
930
        </cmdsynopsis>
931

    
932
        <para>
933
          Remove an instance. This will remove all data from the
934
          instance and there is <emphasis>no way back</emphasis>. If
935
          you are not sure if you use an instance again, use
936
          <command>shutdown</command> first and leave it in the
937
          shutdown state for a while.
938

    
939
        </para>
940

    
941
        <para>
942
          The <option>--ignore-failures</option> option will cause the
943
          removal to proceed even in the presence of errors during the
944
          removal of the instance (e.g. during the shutdown or the
945
          disk removal). If this option is not given, the command will
946
          stop at the first error.
947
        </para>
948

    
949
        <para>
950
          The <option>--shutdown-timeout</option> is used to specify how
951
          much time to wait before forcing the shutdown (xm destroy in xen,
952
          killing the kvm process, for kvm). By default two minutes are
953
          given to each instance to stop.
954
        </para>
955

    
956
        <para>
957
          The <option>--submit</option> option is used to send the job to
958
          the master daemon but not wait for its completion. The job
959
          ID will be shown so that it can be examined via
960
          <command>gnt-job info</command>.
961
        </para>
962

    
963
        <para>
964
          Example:
965
          <screen>
966
# gnt-instance remove instance1.example.com
967
          </screen>
968
        </para>
969
      </refsect3>
970

    
971
      <refsect3>
972
        <title>LIST</title>
973

    
974
        <cmdsynopsis>
975
          <command>list</command>
976
          <arg>--no-headers</arg>
977
          <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
978
          <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
979
          <arg rep="repeat">instance</arg>
980
        </cmdsynopsis>
981

    
982
        <para>
983
          Shows the currently configured instances with memory usage,
984
          disk usage, the node they are running on, and their run
985
          status.
986
        </para>
987

    
988
        <para>
989
          The <option>--no-headers</option> option will skip the
990
          initial header line. The <option>--separator</option> option
991
          takes an argument which denotes what will be used between
992
          the output fields. Both these options are to help scripting.
993
        </para>
994

    
995
        <para>
996
          The <option>-o</option> option takes a comma-separated list
997
          of output fields. The available fields and their meaning
998
          are:
999
          <variablelist>
1000
            <varlistentry>
1001
              <term>name</term>
1002
              <listitem>
1003
                <simpara>the instance name</simpara>
1004
              </listitem>
1005
            </varlistentry>
1006
            <varlistentry>
1007
              <term>os</term>
1008
              <listitem>
1009
                <simpara>the OS of the instance</simpara>
1010
              </listitem>
1011
            </varlistentry>
1012
            <varlistentry>
1013
              <term>pnode</term>
1014
              <listitem>
1015
                <simpara>the primary node of the instance</simpara>
1016
              </listitem>
1017
            </varlistentry>
1018
            <varlistentry>
1019
              <term>snodes</term>
1020
              <listitem>
1021
                <simpara>comma-separated list of secondary nodes for the
1022
                  instance; usually this will be just one node</simpara>
1023
              </listitem>
1024
            </varlistentry>
1025
            <varlistentry>
1026
              <term>admin_state</term>
1027
              <listitem>
1028
                <simpara>the desired state of the instance (either "yes"
1029
                  or "no" denoting the instance should run or
1030
                  not)</simpara>
1031
              </listitem>
1032
            </varlistentry>
1033
            <varlistentry>
1034
              <term>disk_template</term>
1035
              <listitem>
1036
                <simpara>the disk template of the instance</simpara>
1037
              </listitem>
1038
            </varlistentry>
1039
            <varlistentry>
1040
              <term>oper_state</term>
1041
              <listitem>
1042
                <simpara>the actual state of the instance; can be
1043
                one of the values "running", "stopped", "(node
1044
                down)"</simpara>
1045
              </listitem>
1046
            </varlistentry>
1047
            <varlistentry>
1048
              <term>status</term>
1049
              <listitem>
1050
                <simpara>combined form of admin_state and oper_stat;
1051
                this can be one of:
1052
                <computeroutput>ERROR_nodedown</computeroutput> if the
1053
                node of the instance is down,
1054
                <computeroutput>ERROR_down</computeroutput> if the
1055
                instance should run but is down,
1056
                <computeroutput>ERROR_up</computeroutput> if the
1057
                instance should be stopped but is actually running,
1058
                <computeroutput>ADMIN_down</computeroutput> if the
1059
                instance has been stopped (and is stopped) and
1060
                <computeroutput>running</computeroutput> if the
1061
                instance is set to be running (and is
1062
                running)</simpara>
1063
              </listitem>
1064
            </varlistentry>
1065
            <varlistentry>
1066
              <term>oper_ram</term>
1067
              <listitem>
1068
                <simpara>the actual memory usage of the instance as seen
1069
                  by the hypervisor</simpara>
1070
              </listitem>
1071
            </varlistentry>
1072
            <varlistentry>
1073
              <term>ip</term>
1074
              <listitem>
1075
                <simpara>the ip address ganeti recognizes as associated with
1076
                the first instance interface</simpara>
1077
              </listitem>
1078
            </varlistentry>
1079
            <varlistentry>
1080
              <term>mac</term>
1081
              <listitem>
1082
                <simpara>the first instance interface MAC address</simpara>
1083
              </listitem>
1084
            </varlistentry>
1085

    
1086
            <varlistentry>
1087
              <term>nic_mode</term>
1088
              <listitem>
1089
                <simpara>the mode of the first instance NIC
1090
                (routed or bridged)</simpara>
1091
              </listitem>
1092
            </varlistentry>
1093
            <varlistentry>
1094
              <term>nic_link</term>
1095
              <listitem>
1096
                <simpara>the link of the first instance NIC
1097
                </simpara>
1098
              </listitem>
1099
            </varlistentry>
1100
            <varlistentry>
1101
              <term>sda_size</term>
1102
              <listitem>
1103
                <simpara>the size of the instance's first disk</simpara>
1104
              </listitem>
1105
            </varlistentry>
1106
            <varlistentry>
1107
              <term>sdb_size</term>
1108
              <listitem>
1109
                <simpara>the size of the instance's second disk, if
1110
                any</simpara>
1111
              </listitem>
1112
            </varlistentry>
1113
            <varlistentry>
1114
              <term>vcpus</term>
1115
              <listitem>
1116
                <simpara>the number of VCPUs allocated to the
1117
                instance</simpara>
1118
              </listitem>
1119
            </varlistentry>
1120
            <varlistentry>
1121
              <term>tags</term>
1122
              <listitem>
1123
                <simpara>comma-separated list of the instances's
1124
                tags</simpara>
1125
              </listitem>
1126
            </varlistentry>
1127
            <varlistentry>
1128
              <term>serial_no</term>
1129
              <listitem>
1130
                <simpara>the so called 'serial number' of the
1131
                instance; this is a numeric field that is incremented
1132
                each time the instance is modified, and it can be used
1133
                to track modifications</simpara>
1134
              </listitem>
1135
            </varlistentry>
1136
            <varlistentry>
1137
              <term>ctime</term>
1138
              <listitem>
1139
                <para>
1140
                  the creation time of the instance; note that this
1141
                  field contains spaces and as such it's harder to
1142
                  parse
1143
                </para>
1144
                <para>
1145
                  if this attribute is not present (e.g. when
1146
                  upgrading from older versions), then "N/A" will be
1147
                  shown instead
1148
                </para>
1149
              </listitem>
1150
            </varlistentry>
1151
            <varlistentry>
1152
              <term>mtime</term>
1153
              <listitem>
1154
                <para>
1155
                  the last modification time of the instance; note
1156
                  that this field contains spaces and as such it's
1157
                  harder to parse
1158
                </para>
1159
                <para>
1160
                  if this attribute is not present (e.g. when
1161
                  upgrading from older versions), then "N/A" will be
1162
                  shown instead
1163
                </para>
1164
              </listitem>
1165
            </varlistentry>
1166

    
1167
            <varlistentry>
1168
              <term>uuid</term>
1169
              <listitem>
1170
                <simpara>Show the UUID of the instance (generated
1171
                automatically by Ganeti)</simpara>
1172
              </listitem>
1173
            </varlistentry>
1174

    
1175
            <varlistentry>
1176
              <term>network_port</term>
1177
              <listitem>
1178
                <simpara>If the instance has a network port assigned
1179
                to it (e.g. for VNC connections), this will be shown,
1180
                otherwise <literal>-</literal> will be
1181
                displayed.</simpara>
1182
              </listitem>
1183
            </varlistentry>
1184
            <varlistentry>
1185
              <term>beparams</term>
1186
              <listitem>
1187
                <simpara>A text format of the entire beparams for the
1188
                instance. It's more useful to select individual fields
1189
                from this dictionary, see below.</simpara>
1190
              </listitem>
1191
            </varlistentry>
1192
            <varlistentry>
1193
              <term>disk.count</term>
1194
              <listitem>
1195
                <simpara>The number of instance disks.</simpara>
1196
              </listitem>
1197
            </varlistentry>
1198
            <varlistentry>
1199
              <term>disk.size/N</term>
1200
              <listitem>
1201
                <simpara>The size of the instance's Nth disk. This is
1202
                a more generic form of the <literal>sda_size</literal>
1203
                and <literal>sdb_size</literal> fields.</simpara>
1204
              </listitem>
1205
            </varlistentry>
1206
            <varlistentry>
1207
              <term>disk.sizes</term>
1208
              <listitem>
1209
                <simpara>A comma-separated list of the disk sizes for
1210
                this instance.</simpara>
1211
              </listitem>
1212
            </varlistentry>
1213
            <varlistentry>
1214
              <term>disk_usage</term>
1215
              <listitem>
1216
                <simpara>The total disk space used by this instance on
1217
                each of its nodes. This is not the instance-visible
1218
                disk size, but the actual disk "cost" of the
1219
                instance.</simpara>
1220
              </listitem>
1221
            </varlistentry>
1222
            <varlistentry>
1223
              <term>nic.mac/N</term>
1224
              <listitem>
1225
                <simpara>The MAC of the Nth instance NIC.</simpara>
1226
              </listitem>
1227
            </varlistentry>
1228
            <varlistentry>
1229
              <term>nic.ip/N</term>
1230
              <listitem>
1231
                <simpara>The IP address of the Nth instance NIC.</simpara>
1232
              </listitem>
1233
            </varlistentry>
1234
            <varlistentry>
1235
              <term>nic.mode/N</term>
1236
              <listitem>
1237
                <simpara>The mode of the Nth instance NIC</simpara>
1238
              </listitem>
1239
            </varlistentry>
1240
            <varlistentry>
1241
              <term>nic.link/N</term>
1242
              <listitem>
1243
                <simpara>The link of the Nth instance NIC</simpara>
1244
              </listitem>
1245
            </varlistentry>
1246
            <varlistentry>
1247
              <term>nic.macs</term>
1248
              <listitem>
1249
                <simpara>A comma-separated list of all the MACs of the
1250
                instance's NICs.</simpara>
1251
              </listitem>
1252
            </varlistentry>
1253
            <varlistentry>
1254
              <term>nic.ips</term>
1255
              <listitem>
1256
                <simpara>A comma-separated list of all the IP
1257
                addresses of the instance's NICs.</simpara>
1258
              </listitem>
1259
            </varlistentry>
1260
            <varlistentry>
1261
              <term>nic.modes</term>
1262
              <listitem>
1263
                <simpara>A comma-separated list of all the modes of the
1264
                instance's NICs.</simpara>
1265
              </listitem>
1266
            </varlistentry>
1267
            <varlistentry>
1268
              <term>nic.links</term>
1269
              <listitem>
1270
                <simpara>A comma-separated list of all the link parameters
1271
                of the instance's NICs.</simpara>
1272
              </listitem>
1273
            </varlistentry>
1274
            <varlistentry>
1275
              <term>nic.count</term>
1276
              <listitem>
1277
                <simpara>The number of instance nics.</simpara>
1278
              </listitem>
1279
            </varlistentry>
1280
            <varlistentry>
1281
              <term>hv/<replaceable>NAME</replaceable></term>
1282
              <listitem>
1283
                <simpara>The value of the hypervisor parameter called
1284
                <replaceable>NAME</replaceable>. For details of what
1285
                hypervisor parameters exist and their meaning, see the
1286
                <command>add</command> command.</simpara>
1287
              </listitem>
1288
            </varlistentry>
1289
            <varlistentry>
1290
              <term>be/memory</term>
1291
              <listitem>
1292
                <simpara>The configured memory for the instance.</simpara>
1293
              </listitem>
1294
            </varlistentry>
1295
            <varlistentry>
1296
              <term>be/vcpus</term>
1297
              <listitem>
1298
                <simpara>The configured number of VCPUs for the
1299
                instance.</simpara>
1300
              </listitem>
1301
            </varlistentry>
1302
            <varlistentry>
1303
              <term>be/auto_balance</term>
1304
              <listitem>
1305
                <simpara>Whether the instance is considered in N+1
1306
                checks.</simpara>
1307
              </listitem>
1308
            </varlistentry>
1309
          </variablelist>
1310
        </para>
1311

    
1312
        <para>
1313
          If the value of the option starts with the character
1314
          <constant>+</constant>, the new field(s) will be added to the
1315
          default list. This allows to quickly see the default list
1316
          plus a few other fields, instead of retyping the entire list
1317
          of fields.
1318
        </para>
1319

    
1320
        <para>
1321
          There is a subtle grouping about the available output
1322
          fields: all fields except for <option>oper_state</option>,
1323
          <option>oper_ram</option> and <option>status</option> are
1324
          configuration value and not run-time values. So if you don't
1325
          select any of the these fields, the query will be satisfied
1326
          instantly from the cluster configuration, without having to
1327
          ask the remote nodes for the data. This can be helpful for
1328
          big clusters when you only want some data and it makes sense
1329
          to specify a reduced set of output fields.
1330
        </para>
1331

    
1332
        <para>The default output field list is:
1333
          <simplelist type="inline">
1334
            <member>name</member>
1335
            <member>os</member>
1336
            <member>pnode</member>
1337
            <member>admin_state</member>
1338
            <member>oper_state</member>
1339
            <member>oper_ram</member>
1340
          </simplelist>.
1341
        </para>
1342
      </refsect3>
1343

    
1344
      <refsect3>
1345
        <title>INFO</title>
1346

    
1347
        <cmdsynopsis>
1348
          <command>info</command>
1349
          <group>
1350
            <arg>-s</arg>
1351
            <arg>--static</arg>
1352
          </group>
1353
          <group choice="req">
1354
            <arg>--all</arg>
1355
            <arg rep="repeat"><replaceable>instance</replaceable></arg>
1356
          </group>
1357
        </cmdsynopsis>
1358

    
1359
        <para>
1360
          Show detailed information about the given instance(s). This is
1361
          different from <command>list</command> as it shows detailed data
1362
          about the instance's disks (especially useful for the drbd disk
1363
          template).
1364
        </para>
1365

    
1366
        <para>
1367
          If the option <option>-s</option> is used, only information
1368
          available in the configuration file is returned, without
1369
          querying nodes, making the operation faster.
1370
        </para>
1371

    
1372
        <para>
1373
          Use the <option>--all</option> to get info about all instances,
1374
          rather than explicitly passing the ones you're interested in.
1375
        </para>
1376
      </refsect3>
1377

    
1378
      <refsect3>
1379
        <title>MODIFY</title>
1380

    
1381
        <cmdsynopsis>
1382
          <command>modify</command>
1383
          <sbr>
1384
          <arg choice="opt">-H <replaceable>HYPERVISOR_PARAMETERS</replaceable></arg>
1385
          <sbr>
1386
          <arg choice="opt">-B <replaceable>BACKEND_PARAMETERS</replaceable></arg>
1387
          <sbr>
1388
          <group>
1389
            <arg>--net add<replaceable><optional>:options</optional></replaceable></arg>
1390
            <arg>--net remove</arg>
1391
            <arg>--net <replaceable>N:options</replaceable></arg>
1392
          </group>
1393
          <sbr>
1394
          <group>
1395
            <arg>--disk add:size=<replaceable>SIZE</replaceable></arg>
1396
            <arg>--disk remove</arg>
1397
            <arg>--disk <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></arg>
1398
          </group>
1399

    
1400
          <sbr>
1401
          <arg>-t<group choice="req">
1402
              <arg>plain</arg>
1403
              <arg>drbd</arg>
1404
            </group></arg>
1405

    
1406

    
1407
          <sbr>
1408
          <arg>--submit</arg>
1409
          <sbr>
1410
          <arg choice="req"><replaceable>instance</replaceable></arg>
1411
        </cmdsynopsis>
1412

    
1413
        <para>
1414
          Modifies the memory size, number of vcpus, ip address, MAC
1415
          address and/or nic parameters for an instance. It can also
1416
          add and remove disks and NICs to/from the instance. Note
1417
          that you need to give at least one of the arguments, otherwise
1418
          the command complains.
1419
        </para>
1420

    
1421
        <para>
1422
          The <option>-H</option> option specifies hypervisor options
1423
          in the form of <userinput>name=value[,...]</userinput>. For details which options can be specified, see the <command>add</command> command.
1424
        </para>
1425

    
1426
        <para>
1427
          The <option>-t</option> option will change the disk template
1428
          of the instance. Currently only conversions between the
1429
          plain and drbd disk templates are supported, and the
1430
          instance must be stopped before attempting the conversion.
1431
        </para>
1432

    
1433
        <para>
1434
          The <option>--disk
1435
          add:size=<replaceable>SIZE</replaceable></option> option
1436
          adds a disk to the instance. The <option>--disk
1437
          remove</option> will remove the last disk of the
1438
          instance. The <option>--disk
1439
          <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></option>
1440
          option will change the mode of the Nth disk of the instance
1441
          between read-only (<literal>ro</literal>) and read-write
1442
          (<literal>rw</literal>).
1443
        </para>
1444

    
1445
        <para>
1446
          The <option>--net
1447
          add:<replaceable>options</replaceable></option> option will
1448
          add a new NIC to the instance. The available options are the
1449
          same as in the <command>add</command> command (mac, ip, link,
1450
          mode). The <option>--net remove</option> will remove the
1451
          last NIC of the instance, while the <option>--net
1452
          <replaceable>N</replaceable>:<replaceable>options</replaceable></option>
1453
          option will change the parameters of the Nth instance NIC.
1454
        </para>
1455

    
1456
        <para>
1457
          The <option>--submit</option> option is used to send the job to
1458
          the master daemon but not wait for its completion. The job
1459
          ID will be shown so that it can be examined via
1460
          <command>gnt-job info</command>.
1461
        </para>
1462

    
1463
        <para>
1464
          All the changes take effect at the next restart. If the
1465
          instance is running, there is no effect on the instance.
1466
        </para>
1467
      </refsect3>
1468

    
1469
      <refsect3>
1470
        <title>REINSTALL</title>
1471

    
1472
        <cmdsynopsis>
1473
          <command>reinstall</command>
1474
          <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
1475
          <arg>--select-os</arg>
1476
          <arg choice="opt">-f <replaceable>force</replaceable></arg>
1477
          <arg>--force-multiple</arg>
1478
          <sbr>
1479
          <group choice="opt">
1480
            <arg>--instance</arg>
1481
            <arg>--node</arg>
1482
            <arg>--primary</arg>
1483
            <arg>--secondary</arg>
1484
            <arg>--all</arg>
1485
          </group>
1486
          <arg>--submit</arg>
1487
          <arg choice="opt" rep="repeat"><replaceable>instance</replaceable></arg>
1488
        </cmdsynopsis>
1489

    
1490
        <para>
1491
          Reinstalls the operating system on the given instance(s). The
1492
          instance(s) must be stopped when running this command. If the
1493
          <option>--os-type</option> is specified, the operating
1494
          system is changed.
1495
        </para>
1496

    
1497
        <para>
1498
          The <option>--select-os</option> option switches to an
1499
          interactive OS reinstall. The user is prompted to select the OS
1500
          template from the list of available OS templates.
1501
        </para>
1502

    
1503
        <para>
1504
          Since this is a potentially dangerous command, the user will
1505
          be required to confirm this action, unless the
1506
          <option>-f</option> flag is passed. When multiple instances
1507
          are selected (either by passing multiple arguments or by
1508
          using the <option>--node</option>,
1509
          <option>--primary</option>, <option>--secondary</option> or
1510
          <option>--all</option> options), the user must pass both the
1511
          <option>--force</option> and
1512
          <option>--force-multiple</option> options to skip the
1513
          interactive confirmation.
1514
        </para>
1515

    
1516
        <para>
1517
          The <option>--submit</option> option is used to send the job to
1518
          the master daemon but not wait for its completion. The job
1519
          ID will be shown so that it can be examined via
1520
          <command>gnt-job info</command>.
1521
        </para>
1522

    
1523

    
1524
      </refsect3>
1525

    
1526
      <refsect3>
1527
        <title>RENAME</title>
1528

    
1529
        <cmdsynopsis>
1530
          <command>rename</command>
1531
          <arg>--no-ip-check</arg>
1532
          <arg>--submit</arg>
1533
          <arg choice="req"><replaceable>instance</replaceable></arg>
1534
          <arg choice="req"><replaceable>new_name</replaceable></arg>
1535
        </cmdsynopsis>
1536

    
1537
        <para>
1538
          Renames the given instance. The instance must be stopped
1539
          when running this command. The requirements for the new name
1540
          are the same as for adding an instance: the new name must be
1541
          resolvable and the IP it resolves to must not be reachable
1542
          (in order to prevent duplicate IPs the next time the
1543
          instance is started). The IP test can be skipped if the
1544
          <option>--no-ip-check</option> option is passed.
1545
        </para>
1546

    
1547
        <para>
1548
          The <option>--submit</option> option is used to send the job to
1549
          the master daemon but not wait for its completion. The job
1550
          ID will be shown so that it can be examined via
1551
          <command>gnt-job info</command>.
1552
        </para>
1553

    
1554
      </refsect3>
1555

    
1556
    </refsect2>
1557

    
1558
    <refsect2>
1559
      <title>Starting/stopping/connecting to console</title>
1560

    
1561
      <refsect3>
1562
        <title>STARTUP</title>
1563

    
1564
        <cmdsynopsis>
1565
          <command>startup</command>
1566
          <sbr>
1567
          <arg>--force</arg>
1568
          <sbr>
1569
          <arg>--force-multiple</arg>
1570
          <sbr>
1571
          <group choice="opt">
1572
            <arg>--instance</arg>
1573
            <arg>--node</arg>
1574
            <arg>--primary</arg>
1575
            <arg>--secondary</arg>
1576
            <arg>--all</arg>
1577
            <arg>--tags</arg>
1578
            <arg>--node-tags</arg>
1579
            <arg>--pri-node-tags</arg>
1580
            <arg>--sec-node-tags</arg>
1581
          </group>
1582
          <sbr>
1583
          <arg>-H <option>key=value...</option></arg>
1584
          <arg>-B <option>key=value...</option></arg>
1585
          <sbr>
1586
          <arg>--submit</arg>
1587
          <sbr>
1588
          <arg choice="opt"
1589
          rep="repeat"><replaceable>name</replaceable></arg>
1590
        </cmdsynopsis>
1591

    
1592
        <para>
1593
          Starts one or more instances, depending on the following
1594
          options. The four available modes are:
1595
          <variablelist>
1596
            <varlistentry>
1597
              <term><option>--instance</option></term>
1598
              <listitem>
1599
                <simpara>will start the instances given as arguments
1600
                (at least one argument required); this is the default
1601
                selection</simpara>
1602
              </listitem>
1603
            </varlistentry>
1604
            <varlistentry>
1605
              <term>--node</term>
1606
              <listitem>
1607
                <simpara>will start the instances who have the given
1608
                node as either primary or secondary</simpara>
1609
              </listitem>
1610
            </varlistentry>
1611
            <varlistentry>
1612
              <term><option>--primary</option></term>
1613
              <listitem>
1614
                <simpara>will start all instances whose primary node
1615
                is in the list of nodes passed as arguments (at least
1616
                one node required)</simpara>
1617
              </listitem>
1618
            </varlistentry>
1619
            <varlistentry>
1620
              <term><option>--secondary</option></term>
1621
              <listitem>
1622
                <simpara>will start all instances whose secondary node
1623
                is in the list of nodes passed as arguments (at least
1624
                one node required)</simpara>
1625
              </listitem>
1626
            </varlistentry>
1627
            <varlistentry>
1628
              <term>--all</term>
1629
              <listitem>
1630
                <simpara>will start all instances in the cluster (no
1631
                arguments accepted)</simpara>
1632
              </listitem>
1633
            </varlistentry>
1634
            <varlistentry>
1635
              <term>--tags</term>
1636
              <listitem>
1637
                <simpara>will start all instances in the cluster with
1638
                the tags given as arguments</simpara>
1639
              </listitem>
1640
            </varlistentry>
1641
            <varlistentry>
1642
              <term>--node-tags</term>
1643
              <listitem>
1644
                <simpara>will start all instances in the cluster on
1645
                nodes with the tags given as arguments</simpara>
1646
              </listitem>
1647
            </varlistentry>
1648
            <varlistentry>
1649
              <term>--pri-node-tags</term>
1650
              <listitem>
1651
                <simpara>will start all instances in the cluster on
1652
                primary nodes with the tags given as
1653
                arguments</simpara>
1654
              </listitem>
1655
            </varlistentry>
1656
            <varlistentry>
1657
              <term>--sec-node-tags</term>
1658
              <listitem>
1659
                <simpara>will start all instances in the cluster on
1660
                secondary nodes with the tags given as
1661
                arguments</simpara>
1662
              </listitem>
1663
            </varlistentry>
1664
          </variablelist>
1665
        </para>
1666

    
1667
        <para>
1668
          Note that although you can pass more than one selection
1669
          option, the last one wins, so in order to guarantee the
1670
          desired result, don't pass more than one such option.
1671
        </para>
1672

    
1673
        <para>
1674
          Use <option>--force</option> to start even if secondary disks are
1675
          failing.
1676
        </para>
1677

    
1678
        <para>
1679
          The <option>--force-multiple</option> will skip the
1680
          interactive confirmation in the case the more than one
1681
          instance will be affected.
1682
        </para>
1683

    
1684
        <para>
1685
          The <option>-H</option> and <option>-B</option> options
1686
          specify temporary hypervisor and backend parameters that can
1687
          be used to start an instance with modified parameters. They
1688
          can be useful for quick testing without having to modify an
1689
          instance back and forth, e.g.:
1690
          <screen>
1691
# gnt-instance start -H root_args="single" instance1
1692
# gnt-instance start -B memory=2048 instance2
1693
          </screen>
1694
          The first form will start the instance
1695
          <userinput>instance1</userinput> in single-user mode, and
1696
          the instance <userinput>instance2</userinput> with 2GB of
1697
          RAM (this time only, unless that is the actual instance
1698
          memory size already). Note that the values override the
1699
          instance parameters (and not extend them): an instance with
1700
          "root_args=ro" when started with <userinput>-H
1701
          root_args=single</userinput> will result in "single", not
1702
          "ro single".
1703
        </para>
1704

    
1705
        <para>
1706
          The <option>--submit</option> option is used to send the job to
1707
          the master daemon but not wait for its completion. The job
1708
          ID will be shown so that it can be examined via
1709
          <command>gnt-job info</command>.
1710
        </para>
1711

    
1712
        <para>
1713
          Example:
1714
          <screen>
1715
# gnt-instance start instance1.example.com
1716
# gnt-instance start --node node1.example.com node2.example.com
1717
# gnt-instance start --all
1718
          </screen>
1719
        </para>
1720
      </refsect3>
1721

    
1722
      <refsect3>
1723
        <title>SHUTDOWN</title>
1724

    
1725
        <cmdsynopsis>
1726
          <command>shutdown</command>
1727
          <sbr>
1728
          <arg>--timeout=<replaceable>N</replaceable></arg>
1729
          <sbr>
1730
          <arg>--force-multiple</arg>
1731
          <sbr>
1732
          <group choice="opt">
1733
            <arg>--instance</arg>
1734
            <arg>--node</arg>
1735
            <arg>--primary</arg>
1736
            <arg>--secondary</arg>
1737
            <arg>--all</arg>
1738
            <arg>--tags</arg>
1739
            <arg>--node-tags</arg>
1740
            <arg>--pri-node-tags</arg>
1741
            <arg>--sec-node-tags</arg>
1742
          </group>
1743
          <sbr>
1744
          <arg>--submit</arg>
1745
          <sbr>
1746
          <arg choice="opt"
1747
          rep="repeat"><replaceable>name</replaceable></arg>
1748
        </cmdsynopsis>
1749

    
1750
        <para>
1751
          Stops one or more instances. If the instance cannot be
1752
          cleanly stopped during a hardcoded interval (currently 2
1753
          minutes), it will forcibly stop the instance (equivalent to
1754
          switching off the power on a physical machine).
1755
        </para>
1756

    
1757
        <para>
1758
          The <option>--timeout</option> is used to specify how much time to
1759
          wait before forcing the shutdown (xm destroy in xen, killing the kvm
1760
          process, for kvm). By default two minutes are given to each instance
1761
          to stop.
1762
        </para>
1763

    
1764
        <para>
1765
          The <option>--instance</option>, <option>--node</option>,
1766
          <option>--primary</option>, <option>--secondary</option>,
1767
          <option>--all</option>, <option>--tags</option>,
1768
          <option>--node-tags</option>, <option>--pri-node-tags</option> and
1769
          <option>--sec-node-tags</option> options are similar as for the
1770
          <command>startup</command> command and they influence the
1771
          actual instances being shutdown.
1772
        </para>
1773

    
1774
        <para>
1775
          The <option>--submit</option> option is used to send the job to
1776
          the master daemon but not wait for its completion. The job
1777
          ID will be shown so that it can be examined via
1778
          <command>gnt-job info</command>.
1779
        </para>
1780

    
1781

    
1782
        <para>
1783
          Example:
1784
          <screen>
1785
# gnt-instance shutdown instance1.example.com
1786
# gnt-instance shutdown --all
1787
          </screen>
1788
        </para>
1789
      </refsect3>
1790

    
1791
      <refsect3>
1792
        <title>REBOOT</title>
1793

    
1794
        <cmdsynopsis>
1795
          <command>reboot</command>
1796
          <sbr>
1797
          <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
1798
          <sbr>
1799
          <arg>--ignore-secondaries</arg>
1800
          <sbr>
1801
          <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
1802
          <sbr>
1803
          <arg>--force-multiple</arg>
1804
          <sbr>
1805
          <group choice="opt">
1806
            <arg>--instance</arg>
1807
            <arg>--node</arg>
1808
            <arg>--primary</arg>
1809
            <arg>--secondary</arg>
1810
            <arg>--all</arg>
1811
            <arg>--tags</arg>
1812
            <arg>--node-tags</arg>
1813
            <arg>--pri-node-tags</arg>
1814
            <arg>--sec-node-tags</arg>
1815
          </group>
1816
          <sbr>
1817
          <arg>--submit</arg>
1818
          <sbr>
1819
          <arg choice="opt"
1820
          rep="repeat"><replaceable>name</replaceable></arg>
1821
        </cmdsynopsis>
1822

    
1823
        <para>
1824
          Reboots one or more instances. The type of reboot depends on
1825
          the value of <option>--type</option>. A soft reboot does a
1826
          hypervisor reboot, a hard reboot does a instance stop,
1827
          recreates the hypervisor config for the instance and
1828
          starts the instance. A full reboot does the equivalent
1829
          of <command>gnt-instance shutdown &amp;&amp; gnt-instance
1830
          startup</command>. The default is hard reboot.
1831
        </para>
1832

    
1833
        <para>
1834
          For the hard reboot the option
1835
          <option>--ignore-secondaries</option> ignores errors for the
1836
          secondary node while re-assembling the instance disks.
1837
        </para>
1838

    
1839
        <para>
1840
          The <option>--instance</option>, <option>--node</option>,
1841
          <option>--primary</option>, <option>--secondary</option>,
1842
          <option>--all</option>, <option>--tags</option>,
1843
          <option>--node-tags</option>, <option>--pri-node-tags</option> and
1844
          <option>--sec-node-tags</option> options are similar as for the
1845
          <command>startup</command> command and they influence the
1846
          actual instances being rebooted.
1847
        </para>
1848

    
1849
        <para>
1850
          The <option>--shutdown-timeout</option> is used to specify how
1851
          much time to wait before forcing the shutdown (xm destroy in xen,
1852
          killing the kvm process, for kvm). By default two minutes are
1853
          given to each instance to stop.
1854
        </para>
1855

    
1856
        <para>
1857
          The <option>--force-multiple</option> will skip the
1858
          interactive confirmation in the case the more than one
1859
          instance will be affected.
1860
        </para>
1861

    
1862
        <para>
1863
          Example:
1864
          <screen>
1865
# gnt-instance reboot instance1.example.com
1866
# gnt-instance reboot --type=full instance1.example.com
1867
          </screen>
1868
        </para>
1869
      </refsect3>
1870

    
1871
      <refsect3>
1872
        <title>CONSOLE</title>
1873
        <cmdsynopsis>
1874
          <command>console</command>
1875
          <arg choice="opt">--show-cmd</arg>
1876
          <arg choice="req"><replaceable>instance</replaceable></arg>
1877
        </cmdsynopsis>
1878

    
1879
        <para>
1880
          Connects to the console of the given instance. If the
1881
          instance is not up, an error is returned. Use the
1882
          <option>--show-cmd</option> option to display the command
1883
          instead of executing it.
1884
        </para>
1885

    
1886
        <para>
1887
          For HVM instances, this will attempt to connect to the
1888
          serial console of the instance. To connect to the
1889
          virtualized "physical" console of a HVM instance, use a VNC
1890
          client with the connection info from the
1891
          <command>info</command> command.
1892
        </para>
1893

    
1894
        <para>
1895
          Example:
1896
          <screen>
1897
# gnt-instance console instance1.example.com
1898
          </screen>
1899
        </para>
1900
      </refsect3>
1901

    
1902
    </refsect2>
1903

    
1904
    <refsect2>
1905
      <title>Disk management</title>
1906

    
1907
      <refsect3>
1908
        <title>REPLACE-DISKS</title>
1909

    
1910
        <cmdsynopsis>
1911
          <command>replace-disks</command>
1912
          <arg>--submit</arg>
1913
          <arg>--early-release</arg>
1914
          <arg choice="req">-p</arg>
1915
          <arg>--disks <replaceable>idx</replaceable></arg>
1916
          <arg choice="req"><replaceable>instance</replaceable></arg>
1917
        </cmdsynopsis>
1918

    
1919
        <cmdsynopsis>
1920
          <command>replace-disks</command>
1921
          <arg>--submit</arg>
1922
          <arg>--early-release</arg>
1923
          <arg choice="req">-s</arg>
1924
          <arg>--disks <replaceable>idx</replaceable></arg>
1925
          <arg choice="req"><replaceable>instance</replaceable></arg>
1926
        </cmdsynopsis>
1927

    
1928
        <cmdsynopsis>
1929
          <command>replace-disks</command>
1930
          <arg>--submit</arg>
1931
          <arg>--early-release</arg>
1932
          <group choice="req">
1933
            <arg>--iallocator <replaceable>name</replaceable></arg>
1934
            <arg>--new-secondary <replaceable>NODE</replaceable></arg>
1935
          </group>
1936

    
1937
          <arg choice="req"><replaceable>instance</replaceable></arg>
1938
        </cmdsynopsis>
1939

    
1940
        <cmdsynopsis>
1941
          <command>replace-disks</command>
1942
          <arg>--submit</arg>
1943
          <arg>--early-release</arg>
1944
          <arg choice="req">--auto</arg>
1945
          <arg choice="req"><replaceable>instance</replaceable></arg>
1946
        </cmdsynopsis>
1947

    
1948
        <para>
1949
          This command is a generalized form for replacing disks. It
1950
          is currently only valid for the mirrored (DRBD) disk
1951
          template.
1952
        </para>
1953

    
1954
        <para>
1955
          The first form (when passing the <option>-p</option> option)
1956
          will replace the disks on the primary, while the second form
1957
          (when passing the <option>-s</option> option will replace
1958
          the disks on the secondary node. For these two cases (as the
1959
          node doesn't change), it is possible to only run the replace
1960
          for a subset of the disks, using the option
1961
          <option>--disks</option> which takes a list of
1962
          comma-delimited disk indices (zero-based),
1963
          e.g. <userinput>0,2</userinput> to replace only the first
1964
          and third disks.
1965
        </para>
1966

    
1967
        <para>
1968
          The third form (when passing either the
1969
          <option>--iallocator</option> or the
1970
          <option>--new-secondary</option> option) is designed to
1971
          change secondary node of the instance.  Specifying
1972
          <option>--iallocator</option> makes the new secondary be
1973
          selected automatically by the specified allocator plugin,
1974
          otherwise the new secondary node will be the one chosen
1975
          manually via the <option>--new-secondary</option> option.
1976
        </para>
1977

    
1978
        <para>
1979
          The fourth form (when using <option>--auto</option>) will
1980
          automatically determine which disks of an instance are faulty and
1981
          replace them within the same node. The <option>--auto</option>
1982
          option works only when an instance has only faulty disks on
1983
          either the primary or secondary node; it doesn't work when
1984
          both sides have faulty disks.
1985
        </para>
1986

    
1987
        <para>
1988
          The <option>--submit</option> option is used to send the job to
1989
          the master daemon but not wait for its completion. The job
1990
          ID will be shown so that it can be examined via
1991
          <command>gnt-job info</command>.
1992
        </para>
1993

    
1994
        <para>
1995
          The <option>--early-release</option> changes the code so
1996
          that the old storage on secondary node(s) is removed early
1997
          (before the resync is completed) and the internal Ganeti
1998
          locks for the current (and new, if any) secondary node are
1999
          also released, thus allowing more parallelism in the cluster
2000
          operation. This should be used only when recovering from a
2001
          disk failure on the current secondary (thus the old storage
2002
          is already broken) or when the storage on the primary node
2003
          is known to be fine (thus we won't need the old storage for
2004
          potential recovery).
2005
        </para>
2006

    
2007
        <para>
2008
          Note that it is not possible to select an offline or drained
2009
          node as a new secondary.
2010
        </para>
2011

    
2012
      </refsect3>
2013

    
2014
      <refsect3>
2015
        <title>ACTIVATE-DISKS</title>
2016

    
2017
        <cmdsynopsis>
2018
          <command>activate-disks</command>
2019
          <arg>--submit</arg>
2020
          <arg>--ignore-size</arg>
2021
          <arg choice="req"><replaceable>instance</replaceable></arg>
2022
        </cmdsynopsis>
2023
        <para>
2024
          Activates the block devices of the given instance. If
2025
          successful, the command will show the location and name of
2026
          the block devices:
2027
          <screen>
2028
node1.example.com:disk/0:/dev/drbd0
2029
node1.example.com:disk/1:/dev/drbd1
2030
          </screen>
2031

    
2032
          In this example, <emphasis>node1.example.com</emphasis> is
2033
          the name of the node on which the devices have been
2034
          activated. The <emphasis>disk/0</emphasis> and
2035
          <emphasis>disk/1</emphasis> are the Ganeti-names of the
2036
          instance disks; how they are visible inside the instance is
2037
          hypervisor-specific. <emphasis>/dev/drbd0</emphasis> and
2038
          <emphasis>/dev/drbd1</emphasis> are the actual block devices
2039
          as visible on the node.
2040
        </para>
2041

    
2042
        <para>
2043
          The <option>--submit</option> option is used to send the job to
2044
          the master daemon but not wait for its completion. The job
2045
          ID will be shown so that it can be examined via
2046
          <command>gnt-job info</command>.
2047
        </para>
2048

    
2049
        <para>
2050
          The <option>--ignore-size</option> option can be used to
2051
          activate disks ignoring the currently configured size in
2052
          Ganeti. This can be used in cases where the configuration
2053
          has gotten out of sync with the real-world (e.g. after a
2054
          partially-failed grow-disk operation or due to rounding in
2055
          LVM devices). This should not be used in normal cases, but
2056
          only when activate-disks fails without it.
2057
        </para>
2058

    
2059
        <para>
2060
          Note that it is safe to run this command while the instance
2061
          is already running.
2062
        </para>
2063
      </refsect3>
2064

    
2065
      <refsect3>
2066
        <title>DEACTIVATE-DISKS</title>
2067

    
2068
        <cmdsynopsis>
2069
          <command>deactivate-disks</command>
2070
          <arg>--submit</arg>
2071
          <arg choice="req"><replaceable>instance</replaceable></arg>
2072
        </cmdsynopsis>
2073
        <para>
2074
          De-activates the block devices of the given instance. Note
2075
          that if you run this command for an instance with a drbd
2076
          disk template, while it is running, it will not be able to
2077
          shutdown the block devices on the primary node, but it will
2078
          shutdown the block devices on the secondary nodes, thus
2079
          breaking the replication.
2080
        </para>
2081

    
2082
        <para>
2083
          The <option>--submit</option> option is used to send the job to
2084
          the master daemon but not wait for its completion. The job
2085
          ID will be shown so that it can be examined via
2086
          <command>gnt-job info</command>.
2087
        </para>
2088

    
2089
      </refsect3>
2090

    
2091
      <refsect3>
2092
        <title>GROW-DISK</title>
2093
        <cmdsynopsis>
2094
          <command>grow-disk</command>
2095
          <arg>--no-wait-for-sync</arg>
2096
          <arg>--submit</arg>
2097
          <arg choice="req"><replaceable>instance</replaceable></arg>
2098
          <arg choice="req"><replaceable>disk</replaceable></arg>
2099
          <arg choice="req"><replaceable>amount</replaceable></arg>
2100
        </cmdsynopsis>
2101

    
2102
        <para>
2103
          Grows an instance's disk. This is only possible for
2104
          instances having a <literal>plain</literal> or
2105
          <literal>drbd</literal> disk template.
2106
        </para>
2107

    
2108
        <para>
2109
          Note that this command only change the block device size; it
2110
          will not grow the actual filesystems, partitions, etc. that
2111
          live on that disk. Usually, you will need to:
2112
          <orderedlist>
2113
            <listitem>
2114
              <simpara>use <command>gnt-instance grow-disk</command></simpara>
2115
            </listitem>
2116
            <listitem>
2117
              <simpara>reboot the instance (later, at a convenient
2118
              time)</simpara>
2119
            </listitem>
2120
            <listitem>
2121
              <simpara>use a filesystem resizer, such as
2122
              <citerefentry> <refentrytitle>ext2online</refentrytitle>
2123
              <manvolnum>8</manvolnum> </citerefentry> or
2124
              <citerefentry> <refentrytitle>xfs_growfs</refentrytitle>
2125
              <manvolnum>8</manvolnum> </citerefentry> to resize the
2126
              filesystem, or use <citerefentry>
2127
              <refentrytitle>fdisk</refentrytitle>
2128
              <manvolnum>8</manvolnum> </citerefentry> to change the
2129
              partition table on the disk
2130
              </simpara>
2131
            </listitem>
2132
          </orderedlist>
2133
        </para>
2134

    
2135

    
2136
        <para>
2137
          The <replaceable>disk</replaceable> argument is the index of
2138
          the instance disk to grow. The
2139
          <replaceable>amount</replaceable> argument is given either
2140
          as a number (and it represents the amount to increase the
2141
          disk with in mebibytes) or can be given similar to the
2142
          arguments in the create instance operation, with a suffix
2143
          denoting the unit.
2144
        </para>
2145

    
2146
        <para>
2147
          Note that the disk grow operation might complete on one node
2148
          but fail on the other; this will leave the instance with
2149
          different-sized LVs on the two nodes, but this will not
2150
          create problems (except for unused space).
2151
        </para>
2152

    
2153
        <para>
2154
          If you do not want gnt-instance to wait for the new disk
2155
          region to be synced, use the
2156
          <option>--no-wait-for-sync</option> option.
2157
        </para>
2158

    
2159
        <para>
2160
          The <option>--submit</option> option is used to send the job to
2161
          the master daemon but not wait for its completion. The job
2162
          ID will be shown so that it can be examined via
2163
          <command>gnt-job info</command>.
2164
        </para>
2165

    
2166

    
2167
        <para>Example (increase the first disk for instance1 by 16GiB):
2168
          <screen>
2169
# gnt-instance grow-disk instance1.example.com 0 16g
2170
          </screen>
2171
        </para>
2172

    
2173
        <para>
2174
          Also note that disk shrinking is not supported; use
2175
          <command>gnt-backup export</command> and then
2176
          <command>gnt-backup import</command> to reduce the disk size
2177
          of an instance.
2178
        </para>
2179
      </refsect3>
2180

    
2181
      <refsect3>
2182
        <title>RECREATE-DISKS</title>
2183

    
2184
        <cmdsynopsis>
2185
          <command>recreate-disks</command>
2186
          <arg>--submit</arg>
2187
          <arg>--disks=<option>indices</option></arg>
2188
          <arg choice="req"><replaceable>instance</replaceable></arg>
2189
        </cmdsynopsis>
2190
        <para>
2191
          Recreates the disks of the given instance, or only a subset
2192
          of the disks (if the option <option>disks</option> is
2193
          passed, which must be a comma-separated list of disk
2194
          indices, starting from zero).
2195
        </para>
2196

    
2197
        <para>
2198
          Note that this functionality should only be used for missing
2199
          disks; if any of the given disks already exists, the
2200
          operation will fail. While this is suboptimal,
2201
          recreate-disks should hopefully not be needed in normal
2202
          operation and as such the impact of this is low.
2203
        </para>
2204

    
2205
        <para>
2206
          The <option>--submit</option> option is used to send the job to
2207
          the master daemon but not wait for its completion. The job
2208
          ID will be shown so that it can be examined via
2209
          <command>gnt-job info</command>.
2210
        </para>
2211

    
2212
      </refsect3>
2213

    
2214
    </refsect2>
2215

    
2216
    <refsect2>
2217
      <title>Recovery</title>
2218

    
2219
      <refsect3>
2220
        <title>FAILOVER</title>
2221

    
2222
        <cmdsynopsis>
2223
          <command>failover</command>
2224
          <arg>-f</arg>
2225
          <arg>--ignore-consistency</arg>
2226
          <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
2227
          <arg>--submit</arg>
2228
          <arg choice="req"><replaceable>instance</replaceable></arg>
2229
        </cmdsynopsis>
2230

    
2231
        <para>
2232
          Failover will fail the instance over its secondary
2233
          node. This works only for instances having a drbd disk
2234
          template.
2235
        </para>
2236

    
2237
        <para>
2238
          Normally the failover will check the consistency of the
2239
          disks before failing over the instance. If you are trying to
2240
          migrate instances off a dead node, this will fail. Use the
2241
          <option>--ignore-consistency</option> option for this
2242
          purpose. Note that this option can be dangerous as errors in
2243
          shutting down the instance will be ignored, resulting in
2244
          possibly having the instance running on two machines in
2245
          parallel (on disconnected DRBD drives).
2246
        </para>
2247

    
2248
        <para>
2249
          The <option>--shutdown-timeout</option> is used to specify how
2250
          much time to wait before forcing the shutdown (xm destroy in xen,
2251
          killing the kvm process, for kvm). By default two minutes are
2252
          given to each instance to stop.
2253
        </para>
2254

    
2255
        <para>
2256
          The <option>--submit</option> option is used to send the job to
2257
          the master daemon but not wait for its completion. The job
2258
          ID will be shown so that it can be examined via
2259
          <command>gnt-job info</command>.
2260
        </para>
2261

    
2262
        <para>
2263
          Example:
2264
          <screen>
2265
# gnt-instance failover instance1.example.com
2266
          </screen>
2267
        </para>
2268
      </refsect3>
2269

    
2270
      <refsect3>
2271
        <title>MIGRATE</title>
2272

    
2273
        <cmdsynopsis>
2274
          <command>migrate</command>
2275
          <arg>-f</arg>
2276
          <arg choice="req">--cleanup</arg>
2277
          <arg choice="req"><replaceable>instance</replaceable></arg>
2278
        </cmdsynopsis>
2279

    
2280
        <cmdsynopsis>
2281
          <command>migrate</command>
2282
          <arg>-f</arg>
2283
          <arg>--non-live</arg>
2284
          <arg choice="req"><replaceable>instance</replaceable></arg>
2285
        </cmdsynopsis>
2286

    
2287
        <para>
2288
          Migrate will move the instance to its secondary node without
2289
          shutdown. It only works for instances having the drbd8 disk
2290
          template type.
2291
        </para>
2292

    
2293
        <para>
2294
          The migration command needs a perfectly healthy instance, as
2295
          we rely on the dual-master capability of drbd8 and the disks
2296
          of the instance are not allowed to be degraded.
2297
        </para>
2298

    
2299
        <para>
2300
          The <option>--non-live</option> option will switch (for the
2301
          hypervisors that support it) between a "fully live"
2302
          (i.e. the interruption is as minimal as possible) migration
2303
          and one in which the instance is frozen, its state saved and
2304
          transported to the remote node, and then resumed there. This
2305
          all depends on the hypervisor support for two different
2306
          methods. In any case, it is not an error to pass this
2307
          parameter (it will just be ignored if the hypervisor doesn't
2308
          support it).
2309
        </para>
2310

    
2311
        <para>
2312
          If the <option>--cleanup</option> option is passed, the
2313
          operation changes from migration to attempting recovery from
2314
          a failed previous migration. In this mode, ganeti checks if
2315
          the instance runs on the correct node (and updates its
2316
          configuration if not) and ensures the instances's disks are
2317
          configured correctly. In this mode, the
2318
          <option>--non-live</option> option is ignored.
2319
        </para>
2320

    
2321
        <para>
2322
          The option <option>-f</option> will skip the prompting for
2323
          confirmation.
2324
        </para>
2325
        <para>
2326
          Example (and expected output):
2327
          <screen>
2328
# gnt-instance migrate instance1
2329
Migrate will happen to the instance instance1. Note that migration is
2330
**experimental** in this version. This might impact the instance if
2331
anything goes wrong. Continue?
2332
y/[n]/?: y
2333
* checking disk consistency between source and target
2334
* ensuring the target is in secondary mode
2335
* changing disks into dual-master mode
2336
 - INFO: Waiting for instance instance1 to sync disks.
2337
 - INFO: Instance instance1's disks are in sync.
2338
* migrating instance to node2.example.com
2339
* changing the instance's disks on source node to secondary
2340
 - INFO: Waiting for instance instance1 to sync disks.
2341
 - INFO: Instance instance1's disks are in sync.
2342
* changing the instance's disks to single-master
2343
#
2344
          </screen>
2345
        </para>
2346
      </refsect3>
2347

    
2348
      <refsect3>
2349
        <title>MOVE</title>
2350

    
2351
        <cmdsynopsis>
2352
          <command>move</command>
2353
          <arg>-f</arg>
2354
          <arg>-n <replaceable>node</replaceable></arg>
2355
          <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
2356
          <arg>--submit</arg>
2357
          <arg choice="req"><replaceable>instance</replaceable></arg>
2358
        </cmdsynopsis>
2359

    
2360
        <para>
2361
          Move will move the instance to an arbitrary node in the
2362
          cluster. This works only for instances having a plain or
2363
          file disk template.
2364
        </para>
2365

    
2366
        <para>
2367
          Note that since this operation is done via data copy, it
2368
          will take a long time for big disks (similar to
2369
          replace-disks for a drbd instance).
2370
        </para>
2371

    
2372
        <para>
2373
          The <option>--shutdown-timeout</option> is used to specify how
2374
          much time to wait before forcing the shutdown (xm destroy in xen,
2375
          killing the kvm process, for kvm). By default two minutes are
2376
          given to each instance to stop.
2377
        </para>
2378

    
2379
        <para>
2380
          The <option>--submit</option> option is used to send the job to
2381
          the master daemon but not wait for its completion. The job
2382
          ID will be shown so that it can be examined via
2383
          <command>gnt-job info</command>.
2384
        </para>
2385

    
2386
        <para>
2387
          Example:
2388
          <screen>
2389
# gnt-instance move -n node3.example.com instance1.example.com
2390
          </screen>
2391
        </para>
2392
      </refsect3>
2393

    
2394
    </refsect2>
2395

    
2396
    <refsect2>
2397
      <title>TAGS</title>
2398

    
2399
    <refsect3>
2400
        <title>ADD-TAGS</title>
2401

    
2402
        <cmdsynopsis>
2403
          <command>add-tags</command>
2404
          <arg choice="opt">--from <replaceable>file</replaceable></arg>
2405
          <arg choice="req"><replaceable>instancename</replaceable></arg>
2406
          <arg choice="req"
2407
            rep="repeat"><replaceable>tag</replaceable></arg>
2408
        </cmdsynopsis>
2409

    
2410
        <para>
2411
          Add tags to the given instance. If any of the tags contains
2412
          invalid characters, the entire operation will abort.
2413
        </para>
2414
        <para>
2415
          If the <option>--from</option> option is given, the list of
2416
          tags will be extended with the contents of that file (each
2417
          line becomes a tag). In this case, there is not need to pass
2418
          tags on the command line (if you do, both sources will be
2419
          used). A file name of - will be interpreted as stdin.
2420
        </para>
2421
      </refsect3>
2422

    
2423
      <refsect3>
2424
        <title>LIST-TAGS</title>
2425

    
2426
        <cmdsynopsis>
2427
          <command>list-tags</command>
2428
          <arg choice="req"><replaceable>instancename</replaceable></arg>
2429
        </cmdsynopsis>
2430

    
2431
        <para>List the tags of the given instance.</para>
2432
      </refsect3>
2433

    
2434
      <refsect3>
2435
        <title>REMOVE-TAGS</title>
2436
        <cmdsynopsis>
2437
          <command>remove-tags</command>
2438
          <arg choice="opt">--from <replaceable>file</replaceable></arg>
2439
          <arg choice="req"><replaceable>instancename</replaceable></arg>
2440
          <arg choice="req"
2441
            rep="repeat"><replaceable>tag</replaceable></arg>
2442
        </cmdsynopsis>
2443

    
2444
        <para>
2445
          Remove tags from the given instance. If any of the tags are
2446
          not existing on the node, the entire operation will abort.
2447
        </para>
2448

    
2449
        <para>
2450
          If the <option>--from</option> option is given, the list of
2451
          tags will be extended with the contents of that file (each
2452
          line becomes a tag). In this case, there is not need to pass
2453
          tags on the command line (if you do, both sources will be
2454
          used). A file name of - will be interpreted as stdin.
2455
        </para>
2456
      </refsect3>
2457

    
2458
    </refsect2>
2459

    
2460
  </refsect1>
2461

    
2462
  &footer;
2463

    
2464
</refentry>
2465

    
2466
<!-- Keep this comment at the end of the file
2467
Local variables:
2468
mode: sgml
2469
sgml-omittag:t
2470
sgml-shorttag:t
2471
sgml-minimize-attributes:nil
2472
sgml-always-quote-attributes:t
2473
sgml-indent-step:2
2474
sgml-indent-data:t
2475
sgml-parent-document:nil
2476
sgml-default-dtd-file:nil
2477
sgml-exposed-tags:nil
2478
sgml-local-catalogs:nil
2479
sgml-local-ecat-files:nil
2480
End:
2481
-->