Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.rst @ 57fb6fcb

History | View | Annotate | Download (61.6 kB)

1
gnt-instance(8) Ganeti | Version @GANETI_VERSION@
2
=================================================
3

    
4
Name
5
----
6

    
7
gnt-instance - Ganeti instance administration
8

    
9
Synopsis
10
--------
11

    
12
**gnt-instance** {command} [arguments...]
13

    
14
DESCRIPTION
15
-----------
16

    
17
The **gnt-instance** command is used for instance administration in
18
the Ganeti system.
19

    
20
COMMANDS
21
--------
22

    
23
Creation/removal/querying
24
~~~~~~~~~~~~~~~~~~~~~~~~~
25

    
26
ADD
27
^^^
28

    
29
| **add**
30
| {-t|\--disk-template {diskless | file \| plain \| drbd \| rbd}}
31
| {\--disk=*N*: {size=*VAL* \| adopt=*LV*}[,vg=*VG*][,metavg=*VG*][,mode=*ro\|rw*]
32
|  \| {-s|\--os-size} *SIZE*}
33
| [\--no-ip-check] [\--no-name-check] [\--no-start] [\--no-install]
34
| [\--net=*N* [:options...] \| \--no-nics]
35
| [{-B|\--backend-parameters} *BEPARAMS*]
36
| [{-H|\--hypervisor-parameters} *HYPERVISOR* [: option=*value*... ]]
37
| [{-O|\--os-parameters} *param*=*value*... ]
38
| [\--file-storage-dir *dir\_path*] [\--file-driver {loop \| blktap}]
39
| {{-n|\--node} *node[:secondary-node]* \| {-I|\--iallocator} *name*}
40
| {{-o|\--os-type} *os-type*}
41
| [\--submit]
42
| [\--ignore-ipolicy]
43
| {*instance*}
44

    
45
Creates a new instance on the specified host. The *instance* argument
46
must be in DNS, but depending on the bridge/routing setup, need not be
47
in the same network as the nodes in the cluster.
48

    
49
The ``disk`` option specifies the parameters for the disks of the
50
instance. The numbering of disks starts at zero, and at least one disk
51
needs to be passed. For each disk, either the size or the adoption
52
source needs to be given, and optionally the access mode (read-only or
53
the default of read-write) and the LVM volume group can also be
54
specified (via the ``vg`` key). For DRBD devices, a different VG can
55
be specified for the metadata device using the ``metavg`` key.  The
56
size is interpreted (when no unit is given) in mebibytes. You can also
57
use one of the suffixes *m*, *g* or *t* to specify the exact the units
58
used; these suffixes map to mebibytes, gibibytes and tebibytes.
59

    
60
When using the ``adopt`` key in the disk definition, Ganeti will
61
reuse those volumes (instead of creating new ones) as the
62
instance's disks. Ganeti will rename these volumes to the standard
63
format, and (without installing the OS) will use them as-is for the
64
instance. This allows migrating instances from non-managed mode
65
(e.g. plain KVM with LVM) to being managed via Ganeti. Please note that
66
this works only for the \`plain' disk template (see below for
67
template details).
68

    
69
Alternatively, a single-disk instance can be created via the ``-s``
70
option which takes a single argument, the size of the disk. This is
71
similar to the Ganeti 1.2 version (but will only create one disk).
72

    
73
The minimum disk specification is therefore ``--disk 0:size=20G`` (or
74
``-s 20G`` when using the ``-s`` option), and a three-disk instance
75
can be specified as ``--disk 0:size=20G --disk 1:size=4G --disk
76
2:size=100G``.
77

    
78
The ``--no-ip-check`` skips the checks that are done to see if the
79
instance's IP is not already alive (i.e. reachable from the master
80
node).
81

    
82
The ``--no-name-check`` skips the check for the instance name via
83
the resolver (e.g. in DNS or /etc/hosts, depending on your setup).
84
Since the name check is used to compute the IP address, if you pass
85
this option you must also pass the ``--no-ip-check`` option.
86

    
87
If you don't want the instance to automatically start after
88
creation, this is possible via the ``--no-start`` option. This will
89
leave the instance down until a subsequent **gnt-instance start**
90
command.
91

    
92
The NICs of the instances can be specified via the ``--net``
93
option. By default, one NIC is created for the instance, with a
94
random MAC, and set up according the the cluster level nic
95
parameters. Each NIC can take these parameters (all optional):
96

    
97
mac
98
    either a value or 'generate' to generate a new unique MAC
99

    
100
ip
101
    specifies the IP address assigned to the instance from the Ganeti
102
    side (this is not necessarily what the instance will use, but what
103
    the node expects the instance to use)
104

    
105
mode
106
    specifies the connection mode for this nic: routed, bridged or
107
    openvswitch.
108

    
109
link
110
    in bridged or openvswitch mode specifies the interface to attach
111
    this NIC to, in routed mode it's intended to differentiate between
112
    different routing tables/instance groups (but the meaning is
113
    dependent on the network script, see gnt-cluster(8) for more
114
    details). Note that openvswitch support is also hypervisor
115
    dependent.
116

    
117

    
118
Of these "mode" and "link" are nic parameters, and inherit their
119
default at cluster level.  Alternatively, if no network is desired for
120
the instance, you can prevent the default of one NIC with the
121
``--no-nics`` option.
122

    
123
The ``-o (--os-type)`` option specifies the operating system to be
124
installed.  The available operating systems can be listed with
125
**gnt-os list**.  Passing ``--no-install`` will however skip the OS
126
installation, allowing a manual import if so desired. Note that the
127
no-installation mode will automatically disable the start-up of the
128
instance (without an OS, it most likely won't be able to start-up
129
successfully).
130

    
131
The ``-B (--backend-parameters)`` option specifies the backend
132
parameters for the instance. If no such parameters are specified, the
133
values are inherited from the cluster. Possible parameters are:
134

    
135
maxmem
136
    the maximum memory size of the instance; as usual, suffixes can be
137
    used to denote the unit, otherwise the value is taken in mebibytes
138

    
139
minmem
140
    the minimum memory size of the instance; as usual, suffixes can be
141
    used to denote the unit, otherwise the value is taken in mebibytes
142

    
143
vcpus
144
    the number of VCPUs to assign to the instance (if this value makes
145
    sense for the hypervisor)
146

    
147
auto\_balance
148
    whether the instance is considered in the N+1 cluster checks
149
    (enough redundancy in the cluster to survive a node failure)
150

    
151
always\_failover
152
    ``True`` or ``False``, whether the instance must be failed over
153
    (shut down and rebooted) always or it may be migrated (briefly
154
    suspended)
155

    
156
Note that before 2.6 Ganeti had a ``memory`` parameter, which was the
157
only value of memory an instance could have. With the
158
``maxmem``/``minmem`` change Ganeti guarantees that at least the minimum
159
memory is always available for an instance, but allows more memory to be
160
used (up to the maximum memory) should it be free.
161

    
162
The ``-H (--hypervisor-parameters)`` option specified the hypervisor
163
to use for the instance (must be one of the enabled hypervisors on the
164
cluster) and optionally custom parameters for this instance. If not
165
other options are used (i.e. the invocation is just -H *NAME*) the
166
instance will inherit the cluster options. The defaults below show the
167
cluster defaults at cluster creation time.
168

    
169
The possible hypervisor options are as follows:
170

    
171
boot\_order
172
    Valid for the Xen HVM and KVM hypervisors.
173

    
174
    A string value denoting the boot order. This has different meaning
175
    for the Xen HVM hypervisor and for the KVM one.
176

    
177
    For Xen HVM, The boot order is a string of letters listing the boot
178
    devices, with valid device letters being:
179

    
180
    a
181
        floppy drive
182

    
183
    c
184
        hard disk
185

    
186
    d
187
        CDROM drive
188

    
189
    n
190
        network boot (PXE)
191

    
192
    The default is not to set an HVM boot order, which is interpreted
193
    as 'dc'.
194

    
195
    For KVM the boot order is either "floppy", "cdrom", "disk" or
196
    "network".  Please note that older versions of KVM couldn't netboot
197
    from virtio interfaces. This has been fixed in more recent versions
198
    and is confirmed to work at least with qemu-kvm 0.11.1. Also note
199
    that if you have set the ``kernel_path`` option, that will be used
200
    for booting, and this setting will be silently ignored.
201

    
202
blockdev\_prefix
203
    Valid for the Xen HVM and PVM hypervisors.
204

    
205
    Relevant to non-pvops guest kernels, in which the disk device names
206
    are given by the host.  Allows one to specify 'xvd', which helps run
207
    Red Hat based installers, driven by anaconda.
208

    
209
floppy\_image\_path
210
    Valid for the KVM hypervisor.
211

    
212
    The path to a floppy disk image to attach to the instance.  This
213
    is useful to install Windows operating systems on Virt/IO disks
214
    because you can specify here the floppy for the drivers at
215
    installation time.
216

    
217
cdrom\_image\_path
218
    Valid for the Xen HVM and KVM hypervisors.
219

    
220
    The path to a CDROM image to attach to the instance.
221

    
222
cdrom2\_image\_path
223
    Valid for the KVM hypervisor.
224

    
225
    The path to a second CDROM image to attach to the instance.
226
    **NOTE**: This image can't be used to boot the system. To do that
227
    you have to use the 'cdrom\_image\_path' option.
228

    
229
nic\_type
230
    Valid for the Xen HVM and KVM hypervisors.
231

    
232
    This parameter determines the way the network cards are presented
233
    to the instance. The possible options are:
234

    
235
    - rtl8139 (default for Xen HVM) (HVM & KVM)
236
    - ne2k\_isa (HVM & KVM)
237
    - ne2k\_pci (HVM & KVM)
238
    - i82551 (KVM)
239
    - i82557b (KVM)
240
    - i82559er (KVM)
241
    - pcnet (KVM)
242
    - e1000 (KVM)
243
    - paravirtual (default for KVM) (HVM & KVM)
244

    
245
disk\_type
246
    Valid for the Xen HVM and KVM hypervisors.
247

    
248
    This parameter determines the way the disks are presented to the
249
    instance. The possible options are:
250

    
251
    - ioemu [default] (HVM & KVM)
252
    - ide (HVM & KVM)
253
    - scsi (KVM)
254
    - sd (KVM)
255
    - mtd (KVM)
256
    - pflash (KVM)
257

    
258

    
259
cdrom\_disk\_type
260
    Valid for the KVM hypervisor.
261

    
262
    This parameter determines the way the cdroms disks are presented
263
    to the instance. The default behavior is to get the same value of
264
    the earlier parameter (disk_type). The possible options are:
265

    
266
    - paravirtual
267
    - ide
268
    - scsi
269
    - sd
270
    - mtd
271
    - pflash
272

    
273

    
274
vnc\_bind\_address
275
    Valid for the Xen HVM and KVM hypervisors.
276

    
277
    Specifies the address that the VNC listener for this instance
278
    should bind to. Valid values are IPv4 addresses. Use the address
279
    0.0.0.0 to bind to all available interfaces (this is the default)
280
    or specify the address of one of the interfaces on the node to
281
    restrict listening to that interface.
282

    
283
vnc\_tls
284
    Valid for the KVM hypervisor.
285

    
286
    A boolean option that controls whether the VNC connection is
287
    secured with TLS.
288

    
289
vnc\_x509\_path
290
    Valid for the KVM hypervisor.
291

    
292
    If ``vnc_tls`` is enabled, this options specifies the path to the
293
    x509 certificate to use.
294

    
295
vnc\_x509\_verify
296
    Valid for the KVM hypervisor.
297

    
298
spice\_bind
299
    Valid for the KVM hypervisor.
300

    
301
    Specifies the address or interface on which the SPICE server will
302
    listen. Valid values are:
303

    
304
    - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
305
    - IPv6 addresses, including :: and ::1
306
    - names of network interfaces
307

    
308
    If a network interface is specified, the SPICE server will be bound
309
    to one of the addresses of that interface.
310

    
311
spice\_ip\_version
312
    Valid for the KVM hypervisor.
313

    
314
    Specifies which version of the IP protocol should be used by the
315
    SPICE server.
316

    
317
    It is mainly intended to be used for specifying what kind of IP
318
    addresses should be used if a network interface with both IPv4 and
319
    IPv6 addresses is specified via the ``spice_bind`` parameter. In
320
    this case, if the ``spice_ip_version`` parameter is not used, the
321
    default IP version of the cluster will be used.
322

    
323
spice\_password\_file
324
    Valid for the KVM hypervisor.
325

    
326
    Specifies a file containing the password that must be used when
327
    connecting via the SPICE protocol. If the option is not specified,
328
    passwordless connections are allowed.
329

    
330
spice\_image\_compression
331
    Valid for the KVM hypervisor.
332

    
333
    Configures the SPICE lossless image compression. Valid values are:
334

    
335
    - auto_glz
336
    - auto_lz
337
    - quic
338
    - glz
339
    - lz
340
    - off
341

    
342
spice\_jpeg\_wan\_compression
343
    Valid for the KVM hypervisor.
344

    
345
    Configures how SPICE should use the jpeg algorithm for lossy image
346
    compression on slow links. Valid values are:
347

    
348
    - auto
349
    - never
350
    - always
351

    
352
spice\_zlib\_glz\_wan\_compression
353
    Valid for the KVM hypervisor.
354

    
355
    Configures how SPICE should use the zlib-glz algorithm for lossy image
356
    compression on slow links. Valid values are:
357

    
358
    - auto
359
    - never
360
    - always
361

    
362
spice\_streaming\_video
363
    Valid for the KVM hypervisor.
364

    
365
    Configures how SPICE should detect video streams. Valid values are:
366

    
367
    - off
368
    - all
369
    - filter
370

    
371
spice\_playback\_compression
372
    Valid for the KVM hypervisor.
373

    
374
    Configures whether SPICE should compress audio streams or not.
375

    
376
spice\_use\_tls
377
    Valid for the KVM hypervisor.
378

    
379
    Specifies that the SPICE server must use TLS to encrypt all the
380
    traffic with the client.
381

    
382
spice\_tls\_ciphers
383
    Valid for the KVM hypervisor.
384

    
385
    Specifies a list of comma-separated ciphers that SPICE should use
386
    for TLS connections. For the format, see man cipher(1).
387

    
388
spice\_use\_vdagent
389
    Valid for the KVM hypervisor.
390

    
391
    Enables or disables passing mouse events via SPICE vdagent.
392

    
393
cpu\_type
394
    Valid for the KVM hypervisor.
395

    
396
    This parameter determines the emulated cpu for the instance. If this
397
    parameter is empty (which is the default configuration), it will not
398
    be passed to KVM.
399

    
400
    Be aware of setting this parameter to ``"host"`` if you have nodes
401
    with different CPUs from each other. Live migration may stop working
402
    in this situation.
403

    
404
    For more information please refer to the KVM manual.
405

    
406
acpi
407
    Valid for the Xen HVM and KVM hypervisors.
408

    
409
    A boolean option that specifies if the hypervisor should enable
410
    ACPI support for this instance. By default, ACPI is disabled.
411

    
412
pae
413
    Valid for the Xen HVM and KVM hypervisors.
414

    
415
    A boolean option that specifies if the hypervisor should enabled
416
    PAE support for this instance. The default is false, disabling PAE
417
    support.
418

    
419
use\_localtime
420
    Valid for the Xen HVM and KVM hypervisors.
421

    
422
    A boolean option that specifies if the instance should be started
423
    with its clock set to the localtime of the machine (when true) or
424
    to the UTC (When false). The default is false, which is useful for
425
    Linux/Unix machines; for Windows OSes, it is recommended to enable
426
    this parameter.
427

    
428
kernel\_path
429
    Valid for the Xen PVM and KVM hypervisors.
430

    
431
    This option specifies the path (on the node) to the kernel to boot
432
    the instance with. Xen PVM instances always require this, while for
433
    KVM if this option is empty, it will cause the machine to load the
434
    kernel from its disks (and the boot will be done accordingly to
435
    ``boot_order``).
436

    
437
kernel\_args
438
    Valid for the Xen PVM and KVM hypervisors.
439

    
440
    This options specifies extra arguments to the kernel that will be
441
    loaded. device. This is always used for Xen PVM, while for KVM it
442
    is only used if the ``kernel_path`` option is also specified.
443

    
444
    The default setting for this value is simply ``"ro"``, which
445
    mounts the root disk (initially) in read-only one. For example,
446
    setting this to single will cause the instance to start in
447
    single-user mode.
448

    
449
initrd\_path
450
    Valid for the Xen PVM and KVM hypervisors.
451

    
452
    This option specifies the path (on the node) to the initrd to boot
453
    the instance with. Xen PVM instances can use this always, while
454
    for KVM if this option is only used if the ``kernel_path`` option
455
    is also specified. You can pass here either an absolute filename
456
    (the path to the initrd) if you want to use an initrd, or use the
457
    format no\_initrd\_path for no initrd.
458

    
459
root\_path
460
    Valid for the Xen PVM and KVM hypervisors.
461

    
462
    This options specifies the name of the root device. This is always
463
    needed for Xen PVM, while for KVM it is only used if the
464
    ``kernel_path`` option is also specified.
465

    
466
    Please note, that if this setting is an empty string and the
467
    hypervisor is Xen it will not be written to the Xen configuration
468
    file
469

    
470
serial\_console
471
    Valid for the KVM hypervisor.
472

    
473
    This boolean option specifies whether to emulate a serial console
474
    for the instance.
475

    
476
disk\_cache
477
    Valid for the KVM hypervisor.
478

    
479
    The disk cache mode. It can be either default to not pass any
480
    cache option to KVM, or one of the KVM cache modes: none (for
481
    direct I/O), writethrough (to use the host cache but report
482
    completion to the guest only when the host has committed the
483
    changes to disk) or writeback (to use the host cache and report
484
    completion as soon as the data is in the host cache). Note that
485
    there are special considerations for the cache mode depending on
486
    version of KVM used and disk type (always raw file under Ganeti),
487
    please refer to the KVM documentation for more details.
488

    
489
security\_model
490
    Valid for the KVM hypervisor.
491

    
492
    The security model for kvm. Currently one of *none*, *user* or
493
    *pool*. Under *none*, the default, nothing is done and instances
494
    are run as the Ganeti daemon user (normally root).
495

    
496
    Under *user* kvm will drop privileges and become the user
497
    specified by the security\_domain parameter.
498

    
499
    Under *pool* a global cluster pool of users will be used, making
500
    sure no two instances share the same user on the same node. (this
501
    mode is not implemented yet)
502

    
503
security\_domain
504
    Valid for the KVM hypervisor.
505

    
506
    Under security model *user* the username to run the instance
507
    under.  It must be a valid username existing on the host.
508

    
509
    Cannot be set under security model *none* or *pool*.
510

    
511
kvm\_flag
512
    Valid for the KVM hypervisor.
513

    
514
    If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
515
    -disable-kvm is passed. If unset no flag is passed, and the
516
    default running mode for your kvm binary will be used.
517

    
518
mem\_path
519
    Valid for the KVM hypervisor.
520

    
521
    This option passes the -mem-path argument to kvm with the path (on
522
    the node) to the mount point of the hugetlbfs file system, along
523
    with the -mem-prealloc argument too.
524

    
525
use\_chroot
526
    Valid for the KVM hypervisor.
527

    
528
    This boolean option determines whether to run the KVM instance in a
529
    chroot directory.
530

    
531
    If it is set to ``true``, an empty directory is created before
532
    starting the instance and its path is passed via the -chroot flag
533
    to kvm. The directory is removed when the instance is stopped.
534

    
535
    It is set to ``false`` by default.
536

    
537
migration\_downtime
538
    Valid for the KVM hypervisor.
539

    
540
    The maximum amount of time (in ms) a KVM instance is allowed to be
541
    frozen during a live migration, in order to copy dirty memory
542
    pages. Default value is 30ms, but you may need to increase this
543
    value for busy instances.
544

    
545
    This option is only effective with kvm versions >= 87 and qemu-kvm
546
    versions >= 0.11.0.
547

    
548
cpu\_mask
549
    Valid for the Xen, KVM and LXC hypervisors.
550

    
551
    The processes belonging to the given instance are only scheduled
552
    on the specified CPUs.
553

    
554
    The format of the mask can be given in three forms. First, the word
555
    "all", which signifies the common case where all VCPUs can live on
556
    any CPU, based on the hypervisor's decisions.
557

    
558
    Second, a comma-separated list of CPU IDs or CPU ID ranges. The
559
    ranges are defined by a lower and higher boundary, separated by a
560
    dash, and the boundaries are inclusive. In this form, all VCPUs of
561
    the instance will be mapped on the selected list of CPUs. Example:
562
    ``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs
563
    0, 1, 2 and 5.
564

    
565
    The last form is used for explicit control of VCPU-CPU pinnings. In
566
    this form, the list of VCPU mappings is given as a colon (:)
567
    separated list, whose elements are the possible values for the
568
    second or first form above. In this form, the number of elements in
569
    the colon-separated list _must_ equal the number of VCPUs of the
570
    instance.
571

    
572
    Example:
573

    
574
    .. code-block:: Bash
575

    
576
      # Map the entire instance to CPUs 0-2
577
      gnt-instance modify -H cpu_mask=0-2 my-inst
578

    
579
      # Map vCPU 0 to physical CPU 1 and vCPU 1 to CPU 3 (assuming 2 vCPUs)
580
      gnt-instance modify -H cpu_mask=1:3 my-inst
581

    
582
      # Pin vCPU 0 to CPUs 1 or 2, and vCPU 1 to any CPU
583
      gnt-instance modify -H cpu_mask=1-2:all my-inst
584

    
585
      # Pin vCPU 0 to any CPU, vCPU 1 to CPUs 1, 3, 4 or 5, and CPU 2 to
586
      # CPU 0 (backslashes for escaping the comma)
587
      gnt-instance modify -H cpu_mask=all:1\\,3-5:0 my-inst
588

    
589
      # Pin entire VM to CPU 0
590
      gnt-instance modify -H cpu_mask=0 my-inst
591

    
592
      # Turn off CPU pinning (default setting)
593
      gnt-instance modify -H cpu_mask=all my-inst
594

    
595
cpu\_cap
596
    Valid for the Xen hypervisor.
597

    
598
    Set the maximum amount of cpu usage by the VM. The value is a percentage
599
    between 0 and (100 * number of VCPUs). Default cap is 0: unlimited.
600

    
601
cpu\_weight
602
    Valid for the Xen hypervisor.
603

    
604
    Set the cpu time ratio to be allocated to the VM. Valid values are
605
    between 1 and 65535. Default weight is 256.
606

    
607
usb\_mouse
608
    Valid for the KVM hypervisor.
609

    
610
    This option specifies the usb mouse type to be used. It can be
611
    "mouse" or "tablet". When using VNC it's recommended to set it to
612
    "tablet".
613

    
614
keymap
615
    Valid for the KVM hypervisor.
616

    
617
    This option specifies the keyboard mapping to be used. It is only
618
    needed when using the VNC console. For example: "fr" or "en-gb".
619

    
620
reboot\_behavior
621
    Valid for Xen PVM, Xen HVM and KVM hypervisors.
622

    
623
    Normally if an instance reboots, the hypervisor will restart it. If
624
    this option is set to ``exit``, the hypervisor will treat a reboot
625
    as a shutdown instead.
626

    
627
    It is set to ``reboot`` by default.
628

    
629

    
630
The ``-O (--os-parameters)`` option allows customisation of the OS
631
parameters. The actual parameter names and values depends on the OS
632
being used, but the syntax is the same key=value. For example, setting
633
a hypothetical ``dhcp`` parameter to yes can be achieved by::
634

    
635
    gnt-instance add -O dhcp=yes ...
636

    
637
The ``-I (--iallocator)`` option specifies the instance allocator plugin
638
to use (``.`` means the default allocator). If you pass in this option
639
the allocator will select nodes for this instance automatically, so you
640
don't need to pass them with the ``-n`` option. For more information
641
please refer to the instance allocator documentation.
642

    
643
The ``-t (--disk-template)`` options specifies the disk layout type
644
for the instance.  The available choices are:
645

    
646
diskless
647
    This creates an instance with no disks. Its useful for testing only
648
    (or other special cases).
649

    
650
file
651
    Disk devices will be regular files.
652

    
653
plain
654
    Disk devices will be logical volumes.
655

    
656
drbd
657
    Disk devices will be drbd (version 8.x) on top of lvm volumes.
658

    
659
rbd
660
    Disk devices will be rbd volumes residing inside a RADOS cluster.
661

    
662

    
663
The optional second value of the ``-n (--node)`` is used for the drbd
664
template type and specifies the remote node.
665

    
666
If you do not want gnt-instance to wait for the disk mirror to be
667
synced, use the ``--no-wait-for-sync`` option.
668

    
669
The ``--file-storage-dir`` specifies the relative path under the
670
cluster-wide file storage directory to store file-based disks. It is
671
useful for having different subdirectories for different
672
instances. The full path of the directory where the disk files are
673
stored will consist of cluster-wide file storage directory + optional
674
subdirectory + instance name. Example:
675
``@RPL_FILE_STORAGE_DIR@``*/mysubdir/instance1.example.com*. This
676
option is only relevant for instances using the file storage backend.
677

    
678
The ``--file-driver`` specifies the driver to use for file-based
679
disks. Note that currently these drivers work with the xen hypervisor
680
only. This option is only relevant for instances using the file
681
storage backend. The available choices are:
682

    
683
loop
684
    Kernel loopback driver. This driver uses loopback devices to
685
    access the filesystem within the file. However, running I/O
686
    intensive applications in your instance using the loop driver
687
    might result in slowdowns. Furthermore, if you use the loopback
688
    driver consider increasing the maximum amount of loopback devices
689
    (on most systems it's 8) using the max\_loop param.
690

    
691
blktap
692
    The blktap driver (for Xen hypervisors). In order to be able to
693
    use the blktap driver you should check if the 'blktapctrl' user
694
    space disk agent is running (usually automatically started via
695
    xend).  This user-level disk I/O interface has the advantage of
696
    better performance. Especially if you use a network file system
697
    (e.g. NFS) to store your instances this is the recommended choice.
698

    
699
If ``--ignore-ipolicy`` is given any instance policy violations occuring
700
during this operation are ignored.
701

    
702
See **ganeti(7)** for a description of ``--submit`` and other common
703
options.
704

    
705
Example::
706

    
707
    # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
708
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
709
    # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
710
      -o debian-etch -n node1.example.com instance1.example.com
711
    # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
712
      -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
713
    # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
714
      -n node1.example.com:node2.example.com instance2.example.com
715

    
716

    
717
BATCH-CREATE
718
^^^^^^^^^^^^
719

    
720
**batch-create** {instances\_file.json}
721

    
722
This command (similar to the Ganeti 1.2 **batcher** tool) submits
723
multiple instance creation jobs based on a definition file. The
724
instance configurations do not encompass all the possible options for
725
the **add** command, but only a subset.
726

    
727
The instance file should be a valid-formed JSON file, containing a
728
dictionary with instance name and instance parameters. The accepted
729
parameters are:
730

    
731
disk\_size
732
    The size of the disks of the instance.
733

    
734
disk\_template
735
    The disk template to use for the instance, the same as in the
736
    **add** command.
737

    
738
backend
739
    A dictionary of backend parameters.
740

    
741
hypervisor
742
    A dictionary with a single key (the hypervisor name), and as value
743
    the hypervisor options. If not passed, the default hypervisor and
744
    hypervisor options will be inherited.
745

    
746
mac, ip, mode, link
747
    Specifications for the one NIC that will be created for the
748
    instance. 'bridge' is also accepted as a backwards compatible
749
    key.
750

    
751
nics
752
    List of nics that will be created for the instance. Each entry
753
    should be a dict, with mac, ip, mode and link as possible keys.
754
    Please don't provide the "mac, ip, mode, link" parent keys if you
755
    use this method for specifying nics.
756

    
757
primary\_node, secondary\_node
758
    The primary and optionally the secondary node to use for the
759
    instance (in case an iallocator script is not used).
760

    
761
iallocator
762
    Instead of specifying the nodes, an iallocator script can be used
763
    to automatically compute them.
764

    
765
start
766
    whether to start the instance
767

    
768
ip\_check
769
    Skip the check for already-in-use instance; see the description in
770
    the **add** command for details.
771

    
772
name\_check
773
    Skip the name check for instances; see the description in the
774
    **add** command for details.
775

    
776
file\_storage\_dir, file\_driver
777
    Configuration for the file disk type, see the **add** command for
778
    details.
779

    
780

    
781
A simple definition for one instance can be (with most of the
782
parameters taken from the cluster defaults)::
783

    
784
    {
785
      "instance3": {
786
        "template": "drbd",
787
        "os": "debootstrap",
788
        "disk_size": ["25G"],
789
        "iallocator": "dumb"
790
      },
791
      "instance5": {
792
        "template": "drbd",
793
        "os": "debootstrap",
794
        "disk_size": ["25G"],
795
        "iallocator": "dumb",
796
        "hypervisor": "xen-hvm",
797
        "hvparams": {"acpi": true},
798
        "backend": {"maxmem": 512, "minmem": 256}
799
      }
800
    }
801

    
802
The command will display the job id for each submitted instance, as
803
follows::
804

    
805
    # gnt-instance batch-create instances.json
806
    instance3: 11224
807
    instance5: 11225
808

    
809
REMOVE
810
^^^^^^
811

    
812
**remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
813
[\--force] {*instance*}
814

    
815
Remove an instance. This will remove all data from the instance and
816
there is *no way back*. If you are not sure if you use an instance
817
again, use **shutdown** first and leave it in the shutdown state for a
818
while.
819

    
820
The ``--ignore-failures`` option will cause the removal to proceed
821
even in the presence of errors during the removal of the instance
822
(e.g. during the shutdown or the disk removal). If this option is not
823
given, the command will stop at the first error.
824

    
825
The ``--shutdown-timeout`` is used to specify how much time to wait
826
before forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the
827
kvm process for KVM, etc.). By default two minutes are given to each
828
instance to stop.
829

    
830
The ``--force`` option is used to skip the interactive confirmation.
831

    
832
See **ganeti(7)** for a description of ``--submit`` and other common
833
options.
834

    
835
Example::
836

    
837
    # gnt-instance remove instance1.example.com
838

    
839

    
840
LIST
841
^^^^
842

    
843
| **list**
844
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
845
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
846

    
847
Shows the currently configured instances with memory usage, disk
848
usage, the node they are running on, and their run status.
849

    
850
The ``--no-headers`` option will skip the initial header line. The
851
``--separator`` option takes an argument which denotes what will be
852
used between the output fields. Both these options are to help
853
scripting.
854

    
855
The units used to display the numeric values in the output varies,
856
depending on the options given. By default, the values will be
857
formatted in the most appropriate unit. If the ``--separator`` option
858
is given, then the values are shown in mebibytes to allow parsing by
859
scripts. In both cases, the ``--units`` option can be used to enforce
860
a given output unit.
861

    
862
The ``-v`` option activates verbose mode, which changes the display of
863
special field states (see **ganeti(7)**).
864

    
865
The ``-o (--output)`` option takes a comma-separated list of output
866
fields. The available fields and their meaning are:
867

    
868
@QUERY_FIELDS_INSTANCE@
869

    
870
If the value of the option starts with the character ``+``, the new
871
field(s) will be added to the default list. This allows one to quickly
872
see the default list plus a few other fields, instead of retyping the
873
entire list of fields.
874

    
875
There is a subtle grouping about the available output fields: all
876
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
877
``status`` are configuration value and not run-time values. So if you
878
don't select any of the these fields, the query will be satisfied
879
instantly from the cluster configuration, without having to ask the
880
remote nodes for the data. This can be helpful for big clusters when
881
you only want some data and it makes sense to specify a reduced set of
882
output fields.
883

    
884
If exactly one argument is given and it appears to be a query filter
885
(see **ganeti(7)**), the query result is filtered accordingly. For
886
ambiguous cases (e.g. a single field name as a filter) the ``--filter``
887
(``-F``) option forces the argument to be treated as a filter (e.g.
888
``gnt-instance list -F admin_state``).
889

    
890
The default output field list is: ``name``, ``os``, ``pnode``,
891
``admin_state``, ``oper_state``, ``oper_ram``.
892

    
893

    
894
LIST-FIELDS
895
~~~~~~~~~~~
896

    
897
**list-fields** [field...]
898

    
899
Lists available fields for instances.
900

    
901

    
902
INFO
903
^^^^
904

    
905
**info** [-s \| \--static] [\--roman] {\--all \| *instance*}
906

    
907
Show detailed information about the given instance(s). This is
908
different from **list** as it shows detailed data about the instance's
909
disks (especially useful for the drbd disk template).
910

    
911
If the option ``-s`` is used, only information available in the
912
configuration file is returned, without querying nodes, making the
913
operation faster.
914

    
915
Use the ``--all`` to get info about all instances, rather than
916
explicitly passing the ones you're interested in.
917

    
918
The ``--roman`` option can be used to cause envy among people who like
919
ancient cultures, but are stuck with non-latin-friendly cluster
920
virtualization technologies.
921

    
922
MODIFY
923
^^^^^^
924

    
925
| **modify**
926
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
927
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
928
| [{-m|\--runtime-memory} *SIZE*]
929
| [\--net add*[:options]* \| \--net [*N*:]remove \| \--net *N:options*]
930
| [\--disk add:size=*SIZE*[,vg=*VG*][,metavg=*VG*] \| \--disk [*N*:]remove \|
931
|  \--disk *N*:mode=*MODE*]
932
| [{-t|\--disk-template} plain | {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
933
| [\--os-type=*OS* [\--force-variant]]
934
| [{-O|\--os-parameters} *param*=*value*... ]
935
| [\--offline \| \--online]
936
| [\--submit]
937
| [\--ignore-ipolicy]
938
| {*instance*}
939

    
940
Modifies the memory size, number of vcpus, ip address, MAC address
941
and/or nic parameters for an instance. It can also add and remove
942
disks and NICs to/from the instance. Note that you need to give at
943
least one of the arguments, otherwise the command complains.
944

    
945
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
946
and ``-O (--os-parameters)`` options specifies hypervisor, backend and
947
OS parameter options in the form of name=value[,...]. For details
948
which options can be specified, see the **add** command.
949

    
950
The ``-t (--disk-template)`` option will change the disk template of
951
the instance.  Currently only conversions between the plain and drbd
952
disk templates are supported, and the instance must be stopped before
953
attempting the conversion. When changing from the plain to the drbd
954
disk template, a new secondary node must be specified via the ``-n``
955
option. The option ``--no-wait-for-sync`` can be used when converting
956
to the ``drbd`` template in order to make the instance available for
957
startup before DRBD has finished resyncing.
958

    
959
The ``-m (--runtime-memory)`` option will change an instance's runtime
960
memory to the given size (in MB if a different suffix is not specified),
961
by ballooning it up or down to the new value.
962

    
963
The ``--disk add:size=``*SIZE* option adds a disk to the instance. The
964
optional ``vg=``*VG* option specifies an LVM volume group other than
965
the default volume group to create the disk on. For DRBD disks, the
966
``metavg=``*VG* option specifies the volume group for the metadata
967
device. ``--disk`` *N*``:add,size=``**SIZE** can be used to add a
968
disk at a specific index. The ``--disk remove`` option will remove the
969
last disk of the instance. Use ``--disk `` *N*``:remove`` to remove a
970
disk by its index. The ``--disk`` *N*``:mode=``*MODE* option will change
971
the mode of the Nth disk of the instance between read-only (``ro``) and
972
read-write (``rw``).
973

    
974
The ``--net add:``*options* and ``--net`` *N*``:add,``*options* option
975
will add a new network interface to the instance. The available options
976
are the same as in the **add** command (``mac``, ``ip``, ``link``,
977
``mode``). The ``--net remove`` will remove the last network interface
978
of the instance (``--net`` *N*``:remove`` for a specific index), while
979
the ``--net`` *N*``:``*options* option will change the parameters of the Nth
980
instance network interface.
981

    
982
The option ``-o (--os-type)`` will change the OS name for the instance
983
(without reinstallation). In case an OS variant is specified that is
984
not found, then by default the modification is refused, unless
985
``--force-variant`` is passed. An invalid OS will also be refused,
986
unless the ``--force`` option is given.
987

    
988
The ``--online`` and ``--offline`` options are used to transition an
989
instance into and out of the ``offline`` state. An instance can be
990
turned offline only if it was previously down. The ``--online`` option
991
fails if the instance was not in the ``offline`` state, otherwise it
992
changes instance's state to ``down``. These modifications take effect
993
immediately.
994

    
995
If ``--ignore-ipolicy`` is given any instance policy violations occuring
996
during this operation are ignored.
997

    
998
See **ganeti(7)** for a description of ``--submit`` and other common
999
options.
1000

    
1001
Most of the changes take effect at the next restart. If the instance is
1002
running, there is no effect on the instance.
1003

    
1004
REINSTALL
1005
^^^^^^^^^
1006

    
1007
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
1008
| [\--force-multiple]
1009
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1010
| [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] {*instance*...}
1011

    
1012
Reinstalls the operating system on the given instance(s). The
1013
instance(s) must be stopped when running this command. If the ``-o
1014
(--os-type)`` is specified, the operating system is changed.
1015

    
1016
The ``--select-os`` option switches to an interactive OS reinstall.
1017
The user is prompted to select the OS template from the list of
1018
available OS templates. OS parameters can be overridden using ``-O
1019
(--os-parameters)`` (more documentation for this option under the
1020
**add** command).
1021

    
1022
Since this is a potentially dangerous command, the user will be
1023
required to confirm this action, unless the ``-f`` flag is passed.
1024
When multiple instances are selected (either by passing multiple
1025
arguments or by using the ``--node``, ``--primary``, ``--secondary``
1026
or ``--all`` options), the user must pass the ``--force-multiple``
1027
options to skip the interactive confirmation.
1028

    
1029
See **ganeti(7)** for a description of ``--submit`` and other common
1030
options.
1031

    
1032
RENAME
1033
^^^^^^
1034

    
1035
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit]
1036
| {*instance*} {*new\_name*}
1037

    
1038
Renames the given instance. The instance must be stopped when running
1039
this command. The requirements for the new name are the same as for
1040
adding an instance: the new name must be resolvable and the IP it
1041
resolves to must not be reachable (in order to prevent duplicate IPs
1042
the next time the instance is started). The IP test can be skipped if
1043
the ``--no-ip-check`` option is passed.
1044

    
1045
The ``--no-name-check`` skips the check for the new instance name via
1046
the resolver (e.g. in DNS or /etc/hosts, depending on your setup) and
1047
that the resolved name matches the provided name. Since the name check
1048
is used to compute the IP address, if you pass this option you must also
1049
pass the ``--no-ip-check`` option.
1050

    
1051
See **ganeti(7)** for a description of ``--submit`` and other common
1052
options.
1053

    
1054
Starting/stopping/connecting to console
1055
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1056

    
1057
STARTUP
1058
^^^^^^^
1059

    
1060
| **startup**
1061
| [\--force] [\--ignore-offline]
1062
| [\--force-multiple] [\--no-remember]
1063
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1064
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1065
| [{-H|\--hypervisor-parameters} ``key=value...``]
1066
| [{-B|\--backend-parameters} ``key=value...``]
1067
| [\--submit] [\--paused]
1068
| {*name*...}
1069

    
1070
Starts one or more instances, depending on the following options.  The
1071
four available modes are:
1072

    
1073
\--instance
1074
    will start the instances given as arguments (at least one argument
1075
    required); this is the default selection
1076

    
1077
\--node
1078
    will start the instances who have the given node as either primary
1079
    or secondary
1080

    
1081
\--primary
1082
    will start all instances whose primary node is in the list of nodes
1083
    passed as arguments (at least one node required)
1084

    
1085
\--secondary
1086
    will start all instances whose secondary node is in the list of
1087
    nodes passed as arguments (at least one node required)
1088

    
1089
\--all
1090
    will start all instances in the cluster (no arguments accepted)
1091

    
1092
\--tags
1093
    will start all instances in the cluster with the tags given as
1094
    arguments
1095

    
1096
\--node-tags
1097
    will start all instances in the cluster on nodes with the tags
1098
    given as arguments
1099

    
1100
\--pri-node-tags
1101
    will start all instances in the cluster on primary nodes with the
1102
    tags given as arguments
1103

    
1104
\--sec-node-tags
1105
    will start all instances in the cluster on secondary nodes with the
1106
    tags given as arguments
1107

    
1108
Note that although you can pass more than one selection option, the
1109
last one wins, so in order to guarantee the desired result, don't pass
1110
more than one such option.
1111

    
1112
Use ``--force`` to start even if secondary disks are failing.
1113
``--ignore-offline`` can be used to ignore offline primary nodes and
1114
mark the instance as started even if the primary is not available.
1115

    
1116
The ``--force-multiple`` will skip the interactive confirmation in the
1117
case the more than one instance will be affected.
1118

    
1119
The ``--no-remember`` option will perform the startup but not change
1120
the state of the instance in the configuration file (if it was stopped
1121
before, Ganeti will still think it needs to be stopped). This can be
1122
used for testing, or for a one shot-start where you don't want the
1123
watcher to restart the instance if it crashes.
1124

    
1125
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
1126
options specify temporary hypervisor and backend parameters that can
1127
be used to start an instance with modified parameters. They can be
1128
useful for quick testing without having to modify an instance back and
1129
forth, e.g.::
1130

    
1131
    # gnt-instance start -H kernel_args="single" instance1
1132
    # gnt-instance start -B maxmem=2048 instance2
1133

    
1134

    
1135
The first form will start the instance instance1 in single-user mode,
1136
and the instance instance2 with 2GB of RAM (this time only, unless
1137
that is the actual instance memory size already). Note that the values
1138
override the instance parameters (and not extend them): an instance
1139
with "kernel\_args=ro" when started with -H kernel\_args=single will
1140
result in "single", not "ro single".
1141

    
1142
The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
1143
pauses the instance at the start of bootup, awaiting ``gnt-instance
1144
console`` to unpause it, allowing the entire boot process to be
1145
monitored for debugging.
1146

    
1147
See **ganeti(7)** for a description of ``--submit`` and other common
1148
options.
1149

    
1150
Example::
1151

    
1152
    # gnt-instance start instance1.example.com
1153
    # gnt-instance start --node node1.example.com node2.example.com
1154
    # gnt-instance start --all
1155

    
1156

    
1157
SHUTDOWN
1158
^^^^^^^^
1159

    
1160
| **shutdown**
1161
| [\--timeout=*N*]
1162
| [\--force-multiple] [\--ignore-offline] [\--no-remember]
1163
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1164
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1165
| [\--submit]
1166
| {*name*...}
1167

    
1168
Stops one or more instances. If the instance cannot be cleanly stopped
1169
during a hardcoded interval (currently 2 minutes), it will forcibly
1170
stop the instance (equivalent to switching off the power on a physical
1171
machine).
1172

    
1173
The ``--timeout`` is used to specify how much time to wait before
1174
forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the kvm
1175
process for KVM, etc.). By default two minutes are given to each
1176
instance to stop.
1177

    
1178
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1179
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1180
``--sec-node-tags`` options are similar as for the **startup** command
1181
and they influence the actual instances being shutdown.
1182

    
1183
``--ignore-offline`` can be used to ignore offline primary nodes and
1184
force the instance to be marked as stopped. This option should be used
1185
with care as it can lead to an inconsistent cluster state.
1186

    
1187
The ``--no-remember`` option will perform the shutdown but not change
1188
the state of the instance in the configuration file (if it was running
1189
before, Ganeti will still thinks it needs to be running). This can be
1190
useful for a cluster-wide shutdown, where some instances are marked as
1191
up and some as down, and you don't want to change the running state:
1192
you just need to disable the watcher, shutdown all instances with
1193
``--no-remember``, and when the watcher is activated again it will
1194
restore the correct runtime state for all instances.
1195

    
1196
See **ganeti(7)** for a description of ``--submit`` and other common
1197
options.
1198

    
1199
Example::
1200

    
1201
    # gnt-instance shutdown instance1.example.com
1202
    # gnt-instance shutdown --all
1203

    
1204

    
1205
REBOOT
1206
^^^^^^
1207

    
1208
| **reboot**
1209
| [{-t|\--type} *REBOOT-TYPE*]
1210
| [\--ignore-secondaries]
1211
| [\--shutdown-timeout=*N*]
1212
| [\--force-multiple]
1213
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1214
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1215
| [\--submit]
1216
| [*name*...]
1217

    
1218
Reboots one or more instances. The type of reboot depends on the value
1219
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1220
does a instance stop, recreates the hypervisor config for the instance
1221
and starts the instance. A full reboot does the equivalent of
1222
**gnt-instance shutdown && gnt-instance startup**.  The default is
1223
hard reboot.
1224

    
1225
For the hard reboot the option ``--ignore-secondaries`` ignores errors
1226
for the secondary node while re-assembling the instance disks.
1227

    
1228
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1229
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1230
``--sec-node-tags`` options are similar as for the **startup** command
1231
and they influence the actual instances being rebooted.
1232

    
1233
The ``--shutdown-timeout`` is used to specify how much time to wait
1234
before forcing the shutdown (xm destroy in xen, killing the kvm
1235
process, for kvm). By default two minutes are given to each instance
1236
to stop.
1237

    
1238
The ``--force-multiple`` will skip the interactive confirmation in the
1239
case the more than one instance will be affected.
1240

    
1241
See **ganeti(7)** for a description of ``--submit`` and other common
1242
options.
1243

    
1244
Example::
1245

    
1246
    # gnt-instance reboot instance1.example.com
1247
    # gnt-instance reboot --type=full instance1.example.com
1248

    
1249

    
1250
CONSOLE
1251
^^^^^^^
1252

    
1253
**console** [\--show-cmd] {*instance*}
1254

    
1255
Connects to the console of the given instance. If the instance is not
1256
up, an error is returned. Use the ``--show-cmd`` option to display the
1257
command instead of executing it.
1258

    
1259
For HVM instances, this will attempt to connect to the serial console
1260
of the instance. To connect to the virtualized "physical" console of a
1261
HVM instance, use a VNC client with the connection info from the
1262
**info** command.
1263

    
1264
For Xen/kvm instances, if the instance is paused, this attempts to
1265
unpause the instance after waiting a few seconds for the connection to
1266
the console to be made.
1267

    
1268
Example::
1269

    
1270
    # gnt-instance console instance1.example.com
1271

    
1272

    
1273
Disk management
1274
~~~~~~~~~~~~~~~
1275

    
1276
REPLACE-DISKS
1277
^^^^^^^^^^^^^
1278

    
1279
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-p}
1280
[\--disks *idx*] {*instance*}
1281

    
1282
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-s}
1283
[\--disks *idx*] {*instance*}
1284

    
1285
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1286
{{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*}
1287

    
1288
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1289
{-a\|\--auto} {*instance*}
1290

    
1291
This command is a generalized form for replacing disks. It is
1292
currently only valid for the mirrored (DRBD) disk template.
1293

    
1294
The first form (when passing the ``-p`` option) will replace the disks
1295
on the primary, while the second form (when passing the ``-s`` option
1296
will replace the disks on the secondary node. For these two cases (as
1297
the node doesn't change), it is possible to only run the replace for a
1298
subset of the disks, using the option ``--disks`` which takes a list
1299
of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only
1300
the first and third disks.
1301

    
1302
The third form (when passing either the ``--iallocator`` or the
1303
``--new-secondary`` option) is designed to change secondary node of the
1304
instance. Specifying ``--iallocator`` makes the new secondary be
1305
selected automatically by the specified allocator plugin (use ``.`` to
1306
indicate the default allocator), otherwise the new secondary node will
1307
be the one chosen manually via the ``--new-secondary`` option.
1308

    
1309
Note that it is not possible to select an offline or drained node as a
1310
new secondary.
1311

    
1312
The fourth form (when using ``--auto``) will automatically determine
1313
which disks of an instance are faulty and replace them within the same
1314
node. The ``--auto`` option works only when an instance has only
1315
faulty disks on either the primary or secondary node; it doesn't work
1316
when both sides have faulty disks.
1317

    
1318
The ``--early-release`` changes the code so that the old storage on
1319
secondary node(s) is removed early (before the resync is completed)
1320
and the internal Ganeti locks for the current (and new, if any)
1321
secondary node are also released, thus allowing more parallelism in
1322
the cluster operation. This should be used only when recovering from a
1323
disk failure on the current secondary (thus the old storage is already
1324
broken) or when the storage on the primary node is known to be fine
1325
(thus we won't need the old storage for potential recovery).
1326

    
1327
The ``--ignore-ipolicy`` let the command ignore instance policy
1328
violations if replace-disks changes groups and the instance would
1329
violate the new groups instance policy.
1330

    
1331
See **ganeti(7)** for a description of ``--submit`` and other common
1332
options.
1333

    
1334
ACTIVATE-DISKS
1335
^^^^^^^^^^^^^^
1336

    
1337
**activate-disks** [\--submit] [\--ignore-size] [\--wait-for-sync] {*instance*}
1338

    
1339
Activates the block devices of the given instance. If successful, the
1340
command will show the location and name of the block devices::
1341

    
1342
    node1.example.com:disk/0:/dev/drbd0
1343
    node1.example.com:disk/1:/dev/drbd1
1344

    
1345

    
1346
In this example, *node1.example.com* is the name of the node on which
1347
the devices have been activated. The *disk/0* and *disk/1* are the
1348
Ganeti-names of the instance disks; how they are visible inside the
1349
instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the
1350
actual block devices as visible on the node.
1351

    
1352
The ``--ignore-size`` option can be used to activate disks ignoring
1353
the currently configured size in Ganeti. This can be used in cases
1354
where the configuration has gotten out of sync with the real-world
1355
(e.g. after a partially-failed grow-disk operation or due to rounding
1356
in LVM devices). This should not be used in normal cases, but only
1357
when activate-disks fails without it.
1358

    
1359
The ``--wait-for-sync`` option will ensure that the command returns only
1360
after the instance's disks are synchronised (mostly for DRBD); this can
1361
be useful to ensure consistency, as otherwise there are no commands that
1362
can wait until synchronisation is done. However when passing this
1363
option, the command will have additional output, making it harder to
1364
parse the disk information.
1365

    
1366
Note that it is safe to run this command while the instance is already
1367
running.
1368

    
1369
See **ganeti(7)** for a description of ``--submit`` and other common
1370
options.
1371

    
1372
DEACTIVATE-DISKS
1373
^^^^^^^^^^^^^^^^
1374

    
1375
**deactivate-disks** [-f] [\--submit] {*instance*}
1376

    
1377
De-activates the block devices of the given instance. Note that if you
1378
run this command for an instance with a drbd disk template, while it
1379
is running, it will not be able to shutdown the block devices on the
1380
primary node, but it will shutdown the block devices on the secondary
1381
nodes, thus breaking the replication.
1382

    
1383
The ``-f``/``--force`` option will skip checks that the instance is
1384
down; in case the hypervisor is confused and we can't talk to it,
1385
normally Ganeti will refuse to deactivate the disks, but with this
1386
option passed it will skip this check and directly try to deactivate
1387
the disks. This can still fail due to the instance actually running or
1388
other issues.
1389

    
1390
See **ganeti(7)** for a description of ``--submit`` and other common
1391
options.
1392

    
1393
GROW-DISK
1394
^^^^^^^^^
1395

    
1396
| **grow-disk** [\--no-wait-for-sync] [\--submit] [\--absolute]
1397
| {*instance*} {*disk*} {*amount*}
1398

    
1399
Grows an instance's disk. This is only possible for instances having a
1400
plain, drbd or rbd disk template.
1401

    
1402
Note that this command only change the block device size; it will not
1403
grow the actual filesystems, partitions, etc. that live on that
1404
disk. Usually, you will need to:
1405

    
1406
#. use **gnt-instance grow-disk**
1407

    
1408
#. reboot the instance (later, at a convenient time)
1409

    
1410
#. use a filesystem resizer, such as ext2online(8) or
1411
   xfs\_growfs(8) to resize the filesystem, or use fdisk(8) to change
1412
   the partition table on the disk
1413

    
1414
The *disk* argument is the index of the instance disk to grow. The
1415
*amount* argument is given as a number which can have a suffix (like the
1416
disk size in instance create); if the suffix is missing, the value will
1417
be interpreted as mebibytes.
1418

    
1419
By default, the *amount* value represents the desired increase in the
1420
disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If
1421
the optional ``--absolute`` parameter is passed, then the *amount*
1422
argument doesn't represent the delta, but instead the desired final disk
1423
size (e.g. an amount of 8G will take a disk of size 4G to 8G).
1424

    
1425
For instances with a drbd template, note that the disk grow operation
1426
might complete on one node but fail on the other; this will leave the
1427
instance with different-sized LVs on the two nodes, but this will not
1428
create problems (except for unused space).
1429

    
1430
If you do not want gnt-instance to wait for the new disk region to be
1431
synced, use the ``--no-wait-for-sync`` option.
1432

    
1433
See **ganeti(7)** for a description of ``--submit`` and other common
1434
options.
1435

    
1436
Example (increase the first disk for instance1 by 16GiB)::
1437

    
1438
    # gnt-instance grow-disk instance1.example.com 0 16g
1439

    
1440
Example for increasing the disk size to a certain size::
1441

    
1442
   # gnt-instance grow-disk --absolute instance1.example.com 0 32g
1443

    
1444
Also note that disk shrinking is not supported; use **gnt-backup
1445
export** and then **gnt-backup import** to reduce the disk size of an
1446
instance.
1447

    
1448
RECREATE-DISKS
1449
^^^^^^^^^^^^^^
1450

    
1451
| **recreate-disks** [\--submit]
1452
| [{-n node1:[node2] \| {-I\|\--iallocator *name*}}]
1453
| [\--disk=*N*[:[size=*VAL*][,mode=*ro\|rw*]]] {*instance*}
1454

    
1455
Recreates all or a subset of disks of the given instance.
1456

    
1457
Note that this functionality should only be used for missing disks; if
1458
any of the given disks already exists, the operation will fail.  While
1459
this is suboptimal, recreate-disks should hopefully not be needed in
1460
normal operation and as such the impact of this is low.
1461

    
1462
If only a subset should be recreated, any number of ``disk`` options can
1463
be specified. It expects a disk index and an optional list of disk
1464
parameters to change. Only ``size`` and ``mode`` can be changed while
1465
recreating disks. To recreate all disks while changing parameters on
1466
a subset only, a ``--disk`` option must be given for every disk of the
1467
instance.
1468

    
1469
Optionally the instance's disks can be recreated on different
1470
nodes. This can be useful if, for example, the original nodes of the
1471
instance have gone down (and are marked offline), so we can't recreate
1472
on the same nodes. To do this, pass the new node(s) via ``-n`` option,
1473
with a syntax similar to the **add** command. The number of nodes
1474
passed must equal the number of nodes that the instance currently
1475
has. Note that changing nodes is only allowed when all disks are
1476
replaced, e.g. when no ``--disk`` option is passed.
1477

    
1478
Another method of choosing which nodes to place the instance on is by
1479
using the specified iallocator, passing the ``--iallocator`` option.
1480
The primary and secondary nodes will be chosen by the specified
1481
iallocator plugin, or by the default allocator if ``.`` is specified.
1482

    
1483
See **ganeti(7)** for a description of ``--submit`` and other common
1484
options.
1485

    
1486
Recovery
1487
~~~~~~~~
1488

    
1489
FAILOVER
1490
^^^^^^^^
1491

    
1492
| **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy]
1493
| [\--shutdown-timeout=*N*]
1494
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*]
1495
| [\--submit]
1496
| {*instance*}
1497

    
1498
Failover will stop the instance (if running), change its primary node,
1499
and if it was originally running it will start it again (on the new
1500
primary). This only works for instances with drbd template (in which
1501
case you can only fail to the secondary node) and for externally
1502
mirrored templates (blockdev and rbd) (which can change to any other
1503
node).
1504

    
1505
If the instance's disk template is of type blockdev or rbd, then you
1506
can explicitly specify the target node (which can be any node) using
1507
the ``-n`` or ``--target-node`` option, or specify an iallocator plugin
1508
using the ``-I`` or ``--iallocator`` option. If you omit both, the default
1509
iallocator will be used to specify the target node.
1510

    
1511
Normally the failover will check the consistency of the disks before
1512
failing over the instance. If you are trying to migrate instances off
1513
a dead node, this will fail. Use the ``--ignore-consistency`` option
1514
for this purpose. Note that this option can be dangerous as errors in
1515
shutting down the instance will be ignored, resulting in possibly
1516
having the instance running on two machines in parallel (on
1517
disconnected DRBD drives).
1518

    
1519
The ``--shutdown-timeout`` is used to specify how much time to wait
1520
before forcing the shutdown (xm destroy in xen, killing the kvm
1521
process, for kvm). By default two minutes are given to each instance
1522
to stop.
1523

    
1524
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1525
during this operation are ignored.
1526

    
1527
See **ganeti(7)** for a description of ``--submit`` and other common
1528
options.
1529

    
1530
Example::
1531

    
1532
    # gnt-instance failover instance1.example.com
1533

    
1534

    
1535
MIGRATE
1536
^^^^^^^
1537

    
1538
| **migrate** [-f] [\--allow-failover] [\--non-live]
1539
| [\--migration-mode=live\|non-live] [\--ignore-ipolicy]
1540
| [\--no-runtime-changes] [\--submit]
1541
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*}
1542

    
1543
| **migrate** [-f] \--cleanup [\--submit] {*instance*}
1544

    
1545
Migrate will move the instance to its secondary node without shutdown.
1546
As with failover, it only works for instances having the drbd disk
1547
template or an externally mirrored disk template type such as blockdev
1548
or rbd.
1549

    
1550
If the instance's disk template is of type blockdev or rbd, then you can
1551
explicitly specify the target node (which can be any node) using the
1552
``-n`` or ``--target-node`` option, or specify an iallocator plugin
1553
using the ``-I`` or ``--iallocator`` option. If you omit both, the
1554
default iallocator will be used to specify the target node.
1555
Alternatively, the default iallocator can be requested by specifying
1556
``.`` as the name of the plugin.
1557

    
1558
The migration command needs a perfectly healthy instance, as we rely
1559
on the dual-master capability of drbd8 and the disks of the instance
1560
are not allowed to be degraded.
1561

    
1562
The ``--non-live`` and ``--migration-mode=non-live`` options will
1563
switch (for the hypervisors that support it) between a "fully live"
1564
(i.e. the interruption is as minimal as possible) migration and one in
1565
which the instance is frozen, its state saved and transported to the
1566
remote node, and then resumed there. This all depends on the
1567
hypervisor support for two different methods. In any case, it is not
1568
an error to pass this parameter (it will just be ignored if the
1569
hypervisor doesn't support it). The option ``--migration-mode=live``
1570
option will request a fully-live migration. The default, when neither
1571
option is passed, depends on the hypervisor parameters (and can be
1572
viewed with the **gnt-cluster info** command).
1573

    
1574
If the ``--cleanup`` option is passed, the operation changes from
1575
migration to attempting recovery from a failed previous migration.  In
1576
this mode, Ganeti checks if the instance runs on the correct node (and
1577
updates its configuration if not) and ensures the instances' disks
1578
are configured correctly. In this mode, the ``--non-live`` option is
1579
ignored.
1580

    
1581
The option ``-f`` will skip the prompting for confirmation.
1582

    
1583
If ``--allow-failover`` is specified it tries to fallback to failover if
1584
it already can determine that a migration won't work (e.g. if the
1585
instance is shut down). Please note that the fallback will not happen
1586
during execution. If a migration fails during execution it still fails.
1587

    
1588
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1589
during this operation are ignored.
1590

    
1591
The ``--no-runtime-changes`` option forbids migrate to alter an
1592
instance's runtime before migrating it (eg. ballooning an instance
1593
down because the target node doesn't have enough available memory).
1594

    
1595
If an instance has the backend parameter ``always\_failover`` set to
1596
true, then the migration is automatically converted into a failover.
1597

    
1598
See **ganeti(7)** for a description of ``--submit`` and other common
1599
options.
1600

    
1601
Example (and expected output)::
1602

    
1603
    # gnt-instance migrate instance1
1604
    Instance instance1 will be migrated. Note that migration
1605
    might impact the instance if anything goes wrong (e.g. due to bugs in
1606
    the hypervisor). Continue?
1607
    y/[n]/?: y
1608
    Migrating instance instance1.example.com
1609
    * checking disk consistency between source and target
1610
    * switching node node2.example.com to secondary mode
1611
    * changing into standalone mode
1612
    * changing disks into dual-master mode
1613
    * wait until resync is done
1614
    * preparing node2.example.com to accept the instance
1615
    * migrating instance to node2.example.com
1616
    * switching node node1.example.com to secondary mode
1617
    * wait until resync is done
1618
    * changing into standalone mode
1619
    * changing disks into single-master mode
1620
    * wait until resync is done
1621
    * done
1622
    #
1623

    
1624

    
1625
MOVE
1626
^^^^
1627

    
1628
| **move** [-f] [\--ignore-consistency]
1629
| [-n *node*] [\--shutdown-timeout=*N*] [\--submit] [\--ignore-ipolicy]
1630
| {*instance*}
1631

    
1632
Move will move the instance to an arbitrary node in the cluster.  This
1633
works only for instances having a plain or file disk template.
1634

    
1635
Note that since this operation is done via data copy, it will take a
1636
long time for big disks (similar to replace-disks for a drbd
1637
instance).
1638

    
1639
The ``--shutdown-timeout`` is used to specify how much time to wait
1640
before forcing the shutdown (e.g. ``xm destroy`` in XEN, killing the
1641
kvm process for KVM, etc.). By default two minutes are given to each
1642
instance to stop.
1643

    
1644
The ``--ignore-consistency`` option will make Ganeti ignore any errors
1645
in trying to shutdown the instance on its node; useful if the
1646
hypervisor is broken and you want to recuperate the data.
1647

    
1648
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1649
during this operation are ignored.
1650

    
1651
See **ganeti(7)** for a description of ``--submit`` and other common
1652
options.
1653

    
1654
Example::
1655

    
1656
    # gnt-instance move -n node3.example.com instance1.example.com
1657

    
1658

    
1659
CHANGE-GROUP
1660
~~~~~~~~~~~~
1661

    
1662
| **change-group** [\--submit]
1663
| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
1664

    
1665
This command moves an instance to another node group. The move is
1666
calculated by an iallocator, either given on the command line or as a
1667
cluster default.
1668

    
1669
If no specific destination groups are specified using ``--to``, all
1670
groups except the one containing the instance are considered.
1671

    
1672
See **ganeti(7)** for a description of ``--submit`` and other common
1673
options.
1674

    
1675
Example::
1676

    
1677
    # gnt-instance change-group -I hail --to rack2 inst1.example.com
1678

    
1679

    
1680
TAGS
1681
~~~~
1682

    
1683
ADD-TAGS
1684
^^^^^^^^
1685

    
1686
**add-tags** [\--from *file*] {*instancename*} {*tag*...}
1687

    
1688
Add tags to the given instance. If any of the tags contains invalid
1689
characters, the entire operation will abort.
1690

    
1691
If the ``--from`` option is given, the list of tags will be extended
1692
with the contents of that file (each line becomes a tag).  In this
1693
case, there is not need to pass tags on the command line (if you do,
1694
both sources will be used). A file name of ``-`` will be interpreted
1695
as stdin.
1696

    
1697
LIST-TAGS
1698
^^^^^^^^^
1699

    
1700
**list-tags** {*instancename*}
1701

    
1702
List the tags of the given instance.
1703

    
1704
REMOVE-TAGS
1705
^^^^^^^^^^^
1706

    
1707
**remove-tags** [\--from *file*] {*instancename*} {*tag*...}
1708

    
1709
Remove tags from the given instance. If any of the tags are not
1710
existing on the node, the entire operation will abort.
1711

    
1712
If the ``--from`` option is given, the list of tags to be removed will
1713
be extended with the contents of that file (each line becomes a tag).
1714
In this case, there is not need to pass tags on the command line (if
1715
you do, tags from both sources will be removed). A file name of ``-``
1716
will be interpreted as stdin.
1717

    
1718
.. vim: set textwidth=72 :
1719
.. Local Variables:
1720
.. mode: rst
1721
.. fill-column: 72
1722
.. End: