Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.rst @ 94ab995a

History | View | Annotate | Download (71.5 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*[,spindles=*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}]
41
| {{-n|\--node} *node[:secondary-node]* \| {-I|\--iallocator} *name*}
42
| {{-o|\--os-type} *os-type*}
43
| [\--submit] [\--print-job-id]
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
spindles
61
  How many spindles (physical disks on the node) the disk should span.
62

    
63
mode
64
  The access mode. Either ``ro`` (read-only) or the default ``rw``
65
  (read-write).
66

    
67
name
68
   This option specifies a name for the disk, which can be used as a disk
69
   identifier. An instance can not have two disks with the same name.
70

    
71
vg
72
   The LVM volume group. This works only for LVM and DRBD devices.
73

    
74
metavg
75
   This options specifies a different VG for the metadata device. This
76
   works only for DRBD devices
77

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

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

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

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

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

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

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

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

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

    
125
mac
126
    either a value or 'generate' to generate a new unique MAC
127

    
128
ip
129
    specifies the IP address assigned to the instance from the Ganeti
130
    side (this is not necessarily what the instance will use, but what
131
    the node expects the instance to use). Note that if an IP in the
132
    range of a network configured with **gnt-network**\(8) is used,
133
    and the NIC is not already connected to it, this network has to be
134
    passed in the **network** parameter if this NIC is meant to be
135
    connected to the said network. ``--no-conflicts-check`` can be used
136
    to override this check. The special value **pool** causes Ganeti to
137
    select an IP from the the network the NIC is or will be connected to.
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
vlan
164
   in openvswitch mode specifies the VLANs that the NIC will be
165
   connected to. To connect as an access port use ``n`` or ``.n`` with
166
   **n** being the VLAN ID. To connect as an trunk port use ``:n[:n]``.
167
   A hybrid port can be created with ``.n:n[:n]``
168

    
169
Of these "mode" and "link" are NIC parameters, and inherit their
170
default at cluster level.  Alternatively, if no network is desired for
171
the instance, you can prevent the default of one NIC with the
172
``--no-nics`` option.
173

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

    
182
The ``-B (--backend-parameters)`` option specifies the backend
183
parameters for the instance. If no such parameters are specified, the
184
values are inherited from the cluster. Possible parameters are:
185

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

    
190
minmem
191
    the minimum memory size of the instance; as usual, suffixes can be
192
    used to denote the unit, otherwise the value is taken in mebibytes
193

    
194
vcpus
195
    the number of VCPUs to assign to the instance (if this value makes
196
    sense for the hypervisor)
197

    
198
auto\_balance
199
    whether the instance is considered in the N+1 cluster checks
200
    (enough redundancy in the cluster to survive a node failure)
201

    
202
always\_failover
203
    ``True`` or ``False``, whether the instance must be failed over
204
    (shut down and rebooted) always or it may be migrated (briefly
205
    suspended)
206

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

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

    
220
The possible hypervisor options are as follows:
221

    
222
boot\_order
223
    Valid for the Xen HVM and KVM hypervisors.
224

    
225
    A string value denoting the boot order. This has different meaning
226
    for the Xen HVM hypervisor and for the KVM one.
227

    
228
    For Xen HVM, The boot order is a string of letters listing the boot
229
    devices, with valid device letters being:
230

    
231
    a
232
        floppy drive
233

    
234
    c
235
        hard disk
236

    
237
    d
238
        CDROM drive
239

    
240
    n
241
        network boot (PXE)
242

    
243
    The default is not to set an HVM boot order, which is interpreted
244
    as 'dc'.
245

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

    
253
blockdev\_prefix
254
    Valid for the Xen HVM and PVM hypervisors.
255

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

    
260
floppy\_image\_path
261
    Valid for the KVM hypervisor.
262

    
263
    The path to a floppy disk image to attach to the instance.  This
264
    is useful to install Windows operating systems on Virt/IO disks
265
    because you can specify here the floppy for the drivers at
266
    installation time.
267

    
268
cdrom\_image\_path
269
    Valid for the Xen HVM and KVM hypervisors.
270

    
271
    The path to a CDROM image to attach to the instance.
272

    
273
cdrom2\_image\_path
274
    Valid for the KVM hypervisor.
275

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

    
280
nic\_type
281
    Valid for the Xen HVM and KVM hypervisors.
282

    
283
    This parameter determines the way the network cards are presented
284
    to the instance. The possible options are:
285

    
286
    - rtl8139 (default for Xen HVM) (HVM & KVM)
287
    - ne2k\_isa (HVM & KVM)
288
    - ne2k\_pci (HVM & KVM)
289
    - i82551 (KVM)
290
    - i82557b (KVM)
291
    - i82559er (KVM)
292
    - pcnet (KVM)
293
    - e1000 (KVM)
294
    - paravirtual (default for KVM) (HVM & KVM)
295

    
296
vif\_type
297
    Valid for the Xen HVM hypervisor.
298

    
299
    This parameter specifies the vif type of the nic configuration
300
    of the instance. Unsetting the value leads to no type being specified
301
    in the configuration. Note that this parameter only takes effect when
302
    the 'nic_type' is not set. The possible options are:
303

    
304
    - ioemu
305
    - vif
306

    
307
disk\_type
308
    Valid for the Xen HVM and KVM hypervisors.
309

    
310
    This parameter determines the way the disks are presented to the
311
    instance. The possible options are:
312

    
313
    - ioemu [default] (HVM & KVM)
314
    - ide (HVM & KVM)
315
    - scsi (KVM)
316
    - sd (KVM)
317
    - mtd (KVM)
318
    - pflash (KVM)
319

    
320

    
321
cdrom\_disk\_type
322
    Valid for the KVM hypervisor.
323

    
324
    This parameter determines the way the cdroms disks are presented
325
    to the instance. The default behavior is to get the same value of
326
    the earlier parameter (disk_type). The possible options are:
327

    
328
    - paravirtual
329
    - ide
330
    - scsi
331
    - sd
332
    - mtd
333
    - pflash
334

    
335

    
336
vnc\_bind\_address
337
    Valid for the Xen HVM and KVM hypervisors.
338

    
339
    Specifies the address that the VNC listener for this instance
340
    should bind to. Valid values are IPv4 addresses. Use the address
341
    0.0.0.0 to bind to all available interfaces (this is the default)
342
    or specify the address of one of the interfaces on the node to
343
    restrict listening to that interface.
344

    
345
vnc\_tls
346
    Valid for the KVM hypervisor.
347

    
348
    A boolean option that controls whether the VNC connection is
349
    secured with TLS.
350

    
351
vnc\_x509\_path
352
    Valid for the KVM hypervisor.
353

    
354
    If ``vnc_tls`` is enabled, this options specifies the path to the
355
    x509 certificate to use.
356

    
357
vnc\_x509\_verify
358
    Valid for the KVM hypervisor.
359

    
360
spice\_bind
361
    Valid for the KVM hypervisor.
362

    
363
    Specifies the address or interface on which the SPICE server will
364
    listen. Valid values are:
365

    
366
    - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
367
    - IPv6 addresses, including :: and ::1
368
    - names of network interfaces
369

    
370
    If a network interface is specified, the SPICE server will be bound
371
    to one of the addresses of that interface.
372

    
373
spice\_ip\_version
374
    Valid for the KVM hypervisor.
375

    
376
    Specifies which version of the IP protocol should be used by the
377
    SPICE server.
378

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

    
385
spice\_password\_file
386
    Valid for the KVM hypervisor.
387

    
388
    Specifies a file containing the password that must be used when
389
    connecting via the SPICE protocol. If the option is not specified,
390
    passwordless connections are allowed.
391

    
392
spice\_image\_compression
393
    Valid for the KVM hypervisor.
394

    
395
    Configures the SPICE lossless image compression. Valid values are:
396

    
397
    - auto_glz
398
    - auto_lz
399
    - quic
400
    - glz
401
    - lz
402
    - off
403

    
404
spice\_jpeg\_wan\_compression
405
    Valid for the KVM hypervisor.
406

    
407
    Configures how SPICE should use the jpeg algorithm for lossy image
408
    compression on slow links. Valid values are:
409

    
410
    - auto
411
    - never
412
    - always
413

    
414
spice\_zlib\_glz\_wan\_compression
415
    Valid for the KVM hypervisor.
416

    
417
    Configures how SPICE should use the zlib-glz algorithm for lossy image
418
    compression on slow links. Valid values are:
419

    
420
    - auto
421
    - never
422
    - always
423

    
424
spice\_streaming\_video
425
    Valid for the KVM hypervisor.
426

    
427
    Configures how SPICE should detect video streams. Valid values are:
428

    
429
    - off
430
    - all
431
    - filter
432

    
433
spice\_playback\_compression
434
    Valid for the KVM hypervisor.
435

    
436
    Configures whether SPICE should compress audio streams or not.
437

    
438
spice\_use\_tls
439
    Valid for the KVM hypervisor.
440

    
441
    Specifies that the SPICE server must use TLS to encrypt all the
442
    traffic with the client.
443

    
444
spice\_tls\_ciphers
445
    Valid for the KVM hypervisor.
446

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

    
450
spice\_use\_vdagent
451
    Valid for the KVM hypervisor.
452

    
453
    Enables or disables passing mouse events via SPICE vdagent.
454

    
455
cpu\_type
456
    Valid for the KVM hypervisor.
457

    
458
    This parameter determines the emulated cpu for the instance. If this
459
    parameter is empty (which is the default configuration), it will not
460
    be passed to KVM.
461

    
462
    Be aware of setting this parameter to ``"host"`` if you have nodes
463
    with different CPUs from each other. Live migration may stop working
464
    in this situation.
465

    
466
    For more information please refer to the KVM manual.
467

    
468
acpi
469
    Valid for the Xen HVM and KVM hypervisors.
470

    
471
    A boolean option that specifies if the hypervisor should enable
472
    ACPI support for this instance. By default, ACPI is disabled.
473

    
474
pae
475
    Valid for the Xen HVM and KVM hypervisors.
476

    
477
    A boolean option that specifies if the hypervisor should enable
478
    PAE support for this instance. The default is false, disabling PAE
479
    support.
480

    
481
viridian
482
    Valid for the Xen HVM hypervisor.
483

    
484
    A boolean option that specifies if the hypervisor should enable
485
    viridian (Hyper-V) for this instance. The default is false,
486
    disabling viridian support.
487

    
488
use\_localtime
489
    Valid for the Xen HVM and KVM hypervisors.
490

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

    
497
kernel\_path
498
    Valid for the Xen PVM and KVM hypervisors.
499

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

    
506
kernel\_args
507
    Valid for the Xen PVM and KVM hypervisors.
508

    
509
    This options specifies extra arguments to the kernel that will be
510
    loaded. device. This is always used for Xen PVM, while for KVM it
511
    is only used if the ``kernel_path`` option is also specified.
512

    
513
    The default setting for this value is simply ``"ro"``, which
514
    mounts the root disk (initially) in read-only one. For example,
515
    setting this to single will cause the instance to start in
516
    single-user mode.
517

    
518
initrd\_path
519
    Valid for the Xen PVM and KVM hypervisors.
520

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

    
528
root\_path
529
    Valid for the Xen PVM and KVM hypervisors.
530

    
531
    This options specifies the name of the root device. This is always
532
    needed for Xen PVM, while for KVM it is only used if the
533
    ``kernel_path`` option is also specified.
534

    
535
    Please note, that if this setting is an empty string and the
536
    hypervisor is Xen it will not be written to the Xen configuration
537
    file
538

    
539
serial\_console
540
    Valid for the KVM hypervisor.
541

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

    
549
serial\_speed
550
    Valid for the KVM hypervisor.
551

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

    
557
disk\_cache
558
    Valid for the KVM hypervisor.
559

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

    
570
security\_model
571
    Valid for the KVM hypervisor.
572

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

    
577
    Under *user* kvm will drop privileges and become the user
578
    specified by the security\_domain parameter.
579

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

    
584
security\_domain
585
    Valid for the KVM hypervisor.
586

    
587
    Under security model *user* the username to run the instance
588
    under.  It must be a valid username existing on the host.
589

    
590
    Cannot be set under security model *none* or *pool*.
591

    
592
kvm\_flag
593
    Valid for the KVM hypervisor.
594

    
595
    If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
596
    -disable-kvm is passed. If unset no flag is passed, and the
597
    default running mode for your kvm binary will be used.
598

    
599
mem\_path
600
    Valid for the KVM hypervisor.
601

    
602
    This option passes the -mem-path argument to kvm with the path (on
603
    the node) to the mount point of the hugetlbfs file system, along
604
    with the -mem-prealloc argument too.
605

    
606
use\_chroot
607
    Valid for the KVM hypervisor.
608

    
609
    This boolean option determines whether to run the KVM instance in a
610
    chroot directory.
611

    
612
    If it is set to ``true``, an empty directory is created before
613
    starting the instance and its path is passed via the -chroot flag
614
    to kvm. The directory is removed when the instance is stopped.
615

    
616
    It is set to ``false`` by default.
617

    
618
migration\_downtime
619
    Valid for the KVM hypervisor.
620

    
621
    The maximum amount of time (in ms) a KVM instance is allowed to be
622
    frozen during a live migration, in order to copy dirty memory
623
    pages. Default value is 30ms, but you may need to increase this
624
    value for busy instances.
625

    
626
    This option is only effective with kvm versions >= 87 and qemu-kvm
627
    versions >= 0.11.0.
628

    
629
cpu\_mask
630
    Valid for the Xen, KVM and LXC hypervisors.
631

    
632
    The processes belonging to the given instance are only scheduled
633
    on the specified CPUs.
634

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

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

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

    
653
    Example:
654

    
655
    .. code-block:: bash
656

    
657
      # Map the entire instance to CPUs 0-2
658
      gnt-instance modify -H cpu_mask=0-2 my-inst
659

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

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

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

    
670
      # Pin entire VM to CPU 0
671
      gnt-instance modify -H cpu_mask=0 my-inst
672

    
673
      # Turn off CPU pinning (default setting)
674
      gnt-instance modify -H cpu_mask=all my-inst
675

    
676
cpu\_cap
677
    Valid for the Xen hypervisor.
678

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

    
682
cpu\_weight
683
    Valid for the Xen hypervisor.
684

    
685
    Set the cpu time ratio to be allocated to the VM. Valid values are
686
    between 1 and 65535. Default weight is 256.
687

    
688
usb\_mouse
689
    Valid for the KVM hypervisor.
690

    
691
    This option specifies the usb mouse type to be used. It can be
692
    "mouse" or "tablet". When using VNC it's recommended to set it to
693
    "tablet".
694

    
695
keymap
696
    Valid for the KVM hypervisor.
697

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

    
701
reboot\_behavior
702
    Valid for Xen PVM, Xen HVM and KVM hypervisors.
703

    
704
    Normally if an instance reboots, the hypervisor will restart it. If
705
    this option is set to ``exit``, the hypervisor will treat a reboot
706
    as a shutdown instead.
707

    
708
    It is set to ``reboot`` by default.
709

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

    
713
    Number of emulated CPU cores.
714

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

    
718
    Number of emulated CPU threads.
719

    
720
cpu\_sockets
721
    Valid for the KVM hypervisor.
722

    
723
    Number of emulated CPU sockets.
724

    
725
soundhw
726
    Valid for the KVM and XEN hypervisors.
727

    
728
    Comma separated list of emulated sounds cards, or "all" to enable
729
    all the available ones.
730

    
731
cpuid
732
    Valid for the XEN hypervisor.
733

    
734
    Modify the values returned by CPUID_ instructions run within instances.
735

    
736
    This allows you to enable migration between nodes with different CPU
737
    attributes like cores, threads, hyperthreading or SS4 support by hiding
738
    the extra features where needed.
739

    
740
    See the XEN documentation for syntax and more information.
741

    
742
.. _CPUID: http://en.wikipedia.org/wiki/CPUID
743

    
744
usb\_devices
745
    Valid for the KVM hypervisor.
746

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

    
752
vga
753
    Valid for the KVM hypervisor.
754

    
755
    Emulated vga mode, passed the the kvm -vga option.
756

    
757
kvm\_extra
758
    Valid for the KVM hypervisor.
759

    
760
    Any other option to the KVM hypervisor, useful tweaking anything
761
    that Ganeti doesn't support. Note that values set with this
762
    parameter are split on a space character and currently don't support
763
    quoting.
764

    
765
machine\_version
766
    Valid for the KVM hypervisor.
767

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

    
772
kvm\_path
773
    Valid for the KVM hypervisor.
774

    
775
    Path to the userspace KVM (or qemu) program.
776

    
777
vnet\_hdr
778
    Valid for the KVM hypervisor.
779

    
780
    This boolean option determines whether the tap devices used by the
781
    KVM paravirtual nics (virtio-net) will get created with VNET_HDR
782
    (IFF_VNET_HDR) support.
783

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

    
788
    It is set to ``true`` by default.
789

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

    
795
    gnt-instance add -O dhcp=yes ...
796

    
797
The ``-I (--iallocator)`` option specifies the instance allocator plugin
798
to use (``.`` means the default allocator). If you pass in this option
799
the allocator will select nodes for this instance automatically, so you
800
don't need to pass them with the ``-n`` option. For more information
801
please refer to the instance allocator documentation.
802

    
803
The ``-t (--disk-template)`` options specifies the disk layout type
804
for the instance. If no disk template is specified, the default disk
805
template is used. The default disk template is the first in the list
806
of enabled disk templates, which can be adjusted cluster-wide with
807
``gnt-cluster modify``. The available choices for disk templates are:
808

    
809
diskless
810
    This creates an instance with no disks. Its useful for testing only
811
    (or other special cases).
812

    
813
file
814
    Disk devices will be regular files.
815

    
816
sharedfile
817
    Disk devices will be regulare files on a shared directory.
818

    
819
plain
820
    Disk devices will be logical volumes.
821

    
822
drbd
823
    Disk devices will be drbd (version 8.x) on top of lvm volumes.
824

    
825
rbd
826
    Disk devices will be rbd volumes residing inside a RADOS cluster.
827

    
828
blockdev
829
    Disk devices will be adopted pre-existent block devices.
830

    
831
ext
832
    Disk devices will be provided by external shared storage,
833
    through the ExtStorage Interface using ExtStorage providers.
834

    
835
The optional second value of the ``-n (--node)`` is used for the drbd
836
template type and specifies the remote node.
837

    
838
If you do not want gnt-instance to wait for the disk mirror to be
839
synced, use the ``--no-wait-for-sync`` option.
840

    
841
The ``--file-storage-dir`` specifies the relative path under the
842
cluster-wide file storage directory to store file-based disks. It is
843
useful for having different subdirectories for different
844
instances. The full path of the directory where the disk files are
845
stored will consist of cluster-wide file storage directory + optional
846
subdirectory + instance name. This option is only relevant for
847
instances using the file storage backend.
848

    
849
The ``--file-driver`` specifies the driver to use for file-based
850
disks. Note that currently these drivers work with the xen hypervisor
851
only. This option is only relevant for instances using the file
852
storage backend. The available choices are:
853

    
854
loop
855
    Kernel loopback driver. This driver uses loopback devices to
856
    access the filesystem within the file. However, running I/O
857
    intensive applications in your instance using the loop driver
858
    might result in slowdowns. Furthermore, if you use the loopback
859
    driver consider increasing the maximum amount of loopback devices
860
    (on most systems it's 8) using the max\_loop param.
861

    
862
blktap
863
    The blktap driver (for Xen hypervisors). In order to be able to
864
    use the blktap driver you should check if the 'blktapctrl' user
865
    space disk agent is running (usually automatically started via
866
    xend).  This user-level disk I/O interface has the advantage of
867
    better performance. Especially if you use a network file system
868
    (e.g. NFS) to store your instances this is the recommended choice.
869

    
870
If ``--ignore-ipolicy`` is given any instance policy violations occuring
871
during this operation are ignored.
872

    
873
See **ganeti**\(7) for a description of ``--submit`` and other common
874
options.
875

    
876
Example::
877

    
878
    # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
879
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
880
    # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
881
      -o debian-etch -n node1.example.com instance1.example.com
882
    # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
883
      -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
884
    # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
885
      -n node1.example.com:node2.example.com instance2.example.com
886
    # gnt-instance add -t rbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
887
      -n node1.example.com instance1.example.com
888
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1 -B maxmem=512 \
889
      -o debian-etch -n node1.example.com instance1.example.com
890
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1,param1=val1 \
891
      --disk 1:size=40g,provider=pvdr2,param2=val2,param3=val3 -B maxmem=512 \
892
      -o debian-etch -n node1.example.com instance1.example.com
893

    
894

    
895
BATCH-CREATE
896
^^^^^^^^^^^^
897

    
898
| **batch-create**
899
| [{-I|\--iallocator} *instance allocator*]
900
| {instances\_file.json}
901

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

    
909
The instance file must be a valid-formed JSON file, containing an
910
array of dictionaries with instance creation parameters. All parameters
911
(except ``iallocator``) which are valid for the instance creation
912
OP code are allowed. The most important ones are:
913

    
914
instance\_name
915
    The FQDN of the new instance.
916

    
917
disk\_template
918
    The disk template to use for the instance, the same as in the
919
    **add** command.
920

    
921
disks
922
    Array of disk specifications. Each entry describes one disk as a
923
    dictionary of disk parameters.
924

    
925
beparams
926
    A dictionary of backend parameters.
927

    
928
hypervisor
929
    The hypervisor for the instance.
930

    
931
hvparams
932
    A dictionary with the hypervisor options. If not passed, the default
933
    hypervisor options will be inherited.
934

    
935
nics
936
    List of NICs that will be created for the instance. Each entry
937
    should be a dict, with mac, ip, mode and link as possible keys.
938
    Please don't provide the "mac, ip, mode, link" parent keys if you
939
    use this method for specifying NICs.
940

    
941
pnode, snode
942
    The primary and optionally the secondary node to use for the
943
    instance (in case an iallocator script is not used). If those
944
    parameters are given, they have to be given consistently for all
945
    instances in the batch operation.
946

    
947
start
948
    whether to start the instance
949

    
950
ip\_check
951
    Skip the check for already-in-use instance; see the description in
952
    the **add** command for details.
953

    
954
name\_check
955
    Skip the name check for instances; see the description in the
956
    **add** command for details.
957

    
958
file\_storage\_dir, file\_driver
959
    Configuration for the file disk type, see the **add** command for
960
    details.
961

    
962

    
963
A simple definition for one instance can be (with most of the
964
parameters taken from the cluster defaults)::
965

    
966
    [
967
      {
968
        "mode": "create",
969
        "instance_name": "instance1.example.com",
970
        "disk_template": "drbd",
971
        "os_type": "debootstrap",
972
        "disks": [{"size":"1024"}],
973
        "nics": [{}],
974
        "hypervisor": "xen-pvm"
975
      },
976
      {
977
        "mode": "create",
978
        "instance_name": "instance2.example.com",
979
        "disk_template": "drbd",
980
        "os_type": "debootstrap",
981
        "disks": [{"size":"4096", "mode": "rw", "vg": "xenvg"}],
982
        "nics": [{}],
983
        "hypervisor": "xen-hvm",
984
        "hvparams": {"acpi": true},
985
        "beparams": {"maxmem": 512, "minmem": 256}
986
      }
987
    ]
988

    
989
The command will display the job id for each submitted instance, as
990
follows::
991

    
992
    # gnt-instance batch-create instances.json
993
    Submitted jobs 37, 38
994

    
995
REMOVE
996
^^^^^^
997

    
998
| **remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
999
| [\--print-job-id] [\--force] {*instance*}
1000

    
1001
Remove an instance. This will remove all data from the instance and
1002
there is *no way back*. If you are not sure if you use an instance
1003
again, use **shutdown** first and leave it in the shutdown state for a
1004
while.
1005

    
1006
The ``--ignore-failures`` option will cause the removal to proceed
1007
even in the presence of errors during the removal of the instance
1008
(e.g. during the shutdown or the disk removal). If this option is not
1009
given, the command will stop at the first error.
1010

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

    
1016
The ``--force`` option is used to skip the interactive confirmation.
1017

    
1018
See **ganeti**\(7) for a description of ``--submit`` and other common
1019
options.
1020

    
1021
Example::
1022

    
1023
    # gnt-instance remove instance1.example.com
1024

    
1025

    
1026
LIST
1027
^^^^
1028

    
1029
| **list**
1030
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
1031
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
1032

    
1033
Shows the currently configured instances with memory usage, disk
1034
usage, the node they are running on, and their run status.
1035

    
1036
The ``--no-headers`` option will skip the initial header line. The
1037
``--separator`` option takes an argument which denotes what will be
1038
used between the output fields. Both these options are to help
1039
scripting.
1040

    
1041
The units used to display the numeric values in the output varies,
1042
depending on the options given. By default, the values will be
1043
formatted in the most appropriate unit. If the ``--separator`` option
1044
is given, then the values are shown in mebibytes to allow parsing by
1045
scripts. In both cases, the ``--units`` option can be used to enforce
1046
a given output unit.
1047

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

    
1051
The ``-o (--output)`` option takes a comma-separated list of output
1052
fields. The available fields and their meaning are:
1053

    
1054
@QUERY_FIELDS_INSTANCE@
1055

    
1056
If the value of the option starts with the character ``+``, the new
1057
field(s) will be added to the default list. This allows one to quickly
1058
see the default list plus a few other fields, instead of retyping the
1059
entire list of fields.
1060

    
1061
There is a subtle grouping about the available output fields: all
1062
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
1063
``status`` are configuration value and not run-time values. So if you
1064
don't select any of the these fields, the query will be satisfied
1065
instantly from the cluster configuration, without having to ask the
1066
remote nodes for the data. This can be helpful for big clusters when
1067
you only want some data and it makes sense to specify a reduced set of
1068
output fields.
1069

    
1070
If exactly one argument is given and it appears to be a query filter
1071
(see **ganeti**\(7)), the query result is filtered accordingly. For
1072
ambiguous cases (e.g. a single field name as a filter) the ``--filter``
1073
(``-F``) option forces the argument to be treated as a filter (e.g.
1074
``gnt-instance list -F admin_state``).
1075

    
1076
The default output field list is: ``name``, ``os``, ``pnode``,
1077
``admin_state``, ``oper_state``, ``oper_ram``.
1078

    
1079

    
1080
LIST-FIELDS
1081
^^^^^^^^^^^
1082

    
1083
**list-fields** [field...]
1084

    
1085
Lists available fields for instances.
1086

    
1087

    
1088
INFO
1089
^^^^
1090

    
1091
**info** [-s \| \--static] [\--roman] {\--all \| *instance*}
1092

    
1093
Show detailed information about the given instance(s). This is
1094
different from **list** as it shows detailed data about the instance's
1095
disks (especially useful for the drbd disk template).
1096

    
1097
If the option ``-s`` is used, only information available in the
1098
configuration file is returned, without querying nodes, making the
1099
operation faster.
1100

    
1101
Use the ``--all`` to get info about all instances, rather than
1102
explicitly passing the ones you're interested in.
1103

    
1104
The ``--roman`` option can be used to cause envy among people who like
1105
ancient cultures, but are stuck with non-latin-friendly cluster
1106
virtualization technologies.
1107

    
1108
MODIFY
1109
^^^^^^
1110

    
1111
| **modify**
1112
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
1113
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
1114
| [{-m|\--runtime-memory} *SIZE*]
1115
| [\--net add[:options...] \|
1116
|  \--net [*N*:]add[,options...] \|
1117
|  \--net [*ID*:]remove \|
1118
|  \--net *ID*:modify[,options...]]
1119
| [\--disk add:size=*SIZE*[,options...] \|
1120
|  \--disk *N*:add,size=*SIZE*[,options...] \|
1121
|  \--disk *N*:add,size=*SIZE*,provider=*PROVIDER*[,options...][,param=*value*... ] \|
1122
|  \--disk *ID*:modify[,options...]
1123
|  \--disk [*ID*:]remove]
1124
| [{-t|\--disk-template} plain \| {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
1125
| [\--new-primary=*node*]
1126
| [\--os-type=*OS* [\--force-variant]]
1127
| [{-O|\--os-parameters} *param*=*value*... ]
1128
| [\--offline \| \--online]
1129
| [\--submit] [\--print-job-id]
1130
| [\--ignore-ipolicy]
1131
| {*instance*}
1132

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

    
1138
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
1139
and ``-O (--os-parameters)`` options specifies hypervisor, backend and
1140
OS parameter options in the form of name=value[,...]. For details
1141
which options can be specified, see the **add** command.
1142

    
1143
The ``-t (--disk-template)`` option will change the disk template of
1144
the instance.  Currently only conversions between the plain and drbd
1145
disk templates are supported, and the instance must be stopped before
1146
attempting the conversion. When changing from the plain to the drbd
1147
disk template, a new secondary node must be specified via the ``-n``
1148
option. The option ``--no-wait-for-sync`` can be used when converting
1149
to the ``drbd`` template in order to make the instance available for
1150
startup before DRBD has finished resyncing.
1151

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

    
1156
The ``--disk add:size=*SIZE*,[options..]`` option adds a disk to the
1157
instance, and ``--disk *N*:add:size=*SIZE*,[options..]`` will add a disk
1158
to the the instance at a specific index. The available options are the
1159
same as in the **add** command(``spindles``, ``mode``, ``name``, ``vg``,
1160
``metavg``). Per default, gnt-instance waits for the disk mirror to sync.
1161
If you do not want this behavior, use the ``--no-wait-for-sync`` option.
1162
When adding an ExtStorage disk, the ``provider=*PROVIDER*`` option is
1163
also mandatory and specifies the ExtStorage provider. Also, for
1164
ExtStorage disks arbitrary parameters can be passed as additional comma
1165
separated options, same as in the **add** command. The ``--disk remove``
1166
option will remove the last disk of the instance. Use
1167
``--disk `` *ID*``:remove`` to remove a disk by its identifier. *ID*
1168
can be the index of the disk, the disks's name or the disks's UUID. The
1169
``--disk *ID*:modify[,options...]`` will change the options of the disk.
1170
Available options are:
1171

    
1172
mode
1173
  The access mode. Either ``ro`` (read-only) or the default ``rw`` (read-write).
1174

    
1175
name
1176
   This option specifies a name for the disk, which can be used as a disk
1177
   identifier. An instance can not have two disks with the same name.
1178

    
1179
The ``--net *N*:add[,options..]`` will add a new network interface to
1180
the instance. The available options are the same as in the **add**
1181
command (``mac``, ``ip``, ``link``, ``mode``, ``network``). The
1182
``--net *ID*,remove`` will remove the intances' NIC with *ID* identifier,
1183
which can be the index of the NIC, the NIC's name or the NIC's UUID.
1184
The ``--net *ID*:modify[,options..]`` option will change the parameters of
1185
the instance network interface with the *ID* identifier.
1186

    
1187
The option ``-o (--os-type)`` will change the OS name for the instance
1188
(without reinstallation). In case an OS variant is specified that is
1189
not found, then by default the modification is refused, unless
1190
``--force-variant`` is passed. An invalid OS will also be refused,
1191
unless the ``--force`` option is given.
1192

    
1193
The option ``--new-primary`` will set the new primary node of an instance
1194
assuming the disks have already been moved manually. Unless the ``--force``
1195
option is given, it is verified that the instance is no longer running
1196
on its current primary node.
1197

    
1198
The ``--online`` and ``--offline`` options are used to transition an
1199
instance into and out of the ``offline`` state. An instance can be
1200
turned offline only if it was previously down. The ``--online`` option
1201
fails if the instance was not in the ``offline`` state, otherwise it
1202
changes instance's state to ``down``. These modifications take effect
1203
immediately.
1204

    
1205
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1206
during this operation are ignored.
1207

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

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

    
1214
REINSTALL
1215
^^^^^^^^^
1216

    
1217
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
1218
| [\--force-multiple]
1219
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1220
| [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] [\--print-job-id]
1221
| {*instance*...}
1222

    
1223
Reinstalls the operating system on the given instance(s). The
1224
instance(s) must be stopped when running this command. If the ``-o
1225
(--os-type)`` is specified, the operating system is changed.
1226

    
1227
The ``--select-os`` option switches to an interactive OS reinstall.
1228
The user is prompted to select the OS template from the list of
1229
available OS templates. OS parameters can be overridden using ``-O
1230
(--os-parameters)`` (more documentation for this option under the
1231
**add** command).
1232

    
1233
Since this is a potentially dangerous command, the user will be
1234
required to confirm this action, unless the ``-f`` flag is passed.
1235
When multiple instances are selected (either by passing multiple
1236
arguments or by using the ``--node``, ``--primary``, ``--secondary``
1237
or ``--all`` options), the user must pass the ``--force-multiple``
1238
options to skip the interactive confirmation.
1239

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

    
1243
RENAME
1244
^^^^^^
1245

    
1246
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit] [\--print-job-id]
1247
| {*instance*} {*new\_name*}
1248

    
1249
Renames the given instance. The instance must be stopped when running
1250
this command. The requirements for the new name are the same as for
1251
adding an instance: the new name must be resolvable and the IP it
1252
resolves to must not be reachable (in order to prevent duplicate IPs
1253
the next time the instance is started). The IP test can be skipped if
1254
the ``--no-ip-check`` option is passed.
1255

    
1256
Note that you can rename an instance to its same name, to force
1257
re-executing the os-specific rename script for that instance, if
1258
needed.
1259

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

    
1266
See **ganeti**\(7) for a description of ``--submit`` and other common
1267
options.
1268

    
1269
Starting/stopping/connecting to console
1270
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1271

    
1272
STARTUP
1273
^^^^^^^
1274

    
1275
| **startup**
1276
| [\--force] [\--ignore-offline]
1277
| [\--force-multiple] [\--no-remember]
1278
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1279
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1280
| [{-H|\--hypervisor-parameters} ``key=value...``]
1281
| [{-B|\--backend-parameters} ``key=value...``]
1282
| [\--submit] [\--print-job-id] [\--paused]
1283
| {*name*...}
1284

    
1285
Starts one or more instances, depending on the following options.  The
1286
four available modes are:
1287

    
1288
\--instance
1289
    will start the instances given as arguments (at least one argument
1290
    required); this is the default selection
1291

    
1292
\--node
1293
    will start the instances who have the given node as either primary
1294
    or secondary
1295

    
1296
\--primary
1297
    will start all instances whose primary node is in the list of nodes
1298
    passed as arguments (at least one node required)
1299

    
1300
\--secondary
1301
    will start all instances whose secondary node is in the list of
1302
    nodes passed as arguments (at least one node required)
1303

    
1304
\--all
1305
    will start all instances in the cluster (no arguments accepted)
1306

    
1307
\--tags
1308
    will start all instances in the cluster with the tags given as
1309
    arguments
1310

    
1311
\--node-tags
1312
    will start all instances in the cluster on nodes with the tags
1313
    given as arguments
1314

    
1315
\--pri-node-tags
1316
    will start all instances in the cluster on primary nodes with the
1317
    tags given as arguments
1318

    
1319
\--sec-node-tags
1320
    will start all instances in the cluster on secondary nodes with the
1321
    tags given as arguments
1322

    
1323
Note that although you can pass more than one selection option, the
1324
last one wins, so in order to guarantee the desired result, don't pass
1325
more than one such option.
1326

    
1327
Use ``--force`` to start even if secondary disks are failing.
1328
``--ignore-offline`` can be used to ignore offline primary nodes and
1329
mark the instance as started even if the primary is not available.
1330

    
1331
The ``--force-multiple`` will skip the interactive confirmation in the
1332
case the more than one instance will be affected.
1333

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

    
1340
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
1341
options specify temporary hypervisor and backend parameters that can
1342
be used to start an instance with modified parameters. They can be
1343
useful for quick testing without having to modify an instance back and
1344
forth, e.g.::
1345

    
1346
    # gnt-instance start -H kernel_args="single" instance1
1347
    # gnt-instance start -B maxmem=2048 instance2
1348

    
1349

    
1350
The first form will start the instance instance1 in single-user mode,
1351
and the instance instance2 with 2GB of RAM (this time only, unless
1352
that is the actual instance memory size already). Note that the values
1353
override the instance parameters (and not extend them): an instance
1354
with "kernel\_args=ro" when started with -H kernel\_args=single will
1355
result in "single", not "ro single".
1356

    
1357
The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
1358
pauses the instance at the start of bootup, awaiting ``gnt-instance
1359
console`` to unpause it, allowing the entire boot process to be
1360
monitored for debugging.
1361

    
1362
See **ganeti**\(7) for a description of ``--submit`` and other common
1363
options.
1364

    
1365
Example::
1366

    
1367
    # gnt-instance start instance1.example.com
1368
    # gnt-instance start --node node1.example.com node2.example.com
1369
    # gnt-instance start --all
1370

    
1371

    
1372
SHUTDOWN
1373
^^^^^^^^
1374

    
1375
| **shutdown**
1376
| [\--timeout=*N*]
1377
| [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember]
1378
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1379
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1380
| [\--submit] [\--print-job-id]
1381
| {*name*...}
1382

    
1383
Stops one or more instances. If the instance cannot be cleanly stopped
1384
during a hardcoded interval (currently 2 minutes), it will forcibly
1385
stop the instance (equivalent to switching off the power on a physical
1386
machine).
1387

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

    
1393
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1394
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1395
``--sec-node-tags`` options are similar as for the **startup** command
1396
and they influence the actual instances being shutdown.
1397

    
1398
``--ignore-offline`` can be used to ignore offline primary nodes and
1399
force the instance to be marked as stopped. This option should be used
1400
with care as it can lead to an inconsistent cluster state.
1401

    
1402
Use ``--force`` to be able to shutdown an instance even when it's marked
1403
as offline. This is useful is an offline instance ends up in the
1404
``ERROR_up`` state, for example.
1405

    
1406
The ``--no-remember`` option will perform the shutdown but not change
1407
the state of the instance in the configuration file (if it was running
1408
before, Ganeti will still thinks it needs to be running). This can be
1409
useful for a cluster-wide shutdown, where some instances are marked as
1410
up and some as down, and you don't want to change the running state:
1411
you just need to disable the watcher, shutdown all instances with
1412
``--no-remember``, and when the watcher is activated again it will
1413
restore the correct runtime state for all instances.
1414

    
1415
See **ganeti**\(7) for a description of ``--submit`` and other common
1416
options.
1417

    
1418
Example::
1419

    
1420
    # gnt-instance shutdown instance1.example.com
1421
    # gnt-instance shutdown --all
1422

    
1423

    
1424
REBOOT
1425
^^^^^^
1426

    
1427
| **reboot**
1428
| [{-t|\--type} *REBOOT-TYPE*]
1429
| [\--ignore-secondaries]
1430
| [\--shutdown-timeout=*N*]
1431
| [\--force-multiple]
1432
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1433
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1434
| [\--submit] [\--print-job-id]
1435
| [*name*...]
1436

    
1437
Reboots one or more instances. The type of reboot depends on the value
1438
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1439
does a instance stop, recreates the hypervisor config for the instance
1440
and starts the instance. A full reboot does the equivalent of
1441
**gnt-instance shutdown && gnt-instance startup**.  The default is
1442
hard reboot.
1443

    
1444
For the hard reboot the option ``--ignore-secondaries`` ignores errors
1445
for the secondary node while re-assembling the instance disks.
1446

    
1447
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1448
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1449
``--sec-node-tags`` options are similar as for the **startup** command
1450
and they influence the actual instances being rebooted.
1451

    
1452
The ``--shutdown-timeout`` is used to specify how much time to wait
1453
before forcing the shutdown (xm destroy in xen, killing the kvm
1454
process, for kvm). By default two minutes are given to each instance
1455
to stop.
1456

    
1457
The ``--force-multiple`` will skip the interactive confirmation in the
1458
case the more than one instance will be affected.
1459

    
1460
See **ganeti**\(7) for a description of ``--submit`` and other common
1461
options.
1462

    
1463
Example::
1464

    
1465
    # gnt-instance reboot instance1.example.com
1466
    # gnt-instance reboot --type=full instance1.example.com
1467

    
1468

    
1469
CONSOLE
1470
^^^^^^^
1471

    
1472
**console** [\--show-cmd] {*instance*}
1473

    
1474
Connects to the console of the given instance. If the instance is not
1475
up, an error is returned. Use the ``--show-cmd`` option to display the
1476
command instead of executing it.
1477

    
1478
For HVM instances, this will attempt to connect to the serial console
1479
of the instance. To connect to the virtualized "physical" console of a
1480
HVM instance, use a VNC client with the connection info from the
1481
**info** command.
1482

    
1483
For Xen/kvm instances, if the instance is paused, this attempts to
1484
unpause the instance after waiting a few seconds for the connection to
1485
the console to be made.
1486

    
1487
Example::
1488

    
1489
    # gnt-instance console instance1.example.com
1490

    
1491

    
1492
Disk management
1493
~~~~~~~~~~~~~~~
1494

    
1495
REPLACE-DISKS
1496
^^^^^^^^^^^^^
1497

    
1498
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1499
| [\--ignore-ipolicy] {-p} [\--disks *idx*] {*instance*}
1500

    
1501
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1502
| [\--ignore-ipolicy] {-s} [\--disks *idx*] {*instance*}
1503

    
1504
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1505
| [\--ignore-ipolicy]
1506
| {{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*}
1507

    
1508
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1509
| [\--ignore-ipolicy] {-a\|\--auto} {*instance*}
1510

    
1511
This command is a generalized form for replacing disks. It is
1512
currently only valid for the mirrored (DRBD) disk template.
1513

    
1514
The first form (when passing the ``-p`` option) will replace the disks
1515
on the primary, while the second form (when passing the ``-s`` option
1516
will replace the disks on the secondary node. For these two cases (as
1517
the node doesn't change), it is possible to only run the replace for a
1518
subset of the disks, using the option ``--disks`` which takes a list
1519
of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only
1520
the first and third disks.
1521

    
1522
The third form (when passing either the ``--iallocator`` or the
1523
``--new-secondary`` option) is designed to change secondary node of the
1524
instance. Specifying ``--iallocator`` makes the new secondary be
1525
selected automatically by the specified allocator plugin (use ``.`` to
1526
indicate the default allocator), otherwise the new secondary node will
1527
be the one chosen manually via the ``--new-secondary`` option.
1528

    
1529
Note that it is not possible to select an offline or drained node as a
1530
new secondary.
1531

    
1532
The fourth form (when using ``--auto``) will automatically determine
1533
which disks of an instance are faulty and replace them within the same
1534
node. The ``--auto`` option works only when an instance has only
1535
faulty disks on either the primary or secondary node; it doesn't work
1536
when both sides have faulty disks.
1537

    
1538
The ``--early-release`` changes the code so that the old storage on
1539
secondary node(s) is removed early (before the resync is completed)
1540
and the internal Ganeti locks for the current (and new, if any)
1541
secondary node are also released, thus allowing more parallelism in
1542
the cluster operation. This should be used only when recovering from a
1543
disk failure on the current secondary (thus the old storage is already
1544
broken) or when the storage on the primary node is known to be fine
1545
(thus we won't need the old storage for potential recovery).
1546

    
1547
The ``--ignore-ipolicy`` let the command ignore instance policy
1548
violations if replace-disks changes groups and the instance would
1549
violate the new groups instance policy.
1550

    
1551
See **ganeti**\(7) for a description of ``--submit`` and other common
1552
options.
1553

    
1554
ACTIVATE-DISKS
1555
^^^^^^^^^^^^^^
1556

    
1557
| **activate-disks** [\--submit] [\--print-job-id] [\--ignore-size]
1558
| [\--wait-for-sync] {*instance*}
1559

    
1560
Activates the block devices of the given instance. If successful, the
1561
command will show the location and name of the block devices::
1562

    
1563
    node1.example.com:disk/0:/dev/drbd0
1564
    node1.example.com:disk/1:/dev/drbd1
1565

    
1566

    
1567
In this example, *node1.example.com* is the name of the node on which
1568
the devices have been activated. The *disk/0* and *disk/1* are the
1569
Ganeti-names of the instance disks; how they are visible inside the
1570
instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the
1571
actual block devices as visible on the node.
1572

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

    
1580
The ``--wait-for-sync`` option will ensure that the command returns only
1581
after the instance's disks are synchronised (mostly for DRBD); this can
1582
be useful to ensure consistency, as otherwise there are no commands that
1583
can wait until synchronisation is done. However when passing this
1584
option, the command will have additional output, making it harder to
1585
parse the disk information.
1586

    
1587
Note that it is safe to run this command while the instance is already
1588
running.
1589

    
1590
See **ganeti**\(7) for a description of ``--submit`` and other common
1591
options.
1592

    
1593
DEACTIVATE-DISKS
1594
^^^^^^^^^^^^^^^^
1595

    
1596
**deactivate-disks** [-f] [\--submit] [\--print-job-id] {*instance*}
1597

    
1598
De-activates the block devices of the given instance. Note that if you
1599
run this command for an instance with a drbd disk template, while it
1600
is running, it will not be able to shutdown the block devices on the
1601
primary node, but it will shutdown the block devices on the secondary
1602
nodes, thus breaking the replication.
1603

    
1604
The ``-f``/``--force`` option will skip checks that the instance is
1605
down; in case the hypervisor is confused and we can't talk to it,
1606
normally Ganeti will refuse to deactivate the disks, but with this
1607
option passed it will skip this check and directly try to deactivate
1608
the disks. This can still fail due to the instance actually running or
1609
other issues.
1610

    
1611
See **ganeti**\(7) for a description of ``--submit`` and other common
1612
options.
1613

    
1614
GROW-DISK
1615
^^^^^^^^^
1616

    
1617
| **grow-disk** [\--no-wait-for-sync] [\--submit] [\--print-job-id]
1618
| [\--absolute]
1619
| {*instance*} {*disk*} {*amount*}
1620

    
1621
Grows an instance's disk. This is only possible for instances having a
1622
plain, drbd, file, sharedfile, rbd or ext disk template. For the ext
1623
template to work, the ExtStorage provider should also support growing.
1624
This means having a ``grow`` script that actually grows the volume of
1625
the external shared storage.
1626

    
1627
Note that this command only change the block device size; it will not
1628
grow the actual filesystems, partitions, etc. that live on that
1629
disk. Usually, you will need to:
1630

    
1631
#. use **gnt-instance grow-disk**
1632

    
1633
#. reboot the instance (later, at a convenient time)
1634

    
1635
#. use a filesystem resizer, such as **ext2online**\(8) or
1636
   **xfs\_growfs**\(8) to resize the filesystem, or use **fdisk**\(8) to
1637
   change the partition table on the disk
1638

    
1639
The *disk* argument is the index of the instance disk to grow. The
1640
*amount* argument is given as a number which can have a suffix (like the
1641
disk size in instance create); if the suffix is missing, the value will
1642
be interpreted as mebibytes.
1643

    
1644
By default, the *amount* value represents the desired increase in the
1645
disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If
1646
the optional ``--absolute`` parameter is passed, then the *amount*
1647
argument doesn't represent the delta, but instead the desired final disk
1648
size (e.g. an amount of 8G will take a disk of size 4G to 8G).
1649

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

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

    
1658
See **ganeti**\(7) for a description of ``--submit`` and other common
1659
options.
1660

    
1661
Example (increase the first disk for instance1 by 16GiB)::
1662

    
1663
    # gnt-instance grow-disk instance1.example.com 0 16g
1664

    
1665
Example for increasing the disk size to a certain size::
1666

    
1667
   # gnt-instance grow-disk --absolute instance1.example.com 0 32g
1668

    
1669
Also note that disk shrinking is not supported; use **gnt-backup
1670
export** and then **gnt-backup import** to reduce the disk size of an
1671
instance.
1672

    
1673
RECREATE-DISKS
1674
^^^^^^^^^^^^^^
1675

    
1676
| **recreate-disks** [\--submit] [\--print-job-id]
1677
| [{-n node1:[node2] \| {-I\|\--iallocator *name*}}]
1678
| [\--disk=*N*[:[size=*VAL*][,spindles=*VAL*][,mode=*ro\|rw*]]] {*instance*}
1679

    
1680
Recreates all or a subset of disks of the given instance.
1681

    
1682
Note that this functionality should only be used for missing disks; if
1683
any of the given disks already exists, the operation will fail.  While
1684
this is suboptimal, recreate-disks should hopefully not be needed in
1685
normal operation and as such the impact of this is low.
1686

    
1687
If only a subset should be recreated, any number of ``disk`` options can
1688
be specified. It expects a disk index and an optional list of disk
1689
parameters to change. Only ``size``, ``spindles``, and ``mode`` can be
1690
changed while recreating disks. To recreate all disks while changing
1691
parameters on a subset only, a ``--disk`` option must be given for every
1692
disk of the instance.
1693

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

    
1703
Another method of choosing which nodes to place the instance on is by
1704
using the specified iallocator, passing the ``--iallocator`` option.
1705
The primary and secondary nodes will be chosen by the specified
1706
iallocator plugin, or by the default allocator if ``.`` is specified.
1707

    
1708
See **ganeti**\(7) for a description of ``--submit`` and other common
1709
options.
1710

    
1711
Recovery/moving
1712
~~~~~~~~~~~~~~~
1713

    
1714
FAILOVER
1715
^^^^^^^^
1716

    
1717
| **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy]
1718
| [\--shutdown-timeout=*N*]
1719
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*]
1720
| [\--cleanup]
1721
| [\--submit] [\--print-job-id]
1722
| {*instance*}
1723

    
1724
Failover will stop the instance (if running), change its primary node,
1725
and if it was originally running it will start it again (on the new
1726
primary). This works for instances with drbd template (in which case you
1727
can only fail to the secondary node) and for externally mirrored
1728
templates (sharedfile, blockdev, rbd and ext) (in which case you can
1729
fail to any other node).
1730

    
1731
If the instance's disk template is of type sharedfile, blockdev, rbd or
1732
ext, then you can explicitly specify the target node (which can be any
1733
node) using the ``-n`` or ``--target-node`` option, or specify an
1734
iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
1735
omit both, the default iallocator will be used to specify the target
1736
node.
1737

    
1738
If the instance's disk template is of type drbd, the target node is
1739
automatically selected as the drbd's secondary node. Changing the
1740
secondary node is possible with a replace-disks operation.
1741

    
1742
Normally the failover will check the consistency of the disks before
1743
failing over the instance. If you are trying to migrate instances off
1744
a dead node, this will fail. Use the ``--ignore-consistency`` option
1745
for this purpose. Note that this option can be dangerous as errors in
1746
shutting down the instance will be ignored, resulting in possibly
1747
having the instance running on two machines in parallel (on
1748
disconnected DRBD drives).
1749

    
1750
The ``--shutdown-timeout`` is used to specify how much time to wait
1751
before forcing the shutdown (xm destroy in xen, killing the kvm
1752
process, for kvm). By default two minutes are given to each instance
1753
to stop.
1754

    
1755
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1756
during this operation are ignored.
1757

    
1758
If the ``--cleanup`` option is passed, the operation changes from
1759
performin a failover to attempting recovery from a failed previous failover.
1760
In this mode, Ganeti checks if the instance runs on the correct node (and
1761
updates its configuration if not) and ensures the instances' disks
1762
are configured correctly.
1763

    
1764
See **ganeti**\(7) for a description of ``--submit`` and other common
1765
options.
1766

    
1767
Example::
1768

    
1769
    # gnt-instance failover instance1.example.com
1770

    
1771
For externally mirrored templates also ``-n`` is available::
1772

    
1773
    # gnt-instance failover -n node3.example.com instance1.example.com
1774

    
1775

    
1776
MIGRATE
1777
^^^^^^^
1778

    
1779
| **migrate** [-f] [\--allow-failover] [\--non-live]
1780
| [\--migration-mode=live\|non-live] [\--ignore-ipolicy]
1781
| [\--no-runtime-changes] [\--submit] [\--print-job-id]
1782
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*}
1783

    
1784
| **migrate** [-f] \--cleanup [\--submit] [\--print-job-id] {*instance*}
1785

    
1786
Migrate will move the instance to its secondary node without shutdown.
1787
As with failover, it works for instances having the drbd disk template
1788
or an externally mirrored disk template type such as sharedfile,
1789
blockdev, rbd or ext.
1790

    
1791
If the instance's disk template is of type sharedfile, blockdev, rbd or
1792
ext, then you can explicitly specify the target node (which can be any
1793
node) using the ``-n`` or ``--target-node`` option, or specify an
1794
iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
1795
omit both, the default iallocator will be used to specify the target
1796
node.  Alternatively, the default iallocator can be requested by
1797
specifying ``.`` as the name of the plugin.
1798

    
1799
If the instance's disk template is of type drbd, the target node is
1800
automatically selected as the drbd's secondary node. Changing the
1801
secondary node is possible with a replace-disks operation.
1802

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

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

    
1819
If the ``--cleanup`` option is passed, the operation changes from
1820
migration to attempting recovery from a failed previous migration. In
1821
this mode, Ganeti checks if the instance runs on the correct node (and
1822
updates its configuration if not) and ensures the instances' disks
1823
are configured correctly. In this mode, the ``--non-live`` option is
1824
ignored.
1825

    
1826
The option ``-f`` will skip the prompting for confirmation.
1827

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

    
1833
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1834
during this operation are ignored.
1835

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

    
1840
If an instance has the backend parameter ``always_failover`` set to
1841
true, then the migration is automatically converted into a failover.
1842

    
1843
See **ganeti**\(7) for a description of ``--submit`` and other common
1844
options.
1845

    
1846
Example (and expected output)::
1847

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

    
1869

    
1870
MOVE
1871
^^^^
1872

    
1873
| **move** [-f] [\--ignore-consistency]
1874
| [-n *node*] [\--compress=*compression-mode*] [\--shutdown-timeout=*N*]
1875
| [\--submit] [\--print-job-id] [\--ignore-ipolicy]
1876
| {*instance*}
1877

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

    
1881
Note that since this operation is done via data copy, it will take a
1882
long time for big disks (similar to replace-disks for a drbd
1883
instance).
1884

    
1885
The ``--compress`` option is used to specify which compression mode
1886
is used during the move. Valid values are 'none' (the default) and
1887
'gzip'.
1888

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

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

    
1898
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1899
during this operation are ignored.
1900

    
1901
See **ganeti**\(7) for a description of ``--submit`` and other common
1902
options.
1903

    
1904
Example::
1905

    
1906
    # gnt-instance move -n node3.example.com instance1.example.com
1907

    
1908

    
1909
CHANGE-GROUP
1910
^^^^^^^^^^^^
1911

    
1912
| **change-group** [\--submit] [\--print-job-id]
1913
| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
1914

    
1915
This command moves an instance to another node group. The move is
1916
calculated by an iallocator, either given on the command line or as a
1917
cluster default.
1918

    
1919
If no specific destination groups are specified using ``--to``, all
1920
groups except the one containing the instance are considered.
1921

    
1922
See **ganeti**\(7) for a description of ``--submit`` and other common
1923
options.
1924

    
1925
Example::
1926

    
1927
    # gnt-instance change-group -I hail --to rack2 inst1.example.com
1928

    
1929

    
1930
Tags
1931
~~~~
1932

    
1933
ADD-TAGS
1934
^^^^^^^^
1935

    
1936
**add-tags** [\--from *file*] {*instancename*} {*tag*...}
1937

    
1938
Add tags to the given instance. If any of the tags contains invalid
1939
characters, the entire operation will abort.
1940

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

    
1947
LIST-TAGS
1948
^^^^^^^^^
1949

    
1950
**list-tags** {*instancename*}
1951

    
1952
List the tags of the given instance.
1953

    
1954
REMOVE-TAGS
1955
^^^^^^^^^^^
1956

    
1957
**remove-tags** [\--from *file*] {*instancename*} {*tag*...}
1958

    
1959
Remove tags from the given instance. If any of the tags are not
1960
existing on the node, the entire operation will abort.
1961

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

    
1968
.. vim: set textwidth=72 :
1969
.. Local Variables:
1970
.. mode: rst
1971
.. fill-column: 72
1972
.. End: