Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.rst @ 50c1e351

History | View | Annotate | Download (59.8 kB)

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

    
4
Name
5
----
6

    
7
gnt-instance - Ganeti instance administration
8

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

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

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

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

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

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

    
26
ADD
27
^^^
28

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
114

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

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

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

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

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

    
140
vcpus
141
    the number of VCPUs to assign to the instance (if this value makes
142
    sense for the hypervisor)
143

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

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

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

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

    
166
The possible hypervisor options are as follows:
167

    
168
boot\_order
169
    Valid for the Xen HVM and KVM hypervisors.
170

    
171
    A string value denoting the boot order. This has different meaning
172
    for the Xen HVM hypervisor and for the KVM one.
173

    
174
    For Xen HVM, The boot order is a string of letters listing the boot
175
    devices, with valid device letters being:
176

    
177
    a
178
        floppy drive
179

    
180
    c
181
        hard disk
182

    
183
    d
184
        CDROM drive
185

    
186
    n
187
        network boot (PXE)
188

    
189
    The default is not to set an HVM boot order, which is interpreted
190
    as 'dc'.
191

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

    
199
blockdev\_prefix
200
    Valid for the Xen HVM and PVM hypervisors.
201

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

    
206
floppy\_image\_path
207
    Valid for the KVM hypervisor.
208

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

    
214
cdrom\_image\_path
215
    Valid for the Xen HVM and KVM hypervisors.
216

    
217
    The path to a CDROM image to attach to the instance.
218

    
219
cdrom2\_image\_path
220
    Valid for the KVM hypervisor.
221

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

    
226
nic\_type
227
    Valid for the Xen HVM and KVM hypervisors.
228

    
229
    This parameter determines the way the network cards are presented
230
    to the instance. The possible options are:
231

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

    
242
disk\_type
243
    Valid for the Xen HVM and KVM hypervisors.
244

    
245
    This parameter determines the way the disks are presented to the
246
    instance. The possible options are:
247

    
248
    - ioemu [default] (HVM & KVM)
249
    - ide (HVM & KVM)
250
    - scsi (KVM)
251
    - sd (KVM)
252
    - mtd (KVM)
253
    - pflash (KVM)
254

    
255

    
256
cdrom\_disk\_type
257
    Valid for the KVM hypervisor.
258

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

    
263
    - paravirtual
264
    - ide
265
    - scsi
266
    - sd
267
    - mtd
268
    - pflash
269

    
270

    
271
vnc\_bind\_address
272
    Valid for the Xen HVM and KVM hypervisors.
273

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

    
280
vnc\_tls
281
    Valid for the KVM hypervisor.
282

    
283
    A boolean option that controls whether the VNC connection is
284
    secured with TLS.
285

    
286
vnc\_x509\_path
287
    Valid for the KVM hypervisor.
288

    
289
    If ``vnc_tls`` is enabled, this options specifies the path to the
290
    x509 certificate to use.
291

    
292
vnc\_x509\_verify
293
    Valid for the KVM hypervisor.
294

    
295
spice\_bind
296
    Valid for the KVM hypervisor.
297

    
298
    Specifies the address or interface on which the SPICE server will
299
    listen. Valid values are:
300

    
301
    - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
302
    - IPv6 addresses, including :: and ::1
303
    - names of network interfaces
304

    
305
    If a network interface is specified, the SPICE server will be bound
306
    to one of the addresses of that interface.
307

    
308
spice\_ip\_version
309
    Valid for the KVM hypervisor.
310

    
311
    Specifies which version of the IP protocol should be used by the
312
    SPICE server.
313

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

    
320
spice\_password\_file
321
    Valid for the KVM hypervisor.
322

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

    
327
spice\_image\_compression
328
    Valid for the KVM hypervisor.
329

    
330
    Configures the SPICE lossless image compression. Valid values are:
331

    
332
    - auto_glz
333
    - auto_lz
334
    - quic
335
    - glz
336
    - lz
337
    - off
338

    
339
spice\_jpeg\_wan\_compression
340
    Valid for the KVM hypervisor.
341

    
342
    Configures how SPICE should use the jpeg algorithm for lossy image
343
    compression on slow links. Valid values are:
344

    
345
    - auto
346
    - never
347
    - always
348

    
349
spice\_zlib\_glz\_wan\_compression
350
    Valid for the KVM hypervisor.
351

    
352
    Configures how SPICE should use the zlib-glz algorithm for lossy image
353
    compression on slow links. Valid values are:
354

    
355
    - auto
356
    - never
357
    - always
358

    
359
spice\_streaming\_video
360
    Valid for the KVM hypervisor.
361

    
362
    Configures how SPICE should detect video streams. Valid values are:
363

    
364
    - off
365
    - all
366
    - filter
367

    
368
spice\_playback\_compression
369
    Valid for the KVM hypervisor.
370

    
371
    Configures whether SPICE should compress audio streams or not.
372

    
373
spice\_use\_tls
374
    Valid for the KVM hypervisor.
375

    
376
    Specifies that the SPICE server must use TLS to encrypt all the
377
    traffic with the client.
378

    
379
spice\_tls\_ciphers
380
    Valid for the KVM hypervisor.
381

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

    
385
spice\_use\_vdagent
386
    Valid for the KVM hypervisor.
387

    
388
    Enables or disables passing mouse events via SPICE vdagent.
389

    
390
acpi
391
    Valid for the Xen HVM and KVM hypervisors.
392

    
393
    A boolean option that specifies if the hypervisor should enable
394
    ACPI support for this instance. By default, ACPI is disabled.
395

    
396
pae
397
    Valid for the Xen HVM and KVM hypervisors.
398

    
399
    A boolean option that specifies if the hypervisor should enabled
400
    PAE support for this instance. The default is false, disabling PAE
401
    support.
402

    
403
use\_localtime
404
    Valid for the Xen HVM and KVM hypervisors.
405

    
406
    A boolean option that specifies if the instance should be started
407
    with its clock set to the localtime of the machine (when true) or
408
    to the UTC (When false). The default is false, which is useful for
409
    Linux/Unix machines; for Windows OSes, it is recommended to enable
410
    this parameter.
411

    
412
kernel\_path
413
    Valid for the Xen PVM and KVM hypervisors.
414

    
415
    This option specifies the path (on the node) to the kernel to boot
416
    the instance with. Xen PVM instances always require this, while for
417
    KVM if this option is empty, it will cause the machine to load the
418
    kernel from its disks (and the boot will be done accordingly to
419
    ``boot_order``).
420

    
421
kernel\_args
422
    Valid for the Xen PVM and KVM hypervisors.
423

    
424
    This options specifies extra arguments to the kernel that will be
425
    loaded. device. This is always used for Xen PVM, while for KVM it
426
    is only used if the ``kernel_path`` option is also specified.
427

    
428
    The default setting for this value is simply ``"ro"``, which
429
    mounts the root disk (initially) in read-only one. For example,
430
    setting this to single will cause the instance to start in
431
    single-user mode.
432

    
433
initrd\_path
434
    Valid for the Xen PVM and KVM hypervisors.
435

    
436
    This option specifies the path (on the node) to the initrd to boot
437
    the instance with. Xen PVM instances can use this always, while
438
    for KVM if this option is only used if the ``kernel_path`` option
439
    is also specified. You can pass here either an absolute filename
440
    (the path to the initrd) if you want to use an initrd, or use the
441
    format no\_initrd\_path for no initrd.
442

    
443
root\_path
444
    Valid for the Xen PVM and KVM hypervisors.
445

    
446
    This options specifies the name of the root device. This is always
447
    needed for Xen PVM, while for KVM it is only used if the
448
    ``kernel_path`` option is also specified.
449

    
450
    Please note, that if this setting is an empty string and the
451
    hypervisor is Xen it will not be written to the Xen configuration
452
    file
453

    
454
serial\_console
455
    Valid for the KVM hypervisor.
456

    
457
    This boolean option specifies whether to emulate a serial console
458
    for the instance.
459

    
460
disk\_cache
461
    Valid for the KVM hypervisor.
462

    
463
    The disk cache mode. It can be either default to not pass any
464
    cache option to KVM, or one of the KVM cache modes: none (for
465
    direct I/O), writethrough (to use the host cache but report
466
    completion to the guest only when the host has committed the
467
    changes to disk) or writeback (to use the host cache and report
468
    completion as soon as the data is in the host cache). Note that
469
    there are special considerations for the cache mode depending on
470
    version of KVM used and disk type (always raw file under Ganeti),
471
    please refer to the KVM documentation for more details.
472

    
473
security\_model
474
    Valid for the KVM hypervisor.
475

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

    
480
    Under *user* kvm will drop privileges and become the user
481
    specified by the security\_domain parameter.
482

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

    
487
security\_domain
488
    Valid for the KVM hypervisor.
489

    
490
    Under security model *user* the username to run the instance
491
    under.  It must be a valid username existing on the host.
492

    
493
    Cannot be set under security model *none* or *pool*.
494

    
495
kvm\_flag
496
    Valid for the KVM hypervisor.
497

    
498
    If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
499
    -disable-kvm is passed. If unset no flag is passed, and the
500
    default running mode for your kvm binary will be used.
501

    
502
mem\_path
503
    Valid for the KVM hypervisor.
504

    
505
    This option passes the -mem-path argument to kvm with the path (on
506
    the node) to the mount point of the hugetlbfs file system, along
507
    with the -mem-prealloc argument too.
508

    
509
use\_chroot
510
    Valid for the KVM hypervisor.
511

    
512
    This boolean option determines whether to run the KVM instance in a
513
    chroot directory.
514

    
515
    If it is set to ``true``, an empty directory is created before
516
    starting the instance and its path is passed via the -chroot flag
517
    to kvm. The directory is removed when the instance is stopped.
518

    
519
    It is set to ``false`` by default.
520

    
521
migration\_downtime
522
    Valid for the KVM hypervisor.
523

    
524
    The maximum amount of time (in ms) a KVM instance is allowed to be
525
    frozen during a live migration, in order to copy dirty memory
526
    pages. Default value is 30ms, but you may need to increase this
527
    value for busy instances.
528

    
529
    This option is only effective with kvm versions >= 87 and qemu-kvm
530
    versions >= 0.11.0.
531

    
532
cpu\_mask
533
    Valid for the Xen, KVM and LXC hypervisors.
534

    
535
    The processes belonging to the given instance are only scheduled
536
    on the specified CPUs.
537

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

    
542
    Second, a comma-separated list of CPU IDs or CPU ID ranges. The
543
    ranges are defined by a lower and higher boundary, separated by a
544
    dash, and the boundaries are inclusive. In this form, all VCPUs of
545
    the instance will be mapped on the selected list of CPUs. Example:
546
    ``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs
547
    0, 1, 2 and 5.
548

    
549
    The last form is used for explicit control of VCPU-CPU pinnings. In
550
    this form, the list of VCPU mappings is given as a colon (:)
551
    separated list, whose elements are the possible values for the
552
    second or first form above. In this form, the number of elements in
553
    the colon-separated list _must_ equal the number of VCPUs of the
554
    instance.
555

    
556
    Example::
557

    
558
      # Map the entire instance to CPUs 0-2
559
      gnt-instance modify -H cpu_mask=0-2 my-inst
560

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

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

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

    
571
      # Pin entire VM to CPU 0
572
      gnt-instance modify -H cpu_mask=0 my-inst
573

    
574
      # Turn off CPU pinning (default setting)
575
      gnt-instance modify -H cpu_mask=all my-inst
576

    
577
usb\_mouse
578
    Valid for the KVM hypervisor.
579

    
580
    This option specifies the usb mouse type to be used. It can be
581
    "mouse" or "tablet". When using VNC it's recommended to set it to
582
    "tablet".
583

    
584
keymap
585
    Valid for the KVM hypervisor.
586

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

    
590
reboot\_behavior
591
    Valid for Xen PVM, Xen HVM and KVM hypervisors.
592

    
593
    Normally if an instance reboots, the hypervisor will restart it. If
594
    this option is set to ``exit``, the hypervisor will treat a reboot
595
    as a shutdown instead.
596

    
597
    It is set to ``reboot`` by default.
598

    
599

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

    
605
    gnt-instance add -O dhcp=yes ...
606

    
607
The ``-I (--iallocator)`` option specifies the instance allocator
608
plugin to use. If you pass in this option the allocator will select
609
nodes for this instance automatically, so you don't need to pass them
610
with the ``-n`` option. For more information please refer to the
611
instance allocator documentation.
612

    
613
The ``-t (--disk-template)`` options specifies the disk layout type
614
for the instance.  The available choices are:
615

    
616
diskless
617
    This creates an instance with no disks. Its useful for testing only
618
    (or other special cases).
619

    
620
file
621
    Disk devices will be regular files.
622

    
623
plain
624
    Disk devices will be logical volumes.
625

    
626
drbd
627
    Disk devices will be drbd (version 8.x) on top of lvm volumes.
628

    
629
rbd
630
    Disk devices will be rbd volumes residing inside a RADOS cluster.
631

    
632

    
633
The optional second value of the ``-n (--node)`` is used for the drbd
634
template type and specifies the remote node.
635

    
636
If you do not want gnt-instance to wait for the disk mirror to be
637
synced, use the ``--no-wait-for-sync`` option.
638

    
639
The ``--file-storage-dir`` specifies the relative path under the
640
cluster-wide file storage directory to store file-based disks. It is
641
useful for having different subdirectories for different
642
instances. The full path of the directory where the disk files are
643
stored will consist of cluster-wide file storage directory + optional
644
subdirectory + instance name. Example:
645
``@RPL_FILE_STORAGE_DIR@``*/mysubdir/instance1.example.com*. This
646
option is only relevant for instances using the file storage backend.
647

    
648
The ``--file-driver`` specifies the driver to use for file-based
649
disks. Note that currently these drivers work with the xen hypervisor
650
only. This option is only relevant for instances using the file
651
storage backend. The available choices are:
652

    
653
loop
654
    Kernel loopback driver. This driver uses loopback devices to
655
    access the filesystem within the file. However, running I/O
656
    intensive applications in your instance using the loop driver
657
    might result in slowdowns. Furthermore, if you use the loopback
658
    driver consider increasing the maximum amount of loopback devices
659
    (on most systems it's 8) using the max\_loop param.
660

    
661
blktap
662
    The blktap driver (for Xen hypervisors). In order to be able to
663
    use the blktap driver you should check if the 'blktapctrl' user
664
    space disk agent is running (usually automatically started via
665
    xend).  This user-level disk I/O interface has the advantage of
666
    better performance. Especially if you use a network file system
667
    (e.g. NFS) to store your instances this is the recommended choice.
668

    
669
If ``--ignore-ipolicy`` is given any instance policy violations occuring
670
during this operation are ignored.
671

    
672
See **ganeti(7)** for a description of ``--submit`` and other common
673
options.
674

    
675
Example::
676

    
677
    # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
678
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
679
    # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
680
      -o debian-etch -n node1.example.com instance1.example.com
681
    # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
682
      -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
683
    # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
684
      -n node1.example.com:node2.example.com instance2.example.com
685

    
686

    
687
BATCH-CREATE
688
^^^^^^^^^^^^
689

    
690
**batch-create** {instances\_file.json}
691

    
692
This command (similar to the Ganeti 1.2 **batcher** tool) submits
693
multiple instance creation jobs based on a definition file. The
694
instance configurations do not encompass all the possible options for
695
the **add** command, but only a subset.
696

    
697
The instance file should be a valid-formed JSON file, containing a
698
dictionary with instance name and instance parameters. The accepted
699
parameters are:
700

    
701
disk\_size
702
    The size of the disks of the instance.
703

    
704
disk\_template
705
    The disk template to use for the instance, the same as in the
706
    **add** command.
707

    
708
backend
709
    A dictionary of backend parameters.
710

    
711
hypervisor
712
    A dictionary with a single key (the hypervisor name), and as value
713
    the hypervisor options. If not passed, the default hypervisor and
714
    hypervisor options will be inherited.
715

    
716
mac, ip, mode, link
717
    Specifications for the one NIC that will be created for the
718
    instance. 'bridge' is also accepted as a backwards compatible
719
    key.
720

    
721
nics
722
    List of nics that will be created for the instance. Each entry
723
    should be a dict, with mac, ip, mode and link as possible keys.
724
    Please don't provide the "mac, ip, mode, link" parent keys if you
725
    use this method for specifying nics.
726

    
727
primary\_node, secondary\_node
728
    The primary and optionally the secondary node to use for the
729
    instance (in case an iallocator script is not used).
730

    
731
iallocator
732
    Instead of specifying the nodes, an iallocator script can be used
733
    to automatically compute them.
734

    
735
start
736
    whether to start the instance
737

    
738
ip\_check
739
    Skip the check for already-in-use instance; see the description in
740
    the **add** command for details.
741

    
742
name\_check
743
    Skip the name check for instances; see the description in the
744
    **add** command for details.
745

    
746
file\_storage\_dir, file\_driver
747
    Configuration for the file disk type, see the **add** command for
748
    details.
749

    
750

    
751
A simple definition for one instance can be (with most of the
752
parameters taken from the cluster defaults)::
753

    
754
    {
755
      "instance3": {
756
        "template": "drbd",
757
        "os": "debootstrap",
758
        "disk_size": ["25G"],
759
        "iallocator": "dumb"
760
      },
761
      "instance5": {
762
        "template": "drbd",
763
        "os": "debootstrap",
764
        "disk_size": ["25G"],
765
        "iallocator": "dumb",
766
        "hypervisor": "xen-hvm",
767
        "hvparams": {"acpi": true},
768
        "backend": {"maxmem": 512, "minmem": 256}
769
      }
770
    }
771

    
772
The command will display the job id for each submitted instance, as
773
follows::
774

    
775
    # gnt-instance batch-create instances.json
776
    instance3: 11224
777
    instance5: 11225
778

    
779
REMOVE
780
^^^^^^
781

    
782
**remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
783
[\--force] {*instance*}
784

    
785
Remove an instance. This will remove all data from the instance and
786
there is *no way back*. If you are not sure if you use an instance
787
again, use **shutdown** first and leave it in the shutdown state for a
788
while.
789

    
790
The ``--ignore-failures`` option will cause the removal to proceed
791
even in the presence of errors during the removal of the instance
792
(e.g. during the shutdown or the disk removal). If this option is not
793
given, the command will stop at the first error.
794

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

    
800
The ``--force`` option is used to skip the interactive confirmation.
801

    
802
See **ganeti(7)** for a description of ``--submit`` and other common
803
options.
804

    
805
Example::
806

    
807
    # gnt-instance remove instance1.example.com
808

    
809

    
810
LIST
811
^^^^
812

    
813
| **list**
814
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
815
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
816

    
817
Shows the currently configured instances with memory usage, disk
818
usage, the node they are running on, and their run status.
819

    
820
The ``--no-headers`` option will skip the initial header line. The
821
``--separator`` option takes an argument which denotes what will be
822
used between the output fields. Both these options are to help
823
scripting.
824

    
825
The units used to display the numeric values in the output varies,
826
depending on the options given. By default, the values will be
827
formatted in the most appropriate unit. If the ``--separator`` option
828
is given, then the values are shown in mebibytes to allow parsing by
829
scripts. In both cases, the ``--units`` option can be used to enforce
830
a given output unit.
831

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

    
835
The ``-o (--output)`` option takes a comma-separated list of output
836
fields. The available fields and their meaning are:
837

    
838
@QUERY_FIELDS_INSTANCE@
839

    
840
If the value of the option starts with the character ``+``, the new
841
field(s) will be added to the default list. This allows one to quickly
842
see the default list plus a few other fields, instead of retyping the
843
entire list of fields.
844

    
845
There is a subtle grouping about the available output fields: all
846
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
847
``status`` are configuration value and not run-time values. So if you
848
don't select any of the these fields, the query will be satisfied
849
instantly from the cluster configuration, without having to ask the
850
remote nodes for the data. This can be helpful for big clusters when
851
you only want some data and it makes sense to specify a reduced set of
852
output fields.
853

    
854
If exactly one argument is given and it appears to be a query filter
855
(see **ganeti(7)**), the query result is filtered accordingly. For
856
ambiguous cases (e.g. a single field name as a filter) the ``--filter``
857
(``-F``) option forces the argument to be treated as a filter (e.g.
858
``gnt-instance list -F admin_state``).
859

    
860
The default output field list is: ``name``, ``os``, ``pnode``,
861
``admin_state``, ``oper_state``, ``oper_ram``.
862

    
863

    
864
LIST-FIELDS
865
~~~~~~~~~~~
866

    
867
**list-fields** [field...]
868

    
869
Lists available fields for instances.
870

    
871

    
872
INFO
873
^^^^
874

    
875
**info** [-s \| \--static] [\--roman] {\--all \| *instance*}
876

    
877
Show detailed information about the given instance(s). This is
878
different from **list** as it shows detailed data about the instance's
879
disks (especially useful for the drbd disk template).
880

    
881
If the option ``-s`` is used, only information available in the
882
configuration file is returned, without querying nodes, making the
883
operation faster.
884

    
885
Use the ``--all`` to get info about all instances, rather than
886
explicitly passing the ones you're interested in.
887

    
888
The ``--roman`` option can be used to cause envy among people who like
889
ancient cultures, but are stuck with non-latin-friendly cluster
890
virtualization technologies.
891

    
892
MODIFY
893
^^^^^^
894

    
895
| **modify**
896
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
897
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
898
| [{-m|\--runtime-memory} *SIZE*]
899
| [\--net add*[:options]* \| \--net remove \| \--net *N:options*]
900
| [\--disk add:size=*SIZE*[,vg=*VG*][,metavg=*VG*] \| \--disk remove \|
901
|  \--disk *N*:mode=*MODE*]
902
| [{-t|\--disk-template} plain | {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
903
| [\--os-type=*OS* [\--force-variant]]
904
| [{-O|\--os-parameters} *param*=*value*... ]
905
| [\--offline \| \--online]
906
| [\--submit]
907
| [\--ignore-ipolicy]
908
| {*instance*}
909

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

    
915
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
916
and ``-O (--os-parameters)`` options specifies hypervisor, backend and
917
OS parameter options in the form of name=value[,...]. For details
918
which options can be specified, see the **add** command.
919

    
920
The ``-t (--disk-template)`` option will change the disk template of
921
the instance.  Currently only conversions between the plain and drbd
922
disk templates are supported, and the instance must be stopped before
923
attempting the conversion. When changing from the plain to the drbd
924
disk template, a new secondary node must be specified via the ``-n``
925
option. The option ``--no-wait-for-sync`` can be used when converting
926
to the ``drbd`` template in order to make the instance available for
927
startup before DRBD has finished resyncing.
928

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

    
933
The ``--disk add:size=``*SIZE* option adds a disk to the instance. The
934
optional ``vg=``*VG* option specifies an LVM volume group other than
935
the default volume group to create the disk on. For DRBD disks, the
936
``metavg=``*VG* option specifies the volume group for the metadata
937
device. ``--disk`` *N*``:add,size=``**SIZE** can be used to add a
938
disk at a specific index. The ``--disk remove`` option will remove the
939
last disk of the instance. Use ``--disk `` *N*``:remove`` to remove a
940
disk by its index. The ``--disk`` *N*``:mode=``*MODE* option will change
941
the mode of the Nth disk of the instance between read-only (``ro``) and
942
read-write (``rw``).
943

    
944
The ``--net add:``*options* and ``--net`` *N*``:add,``*options* option
945
will add a new network interface to the instance. The available options
946
are the same as in the **add** command (``mac``, ``ip``, ``link``,
947
``mode``). The ``--net remove`` will remove the last network interface
948
of the instance (``--net`` *N*``:remove`` for a specific index), while
949
the ``--net`` *N*``:``*options* option will change the parameters of the Nth
950
instance network interface.
951

    
952
The option ``-o (--os-type)`` will change the OS name for the instance
953
(without reinstallation). In case an OS variant is specified that is
954
not found, then by default the modification is refused, unless
955
``--force-variant`` is passed. An invalid OS will also be refused,
956
unless the ``--force`` option is given.
957

    
958
The ``--online`` and ``--offline`` options are used to transition an
959
instance into and out of the ``offline`` state. An instance can be
960
turned offline only if it was previously down. The ``--online`` option
961
fails if the instance was not in the ``offline`` state, otherwise it
962
changes instance's state to ``down``. These modifications take effect
963
immediately.
964

    
965
If ``--ignore-ipolicy`` is given any instance policy violations occuring
966
during this operation are ignored.
967

    
968
See **ganeti(7)** for a description of ``--submit`` and other common
969
options.
970

    
971
Most of the changes take effect at the next restart. If the instance is
972
running, there is no effect on the instance.
973

    
974
REINSTALL
975
^^^^^^^^^
976

    
977
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
978
| [\--force-multiple]
979
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
980
| [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] {*instance*...}
981

    
982
Reinstalls the operating system on the given instance(s). The
983
instance(s) must be stopped when running this command. If the ``-o
984
(--os-type)`` is specified, the operating system is changed.
985

    
986
The ``--select-os`` option switches to an interactive OS reinstall.
987
The user is prompted to select the OS template from the list of
988
available OS templates. OS parameters can be overridden using ``-O
989
(--os-parameters)`` (more documentation for this option under the
990
**add** command).
991

    
992
Since this is a potentially dangerous command, the user will be
993
required to confirm this action, unless the ``-f`` flag is passed.
994
When multiple instances are selected (either by passing multiple
995
arguments or by using the ``--node``, ``--primary``, ``--secondary``
996
or ``--all`` options), the user must pass the ``--force-multiple``
997
options to skip the interactive confirmation.
998

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

    
1002
RENAME
1003
^^^^^^
1004

    
1005
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit]
1006
| {*instance*} {*new\_name*}
1007

    
1008
Renames the given instance. The instance must be stopped when running
1009
this command. The requirements for the new name are the same as for
1010
adding an instance: the new name must be resolvable and the IP it
1011
resolves to must not be reachable (in order to prevent duplicate IPs
1012
the next time the instance is started). The IP test can be skipped if
1013
the ``--no-ip-check`` option is passed.
1014

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

    
1021
See **ganeti(7)** for a description of ``--submit`` and other common
1022
options.
1023

    
1024
Starting/stopping/connecting to console
1025
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1026

    
1027
STARTUP
1028
^^^^^^^
1029

    
1030
| **startup**
1031
| [\--force] [\--ignore-offline]
1032
| [\--force-multiple] [\--no-remember]
1033
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1034
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1035
| [{-H|\--hypervisor-parameters} ``key=value...``]
1036
| [{-B|\--backend-parameters} ``key=value...``]
1037
| [\--submit] [\--paused]
1038
| {*name*...}
1039

    
1040
Starts one or more instances, depending on the following options.  The
1041
four available modes are:
1042

    
1043
\--instance
1044
    will start the instances given as arguments (at least one argument
1045
    required); this is the default selection
1046

    
1047
\--node
1048
    will start the instances who have the given node as either primary
1049
    or secondary
1050

    
1051
\--primary
1052
    will start all instances whose primary node is in the list of nodes
1053
    passed as arguments (at least one node required)
1054

    
1055
\--secondary
1056
    will start all instances whose secondary node is in the list of
1057
    nodes passed as arguments (at least one node required)
1058

    
1059
\--all
1060
    will start all instances in the cluster (no arguments accepted)
1061

    
1062
\--tags
1063
    will start all instances in the cluster with the tags given as
1064
    arguments
1065

    
1066
\--node-tags
1067
    will start all instances in the cluster on nodes with the tags
1068
    given as arguments
1069

    
1070
\--pri-node-tags
1071
    will start all instances in the cluster on primary nodes with the
1072
    tags given as arguments
1073

    
1074
\--sec-node-tags
1075
    will start all instances in the cluster on secondary nodes with the
1076
    tags given as arguments
1077

    
1078
Note that although you can pass more than one selection option, the
1079
last one wins, so in order to guarantee the desired result, don't pass
1080
more than one such option.
1081

    
1082
Use ``--force`` to start even if secondary disks are failing.
1083
``--ignore-offline`` can be used to ignore offline primary nodes and
1084
mark the instance as started even if the primary is not available.
1085

    
1086
The ``--force-multiple`` will skip the interactive confirmation in the
1087
case the more than one instance will be affected.
1088

    
1089
The ``--no-remember`` option will perform the startup but not change
1090
the state of the instance in the configuration file (if it was stopped
1091
before, Ganeti will still thinks it needs to be stopped). This can be
1092
used for testing, or for a one shot-start where you don't want the
1093
watcher to restart the instance if it crashes.
1094

    
1095
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
1096
options specify temporary hypervisor and backend parameters that can
1097
be used to start an instance with modified parameters. They can be
1098
useful for quick testing without having to modify an instance back and
1099
forth, e.g.::
1100

    
1101
    # gnt-instance start -H kernel_args="single" instance1
1102
    # gnt-instance start -B maxmem=2048 instance2
1103

    
1104

    
1105
The first form will start the instance instance1 in single-user mode,
1106
and the instance instance2 with 2GB of RAM (this time only, unless
1107
that is the actual instance memory size already). Note that the values
1108
override the instance parameters (and not extend them): an instance
1109
with "kernel\_args=ro" when started with -H kernel\_args=single will
1110
result in "single", not "ro single".
1111

    
1112
The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
1113
pauses the instance at the start of bootup, awaiting ``gnt-instance
1114
console`` to unpause it, allowing the entire boot process to be
1115
monitored for debugging.
1116

    
1117
See **ganeti(7)** for a description of ``--submit`` and other common
1118
options.
1119

    
1120
Example::
1121

    
1122
    # gnt-instance start instance1.example.com
1123
    # gnt-instance start --node node1.example.com node2.example.com
1124
    # gnt-instance start --all
1125

    
1126

    
1127
SHUTDOWN
1128
^^^^^^^^
1129

    
1130
| **shutdown**
1131
| [\--timeout=*N*]
1132
| [\--force-multiple] [\--ignore-offline] [\--no-remember]
1133
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1134
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1135
| [\--submit]
1136
| {*name*...}
1137

    
1138
Stops one or more instances. If the instance cannot be cleanly stopped
1139
during a hardcoded interval (currently 2 minutes), it will forcibly
1140
stop the instance (equivalent to switching off the power on a physical
1141
machine).
1142

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

    
1148
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1149
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1150
``--sec-node-tags`` options are similar as for the **startup** command
1151
and they influence the actual instances being shutdown.
1152

    
1153
``--ignore-offline`` can be used to ignore offline primary nodes and
1154
force the instance to be marked as stopped. This option should be used
1155
with care as it can lead to an inconsistent cluster state.
1156

    
1157
The ``--no-remember`` option will perform the shutdown but not change
1158
the state of the instance in the configuration file (if it was running
1159
before, Ganeti will still thinks it needs to be running). This can be
1160
useful for a cluster-wide shutdown, where some instances are marked as
1161
up and some as down, and you don't want to change the running state:
1162
you just need to disable the watcher, shutdown all instances with
1163
``--no-remember``, and when the watcher is activated again it will
1164
restore the correct runtime state for all instances.
1165

    
1166
See **ganeti(7)** for a description of ``--submit`` and other common
1167
options.
1168

    
1169
Example::
1170

    
1171
    # gnt-instance shutdown instance1.example.com
1172
    # gnt-instance shutdown --all
1173

    
1174

    
1175
REBOOT
1176
^^^^^^
1177

    
1178
| **reboot**
1179
| [{-t|\--type} *REBOOT-TYPE*]
1180
| [\--ignore-secondaries]
1181
| [\--shutdown-timeout=*N*]
1182
| [\--force-multiple]
1183
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1184
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1185
| [\--submit]
1186
| [*name*...]
1187

    
1188
Reboots one or more instances. The type of reboot depends on the value
1189
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1190
does a instance stop, recreates the hypervisor config for the instance
1191
and starts the instance. A full reboot does the equivalent of
1192
**gnt-instance shutdown && gnt-instance startup**.  The default is
1193
hard reboot.
1194

    
1195
For the hard reboot the option ``--ignore-secondaries`` ignores errors
1196
for the secondary node while re-assembling the instance disks.
1197

    
1198
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1199
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1200
``--sec-node-tags`` options are similar as for the **startup** command
1201
and they influence the actual instances being rebooted.
1202

    
1203
The ``--shutdown-timeout`` is used to specify how much time to wait
1204
before forcing the shutdown (xm destroy in xen, killing the kvm
1205
process, for kvm). By default two minutes are given to each instance
1206
to stop.
1207

    
1208
The ``--force-multiple`` will skip the interactive confirmation in the
1209
case the more than one instance will be affected.
1210

    
1211
See **ganeti(7)** for a description of ``--submit`` and other common
1212
options.
1213

    
1214
Example::
1215

    
1216
    # gnt-instance reboot instance1.example.com
1217
    # gnt-instance reboot --type=full instance1.example.com
1218

    
1219

    
1220
CONSOLE
1221
^^^^^^^
1222

    
1223
**console** [\--show-cmd] {*instance*}
1224

    
1225
Connects to the console of the given instance. If the instance is not
1226
up, an error is returned. Use the ``--show-cmd`` option to display the
1227
command instead of executing it.
1228

    
1229
For HVM instances, this will attempt to connect to the serial console
1230
of the instance. To connect to the virtualized "physical" console of a
1231
HVM instance, use a VNC client with the connection info from the
1232
**info** command.
1233

    
1234
For Xen/kvm instances, if the instance is paused, this attempts to
1235
unpause the instance after waiting a few seconds for the connection to
1236
the console to be made.
1237

    
1238
Example::
1239

    
1240
    # gnt-instance console instance1.example.com
1241

    
1242

    
1243
Disk management
1244
~~~~~~~~~~~~~~~
1245

    
1246
REPLACE-DISKS
1247
^^^^^^^^^^^^^
1248

    
1249
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-p}
1250
[\--disks *idx*] {*instance*}
1251

    
1252
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-s}
1253
[\--disks *idx*] {*instance*}
1254

    
1255
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1256
{{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*}
1257

    
1258
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1259
{-a\|\--auto} {*instance*}
1260

    
1261
This command is a generalized form for replacing disks. It is
1262
currently only valid for the mirrored (DRBD) disk template.
1263

    
1264
The first form (when passing the ``-p`` option) will replace the disks
1265
on the primary, while the second form (when passing the ``-s`` option
1266
will replace the disks on the secondary node. For these two cases (as
1267
the node doesn't change), it is possible to only run the replace for a
1268
subset of the disks, using the option ``--disks`` which takes a list
1269
of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only
1270
the first and third disks.
1271

    
1272
The third form (when passing either the ``--iallocator`` or the
1273
``--new-secondary`` option) is designed to change secondary node of
1274
the instance. Specifying ``--iallocator`` makes the new secondary be
1275
selected automatically by the specified allocator plugin, otherwise
1276
the new secondary node will be the one chosen manually via the
1277
``--new-secondary`` option.
1278

    
1279
Note that it is not possible to select an offline or drained node as a
1280
new secondary.
1281

    
1282
The fourth form (when using ``--auto``) will automatically determine
1283
which disks of an instance are faulty and replace them within the same
1284
node. The ``--auto`` option works only when an instance has only
1285
faulty disks on either the primary or secondary node; it doesn't work
1286
when both sides have faulty disks.
1287

    
1288
The ``--early-release`` changes the code so that the old storage on
1289
secondary node(s) is removed early (before the resync is completed)
1290
and the internal Ganeti locks for the current (and new, if any)
1291
secondary node are also released, thus allowing more parallelism in
1292
the cluster operation. This should be used only when recovering from a
1293
disk failure on the current secondary (thus the old storage is already
1294
broken) or when the storage on the primary node is known to be fine
1295
(thus we won't need the old storage for potential recovery).
1296

    
1297
The ``--ignore-ipolicy`` let the command ignore instance policy
1298
violations if replace-disks changes groups and the instance would
1299
violate the new groups instance policy.
1300

    
1301
See **ganeti(7)** for a description of ``--submit`` and other common
1302
options.
1303

    
1304
ACTIVATE-DISKS
1305
^^^^^^^^^^^^^^
1306

    
1307
**activate-disks** [\--submit] [\--ignore-size] {*instance*}
1308

    
1309
Activates the block devices of the given instance. If successful, the
1310
command will show the location and name of the block devices::
1311

    
1312
    node1.example.com:disk/0:/dev/drbd0
1313
    node1.example.com:disk/1:/dev/drbd1
1314

    
1315

    
1316
In this example, *node1.example.com* is the name of the node on which
1317
the devices have been activated. The *disk/0* and *disk/1* are the
1318
Ganeti-names of the instance disks; how they are visible inside the
1319
instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the
1320
actual block devices as visible on the node.
1321

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

    
1329
Note that it is safe to run this command while the instance is already
1330
running.
1331

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

    
1335
DEACTIVATE-DISKS
1336
^^^^^^^^^^^^^^^^
1337

    
1338
**deactivate-disks** [-f] [\--submit] {*instance*}
1339

    
1340
De-activates the block devices of the given instance. Note that if you
1341
run this command for an instance with a drbd disk template, while it
1342
is running, it will not be able to shutdown the block devices on the
1343
primary node, but it will shutdown the block devices on the secondary
1344
nodes, thus breaking the replication.
1345

    
1346
The ``-f``/``--force`` option will skip checks that the instance is
1347
down; in case the hypervisor is confused and we can't talk to it,
1348
normally Ganeti will refuse to deactivate the disks, but with this
1349
option passed it will skip this check and directly try to deactivate
1350
the disks. This can still fail due to the instance actually running or
1351
other issues.
1352

    
1353
See **ganeti(7)** for a description of ``--submit`` and other common
1354
options.
1355

    
1356
GROW-DISK
1357
^^^^^^^^^
1358

    
1359
| **grow-disk** [\--no-wait-for-sync] [\--submit] [\--absolute]
1360
| {*instance*} {*disk*} {*amount*}
1361

    
1362
Grows an instance's disk. This is only possible for instances having a
1363
plain, drbd or rbd disk template.
1364

    
1365
Note that this command only change the block device size; it will not
1366
grow the actual filesystems, partitions, etc. that live on that
1367
disk. Usually, you will need to:
1368

    
1369
#. use **gnt-instance grow-disk**
1370

    
1371
#. reboot the instance (later, at a convenient time)
1372

    
1373
#. use a filesystem resizer, such as ext2online(8) or
1374
   xfs\_growfs(8) to resize the filesystem, or use fdisk(8) to change
1375
   the partition table on the disk
1376

    
1377
The *disk* argument is the index of the instance disk to grow. The
1378
*amount* argument is given as a number which can have a suffix (like the
1379
disk size in instance create); if the suffix is missing, the value will
1380
be interpreted as mebibytes.
1381

    
1382
By default, the *amount* value represents the desired increase in the
1383
disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If
1384
the optional ``--absolute`` parameter is passed, then the *amount*
1385
argument doesn't represent the delta, but instead the desired final disk
1386
size (e.g. an amount of 8G will take a disk of size 4G to 8G).
1387

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

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

    
1396
See **ganeti(7)** for a description of ``--submit`` and other common
1397
options.
1398

    
1399
Example (increase the first disk for instance1 by 16GiB)::
1400

    
1401
    # gnt-instance grow-disk instance1.example.com 0 16g
1402

    
1403
Example for increasing the disk size to a certain size::
1404

    
1405
   # gnt-instance grow-disk --absolute instance1.example.com 0 32g
1406

    
1407
Also note that disk shrinking is not supported; use **gnt-backup
1408
export** and then **gnt-backup import** to reduce the disk size of an
1409
instance.
1410

    
1411
RECREATE-DISKS
1412
^^^^^^^^^^^^^^
1413

    
1414
| **recreate-disks** [\--submit] [-n node1:[node2]]
1415
| [\--disk=*N*[:[size=*VAL*][,mode=*ro\|rw*]]] {*instance*}
1416

    
1417
Recreates all or a subset of disks of the given instance.
1418

    
1419
Note that this functionality should only be used for missing disks; if
1420
any of the given disks already exists, the operation will fail.  While
1421
this is suboptimal, recreate-disks should hopefully not be needed in
1422
normal operation and as such the impact of this is low.
1423

    
1424
If only a subset should be recreated, any number of ``disk`` options can
1425
be specified. It expects a disk index and an optional list of disk
1426
parameters to change. Only ``size`` and ``mode`` can be changed while
1427
recreating disks. To recreate all disks while changing parameters on
1428
a subset only, a ``--disk`` option must be given for every disk of the
1429
instance.
1430

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

    
1440
See **ganeti(7)** for a description of ``--submit`` and other common
1441
options.
1442

    
1443
Recovery
1444
~~~~~~~~
1445

    
1446
FAILOVER
1447
^^^^^^^^
1448

    
1449
| **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy]
1450
| [\--shutdown-timeout=*N*]
1451
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*]
1452
| [\--submit]
1453
| {*instance*}
1454

    
1455
Failover will stop the instance (if running), change its primary node,
1456
and if it was originally running it will start it again (on the new
1457
primary). This only works for instances with drbd template (in which
1458
case you can only fail to the secondary node) and for externally
1459
mirrored templates (blockdev and rbd) (which can change to any other
1460
node).
1461

    
1462
If the instance's disk template is of type blockdev or rbd, then you
1463
can explicitly specify the target node (which can be any node) using
1464
the ``-n`` or ``--target-node`` option, or specify an iallocator plugin
1465
using the ``-I`` or ``--iallocator`` option. If you omit both, the default
1466
iallocator will be used to specify the target node.
1467

    
1468
Normally the failover will check the consistency of the disks before
1469
failing over the instance. If you are trying to migrate instances off
1470
a dead node, this will fail. Use the ``--ignore-consistency`` option
1471
for this purpose. Note that this option can be dangerous as errors in
1472
shutting down the instance will be ignored, resulting in possibly
1473
having the instance running on two machines in parallel (on
1474
disconnected DRBD drives).
1475

    
1476
The ``--shutdown-timeout`` is used to specify how much time to wait
1477
before forcing the shutdown (xm destroy in xen, killing the kvm
1478
process, for kvm). By default two minutes are given to each instance
1479
to stop.
1480

    
1481
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1482
during this operation are ignored.
1483

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

    
1487
Example::
1488

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

    
1491

    
1492
MIGRATE
1493
^^^^^^^
1494

    
1495
| **migrate** [-f] [\--allow-failover] [\--non-live]
1496
| [\--migration-mode=live\|non-live] [\--ignore-ipolicy]
1497
| [\--no-runtime-changes] [\--submit]
1498
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*}
1499

    
1500
| **migrate** [-f] \--cleanup [\--submit] {*instance*}
1501

    
1502
Migrate will move the instance to its secondary node without shutdown.
1503
As with failover, it only works for instances having the drbd disk
1504
template or an externally mirrored disk template type such as blockdev
1505
or rbd.
1506

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

    
1513
The migration command needs a perfectly healthy instance, as we rely
1514
on the dual-master capability of drbd8 and the disks of the instance
1515
are not allowed to be degraded.
1516

    
1517
The ``--non-live`` and ``--migration-mode=non-live`` options will
1518
switch (for the hypervisors that support it) between a "fully live"
1519
(i.e. the interruption is as minimal as possible) migration and one in
1520
which the instance is frozen, its state saved and transported to the
1521
remote node, and then resumed there. This all depends on the
1522
hypervisor support for two different methods. In any case, it is not
1523
an error to pass this parameter (it will just be ignored if the
1524
hypervisor doesn't support it). The option ``--migration-mode=live``
1525
option will request a fully-live migration. The default, when neither
1526
option is passed, depends on the hypervisor parameters (and can be
1527
viewed with the **gnt-cluster info** command).
1528

    
1529
If the ``--cleanup`` option is passed, the operation changes from
1530
migration to attempting recovery from a failed previous migration.  In
1531
this mode, Ganeti checks if the instance runs on the correct node (and
1532
updates its configuration if not) and ensures the instances' disks
1533
are configured correctly. In this mode, the ``--non-live`` option is
1534
ignored.
1535

    
1536
The option ``-f`` will skip the prompting for confirmation.
1537

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

    
1543
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1544
during this operation are ignored.
1545

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

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

    
1553
See **ganeti(7)** for a description of ``--submit`` and other common
1554
options.
1555

    
1556
Example (and expected output)::
1557

    
1558
    # gnt-instance migrate instance1
1559
    Instance instance1 will be migrated. Note that migration
1560
    might impact the instance if anything goes wrong (e.g. due to bugs in
1561
    the hypervisor). Continue?
1562
    y/[n]/?: y
1563
    Migrating instance instance1.example.com
1564
    * checking disk consistency between source and target
1565
    * switching node node2.example.com to secondary mode
1566
    * changing into standalone mode
1567
    * changing disks into dual-master mode
1568
    * wait until resync is done
1569
    * preparing node2.example.com to accept the instance
1570
    * migrating instance to node2.example.com
1571
    * switching node node1.example.com to secondary mode
1572
    * wait until resync is done
1573
    * changing into standalone mode
1574
    * changing disks into single-master mode
1575
    * wait until resync is done
1576
    * done
1577
    #
1578

    
1579

    
1580
MOVE
1581
^^^^
1582

    
1583
| **move** [-f] [\--ignore-consistency]
1584
| [-n *node*] [\--shutdown-timeout=*N*] [\--submit] [\--ignore-ipolicy]
1585
| {*instance*}
1586

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

    
1590
Note that since this operation is done via data copy, it will take a
1591
long time for big disks (similar to replace-disks for a drbd
1592
instance).
1593

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

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

    
1603
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1604
during this operation are ignored.
1605

    
1606
See **ganeti(7)** for a description of ``--submit`` and other common
1607
options.
1608

    
1609
Example::
1610

    
1611
    # gnt-instance move -n node3.example.com instance1.example.com
1612

    
1613

    
1614
CHANGE-GROUP
1615
~~~~~~~~~~~~
1616

    
1617
| **change-group** [\--submit]
1618
| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
1619

    
1620
This command moves an instance to another node group. The move is
1621
calculated by an iallocator, either given on the command line or as a
1622
cluster default.
1623

    
1624
If no specific destination groups are specified using ``--to``, all
1625
groups except the one containing the instance are considered.
1626

    
1627
See **ganeti(7)** for a description of ``--submit`` and other common
1628
options.
1629

    
1630
Example::
1631

    
1632
    # gnt-instance change-group -I hail --to rack2 inst1.example.com
1633

    
1634

    
1635
TAGS
1636
~~~~
1637

    
1638
ADD-TAGS
1639
^^^^^^^^
1640

    
1641
**add-tags** [\--from *file*] {*instancename*} {*tag*...}
1642

    
1643
Add tags to the given instance. If any of the tags contains invalid
1644
characters, the entire operation will abort.
1645

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

    
1652
LIST-TAGS
1653
^^^^^^^^^
1654

    
1655
**list-tags** {*instancename*}
1656

    
1657
List the tags of the given instance.
1658

    
1659
REMOVE-TAGS
1660
^^^^^^^^^^^
1661

    
1662
**remove-tags** [\--from *file*] {*instancename*} {*tag*...}
1663

    
1664
Remove tags from the given instance. If any of the tags are not
1665
existing on the node, the entire operation will abort.
1666

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

    
1673
.. vim: set textwidth=72 :
1674
.. Local Variables:
1675
.. mode: rst
1676
.. fill-column: 72
1677
.. End: