Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.sgml @ 07813a9e

History | View | Annotate | Download (69.6 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>February 11, 2009</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
      <holder>Google Inc.</holder>
26
    </copyright>
27
    &dhdate;
28
  </refentryinfo>
29
  <refmeta>
30
    &dhucpackage;
31

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

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

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

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

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

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

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

    
76
          <group choice="req">
77
            <arg rep="repeat">--disk=<replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
78
            <arg>-s <replaceable>SIZE</replaceable></arg>
79
          </group>
80
          <sbr>
81
          <group>
82
            <arg rep="repeat">--net=<replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>
83
            <arg>--no-nics</arg>
84
          </group>
85
          <sbr>
86
          <arg>-B <replaceable>BEPARAMS</replaceable></arg>
87
          <sbr>
88

    
89
          <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>
90
          <sbr>
91

    
92
          <arg>--file-storage-dir <replaceable>dir_path</replaceable></arg>
93
          <arg>--file-driver<group choice="req">
94
              <arg>loop</arg>
95
              <arg>blktap</arg>
96
            </group></arg>
97
          <sbr>
98

    
99
          <group choice="req">
100
            <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
101
            <arg>--iallocator <replaceable>name</replaceable></arg>
102
          </group>
103
          <sbr>
104

    
105
          <arg choice="req">-o <replaceable>os-type</replaceable></arg>
106
          <sbr>
107
          <arg>--submit</arg>
108
          <sbr>
109

    
110
          <arg choice="req"><replaceable>instance</replaceable></arg>
111
        </cmdsynopsis>
112

    
113
        <para>
114
          Creates a new instance on the specified host. The
115
          <replaceable>instance</replaceable> argument must be in DNS,
116
          but depending on the bridge setup, need not be in the same
117
          network as the nodes in the cluster.
118
        </para>
119

    
120
        <para>
121
          The <option>disk</option> option specifies the parameters
122
          for the disks of the instance. The numbering of disks starts
123
          at zero, and at least one disk needs to be passed. For each
124
          disk, at least the size needs to be given, and optionally
125
          the access mode (read-only or the default of read-write) can
126
          also be specified.  The size is interpreted (when no unit is
127
          given) in mebibytes. You can also use one of the suffixes
128
          <literal>m</literal>, <literal>g</literal> or
129
          <literal>t</literal> to specificy the exact the units used;
130
          these suffixes map to mebibytes, gibibytes and tebibytes.
131
        </para>
132

    
133
        <para>
134
          Alternatively, a single-disk instance can be created via the
135
          <option>-s</option> option which takes a single argument,
136
          the size of the disk. This is similar to the Ganeti 1.2
137
          version (but will only create one disk).
138
        </para>
139

    
140
        <para>
141
          The minimum disk specification is therefore
142
          <userinput>--disk 0:size=20G</userinput> (or <userinput>-s
143
          20G</userinput> when using the <option>-s</option> option),
144
          and a three-disk instance can be specified as
145
          <userinput>--disk 0:size=20G --disk 1:size=4G --disk
146
          2:size=100G</userinput>.
147
        </para>
148

    
149
        <para>
150
          The NICs of the instances can be specified via the
151
          <option>--nic</option> option. By default, one NIC is
152
          created for the instance, with a random MAC, and connected
153
          to the default bridge. Each NIC can take up to three
154
          parameters (all optional):
155
          <variablelist>
156
            <varlistentry>
157
              <term>mac</term>
158
              <listitem>
159
                <simpara>either a value or <constant>GENERATE</constant>
160
                  to generate a new unique MAC</simpara>
161
              </listitem>
162
            </varlistentry>
163
            <varlistentry>
164
              <term>ip</term>
165
              <listitem>
166
                <simpara>specifies the IP address assigned to the
167
                  instance from the Ganeti side (this is not necessarily
168
                  what the instance will use, but what the node expects
169
                  the instance to use)</simpara>
170
              </listitem>
171
            </varlistentry>
172
            <varlistentry>
173
              <term>bridge</term>
174
              <listitem>
175
                <simpara>specifies the bridge to attach this NIC
176
                  to</simpara>
177
              </listitem>
178
            </varlistentry>
179
          </variablelist>
180
        </para>
181

    
182
        <para>
183
          Alternatively, if no network is desired for the instance, you
184
          can prevent the default of one NIC with the
185
          <option>--no-nics</option> option.
186
        </para>
187

    
188
        <para>
189
          The <option>-o</option> options specifies the operating
190
          system to be installed. The available operating systems can
191
          be listed with <command>gnt-os list</command>.
192
        </para>
193

    
194
        <para>
195
          The <option>-B</option> option specifies the backend
196
          parameters for the instance. If no such parameters are
197
          specified, the values are inherited from the cluster. Possible
198
          parameters are:
199
          <variablelist>
200
            <varlistentry>
201
              <term>memory</term>
202
              <listitem>
203
                <simpara>the memory size of the instance; as usual,
204
                  suffixes can be used to denote the unit, otherwise the
205
                  value is taken in mebibites</simpara>
206
              </listitem>
207
            </varlistentry>
208
            <varlistentry>
209
              <term>vcpus</term>
210
              <listitem>
211
                <simpara>the number of VCPUs to assign to the instance
212
                  (if this value makes sense for the hypervisor)</simpara>
213
              </listitem>
214
            </varlistentry>
215
            <varlistentry>
216
              <term>auto_balance</term>
217
              <listitem>
218
                <simpara>whether the instance is considered in the N+1
219
                  cluster checks (enough redundancy in the cluster to
220
                  survive a node failure)</simpara>
221
              </listitem>
222
            </varlistentry>
223
          </variablelist>
224
        </para>
225

    
226
        <para>
227
          The <option>-H</option> option specified the hypervisor to
228
          use for the instance (must be one of the enabled hypervisors
229
          on the cluster) and optionally custom parameters for this
230
          instance. If not other options are used (i.e. the invocation
231
          is just <userinput>-H
232
          <replaceable>NAME</replaceable></userinput>) the instance
233
          will inherit the cluster options. The defaults below show
234
          the cluster defaults at cluster creation time.
235
        </para>
236

    
237
        <para>
238
          The possible hypervisor options are as follows:
239
          <variablelist>
240
            <varlistentry>
241
              <term>boot_order</term>
242
              <listitem>
243
                <simpara>Valid for the Xen HVM and KVM
244
                hypervisors.</simpara>
245

    
246
                <simpara>A string value denoting the boot order. This
247
                has different meaning for the Xen HVM hypervisor and
248
                for the KVM one.</simpara>
249

    
250
                <simpara>
251
                  For Xen HVM, The boot order is a string of letters
252
                  listing the boot devices, with valid device letters
253
                  being:
254
                </simpara>
255
                  <variablelist>
256
                    <varlistentry>
257
                      <term>a</term>
258
                      <listitem>
259
                        <para>
260
                          floppy drive
261
                        </para>
262
                      </listitem>
263
                    </varlistentry>
264
                    <varlistentry>
265
                      <term>c</term>
266
                      <listitem>
267
                        <para>
268
                          hard disk
269
                        </para>
270
                      </listitem>
271
                    </varlistentry>
272
                    <varlistentry>
273
                      <term>d</term>
274
                      <listitem>
275
                        <para>
276
                          CDROM drive
277
                        </para>
278
                      </listitem>
279
                    </varlistentry>
280
                    <varlistentry>
281
                      <term>n</term>
282
                      <listitem>
283
                        <para>
284
                          network boot (PXE)
285
                        </para>
286
                      </listitem>
287
                    </varlistentry>
288
                  </variablelist>
289
                <simpara>
290
                  The default is not to set an HVM boot order which is
291
                  interpreted as 'dc'.
292
                </simpara>
293

    
294
              </listitem>
295
            </varlistentry>
296
            <varlistentry>
297
              <term>cdrom_image_path</term>
298
              <listitem>
299
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
300

    
301
                <simpara>The path to a CDROM image to attach to the
302
                instance.</simpara>
303

    
304
              </listitem>
305
            </varlistentry>
306
            <varlistentry>
307
              <term>nic_type</term>
308
              <listitem>
309
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
310

    
311
                <para>
312
                  This parameter determines the way the network cards
313
                  are presented to the instance. The possible options are:
314
                  <simplelist>
315
                    <member>rtl8139 (default for Xen HVM) (HVM & KVM)</member>
316
                    <member>ne2k_isa (HVM & KVM)</member>
317
                    <member>ne2k_pci (HVM & KVM)</member>
318
                    <member>i82551 (KVM)</member>
319
                    <member>i82557b (KVM)</member>
320
                    <member>i82559er (KVM)</member>
321
                    <member>pcnet (KVM)</member>
322
                    <member>e1000 (KVM)</member>
323
                    <member>paravirtual (default for KVM) (HVM & KVM)</member>
324
                  </simplelist>
325
                </para>
326
              </listitem>
327
            </varlistentry>
328
            <varlistentry>
329
              <term>disk_type</term>
330
              <listitem>
331
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
332

    
333
                <para>
334
                  This parameter determines the way the disks are
335
                  presented to the instance. The possible options are:
336
                  <simplelist>
337
                    <member>ioemu (default for HVM & KVM) (HVM & KVM)</member>
338
                    <member>ide (HVM & KVM)</member>
339
                    <member>scsi (KVM)</member>
340
                    <member>sd (KVM)</member>
341
                    <member>mtd (KVM)</member>
342
                    <member>pflash (KVM)</member>
343
                  </simplelist>
344
                </para>
345
              </listitem>
346
            </varlistentry>
347
            <varlistentry>
348
              <term>vnc_bind_address</term>
349
              <listitem>
350
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
351

    
352
                <para>Specifies the address that the VNC listener for
353
                this instance should bind to. Valid values are IPv4
354
                addresses. Use the address 0.0.0.0 to bind to all
355
                available interfaces (this is the default) or specify
356
                the address of one of the interfaces on the node to
357
                restrict listening to that interface.</para>
358
              </listitem>
359
            </varlistentry>
360

    
361
            <varlistentry>
362
              <term>vnc_tls</term>
363
              <listitem>
364
                <simpara>Valid for the KVM hypervisor.</simpara>
365

    
366
                <simpara>A boolean option that controls whether the
367
                VNC connection is secured with TLS.</simpara>
368
              </listitem>
369
            </varlistentry>
370

    
371
            <varlistentry>
372
              <term>vnc_x509_path</term>
373
              <listitem>
374
                <simpara>Valid for the KVM hypervisor.</simpara>
375

    
376
                <para>If <option>vnc_tls</option> is enabled, this
377
                options specifies the path to the x509 certificate to
378
                use.</para>
379
              </listitem>
380
            </varlistentry>
381

    
382
            <varlistentry>
383
              <term>vnc_x509_verify</term>
384
              <listitem>
385
                <simpara>Valid for the KVM hypervisor.</simpara>
386
              </listitem>
387
            </varlistentry>
388

    
389
            <varlistentry>
390
              <term>acpi</term>
391
              <listitem>
392
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
393

    
394
                <para>
395
                  A boolean option that specifies if the hypervisor
396
                  should enable ACPI support for this instance. By
397
                  default, ACPI is disabled.
398
                </para>
399
              </listitem>
400
            </varlistentry>
401

    
402
            <varlistentry>
403
              <term>pae</term>
404
              <listitem>
405
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
406

    
407
                <para>
408
                  A boolean option that specifies if the hypervisor
409
                  should enabled PAE support for this instance. The
410
                  default is false, disabling PAE support.
411
                </para>
412
              </listitem>
413
            </varlistentry>
414

    
415
            <varlistentry>
416
              <term>kernel_path</term>
417
              <listitem>
418
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
419

    
420
                <para>
421
                  This option specifies the path (on the node) to the
422
                  kernel to boot the instance with. Xen PVM instances
423
                  always require this, while for KVM if this option is
424
                  empty, it will cause the machine to load the kernel
425
                  from its disks.
426
                </para>
427
              </listitem>
428
            </varlistentry>
429

    
430
            <varlistentry>
431
              <term>kernel_args</term>
432
              <listitem>
433
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
434

    
435
                <para>
436
                  This options specifies extra arguments to the kernel
437
                  that will be loaded.  device. This is always used
438
                  for Xen PVM, while for KVM it is only used if the
439
                  <option>kernel_path</option> option is also
440
                  specified.
441
                </para>
442

    
443
                <para>
444
                  The default setting for this value is simply
445
                  <constant>"ro"</constant>, which mounts the root
446
                  disk (initially) in read-only one. For example,
447
                  setting this to <userinput>single</userinput> will
448
                  cause the instance to start in single-user mode.
449
                </para>
450
              </listitem>
451
            </varlistentry>
452

    
453
            <varlistentry>
454
              <term>initrd_path</term>
455
              <listitem>
456
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
457

    
458
                <para>
459
                  This option specifies the path (on the node) to the
460
                  initrd to boot the instance with. Xen PVM instances
461
                  can use this always, while for KVM if this option is
462
                  only used if the <option>kernel_path</option> option
463
                  is also specified.
464
                </para>
465
              </listitem>
466
            </varlistentry>
467

    
468
            <varlistentry>
469
              <term>root_path</term>
470
              <listitem>
471
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
472

    
473
                <para>
474
                  This options specifies the name of the root
475
                  device. This is always needed for Xen PVM, while for
476
                  KVM it is only used if the
477
                  <option>kernel_path</option> option is also
478
                  specified.
479
                </para>
480
              </listitem>
481
            </varlistentry>
482

    
483
            <varlistentry>
484
              <term>serial_console</term>
485
              <listitem>
486
                <simpara>Valid for the KVM hypervisor.</simpara>
487

    
488
                <simpara>This boolean option specifies whether to
489
                emulate a serial console for the instance.</simpara>
490
              </listitem>
491
            </varlistentry>
492
          </variablelist>
493
        </para>
494

    
495
        <para>
496
        </para>
497

    
498
        <para>
499
          The <option>--iallocator</option> option specifies the instance
500
          allocator plugin to use. If you pass in this option the allocator
501
          will select nodes for this instance automatically, so you don't need
502
          to pass them with the <option>-n</option> option. For more
503
          information please refer to the instance allocator documentation.
504
        </para>
505

    
506
        <para>
507
          The <option>-t</option> options specifies the disk layout type for
508
          the instance. The available choices are:
509
          <variablelist>
510
            <varlistentry>
511
              <term>diskless</term>
512
              <listitem>
513
                <para>
514
                  This creates an instance with no disks. Its useful for
515
                  testing only (or other special cases).
516
                </para>
517
              </listitem>
518
            </varlistentry>
519
            <varlistentry>
520
              <term>file</term>
521
              <listitem>
522
                <para>Disk devices will be regular files.</para>
523
              </listitem>
524
            </varlistentry>
525
            <varlistentry>
526
              <term>plain</term>
527
              <listitem>
528
                <para>Disk devices will be logical volumes.</para>
529
              </listitem>
530
            </varlistentry>
531
            <varlistentry>
532
              <term>drbd</term>
533
              <listitem>
534
                <para>
535
                  Disk devices will be drbd (version 8.x) on top of
536
                  lvm volumes.
537
                </para>
538
              </listitem>
539
            </varlistentry>
540
          </variablelist>
541
        </para>
542

    
543
        <para>
544
          The optional second value of the <option>--node</option> is used for
545
          the drbd template type and specifies the remote node.
546
        </para>
547

    
548
        <para>
549
          If you do not want gnt-instance to wait for the disk mirror
550
          to be synced, use the <option>--no-wait-for-sync</option>
551
          option.
552
        </para>
553

    
554
        <para>
555
          The <option>--file-storage-dir</option> specifies the relative path
556
          under the cluster-wide file storage directory to store file-based
557
          disks. It is useful for having different subdirectories for
558
          different instances. The full path of the directory where the disk
559
          files are stored will consist of cluster-wide file storage directory
560
          + optional subdirectory + instance name. Example:
561
          /srv/ganeti/file-storage/mysubdir/instance1.example.com. This option
562
          is only relevant for instances using the file storage backend.
563
        </para>
564

    
565
        <para>
566
          The <option>--file-driver</option> specifies the driver to use for
567
          file-based disks. Note that currently these drivers work with the
568
          xen hypervisor only. This option is only relevant for instances using
569
          the file storage backend. The available choices are:
570
          <variablelist>
571
            <varlistentry>
572
              <term>loop</term>
573
              <listitem>
574
                <para>
575
                  Kernel loopback driver. This driver uses loopback
576
                  devices to access the filesystem within the
577
                  file. However, running I/O intensive applications in
578
                  your instance using the loop driver might result in
579
                  slowdowns.  Furthermore, if you use the loopback
580
                  driver consider increasing the maximum amount of
581
                  loopback devices (on most systems it's 8) using the
582
                  max_loop param.
583
                </para>
584
              </listitem>
585
            </varlistentry>
586
            <varlistentry>
587
              <term>blktap</term>
588
              <listitem>
589
                <para>The blktap driver (for Xen hypervisors). In
590
                order to be able to use the blktap driver you should
591
                check if the 'blktapctrl' user space disk agent is
592
                running (usually automatically started via xend). This
593
                user-level disk I/O interface has the advantage of
594
                better performance. Especially if you use a network
595
                file system (e.g. NFS) to store your instances this is
596
                the recommended choice.
597
                </para>
598
              </listitem>
599
            </varlistentry>
600
          </variablelist>
601
        </para>
602

    
603
        <para>
604
          The <option>--submit</option> option is used to send the job to
605
          the master daemon but not wait for its completion. The job
606
          ID will be shown so that it can be examined via
607
          <command>gnt-job info</command>.
608
        </para>
609

    
610
        <para>
611
          Example:
612
          <screen>
613
# gnt-instance add -t file --disk 0:size=30g -B memory=512 -o debian-etch \
614
  -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
615
# gnt-instance add -t plain --disk 0:size=30g -B memory=512 -o debian-etch \
616
  -n node1.example.com instance1.example.com
617
# gnt-instance add -t drbd --disk 0:size=30g -B memory=512 -o debian-etch \
618
  -n node1.example.com:node2.example.com instance2.example.com
619
          </screen>
620
        </para>
621
      </refsect3>
622

    
623
      <refsect3>
624
        <title>BATCH-CREATE</title>
625
        <cmdsynopsis>
626
          <command>batch-create</command>
627
          <arg choice="req">instances_file.json</arg>
628
        </cmdsynopsis>
629

    
630
        <para>
631
          This command (similar to the Ganeti 1.2
632
          <command>batcher</command> tool) submits multiple instance
633
          creation jobs based on a definition file. The instance
634
          configurations do not encompass all the possible options for
635
          the <command>add</command> command, but only a subset.
636
        </para>
637

    
638
        <para>
639
          The instance file should be a valid-formed JSON file,
640
          containing a dictionary with instance name and instance
641
          parameters. The accepted parameters are:
642

    
643
          <variablelist>
644
            <varlistentry>
645
              <term>disk_size</term>
646
              <listitem>
647
                <simpara>The size of the disks of the instance.</simpara>
648
              </listitem>
649
            </varlistentry>
650
            <varlistentry>
651
              <term>disk_templace</term>
652
              <listitem>
653
                <simpara>The disk template to use for the instance,
654
                the same as in the <command>add</command>
655
                command.</simpara>
656
              </listitem>
657
            </varlistentry>
658
            <varlistentry>
659
              <term>backend</term>
660
              <listitem>
661
                <simpara>A dictionary of backend parameters.</simpara>
662
              </listitem>
663
            </varlistentry>
664
            <varlistentry>
665
              <term>hypervisor</term>
666
              <listitem>
667
                <simpara>A dictionary with a single key (the
668
                hypervisor name), and as value the hypervisor
669
                options. If not passed, the default hypervisor and
670
                hypervisor options will be inherited.</simpara>
671
              </listitem>
672
            </varlistentry>
673
            <varlistentry>
674
              <term>mac, ip, bridge</term>
675
              <listitem>
676
                <simpara>Specifications for the one NIC that will be
677
                created for the instance.</simpara>
678
              </listitem>
679
            </varlistentry>
680
            <varlistentry>
681
              <term>primary_node, secondary_node</term>
682
              <listitem>
683
                <simpara>The primary and optionally the secondary node
684
                to use for the instance (in case an iallocator script
685
                is not used).</simpara>
686
              </listitem>
687
            </varlistentry>
688
            <varlistentry>
689
              <term>iallocator</term>
690
              <listitem>
691
                <simpara>Instead of specifying the nodes, an
692
                iallocator script can be used to automatically compute
693
                them.</simpara>
694
              </listitem>
695
            </varlistentry>
696
            <varlistentry>
697
              <term>start</term>
698
              <listitem>
699
                <simpara>whether to start the instance</simpara>
700
              </listitem>
701
            </varlistentry>
702
            <varlistentry>
703
              <term>ip_check</term>
704
              <listitem>
705
                <simpara>Skip the check for already-in-use instance;
706
                see the description in the <command>add</command>
707
                command for details.</simpara>
708
              </listitem>
709
            </varlistentry>
710
            <varlistentry>
711
              <term>file_storage_dir, file_driver</term>
712
              <listitem>
713
                <simpara>Configuration for the <literal>file</literal>
714
                disk type, see the <command>add</command> command for
715
                details.</simpara>
716
              </listitem>
717
            </varlistentry>
718
          </variablelist>
719
        </para>
720

    
721
        <para>
722
          A simple definition for one instance can be (with most of
723
          the parameters taken from the cluster defaults):
724
          <screen>
725
{
726
  "instance3": {
727
    "template": "drbd",
728
    "os": "debootstrap",
729
    "disk_size": ["25G"],
730
    "iallocator": "dumb"
731
  },
732
  "instance5": {
733
    "template": "drbd",
734
    "os": "debootstrap",
735
    "disk_size": ["25G"],
736
    "iallocator": "dumb",
737
    "hypervisor": "xen-hvm",
738
    "hvparams": {"acpi": true},
739
    "backend": {"memory": 512}
740
  }
741
}
742
</screen>
743
        </para>
744

    
745
        <para>
746
          The command will display the job id for each submitted instance, as follows:
747
          <screen>
748
# gnt-instance batch-create instances.json
749
instance3: 11224
750
instance5: 11225
751
</screen>
752
        </para>
753

    
754
      </refsect3>
755

    
756
      <refsect3>
757
        <title>REMOVE</title>
758

    
759
        <cmdsynopsis>
760
          <command>remove</command>
761
          <arg>--ignore-failures</arg>
762
          <arg>--submit</arg>
763
          <arg choice="req"><replaceable>instance</replaceable></arg>
764
        </cmdsynopsis>
765

    
766
        <para>
767
          Remove an instance. This will remove all data from the
768
          instance and there is <emphasis>no way back</emphasis>. If
769
          you are not sure if you use an instance again, use
770
          <command>shutdown</command> first and leave it in the
771
          shutdown state for a while.
772

    
773
        </para>
774

    
775
        <para>
776
          The <option>--ignore-failures</option> option will cause the
777
          removal to proceed even in the presence of errors during the
778
          removal of the instance (e.g. during the shutdown or the
779
          disk removal). If this option is not given, the command will
780
          stop at the first error.
781
        </para>
782

    
783
        <para>
784
          The <option>--submit</option> option is used to send the job to
785
          the master daemon but not wait for its completion. The job
786
          ID will be shown so that it can be examined via
787
          <command>gnt-job info</command>.
788
        </para>
789

    
790
        <para>
791
          Example:
792
          <screen>
793
# gnt-instance remove instance1.example.com
794
          </screen>
795
        </para>
796
      </refsect3>
797

    
798
      <refsect3>
799
        <title>LIST</title>
800

    
801
        <cmdsynopsis>
802
          <command>list</command>
803
          <arg>--no-headers</arg>
804
          <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
805
          <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
806
          <arg rep="repeat">instance</arg>
807
        </cmdsynopsis>
808

    
809
        <para>
810
          Shows the currently configured instances with memory usage,
811
          disk usage, the node they are running on, and their run
812
          status.
813
        </para>
814

    
815
        <para>
816
          The <option>--no-headers</option> option will skip the
817
          initial header line. The <option>--separator</option> option
818
          takes an argument which denotes what will be used between
819
          the output fields. Both these options are to help scripting.
820
        </para>
821

    
822
        <para>
823
          The <option>-o</option> option takes a comma-separated list
824
          of output fields. The available fields and their meaning
825
          are:
826
          <variablelist>
827
            <varlistentry>
828
              <term>name</term>
829
              <listitem>
830
                <simpara>the instance name</simpara>
831
              </listitem>
832
            </varlistentry>
833
            <varlistentry>
834
              <term>os</term>
835
              <listitem>
836
                <simpara>the OS of the instance</simpara>
837
              </listitem>
838
            </varlistentry>
839
            <varlistentry>
840
              <term>pnode</term>
841
              <listitem>
842
                <simpara>the primary node of the instance</simpara>
843
              </listitem>
844
            </varlistentry>
845
            <varlistentry>
846
              <term>snodes</term>
847
              <listitem>
848
                <simpara>comma-separated list of secondary nodes for the
849
                  instance; usually this will be just one node</simpara>
850
              </listitem>
851
            </varlistentry>
852
            <varlistentry>
853
              <term>admin_state</term>
854
              <listitem>
855
                <simpara>the desired state of the instance (either "yes"
856
                  or "no" denoting the instance should run or
857
                  not)</simpara>
858
              </listitem>
859
            </varlistentry>
860
            <varlistentry>
861
              <term>disk_template</term>
862
              <listitem>
863
                <simpara>the disk template of the instance</simpara>
864
              </listitem>
865
            </varlistentry>
866
            <varlistentry>
867
              <term>oper_state</term>
868
              <listitem>
869
                <simpara>the actual state of the instance; can be
870
                one of the values "running", "stopped", "(node
871
                down)"</simpara>
872
              </listitem>
873
            </varlistentry>
874
            <varlistentry>
875
              <term>status</term>
876
              <listitem>
877
                <simpara>combined form of admin_state and oper_stat;
878
                this can be one of:
879
                <computeroutput>ERROR_nodedown</computeroutput> if the
880
                node of the instance is down,
881
                <computeroutput>ERROR_down</computeroutput> if the
882
                instance should run but is down,
883
                <computeroutput>ERROR_up</computeroutput> if the
884
                instance should be stopped but is actually running,
885
                <computeroutput>ADMIN_down</computeroutput> if the
886
                instance has been stopped (and is stopped) and
887
                <computeroutput>running</computeroutput> if the
888
                instance is set to be running (and is
889
                running)</simpara>
890
              </listitem>
891
            </varlistentry>
892
            <varlistentry>
893
              <term>oper_ram</term>
894
              <listitem>
895
                <simpara>the actual memory usage of the instance as seen
896
                  by the hypervisor</simpara>
897
              </listitem>
898
            </varlistentry>
899
            <varlistentry>
900
              <term>ip</term>
901
              <listitem>
902
                <simpara>the ip address ganeti recognizes as associated with
903
                the first instance interface</simpara>
904
              </listitem>
905
            </varlistentry>
906
            <varlistentry>
907
              <term>mac</term>
908
              <listitem>
909
                <simpara>the first instance interface MAC address</simpara>
910
              </listitem>
911
            </varlistentry>
912
            <varlistentry>
913
              <term>bridge</term>
914
              <listitem>
915
                <simpara>the bridge of the first instance NIC
916
                </simpara>
917
              </listitem>
918
            </varlistentry>
919
            <varlistentry>
920
              <term>sda_size</term>
921
              <listitem>
922
                <simpara>the size of the instance's first disk</simpara>
923
              </listitem>
924
            </varlistentry>
925
            <varlistentry>
926
              <term>sdb_size</term>
927
              <listitem>
928
                <simpara>the size of the instance's second disk, if
929
                any</simpara>
930
              </listitem>
931
            </varlistentry>
932
            <varlistentry>
933
              <term>vcpus</term>
934
              <listitem>
935
                <simpara>the number of VCPUs allocated to the
936
                instance</simpara>
937
              </listitem>
938
            </varlistentry>
939
            <varlistentry>
940
              <term>tags</term>
941
              <listitem>
942
                <simpara>comma-separated list of the instances's
943
                tags</simpara>
944
              </listitem>
945
            </varlistentry>
946
            <varlistentry>
947
              <term>serial_no</term>
948
              <listitem>
949
                <simpara>the so called 'serial number' of the
950
                instance; this is a numeric field that is incremented
951
                each time the instance is modified, and it can be used
952
                to track modifications</simpara>
953
              </listitem>
954
            </varlistentry>
955
            <varlistentry>
956
              <term>network_port</term>
957
              <listitem>
958
                <simpara>If the instance has a network port assigned
959
                to it (e.g. for VNC connections), this will be shown,
960
                otherwise <literal>-</literal> will be
961
                displayed.</simpara>
962
              </listitem>
963
            </varlistentry>
964
            <varlistentry>
965
              <term>beparams</term>
966
              <listitem>
967
                <simpara>A text format of the entire beparams for the
968
                instance. It's more useful to select individual fields
969
                from this dictionary, see below.</simpara>
970
              </listitem>
971
            </varlistentry>
972
            <varlistentry>
973
              <term>disk.count</term>
974
              <listitem>
975
                <simpara>The number of instance disks.</simpara>
976
              </listitem>
977
            </varlistentry>
978
            <varlistentry>
979
              <term>disk.size/N</term>
980
              <listitem>
981
                <simpara>The size of the instance's Nth disk. This is
982
                a more generic form of the <literal>sda_size</literal>
983
                and <literal>sdb_size</literal> fields.</simpara>
984
              </listitem>
985
            </varlistentry>
986
            <varlistentry>
987
              <term>disk.sizes</term>
988
              <listitem>
989
                <simpara>A comma-separated list of the disk sizes for
990
                this instance.</simpara>
991
              </listitem>
992
            </varlistentry>
993
            <varlistentry>
994
              <term>disk_usage</term>
995
              <listitem>
996
                <simpara>The total disk space used by this instance on
997
                each of its nodes. This is not the instance-visible
998
                disk size, but the actual disk "cost" of the
999
                instance.</simpara>
1000
              </listitem>
1001
            </varlistentry>
1002
            <varlistentry>
1003
              <term>nic.mac/N</term>
1004
              <listitem>
1005
                <simpara>The MAC of the Nth instance NIC.</simpara>
1006
              </listitem>
1007
            </varlistentry>
1008
            <varlistentry>
1009
              <term>nic.ip/N</term>
1010
              <listitem>
1011
                <simpara>The IP address of the Nth instance NIC.</simpara>
1012
              </listitem>
1013
            </varlistentry>
1014
            <varlistentry>
1015
              <term>nic.bridge/N</term>
1016
              <listitem>
1017
                <simpara>The bridge the Nth instance NIC is attached
1018
                to.</simpara>
1019
              </listitem>
1020
            </varlistentry>
1021
            <varlistentry>
1022
              <term>nic.macs</term>
1023
              <listitem>
1024
                <simpara>A comma-separated list of all the MACs of the
1025
                instance's NICs.</simpara>
1026
              </listitem>
1027
            </varlistentry>
1028
            <varlistentry>
1029
              <term>nic.ips</term>
1030
              <listitem>
1031
                <simpara>A comma-separated list of all the IP
1032
                addresses of the instance's NICs.</simpara>
1033
              </listitem>
1034
            </varlistentry>
1035
            <varlistentry>
1036
              <term>nic.bridges</term>
1037
              <listitem>
1038
                <simpara>A comma-separated list of all the bridges of the
1039
                instance's NICs.</simpara>
1040
              </listitem>
1041
            </varlistentry>
1042
            <varlistentry>
1043
              <term>nic.count</term>
1044
              <listitem>
1045
                <simpara>The number of instance nics.</simpara>
1046
              </listitem>
1047
            </varlistentry>
1048
            <varlistentry>
1049
              <term>hv/<replaceable>NAME</replaceable></term>
1050
              <listitem>
1051
                <simpara>The value of the hypervisor parameter called
1052
                <replaceable>NAME</replaceable>. For details of what
1053
                hypervisor parameters exist and their meaning, see the
1054
                <command>add</command> command.</simpara>
1055
              </listitem>
1056
            </varlistentry>
1057
            <varlistentry>
1058
              <term>be/memory</term>
1059
              <listitem>
1060
                <simpara>The configured memory for the instance.</simpara>
1061
              </listitem>
1062
            </varlistentry>
1063
            <varlistentry>
1064
              <term>be/vcpus</term>
1065
              <listitem>
1066
                <simpara>The configured number of VCPUs for the
1067
                instance.</simpara>
1068
              </listitem>
1069
            </varlistentry>
1070
            <varlistentry>
1071
              <term>be/auto_balance</term>
1072
              <listitem>
1073
                <simpara>Whether the instance is considered in N+1
1074
                checks.</simpara>
1075
              </listitem>
1076
            </varlistentry>
1077
          </variablelist>
1078
        </para>
1079

    
1080
        <para>
1081
          If the value of the option starts with the character
1082
          <constant>+</constant>, the new field(s) will be added to the
1083
          default list. This allows to quickly see the default list
1084
          plus a few other fields, instead of retyping the entire list
1085
          of fields.
1086
        </para>
1087

    
1088
        <para>
1089
          There is a subtle grouping about the available output
1090
          fields: all fields except for <option>oper_state</option>,
1091
          <option>oper_ram</option> and <option>status</option> are
1092
          configuration value and not run-time values. So if you don't
1093
          select any of the these fields, the query will be satisfied
1094
          instantly from the cluster configuration, without having to
1095
          ask the remote nodes for the data. This can be helpful for
1096
          big clusters when you only want some data and it makes sense
1097
          to specify a reduced set of output fields.
1098
        </para>
1099

    
1100
        <para>The default output field list is:
1101
          <simplelist type="inline">
1102
            <member>name</member>
1103
            <member>os</member>
1104
            <member>pnode</member>
1105
            <member>admin_state</member>
1106
            <member>oper_state</member>
1107
            <member>oper_ram</member>
1108
          </simplelist>.
1109
        </para>
1110
      </refsect3>
1111

    
1112
      <refsect3>
1113
        <title>INFO</title>
1114

    
1115
        <cmdsynopsis>
1116
          <command>info</command>
1117
          <group>
1118
            <arg>-s</arg>
1119
            <arg>--static</arg>
1120
          </group>
1121
          <arg rep="repeat"><replaceable>instance</replaceable></arg>
1122
        </cmdsynopsis>
1123

    
1124
        <para>
1125
          Show detailed information about the (given) instances. This
1126
          is different from <command>list</command> as it shows
1127
          detailed data about the instance's disks (especially useful
1128
          for drbd disk template).
1129
        </para>
1130

    
1131
        <para>
1132
          If the option <option>-s</option> is used, only information
1133
          available in the configuration file is returned, without
1134
          querying nodes, making the operation faster.
1135
        </para>
1136
      </refsect3>
1137

    
1138
      <refsect3>
1139
        <title>MODIFY</title>
1140

    
1141
        <cmdsynopsis>
1142
          <command>modify</command>
1143
          <sbr>
1144
          <arg choice="opt">-H <replaceable>HYPERVISOR_PARAMETERS</replaceable></arg>
1145
          <sbr>
1146
          <arg choice="opt">-B <replaceable>BACKEND_PARAMETERS</replaceable></arg>
1147
          <sbr>
1148
          <group>
1149
            <arg>--net add<replaceable><optional>:options</optional></replaceable></arg>
1150
            <arg>--net remove</arg>
1151
            <arg>--net <replaceable>N:options</replaceable></arg>
1152
          </group>
1153
          <sbr>
1154
          <group>
1155
            <arg>--disk add:size=<replaceable>SIZE</replaceable></arg>
1156
            <arg>--disk remove</arg>
1157
            <arg>--disk <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></arg>
1158
          </group>
1159

    
1160
          <sbr>
1161
          <arg>--submit</arg>
1162
          <sbr>
1163
          <arg choice="req"><replaceable>instance</replaceable></arg>
1164
        </cmdsynopsis>
1165

    
1166
        <para>
1167
          Modifies the memory size, number of vcpus, ip address, MAC
1168
          address and/or bridge for an instance. It can also add and
1169
          remove disks and NICs to/from the instance. Note that you
1170
          need to give at least one of the arguments, otherwise the
1171
          command complains.
1172
        </para>
1173

    
1174
        <para>
1175
          The <option>-H</option> option specifies hypervisor options
1176
          in the form of <userinput>name=value[,...]</userinput>. For details which options can be specified, see the <command>add</command> command.
1177
        </para>
1178

    
1179
        <para>
1180
          The <option>--disk
1181
          add:size=<replaceable>SIZE</replaceable></option> option
1182
          adds a disk to the instance. The <option>--disk
1183
          remove</option> will remove the last disk of the
1184
          instance. The <option>--disk
1185
          <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></option>
1186
          option will change the mode of the Nth disk of the instance
1187
          between read-only (<literal>ro</literal>) and read-write
1188
          (<literal>rw</literal>).
1189
        </para>
1190

    
1191
        <para>
1192
          The <option>--nic
1193
          add:<replaceable>options</replaceable></option> option will
1194
          add a new NIC to the instance. The available options are the
1195
          same as in the <command>add</command> command (mac, ip,
1196
          bridge). The <option>--nice remove</option> will remove the
1197
          last NIC of the instance, while the <option>--nic
1198
          <replaceable>N</replaceable>:<replaceable>options</replaceable></option>
1199
          option will change the parameters of the Nth instance NIC.
1200
        </para>
1201

    
1202
        <para>
1203
          The <option>--submit</option> option is used to send the job to
1204
          the master daemon but not wait for its completion. The job
1205
          ID will be shown so that it can be examined via
1206
          <command>gnt-job info</command>.
1207
        </para>
1208

    
1209
        <para>
1210
          All the changes take effect at the next restart. If the
1211
          instance is running, there is no effect on the instance.
1212
        </para>
1213
      </refsect3>
1214

    
1215
      <refsect3>
1216
        <title>REINSTALL</title>
1217

    
1218
        <cmdsynopsis>
1219
          <command>reinstall</command>
1220
          <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
1221
          <arg choice="opt">-f <replaceable>force</replaceable></arg>
1222
          <arg>--select-os</arg>
1223
          <arg>--submit</arg>
1224
          <arg choice="req"><replaceable>instance</replaceable></arg>
1225
        </cmdsynopsis>
1226

    
1227
        <para>
1228
          Reinstalls the operating system on the given instance. The instance
1229
          must be stopped when running this command. If the
1230
          <option>--os-type</option> is specified, the operating system is
1231
          changed.
1232
        </para>
1233

    
1234
        <para>
1235
          The <option>--select-os</option> option switches to an
1236
          interactive OS reinstall. The user is prompted to select the OS
1237
          template from the list of available OS templates.
1238
        </para>
1239

    
1240
        <para>
1241
          The <option>--submit</option> option is used to send the job to
1242
          the master daemon but not wait for its completion. The job
1243
          ID will be shown so that it can be examined via
1244
          <command>gnt-job info</command>.
1245
        </para>
1246

    
1247

    
1248
      </refsect3>
1249

    
1250
      <refsect3>
1251
        <title>RENAME</title>
1252

    
1253
        <cmdsynopsis>
1254
          <command>rename</command>
1255
          <arg>--no-ip-check</arg>
1256
          <arg>--submit</arg>
1257
          <arg choice="req"><replaceable>instance</replaceable></arg>
1258
          <arg choice="req"><replaceable>new_name</replaceable></arg>
1259
        </cmdsynopsis>
1260

    
1261
        <para>
1262
          Renames the given instance. The instance must be stopped
1263
          when running this command. The requirements for the new name
1264
          are the same as for adding an instance: the new name must be
1265
          resolvable and the IP it resolves to must not be reachable
1266
          (in order to prevent duplicate IPs the next time the
1267
          instance is started). The IP test can be skipped if the
1268
          <option>--no-ip-check</option> option is passed.
1269
        </para>
1270

    
1271
        <para>
1272
          The <option>--submit</option> option is used to send the job to
1273
          the master daemon but not wait for its completion. The job
1274
          ID will be shown so that it can be examined via
1275
          <command>gnt-job info</command>.
1276
        </para>
1277

    
1278
      </refsect3>
1279

    
1280
    </refsect2>
1281

    
1282
    <refsect2>
1283
      <title>Starting/stopping/connecting to console</title>
1284

    
1285
      <refsect3>
1286
        <title>STARTUP</title>
1287

    
1288
        <cmdsynopsis>
1289
          <command>startup</command>
1290
          <sbr>
1291
          <arg>--force</arg>
1292
          <sbr>
1293
          <arg>--force-multiple</arg>
1294
          <sbr>
1295
          <group choice="opt">
1296
            <arg>--instance</arg>
1297
            <arg>--node</arg>
1298
            <arg>--primary</arg>
1299
            <arg>--secondary</arg>
1300
            <arg>--all</arg>
1301
          </group>
1302
          <sbr>
1303
          <arg>--submit</arg>
1304
          <sbr>
1305
          <arg choice="opt"
1306
          rep="repeat"><replaceable>name</replaceable></arg>
1307
        </cmdsynopsis>
1308

    
1309
        <para>
1310
          Starts one or more instances, depending on the following
1311
          options. The four available modes are:
1312
          <variablelist>
1313
            <varlistentry>
1314
              <term><option>--instance</option></term>
1315
              <listitem>
1316
                <simpara>will start the instances given as arguments
1317
                (at least one argument required); this is the default
1318
                selection</simpara>
1319
              </listitem>
1320
            </varlistentry>
1321
            <varlistentry>
1322
              <term>--node</term>
1323
              <listitem>
1324
                <simpara>will start the instances who have the given
1325
                node as either primary or secondary</simpara>
1326
              </listitem>
1327
            </varlistentry>
1328
            <varlistentry>
1329
              <term><option>--primary</option></term>
1330
              <listitem>
1331
                <simpara>will start all instances whose primary node
1332
                is in the list of nodes passed as arguments (at least
1333
                one node required)</simpara>
1334
              </listitem>
1335
            </varlistentry>
1336
            <varlistentry>
1337
              <term><option>--secondary</option></term>
1338
              <listitem>
1339
                <simpara>will start all instances whose secondary node
1340
                is in the list of nodes passed as arguments (at least
1341
                one node required)</simpara>
1342
              </listitem>
1343
            </varlistentry>
1344
            <varlistentry>
1345
              <term>--all</term>
1346
              <listitem>
1347
                <simpara>will start all instances in the cluster (no
1348
                arguments accepted)</simpara>
1349
              </listitem>
1350
            </varlistentry>
1351
          </variablelist>
1352
        </para>
1353

    
1354
        <para>
1355
          Note that although you can pass more than one selection
1356
          option, the last one wins, so in order to guarantee the
1357
          desired result, don't pass more than one such option.
1358
        </para>
1359

    
1360
        <para>
1361
          Use <option>--force</option> to start even if secondary disks are
1362
          failing.
1363
        </para>
1364

    
1365
        <para>
1366
          The <option>--force-multiple</option> will skip the
1367
          interactive confirmation in the case the more than one
1368
          instance will be affected.
1369
        </para>
1370

    
1371
        <para>
1372
          The <option>--submit</option> option is used to send the job to
1373
          the master daemon but not wait for its completion. The job
1374
          ID will be shown so that it can be examined via
1375
          <command>gnt-job info</command>.
1376
        </para>
1377

    
1378
        <para>
1379
          Example:
1380
          <screen>
1381
# gnt-instance start instance1.example.com
1382
# gnt-instance start --node node1.example.com node2.example.com
1383
# gnt-instance start --all
1384
          </screen>
1385
        </para>
1386
      </refsect3>
1387

    
1388
      <refsect3>
1389
        <title>SHUTDOWN</title>
1390

    
1391
        <cmdsynopsis>
1392
          <command>shutdown</command>
1393
          <sbr>
1394
          <arg>--force-multiple</arg>
1395
          <sbr>
1396
          <group choice="opt">
1397
            <arg>--instance</arg>
1398
            <arg>--node</arg>
1399
            <arg>--primary</arg>
1400
            <arg>--secondary</arg>
1401
            <arg>--all</arg>
1402
          </group>
1403
          <sbr>
1404
          <arg>--submit</arg>
1405
          <sbr>
1406
          <arg choice="opt"
1407
          rep="repeat"><replaceable>name</replaceable></arg>
1408
        </cmdsynopsis>
1409

    
1410
        <para>
1411
          Stops one or more instances. If the instance cannot be
1412
          cleanly stopped during a hardcoded interval (currently 2
1413
          minutes), it will forcibly stop the instance (equivalent to
1414
          switching off the power on a physical machine).
1415
        </para>
1416

    
1417
        <para>
1418
          The <option>--instance</option>, <option>--node</option>,
1419
          <option>--primary</option>, <option>--secondary</option> and
1420
          <option>--all</option> options are similar as for the
1421
          <command>startup</command> command and they influence the
1422
          actual instances being shutdown.
1423
        </para>
1424

    
1425
        <para>
1426
          The <option>--submit</option> option is used to send the job to
1427
          the master daemon but not wait for its completion. The job
1428
          ID will be shown so that it can be examined via
1429
          <command>gnt-job info</command>.
1430
        </para>
1431

    
1432

    
1433
        <para>
1434
          Example:
1435
          <screen>
1436
# gnt-instance shutdown instance1.example.com
1437
# gnt-instance shutdown --all
1438
          </screen>
1439
        </para>
1440
      </refsect3>
1441

    
1442
      <refsect3>
1443
        <title>REBOOT</title>
1444

    
1445
        <cmdsynopsis>
1446
          <command>reboot</command>
1447
          <sbr>
1448
          <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
1449
          <sbr>
1450
          <arg>--ignore-secondaries</arg>
1451
          <sbr>
1452
          <arg>--force-multiple</arg>
1453
          <sbr>
1454
          <group choice="opt">
1455
            <arg>--instance</arg>
1456
            <arg>--node</arg>
1457
            <arg>--primary</arg>
1458
            <arg>--secondary</arg>
1459
            <arg>--all</arg>
1460
          </group>
1461
          <sbr>
1462
          <arg>--submit</arg>
1463
          <sbr>
1464
          <arg choice="opt"
1465
          rep="repeat"><replaceable>name</replaceable></arg>
1466
        </cmdsynopsis>
1467

    
1468
        <para>
1469
          Reboots one or more instances. The type of reboot depends on
1470
          the value of <option>--type</option>. A soft reboot does a
1471
          hypervisor reboot, a hard reboot does a instance stop,
1472
          recreates the hypervisor config for the instance and
1473
          starts the instance. A full reboot does the equivalent
1474
          of <command>gnt-instance shutdown &amp;&amp; gnt-instance
1475
          startup</command>. The default is hard reboot.
1476
        </para>
1477

    
1478
        <para>
1479
          For the hard reboot the option
1480
          <option>--ignore-secondaries</option> ignores errors for the
1481
          secondary node while re-assembling the instance disks.
1482
        </para>
1483

    
1484
        <para>
1485
          The <option>--instance</option>, <option>--node</option>,
1486
          <option>--primary</option>, <option>--secondary</option> and
1487
          <option>--all</option> options are similar as for the
1488
          <command>startup</command> command and they influence the
1489
          actual instances being rebooted.
1490
        </para>
1491

    
1492
        <para>
1493
          The <option>--force-multiple</option> will skip the
1494
          interactive confirmation in the case the more than one
1495
          instance will be affected.
1496
        </para>
1497

    
1498
        <para>
1499
          Example:
1500
          <screen>
1501
# gnt-instance reboot instance1.example.com
1502
# gnt-instance reboot --type=full instance1.example.com
1503
          </screen>
1504
        </para>
1505
      </refsect3>
1506

    
1507
      <refsect3>
1508
        <title>CONSOLE</title>
1509
        <cmdsynopsis>
1510
          <command>console</command>
1511
          <arg choice="opt">--show-cmd</arg>
1512
          <arg choice="req"><replaceable>instance</replaceable></arg>
1513
        </cmdsynopsis>
1514

    
1515
        <para>
1516
          Connects to the console of the given instance. If the
1517
          instance is not up, an error is returned. Use the
1518
          <option>--show-cmd</option> option to display the command
1519
          instead of executing it.
1520
        </para>
1521

    
1522
        <para>
1523
          For HVM instances, this will attempt to connect to the
1524
          serial console of the instance. To connect to the
1525
          virtualized "physical" console of a HVM instance, use a VNC
1526
          client with the connection info from the
1527
          <command>info</command> command.
1528
        </para>
1529

    
1530
        <para>
1531
          Example:
1532
          <screen>
1533
# gnt-instance console instance1.example.com
1534
          </screen>
1535
        </para>
1536
      </refsect3>
1537

    
1538
    </refsect2>
1539

    
1540
    <refsect2>
1541
      <title>Disk management</title>
1542

    
1543
      <refsect3>
1544
        <title>REPLACE-DISKS</title>
1545

    
1546
        <cmdsynopsis>
1547
          <command>replace-disks</command>
1548
          <arg>--submit</arg>
1549
          <arg choice="req">-p</arg>
1550
          <arg choice="req"><replaceable>instance</replaceable></arg>
1551
        </cmdsynopsis>
1552

    
1553
        <cmdsynopsis>
1554
          <command>replace-disks</command>
1555
          <arg>--submit</arg>
1556
          <arg choice="req">-s</arg>
1557
          <arg choice="req"><replaceable>instance</replaceable></arg>
1558
        </cmdsynopsis>
1559

    
1560
        <cmdsynopsis>
1561
          <command>replace-disks</command>
1562
          <arg>--submit</arg>
1563
          <group choice="req">
1564
            <arg>--iallocator <replaceable>name</replaceable></arg>
1565
            <arg>--new-secondary <replaceable>NODE</replaceable></arg>
1566
          </group>
1567

    
1568
          <arg choice="req"><replaceable>instance</replaceable></arg>
1569
        </cmdsynopsis>
1570

    
1571
        <para>
1572
          This command is a generalized form for adding and replacing
1573
          disks. It is currently only valid for the mirrored (DRBD)
1574
          disk template.
1575
        </para>
1576

    
1577
        <para>
1578
          The first form (when passing the <option>-p</option> option)
1579
          will replace the disks on the primary, while the second form
1580
          (when passing the <option>-s</option> option will replace
1581
          the disks on the secondary node.
1582
        </para>
1583

    
1584
        <para>
1585
          The third form (when passing either the
1586
          <option>--iallocator</option> or the
1587
          <option>--new-secondary</option> option) is designed to
1588
          change secondary node of the instance.  Specifying
1589
          <option>--iallocator</option> makes the new secondary be
1590
          selected automatically by the specified allocator plugin,
1591
          otherwise the new secondary node will be the one chosen
1592
          manually via the <option>--new-secondary</option> option.
1593
        </para>
1594

    
1595
        <para>
1596
          The <option>--submit</option> option is used to send the job to
1597
          the master daemon but not wait for its completion. The job
1598
          ID will be shown so that it can be examined via
1599
          <command>gnt-job info</command>.
1600
        </para>
1601

    
1602
        <para>
1603
          Note that it is not possible to select an offline or drained
1604
          node as a new secondary.
1605
        </para>
1606

    
1607
      </refsect3>
1608

    
1609
      <refsect3>
1610
        <title>ACTIVATE-DISKS</title>
1611

    
1612
        <cmdsynopsis>
1613
          <command>activate-disks</command>
1614
          <arg>--submit</arg>
1615
          <arg choice="req"><replaceable>instance</replaceable></arg>
1616
        </cmdsynopsis>
1617
        <para>
1618
          Activates the block devices of the given instance. If
1619
          successful, the command will show the location and name of
1620
          the block devices:
1621
          <screen>
1622
node1.example.com:disk/0:/dev/drbd0
1623
node1.example.com:disk/1:/dev/drbd1
1624
          </screen>
1625

    
1626
          In this example, <emphasis>node1.example.com</emphasis> is
1627
          the name of the node on which the devices have been
1628
          activated. The <emphasis>disk/0</emphasis> and
1629
          <emphasis>disk/1</emphasis> are the Ganeti-names of the
1630
          instance disks; how they are visible inside the instance is
1631
          hypervisor-specific. <emphasis>/dev/drbd0</emphasis> and
1632
          <emphasis>/dev/drbd1</emphasis> are the actual block devices
1633
          as visible on the node.
1634
        </para>
1635

    
1636
        <para>
1637
          The <option>--submit</option> option is used to send the job to
1638
          the master daemon but not wait for its completion. The job
1639
          ID will be shown so that it can be examined via
1640
          <command>gnt-job info</command>.
1641
        </para>
1642

    
1643
        <para>
1644
          Note that it is safe to run this command while the instance
1645
          is already running.
1646
        </para>
1647
      </refsect3>
1648

    
1649
      <refsect3>
1650
        <title>DEACTIVATE-DISKS</title>
1651

    
1652
        <cmdsynopsis>
1653
          <command>deactivate-disks</command>
1654
          <arg>--submit</arg>
1655
          <arg choice="req"><replaceable>instance</replaceable></arg>
1656
        </cmdsynopsis>
1657
        <para>
1658
          De-activates the block devices of the given instance. Note
1659
          that if you run this command for an instance with a drbd
1660
          disk template, while it is running, it will not be able to
1661
          shutdown the block devices on the primary node, but it will
1662
          shutdown the block devices on the secondary nodes, thus
1663
          breaking the replication.
1664
        </para>
1665

    
1666
        <para>
1667
          The <option>--submit</option> option is used to send the job to
1668
          the master daemon but not wait for its completion. The job
1669
          ID will be shown so that it can be examined via
1670
          <command>gnt-job info</command>.
1671
        </para>
1672

    
1673
      </refsect3>
1674

    
1675
      <refsect3>
1676
        <title>GROW-DISK</title>
1677
        <cmdsynopsis>
1678
          <command>grow-disk</command>
1679
          <arg>--no-wait-for-sync</arg>
1680
          <arg>--submit</arg>
1681
          <arg choice="req"><replaceable>instance</replaceable></arg>
1682
          <arg choice="req"><replaceable>disk</replaceable></arg>
1683
          <arg choice="req"><replaceable>amount</replaceable></arg>
1684
        </cmdsynopsis>
1685

    
1686
        <para>
1687
          Grows an instance's disk. This is only possible for
1688
          instances having a <literal>plain</literal> or
1689
          <literal>drbd</literal> disk template.
1690
        </para>
1691

    
1692
        <para>
1693
          Note that this command only change the block device size; it
1694
          will not grow the actual filesystems, partitions, etc. that
1695
          live on that disk. Usually, you will need to:
1696
          <orderedlist>
1697
            <listitem>
1698
              <simpara>use <command>gnt-instance grow-disk</command></simpara>
1699
            </listitem>
1700
            <listitem>
1701
              <simpara>reboot the instance (later, at a convenient
1702
              time)</simpara>
1703
            </listitem>
1704
            <listitem>
1705
              <simpara>use a filesystem resizer, such as
1706
              <citerefentry> <refentrytitle>ext2online</refentrytitle>
1707
              <manvolnum>8</manvolnum> </citerefentry> or
1708
              <citerefentry> <refentrytitle>xfs_growfs</refentrytitle>
1709
              <manvolnum>8</manvolnum> </citerefentry> to resize the
1710
              filesystem, or use <citerefentry>
1711
              <refentrytitle>fdisk</refentrytitle>
1712
              <manvolnum>8</manvolnum> </citerefentry> to change the
1713
              partition table on the disk
1714
              </simpara>
1715
            </listitem>
1716
          </orderedlist>
1717
        </para>
1718

    
1719

    
1720
        <para>
1721
          The <replaceable>disk</replaceable> argument is the index of
1722
          the instance disk to grow. The
1723
          <replaceable>amount</replaceable> argument is given either
1724
          as a number (and it represents the amount to increase the
1725
          disk with in mebibytes) or can be given similar to the
1726
          arguments in the create instance operation, with a suffix
1727
          denoting the unit.
1728
        </para>
1729

    
1730
        <para>
1731
          Note that the disk grow operation might complete on one node
1732
          but fail on the other; this will leave the instance with
1733
          different-sized LVs on the two nodes, but this will not
1734
          create problems (except for unused space).
1735
        </para>
1736

    
1737
        <para>
1738
          If you do not want gnt-instance to wait for the new disk
1739
          region to be synced, use the
1740
          <option>--no-wait-for-sync</option> option.
1741
        </para>
1742

    
1743
        <para>
1744
          The <option>--submit</option> option is used to send the job to
1745
          the master daemon but not wait for its completion. The job
1746
          ID will be shown so that it can be examined via
1747
          <command>gnt-job info</command>.
1748
        </para>
1749

    
1750

    
1751
        <para>Example (increase the first disk for instance1 by 16GiB):
1752
          <screen>
1753
# gnt-instance grow-disk instance1.example.com 0 16g
1754
          </screen>
1755
        </para>
1756

    
1757
        <para>
1758
          Also note that disk shrinking is not supported; use
1759
          <command>gnt-backup export</command> and then
1760
          <command>gnt-backup import</command> to reduce the disk size
1761
          of an instance.
1762
        </para>
1763
      </refsect3>
1764

    
1765
    </refsect2>
1766

    
1767
    <refsect2>
1768
      <title>Recovery</title>
1769

    
1770
      <refsect3>
1771
        <title>FAILOVER</title>
1772

    
1773
        <cmdsynopsis>
1774
          <command>failover</command>
1775
          <arg>-f</arg>
1776
          <arg>--ignore-consistency</arg>
1777
          <arg>--submit</arg>
1778
          <arg choice="req"><replaceable>instance</replaceable></arg>
1779
        </cmdsynopsis>
1780

    
1781
        <para>
1782
          Failover will fail the instance over its secondary
1783
          node. This works only for instances having a drbd disk
1784
          template.
1785
        </para>
1786

    
1787
        <para>
1788
          Normally the failover will check the consistency of the
1789
          disks before failing over the instance. If you are trying to
1790
          migrate instances off a dead node, this will fail. Use the
1791
          <option>--ignore-consistency</option> option for this
1792
          purpose. Note that this option can be dangerous as errors in
1793
          shutting down the instance will be ignored, resulting in
1794
          possibly having the instance running on two machines in
1795
          parallel (on disconnected DRBD drives).
1796
        </para>
1797

    
1798
        <para>
1799
          The <option>--submit</option> option is used to send the job to
1800
          the master daemon but not wait for its completion. The job
1801
          ID will be shown so that it can be examined via
1802
          <command>gnt-job info</command>.
1803
        </para>
1804

    
1805
        <para>
1806
          Example:
1807
          <screen>
1808
# gnt-instance failover instance1.example.com
1809
          </screen>
1810
        </para>
1811
      </refsect3>
1812

    
1813
      <refsect3>
1814
        <title>MIGRATE</title>
1815

    
1816
        <cmdsynopsis>
1817
          <command>migrate</command>
1818
          <arg>-f</arg>
1819
          <arg choice="req">--cleanup</arg>
1820
          <arg choice="req"><replaceable>instance</replaceable></arg>
1821
        </cmdsynopsis>
1822

    
1823
        <cmdsynopsis>
1824
          <command>migrate</command>
1825
          <arg>-f</arg>
1826
          <arg>--non-live</arg>
1827
          <arg choice="req"><replaceable>instance</replaceable></arg>
1828
        </cmdsynopsis>
1829

    
1830
        <para>
1831
          Migrate will move the instance to its secondary node without
1832
          shutdown. It only works for instances having the drbd8 disk
1833
          template type.
1834
        </para>
1835

    
1836
        <para>
1837
          The migration command needs a perfectly healthy instance, as
1838
          we rely on the dual-master capability of drbd8 and the disks
1839
          of the instance are not allowed to be degraded.
1840
        </para>
1841

    
1842
        <para>
1843
          The <option>--non-live</option> option will switch (for the
1844
          hypervisors that support it) between a "fully live"
1845
          (i.e. the interruption is as minimal as possible) migration
1846
          and one in which the instance is frozen, its state saved and
1847
          transported to the remote node, and then resumed there. This
1848
          all depends on the hypervisor support for two different
1849
          methods. In any case, it is not an error to pass this
1850
          parameter (it will just be ignored if the hypervisor doesn't
1851
          support it).
1852
        </para>
1853

    
1854
        <para>
1855
          If the <option>--cleanup</option> option is passed, the
1856
          operation changes from migration to attempting recovery from
1857
          a failed previous migration. In this mode, ganeti checks if
1858
          the instance runs on the correct node (and updates its
1859
          configuration if not) and ensures the instances's disks are
1860
          configured correctly. In this mode, the
1861
          <option>--non-live</option> option is ignored.
1862
        </para>
1863

    
1864
        <para>
1865
          The option <option>-f</option> will skip the prompting for
1866
          confirmation.
1867
        </para>
1868
        <para>
1869
          Example (and expected output):
1870
          <screen>
1871
# gnt-instance migrate instance1
1872
Migrate will happen to the instance instance1. Note that migration is
1873
**experimental** in this version. This might impact the instance if
1874
anything goes wrong. Continue?
1875
y/[n]/?: y
1876
* checking disk consistency between source and target
1877
* ensuring the target is in secondary mode
1878
* changing disks into dual-master mode
1879
 - INFO: Waiting for instance instance1 to sync disks.
1880
 - INFO: Instance instance1's disks are in sync.
1881
* migrating instance to node2.example.com
1882
* changing the instance's disks on source node to secondary
1883
 - INFO: Waiting for instance instance1 to sync disks.
1884
 - INFO: Instance instance1's disks are in sync.
1885
* changing the instance's disks to single-master
1886
#
1887
          </screen>
1888
        </para>
1889
      </refsect3>
1890

    
1891
    </refsect2>
1892

    
1893
    <refsect2>
1894
      <title>TAGS</title>
1895

    
1896
    <refsect3>
1897
        <title>ADD-TAGS</title>
1898

    
1899
        <cmdsynopsis>
1900
          <command>add-tags</command>
1901
          <arg choice="opt">--from <replaceable>file</replaceable></arg>
1902
          <arg choice="req"><replaceable>instancename</replaceable></arg>
1903
          <arg choice="req"
1904
            rep="repeat"><replaceable>tag</replaceable></arg>
1905
        </cmdsynopsis>
1906

    
1907
        <para>
1908
          Add tags to the given instance. If any of the tags contains
1909
          invalid characters, the entire operation will abort.
1910
        </para>
1911
        <para>
1912
          If the <option>--from</option> option is given, the list of
1913
          tags will be extended with the contents of that file (each
1914
          line becomes a tag). In this case, there is not need to pass
1915
          tags on the command line (if you do, both sources will be
1916
          used). A file name of - will be interpreted as stdin.
1917
        </para>
1918
      </refsect3>
1919

    
1920
      <refsect3>
1921
        <title>LIST-TAGS</title>
1922

    
1923
        <cmdsynopsis>
1924
          <command>list-tags</command>
1925
          <arg choice="req"><replaceable>instancename</replaceable></arg>
1926
        </cmdsynopsis>
1927

    
1928
        <para>List the tags of the given instance.</para>
1929
      </refsect3>
1930

    
1931
      <refsect3>
1932
        <title>REMOVE-TAGS</title>
1933
        <cmdsynopsis>
1934
          <command>remove-tags</command>
1935
          <arg choice="opt">--from <replaceable>file</replaceable></arg>
1936
          <arg choice="req"><replaceable>instancename</replaceable></arg>
1937
          <arg choice="req"
1938
            rep="repeat"><replaceable>tag</replaceable></arg>
1939
        </cmdsynopsis>
1940

    
1941
        <para>
1942
          Remove tags from the given instance. If any of the tags are
1943
          not existing on the node, the entire operation will abort.
1944
        </para>
1945

    
1946
        <para>
1947
          If the <option>--from</option> option is given, the list of
1948
          tags will be extended with the contents of that file (each
1949
          line becomes a tag). In this case, there is not need to pass
1950
          tags on the command line (if you do, both sources will be
1951
          used). A file name of - will be interpreted as stdin.
1952
        </para>
1953
      </refsect3>
1954

    
1955
    </refsect2>
1956

    
1957
  </refsect1>
1958

    
1959
  &footer;
1960

    
1961
</refentry>
1962

    
1963
<!-- Keep this comment at the end of the file
1964
Local variables:
1965
mode: sgml
1966
sgml-omittag:t
1967
sgml-shorttag:t
1968
sgml-minimize-attributes:nil
1969
sgml-always-quote-attributes:t
1970
sgml-indent-step:2
1971
sgml-indent-data:t
1972
sgml-parent-document:nil
1973
sgml-default-dtd-file:nil
1974
sgml-exposed-tags:nil
1975
sgml-local-catalogs:nil
1976
sgml-local-ecat-files:nil
1977
End:
1978
-->