Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.rst @ 06c2fb4a

History | View | Annotate | Download (71.4 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*}[,options...]
32
|  \| {size=*VAL*,provider=*PROVIDER*}[,param=*value*... ][,options...]
33
|  \| {-s|\--os-size} *SIZE*}
34
| [\--no-ip-check] [\--no-name-check] [\--no-conflicts-check]
35
| [\--no-start] [\--no-install]
36
| [\--net=*N* [:options...] \| \--no-nics]
37
| [{-B|\--backend-parameters} *BEPARAMS*]
38
| [{-H|\--hypervisor-parameters} *HYPERVISOR* [: option=*value*... ]]
39
| [{-O|\--os-parameters} *param*=*value*... ]
40
| [\--file-storage-dir *dir\_path*] [\--file-driver {loop \| blktap \| blktap2}]
41
| {{-n|\--node} *node[:secondary-node]* \| {-I|\--iallocator} *name*}
42
| {{-o|\--os-type} *os-type*}
43
| [\--submit]
44
| [\--ignore-ipolicy]
45
| {*instance*}
46

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

    
51
The ``disk`` option specifies the parameters for the disks of the
52
instance. The numbering of disks starts at zero, and at least one disk
53
needs to be passed. For each disk, either the size or the adoption
54
source needs to be given. The size is interpreted (when no unit is
55
given) in mebibytes. You can also use one of the suffixes *m*, *g* or
56
*t* to specify the exact the units used; these suffixes map to
57
mebibytes, gibibytes and tebibytes. Each disk can also take these
58
parameters (all optional):
59

    
60
mode
61
  The access mode. Either ``ro`` (read-only) or the default ``rw``
62
  (read-write).
63

    
64
name
65
   this option specifies a name for the disk, which can be used as a disk
66
   identifier. An instance can not have two disks with the same name.
67

    
68
vg
69
   The LVM volume group. This works only for LVM and DRBD devices.
70

    
71
metavg
72
   This options specifies a different VG for the metadata device. This
73
   works only for DRBD devices
74

    
75
When creating ExtStorage disks, also arbitrary parameters can be passed,
76
to the ExtStorage provider. Those parameters are passed as additional
77
comma separated options. Therefore, an ExtStorage disk provided by
78
provider ``pvdr1`` with parameters ``param1``, ``param2`` would be
79
passed as ``--disk 0:size=10G,provider=pvdr1,param1=val1,param2=val2``.
80

    
81
When using the ``adopt`` key in the disk definition, Ganeti will
82
reuse those volumes (instead of creating new ones) as the
83
instance's disks. Ganeti will rename these volumes to the standard
84
format, and (without installing the OS) will use them as-is for the
85
instance. This allows migrating instances from non-managed mode
86
(e.g. plain KVM with LVM) to being managed via Ganeti. Please note that
87
this works only for the \`plain' disk template (see below for
88
template details).
89

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

    
94
The minimum disk specification is therefore ``--disk 0:size=20G`` (or
95
``-s 20G`` when using the ``-s`` option), and a three-disk instance
96
can be specified as ``--disk 0:size=20G --disk 1:size=4G --disk
97
2:size=100G``.
98

    
99
The minimum information needed to specify an ExtStorage disk are the
100
``size`` and the ``provider``. For example:
101
``--disk 0:size=20G,provider=pvdr1``.
102

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

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

    
112
If you don't want the instance to automatically start after
113
creation, this is possible via the ``--no-start`` option. This will
114
leave the instance down until a subsequent **gnt-instance start**
115
command.
116

    
117
The NICs of the instances can be specified via the ``--net``
118
option. By default, one NIC is created for the instance, with a
119
random MAC, and set up according the the cluster level NIC
120
parameters. Each NIC can take these parameters (all optional):
121

    
122
mac
123
    either a value or 'generate' to generate a new unique MAC
124

    
125
ip
126
    specifies the IP address assigned to the instance from the Ganeti
127
    side (this is not necessarily what the instance will use, but what
128
    the node expects the instance to use). Note that if an IP in the
129
    range of a network configured with **gnt-network**\(8) is used,
130
    and the NIC is not already connected to it, this network has to be
131
    passed in the **network** parameter if this NIC is meant to be
132
    connected to the said network. ``--no-conflicts-check`` can be used
133
    to override this check. The special value **pool** causes Ganeti to
134
    select an IP from the the network the NIC is or will be connected to.
135
    One can pick an externally reserved IP of a network along with
136
    ``--no-conflict-check``. Note that this IP cannot be assigned to
137
    any other instance until it gets released.
138

    
139
mode
140
    specifies the connection mode for this NIC: routed, bridged or
141
    openvswitch.
142

    
143
link
144
    in bridged or openvswitch mode specifies the interface to attach
145
    this NIC to, in routed mode it's intended to differentiate between
146
    different routing tables/instance groups (but the meaning is
147
    dependent on the network script, see **gnt-cluster**\(8) for more
148
    details). Note that openvswitch support is also hypervisor
149
    dependent.
150

    
151
network
152
    derives the mode and the link from the settings of the network
153
    which is identified by its name. If the network option is chosen,
154
    link and mode must not be specified. Note that the mode and link
155
    depend on the network-to-nodegroup connection, thus allowing
156
    different nodegroups to be connected to the same network in
157
    different ways.
158

    
159
name
160
   this option specifies a name for the NIC, which can be used as a NIC
161
   identifier. An instance can not have two NICs with the same name.
162

    
163

    
164
Of these "mode" and "link" are NIC parameters, and inherit their
165
default at cluster level.  Alternatively, if no network is desired for
166
the instance, you can prevent the default of one NIC with the
167
``--no-nics`` option.
168

    
169
The ``-o (--os-type)`` option specifies the operating system to be
170
installed.  The available operating systems can be listed with
171
**gnt-os list**.  Passing ``--no-install`` will however skip the OS
172
installation, allowing a manual import if so desired. Note that the
173
no-installation mode will automatically disable the start-up of the
174
instance (without an OS, it most likely won't be able to start-up
175
successfully).
176

    
177
The ``-B (--backend-parameters)`` option specifies the backend
178
parameters for the instance. If no such parameters are specified, the
179
values are inherited from the cluster. Possible parameters are:
180

    
181
maxmem
182
    the maximum memory size of the instance; as usual, suffixes can be
183
    used to denote the unit, otherwise the value is taken in mebibytes
184

    
185
minmem
186
    the minimum memory size of the instance; as usual, suffixes can be
187
    used to denote the unit, otherwise the value is taken in mebibytes
188

    
189
vcpus
190
    the number of VCPUs to assign to the instance (if this value makes
191
    sense for the hypervisor)
192

    
193
auto\_balance
194
    whether the instance is considered in the N+1 cluster checks
195
    (enough redundancy in the cluster to survive a node failure)
196

    
197
always\_failover
198
    ``True`` or ``False``, whether the instance must be failed over
199
    (shut down and rebooted) always or it may be migrated (briefly
200
    suspended)
201

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

    
208
The ``-H (--hypervisor-parameters)`` option specified the hypervisor
209
to use for the instance (must be one of the enabled hypervisors on the
210
cluster) and optionally custom parameters for this instance. If not
211
other options are used (i.e. the invocation is just -H *NAME*) the
212
instance will inherit the cluster options. The defaults below show the
213
cluster defaults at cluster creation time.
214

    
215
The possible hypervisor options are as follows:
216

    
217
boot\_order
218
    Valid for the Xen HVM and KVM hypervisors.
219

    
220
    A string value denoting the boot order. This has different meaning
221
    for the Xen HVM hypervisor and for the KVM one.
222

    
223
    For Xen HVM, The boot order is a string of letters listing the boot
224
    devices, with valid device letters being:
225

    
226
    a
227
        floppy drive
228

    
229
    c
230
        hard disk
231

    
232
    d
233
        CDROM drive
234

    
235
    n
236
        network boot (PXE)
237

    
238
    The default is not to set an HVM boot order, which is interpreted
239
    as 'dc'.
240

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

    
248
blockdev\_prefix
249
    Valid for the Xen HVM and PVM hypervisors.
250

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

    
255
floppy\_image\_path
256
    Valid for the KVM hypervisor.
257

    
258
    The path to a floppy disk image to attach to the instance.  This
259
    is useful to install Windows operating systems on Virt/IO disks
260
    because you can specify here the floppy for the drivers at
261
    installation time.
262

    
263
cdrom\_image\_path
264
    Valid for the Xen HVM and KVM hypervisors.
265

    
266
    The path to a CDROM image to attach to the instance.
267

    
268
cdrom2\_image\_path
269
    Valid for the KVM hypervisor.
270

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

    
275
nic\_type
276
    Valid for the Xen HVM and KVM hypervisors.
277

    
278
    This parameter determines the way the network cards are presented
279
    to the instance. The possible options are:
280

    
281
    - rtl8139 (default for Xen HVM) (HVM & KVM)
282
    - ne2k\_isa (HVM & KVM)
283
    - ne2k\_pci (HVM & KVM)
284
    - i82551 (KVM)
285
    - i82557b (KVM)
286
    - i82559er (KVM)
287
    - pcnet (KVM)
288
    - e1000 (KVM)
289
    - paravirtual (default for KVM) (HVM & KVM)
290

    
291
vif\_type
292
    Valid for the Xen HVM hypervisor.
293

    
294
    This parameter specifies the vif type of the nic configuration
295
    of the instance. Unsetting the value leads to no type being specified
296
    in the configuration. Note that this parameter only takes effect when
297
    the 'nic_type' is not set. The possible options are:
298

    
299
    - ioemu
300
    - vif
301

    
302
disk\_type
303
    Valid for the Xen HVM and KVM hypervisors.
304

    
305
    This parameter determines the way the disks are presented to the
306
    instance. The possible options are:
307

    
308
    - ioemu [default] (HVM & KVM)
309
    - ide (HVM & KVM)
310
    - scsi (KVM)
311
    - sd (KVM)
312
    - mtd (KVM)
313
    - pflash (KVM)
314

    
315

    
316
cdrom\_disk\_type
317
    Valid for the KVM hypervisor.
318

    
319
    This parameter determines the way the cdroms disks are presented
320
    to the instance. The default behavior is to get the same value of
321
    the earlier parameter (disk_type). The possible options are:
322

    
323
    - paravirtual
324
    - ide
325
    - scsi
326
    - sd
327
    - mtd
328
    - pflash
329

    
330

    
331
vnc\_bind\_address
332
    Valid for the Xen HVM and KVM hypervisors.
333

    
334
    Specifies the address that the VNC listener for this instance
335
    should bind to. Valid values are IPv4 addresses. Use the address
336
    0.0.0.0 to bind to all available interfaces (this is the default)
337
    or specify the address of one of the interfaces on the node to
338
    restrict listening to that interface.
339

    
340
vnc\_tls
341
    Valid for the KVM hypervisor.
342

    
343
    A boolean option that controls whether the VNC connection is
344
    secured with TLS.
345

    
346
vnc\_x509\_path
347
    Valid for the KVM hypervisor.
348

    
349
    If ``vnc_tls`` is enabled, this options specifies the path to the
350
    x509 certificate to use.
351

    
352
vnc\_x509\_verify
353
    Valid for the KVM hypervisor.
354

    
355
spice\_bind
356
    Valid for the KVM hypervisor.
357

    
358
    Specifies the address or interface on which the SPICE server will
359
    listen. Valid values are:
360

    
361
    - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
362
    - IPv6 addresses, including :: and ::1
363
    - names of network interfaces
364

    
365
    If a network interface is specified, the SPICE server will be bound
366
    to one of the addresses of that interface.
367

    
368
spice\_ip\_version
369
    Valid for the KVM hypervisor.
370

    
371
    Specifies which version of the IP protocol should be used by the
372
    SPICE server.
373

    
374
    It is mainly intended to be used for specifying what kind of IP
375
    addresses should be used if a network interface with both IPv4 and
376
    IPv6 addresses is specified via the ``spice_bind`` parameter. In
377
    this case, if the ``spice_ip_version`` parameter is not used, the
378
    default IP version of the cluster will be used.
379

    
380
spice\_password\_file
381
    Valid for the KVM hypervisor.
382

    
383
    Specifies a file containing the password that must be used when
384
    connecting via the SPICE protocol. If the option is not specified,
385
    passwordless connections are allowed.
386

    
387
spice\_image\_compression
388
    Valid for the KVM hypervisor.
389

    
390
    Configures the SPICE lossless image compression. Valid values are:
391

    
392
    - auto_glz
393
    - auto_lz
394
    - quic
395
    - glz
396
    - lz
397
    - off
398

    
399
spice\_jpeg\_wan\_compression
400
    Valid for the KVM hypervisor.
401

    
402
    Configures how SPICE should use the jpeg algorithm for lossy image
403
    compression on slow links. Valid values are:
404

    
405
    - auto
406
    - never
407
    - always
408

    
409
spice\_zlib\_glz\_wan\_compression
410
    Valid for the KVM hypervisor.
411

    
412
    Configures how SPICE should use the zlib-glz algorithm for lossy image
413
    compression on slow links. Valid values are:
414

    
415
    - auto
416
    - never
417
    - always
418

    
419
spice\_streaming\_video
420
    Valid for the KVM hypervisor.
421

    
422
    Configures how SPICE should detect video streams. Valid values are:
423

    
424
    - off
425
    - all
426
    - filter
427

    
428
spice\_playback\_compression
429
    Valid for the KVM hypervisor.
430

    
431
    Configures whether SPICE should compress audio streams or not.
432

    
433
spice\_use\_tls
434
    Valid for the KVM hypervisor.
435

    
436
    Specifies that the SPICE server must use TLS to encrypt all the
437
    traffic with the client.
438

    
439
spice\_tls\_ciphers
440
    Valid for the KVM hypervisor.
441

    
442
    Specifies a list of comma-separated ciphers that SPICE should use
443
    for TLS connections. For the format, see man **cipher**\(1).
444

    
445
spice\_use\_vdagent
446
    Valid for the KVM hypervisor.
447

    
448
    Enables or disables passing mouse events via SPICE vdagent.
449

    
450
cpu\_type
451
    Valid for the KVM hypervisor.
452

    
453
    This parameter determines the emulated cpu for the instance. If this
454
    parameter is empty (which is the default configuration), it will not
455
    be passed to KVM.
456

    
457
    Be aware of setting this parameter to ``"host"`` if you have nodes
458
    with different CPUs from each other. Live migration may stop working
459
    in this situation.
460

    
461
    For more information please refer to the KVM manual.
462

    
463
acpi
464
    Valid for the Xen HVM and KVM hypervisors.
465

    
466
    A boolean option that specifies if the hypervisor should enable
467
    ACPI support for this instance. By default, ACPI is disabled.
468

    
469
pae
470
    Valid for the Xen HVM and KVM hypervisors.
471

    
472
    A boolean option that specifies if the hypervisor should enable
473
    PAE support for this instance. The default is false, disabling PAE
474
    support.
475

    
476
viridian
477
    Valid for the Xen HVM hypervisor.
478

    
479
    A boolean option that specifies if the hypervisor should enable
480
    viridian (Hyper-V) for this instance. The default is false,
481
    disabling viridian support.
482

    
483
use\_localtime
484
    Valid for the Xen HVM and KVM hypervisors.
485

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

    
492
kernel\_path
493
    Valid for the Xen PVM and KVM hypervisors.
494

    
495
    This option specifies the path (on the node) to the kernel to boot
496
    the instance with. Xen PVM instances always require this, while for
497
    KVM if this option is empty, it will cause the machine to load the
498
    kernel from its disks (and the boot will be done accordingly to
499
    ``boot_order``).
500

    
501
kernel\_args
502
    Valid for the Xen PVM and KVM hypervisors.
503

    
504
    This options specifies extra arguments to the kernel that will be
505
    loaded. device. This is always used for Xen PVM, while for KVM it
506
    is only used if the ``kernel_path`` option is also specified.
507

    
508
    The default setting for this value is simply ``"ro"``, which
509
    mounts the root disk (initially) in read-only one. For example,
510
    setting this to single will cause the instance to start in
511
    single-user mode.
512

    
513
initrd\_path
514
    Valid for the Xen PVM and KVM hypervisors.
515

    
516
    This option specifies the path (on the node) to the initrd to boot
517
    the instance with. Xen PVM instances can use this always, while
518
    for KVM if this option is only used if the ``kernel_path`` option
519
    is also specified. You can pass here either an absolute filename
520
    (the path to the initrd) if you want to use an initrd, or use the
521
    format no\_initrd\_path for no initrd.
522

    
523
root\_path
524
    Valid for the Xen PVM and KVM hypervisors.
525

    
526
    This options specifies the name of the root device. This is always
527
    needed for Xen PVM, while for KVM it is only used if the
528
    ``kernel_path`` option is also specified.
529

    
530
    Please note, that if this setting is an empty string and the
531
    hypervisor is Xen it will not be written to the Xen configuration
532
    file
533

    
534
serial\_console
535
    Valid for the KVM hypervisor.
536

    
537
    This boolean option specifies whether to emulate a serial console
538
    for the instance. Note that some versions of KVM have a bug that
539
    will make an instance hang when configured to use the serial console
540
    unless a connection is made to it within about 2 seconds of the
541
    instance's startup. For such case it's recommended to disable this
542
    option, which is enabled by default.
543

    
544
serial\_speed
545
    Valid for the KVM hypervisor.
546

    
547
    This integer option specifies the speed of the serial console.
548
    Common values are 9600, 19200, 38400, 57600 and 115200: choose the
549
    one which works on your system. (The default is 38400 for historical
550
    reasons, but newer versions of kvm/qemu work with 115200)
551

    
552
disk\_cache
553
    Valid for the KVM hypervisor.
554

    
555
    The disk cache mode. It can be either default to not pass any
556
    cache option to KVM, or one of the KVM cache modes: none (for
557
    direct I/O), writethrough (to use the host cache but report
558
    completion to the guest only when the host has committed the
559
    changes to disk) or writeback (to use the host cache and report
560
    completion as soon as the data is in the host cache). Note that
561
    there are special considerations for the cache mode depending on
562
    version of KVM used and disk type (always raw file under Ganeti),
563
    please refer to the KVM documentation for more details.
564

    
565
security\_model
566
    Valid for the KVM hypervisor.
567

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

    
572
    Under *user* kvm will drop privileges and become the user
573
    specified by the security\_domain parameter.
574

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

    
579
security\_domain
580
    Valid for the KVM hypervisor.
581

    
582
    Under security model *user* the username to run the instance
583
    under.  It must be a valid username existing on the host.
584

    
585
    Cannot be set under security model *none* or *pool*.
586

    
587
kvm\_flag
588
    Valid for the KVM hypervisor.
589

    
590
    If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
591
    -disable-kvm is passed. If unset no flag is passed, and the
592
    default running mode for your kvm binary will be used.
593

    
594
mem\_path
595
    Valid for the KVM hypervisor.
596

    
597
    This option passes the -mem-path argument to kvm with the path (on
598
    the node) to the mount point of the hugetlbfs file system, along
599
    with the -mem-prealloc argument too.
600

    
601
use\_chroot
602
    Valid for the KVM hypervisor.
603

    
604
    This boolean option determines whether to run the KVM instance in a
605
    chroot directory.
606

    
607
    If it is set to ``true``, an empty directory is created before
608
    starting the instance and its path is passed via the -chroot flag
609
    to kvm. The directory is removed when the instance is stopped.
610

    
611
    It is set to ``false`` by default.
612

    
613
migration\_downtime
614
    Valid for the KVM hypervisor.
615

    
616
    The maximum amount of time (in ms) a KVM instance is allowed to be
617
    frozen during a live migration, in order to copy dirty memory
618
    pages. Default value is 30ms, but you may need to increase this
619
    value for busy instances.
620

    
621
    This option is only effective with kvm versions >= 87 and qemu-kvm
622
    versions >= 0.11.0.
623

    
624
cpu\_mask
625
    Valid for the Xen, KVM and LXC hypervisors.
626

    
627
    The processes belonging to the given instance are only scheduled
628
    on the specified CPUs.
629

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

    
634
    Second, a comma-separated list of CPU IDs or CPU ID ranges. The
635
    ranges are defined by a lower and higher boundary, separated by a
636
    dash, and the boundaries are inclusive. In this form, all VCPUs of
637
    the instance will be mapped on the selected list of CPUs. Example:
638
    ``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs
639
    0, 1, 2 and 5.
640

    
641
    The last form is used for explicit control of VCPU-CPU pinnings. In
642
    this form, the list of VCPU mappings is given as a colon (:)
643
    separated list, whose elements are the possible values for the
644
    second or first form above. In this form, the number of elements in
645
    the colon-separated list _must_ equal the number of VCPUs of the
646
    instance.
647

    
648
    Example:
649

    
650
    .. code-block:: bash
651

    
652
      # Map the entire instance to CPUs 0-2
653
      gnt-instance modify -H cpu_mask=0-2 my-inst
654

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

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

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

    
665
      # Pin entire VM to CPU 0
666
      gnt-instance modify -H cpu_mask=0 my-inst
667

    
668
      # Turn off CPU pinning (default setting)
669
      gnt-instance modify -H cpu_mask=all my-inst
670

    
671
cpu\_cap
672
    Valid for the Xen hypervisor.
673

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

    
677
cpu\_weight
678
    Valid for the Xen hypervisor.
679

    
680
    Set the cpu time ratio to be allocated to the VM. Valid values are
681
    between 1 and 65535. Default weight is 256.
682

    
683
usb\_mouse
684
    Valid for the KVM hypervisor.
685

    
686
    This option specifies the usb mouse type to be used. It can be
687
    "mouse" or "tablet". When using VNC it's recommended to set it to
688
    "tablet".
689

    
690
keymap
691
    Valid for the KVM hypervisor.
692

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

    
696
reboot\_behavior
697
    Valid for Xen PVM, Xen HVM and KVM hypervisors.
698

    
699
    Normally if an instance reboots, the hypervisor will restart it. If
700
    this option is set to ``exit``, the hypervisor will treat a reboot
701
    as a shutdown instead.
702

    
703
    It is set to ``reboot`` by default.
704

    
705
cpu\_cores
706
    Valid for the KVM hypervisor.
707

    
708
    Number of emulated CPU cores.
709

    
710
cpu\_threads
711
    Valid for the KVM hypervisor.
712

    
713
    Number of emulated CPU threads.
714

    
715
cpu\_sockets
716
    Valid for the KVM hypervisor.
717

    
718
    Number of emulated CPU sockets.
719

    
720
soundhw
721
    Valid for the KVM hypervisor.
722

    
723
    Comma separated list of emulated sounds cards, or "all" to enable
724
    all the available ones.
725

    
726
usb\_devices
727
    Valid for the KVM hypervisor.
728

    
729
    Comma separated list of usb devices. These can be emulated devices
730
    or passthrough ones, and each one gets passed to kvm with its own
731
    ``-usbdevice`` option. See the **qemu**\(1) manpage for the syntax
732
    of the possible components.
733

    
734
vga
735
    Valid for the KVM hypervisor.
736

    
737
    Emulated vga mode, passed the the kvm -vga option.
738

    
739
kvm\_extra
740
    Valid for the KVM hypervisor.
741

    
742
    Any other option to the KVM hypervisor, useful tweaking anything
743
    that Ganeti doesn't support. Note that values set with this
744
    parameter are split on a space character and currently don't support
745
    quoting.
746

    
747
machine\_version
748
    Valid for the KVM hypervisor.
749

    
750
    Use in case an instance must be booted with an exact type of
751
    machine version (due to e.g. outdated drivers). In case it's not set
752
    the default version supported by your version of kvm is used.
753

    
754
kvm\_path
755
    Valid for the KVM hypervisor.
756

    
757
    Path to the userspace KVM (or qemu) program.
758

    
759
vnet\_hdr
760
    Valid for the KVM hypervisor.
761

    
762
    This boolean option determines whether the tap devices used by the
763
    KVM paravirtual nics (virtio-net) will get created with VNET_HDR
764
    (IFF_VNET_HDR) support.
765

    
766
    If set to false, it effectively disables offloading on the virio-net
767
    interfaces, which prevents host kernel tainting and log flooding,
768
    when dealing with broken or malicious virtio-net drivers.
769

    
770
    It is set to ``true`` by default.
771

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

    
777
    gnt-instance add -O dhcp=yes ...
778

    
779
The ``-I (--iallocator)`` option specifies the instance allocator plugin
780
to use (``.`` means the default allocator). If you pass in this option
781
the allocator will select nodes for this instance automatically, so you
782
don't need to pass them with the ``-n`` option. For more information
783
please refer to the instance allocator documentation.
784

    
785
The ``-t (--disk-template)`` options specifies the disk layout type
786
for the instance.  The available choices are:
787

    
788
diskless
789
    This creates an instance with no disks. Its useful for testing only
790
    (or other special cases).
791

    
792
file
793
    Disk devices will be regular files.
794

    
795
sharedfile
796
    Disk devices will be regulare files on a shared directory.
797

    
798
plain
799
    Disk devices will be logical volumes.
800

    
801
drbd
802
    Disk devices will be drbd (version 8.x) on top of lvm volumes.
803

    
804
rbd
805
    Disk devices will be rbd volumes residing inside a RADOS cluster.
806

    
807
blockdev
808
    Disk devices will be adopted pre-existent block devices.
809

    
810
ext
811
    Disk devices will be provided by external shared storage,
812
    through the ExtStorage Interface using ExtStorage providers.
813

    
814
The optional second value of the ``-n (--node)`` is used for the drbd
815
template type and specifies the remote node.
816

    
817
If you do not want gnt-instance to wait for the disk mirror to be
818
synced, use the ``--no-wait-for-sync`` option.
819

    
820
The ``--file-storage-dir`` specifies the relative path under the
821
cluster-wide file storage directory to store file-based disks. It is
822
useful for having different subdirectories for different
823
instances. The full path of the directory where the disk files are
824
stored will consist of cluster-wide file storage directory + optional
825
subdirectory + instance name. Example:
826
``@RPL_FILE_STORAGE_DIR@/mysubdir/instance1.example.com``. This
827
option is only relevant for instances using the file storage backend.
828

    
829
The ``--file-driver`` specifies the driver to use for file-based
830
disks. Note that currently these drivers work with the xen hypervisor
831
only. This option is only relevant for instances using the file
832
storage backend. The available choices are:
833

    
834
loop
835
    Kernel loopback driver. This driver uses loopback devices to
836
    access the filesystem within the file. However, running I/O
837
    intensive applications in your instance using the loop driver
838
    might result in slowdowns. Furthermore, if you use the loopback
839
    driver consider increasing the maximum amount of loopback devices
840
    (on most systems it's 8) using the max\_loop param.
841

    
842
blktap
843
    The blktap driver (for Xen hypervisors). In order to be able to
844
    use the blktap driver you should check if the 'blktapctrl' user
845
    space disk agent is running (usually automatically started via
846
    xend).  This user-level disk I/O interface has the advantage of
847
    better performance. Especially if you use a network file system
848
    (e.g. NFS) to store your instances this is the recommended choice.
849

    
850
blktap2
851
    Analogous to the blktap driver, but used by newer versions of Xen.
852

    
853
If ``--ignore-ipolicy`` is given any instance policy violations occuring
854
during this operation are ignored.
855

    
856
See **ganeti**\(7) for a description of ``--submit`` and other common
857
options.
858

    
859
Example::
860

    
861
    # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
862
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
863
    # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
864
      -o debian-etch -n node1.example.com instance1.example.com
865
    # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
866
      -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
867
    # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
868
      -n node1.example.com:node2.example.com instance2.example.com
869
    # gnt-instance add -t rbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
870
      -n node1.example.com instance1.example.com
871
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1 -B maxmem=512 \
872
      -o debian-etch -n node1.example.com instance1.example.com
873
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1,param1=val1 \
874
      --disk 1:size=40g,provider=pvdr2,param2=val2,param3=val3 -B maxmem=512 \
875
      -o debian-etch -n node1.example.com instance1.example.com
876

    
877

    
878
BATCH-CREATE
879
^^^^^^^^^^^^
880

    
881
| **batch-create**
882
| [{-I|\--iallocator} *instance allocator*]
883
| {instances\_file.json}
884

    
885
This command (similar to the Ganeti 1.2 **batcher** tool) submits
886
multiple instance creation jobs based on a definition file. This
887
file can contain all options which are valid when adding an instance
888
with the exception of the ``iallocator`` field. The IAllocator is,
889
for optimization purposes, only allowed to be set for the whole batch
890
operation using the ``--iallocator`` parameter.
891

    
892
The instance file must be a valid-formed JSON file, containing an
893
array of dictionaries with instance creation parameters. All parameters
894
(except ``iallocator``) which are valid for the instance creation
895
OP code are allowed. The most important ones are:
896

    
897
instance\_name
898
    The FQDN of the new instance.
899

    
900
disk\_template
901
    The disk template to use for the instance, the same as in the
902
    **add** command.
903

    
904
disks
905
    Array of disk specifications. Each entry describes one disk as a
906
    dictionary of disk parameters.
907

    
908
beparams
909
    A dictionary of backend parameters.
910

    
911
hypervisor
912
    The hypervisor for the instance.
913

    
914
hvparams
915
    A dictionary with the hypervisor options. If not passed, the default
916
    hypervisor options will be inherited.
917

    
918
nics
919
    List of NICs that will be created for the instance. Each entry
920
    should be a dict, with mac, ip, mode and link as possible keys.
921
    Please don't provide the "mac, ip, mode, link" parent keys if you
922
    use this method for specifying NICs.
923

    
924
pnode, snode
925
    The primary and optionally the secondary node to use for the
926
    instance (in case an iallocator script is not used). If those
927
    parameters are given, they have to be given consistently for all
928
    instances in the batch operation.
929

    
930
start
931
    whether to start the instance
932

    
933
ip\_check
934
    Skip the check for already-in-use instance; see the description in
935
    the **add** command for details.
936

    
937
name\_check
938
    Skip the name check for instances; see the description in the
939
    **add** command for details.
940

    
941
file\_storage\_dir, file\_driver
942
    Configuration for the file disk type, see the **add** command for
943
    details.
944

    
945

    
946
A simple definition for one instance can be (with most of the
947
parameters taken from the cluster defaults)::
948

    
949
    [
950
      {
951
        "mode": "create",
952
        "instance_name": "instance1.example.com",
953
        "disk_template": "drbd",
954
        "os_type": "debootstrap",
955
        "disks": [{"size":"1024"}],
956
        "nics": [{}],
957
        "hypervisor": "xen-pvm"
958
      },
959
      {
960
        "mode": "create",
961
        "instance_name": "instance2.example.com",
962
        "disk_template": "drbd",
963
        "os_type": "debootstrap",
964
        "disks": [{"size":"4096", "mode": "rw", "vg": "xenvg"}],
965
        "nics": [{}],
966
        "hypervisor": "xen-hvm",
967
        "hvparams": {"acpi": true},
968
        "beparams": {"maxmem": 512, "minmem": 256}
969
      }
970
    ]
971

    
972
The command will display the job id for each submitted instance, as
973
follows::
974

    
975
    # gnt-instance batch-create instances.json
976
    Submitted jobs 37, 38
977

    
978
REMOVE
979
^^^^^^
980

    
981
**remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
982
[\--force] {*instance*}
983

    
984
Remove an instance. This will remove all data from the instance and
985
there is *no way back*. If you are not sure if you use an instance
986
again, use **shutdown** first and leave it in the shutdown state for a
987
while.
988

    
989
The ``--ignore-failures`` option will cause the removal to proceed
990
even in the presence of errors during the removal of the instance
991
(e.g. during the shutdown or the disk removal). If this option is not
992
given, the command will stop at the first error.
993

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

    
999
The ``--force`` option is used to skip the interactive confirmation.
1000

    
1001
See **ganeti**\(7) for a description of ``--submit`` and other common
1002
options.
1003

    
1004
Example::
1005

    
1006
    # gnt-instance remove instance1.example.com
1007

    
1008

    
1009
LIST
1010
^^^^
1011

    
1012
| **list**
1013
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
1014
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
1015

    
1016
Shows the currently configured instances with memory usage, disk
1017
usage, the node they are running on, and their run status.
1018

    
1019
The ``--no-headers`` option will skip the initial header line. The
1020
``--separator`` option takes an argument which denotes what will be
1021
used between the output fields. Both these options are to help
1022
scripting.
1023

    
1024
The units used to display the numeric values in the output varies,
1025
depending on the options given. By default, the values will be
1026
formatted in the most appropriate unit. If the ``--separator`` option
1027
is given, then the values are shown in mebibytes to allow parsing by
1028
scripts. In both cases, the ``--units`` option can be used to enforce
1029
a given output unit.
1030

    
1031
The ``-v`` option activates verbose mode, which changes the display of
1032
special field states (see **ganeti**\(7)).
1033

    
1034
The ``-o (--output)`` option takes a comma-separated list of output
1035
fields. The available fields and their meaning are:
1036

    
1037
@QUERY_FIELDS_INSTANCE@
1038

    
1039
If the value of the option starts with the character ``+``, the new
1040
field(s) will be added to the default list. This allows one to quickly
1041
see the default list plus a few other fields, instead of retyping the
1042
entire list of fields.
1043

    
1044
There is a subtle grouping about the available output fields: all
1045
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
1046
``status`` are configuration value and not run-time values. So if you
1047
don't select any of the these fields, the query will be satisfied
1048
instantly from the cluster configuration, without having to ask the
1049
remote nodes for the data. This can be helpful for big clusters when
1050
you only want some data and it makes sense to specify a reduced set of
1051
output fields.
1052

    
1053
If exactly one argument is given and it appears to be a query filter
1054
(see **ganeti**\(7)), the query result is filtered accordingly. For
1055
ambiguous cases (e.g. a single field name as a filter) the ``--filter``
1056
(``-F``) option forces the argument to be treated as a filter (e.g.
1057
``gnt-instance list -F admin_state``).
1058

    
1059
The default output field list is: ``name``, ``os``, ``pnode``,
1060
``admin_state``, ``oper_state``, ``oper_ram``.
1061

    
1062

    
1063
LIST-FIELDS
1064
^^^^^^^^^^^
1065

    
1066
**list-fields** [field...]
1067

    
1068
Lists available fields for instances.
1069

    
1070

    
1071
INFO
1072
^^^^
1073

    
1074
**info** [-s \| \--static] [\--roman] {\--all \| *instance*}
1075

    
1076
Show detailed information about the given instance(s). This is
1077
different from **list** as it shows detailed data about the instance's
1078
disks (especially useful for the drbd disk template).
1079

    
1080
If the option ``-s`` is used, only information available in the
1081
configuration file is returned, without querying nodes, making the
1082
operation faster.
1083

    
1084
Use the ``--all`` to get info about all instances, rather than
1085
explicitly passing the ones you're interested in.
1086

    
1087
The ``--roman`` option can be used to cause envy among people who like
1088
ancient cultures, but are stuck with non-latin-friendly cluster
1089
virtualization technologies.
1090

    
1091
MODIFY
1092
^^^^^^
1093

    
1094
| **modify**
1095
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
1096
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
1097
| [{-m|\--runtime-memory} *SIZE*]
1098
| [\--net add[:options...] \|
1099
|  \--net [*N*:]add[,options...] \|
1100
|  \--net [*ID*:]remove \|
1101
|  \--net *ID*:modify[,options...]]
1102
| [\--disk add:size=*SIZE*[,options...] \|
1103
|  \--disk *N*:add,size=*SIZE*[,options...] \|
1104
|  \--disk *N*:add,size=*SIZE*,provider=*PROVIDER*[,options...][,param=*value*... ] \|
1105
|  \--disk *ID*:modify[,options...]
1106
|  \--disk [*ID*:]remove]
1107
| [{-t|\--disk-template} plain | {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
1108
| [\--new-primary=*node*]
1109
| [\--os-type=*OS* [\--force-variant]]
1110
| [{-O|\--os-parameters} *param*=*value*... ]
1111
| [\--offline \| \--online]
1112
| [\--submit]
1113
| [\--ignore-ipolicy]
1114
| [\--hotplug]
1115
| [\--hotplug-if-possible]
1116
| {*instance*}
1117

    
1118
Modifies the memory size, number of vcpus, ip address, MAC address
1119
and/or NIC parameters for an instance. It can also add and remove
1120
disks and NICs to/from the instance. Note that you need to give at
1121
least one of the arguments, otherwise the command complains.
1122

    
1123
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
1124
and ``-O (--os-parameters)`` options specifies hypervisor, backend and
1125
OS parameter options in the form of name=value[,...]. For details
1126
which options can be specified, see the **add** command.
1127

    
1128
The ``-t (--disk-template)`` option will change the disk template of
1129
the instance.  Currently only conversions between the plain and drbd
1130
disk templates are supported, and the instance must be stopped before
1131
attempting the conversion. When changing from the plain to the drbd
1132
disk template, a new secondary node must be specified via the ``-n``
1133
option. The option ``--no-wait-for-sync`` can be used when converting
1134
to the ``drbd`` template in order to make the instance available for
1135
startup before DRBD has finished resyncing.
1136

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

    
1141
The ``--disk add:size=*SIZE*,[options..]`` option adds a disk to the
1142
instance, and ``--disk *N*:add:size=*SIZE*,[options..]`` will add a disk
1143
to the the instance at a specific index. The available options are the
1144
same as in the **add** command(``mode``, ``name``, ``vg``, ``metavg``).
1145
When adding an ExtStorage disk the ``provider=*PROVIDER*`` option is
1146
also mandatory and specifies the ExtStorage provider. Also, for
1147
ExtStorage disks arbitrary parameters can be passed as additional comma
1148
separated options, same as in the **add** command. -The ``--disk remove``
1149
option will remove the last disk of the instance. Use
1150
``--disk `` *ID*``:remove`` to remove a disk by its identifier.  *ID*
1151
can be the index of the disk, the disks's name or the disks's UUID.  The
1152
``--disk *ID*:modify[,options...]`` wil change the options of the disk.
1153
Available options are:
1154

    
1155
mode
1156
  The access mode. Either ``ro`` (read-only) or the default ``rw`` (read-write).
1157

    
1158
name
1159
   this option specifies a name for the disk, which can be used as a disk
1160
   identifier. An instance can not have two disks with the same name.
1161

    
1162
The ``--net *N*:add[,options..]`` will add a new network interface to
1163
the instance. The available options are the same as in the **add**
1164
command (``mac``, ``ip``, ``link``, ``mode``, ``network``). The
1165
``--net *ID*,remove`` will remove the intances' NIC with *ID* identifier,
1166
which can be the index of the NIC, the NIC's name or the NIC's UUID.
1167
The ``--net *ID*:modify[,options..]`` option will change the parameters of
1168
the instance network interface with the *ID* identifier.
1169

    
1170
The option ``-o (--os-type)`` will change the OS name for the instance
1171
(without reinstallation). In case an OS variant is specified that is
1172
not found, then by default the modification is refused, unless
1173
``--force-variant`` is passed. An invalid OS will also be refused,
1174
unless the ``--force`` option is given.
1175

    
1176
The option ``--new-primary`` will set the new primary node of an instance
1177
assuming the disks have already been moved manually. Unless the ``--force``
1178
option is given, it is verified that the instance is no longer running
1179
on its current primary node.
1180

    
1181
The ``--online`` and ``--offline`` options are used to transition an
1182
instance into and out of the ``offline`` state. An instance can be
1183
turned offline only if it was previously down. The ``--online`` option
1184
fails if the instance was not in the ``offline`` state, otherwise it
1185
changes instance's state to ``down``. These modifications take effect
1186
immediately.
1187

    
1188
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1189
during this operation are ignored.
1190

    
1191
If ``--hotplug`` is given any disk and NIC modifications will take
1192
effect without the need of actual reboot. Please note that this feature
1193
is currently supported only for KVM hypervisor and there are some
1194
restrictions: a) KVM versions >= 1.0 support it b) instances with chroot
1195
or uid pool security model do not support disk hotplug c) RBD disks with
1196
userspace access mode can not be hotplugged (yet) d) if hotplug fails
1197
(for any reason) a warning is printed but execution is continued e)
1198
for existing NIC modification interactive verification is needed unless
1199
``--force`` option is passed.
1200

    
1201
If ``--hotplug-if-possible`` is given then ganeti won't abort in case
1202
hotplug is not supported. It will continue execution and modification
1203
will take place after reboot. This covers use cases where instances are
1204
not running or hypervisor is not KVM.
1205

    
1206
See **ganeti**\(7) for a description of ``--submit`` and other common
1207
options.
1208

    
1209
Most of the changes take effect at the next restart. If the instance is
1210
running, there is no effect on the instance.
1211

    
1212

    
1213
SNAPSHOT
1214
^^^^^^^^
1215

    
1216
| **snapshot**
1217
| {\--disk=*ID*:snapshot_name=*VAL*
1218
| [\--submit]
1219
| {*instance*}
1220

    
1221
This only works for instances with ext disk template. It eventualla runs
1222
the snapshot script of the corresponding extstorage provider.
1223
The ``--disk 0:snapshot_name=snap1`` will take snapshot of the first disk
1224
by exporting snapshot name (via VOL_SNAPSHOT_NAME) and disk related info
1225
to the script environment. *ID* can be a disk index, name or UUID.
1226

    
1227

    
1228
REINSTALL
1229
^^^^^^^^^
1230

    
1231
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
1232
| [\--force-multiple]
1233
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1234
| [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] {*instance*...}
1235

    
1236
Reinstalls the operating system on the given instance(s). The
1237
instance(s) must be stopped when running this command. If the ``-o
1238
(--os-type)`` is specified, the operating system is changed.
1239

    
1240
The ``--select-os`` option switches to an interactive OS reinstall.
1241
The user is prompted to select the OS template from the list of
1242
available OS templates. OS parameters can be overridden using ``-O
1243
(--os-parameters)`` (more documentation for this option under the
1244
**add** command).
1245

    
1246
Since this is a potentially dangerous command, the user will be
1247
required to confirm this action, unless the ``-f`` flag is passed.
1248
When multiple instances are selected (either by passing multiple
1249
arguments or by using the ``--node``, ``--primary``, ``--secondary``
1250
or ``--all`` options), the user must pass the ``--force-multiple``
1251
options to skip the interactive confirmation.
1252

    
1253
See **ganeti**\(7) for a description of ``--submit`` and other common
1254
options.
1255

    
1256
RENAME
1257
^^^^^^
1258

    
1259
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit]
1260
| {*instance*} {*new\_name*}
1261

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

    
1269
Note that you can rename an instance to its same name, to force
1270
re-executing the os-specific rename script for that instance, if
1271
needed.
1272

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

    
1279
See **ganeti**\(7) for a description of ``--submit`` and other common
1280
options.
1281

    
1282
Starting/stopping/connecting to console
1283
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1284

    
1285
STARTUP
1286
^^^^^^^
1287

    
1288
| **startup**
1289
| [\--force] [\--ignore-offline]
1290
| [\--force-multiple] [\--no-remember]
1291
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1292
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1293
| [{-H|\--hypervisor-parameters} ``key=value...``]
1294
| [{-B|\--backend-parameters} ``key=value...``]
1295
| [\--submit] [\--paused]
1296
| {*name*...}
1297

    
1298
Starts one or more instances, depending on the following options.  The
1299
four available modes are:
1300

    
1301
\--instance
1302
    will start the instances given as arguments (at least one argument
1303
    required); this is the default selection
1304

    
1305
\--node
1306
    will start the instances who have the given node as either primary
1307
    or secondary
1308

    
1309
\--primary
1310
    will start all instances whose primary node is in the list of nodes
1311
    passed as arguments (at least one node required)
1312

    
1313
\--secondary
1314
    will start all instances whose secondary node is in the list of
1315
    nodes passed as arguments (at least one node required)
1316

    
1317
\--all
1318
    will start all instances in the cluster (no arguments accepted)
1319

    
1320
\--tags
1321
    will start all instances in the cluster with the tags given as
1322
    arguments
1323

    
1324
\--node-tags
1325
    will start all instances in the cluster on nodes with the tags
1326
    given as arguments
1327

    
1328
\--pri-node-tags
1329
    will start all instances in the cluster on primary nodes with the
1330
    tags given as arguments
1331

    
1332
\--sec-node-tags
1333
    will start all instances in the cluster on secondary nodes with the
1334
    tags given as arguments
1335

    
1336
Note that although you can pass more than one selection option, the
1337
last one wins, so in order to guarantee the desired result, don't pass
1338
more than one such option.
1339

    
1340
Use ``--force`` to start even if secondary disks are failing.
1341
``--ignore-offline`` can be used to ignore offline primary nodes and
1342
mark the instance as started even if the primary is not available.
1343

    
1344
The ``--force-multiple`` will skip the interactive confirmation in the
1345
case the more than one instance will be affected.
1346

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

    
1353
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
1354
options specify temporary hypervisor and backend parameters that can
1355
be used to start an instance with modified parameters. They can be
1356
useful for quick testing without having to modify an instance back and
1357
forth, e.g.::
1358

    
1359
    # gnt-instance start -H kernel_args="single" instance1
1360
    # gnt-instance start -B maxmem=2048 instance2
1361

    
1362

    
1363
The first form will start the instance instance1 in single-user mode,
1364
and the instance instance2 with 2GB of RAM (this time only, unless
1365
that is the actual instance memory size already). Note that the values
1366
override the instance parameters (and not extend them): an instance
1367
with "kernel\_args=ro" when started with -H kernel\_args=single will
1368
result in "single", not "ro single".
1369

    
1370
The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
1371
pauses the instance at the start of bootup, awaiting ``gnt-instance
1372
console`` to unpause it, allowing the entire boot process to be
1373
monitored for debugging.
1374

    
1375
See **ganeti**\(7) for a description of ``--submit`` and other common
1376
options.
1377

    
1378
Example::
1379

    
1380
    # gnt-instance start instance1.example.com
1381
    # gnt-instance start --node node1.example.com node2.example.com
1382
    # gnt-instance start --all
1383

    
1384

    
1385
SHUTDOWN
1386
^^^^^^^^
1387

    
1388
| **shutdown**
1389
| [\--timeout=*N*]
1390
| [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember]
1391
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1392
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1393
| [\--submit]
1394
| {*name*...}
1395

    
1396
Stops one or more instances. If the instance cannot be cleanly stopped
1397
during a hardcoded interval (currently 2 minutes), it will forcibly
1398
stop the instance (equivalent to switching off the power on a physical
1399
machine).
1400

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

    
1406
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1407
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1408
``--sec-node-tags`` options are similar as for the **startup** command
1409
and they influence the actual instances being shutdown.
1410

    
1411
``--ignore-offline`` can be used to ignore offline primary nodes and
1412
force the instance to be marked as stopped. This option should be used
1413
with care as it can lead to an inconsistent cluster state.
1414

    
1415
Use ``--force`` to be able to shutdown an instance even when it's marked
1416
as offline. This is useful is an offline instance ends up in the
1417
``ERROR_up`` state, for example.
1418

    
1419
The ``--no-remember`` option will perform the shutdown but not change
1420
the state of the instance in the configuration file (if it was running
1421
before, Ganeti will still thinks it needs to be running). This can be
1422
useful for a cluster-wide shutdown, where some instances are marked as
1423
up and some as down, and you don't want to change the running state:
1424
you just need to disable the watcher, shutdown all instances with
1425
``--no-remember``, and when the watcher is activated again it will
1426
restore the correct runtime state for all instances.
1427

    
1428
See **ganeti**\(7) for a description of ``--submit`` and other common
1429
options.
1430

    
1431
Example::
1432

    
1433
    # gnt-instance shutdown instance1.example.com
1434
    # gnt-instance shutdown --all
1435

    
1436

    
1437
REBOOT
1438
^^^^^^
1439

    
1440
| **reboot**
1441
| [{-t|\--type} *REBOOT-TYPE*]
1442
| [\--ignore-secondaries]
1443
| [\--shutdown-timeout=*N*]
1444
| [\--force-multiple]
1445
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1446
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1447
| [\--submit]
1448
| [*name*...]
1449

    
1450
Reboots one or more instances. The type of reboot depends on the value
1451
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1452
does a instance stop, recreates the hypervisor config for the instance
1453
and starts the instance. A full reboot does the equivalent of
1454
**gnt-instance shutdown && gnt-instance startup**.  The default is
1455
hard reboot.
1456

    
1457
For the hard reboot the option ``--ignore-secondaries`` ignores errors
1458
for the secondary node while re-assembling the instance disks.
1459

    
1460
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1461
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1462
``--sec-node-tags`` options are similar as for the **startup** command
1463
and they influence the actual instances being rebooted.
1464

    
1465
The ``--shutdown-timeout`` is used to specify how much time to wait
1466
before forcing the shutdown (xm destroy in xen, killing the kvm
1467
process, for kvm). By default two minutes are given to each instance
1468
to stop.
1469

    
1470
The ``--force-multiple`` will skip the interactive confirmation in the
1471
case the more than one instance will be affected.
1472

    
1473
See **ganeti**\(7) for a description of ``--submit`` and other common
1474
options.
1475

    
1476
Example::
1477

    
1478
    # gnt-instance reboot instance1.example.com
1479
    # gnt-instance reboot --type=full instance1.example.com
1480

    
1481

    
1482
CONSOLE
1483
^^^^^^^
1484

    
1485
**console** [\--show-cmd] {*instance*}
1486

    
1487
Connects to the console of the given instance. If the instance is not
1488
up, an error is returned. Use the ``--show-cmd`` option to display the
1489
command instead of executing it.
1490

    
1491
For HVM instances, this will attempt to connect to the serial console
1492
of the instance. To connect to the virtualized "physical" console of a
1493
HVM instance, use a VNC client with the connection info from the
1494
**info** command.
1495

    
1496
For Xen/kvm instances, if the instance is paused, this attempts to
1497
unpause the instance after waiting a few seconds for the connection to
1498
the console to be made.
1499

    
1500
Example::
1501

    
1502
    # gnt-instance console instance1.example.com
1503

    
1504

    
1505
Disk management
1506
~~~~~~~~~~~~~~~
1507

    
1508
REPLACE-DISKS
1509
^^^^^^^^^^^^^
1510

    
1511
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-p}
1512
[\--disks *idx*] {*instance*}
1513

    
1514
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-s}
1515
[\--disks *idx*] {*instance*}
1516

    
1517
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1518
{{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*}
1519

    
1520
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1521
{-a\|\--auto} {*instance*}
1522

    
1523
This command is a generalized form for replacing disks. It is
1524
currently only valid for the mirrored (DRBD) disk template.
1525

    
1526
The first form (when passing the ``-p`` option) will replace the disks
1527
on the primary, while the second form (when passing the ``-s`` option
1528
will replace the disks on the secondary node. For these two cases (as
1529
the node doesn't change), it is possible to only run the replace for a
1530
subset of the disks, using the option ``--disks`` which takes a list
1531
of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only
1532
the first and third disks.
1533

    
1534
The third form (when passing either the ``--iallocator`` or the
1535
``--new-secondary`` option) is designed to change secondary node of the
1536
instance. Specifying ``--iallocator`` makes the new secondary be
1537
selected automatically by the specified allocator plugin (use ``.`` to
1538
indicate the default allocator), otherwise the new secondary node will
1539
be the one chosen manually via the ``--new-secondary`` option.
1540

    
1541
Note that it is not possible to select an offline or drained node as a
1542
new secondary.
1543

    
1544
The fourth form (when using ``--auto``) will automatically determine
1545
which disks of an instance are faulty and replace them within the same
1546
node. The ``--auto`` option works only when an instance has only
1547
faulty disks on either the primary or secondary node; it doesn't work
1548
when both sides have faulty disks.
1549

    
1550
The ``--early-release`` changes the code so that the old storage on
1551
secondary node(s) is removed early (before the resync is completed)
1552
and the internal Ganeti locks for the current (and new, if any)
1553
secondary node are also released, thus allowing more parallelism in
1554
the cluster operation. This should be used only when recovering from a
1555
disk failure on the current secondary (thus the old storage is already
1556
broken) or when the storage on the primary node is known to be fine
1557
(thus we won't need the old storage for potential recovery).
1558

    
1559
The ``--ignore-ipolicy`` let the command ignore instance policy
1560
violations if replace-disks changes groups and the instance would
1561
violate the new groups instance policy.
1562

    
1563
See **ganeti**\(7) for a description of ``--submit`` and other common
1564
options.
1565

    
1566
ACTIVATE-DISKS
1567
^^^^^^^^^^^^^^
1568

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

    
1571
Activates the block devices of the given instance. If successful, the
1572
command will show the location and name of the block devices::
1573

    
1574
    node1.example.com:disk/0:/dev/drbd0
1575
    node1.example.com:disk/1:/dev/drbd1
1576

    
1577

    
1578
In this example, *node1.example.com* is the name of the node on which
1579
the devices have been activated. The *disk/0* and *disk/1* are the
1580
Ganeti-names of the instance disks; how they are visible inside the
1581
instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the
1582
actual block devices as visible on the node.
1583

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

    
1591
The ``--wait-for-sync`` option will ensure that the command returns only
1592
after the instance's disks are synchronised (mostly for DRBD); this can
1593
be useful to ensure consistency, as otherwise there are no commands that
1594
can wait until synchronisation is done. However when passing this
1595
option, the command will have additional output, making it harder to
1596
parse the disk information.
1597

    
1598
Note that it is safe to run this command while the instance is already
1599
running.
1600

    
1601
See **ganeti**\(7) for a description of ``--submit`` and other common
1602
options.
1603

    
1604
DEACTIVATE-DISKS
1605
^^^^^^^^^^^^^^^^
1606

    
1607
**deactivate-disks** [-f] [\--submit] {*instance*}
1608

    
1609
De-activates the block devices of the given instance. Note that if you
1610
run this command for an instance with a drbd disk template, while it
1611
is running, it will not be able to shutdown the block devices on the
1612
primary node, but it will shutdown the block devices on the secondary
1613
nodes, thus breaking the replication.
1614

    
1615
The ``-f``/``--force`` option will skip checks that the instance is
1616
down; in case the hypervisor is confused and we can't talk to it,
1617
normally Ganeti will refuse to deactivate the disks, but with this
1618
option passed it will skip this check and directly try to deactivate
1619
the disks. This can still fail due to the instance actually running or
1620
other issues.
1621

    
1622
See **ganeti**\(7) for a description of ``--submit`` and other common
1623
options.
1624

    
1625
GROW-DISK
1626
^^^^^^^^^
1627

    
1628
| **grow-disk** [\--no-wait-for-sync] [\--submit] [\--absolute]
1629
| {*instance*} {*disk*} {*amount*}
1630

    
1631
Grows an instance's disk. This is only possible for instances having a
1632
plain, drbd, file, sharedfile, rbd or ext disk template. For the ext
1633
template to work, the ExtStorage provider should also support growing.
1634
This means having a ``grow`` script that actually grows the volume of
1635
the external shared storage.
1636

    
1637
Note that this command only change the block device size; it will not
1638
grow the actual filesystems, partitions, etc. that live on that
1639
disk. Usually, you will need to:
1640

    
1641
#. use **gnt-instance grow-disk**
1642

    
1643
#. reboot the instance (later, at a convenient time)
1644

    
1645
#. use a filesystem resizer, such as **ext2online**\(8) or
1646
   **xfs\_growfs**\(8) to resize the filesystem, or use **fdisk**\(8) to
1647
   change the partition table on the disk
1648

    
1649
The *disk* argument is the index of the instance disk to grow. The
1650
*amount* argument is given as a number which can have a suffix (like the
1651
disk size in instance create); if the suffix is missing, the value will
1652
be interpreted as mebibytes.
1653

    
1654
By default, the *amount* value represents the desired increase in the
1655
disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If
1656
the optional ``--absolute`` parameter is passed, then the *amount*
1657
argument doesn't represent the delta, but instead the desired final disk
1658
size (e.g. an amount of 8G will take a disk of size 4G to 8G).
1659

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

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

    
1668
See **ganeti**\(7) for a description of ``--submit`` and other common
1669
options.
1670

    
1671
Example (increase the first disk for instance1 by 16GiB)::
1672

    
1673
    # gnt-instance grow-disk instance1.example.com 0 16g
1674

    
1675
Example for increasing the disk size to a certain size::
1676

    
1677
   # gnt-instance grow-disk --absolute instance1.example.com 0 32g
1678

    
1679
Also note that disk shrinking is not supported; use **gnt-backup
1680
export** and then **gnt-backup import** to reduce the disk size of an
1681
instance.
1682

    
1683
RECREATE-DISKS
1684
^^^^^^^^^^^^^^
1685

    
1686
| **recreate-disks** [\--submit]
1687
| [{-n node1:[node2] \| {-I\|\--iallocator *name*}}]
1688
| [\--disk=*N*[:[size=*VAL*][,mode=*ro\|rw*]]] {*instance*}
1689

    
1690
Recreates all or a subset of disks of the given instance.
1691

    
1692
Note that this functionality should only be used for missing disks; if
1693
any of the given disks already exists, the operation will fail.  While
1694
this is suboptimal, recreate-disks should hopefully not be needed in
1695
normal operation and as such the impact of this is low.
1696

    
1697
If only a subset should be recreated, any number of ``disk`` options can
1698
be specified. It expects a disk index and an optional list of disk
1699
parameters to change. Only ``size`` and ``mode`` can be changed while
1700
recreating disks. To recreate all disks while changing parameters on
1701
a subset only, a ``--disk`` option must be given for every disk of the
1702
instance.
1703

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

    
1713
Another method of choosing which nodes to place the instance on is by
1714
using the specified iallocator, passing the ``--iallocator`` option.
1715
The primary and secondary nodes will be chosen by the specified
1716
iallocator plugin, or by the default allocator if ``.`` is specified.
1717

    
1718
See **ganeti**\(7) for a description of ``--submit`` and other common
1719
options.
1720

    
1721
Recovery/moving
1722
~~~~~~~~~~~~~~~
1723

    
1724
FAILOVER
1725
^^^^^^^^
1726

    
1727
| **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy]
1728
| [\--shutdown-timeout=*N*]
1729
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*]
1730
| [\--submit] [\--cleanup]
1731
| {*instance*}
1732

    
1733
Failover will stop the instance (if running), change its primary node,
1734
and if it was originally running it will start it again (on the new
1735
primary). This works for instances with drbd template (in which case you
1736
can only fail to the secondary node) and for externally mirrored
1737
templates (sharedfile, blockdev, rbd and ext) (in which case you can
1738
fail to any other node).
1739

    
1740
If the instance's disk template is of type sharedfile, blockdev, rbd or
1741
ext, then you can explicitly specify the target node (which can be any
1742
node) using the ``-n`` or ``--target-node`` option, or specify an
1743
iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
1744
omit both, the default iallocator will be used to specify the target
1745
node.
1746

    
1747
If the instance's disk template is of type drbd, the target node is
1748
automatically selected as the drbd's secondary node. Changing the
1749
secondary node is possible with a replace-disks operation.
1750

    
1751
Normally the failover will check the consistency of the disks before
1752
failing over the instance. If you are trying to migrate instances off
1753
a dead node, this will fail. Use the ``--ignore-consistency`` option
1754
for this purpose. Note that this option can be dangerous as errors in
1755
shutting down the instance will be ignored, resulting in possibly
1756
having the instance running on two machines in parallel (on
1757
disconnected DRBD drives).
1758

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

    
1764
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1765
during this operation are ignored.
1766

    
1767
If the ``--cleanup`` option is passed, the operation changes from
1768
performin a failover to attempting recovery from a failed previous failover.
1769
In this mode, Ganeti checks if the instance runs on the correct node (and
1770
updates its configuration if not) and ensures the instances' disks
1771
are configured correctly.
1772

    
1773
See **ganeti**\(7) for a description of ``--submit`` and other common
1774
options.
1775

    
1776
Example::
1777

    
1778
    # gnt-instance failover instance1.example.com
1779

    
1780
For externally mirrored templates also ``-n`` is available::
1781

    
1782
    # gnt-instance failover -n node3.example.com instance1.example.com
1783

    
1784

    
1785
MIGRATE
1786
^^^^^^^
1787

    
1788
| **migrate** [-f] [\--allow-failover] [\--non-live]
1789
| [\--migration-mode=live\|non-live] [\--ignore-ipolicy]
1790
| [\--no-runtime-changes] [\--submit]
1791
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*}
1792

    
1793
| **migrate** [-f] \--cleanup [\--submit] {*instance*}
1794

    
1795
Migrate will move the instance to its secondary node without shutdown.
1796
As with failover, it works for instances having the drbd disk template
1797
or an externally mirrored disk template type such as sharedfile,
1798
blockdev, rbd or ext.
1799

    
1800
If the instance's disk template is of type sharedfile, blockdev, rbd or
1801
ext, then you can explicitly specify the target node (which can be any
1802
node) using the ``-n`` or ``--target-node`` option, or specify an
1803
iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
1804
omit both, the default iallocator will be used to specify the target
1805
node.  Alternatively, the default iallocator can be requested by
1806
specifying ``.`` as the name of the plugin.
1807

    
1808
If the instance's disk template is of type drbd, the target node is
1809
automatically selected as the drbd's secondary node. Changing the
1810
secondary node is possible with a replace-disks operation.
1811

    
1812
The migration command needs a perfectly healthy instance for drbd
1813
instances, as we rely on the dual-master capability of drbd8 and the
1814
disks of the instance are not allowed to be degraded.
1815

    
1816
The ``--non-live`` and ``--migration-mode=non-live`` options will
1817
switch (for the hypervisors that support it) between a "fully live"
1818
(i.e. the interruption is as minimal as possible) migration and one in
1819
which the instance is frozen, its state saved and transported to the
1820
remote node, and then resumed there. This all depends on the
1821
hypervisor support for two different methods. In any case, it is not
1822
an error to pass this parameter (it will just be ignored if the
1823
hypervisor doesn't support it). The option ``--migration-mode=live``
1824
option will request a fully-live migration. The default, when neither
1825
option is passed, depends on the hypervisor parameters (and can be
1826
viewed with the **gnt-cluster info** command).
1827

    
1828
If the ``--cleanup`` option is passed, the operation changes from
1829
migration to attempting recovery from a failed previous migration. In
1830
this mode, Ganeti checks if the instance runs on the correct node (and
1831
updates its configuration if not) and ensures the instances' disks
1832
are configured correctly. In this mode, the ``--non-live`` option is
1833
ignored.
1834

    
1835
The option ``-f`` will skip the prompting for confirmation.
1836

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

    
1842
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1843
during this operation are ignored.
1844

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

    
1849
If an instance has the backend parameter ``always_failover`` set to
1850
true, then the migration is automatically converted into a failover.
1851

    
1852
See **ganeti**\(7) for a description of ``--submit`` and other common
1853
options.
1854

    
1855
Example (and expected output)::
1856

    
1857
    # gnt-instance migrate instance1
1858
    Instance instance1 will be migrated. Note that migration
1859
    might impact the instance if anything goes wrong (e.g. due to bugs in
1860
    the hypervisor). Continue?
1861
    y/[n]/?: y
1862
    Migrating instance instance1.example.com
1863
    * checking disk consistency between source and target
1864
    * switching node node2.example.com to secondary mode
1865
    * changing into standalone mode
1866
    * changing disks into dual-master mode
1867
    * wait until resync is done
1868
    * preparing node2.example.com to accept the instance
1869
    * migrating instance to node2.example.com
1870
    * switching node node1.example.com to secondary mode
1871
    * wait until resync is done
1872
    * changing into standalone mode
1873
    * changing disks into single-master mode
1874
    * wait until resync is done
1875
    * done
1876
    #
1877

    
1878

    
1879
MOVE
1880
^^^^
1881

    
1882
| **move** [-f] [\--ignore-consistency]
1883
| [-n *node*] [\--shutdown-timeout=*N*] [\--submit] [\--ignore-ipolicy]
1884
| {*instance*}
1885

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

    
1889
Note that since this operation is done via data copy, it will take a
1890
long time for big disks (similar to replace-disks for a drbd
1891
instance).
1892

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

    
1898
The ``--ignore-consistency`` option will make Ganeti ignore any errors
1899
in trying to shutdown the instance on its node; useful if the
1900
hypervisor is broken and you want to recover the data.
1901

    
1902
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1903
during this operation are ignored.
1904

    
1905
See **ganeti**\(7) for a description of ``--submit`` and other common
1906
options.
1907

    
1908
Example::
1909

    
1910
    # gnt-instance move -n node3.example.com instance1.example.com
1911

    
1912

    
1913
CHANGE-GROUP
1914
^^^^^^^^^^^^
1915

    
1916
| **change-group** [\--submit]
1917
| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
1918

    
1919
This command moves an instance to another node group. The move is
1920
calculated by an iallocator, either given on the command line or as a
1921
cluster default.
1922

    
1923
If no specific destination groups are specified using ``--to``, all
1924
groups except the one containing the instance are considered.
1925

    
1926
See **ganeti**\(7) for a description of ``--submit`` and other common
1927
options.
1928

    
1929
Example::
1930

    
1931
    # gnt-instance change-group -I hail --to rack2 inst1.example.com
1932

    
1933

    
1934
Tags
1935
~~~~
1936

    
1937
ADD-TAGS
1938
^^^^^^^^
1939

    
1940
**add-tags** [\--from *file*] {*instancename*} {*tag*...}
1941

    
1942
Add tags to the given instance. If any of the tags contains invalid
1943
characters, the entire operation will abort.
1944

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

    
1951
LIST-TAGS
1952
^^^^^^^^^
1953

    
1954
**list-tags** {*instancename*}
1955

    
1956
List the tags of the given instance.
1957

    
1958
REMOVE-TAGS
1959
^^^^^^^^^^^
1960

    
1961
**remove-tags** [\--from *file*] {*instancename*} {*tag*...}
1962

    
1963
Remove tags from the given instance. If any of the tags are not
1964
existing on the node, the entire operation will abort.
1965

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

    
1972
.. vim: set textwidth=72 :
1973
.. Local Variables:
1974
.. mode: rst
1975
.. fill-column: 72
1976
.. End: