Statistics
| Branch: | Tag: | Revision:

root / man / gnt-instance.rst @ 2fddb144

History | View | Annotate | Download (62.7 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, bridged or
107
    openvswitch.
108

    
109
link
110
    in bridged or openvswitch mode specifies the interface to attach
111
    this NIC to, in routed mode it's intended to differentiate between
112
    different routing tables/instance groups (but the meaning is
113
    dependent on the network script, see **gnt-cluster**\(8) for more
114
    details). Note that openvswitch support is also hypervisor
115
    dependent.
116

    
117

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

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

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

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

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

    
143
vcpus
144
    the number of VCPUs to assign to the instance (if this value makes
145
    sense for the hypervisor)
146

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

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

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

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

    
169
The possible hypervisor options are as follows:
170

    
171
boot\_order
172
    Valid for the Xen HVM and KVM hypervisors.
173

    
174
    A string value denoting the boot order. This has different meaning
175
    for the Xen HVM hypervisor and for the KVM one.
176

    
177
    For Xen HVM, The boot order is a string of letters listing the boot
178
    devices, with valid device letters being:
179

    
180
    a
181
        floppy drive
182

    
183
    c
184
        hard disk
185

    
186
    d
187
        CDROM drive
188

    
189
    n
190
        network boot (PXE)
191

    
192
    The default is not to set an HVM boot order, which is interpreted
193
    as 'dc'.
194

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

    
202
blockdev\_prefix
203
    Valid for the Xen HVM and PVM hypervisors.
204

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

    
209
floppy\_image\_path
210
    Valid for the KVM hypervisor.
211

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

    
217
cdrom\_image\_path
218
    Valid for the Xen HVM and KVM hypervisors.
219

    
220
    The path to a CDROM image to attach to the instance.
221

    
222
cdrom2\_image\_path
223
    Valid for the KVM hypervisor.
224

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

    
229
nic\_type
230
    Valid for the Xen HVM and KVM hypervisors.
231

    
232
    This parameter determines the way the network cards are presented
233
    to the instance. The possible options are:
234

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

    
245
disk\_type
246
    Valid for the Xen HVM and KVM hypervisors.
247

    
248
    This parameter determines the way the disks are presented to the
249
    instance. The possible options are:
250

    
251
    - ioemu [default] (HVM & KVM)
252
    - ide (HVM & KVM)
253
    - scsi (KVM)
254
    - sd (KVM)
255
    - mtd (KVM)
256
    - pflash (KVM)
257

    
258

    
259
cdrom\_disk\_type
260
    Valid for the KVM hypervisor.
261

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

    
266
    - paravirtual
267
    - ide
268
    - scsi
269
    - sd
270
    - mtd
271
    - pflash
272

    
273

    
274
vnc\_bind\_address
275
    Valid for the Xen HVM and KVM hypervisors.
276

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

    
283
vnc\_tls
284
    Valid for the KVM hypervisor.
285

    
286
    A boolean option that controls whether the VNC connection is
287
    secured with TLS.
288

    
289
vnc\_x509\_path
290
    Valid for the KVM hypervisor.
291

    
292
    If ``vnc_tls`` is enabled, this options specifies the path to the
293
    x509 certificate to use.
294

    
295
vnc\_x509\_verify
296
    Valid for the KVM hypervisor.
297

    
298
spice\_bind
299
    Valid for the KVM hypervisor.
300

    
301
    Specifies the address or interface on which the SPICE server will
302
    listen. Valid values are:
303

    
304
    - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
305
    - IPv6 addresses, including :: and ::1
306
    - names of network interfaces
307

    
308
    If a network interface is specified, the SPICE server will be bound
309
    to one of the addresses of that interface.
310

    
311
spice\_ip\_version
312
    Valid for the KVM hypervisor.
313

    
314
    Specifies which version of the IP protocol should be used by the
315
    SPICE server.
316

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

    
323
spice\_password\_file
324
    Valid for the KVM hypervisor.
325

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

    
330
spice\_image\_compression
331
    Valid for the KVM hypervisor.
332

    
333
    Configures the SPICE lossless image compression. Valid values are:
334

    
335
    - auto_glz
336
    - auto_lz
337
    - quic
338
    - glz
339
    - lz
340
    - off
341

    
342
spice\_jpeg\_wan\_compression
343
    Valid for the KVM hypervisor.
344

    
345
    Configures how SPICE should use the jpeg algorithm for lossy image
346
    compression on slow links. Valid values are:
347

    
348
    - auto
349
    - never
350
    - always
351

    
352
spice\_zlib\_glz\_wan\_compression
353
    Valid for the KVM hypervisor.
354

    
355
    Configures how SPICE should use the zlib-glz algorithm for lossy image
356
    compression on slow links. Valid values are:
357

    
358
    - auto
359
    - never
360
    - always
361

    
362
spice\_streaming\_video
363
    Valid for the KVM hypervisor.
364

    
365
    Configures how SPICE should detect video streams. Valid values are:
366

    
367
    - off
368
    - all
369
    - filter
370

    
371
spice\_playback\_compression
372
    Valid for the KVM hypervisor.
373

    
374
    Configures whether SPICE should compress audio streams or not.
375

    
376
spice\_use\_tls
377
    Valid for the KVM hypervisor.
378

    
379
    Specifies that the SPICE server must use TLS to encrypt all the
380
    traffic with the client.
381

    
382
spice\_tls\_ciphers
383
    Valid for the KVM hypervisor.
384

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

    
388
spice\_use\_vdagent
389
    Valid for the KVM hypervisor.
390

    
391
    Enables or disables passing mouse events via SPICE vdagent.
392

    
393
cpu\_type
394
    Valid for the KVM hypervisor.
395

    
396
    This parameter determines the emulated cpu for the instance. If this
397
    parameter is empty (which is the default configuration), it will not
398
    be passed to KVM.
399

    
400
    Be aware of setting this parameter to ``"host"`` if you have nodes
401
    with different CPUs from each other. Live migration may stop working
402
    in this situation.
403

    
404
    For more information please refer to the KVM manual.
405

    
406
acpi
407
    Valid for the Xen HVM and KVM hypervisors.
408

    
409
    A boolean option that specifies if the hypervisor should enable
410
    ACPI support for this instance. By default, ACPI is disabled.
411

    
412
pae
413
    Valid for the Xen HVM and KVM hypervisors.
414

    
415
    A boolean option that specifies if the hypervisor should enabled
416
    PAE support for this instance. The default is false, disabling PAE
417
    support.
418

    
419
use\_localtime
420
    Valid for the Xen HVM and KVM hypervisors.
421

    
422
    A boolean option that specifies if the instance should be started
423
    with its clock set to the localtime of the machine (when true) or
424
    to the UTC (When false). The default is false, which is useful for
425
    Linux/Unix machines; for Windows OSes, it is recommended to enable
426
    this parameter.
427

    
428
kernel\_path
429
    Valid for the Xen PVM and KVM hypervisors.
430

    
431
    This option specifies the path (on the node) to the kernel to boot
432
    the instance with. Xen PVM instances always require this, while for
433
    KVM if this option is empty, it will cause the machine to load the
434
    kernel from its disks (and the boot will be done accordingly to
435
    ``boot_order``).
436

    
437
kernel\_args
438
    Valid for the Xen PVM and KVM hypervisors.
439

    
440
    This options specifies extra arguments to the kernel that will be
441
    loaded. device. This is always used for Xen PVM, while for KVM it
442
    is only used if the ``kernel_path`` option is also specified.
443

    
444
    The default setting for this value is simply ``"ro"``, which
445
    mounts the root disk (initially) in read-only one. For example,
446
    setting this to single will cause the instance to start in
447
    single-user mode.
448

    
449
initrd\_path
450
    Valid for the Xen PVM and KVM hypervisors.
451

    
452
    This option specifies the path (on the node) to the initrd to boot
453
    the instance with. Xen PVM instances can use this always, while
454
    for KVM if this option is only used if the ``kernel_path`` option
455
    is also specified. You can pass here either an absolute filename
456
    (the path to the initrd) if you want to use an initrd, or use the
457
    format no\_initrd\_path for no initrd.
458

    
459
root\_path
460
    Valid for the Xen PVM and KVM hypervisors.
461

    
462
    This options specifies the name of the root device. This is always
463
    needed for Xen PVM, while for KVM it is only used if the
464
    ``kernel_path`` option is also specified.
465

    
466
    Please note, that if this setting is an empty string and the
467
    hypervisor is Xen it will not be written to the Xen configuration
468
    file
469

    
470
serial\_console
471
    Valid for the KVM hypervisor.
472

    
473
    This boolean option specifies whether to emulate a serial console
474
    for the instance.
475

    
476
serial\_speed
477
    Valid for the KVM hypervisor.
478

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

    
484
disk\_cache
485
    Valid for the KVM hypervisor.
486

    
487
    The disk cache mode. It can be either default to not pass any
488
    cache option to KVM, or one of the KVM cache modes: none (for
489
    direct I/O), writethrough (to use the host cache but report
490
    completion to the guest only when the host has committed the
491
    changes to disk) or writeback (to use the host cache and report
492
    completion as soon as the data is in the host cache). Note that
493
    there are special considerations for the cache mode depending on
494
    version of KVM used and disk type (always raw file under Ganeti),
495
    please refer to the KVM documentation for more details.
496

    
497
security\_model
498
    Valid for the KVM hypervisor.
499

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

    
504
    Under *user* kvm will drop privileges and become the user
505
    specified by the security\_domain parameter.
506

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

    
511
security\_domain
512
    Valid for the KVM hypervisor.
513

    
514
    Under security model *user* the username to run the instance
515
    under.  It must be a valid username existing on the host.
516

    
517
    Cannot be set under security model *none* or *pool*.
518

    
519
kvm\_flag
520
    Valid for the KVM hypervisor.
521

    
522
    If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
523
    -disable-kvm is passed. If unset no flag is passed, and the
524
    default running mode for your kvm binary will be used.
525

    
526
mem\_path
527
    Valid for the KVM hypervisor.
528

    
529
    This option passes the -mem-path argument to kvm with the path (on
530
    the node) to the mount point of the hugetlbfs file system, along
531
    with the -mem-prealloc argument too.
532

    
533
use\_chroot
534
    Valid for the KVM hypervisor.
535

    
536
    This boolean option determines whether to run the KVM instance in a
537
    chroot directory.
538

    
539
    If it is set to ``true``, an empty directory is created before
540
    starting the instance and its path is passed via the -chroot flag
541
    to kvm. The directory is removed when the instance is stopped.
542

    
543
    It is set to ``false`` by default.
544

    
545
migration\_downtime
546
    Valid for the KVM hypervisor.
547

    
548
    The maximum amount of time (in ms) a KVM instance is allowed to be
549
    frozen during a live migration, in order to copy dirty memory
550
    pages. Default value is 30ms, but you may need to increase this
551
    value for busy instances.
552

    
553
    This option is only effective with kvm versions >= 87 and qemu-kvm
554
    versions >= 0.11.0.
555

    
556
cpu\_mask
557
    Valid for the Xen, KVM and LXC hypervisors.
558

    
559
    The processes belonging to the given instance are only scheduled
560
    on the specified CPUs.
561

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

    
566
    Second, a comma-separated list of CPU IDs or CPU ID ranges. The
567
    ranges are defined by a lower and higher boundary, separated by a
568
    dash, and the boundaries are inclusive. In this form, all VCPUs of
569
    the instance will be mapped on the selected list of CPUs. Example:
570
    ``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs
571
    0, 1, 2 and 5.
572

    
573
    The last form is used for explicit control of VCPU-CPU pinnings. In
574
    this form, the list of VCPU mappings is given as a colon (:)
575
    separated list, whose elements are the possible values for the
576
    second or first form above. In this form, the number of elements in
577
    the colon-separated list _must_ equal the number of VCPUs of the
578
    instance.
579

    
580
    Example:
581

    
582
    .. code-block:: bash
583

    
584
      # Map the entire instance to CPUs 0-2
585
      gnt-instance modify -H cpu_mask=0-2 my-inst
586

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

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

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

    
597
      # Pin entire VM to CPU 0
598
      gnt-instance modify -H cpu_mask=0 my-inst
599

    
600
      # Turn off CPU pinning (default setting)
601
      gnt-instance modify -H cpu_mask=all my-inst
602

    
603
cpu\_cap
604
    Valid for the Xen hypervisor.
605

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

    
609
cpu\_weight
610
    Valid for the Xen hypervisor.
611

    
612
    Set the cpu time ratio to be allocated to the VM. Valid values are
613
    between 1 and 65535. Default weight is 256.
614

    
615
usb\_mouse
616
    Valid for the KVM hypervisor.
617

    
618
    This option specifies the usb mouse type to be used. It can be
619
    "mouse" or "tablet". When using VNC it's recommended to set it to
620
    "tablet".
621

    
622
keymap
623
    Valid for the KVM hypervisor.
624

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

    
628
reboot\_behavior
629
    Valid for Xen PVM, Xen HVM and KVM hypervisors.
630

    
631
    Normally if an instance reboots, the hypervisor will restart it. If
632
    this option is set to ``exit``, the hypervisor will treat a reboot
633
    as a shutdown instead.
634

    
635
    It is set to ``reboot`` by default.
636

    
637
cpu\_cores
638
    Valid for the KVM hypervisor.
639

    
640
    Number of emulated CPU cores.
641

    
642
cpu\_threads
643
    Valid for the KVM hypervisor.
644

    
645
    Number of emulated CPU threads.
646

    
647
cpu\_sockets
648
    Valid for the KVM hypervisor.
649

    
650
    Number of emulated CPU sockets.
651

    
652
soundhw
653
    Valid for the KVM hypervisor.
654

    
655
    Comma separated list of emulated sounds cards, or "all" to enable
656
    all the available ones.
657

    
658

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

    
664
    gnt-instance add -O dhcp=yes ...
665

    
666
The ``-I (--iallocator)`` option specifies the instance allocator plugin
667
to use (``.`` means the default allocator). If you pass in this option
668
the allocator will select nodes for this instance automatically, so you
669
don't need to pass them with the ``-n`` option. For more information
670
please refer to the instance allocator documentation.
671

    
672
The ``-t (--disk-template)`` options specifies the disk layout type
673
for the instance.  The available choices are:
674

    
675
diskless
676
    This creates an instance with no disks. Its useful for testing only
677
    (or other special cases).
678

    
679
file
680
    Disk devices will be regular files.
681

    
682
plain
683
    Disk devices will be logical volumes.
684

    
685
drbd
686
    Disk devices will be drbd (version 8.x) on top of lvm volumes.
687

    
688
rbd
689
    Disk devices will be rbd volumes residing inside a RADOS cluster.
690

    
691

    
692
The optional second value of the ``-n (--node)`` is used for the drbd
693
template type and specifies the remote node.
694

    
695
If you do not want gnt-instance to wait for the disk mirror to be
696
synced, use the ``--no-wait-for-sync`` option.
697

    
698
The ``--file-storage-dir`` specifies the relative path under the
699
cluster-wide file storage directory to store file-based disks. It is
700
useful for having different subdirectories for different
701
instances. The full path of the directory where the disk files are
702
stored will consist of cluster-wide file storage directory + optional
703
subdirectory + instance name. Example:
704
``@RPL_FILE_STORAGE_DIR@/mysubdir/instance1.example.com``. This
705
option is only relevant for instances using the file storage backend.
706

    
707
The ``--file-driver`` specifies the driver to use for file-based
708
disks. Note that currently these drivers work with the xen hypervisor
709
only. This option is only relevant for instances using the file
710
storage backend. The available choices are:
711

    
712
loop
713
    Kernel loopback driver. This driver uses loopback devices to
714
    access the filesystem within the file. However, running I/O
715
    intensive applications in your instance using the loop driver
716
    might result in slowdowns. Furthermore, if you use the loopback
717
    driver consider increasing the maximum amount of loopback devices
718
    (on most systems it's 8) using the max\_loop param.
719

    
720
blktap
721
    The blktap driver (for Xen hypervisors). In order to be able to
722
    use the blktap driver you should check if the 'blktapctrl' user
723
    space disk agent is running (usually automatically started via
724
    xend).  This user-level disk I/O interface has the advantage of
725
    better performance. Especially if you use a network file system
726
    (e.g. NFS) to store your instances this is the recommended choice.
727

    
728
If ``--ignore-ipolicy`` is given any instance policy violations occuring
729
during this operation are ignored.
730

    
731
See **ganeti**\(7) for a description of ``--submit`` and other common
732
options.
733

    
734
Example::
735

    
736
    # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
737
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
738
    # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
739
      -o debian-etch -n node1.example.com instance1.example.com
740
    # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
741
      -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
742
    # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
743
      -n node1.example.com:node2.example.com instance2.example.com
744

    
745

    
746
BATCH-CREATE
747
^^^^^^^^^^^^
748

    
749
**batch-create** {instances\_file.json}
750

    
751
This command (similar to the Ganeti 1.2 **batcher** tool) submits
752
multiple instance creation jobs based on a definition file. The
753
instance configurations do not encompass all the possible options for
754
the **add** command, but only a subset.
755

    
756
The instance file should be a valid-formed JSON file, containing a
757
dictionary with instance name and instance parameters. The accepted
758
parameters are:
759

    
760
disk\_size
761
    The size of the disks of the instance.
762

    
763
disk\_template
764
    The disk template to use for the instance, the same as in the
765
    **add** command.
766

    
767
backend
768
    A dictionary of backend parameters.
769

    
770
hypervisor
771
    A dictionary with a single key (the hypervisor name), and as value
772
    the hypervisor options. If not passed, the default hypervisor and
773
    hypervisor options will be inherited.
774

    
775
mac, ip, mode, link
776
    Specifications for the one NIC that will be created for the
777
    instance. 'bridge' is also accepted as a backwards compatible
778
    key.
779

    
780
nics
781
    List of nics that will be created for the instance. Each entry
782
    should be a dict, with mac, ip, mode and link as possible keys.
783
    Please don't provide the "mac, ip, mode, link" parent keys if you
784
    use this method for specifying nics.
785

    
786
primary\_node, secondary\_node
787
    The primary and optionally the secondary node to use for the
788
    instance (in case an iallocator script is not used).
789

    
790
iallocator
791
    Instead of specifying the nodes, an iallocator script can be used
792
    to automatically compute them.
793

    
794
start
795
    whether to start the instance
796

    
797
ip\_check
798
    Skip the check for already-in-use instance; see the description in
799
    the **add** command for details.
800

    
801
name\_check
802
    Skip the name check for instances; see the description in the
803
    **add** command for details.
804

    
805
file\_storage\_dir, file\_driver
806
    Configuration for the file disk type, see the **add** command for
807
    details.
808

    
809

    
810
A simple definition for one instance can be (with most of the
811
parameters taken from the cluster defaults)::
812

    
813
    {
814
      "instance3": {
815
        "template": "drbd",
816
        "os": "debootstrap",
817
        "disk_size": ["25G"],
818
        "iallocator": "dumb"
819
      },
820
      "instance5": {
821
        "template": "drbd",
822
        "os": "debootstrap",
823
        "disk_size": ["25G"],
824
        "iallocator": "dumb",
825
        "hypervisor": "xen-hvm",
826
        "hvparams": {"acpi": true},
827
        "backend": {"maxmem": 512, "minmem": 256}
828
      }
829
    }
830

    
831
The command will display the job id for each submitted instance, as
832
follows::
833

    
834
    # gnt-instance batch-create instances.json
835
    instance3: 11224
836
    instance5: 11225
837

    
838
REMOVE
839
^^^^^^
840

    
841
**remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
842
[\--force] {*instance*}
843

    
844
Remove an instance. This will remove all data from the instance and
845
there is *no way back*. If you are not sure if you use an instance
846
again, use **shutdown** first and leave it in the shutdown state for a
847
while.
848

    
849
The ``--ignore-failures`` option will cause the removal to proceed
850
even in the presence of errors during the removal of the instance
851
(e.g. during the shutdown or the disk removal). If this option is not
852
given, the command will stop at the first error.
853

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

    
859
The ``--force`` option is used to skip the interactive confirmation.
860

    
861
See **ganeti**\(7) for a description of ``--submit`` and other common
862
options.
863

    
864
Example::
865

    
866
    # gnt-instance remove instance1.example.com
867

    
868

    
869
LIST
870
^^^^
871

    
872
| **list**
873
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
874
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
875

    
876
Shows the currently configured instances with memory usage, disk
877
usage, the node they are running on, and their run status.
878

    
879
The ``--no-headers`` option will skip the initial header line. The
880
``--separator`` option takes an argument which denotes what will be
881
used between the output fields. Both these options are to help
882
scripting.
883

    
884
The units used to display the numeric values in the output varies,
885
depending on the options given. By default, the values will be
886
formatted in the most appropriate unit. If the ``--separator`` option
887
is given, then the values are shown in mebibytes to allow parsing by
888
scripts. In both cases, the ``--units`` option can be used to enforce
889
a given output unit.
890

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

    
894
The ``-o (--output)`` option takes a comma-separated list of output
895
fields. The available fields and their meaning are:
896

    
897
@QUERY_FIELDS_INSTANCE@
898

    
899
If the value of the option starts with the character ``+``, the new
900
field(s) will be added to the default list. This allows one to quickly
901
see the default list plus a few other fields, instead of retyping the
902
entire list of fields.
903

    
904
There is a subtle grouping about the available output fields: all
905
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
906
``status`` are configuration value and not run-time values. So if you
907
don't select any of the these fields, the query will be satisfied
908
instantly from the cluster configuration, without having to ask the
909
remote nodes for the data. This can be helpful for big clusters when
910
you only want some data and it makes sense to specify a reduced set of
911
output fields.
912

    
913
If exactly one argument is given and it appears to be a query filter
914
(see **ganeti**\(7)), the query result is filtered accordingly. For
915
ambiguous cases (e.g. a single field name as a filter) the ``--filter``
916
(``-F``) option forces the argument to be treated as a filter (e.g.
917
``gnt-instance list -F admin_state``).
918

    
919
The default output field list is: ``name``, ``os``, ``pnode``,
920
``admin_state``, ``oper_state``, ``oper_ram``.
921

    
922

    
923
LIST-FIELDS
924
^^^^^^^^^^^
925

    
926
**list-fields** [field...]
927

    
928
Lists available fields for instances.
929

    
930

    
931
INFO
932
^^^^
933

    
934
**info** [-s \| \--static] [\--roman] {\--all \| *instance*}
935

    
936
Show detailed information about the given instance(s). This is
937
different from **list** as it shows detailed data about the instance's
938
disks (especially useful for the drbd disk template).
939

    
940
If the option ``-s`` is used, only information available in the
941
configuration file is returned, without querying nodes, making the
942
operation faster.
943

    
944
Use the ``--all`` to get info about all instances, rather than
945
explicitly passing the ones you're interested in.
946

    
947
The ``--roman`` option can be used to cause envy among people who like
948
ancient cultures, but are stuck with non-latin-friendly cluster
949
virtualization technologies.
950

    
951
MODIFY
952
^^^^^^
953

    
954
| **modify**
955
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
956
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
957
| [{-m|\--runtime-memory} *SIZE*]
958
| [\--net add*[:options]* \| \--net [*N*:]remove \| \--net *N:options*]
959
| [\--disk add:size=*SIZE*[,vg=*VG*][,metavg=*VG*] \| \--disk [*N*:]remove \|
960
|  \--disk *N*:mode=*MODE*]
961
| [{-t|\--disk-template} plain | {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
962
| [\--os-type=*OS* [\--force-variant]]
963
| [{-O|\--os-parameters} *param*=*value*... ]
964
| [\--offline \| \--online]
965
| [\--submit]
966
| [\--ignore-ipolicy]
967
| {*instance*}
968

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

    
974
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
975
and ``-O (--os-parameters)`` options specifies hypervisor, backend and
976
OS parameter options in the form of name=value[,...]. For details
977
which options can be specified, see the **add** command.
978

    
979
The ``-t (--disk-template)`` option will change the disk template of
980
the instance.  Currently only conversions between the plain and drbd
981
disk templates are supported, and the instance must be stopped before
982
attempting the conversion. When changing from the plain to the drbd
983
disk template, a new secondary node must be specified via the ``-n``
984
option. The option ``--no-wait-for-sync`` can be used when converting
985
to the ``drbd`` template in order to make the instance available for
986
startup before DRBD has finished resyncing.
987

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

    
992
The ``--disk add:size=``*SIZE* option adds a disk to the instance. The
993
optional ``vg=``*VG* option specifies an LVM volume group other than
994
the default volume group to create the disk on. For DRBD disks, the
995
``metavg=``*VG* option specifies the volume group for the metadata
996
device. ``--disk`` *N*``:add,size=``**SIZE** can be used to add a
997
disk at a specific index. The ``--disk remove`` option will remove the
998
last disk of the instance. Use ``--disk `` *N*``:remove`` to remove a
999
disk by its index. The ``--disk`` *N*``:mode=``*MODE* option will change
1000
the mode of the Nth disk of the instance between read-only (``ro``) and
1001
read-write (``rw``).
1002

    
1003
The ``--net add:``*options* and ``--net`` *N*``:add,``*options* option
1004
will add a new network interface to the instance. The available options
1005
are the same as in the **add** command (``mac``, ``ip``, ``link``,
1006
``mode``). The ``--net remove`` will remove the last network interface
1007
of the instance (``--net`` *N*``:remove`` for a specific index), while
1008
the ``--net`` *N*``:``*options* option will change the parameters of the Nth
1009
instance network interface.
1010

    
1011
The option ``-o (--os-type)`` will change the OS name for the instance
1012
(without reinstallation). In case an OS variant is specified that is
1013
not found, then by default the modification is refused, unless
1014
``--force-variant`` is passed. An invalid OS will also be refused,
1015
unless the ``--force`` option is given.
1016

    
1017
The ``--online`` and ``--offline`` options are used to transition an
1018
instance into and out of the ``offline`` state. An instance can be
1019
turned offline only if it was previously down. The ``--online`` option
1020
fails if the instance was not in the ``offline`` state, otherwise it
1021
changes instance's state to ``down``. These modifications take effect
1022
immediately.
1023

    
1024
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1025
during this operation are ignored.
1026

    
1027
See **ganeti**\(7) for a description of ``--submit`` and other common
1028
options.
1029

    
1030
Most of the changes take effect at the next restart. If the instance is
1031
running, there is no effect on the instance.
1032

    
1033
REINSTALL
1034
^^^^^^^^^
1035

    
1036
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
1037
| [\--force-multiple]
1038
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1039
| [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] {*instance*...}
1040

    
1041
Reinstalls the operating system on the given instance(s). The
1042
instance(s) must be stopped when running this command. If the ``-o
1043
(--os-type)`` is specified, the operating system is changed.
1044

    
1045
The ``--select-os`` option switches to an interactive OS reinstall.
1046
The user is prompted to select the OS template from the list of
1047
available OS templates. OS parameters can be overridden using ``-O
1048
(--os-parameters)`` (more documentation for this option under the
1049
**add** command).
1050

    
1051
Since this is a potentially dangerous command, the user will be
1052
required to confirm this action, unless the ``-f`` flag is passed.
1053
When multiple instances are selected (either by passing multiple
1054
arguments or by using the ``--node``, ``--primary``, ``--secondary``
1055
or ``--all`` options), the user must pass the ``--force-multiple``
1056
options to skip the interactive confirmation.
1057

    
1058
See **ganeti**\(7) for a description of ``--submit`` and other common
1059
options.
1060

    
1061
RENAME
1062
^^^^^^
1063

    
1064
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit]
1065
| {*instance*} {*new\_name*}
1066

    
1067
Renames the given instance. The instance must be stopped when running
1068
this command. The requirements for the new name are the same as for
1069
adding an instance: the new name must be resolvable and the IP it
1070
resolves to must not be reachable (in order to prevent duplicate IPs
1071
the next time the instance is started). The IP test can be skipped if
1072
the ``--no-ip-check`` option is passed.
1073

    
1074
Note that you can rename an instance to its same name, to force
1075
re-executing the os-specific rename script for that instance, if
1076
needed.
1077

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

    
1084
See **ganeti**\(7) for a description of ``--submit`` and other common
1085
options.
1086

    
1087
Starting/stopping/connecting to console
1088
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1089

    
1090
STARTUP
1091
^^^^^^^
1092

    
1093
| **startup**
1094
| [\--force] [\--ignore-offline]
1095
| [\--force-multiple] [\--no-remember]
1096
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1097
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1098
| [{-H|\--hypervisor-parameters} ``key=value...``]
1099
| [{-B|\--backend-parameters} ``key=value...``]
1100
| [\--submit] [\--paused]
1101
| {*name*...}
1102

    
1103
Starts one or more instances, depending on the following options.  The
1104
four available modes are:
1105

    
1106
\--instance
1107
    will start the instances given as arguments (at least one argument
1108
    required); this is the default selection
1109

    
1110
\--node
1111
    will start the instances who have the given node as either primary
1112
    or secondary
1113

    
1114
\--primary
1115
    will start all instances whose primary node is in the list of nodes
1116
    passed as arguments (at least one node required)
1117

    
1118
\--secondary
1119
    will start all instances whose secondary node is in the list of
1120
    nodes passed as arguments (at least one node required)
1121

    
1122
\--all
1123
    will start all instances in the cluster (no arguments accepted)
1124

    
1125
\--tags
1126
    will start all instances in the cluster with the tags given as
1127
    arguments
1128

    
1129
\--node-tags
1130
    will start all instances in the cluster on nodes with the tags
1131
    given as arguments
1132

    
1133
\--pri-node-tags
1134
    will start all instances in the cluster on primary nodes with the
1135
    tags given as arguments
1136

    
1137
\--sec-node-tags
1138
    will start all instances in the cluster on secondary nodes with the
1139
    tags given as arguments
1140

    
1141
Note that although you can pass more than one selection option, the
1142
last one wins, so in order to guarantee the desired result, don't pass
1143
more than one such option.
1144

    
1145
Use ``--force`` to start even if secondary disks are failing.
1146
``--ignore-offline`` can be used to ignore offline primary nodes and
1147
mark the instance as started even if the primary is not available.
1148

    
1149
The ``--force-multiple`` will skip the interactive confirmation in the
1150
case the more than one instance will be affected.
1151

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

    
1158
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
1159
options specify temporary hypervisor and backend parameters that can
1160
be used to start an instance with modified parameters. They can be
1161
useful for quick testing without having to modify an instance back and
1162
forth, e.g.::
1163

    
1164
    # gnt-instance start -H kernel_args="single" instance1
1165
    # gnt-instance start -B maxmem=2048 instance2
1166

    
1167

    
1168
The first form will start the instance instance1 in single-user mode,
1169
and the instance instance2 with 2GB of RAM (this time only, unless
1170
that is the actual instance memory size already). Note that the values
1171
override the instance parameters (and not extend them): an instance
1172
with "kernel\_args=ro" when started with -H kernel\_args=single will
1173
result in "single", not "ro single".
1174

    
1175
The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
1176
pauses the instance at the start of bootup, awaiting ``gnt-instance
1177
console`` to unpause it, allowing the entire boot process to be
1178
monitored for debugging.
1179

    
1180
See **ganeti**\(7) for a description of ``--submit`` and other common
1181
options.
1182

    
1183
Example::
1184

    
1185
    # gnt-instance start instance1.example.com
1186
    # gnt-instance start --node node1.example.com node2.example.com
1187
    # gnt-instance start --all
1188

    
1189

    
1190
SHUTDOWN
1191
^^^^^^^^
1192

    
1193
| **shutdown**
1194
| [\--timeout=*N*]
1195
| [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember]
1196
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1197
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1198
| [\--submit]
1199
| {*name*...}
1200

    
1201
Stops one or more instances. If the instance cannot be cleanly stopped
1202
during a hardcoded interval (currently 2 minutes), it will forcibly
1203
stop the instance (equivalent to switching off the power on a physical
1204
machine).
1205

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

    
1211
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1212
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1213
``--sec-node-tags`` options are similar as for the **startup** command
1214
and they influence the actual instances being shutdown.
1215

    
1216
``--ignore-offline`` can be used to ignore offline primary nodes and
1217
force the instance to be marked as stopped. This option should be used
1218
with care as it can lead to an inconsistent cluster state.
1219

    
1220
Use ``--force`` to be able to shutdown an instance even when it's marked
1221
as offline. This is useful is an offline instance ends up in the
1222
``ERROR_up`` state, for example.
1223

    
1224
The ``--no-remember`` option will perform the shutdown but not change
1225
the state of the instance in the configuration file (if it was running
1226
before, Ganeti will still thinks it needs to be running). This can be
1227
useful for a cluster-wide shutdown, where some instances are marked as
1228
up and some as down, and you don't want to change the running state:
1229
you just need to disable the watcher, shutdown all instances with
1230
``--no-remember``, and when the watcher is activated again it will
1231
restore the correct runtime state for all instances.
1232

    
1233
See **ganeti**\(7) for a description of ``--submit`` and other common
1234
options.
1235

    
1236
Example::
1237

    
1238
    # gnt-instance shutdown instance1.example.com
1239
    # gnt-instance shutdown --all
1240

    
1241

    
1242
REBOOT
1243
^^^^^^
1244

    
1245
| **reboot**
1246
| [{-t|\--type} *REBOOT-TYPE*]
1247
| [\--ignore-secondaries]
1248
| [\--shutdown-timeout=*N*]
1249
| [\--force-multiple]
1250
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1251
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1252
| [\--submit]
1253
| [*name*...]
1254

    
1255
Reboots one or more instances. The type of reboot depends on the value
1256
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1257
does a instance stop, recreates the hypervisor config for the instance
1258
and starts the instance. A full reboot does the equivalent of
1259
**gnt-instance shutdown && gnt-instance startup**.  The default is
1260
hard reboot.
1261

    
1262
For the hard reboot the option ``--ignore-secondaries`` ignores errors
1263
for the secondary node while re-assembling the instance disks.
1264

    
1265
The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1266
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1267
``--sec-node-tags`` options are similar as for the **startup** command
1268
and they influence the actual instances being rebooted.
1269

    
1270
The ``--shutdown-timeout`` is used to specify how much time to wait
1271
before forcing the shutdown (xm destroy in xen, killing the kvm
1272
process, for kvm). By default two minutes are given to each instance
1273
to stop.
1274

    
1275
The ``--force-multiple`` will skip the interactive confirmation in the
1276
case the more than one instance will be affected.
1277

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

    
1281
Example::
1282

    
1283
    # gnt-instance reboot instance1.example.com
1284
    # gnt-instance reboot --type=full instance1.example.com
1285

    
1286

    
1287
CONSOLE
1288
^^^^^^^
1289

    
1290
**console** [\--show-cmd] {*instance*}
1291

    
1292
Connects to the console of the given instance. If the instance is not
1293
up, an error is returned. Use the ``--show-cmd`` option to display the
1294
command instead of executing it.
1295

    
1296
For HVM instances, this will attempt to connect to the serial console
1297
of the instance. To connect to the virtualized "physical" console of a
1298
HVM instance, use a VNC client with the connection info from the
1299
**info** command.
1300

    
1301
For Xen/kvm instances, if the instance is paused, this attempts to
1302
unpause the instance after waiting a few seconds for the connection to
1303
the console to be made.
1304

    
1305
Example::
1306

    
1307
    # gnt-instance console instance1.example.com
1308

    
1309

    
1310
Disk management
1311
~~~~~~~~~~~~~~~
1312

    
1313
REPLACE-DISKS
1314
^^^^^^^^^^^^^
1315

    
1316
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-p}
1317
[\--disks *idx*] {*instance*}
1318

    
1319
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {-s}
1320
[\--disks *idx*] {*instance*}
1321

    
1322
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1323
{{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*}
1324

    
1325
**replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy]
1326
{-a\|\--auto} {*instance*}
1327

    
1328
This command is a generalized form for replacing disks. It is
1329
currently only valid for the mirrored (DRBD) disk template.
1330

    
1331
The first form (when passing the ``-p`` option) will replace the disks
1332
on the primary, while the second form (when passing the ``-s`` option
1333
will replace the disks on the secondary node. For these two cases (as
1334
the node doesn't change), it is possible to only run the replace for a
1335
subset of the disks, using the option ``--disks`` which takes a list
1336
of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only
1337
the first and third disks.
1338

    
1339
The third form (when passing either the ``--iallocator`` or the
1340
``--new-secondary`` option) is designed to change secondary node of the
1341
instance. Specifying ``--iallocator`` makes the new secondary be
1342
selected automatically by the specified allocator plugin (use ``.`` to
1343
indicate the default allocator), otherwise the new secondary node will
1344
be the one chosen manually via the ``--new-secondary`` option.
1345

    
1346
Note that it is not possible to select an offline or drained node as a
1347
new secondary.
1348

    
1349
The fourth form (when using ``--auto``) will automatically determine
1350
which disks of an instance are faulty and replace them within the same
1351
node. The ``--auto`` option works only when an instance has only
1352
faulty disks on either the primary or secondary node; it doesn't work
1353
when both sides have faulty disks.
1354

    
1355
The ``--early-release`` changes the code so that the old storage on
1356
secondary node(s) is removed early (before the resync is completed)
1357
and the internal Ganeti locks for the current (and new, if any)
1358
secondary node are also released, thus allowing more parallelism in
1359
the cluster operation. This should be used only when recovering from a
1360
disk failure on the current secondary (thus the old storage is already
1361
broken) or when the storage on the primary node is known to be fine
1362
(thus we won't need the old storage for potential recovery).
1363

    
1364
The ``--ignore-ipolicy`` let the command ignore instance policy
1365
violations if replace-disks changes groups and the instance would
1366
violate the new groups instance policy.
1367

    
1368
See **ganeti**\(7) for a description of ``--submit`` and other common
1369
options.
1370

    
1371
ACTIVATE-DISKS
1372
^^^^^^^^^^^^^^
1373

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

    
1376
Activates the block devices of the given instance. If successful, the
1377
command will show the location and name of the block devices::
1378

    
1379
    node1.example.com:disk/0:/dev/drbd0
1380
    node1.example.com:disk/1:/dev/drbd1
1381

    
1382

    
1383
In this example, *node1.example.com* is the name of the node on which
1384
the devices have been activated. The *disk/0* and *disk/1* are the
1385
Ganeti-names of the instance disks; how they are visible inside the
1386
instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the
1387
actual block devices as visible on the node.
1388

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

    
1396
The ``--wait-for-sync`` option will ensure that the command returns only
1397
after the instance's disks are synchronised (mostly for DRBD); this can
1398
be useful to ensure consistency, as otherwise there are no commands that
1399
can wait until synchronisation is done. However when passing this
1400
option, the command will have additional output, making it harder to
1401
parse the disk information.
1402

    
1403
Note that it is safe to run this command while the instance is already
1404
running.
1405

    
1406
See **ganeti**\(7) for a description of ``--submit`` and other common
1407
options.
1408

    
1409
DEACTIVATE-DISKS
1410
^^^^^^^^^^^^^^^^
1411

    
1412
**deactivate-disks** [-f] [\--submit] {*instance*}
1413

    
1414
De-activates the block devices of the given instance. Note that if you
1415
run this command for an instance with a drbd disk template, while it
1416
is running, it will not be able to shutdown the block devices on the
1417
primary node, but it will shutdown the block devices on the secondary
1418
nodes, thus breaking the replication.
1419

    
1420
The ``-f``/``--force`` option will skip checks that the instance is
1421
down; in case the hypervisor is confused and we can't talk to it,
1422
normally Ganeti will refuse to deactivate the disks, but with this
1423
option passed it will skip this check and directly try to deactivate
1424
the disks. This can still fail due to the instance actually running or
1425
other issues.
1426

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

    
1430
GROW-DISK
1431
^^^^^^^^^
1432

    
1433
| **grow-disk** [\--no-wait-for-sync] [\--submit] [\--absolute]
1434
| {*instance*} {*disk*} {*amount*}
1435

    
1436
Grows an instance's disk. This is only possible for instances having a
1437
plain, drbd, file, sharedfile or rbd disk template.
1438

    
1439
Note that this command only change the block device size; it will not
1440
grow the actual filesystems, partitions, etc. that live on that
1441
disk. Usually, you will need to:
1442

    
1443
#. use **gnt-instance grow-disk**
1444

    
1445
#. reboot the instance (later, at a convenient time)
1446

    
1447
#. use a filesystem resizer, such as **ext2online**\(8) or
1448
   **xfs\_growfs**\(8) to resize the filesystem, or use **fdisk**\(8) to
1449
   change the partition table on the disk
1450

    
1451
The *disk* argument is the index of the instance disk to grow. The
1452
*amount* argument is given as a number which can have a suffix (like the
1453
disk size in instance create); if the suffix is missing, the value will
1454
be interpreted as mebibytes.
1455

    
1456
By default, the *amount* value represents the desired increase in the
1457
disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If
1458
the optional ``--absolute`` parameter is passed, then the *amount*
1459
argument doesn't represent the delta, but instead the desired final disk
1460
size (e.g. an amount of 8G will take a disk of size 4G to 8G).
1461

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

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

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

    
1473
Example (increase the first disk for instance1 by 16GiB)::
1474

    
1475
    # gnt-instance grow-disk instance1.example.com 0 16g
1476

    
1477
Example for increasing the disk size to a certain size::
1478

    
1479
   # gnt-instance grow-disk --absolute instance1.example.com 0 32g
1480

    
1481
Also note that disk shrinking is not supported; use **gnt-backup
1482
export** and then **gnt-backup import** to reduce the disk size of an
1483
instance.
1484

    
1485
RECREATE-DISKS
1486
^^^^^^^^^^^^^^
1487

    
1488
| **recreate-disks** [\--submit]
1489
| [{-n node1:[node2] \| {-I\|\--iallocator *name*}}]
1490
| [\--disk=*N*[:[size=*VAL*][,mode=*ro\|rw*]]] {*instance*}
1491

    
1492
Recreates all or a subset of disks of the given instance.
1493

    
1494
Note that this functionality should only be used for missing disks; if
1495
any of the given disks already exists, the operation will fail.  While
1496
this is suboptimal, recreate-disks should hopefully not be needed in
1497
normal operation and as such the impact of this is low.
1498

    
1499
If only a subset should be recreated, any number of ``disk`` options can
1500
be specified. It expects a disk index and an optional list of disk
1501
parameters to change. Only ``size`` and ``mode`` can be changed while
1502
recreating disks. To recreate all disks while changing parameters on
1503
a subset only, a ``--disk`` option must be given for every disk of the
1504
instance.
1505

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

    
1515
Another method of choosing which nodes to place the instance on is by
1516
using the specified iallocator, passing the ``--iallocator`` option.
1517
The primary and secondary nodes will be chosen by the specified
1518
iallocator plugin, or by the default allocator if ``.`` is specified.
1519

    
1520
See **ganeti**\(7) for a description of ``--submit`` and other common
1521
options.
1522

    
1523
Recovery/moving
1524
~~~~~~~~~~~~~~~
1525

    
1526
FAILOVER
1527
^^^^^^^^
1528

    
1529
| **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy]
1530
| [\--shutdown-timeout=*N*]
1531
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*]
1532
| [\--submit]
1533
| {*instance*}
1534

    
1535
Failover will stop the instance (if running), change its primary node,
1536
and if it was originally running it will start it again (on the new
1537
primary). This only works for instances with drbd template (in which
1538
case you can only fail to the secondary node) and for externally
1539
mirrored templates (blockdev and rbd) (which can change to any other
1540
node).
1541

    
1542
If the instance's disk template is of type blockdev or rbd, then you
1543
can explicitly specify the target node (which can be any node) using
1544
the ``-n`` or ``--target-node`` option, or specify an iallocator plugin
1545
using the ``-I`` or ``--iallocator`` option. If you omit both, the default
1546
iallocator will be used to specify the target node.
1547

    
1548
Normally the failover will check the consistency of the disks before
1549
failing over the instance. If you are trying to migrate instances off
1550
a dead node, this will fail. Use the ``--ignore-consistency`` option
1551
for this purpose. Note that this option can be dangerous as errors in
1552
shutting down the instance will be ignored, resulting in possibly
1553
having the instance running on two machines in parallel (on
1554
disconnected DRBD drives).
1555

    
1556
The ``--shutdown-timeout`` is used to specify how much time to wait
1557
before forcing the shutdown (xm destroy in xen, killing the kvm
1558
process, for kvm). By default two minutes are given to each instance
1559
to stop.
1560

    
1561
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1562
during this operation are ignored.
1563

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

    
1567
Example::
1568

    
1569
    # gnt-instance failover instance1.example.com
1570

    
1571

    
1572
MIGRATE
1573
^^^^^^^
1574

    
1575
| **migrate** [-f] [\--allow-failover] [\--non-live]
1576
| [\--migration-mode=live\|non-live] [\--ignore-ipolicy]
1577
| [\--no-runtime-changes] [\--submit]
1578
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*}
1579

    
1580
| **migrate** [-f] \--cleanup [\--submit] {*instance*}
1581

    
1582
Migrate will move the instance to its secondary node without shutdown.
1583
As with failover, it only works for instances having the drbd disk
1584
template or an externally mirrored disk template type such as blockdev
1585
or rbd.
1586

    
1587
If the instance's disk template is of type blockdev or rbd, then you can
1588
explicitly specify the target node (which can be any node) using the
1589
``-n`` or ``--target-node`` option, or specify an iallocator plugin
1590
using the ``-I`` or ``--iallocator`` option. If you omit both, the
1591
default iallocator will be used to specify the target node.
1592
Alternatively, the default iallocator can be requested by specifying
1593
``.`` as the name of the plugin.
1594

    
1595
The migration command needs a perfectly healthy instance, as we rely
1596
on the dual-master capability of drbd8 and the disks of the instance
1597
are not allowed to be degraded.
1598

    
1599
The ``--non-live`` and ``--migration-mode=non-live`` options will
1600
switch (for the hypervisors that support it) between a "fully live"
1601
(i.e. the interruption is as minimal as possible) migration and one in
1602
which the instance is frozen, its state saved and transported to the
1603
remote node, and then resumed there. This all depends on the
1604
hypervisor support for two different methods. In any case, it is not
1605
an error to pass this parameter (it will just be ignored if the
1606
hypervisor doesn't support it). The option ``--migration-mode=live``
1607
option will request a fully-live migration. The default, when neither
1608
option is passed, depends on the hypervisor parameters (and can be
1609
viewed with the **gnt-cluster info** command).
1610

    
1611
If the ``--cleanup`` option is passed, the operation changes from
1612
migration to attempting recovery from a failed previous migration.  In
1613
this mode, Ganeti checks if the instance runs on the correct node (and
1614
updates its configuration if not) and ensures the instances' disks
1615
are configured correctly. In this mode, the ``--non-live`` option is
1616
ignored.
1617

    
1618
The option ``-f`` will skip the prompting for confirmation.
1619

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

    
1625
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1626
during this operation are ignored.
1627

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

    
1632
If an instance has the backend parameter ``always_failover`` set to
1633
true, then the migration is automatically converted into a failover.
1634

    
1635
See **ganeti**\(7) for a description of ``--submit`` and other common
1636
options.
1637

    
1638
Example (and expected output)::
1639

    
1640
    # gnt-instance migrate instance1
1641
    Instance instance1 will be migrated. Note that migration
1642
    might impact the instance if anything goes wrong (e.g. due to bugs in
1643
    the hypervisor). Continue?
1644
    y/[n]/?: y
1645
    Migrating instance instance1.example.com
1646
    * checking disk consistency between source and target
1647
    * switching node node2.example.com to secondary mode
1648
    * changing into standalone mode
1649
    * changing disks into dual-master mode
1650
    * wait until resync is done
1651
    * preparing node2.example.com to accept the instance
1652
    * migrating instance to node2.example.com
1653
    * switching node node1.example.com to secondary mode
1654
    * wait until resync is done
1655
    * changing into standalone mode
1656
    * changing disks into single-master mode
1657
    * wait until resync is done
1658
    * done
1659
    #
1660

    
1661

    
1662
MOVE
1663
^^^^
1664

    
1665
| **move** [-f] [\--ignore-consistency]
1666
| [-n *node*] [\--shutdown-timeout=*N*] [\--submit] [\--ignore-ipolicy]
1667
| {*instance*}
1668

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

    
1672
Note that since this operation is done via data copy, it will take a
1673
long time for big disks (similar to replace-disks for a drbd
1674
instance).
1675

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

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

    
1685
If ``--ignore-ipolicy`` is given any instance policy violations occuring
1686
during this operation are ignored.
1687

    
1688
See **ganeti**\(7) for a description of ``--submit`` and other common
1689
options.
1690

    
1691
Example::
1692

    
1693
    # gnt-instance move -n node3.example.com instance1.example.com
1694

    
1695

    
1696
CHANGE-GROUP
1697
^^^^^^^^^^^^
1698

    
1699
| **change-group** [\--submit]
1700
| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
1701

    
1702
This command moves an instance to another node group. The move is
1703
calculated by an iallocator, either given on the command line or as a
1704
cluster default.
1705

    
1706
If no specific destination groups are specified using ``--to``, all
1707
groups except the one containing the instance are considered.
1708

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

    
1712
Example::
1713

    
1714
    # gnt-instance change-group -I hail --to rack2 inst1.example.com
1715

    
1716

    
1717
Tags
1718
~~~~
1719

    
1720
ADD-TAGS
1721
^^^^^^^^
1722

    
1723
**add-tags** [\--from *file*] {*instancename*} {*tag*...}
1724

    
1725
Add tags to the given instance. If any of the tags contains invalid
1726
characters, the entire operation will abort.
1727

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

    
1734
LIST-TAGS
1735
^^^^^^^^^
1736

    
1737
**list-tags** {*instancename*}
1738

    
1739
List the tags of the given instance.
1740

    
1741
REMOVE-TAGS
1742
^^^^^^^^^^^
1743

    
1744
**remove-tags** [\--from *file*] {*instancename*} {*tag*...}
1745

    
1746
Remove tags from the given instance. If any of the tags are not
1747
existing on the node, the entire operation will abort.
1748

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

    
1755
.. vim: set textwidth=72 :
1756
.. Local Variables:
1757
.. mode: rst
1758
.. fill-column: 72
1759
.. End: