Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.rst @ 56956bcb

History | View | Annotate | Download (48.4 kB)

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

    
4
Name
5
----
6

    
7
gnt-instance - Ganeti instance administration
8

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

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

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

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

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

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

    
26
ADD
27
^^^
28

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

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

    
46
The ``disk`` option specifies the parameters for the disks of the
47
instance. The numbering of disks starts at zero, and at least one disk
48
needs to be passed. For each disk, either the size or the adoption
49
source needs to be given, and optionally the access mode (read-only or
50
the default of read-write) can also be specified. The size is
51
interpreted (when no unit is given) in mebibytes. You can also use one
52
of the suffixes *m*, *g* or *t* to specify the exact the units used;
53
these suffixes map to mebibytes, gibibytes and tebibytes.
54

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

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

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

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

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

    
82
If you don't wat the instance to automatically start after
83
creation, this is possible via the ``--no-start`` option. This will
84
leave the instance down until a subsequent **gnt-instance start**
85
command.
86

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

    
92

    
93

    
94
mac
95
    either a value or 'generate' to generate a new unique MAC
96

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

    
102
mode
103
    specifies the connection mode for this nic: routed or bridged.
104

    
105
link
106
    in bridged mode specifies the bridge to attach this NIC to, in
107
    routed mode it's intended to differentiate between different
108
    routing tables/instance groups (but the meaning is dependent on the
109
    network script, see gnt-cluster(8) for more details)
110

    
111

    
112
Of these "mode" and "link" are nic parameters, and inherit their
113
default at cluster level.
114
Alternatively, if no network is desired for the instance, you can
115
prevent the default of one NIC with the ``--no-nics`` option.
116

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

    
125
The ``-B`` option specifies the backend parameters for the
126
instance. If no such parameters are specified, the values are
127
inherited from the cluster. Possible parameters are:
128

    
129

    
130

    
131
memory
132
    the memory size of the instance; as usual, suffixes can be used to
133
    denote the unit, otherwise the value is taken in mebibites
134

    
135
vcpus
136
    the number of VCPUs to assign to the instance (if this value makes
137
    sense for the hypervisor)
138

    
139
auto\_balance
140
    whether the instance is considered in the N+1 cluster checks
141
    (enough redundancy in the cluster to survive a node failure)
142

    
143

    
144
The ``-H`` option specified the hypervisor to use for the instance
145
(must be one of the enabled hypervisors on the cluster) and
146
optionally custom parameters for this instance. If not other
147
options are used (i.e. the invocation is just -H *NAME*) the
148
instance will inherit the cluster options. The defaults below show
149
the cluster defaults at cluster creation time.
150

    
151
The possible hypervisor options are as follows:
152

    
153

    
154

    
155
boot\_order
156
    Valid for the Xen HVM and KVM hypervisors.
157

    
158
    A string value denoting the boot order. This has different meaning
159
    for the Xen HVM hypervisor and for the KVM one.
160

    
161
    For Xen HVM, The boot order is a string of letters listing the boot
162
    devices, with valid device letters being:
163

    
164

    
165

    
166
    a
167
        floppy drive
168

    
169
    c
170
        hard disk
171

    
172
    d
173
        CDROM drive
174

    
175
    n
176
        network boot (PXE)
177

    
178

    
179
    The default is not to set an HVM boot order which is interpreted as
180
    'dc'.
181

    
182
    For KVM the boot order is either "cdrom", "disk" or "network".
183
    Please note that older versions of KVM couldn't netboot from virtio
184
    interfaces. This has been fixed in more recent versions and is
185
    confirmed to work at least with qemu-kvm 0.11.1.
186

    
187
cdrom\_image\_path
188
    Valid for the Xen HVM and KVM hypervisors.
189

    
190
    The path to a CDROM image to attach to the instance.
191

    
192
nic\_type
193
    Valid for the Xen HVM and KVM hypervisors.
194

    
195
    This parameter determines the way the network cards are presented
196
    to the instance. The possible options are:
197

    
198

    
199

    
200
    rtl8139 (default for Xen HVM) (HVM & KVM)
201
    ne2k\_isa (HVM & KVM)
202
    ne2k\_pci (HVM & KVM)
203
    i82551 (KVM)
204
    i82557b (KVM)
205
    i82559er (KVM)
206
    pcnet (KVM)
207
    e1000 (KVM)
208
    paravirtual (default for KVM) (HVM & KVM)
209

    
210

    
211
disk\_type
212
    Valid for the Xen HVM and KVM hypervisors.
213

    
214
    This parameter determines the way the disks are presented to the
215
    instance. The possible options are:
216

    
217

    
218

    
219
    ioemu (default for HVM & KVM) (HVM & KVM)
220
    ide (HVM & KVM)
221
    scsi (KVM)
222
    sd (KVM)
223
    mtd (KVM)
224
    pflash (KVM)
225

    
226

    
227
vnc\_bind\_address
228
    Valid for the Xen HVM and KVM hypervisors.
229

    
230
    Specifies the address that the VNC listener for this instance
231
    should bind to. Valid values are IPv4 addresses. Use the address
232
    0.0.0.0 to bind to all available interfaces (this is the default)
233
    or specify the address of one of the interfaces on the node to
234
    restrict listening to that interface.
235

    
236
vnc\_tls
237
    Valid for the KVM hypervisor.
238

    
239
    A boolean option that controls whether the VNC connection is
240
    secured with TLS.
241

    
242
vnc\_x509\_path
243
    Valid for the KVM hypervisor.
244

    
245
    If ``vnc_tls`` is enabled, this options specifies the path to the
246
    x509 certificate to use.
247

    
248
vnc\_x509\_verify
249
    Valid for the KVM hypervisor.
250

    
251
acpi
252
    Valid for the Xen HVM and KVM hypervisors.
253

    
254
    A boolean option that specifies if the hypervisor should enable
255
    ACPI support for this instance. By default, ACPI is disabled.
256

    
257
pae
258
    Valid for the Xen HVM and KVM hypervisors.
259

    
260
    A boolean option that specifies if the hypervisor should enabled
261
    PAE support for this instance. The default is false, disabling PAE
262
    support.
263

    
264
use\_localtime
265
    Valid for the Xen HVM and KVM hypervisors.
266

    
267
    A boolean option that specifies if the instance should be started
268
    with its clock set to the localtime of the machine (when true) or
269
    to the UTC (When false). The default is false, which is useful for
270
    Linux/Unix machines; for Windows OSes, it is recommended to enable
271
    this parameter.
272

    
273
kernel\_path
274
    Valid for the Xen PVM and KVM hypervisors.
275

    
276
    This option specifies the path (on the node) to the kernel to boot
277
    the instance with. Xen PVM instances always require this, while for
278
    KVM if this option is empty, it will cause the machine to load the
279
    kernel from its disks.
280

    
281
kernel\_args
282
    Valid for the Xen PVM and KVM hypervisors.
283

    
284
    This options specifies extra arguments to the kernel that will be
285
    loaded. device. This is always used for Xen PVM, while for KVM it
286
    is only used if the ``kernel_path`` option is also specified.
287

    
288
    The default setting for this value is simply ``"ro"``, which mounts
289
    the root disk (initially) in read-only one. For example, setting
290
    this to single will cause the instance to start in single-user
291
    mode.
292

    
293
initrd\_path
294
    Valid for the Xen PVM and KVM hypervisors.
295

    
296
    This option specifies the path (on the node) to the initrd to boot
297
    the instance with. Xen PVM instances can use this always, while for
298
    KVM if this option is only used if the ``kernel_path`` option is
299
    also specified. You can pass here either an absolute filename (the
300
    path to the initrd) if you want to use an initrd, or use the format
301
    no\_initrd\_path for no initrd.
302

    
303
root\_path
304
    Valid for the Xen PVM and KVM hypervisors.
305

    
306
    This options specifies the name of the root device. This is always
307
    needed for Xen PVM, while for KVM it is only used if the
308
    ``kernel_path`` option is also specified.
309

    
310
serial\_console
311
    Valid for the KVM hypervisor.
312

    
313
    This boolean option specifies whether to emulate a serial console
314
    for the instance.
315

    
316
disk\_cache
317
    Valid for the KVM hypervisor.
318

    
319
    The disk cache mode. It can be either default to not pass any cache
320
    option to KVM, or one of the KVM cache modes: none (for direct
321
    I/O), writethrough (to use the host cache but report completion to
322
    the guest only when the host has committed the changes to disk) or
323
    writeback (to use the host cache and report completion as soon as
324
    the data is in the host cache). Note that there are special
325
    considerations for the cache mode depending on version of KVM used
326
    and disk type (always raw file under Ganeti), please refer to the
327
    KVM documentation for more details.
328

    
329
security\_model
330
    Valid for the KVM hypervisor.
331

    
332
    The security model for kvm. Currently one of "none", "user" or
333
    "pool". Under "none", the default, nothing is done and instances
334
    are run as the Ganeti daemon user (normally root).
335

    
336
    Under "user" kvm will drop privileges and become the user specified
337
    by the security\_domain parameter.
338

    
339
    Under "pool" a global cluster pool of users will be used, making
340
    sure no two instances share the same user on the same node. (this
341
    mode is not implemented yet)
342

    
343
security\_domain
344
    Valid for the KVM hypervisor.
345

    
346
    Under security model "user" the username to run the instance under.
347
    It must be a valid username existing on the host.
348

    
349
    Cannot be set under security model "none" or "pool".
350

    
351
kvm\_flag
352
    Valid for the KVM hypervisor.
353

    
354
    If "enabled" the -enable-kvm flag is passed to kvm. If "disabled"
355
    -disable-kvm is passed. If unset no flag is passed, and the default
356
    running mode for your kvm binary will be used.
357

    
358
mem\_path
359
    Valid for the KVM hypervisor.
360

    
361
    This option passes the -mem-path argument to kvm with the path (on
362
    the node) to the mount point of the hugetlbfs file system, along
363
    with the -mem-prealloc argument too.
364

    
365
use\_chroot
366
    Valid for the KVM hypervisor.
367

    
368
    This boolean option determines wether to run the KVM instance in a
369
    chroot directory.
370

    
371
    If it is set to ``true``, an empty directory is created before
372
    starting the instance and its path is passed via the -chroot flag
373
    to kvm. The directory is removed when the instance is stopped.
374

    
375
    It is set to ``false`` by default.
376

    
377
migration\_downtime
378
    Valid for the KVM hypervisor.
379

    
380
    The maximum amount of time (in ms) a KVM instance is allowed to be
381
    frozen during a live migration, in order to copy dirty memory
382
    pages. Default value is 30ms, but you may need to increase this
383
    value for busy instances.
384

    
385
    This option is only effective with kvm versions >= 87 and qemu-kvm
386
    versions >= 0.11.0.
387

    
388
cpu\_mask
389
    Valid for the LXC hypervisor.
390

    
391
    The processes belonging to the given instance are only scheduled on
392
    the specified CPUs.
393

    
394
    The parameter format is a comma-separated list of CPU IDs or CPU ID
395
    ranges. The ranges are defined by a lower and higher boundary,
396
    separated by a dash. The boundaries are inclusive.
397

    
398
usb\_mouse
399
    Valid for the KVM hypervisor.
400

    
401
    This option specifies the usb mouse type to be used. It can be
402
    "mouse" or "tablet". When using VNC it's recommended to set it to
403
    "tablet".
404

    
405

    
406
The ``--iallocator`` option specifies the instance allocator plugin
407
to use. If you pass in this option the allocator will select nodes
408
for this instance automatically, so you don't need to pass them
409
with the ``-n`` option. For more information please refer to the
410
instance allocator documentation.
411

    
412
The ``-t`` options specifies the disk layout type for the instance.
413
The available choices are:
414

    
415

    
416

    
417
diskless
418
    This creates an instance with no disks. Its useful for testing only
419
    (or other special cases).
420

    
421
file
422
    Disk devices will be regular files.
423

    
424
plain
425
    Disk devices will be logical volumes.
426

    
427
drbd
428
    Disk devices will be drbd (version 8.x) on top of lvm volumes.
429

    
430

    
431
The optional second value of the ``--node`` is used for the drbd
432
template type and specifies the remote node.
433

    
434
If you do not want gnt-instance to wait for the disk mirror to be
435
synced, use the ``--no-wait-for-sync`` option.
436

    
437
The ``--file-storage-dir`` specifies the relative path under the
438
cluster-wide file storage directory to store file-based disks. It is
439
useful for having different subdirectories for different
440
instances. The full path of the directory where the disk files are
441
stored will consist of cluster-wide file storage directory + optional
442
subdirectory + instance name. Example:
443
``@RPL_FILE_STORAGE_DIR@``*/mysubdir/instance1.example.com*. This
444
option is only relevant for instances using the file storage backend.
445

    
446
The ``--file-driver`` specifies the driver to use for file-based
447
disks. Note that currently these drivers work with the xen
448
hypervisor only. This option is only relevant for instances using
449
the file storage backend. The available choices are:
450

    
451

    
452

    
453
loop
454
    Kernel loopback driver. This driver uses loopback devices to access
455
    the filesystem within the file. However, running I/O intensive
456
    applications in your instance using the loop driver might result in
457
    slowdowns. Furthermore, if you use the loopback driver consider
458
    increasing the maximum amount of loopback devices (on most systems
459
    it's 8) using the max\_loop param.
460

    
461
blktap
462
    The blktap driver (for Xen hypervisors). In order to be able to use
463
    the blktap driver you should check if the 'blktapctrl' user space
464
    disk agent is running (usually automatically started via xend).
465
    This user-level disk I/O interface has the advantage of better
466
    performance. Especially if you use a network file system (e.g. NFS)
467
    to store your instances this is the recommended choice.
468

    
469

    
470
The ``--submit`` option is used to send the job to the master
471
daemon but not wait for its completion. The job ID will be shown so
472
that it can be examined via **gnt-job info**.
473

    
474
Example::
475

    
476
    # gnt-instance add -t file --disk 0:size=30g -B memory=512 -o debian-etch \
477
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
478
    # gnt-instance add -t plain --disk 0:size=30g -B memory=512 -o debian-etch \
479
      -n node1.example.com instance1.example.com
480
    # gnt-instance add -t drbd --disk 0:size=30g -B memory=512 -o debian-etch \
481
      -n node1.example.com:node2.example.com instance2.example.com
482

    
483

    
484
BATCH-CREATE
485
^^^^^^^^^^^^
486

    
487
**batch-create** {instances\_file.json}
488

    
489
This command (similar to the Ganeti 1.2 **batcher** tool) submits
490
multiple instance creation jobs based on a definition file. The
491
instance configurations do not encompass all the possible options
492
for the **add** command, but only a subset.
493

    
494
The instance file should be a valid-formed JSON file, containing a
495
dictionary with instance name and instance parameters. The accepted
496
parameters are:
497

    
498

    
499

    
500
disk\_size
501
    The size of the disks of the instance.
502

    
503
disk\_template
504
    The disk template to use for the instance, the same as in the
505
    **add** command.
506

    
507
backend
508
    A dictionary of backend parameters.
509

    
510
hypervisor
511
    A dictionary with a single key (the hypervisor name), and as value
512
    the hypervisor options. If not passed, the default hypervisor and
513
    hypervisor options will be inherited.
514

    
515
mac, ip, mode, link
516
    Specifications for the one NIC that will be created for the
517
    instance. 'bridge' is also accepted as a backwards compatibile
518
    key.
519

    
520
nics
521
    List of nics that will be created for the instance. Each entry
522
    should be a dict, with mac, ip, mode and link as possible keys.
523
    Please don't provide the "mac, ip, mode, link" parent keys if you
524
    use this method for specifying nics.
525

    
526
primary\_node, secondary\_node
527
    The primary and optionally the secondary node to use for the
528
    instance (in case an iallocator script is not used).
529

    
530
iallocator
531
    Instead of specifying the nodes, an iallocator script can be used
532
    to automatically compute them.
533

    
534
start
535
    whether to start the instance
536

    
537
ip\_check
538
    Skip the check for already-in-use instance; see the description in
539
    the **add** command for details.
540

    
541
name\_check
542
    Skip the name check for instances; see the description in the
543
    **add** command for details.
544

    
545
file\_storage\_dir, file\_driver
546
    Configuration for the file disk type, see the **add** command for
547
    details.
548

    
549

    
550
A simple definition for one instance can be (with most of the
551
parameters taken from the cluster defaults)::
552

    
553
    {
554
      "instance3": {
555
        "template": "drbd",
556
        "os": "debootstrap",
557
        "disk_size": ["25G"],
558
        "iallocator": "dumb"
559
      },
560
      "instance5": {
561
        "template": "drbd",
562
        "os": "debootstrap",
563
        "disk_size": ["25G"],
564
        "iallocator": "dumb",
565
        "hypervisor": "xen-hvm",
566
        "hvparams": {"acpi": true},
567
        "backend": {"memory": 512}
568
      }
569
    }
570

    
571
The command will display the job id for each submitted instance, as
572
follows::
573

    
574
    # gnt-instance batch-create instances.json
575
    instance3: 11224
576
    instance5: 11225
577

    
578
REMOVE
579
^^^^^^
580

    
581
**remove** [--ignore-failures] [--shutdown-timeout=*N*] [--submit]
582
{*instance*}
583

    
584
Remove an instance. This will remove all data from the instance and
585
there is *no way back*. If you are not sure if you use an instance
586
again, use **shutdown** first and leave it in the shutdown state
587
for a while.
588

    
589
The ``--ignore-failures`` option will cause the removal to proceed
590
even in the presence of errors during the removal of the instance
591
(e.g. during the shutdown or the disk removal). If this option is
592
not given, the command will stop at the first error.
593

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

    
599
The ``--submit`` option is used to send the job to the master
600
daemon but not wait for its completion. The job ID will be shown so
601
that it can be examined via **gnt-job info**.
602

    
603
Example::
604

    
605
    # gnt-instance remove instance1.example.com
606

    
607

    
608
LIST
609
^^^^
610

    
611
| **list**
612
| [--no-headers] [--separator=*SEPARATOR*] [--units=*UNITS*]
613
| [-o *[+]FIELD,...*] [--roman] [instance...]
614

    
615
Shows the currently configured instances with memory usage, disk
616
usage, the node they are running on, and their run status.
617

    
618
The ``--no-headers`` option will skip the initial header line. The
619
``--separator`` option takes an argument which denotes what will be
620
used between the output fields. Both these options are to help
621
scripting.
622

    
623
The units used to display the numeric values in the output varies,
624
depending on the options given. By default, the values will be
625
formatted in the most appropriate unit. If the ``--separator``
626
option is given, then the values are shown in mebibytes to allow
627
parsing by scripts. In both cases, the ``--units`` option can be
628
used to enforce a given output unit.
629

    
630
The ``--roman`` option allows latin people to better understand the
631
cluster instances' status.
632

    
633
The ``-o`` option takes a comma-separated list of output fields.
634
The available fields and their meaning are:
635

    
636

    
637

    
638
name
639
    the instance name
640

    
641
os
642
    the OS of the instance
643

    
644
pnode
645
    the primary node of the instance
646

    
647
snodes
648
    comma-separated list of secondary nodes for the instance; usually
649
    this will be just one node
650

    
651
admin\_state
652
    the desired state of the instance (either "yes" or "no" denoting
653
    the instance should run or not)
654

    
655
disk\_template
656
    the disk template of the instance
657

    
658
oper\_state
659
    the actual state of the instance; can be one of the values
660
    "running", "stopped", "(node down)"
661

    
662
status
663
    combined form of admin\_state and oper\_stat; this can be one of:
664
    ERROR\_nodedown if the node of the instance is down, ERROR\_down if
665
    the instance should run but is down, ERROR\_up if the instance
666
    should be stopped but is actually running, ADMIN\_down if the
667
    instance has been stopped (and is stopped) and running if the
668
    instance is set to be running (and is running)
669

    
670
oper\_ram
671
    the actual memory usage of the instance as seen by the hypervisor
672

    
673
oper\_vcpus
674
    the actual number of VCPUs the instance is using as seen by the
675
    hypervisor
676

    
677
ip
678
    the ip address Ganeti recognizes as associated with the first
679
    instance interface
680

    
681
mac
682
    the first instance interface MAC address
683

    
684
nic\_mode
685
    the mode of the first instance NIC (routed or bridged)
686

    
687
nic\_link
688
    the link of the first instance NIC
689

    
690
sda\_size
691
    the size of the instance's first disk
692

    
693
sdb\_size
694
    the size of the instance's second disk, if any
695

    
696
vcpus
697
    the number of VCPUs allocated to the instance
698

    
699
tags
700
    comma-separated list of the instances's tags
701

    
702
serial\_no
703
    the so called 'serial number' of the instance; this is a numeric
704
    field that is incremented each time the instance is modified, and
705
    it can be used to track modifications
706

    
707
ctime
708
    the creation time of the instance; note that this field contains
709
    spaces and as such it's harder to parse
710

    
711
    if this attribute is not present (e.g. when upgrading from older
712
    versions), then "N/A" will be shown instead
713

    
714
mtime
715
    the last modification time of the instance; note that this field
716
    contains spaces and as such it's harder to parse
717

    
718
    if this attribute is not present (e.g. when upgrading from older
719
    versions), then "N/A" will be shown instead
720

    
721
uuid
722
    Show the UUID of the instance (generated automatically by Ganeti)
723

    
724
network\_port
725
    If the instance has a network port assigned to it (e.g. for VNC
726
    connections), this will be shown, otherwise - will be displayed.
727

    
728
beparams
729
    A text format of the entire beparams for the instance. It's more
730
    useful to select individual fields from this dictionary, see
731
    below.
732

    
733
disk.count
734
    The number of instance disks.
735

    
736
disk.size/N
737
    The size of the instance's Nth disk. This is a more generic form of
738
    the sda\_size and sdb\_size fields.
739

    
740
disk.sizes
741
    A comma-separated list of the disk sizes for this instance.
742

    
743
disk\_usage
744
    The total disk space used by this instance on each of its nodes.
745
    This is not the instance-visible disk size, but the actual disk
746
    "cost" of the instance.
747

    
748
nic.mac/N
749
    The MAC of the Nth instance NIC.
750

    
751
nic.ip/N
752
    The IP address of the Nth instance NIC.
753

    
754
nic.mode/N
755
    The mode of the Nth instance NIC
756

    
757
nic.link/N
758
    The link of the Nth instance NIC
759

    
760
nic.macs
761
    A comma-separated list of all the MACs of the instance's NICs.
762

    
763
nic.ips
764
    A comma-separated list of all the IP addresses of the instance's
765
    NICs.
766

    
767
nic.modes
768
    A comma-separated list of all the modes of the instance's NICs.
769

    
770
nic.links
771
    A comma-separated list of all the link parameters of the instance's
772
    NICs.
773

    
774
nic.count
775
    The number of instance nics.
776

    
777
hv/*NAME*
778
    The value of the hypervisor parameter called *NAME*. For details of
779
    what hypervisor parameters exist and their meaning, see the **add**
780
    command.
781

    
782
be/memory
783
    The configured memory for the instance.
784

    
785
be/vcpus
786
    The configured number of VCPUs for the instance.
787

    
788
be/auto\_balance
789
    Whether the instance is considered in N+1 checks.
790

    
791

    
792
If the value of the option starts with the character ``+``, the new
793
field(s) will be added to the default list. This allows to quickly
794
see the default list plus a few other fields, instead of retyping
795
the entire list of fields.
796

    
797
There is a subtle grouping about the available output fields: all
798
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
799
``status`` are configuration value and not run-time values. So if
800
you don't select any of the these fields, the query will be
801
satisfied instantly from the cluster configuration, without having
802
to ask the remote nodes for the data. This can be helpful for big
803
clusters when you only want some data and it makes sense to specify
804
a reduced set of output fields.
805

    
806
The default output field list is: name, os, pnode, admin\_state,
807
oper\_state, oper\_ram.
808

    
809
INFO
810
^^^^
811

    
812
**info** [-s \| --static] [--roman] {--all \| *instance*}
813

    
814
Show detailed information about the given instance(s). This is
815
different from **list** as it shows detailed data about the
816
instance's disks (especially useful for the drbd disk template).
817

    
818
If the option ``-s`` is used, only information available in the
819
configuration file is returned, without querying nodes, making the
820
operation faster.
821

    
822
Use the ``--all`` to get info about all instances, rather than
823
explicitly passing the ones you're interested in.
824

    
825
The ``--roman`` option can be used to cause envy among people who
826
like ancient cultures, but are stuck with non-latin-friendly
827
cluster virtualization technologies.
828

    
829
MODIFY
830
^^^^^^
831

    
832
| **modify**
833
| [-H *HYPERVISOR\_PARAMETERS*]
834
| [-B *BACKEND\_PARAMETERS*]
835
| [--net add*[:options]* \| --net remove \| --net *N:options*]
836
| [--disk add:size=*SIZE* \| --disk remove \| --disk *N*:mode=*MODE*]
837
| [-t {plain \| drbd}]
838
| [--os-name=*OS* [--force-variant]]
839
| [--submit]
840
| {*instance*}
841

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

    
847
The ``-H`` option specifies hypervisor options in the form of
848
name=value[,...]. For details which options can be specified, see
849
the **add** command.
850

    
851
The ``-t`` option will change the disk template of the instance.
852
Currently only conversions between the plain and drbd disk
853
templates are supported, and the instance must be stopped before
854
attempting the conversion.
855

    
856
The ``--disk add:size=``*SIZE* option adds a disk to the instance. The
857
``--disk remove`` option will remove the last disk of the
858
instance. The ``--disk`` *N*``:mode=``*MODE* option will change the
859
mode of the Nth disk of the instance between read-only (``ro``) and
860
read-write (``rw``).
861

    
862
The ``--net add:``*options* option will add a new NIC to the
863
instance. The available options are the same as in the **add** command
864
(mac, ip, link, mode). The ``--net remove`` will remove the last NIC
865
of the instance, while the ``--net`` *N*:*options* option will
866
change the parameters of the Nth instance NIC.
867

    
868
The option ``--os-name`` will change the OS name for the instance
869
(without reinstallation). In case an OS variant is specified that
870
is not found, then by default the modification is refused, unless
871
``--force-variant`` is passed. An invalid OS will also be refused,
872
unless the ``--force`` option is given.
873

    
874
The ``--submit`` option is used to send the job to the master
875
daemon but not wait for its completion. The job ID will be shown so
876
that it can be examined via **gnt-job info**.
877

    
878
All the changes take effect at the next restart. If the instance is
879
running, there is no effect on the instance.
880

    
881
REINSTALL
882
^^^^^^^^^
883

    
884
| **reinstall** [-o *os-type*] [--select-os] [-f *force*]
885
| [--force-multiple]
886
| [--instance \| --node \| --primary \| --secondary \| --all]
887
| [-O *OS\_PARAMETERS*] [--submit] {*instance*...}
888

    
889
Reinstalls the operating system on the given instance(s). The
890
instance(s) must be stopped when running this command. If the
891
``--os-type`` is specified, the operating system is changed.
892

    
893
The ``--select-os`` option switches to an interactive OS reinstall.
894
The user is prompted to select the OS template from the list of
895
available OS templates. OS parameters can be overridden using
896
``-O``.
897

    
898
Since this is a potentially dangerous command, the user will be
899
required to confirm this action, unless the ``-f`` flag is passed.
900
When multiple instances are selected (either by passing multiple
901
arguments or by using the ``--node``, ``--primary``,
902
``--secondary`` or ``--all`` options), the user must pass the
903
``--force-multiple`` options to skip the interactive confirmation.
904

    
905
The ``--submit`` option is used to send the job to the master
906
daemon but not wait for its completion. The job ID will be shown so
907
that it can be examined via **gnt-job info**.
908

    
909
RENAME
910
^^^^^^
911

    
912
| **rename** [--no-ip-check] [--no-name-check] [--submit]
913
| {*instance*} {*new\_name*}
914

    
915
Renames the given instance. The instance must be stopped when
916
running this command. The requirements for the new name are the
917
same as for adding an instance: the new name must be resolvable and
918
the IP it resolves to must not be reachable (in order to prevent
919
duplicate IPs the next time the instance is started). The IP test
920
can be skipped if the ``--no-ip-check`` option is passed.
921

    
922
The ``--no-name-check`` skips the check for the new instance name
923
via the resolver (e.g. in DNS or /etc/hosts, depending on your
924
setup). Since the name check is used to compute the IP address, if
925
you pass this option you must also pass the ``--no-ip-check``
926
option.
927

    
928
The ``--submit`` option is used to send the job to the master
929
daemon but not wait for its completion. The job ID will be shown so
930
that it can be examined via **gnt-job info**.
931

    
932
Starting/stopping/connecting to console
933
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
934

    
935
STARTUP
936
^^^^^^^
937

    
938
| **startup**
939
| [--force] [--ignore-offline]
940
| [--force-multiple]
941
| [--instance \| --node \| --primary \| --secondary \| --all \|
942
| --tags \| --node-tags \| --pri-node-tags \| --sec-node-tags]
943
| [-H ``key=value...``] [-B ``key=value...``]
944
| [--submit]
945
| {*name*...}
946

    
947
Starts one or more instances, depending on the following options.
948
The four available modes are:
949

    
950

    
951
--instance
952
    will start the instances given as arguments (at least one argument
953
    required); this is the default selection
954

    
955
--node
956
    will start the instances who have the given node as either primary
957
    or secondary
958

    
959
--primary
960
    will start all instances whose primary node is in the list of nodes
961
    passed as arguments (at least one node required)
962

    
963
--secondary
964
    will start all instances whose secondary node is in the list of
965
    nodes passed as arguments (at least one node required)
966

    
967
--all
968
    will start all instances in the cluster (no arguments accepted)
969

    
970
--tags
971
    will start all instances in the cluster with the tags given as
972
    arguments
973

    
974
--node-tags
975
    will start all instances in the cluster on nodes with the tags
976
    given as arguments
977

    
978
--pri-node-tags
979
    will start all instances in the cluster on primary nodes with the
980
    tags given as arguments
981

    
982
--sec-node-tags
983
    will start all instances in the cluster on secondary nodes with the
984
    tags given as arguments
985

    
986

    
987
Note that although you can pass more than one selection option, the
988
last one wins, so in order to guarantee the desired result, don't
989
pass more than one such option.
990

    
991
Use ``--force`` to start even if secondary disks are failing.
992
``--ignore-offline`` can be used to ignore offline primary nodes
993
and mark the instance as started even if the primary is not
994
available.
995

    
996
The ``--force-multiple`` will skip the interactive confirmation in
997
the case the more than one instance will be affected.
998

    
999
The ``-H`` and ``-B`` options specify temporary hypervisor and
1000
backend parameters that can be used to start an instance with
1001
modified parameters. They can be useful for quick testing without
1002
having to modify an instance back and forth, e.g.::
1003

    
1004
    # gnt-instance start -H root_args="single" instance1
1005
    # gnt-instance start -B memory=2048 instance2
1006

    
1007

    
1008
The first form will start the instance instance1 in single-user
1009
mode, and the instance instance2 with 2GB of RAM (this time only,
1010
unless that is the actual instance memory size already). Note that
1011
the values override the instance parameters (and not extend them):
1012
an instance with "root\_args=ro" when started with -H
1013
root\_args=single will result in "single", not "ro single".
1014
The ``--submit`` option is used to send the job to the master
1015
daemon but not wait for its completion. The job ID will be shown so
1016
that it can be examined via **gnt-job info**.
1017

    
1018
Example::
1019

    
1020
    # gnt-instance start instance1.example.com
1021
    # gnt-instance start --node node1.example.com node2.example.com
1022
    # gnt-instance start --all
1023

    
1024

    
1025
SHUTDOWN
1026
^^^^^^^^
1027

    
1028
| **shutdown**
1029
| [--timeout=*N*]
1030
| [--force-multiple] [--ignore-offline]
1031
| [--instance \| --node \| --primary \| --secondary \| --all \|
1032
| --tags \| --node-tags \| --pri-node-tags \| --sec-node-tags]
1033
| [--submit]
1034
| {*name*...}
1035

    
1036
Stops one or more instances. If the instance cannot be cleanly
1037
stopped during a hardcoded interval (currently 2 minutes), it will
1038
forcibly stop the instance (equivalent to switching off the power
1039
on a physical machine).
1040

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

    
1046
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1047
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1048
``--sec-node-tags`` options are similar as for the **startup**
1049
command and they influence the actual instances being shutdown.
1050

    
1051
The ``--submit`` option is used to send the job to the master
1052
daemon but not wait for its completion. The job ID will be shown so
1053
that it can be examined via **gnt-job info**.
1054

    
1055
``--ignore-offline`` can be used to ignore offline primary nodes
1056
and force the instance to be marked as stopped. This option should
1057
be used with care as it can lead to an inconsistent cluster state.
1058

    
1059
Example::
1060

    
1061
    # gnt-instance shutdown instance1.example.com
1062
    # gnt-instance shutdown --all
1063

    
1064

    
1065
REBOOT
1066
^^^^^^
1067

    
1068
| **reboot**
1069
| [--type=*REBOOT-TYPE*]
1070
| [--ignore-secondaries]
1071
| [--shutdown-timeout=*N*]
1072
| [--force-multiple]
1073
| [--instance \| --node \| --primary \| --secondary \| --all \|
1074
| --tags \| --node-tags \| --pri-node-tags \| --sec-node-tags]
1075
| [--submit]
1076
| [*name*...]
1077

    
1078
Reboots one or more instances. The type of reboot depends on the
1079
value of ``--type``. A soft reboot does a hypervisor reboot, a hard
1080
reboot does a instance stop, recreates the hypervisor config for
1081
the instance and starts the instance. A full reboot does the
1082
equivalent of **gnt-instance shutdown && gnt-instance startup**.
1083
The default is hard reboot.
1084

    
1085
For the hard reboot the option ``--ignore-secondaries`` ignores
1086
errors for the secondary node while re-assembling the instance
1087
disks.
1088

    
1089
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1090
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1091
``--sec-node-tags`` options are similar as for the **startup**
1092
command and they influence the actual instances being rebooted.
1093

    
1094
The ``--shutdown-timeout`` is used to specify how much time to wait
1095
before forcing the shutdown (xm destroy in xen, killing the kvm
1096
process, for kvm). By default two minutes are given to each
1097
instance to stop.
1098

    
1099
The ``--force-multiple`` will skip the interactive confirmation in
1100
the case the more than one instance will be affected.
1101

    
1102
Example::
1103

    
1104
    # gnt-instance reboot instance1.example.com
1105
    # gnt-instance reboot --type=full instance1.example.com
1106

    
1107

    
1108
CONSOLE
1109
^^^^^^^
1110

    
1111
**console** [--show-cmd] {*instance*}
1112

    
1113
Connects to the console of the given instance. If the instance is
1114
not up, an error is returned. Use the ``--show-cmd`` option to
1115
display the command instead of executing it.
1116

    
1117
For HVM instances, this will attempt to connect to the serial
1118
console of the instance. To connect to the virtualized "physical"
1119
console of a HVM instance, use a VNC client with the connection
1120
info from the **info** command.
1121

    
1122
Example::
1123

    
1124
    # gnt-instance console instance1.example.com
1125

    
1126

    
1127
Disk management
1128
~~~~~~~~~~~~~~~
1129

    
1130
REPLACE-DISKS
1131
^^^^^^^^^^^^^
1132

    
1133
**replace-disks** [--submit] [--early-release] {-p} [--disks *idx*]
1134
{*instance*}
1135

    
1136
**replace-disks** [--submit] [--early-release] {-s} [--disks *idx*]
1137
{*instance*}
1138

    
1139
**replace-disks** [--submit] [--early-release] {--iallocator *name*
1140
\| --new-secondary *NODE*} {*instance*}
1141

    
1142
**replace-disks** [--submit] [--early-release] {--auto}
1143
{*instance*}
1144

    
1145
This command is a generalized form for replacing disks. It is
1146
currently only valid for the mirrored (DRBD) disk template.
1147

    
1148
The first form (when passing the ``-p`` option) will replace the
1149
disks on the primary, while the second form (when passing the
1150
``-s`` option will replace the disks on the secondary node. For
1151
these two cases (as the node doesn't change), it is possible to
1152
only run the replace for a subset of the disks, using the option
1153
``--disks`` which takes a list of comma-delimited disk indices
1154
(zero-based), e.g. 0,2 to replace only the first and third disks.
1155

    
1156
The third form (when passing either the ``--iallocator`` or the
1157
``--new-secondary`` option) is designed to change secondary node of
1158
the instance. Specifying ``--iallocator`` makes the new secondary
1159
be selected automatically by the specified allocator plugin,
1160
otherwise the new secondary node will be the one chosen manually
1161
via the ``--new-secondary`` option.
1162

    
1163
The fourth form (when using ``--auto``) will automatically
1164
determine which disks of an instance are faulty and replace them
1165
within the same node. The ``--auto`` option works only when an
1166
instance has only faulty disks on either the primary or secondary
1167
node; it doesn't work when both sides have faulty disks.
1168

    
1169
The ``--submit`` option is used to send the job to the master
1170
daemon but not wait for its completion. The job ID will be shown so
1171
that it can be examined via **gnt-job info**.
1172

    
1173
The ``--early-release`` changes the code so that the old storage on
1174
secondary node(s) is removed early (before the resync is completed)
1175
and the internal Ganeti locks for the current (and new, if any)
1176
secondary node are also released, thus allowing more parallelism in
1177
the cluster operation. This should be used only when recovering
1178
from a disk failure on the current secondary (thus the old storage
1179
is already broken) or when the storage on the primary node is known
1180
to be fine (thus we won't need the old storage for potential
1181
recovery).
1182

    
1183
Note that it is not possible to select an offline or drained node
1184
as a new secondary.
1185

    
1186
ACTIVATE-DISKS
1187
^^^^^^^^^^^^^^
1188

    
1189
**activate-disks** [--submit] [--ignore-size] {*instance*}
1190

    
1191
Activates the block devices of the given instance. If successful,
1192
the command will show the location and name of the block devices::
1193

    
1194
    node1.example.com:disk/0:/dev/drbd0
1195
    node1.example.com:disk/1:/dev/drbd1
1196

    
1197

    
1198
In this example, *node1.example.com* is the name of the node on
1199
which the devices have been activated. The *disk/0* and *disk/1*
1200
are the Ganeti-names of the instance disks; how they are visible
1201
inside the instance is hypervisor-specific. */dev/drbd0* and
1202
*/dev/drbd1* are the actual block devices as visible on the node.
1203
The ``--submit`` option is used to send the job to the master
1204
daemon but not wait for its completion. The job ID will be shown so
1205
that it can be examined via **gnt-job info**.
1206

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

    
1214
Note that it is safe to run this command while the instance is
1215
already running.
1216

    
1217
DEACTIVATE-DISKS
1218
^^^^^^^^^^^^^^^^
1219

    
1220
**deactivate-disks** [--submit] {*instance*}
1221

    
1222
De-activates the block devices of the given instance. Note that if
1223
you run this command for an instance with a drbd disk template,
1224
while it is running, it will not be able to shutdown the block
1225
devices on the primary node, but it will shutdown the block devices
1226
on the secondary nodes, thus breaking the replication.
1227

    
1228
The ``--submit`` option is used to send the job to the master
1229
daemon but not wait for its completion. The job ID will be shown so
1230
that it can be examined via **gnt-job info**.
1231

    
1232
GROW-DISK
1233
^^^^^^^^^
1234

    
1235
**grow-disk** [--no-wait-for-sync] [--submit] {*instance*} {*disk*}
1236
{*amount*}
1237

    
1238
Grows an instance's disk. This is only possible for instances
1239
having a plain or drbd disk template.
1240

    
1241
Note that this command only change the block device size; it will
1242
not grow the actual filesystems, partitions, etc. that live on that
1243
disk. Usually, you will need to:
1244

    
1245

    
1246

    
1247

    
1248
#. use **gnt-instance grow-disk**
1249

    
1250
#. reboot the instance (later, at a convenient time)
1251

    
1252
#. use a filesystem resizer, such as ext2online(8) or
1253
   xfs\_growfs(8) to resize the filesystem, or use fdisk(8) to change
1254
   the partition table on the disk
1255

    
1256

    
1257
The *disk* argument is the index of the instance disk to grow. The
1258
*amount* argument is given either as a number (and it represents
1259
the amount to increase the disk with in mebibytes) or can be given
1260
similar to the arguments in the create instance operation, with a
1261
suffix denoting the unit.
1262

    
1263
Note that the disk grow operation might complete on one node but
1264
fail on the other; this will leave the instance with
1265
different-sized LVs on the two nodes, but this will not create
1266
problems (except for unused space).
1267

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

    
1271
The ``--submit`` option is used to send the job to the master
1272
daemon but not wait for its completion. The job ID will be shown so
1273
that it can be examined via **gnt-job info**.
1274

    
1275
Example (increase the first disk for instance1 by 16GiB)::
1276

    
1277
    # gnt-instance grow-disk instance1.example.com 0 16g
1278

    
1279

    
1280
Also note that disk shrinking is not supported; use
1281
**gnt-backup export** and then **gnt-backup import** to reduce the
1282
disk size of an instance.
1283

    
1284
RECREATE-DISKS
1285
^^^^^^^^^^^^^^
1286

    
1287
**recreate-disks** [--submit] [--disks=``indices``] {*instance*}
1288

    
1289
Recreates the disks of the given instance, or only a subset of the
1290
disks (if the option ``disks`` is passed, which must be a
1291
comma-separated list of disk indices, starting from zero).
1292

    
1293
Note that this functionality should only be used for missing disks;
1294
if any of the given disks already exists, the operation will fail.
1295
While this is suboptimal, recreate-disks should hopefully not be
1296
needed in normal operation and as such the impact of this is low.
1297

    
1298
The ``--submit`` option is used to send the job to the master
1299
daemon but not wait for its completion. The job ID will be shown so
1300
that it can be examined via **gnt-job info**.
1301

    
1302
Recovery
1303
~~~~~~~~
1304

    
1305
FAILOVER
1306
^^^^^^^^
1307

    
1308
**failover** [-f] [--ignore-consistency] [--shutdown-timeout=*N*]
1309
[--submit] {*instance*}
1310

    
1311
Failover will fail the instance over its secondary node. This works
1312
only for instances having a drbd disk template.
1313

    
1314
Normally the failover will check the consistency of the disks
1315
before failing over the instance. If you are trying to migrate
1316
instances off a dead node, this will fail. Use the
1317
``--ignore-consistency`` option for this purpose. Note that this
1318
option can be dangerous as errors in shutting down the instance
1319
will be ignored, resulting in possibly having the instance running
1320
on two machines in parallel (on disconnected DRBD drives).
1321

    
1322
The ``--shutdown-timeout`` is used to specify how much time to wait
1323
before forcing the shutdown (xm destroy in xen, killing the kvm
1324
process, for kvm). By default two minutes are given to each
1325
instance to stop.
1326

    
1327
The ``--submit`` option is used to send the job to the master
1328
daemon but not wait for its completion. The job ID will be shown so
1329
that it can be examined via **gnt-job info**.
1330

    
1331
Example::
1332

    
1333
    # gnt-instance failover instance1.example.com
1334

    
1335

    
1336
MIGRATE
1337
^^^^^^^
1338

    
1339
**migrate** [-f] {--cleanup} {*instance*}
1340

    
1341
**migrate** [-f] [--non-live] [--migration-mode=live\|non-live]
1342
{*instance*}
1343

    
1344
Migrate will move the instance to its secondary node without
1345
shutdown. It only works for instances having the drbd8 disk
1346
template type.
1347

    
1348
The migration command needs a perfectly healthy instance, as we
1349
rely on the dual-master capability of drbd8 and the disks of the
1350
instance are not allowed to be degraded.
1351

    
1352
The ``--non-live`` and ``--migration-mode=non-live`` options will
1353
switch (for the hypervisors that support it) between a "fully live"
1354
(i.e. the interruption is as minimal as possible) migration and one
1355
in which the instance is frozen, its state saved and transported to
1356
the remote node, and then resumed there. This all depends on the
1357
hypervisor support for two different methods. In any case, it is
1358
not an error to pass this parameter (it will just be ignored if the
1359
hypervisor doesn't support it). The option
1360
``--migration-mode=live`` option will request a fully-live
1361
migration. The default, when neither option is passed, depends on
1362
the hypervisor parameters (and can be viewed with the
1363
**gnt-cluster info** command).
1364

    
1365
If the ``--cleanup`` option is passed, the operation changes from
1366
migration to attempting recovery from a failed previous migration.
1367
In this mode, Ganeti checks if the instance runs on the correct
1368
node (and updates its configuration if not) and ensures the
1369
instances's disks are configured correctly. In this mode, the
1370
``--non-live`` option is ignored.
1371

    
1372
The option ``-f`` will skip the prompting for confirmation.
1373

    
1374
Example (and expected output)::
1375

    
1376
    # gnt-instance migrate instance1
1377
    Migrate will happen to the instance instance1. Note that migration is
1378
    **experimental** in this version. This might impact the instance if
1379
    anything goes wrong. Continue?
1380
    y/[n]/?: y
1381
    * checking disk consistency between source and target
1382
    * ensuring the target is in secondary mode
1383
    * changing disks into dual-master mode
1384
     - INFO: Waiting for instance instance1 to sync disks.
1385
     - INFO: Instance instance1's disks are in sync.
1386
    * migrating instance to node2.example.com
1387
    * changing the instance's disks on source node to secondary
1388
     - INFO: Waiting for instance instance1 to sync disks.
1389
     - INFO: Instance instance1's disks are in sync.
1390
    * changing the instance's disks to single-master
1391
    #
1392

    
1393

    
1394
MOVE
1395
^^^^
1396

    
1397
**move** [-f] [-n *node*] [--shutdown-timeout=*N*] [--submit]
1398
{*instance*}
1399

    
1400
Move will move the instance to an arbitrary node in the cluster.
1401
This works only for instances having a plain or file disk
1402
template.
1403

    
1404
Note that since this operation is done via data copy, it will take
1405
a long time for big disks (similar to replace-disks for a drbd
1406
instance).
1407

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

    
1413
The ``--submit`` option is used to send the job to the master
1414
daemon but not wait for its completion. The job ID will be shown so
1415
that it can be examined via **gnt-job info**.
1416

    
1417
Example::
1418

    
1419
    # gnt-instance move -n node3.example.com instance1.example.com
1420

    
1421

    
1422
TAGS
1423
~~~~
1424

    
1425
ADD-TAGS
1426
^^^^^^^^
1427

    
1428
**add-tags** [--from *file*] {*instancename*} {*tag*...}
1429

    
1430
Add tags to the given instance. If any of the tags contains invalid
1431
characters, the entire operation will abort.
1432

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

    
1439
LIST-TAGS
1440
^^^^^^^^^
1441

    
1442
**list-tags** {*instancename*}
1443

    
1444
List the tags of the given instance.
1445

    
1446
REMOVE-TAGS
1447
^^^^^^^^^^^
1448

    
1449
**remove-tags** [--from *file*] {*instancename*} {*tag*...}
1450

    
1451
Remove tags from the given instance. If any of the tags are not
1452
existing on the node, the entire operation will abort.
1453

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