Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.rst @ e15a00dc

History | View | Annotate | Download (71.9 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
| [\--hotplug]
1132
| {*instance*}
1133

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

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

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

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

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

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

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

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

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

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

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

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

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

    
1219
See **ganeti**\(7) for a description of ``--submit`` and other common
1220
options.
1221

    
1222
Most of the changes take effect at the next restart. If the instance is
1223
running, there is no effect on the instance.
1224

    
1225
REINSTALL
1226
^^^^^^^^^
1227

    
1228
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
1229
| [\--force-multiple]
1230
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1231
| [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] [\--print-job-id]
1232
| {*instance*...}
1233

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

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

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

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

    
1254
RENAME
1255
^^^^^^
1256

    
1257
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit] [\--print-job-id]
1258
| {*instance*} {*new\_name*}
1259

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

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

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

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

    
1280
Starting/stopping/connecting to console
1281
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1282

    
1283
STARTUP
1284
^^^^^^^
1285

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

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

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

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

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

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

    
1315
\--all
1316
    will start all instances in the cluster (no arguments accepted)
1317

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

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

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

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

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

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

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

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

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

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

    
1360

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

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

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

    
1376
Example::
1377

    
1378
    # gnt-instance start instance1.example.com
1379
    # gnt-instance start --node node1.example.com node2.example.com
1380
    # gnt-instance start --all
1381

    
1382

    
1383
SHUTDOWN
1384
^^^^^^^^
1385

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

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

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

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

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

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

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

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

    
1429
Example::
1430

    
1431
    # gnt-instance shutdown instance1.example.com
1432
    # gnt-instance shutdown --all
1433

    
1434

    
1435
REBOOT
1436
^^^^^^
1437

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

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

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

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

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

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

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

    
1474
Example::
1475

    
1476
    # gnt-instance reboot instance1.example.com
1477
    # gnt-instance reboot --type=full instance1.example.com
1478

    
1479

    
1480
CONSOLE
1481
^^^^^^^
1482

    
1483
**console** [\--show-cmd] {*instance*}
1484

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

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

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

    
1498
Example::
1499

    
1500
    # gnt-instance console instance1.example.com
1501

    
1502

    
1503
Disk management
1504
~~~~~~~~~~~~~~~
1505

    
1506
REPLACE-DISKS
1507
^^^^^^^^^^^^^
1508

    
1509
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1510
| [\--ignore-ipolicy] {-p} [\--disks *idx*] {*instance*}
1511

    
1512
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1513
| [\--ignore-ipolicy] {-s} [\--disks *idx*] {*instance*}
1514

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

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

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

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

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

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

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

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

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

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

    
1565
ACTIVATE-DISKS
1566
^^^^^^^^^^^^^^
1567

    
1568
| **activate-disks** [\--submit] [\--print-job-id] [\--ignore-size]
1569
| [\--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] [\--print-job-id] {*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] [\--print-job-id]
1629
| [\--absolute]
1630
| {*instance*} {*disk*} {*amount*}
1631

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
1684
RECREATE-DISKS
1685
^^^^^^^^^^^^^^
1686

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

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

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

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

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

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

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

    
1722
Recovery/moving
1723
~~~~~~~~~~~~~~~
1724

    
1725
FAILOVER
1726
^^^^^^^^
1727

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

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

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

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

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

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

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

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

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

    
1778
Example::
1779

    
1780
    # gnt-instance failover instance1.example.com
1781

    
1782
For externally mirrored templates also ``-n`` is available::
1783

    
1784
    # gnt-instance failover -n node3.example.com instance1.example.com
1785

    
1786

    
1787
MIGRATE
1788
^^^^^^^
1789

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

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

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

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

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

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

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

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

    
1837
The option ``-f`` will skip the prompting for confirmation.
1838

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

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

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

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

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

    
1857
Example (and expected output)::
1858

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

    
1880

    
1881
MOVE
1882
^^^^
1883

    
1884
| **move** [-f] [\--ignore-consistency]
1885
| [-n *node*] [\--shutdown-timeout=*N*] [\--submit] [\--print-job-id]
1886
| [\--ignore-ipolicy]
1887
| {*instance*}
1888

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

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

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

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

    
1905
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1906
during this operation are ignored.
1907

    
1908
See **ganeti**\(7) for a description of ``--submit`` and other common
1909
options.
1910

    
1911
Example::
1912

    
1913
    # gnt-instance move -n node3.example.com instance1.example.com
1914

    
1915

    
1916
CHANGE-GROUP
1917
^^^^^^^^^^^^
1918

    
1919
| **change-group** [\--submit] [\--print-job-id]
1920
| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
1921

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

    
1926
If no specific destination groups are specified using ``--to``, all
1927
groups except the one containing the instance are considered.
1928

    
1929
See **ganeti**\(7) for a description of ``--submit`` and other common
1930
options.
1931

    
1932
Example::
1933

    
1934
    # gnt-instance change-group -I hail --to rack2 inst1.example.com
1935

    
1936

    
1937
Tags
1938
~~~~
1939

    
1940
ADD-TAGS
1941
^^^^^^^^
1942

    
1943
**add-tags** [\--from *file*] {*instancename*} {*tag*...}
1944

    
1945
Add tags to the given instance. If any of the tags contains invalid
1946
characters, the entire operation will abort.
1947

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

    
1954
LIST-TAGS
1955
^^^^^^^^^
1956

    
1957
**list-tags** {*instancename*}
1958

    
1959
List the tags of the given instance.
1960

    
1961
REMOVE-TAGS
1962
^^^^^^^^^^^
1963

    
1964
**remove-tags** [\--from *file*] {*instancename*} {*tag*...}
1965

    
1966
Remove tags from the given instance. If any of the tags are not
1967
existing on the node, the entire operation will abort.
1968

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

    
1975
.. vim: set textwidth=72 :
1976
.. Local Variables:
1977
.. mode: rst
1978
.. fill-column: 72
1979
.. End: