gnt-instance.rst 74.2 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
gnt-instance(8) Ganeti | Version @GANETI_VERSION@
=================================================

Name
----

gnt-instance - Ganeti instance administration

Synopsis
--------

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

DESCRIPTION
-----------

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

COMMANDS
--------

Creation/removal/querying
~~~~~~~~~~~~~~~~~~~~~~~~~

ADD
^^^

| **add**
30
| {-t|\--disk-template {diskless \| file \| plain \| drbd \| rbd}}
31
| {\--disk=*N*: {size=*VAL*[,spindles=*VAL*] \| adopt=*LV*}[,options...]
32
|  \| {size=*VAL*,provider=*PROVIDER*}[,param=*value*... ][,options...]
Iustin Pop's avatar
Iustin Pop committed
33
|  \| {-s|\--os-size} *SIZE*}
34
35
| [\--no-ip-check] [\--no-name-check] [\--no-conflicts-check]
| [\--no-start] [\--no-install]
Iustin Pop's avatar
Iustin Pop committed
36
37
38
39
| [\--net=*N* [:options...] \| \--no-nics]
| [{-B|\--backend-parameters} *BEPARAMS*]
| [{-H|\--hypervisor-parameters} *HYPERVISOR* [: option=*value*... ]]
| [{-O|\--os-parameters} *param*=*value*... ]
40
| [\--file-storage-dir *dir\_path*] [\--file-driver {loop \| blktap \| blktap2}]
Iustin Pop's avatar
Iustin Pop committed
41
42
| {{-n|\--node} *node[:secondary-node]* \| {-I|\--iallocator} *name*}
| {{-o|\--os-type} *os-type*}
43
| [\--submit] [\--print-job-id]
Iustin Pop's avatar
Iustin Pop committed
44
| [\--ignore-ipolicy]
45
| [\--no-wait-for-sync]
46
47
48
49
50
51
52
53
54
| {*instance*}

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

The ``disk`` option specifies the parameters for the disks of the
instance. The numbering of disks starts at zero, and at least one disk
needs to be passed. For each disk, either the size or the adoption
55
source needs to be given. The size is interpreted (when no unit is
56
57
given) in mebibytes. You can also use one of the suffixes *m*, *g* or
*t* to specify the exact the units used; these suffixes map to
58
59
60
mebibytes, gibibytes and tebibytes. Each disk can also take these
parameters (all optional):

61
62
63
spindles
  How many spindles (physical disks on the node) the disk should span.

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

name
69
   This option specifies a name for the disk, which can be used as a disk
70
71
72
73
74
75
76
   identifier. An instance can not have two disks with the same name.

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

metavg
   This options specifies a different VG for the metadata device. This
77
78
79
   works only for DRBD devices. If not specified, the default metavg
   of the node-group (possibly inherited from the cluster-wide settings)
   will be used.
80
81
82
83
84
85

When creating ExtStorage disks, also arbitrary parameters can be passed,
to the ExtStorage provider. Those parameters are passed as additional
comma separated options. Therefore, an ExtStorage disk provided by
provider ``pvdr1`` with parameters ``param1``, ``param2`` would be
passed as ``--disk 0:size=10G,provider=pvdr1,param1=val1,param2=val2``.
86
87
88
89
90
91

When using the ``adopt`` key in the disk definition, Ganeti will
reuse those volumes (instead of creating new ones) as the
instance's disks. Ganeti will rename these volumes to the standard
format, and (without installing the OS) will use them as-is for the
instance. This allows migrating instances from non-managed mode
92
(e.g. plain KVM with LVM) to being managed via Ganeti. Please note that
93
94
95
96
97
98
99
100
101
102
103
104
this works only for the \`plain' disk template (see below for
template details).

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

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

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

109
110
111
112
113
114
115
116
117
The ``--no-ip-check`` skips the checks that are done to see if the
instance's IP is not already alive (i.e. reachable from the master
node).

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

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

The NICs of the instances can be specified via the ``--net``
option. By default, one NIC is created for the instance, with a
Lisa Velden's avatar
Lisa Velden committed
125
random MAC, and set up according to the cluster level NIC
126
127
128
129
130
131
132
133
parameters. Each NIC can take these parameters (all optional):

mac
    either a value or 'generate' to generate a new unique MAC

ip
    specifies the IP address assigned to the instance from the Ganeti
    side (this is not necessarily what the instance will use, but what
134
135
136
137
138
139
    the node expects the instance to use). Note that if an IP in the
    range of a network configured with **gnt-network**\(8) is used,
    and the NIC is not already connected to it, this network has to be
    passed in the **network** parameter if this NIC is meant to be
    connected to the said network. ``--no-conflicts-check`` can be used
    to override this check. The special value **pool** causes Ganeti to
Lisa Velden's avatar
Lisa Velden committed
140
    select an IP from the network the NIC is or will be connected to.
141
142
143
    One can pick an externally reserved IP of a network along with
    ``--no-conflict-check``. Note that this IP cannot be assigned to
    any other instance until it gets released.
144
145

mode
Guido Trotter's avatar
Guido Trotter committed
146
    specifies the connection mode for this NIC: routed, bridged or
147
    openvswitch.
148
149

link
150
151
152
    in bridged or openvswitch mode specifies the interface to attach
    this NIC to, in routed mode it's intended to differentiate between
    different routing tables/instance groups (but the meaning is
153
    dependent on the network script, see **gnt-cluster**\(8) for more
154
155
    details). Note that openvswitch support is also hypervisor
    dependent.
156

157
158
159
network
    derives the mode and the link from the settings of the network
    which is identified by its name. If the network option is chosen,
Guido Trotter's avatar
Guido Trotter committed
160
161
162
163
    link and mode must not be specified. Note that the mode and link
    depend on the network-to-nodegroup connection, thus allowing
    different nodegroups to be connected to the same network in
    different ways.
164

165
166
167
168
name
   this option specifies a name for the NIC, which can be used as a NIC
   identifier. An instance can not have two NICs with the same name.

169
170
171
172
173
vlan
   in openvswitch mode specifies the VLANs that the NIC will be
   connected to. To connect as an access port use ``n`` or ``.n`` with
   **n** being the VLAN ID. To connect as an trunk port use ``:n[:n]``.
   A hybrid port can be created with ``.n:n[:n]``
174

Guido Trotter's avatar
Guido Trotter committed
175
Of these "mode" and "link" are NIC parameters, and inherit their
176
177
178
default at cluster level.  Alternatively, if no network is desired for
the instance, you can prevent the default of one NIC with the
``--no-nics`` option.
179

Iustin Pop's avatar
Iustin Pop committed
180
181
182
183
The ``-o (--os-type)`` option specifies the operating system to be
installed.  The available operating systems can be listed with
**gnt-os list**.  Passing ``--no-install`` will however skip the OS
installation, allowing a manual import if so desired. Note that the
184
185
186
187
no-installation mode will automatically disable the start-up of the
instance (without an OS, it most likely won't be able to start-up
successfully).

Iustin Pop's avatar
Iustin Pop committed
188
189
190
The ``-B (--backend-parameters)`` option specifies the backend
parameters for the instance. If no such parameters are specified, the
values are inherited from the cluster. Possible parameters are:
191

192
193
maxmem
    the maximum memory size of the instance; as usual, suffixes can be
194
    used to denote the unit, otherwise the value is taken in mebibytes
195
196
197

minmem
    the minimum memory size of the instance; as usual, suffixes can be
198
    used to denote the unit, otherwise the value is taken in mebibytes
199
200
201
202
203
204
205
206
207

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

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

208
209
210
211
212
always\_failover
    ``True`` or ``False``, whether the instance must be failed over
    (shut down and rebooted) always or it may be migrated (briefly
    suspended)

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

Iustin Pop's avatar
Iustin Pop committed
219
220
221
222
223
224
The ``-H (--hypervisor-parameters)`` option specified the hypervisor
to use for the instance (must be one of the enabled hypervisors on the
cluster) and optionally custom parameters for this instance. If not
other options are used (i.e. the invocation is just -H *NAME*) the
instance will inherit the cluster options. The defaults below show the
cluster defaults at cluster creation time.
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248

The possible hypervisor options are as follows:

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

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

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

    a
        floppy drive

    c
        hard disk

    d
        CDROM drive

    n
        network boot (PXE)

249
    The default is not to set an HVM boot order, which is interpreted
250
    as 'dc'.
251

252
    For KVM the boot order is either "floppy", "cdrom", "disk" or
Iustin Pop's avatar
Iustin Pop committed
253
254
255
256
257
    "network".  Please note that older versions of KVM couldn't netboot
    from virtio interfaces. This has been fixed in more recent versions
    and is confirmed to work at least with qemu-kvm 0.11.1. Also note
    that if you have set the ``kernel_path`` option, that will be used
    for booting, and this setting will be silently ignored.
258

259
260
261
blockdev\_prefix
    Valid for the Xen HVM and PVM hypervisors.

Iustin Pop's avatar
Iustin Pop committed
262
263
    Relevant to non-pvops guest kernels, in which the disk device names
    are given by the host.  Allows one to specify 'xvd', which helps run
264
    Red Hat based installers, driven by anaconda.
265

266
267
268
floppy\_image\_path
    Valid for the KVM hypervisor.

269
270
271
272
    The path to a floppy disk image to attach to the instance.  This
    is useful to install Windows operating systems on Virt/IO disks
    because you can specify here the floppy for the drivers at
    installation time.
273

274
275
276
277
278
cdrom\_image\_path
    Valid for the Xen HVM and KVM hypervisors.

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

279
280
281
282
283
284
285
cdrom2\_image\_path
    Valid for the KVM hypervisor.

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

286
287
288
289
290
291
nic\_type
    Valid for the Xen HVM and KVM hypervisors.

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

Iustin Pop's avatar
Iustin Pop committed
292
293
294
295
296
297
298
299
300
    - rtl8139 (default for Xen HVM) (HVM & KVM)
    - ne2k\_isa (HVM & KVM)
    - ne2k\_pci (HVM & KVM)
    - i82551 (KVM)
    - i82557b (KVM)
    - i82559er (KVM)
    - pcnet (KVM)
    - e1000 (KVM)
    - paravirtual (default for KVM) (HVM & KVM)
301

302
303
304
305
306
307
308
309
310
311
312
vif\_type
    Valid for the Xen HVM hypervisor.

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

    - ioemu
    - vif

313
314
315
316
317
318
disk\_type
    Valid for the Xen HVM and KVM hypervisors.

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

319
    - ioemu [default] (HVM & KVM)
320
321
    - paravirtual (HVM & KVM)
    - ide (KVM)
322
323
324
325
    - scsi (KVM)
    - sd (KVM)
    - mtd (KVM)
    - pflash (KVM)
326
327


328
329
cdrom\_disk\_type
    Valid for the KVM hypervisor.
330

331
332
    This parameter determines the way the cdroms disks are presented
    to the instance. The default behavior is to get the same value of
333
    the earlier parameter (disk_type). The possible options are:
334

335
336
337
338
339
340
    - paravirtual
    - ide
    - scsi
    - sd
    - mtd
    - pflash
341
342
343
344
345
346
347
348
349
350
351


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

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

352
353
354
355
356
357
358
359
vnc\_password\_file
    Valid for the Xen HVM and KVM hypervisors.

    Specifies the location of the file containing the password for
    connections using VNC. The default is a file named
    vnc-cluster-password which can be found in the configuration
    directory.

360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
vnc\_tls
    Valid for the KVM hypervisor.

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

vnc\_x509\_path
    Valid for the KVM hypervisor.

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

vnc\_x509\_verify
    Valid for the KVM hypervisor.

375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
spice\_bind
    Valid for the KVM hypervisor.

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

    - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
    - IPv6 addresses, including :: and ::1
    - names of network interfaces

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

spice\_ip\_version
    Valid for the KVM hypervisor.

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

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

400
401
402
403
404
405
406
spice\_password\_file
    Valid for the KVM hypervisor.

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

407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
spice\_image\_compression
    Valid for the KVM hypervisor.

    Configures the SPICE lossless image compression. Valid values are:

    - auto_glz
    - auto_lz
    - quic
    - glz
    - lz
    - off

spice\_jpeg\_wan\_compression
    Valid for the KVM hypervisor.

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

    - auto
    - never
    - always

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

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

    - auto
    - never
    - always

spice\_streaming\_video
    Valid for the KVM hypervisor.

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

    - off
    - all
    - filter

spice\_playback\_compression
    Valid for the KVM hypervisor.

    Configures whether SPICE should compress audio streams or not.

453
454
455
456
457
458
spice\_use\_tls
    Valid for the KVM hypervisor.

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

459
460
461
462
spice\_tls\_ciphers
    Valid for the KVM hypervisor.

    Specifies a list of comma-separated ciphers that SPICE should use
463
    for TLS connections. For the format, see man **cipher**\(1).
464
465
466
467
468
469

spice\_use\_vdagent
    Valid for the KVM hypervisor.

    Enables or disables passing mouse events via SPICE vdagent.

470
471
472
473
474
475
476
477
478
479
480
481
482
cpu\_type
    Valid for the KVM hypervisor.

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

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

    For more information please refer to the KVM manual.

483
484
485
486
487
488
acpi
    Valid for the Xen HVM and KVM hypervisors.

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

Jose A. Lopes's avatar
Jose A. Lopes committed
489
490
491
    ACPI should be enabled for user shutdown detection.  See
    ``user_shutdown``.

492
493
494
pae
    Valid for the Xen HVM and KVM hypervisors.

495
    A boolean option that specifies if the hypervisor should enable
496
497
498
    PAE support for this instance. The default is false, disabling PAE
    support.

499
500
501
502
503
504
505
viridian
    Valid for the Xen HVM hypervisor.

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

506
507
508
509
510
511
512
513
514
515
516
517
518
use\_localtime
    Valid for the Xen HVM and KVM hypervisors.

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

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

    This option specifies the path (on the node) to the kernel to boot
Iustin Pop's avatar
Iustin Pop committed
519
520
521
522
    the instance with. Xen PVM instances always require this, while for
    KVM if this option is empty, it will cause the machine to load the
    kernel from its disks (and the boot will be done accordingly to
    ``boot_order``).
523
524
525
526
527
528
529
530

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

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

531
532
533
534
    The default setting for this value is simply ``"ro"``, which
    mounts the root disk (initially) in read-only one. For example,
    setting this to single will cause the instance to start in
    single-user mode.
535
536
537
538
539

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

    This option specifies the path (on the node) to the initrd to boot
540
541
542
543
544
    the instance with. Xen PVM instances can use this always, while
    for KVM if this option is only used if the ``kernel_path`` option
    is also specified. You can pass here either an absolute filename
    (the path to the initrd) if you want to use an initrd, or use the
    format no\_initrd\_path for no initrd.
545
546
547
548
549
550
551
552

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

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

553
554
555
556
    Please note, that if this setting is an empty string and the
    hypervisor is Xen it will not be written to the Xen configuration
    file

557
558
559
560
serial\_console
    Valid for the KVM hypervisor.

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

Guido Trotter's avatar
Guido Trotter committed
567
568
569
570
571
572
573
574
serial\_speed
    Valid for the KVM hypervisor.

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

575
576
577
disk\_cache
    Valid for the KVM hypervisor.

578
579
580
581
582
583
584
585
586
    The disk cache mode. It can be either default to not pass any
    cache option to KVM, or one of the KVM cache modes: none (for
    direct I/O), writethrough (to use the host cache but report
    completion to the guest only when the host has committed the
    changes to disk) or writeback (to use the host cache and report
    completion as soon as the data is in the host cache). Note that
    there are special considerations for the cache mode depending on
    version of KVM used and disk type (always raw file under Ganeti),
    please refer to the KVM documentation for more details.
587
588
589
590

security\_model
    Valid for the KVM hypervisor.

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

595
596
    Under *user* kvm will drop privileges and become the user
    specified by the security\_domain parameter.
597

598
    Under *pool* a global cluster pool of users will be used, making
599
600
601
602
603
604
    sure no two instances share the same user on the same node. (this
    mode is not implemented yet)

security\_domain
    Valid for the KVM hypervisor.

605
606
    Under security model *user* the username to run the instance
    under.  It must be a valid username existing on the host.
607

608
    Cannot be set under security model *none* or *pool*.
609
610
611
612

kvm\_flag
    Valid for the KVM hypervisor.

613
614
615
    If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
    -disable-kvm is passed. If unset no flag is passed, and the
    default running mode for your kvm binary will be used.
616
617
618
619
620
621
622
623
624
625
626

mem\_path
    Valid for the KVM hypervisor.

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

use\_chroot
    Valid for the KVM hypervisor.

627
    This boolean option determines whether to run the KVM instance in a
628
629
630
631
632
633
634
635
    chroot directory.

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

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

Jose A. Lopes's avatar
Jose A. Lopes committed
636
637
638
639
640
641
642
643
644
645
646
647
648
user\_shutdown
    Valid for the KVM hypervisor.

    This boolean option determines whether the KVM instance suports user
    shutdown detection.  This option does not necessarily require ACPI
    enabled, but ACPI must be enabled for users to poweroff their KVM
    instances.

    If it is set to ``true``, the user can shutdown this KVM instance
    and its status is reported as ``USER_down``.

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

649
650
651
652
653
654
655
656
657
658
659
660
migration\_downtime
    Valid for the KVM hypervisor.

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

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

cpu\_mask
661
    Valid for the Xen, KVM and LXC hypervisors.
662

663
664
    The processes belonging to the given instance are only scheduled
    on the specified CPUs.
665

666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
    The format of the mask can be given in three forms. First, the word
    "all", which signifies the common case where all VCPUs can live on
    any CPU, based on the hypervisor's decisions.

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

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

684
685
    Example:

686
    .. code-block:: bash
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705

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

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

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

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

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

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

707
708
709
710
711
712
713
714
715
716
717
718
cpu\_cap
    Valid for the Xen hypervisor.

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

cpu\_weight
    Valid for the Xen hypervisor.

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

719
720
721
722
723
724
725
usb\_mouse
    Valid for the KVM hypervisor.

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

726
727
728
729
730
731
keymap
    Valid for the KVM hypervisor.

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

732
733
734
735
736
737
738
739
740
reboot\_behavior
    Valid for Xen PVM, Xen HVM and KVM hypervisors.

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

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

741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
cpu\_cores
    Valid for the KVM hypervisor.

    Number of emulated CPU cores.

cpu\_threads
    Valid for the KVM hypervisor.

    Number of emulated CPU threads.

cpu\_sockets
    Valid for the KVM hypervisor.

    Number of emulated CPU sockets.

Guido Trotter's avatar
Guido Trotter committed
756
soundhw
757
    Valid for the KVM and XEN hypervisors.
Guido Trotter's avatar
Guido Trotter committed
758
759
760
761

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

762
763
764
765
766
767
768
769
770
771
772
773
774
cpuid
    Valid for the XEN hypervisor.

    Modify the values returned by CPUID_ instructions run within instances.

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

    See the XEN documentation for syntax and more information.

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

Guido Trotter's avatar
Guido Trotter committed
775
776
777
usb\_devices
    Valid for the KVM hypervisor.

778
    Space separated list of usb devices. These can be emulated devices
Guido Trotter's avatar
Guido Trotter committed
779
780
    or passthrough ones, and each one gets passed to kvm with its own
    ``-usbdevice`` option. See the **qemu**\(1) manpage for the syntax
781
782
    of the possible components. Note that values set with this
    parameter are split on a space character and currently don't support
783
784
    quoting. For backwards compatibility reasons, the RAPI interface keeps
    accepting comma separated lists too.
Guido Trotter's avatar
Guido Trotter committed
785

Guido Trotter's avatar
Guido Trotter committed
786
787
788
789
790
vga
    Valid for the KVM hypervisor.

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

Guido Trotter's avatar
Guido Trotter committed
791
792
793
794
kvm\_extra
    Valid for the KVM hypervisor.

    Any other option to the KVM hypervisor, useful tweaking anything
795
796
797
    that Ganeti doesn't support. Note that values set with this
    parameter are split on a space character and currently don't support
    quoting.
Guido Trotter's avatar
Guido Trotter committed
798

799
800
801
802
803
804
machine\_version
    Valid for the KVM hypervisor.

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

806
807
808
809
810
kvm\_path
    Valid for the KVM hypervisor.

    Path to the userspace KVM (or qemu) program.

811
812
813
814
815
816
817
818
819
820
821
822
823
vnet\_hdr
    Valid for the KVM hypervisor.

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

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

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

Iustin Pop's avatar
Iustin Pop committed
824
The ``-O (--os-parameters)`` option allows customisation of the OS
825
826
827
parameters. The actual parameter names and values depend on the OS being
used, but the syntax is the same key=value. For example, setting a
hypothetical ``dhcp`` parameter to yes can be achieved by::
828
829
830

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

831
832
833
834
835
The ``-I (--iallocator)`` option specifies the instance allocator plugin
to use (``.`` means the default allocator). If you pass in this option
the allocator will select nodes for this instance automatically, so you
don't need to pass them with the ``-n`` option. For more information
please refer to the instance allocator documentation.
836

Iustin Pop's avatar
Iustin Pop committed
837
The ``-t (--disk-template)`` options specifies the disk layout type
838
839
840
841
for the instance. If no disk template is specified, the default disk
template is used. The default disk template is the first in the list
of enabled disk templates, which can be adjusted cluster-wide with
``gnt-cluster modify``. The available choices for disk templates are:
842
843
844
845
846
847
848
849

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

file
    Disk devices will be regular files.

850
851
852
sharedfile
    Disk devices will be regulare files on a shared directory.

853
854
855
856
857
858
plain
    Disk devices will be logical volumes.

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

859
860
861
rbd
    Disk devices will be rbd volumes residing inside a RADOS cluster.

862
863
864
865
866
867
blockdev
    Disk devices will be adopted pre-existent block devices.

ext
    Disk devices will be provided by external shared storage,
    through the ExtStorage Interface using ExtStorage providers.
868

Iustin Pop's avatar
Iustin Pop committed
869
The optional second value of the ``-n (--node)`` is used for the drbd
870
871
872
873
874
875
template type and specifies the remote node.

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

The ``--file-storage-dir`` specifies the relative path under the
Iustin Pop's avatar
Iustin Pop committed
876
877
cluster-wide file storage directory to store file-based disks. It is
useful for having different subdirectories for different
878
instances. The full path of the directory where the disk files are
Iustin Pop's avatar
Iustin Pop committed
879
stored will consist of cluster-wide file storage directory + optional
880
881
subdirectory + instance name. This option is only relevant for
instances using the file storage backend.
882
883

The ``--file-driver`` specifies the driver to use for file-based
884
885
886
disks. Note that currently these drivers work with the xen hypervisor
only. This option is only relevant for instances using the file
storage backend. The available choices are:
887
888

loop
889
890
891
892
893
894
    Kernel loopback driver. This driver uses loopback devices to
    access the filesystem within the file. However, running I/O
    intensive applications in your instance using the loop driver
    might result in slowdowns. Furthermore, if you use the loopback
    driver consider increasing the maximum amount of loopback devices
    (on most systems it's 8) using the max\_loop param.
895
896

blktap
897
898
899
900
901
902
    The blktap driver (for Xen hypervisors). In order to be able to
    use the blktap driver you should check if the 'blktapctrl' user
    space disk agent is running (usually automatically started via
    xend).  This user-level disk I/O interface has the advantage of
    better performance. Especially if you use a network file system
    (e.g. NFS) to store your instances this is the recommended choice.
903

904
905
906
blktap2
    Analogous to the blktap driver, but used by newer versions of Xen.

907
908
909
If ``--ignore-ipolicy`` is given any instance policy violations occuring
during this operation are ignored.

910
See **ganeti**\(7) for a description of ``--submit`` and other common
911
912
options.

913
914
Example::

915
    # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
916
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
917
918
    # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
      -o debian-etch -n node1.example.com instance1.example.com
919
    # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
920
921
      -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
    # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
922
      -n node1.example.com:node2.example.com instance2.example.com
923
924
925
926
927
928
929
    # gnt-instance add -t rbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
      -n node1.example.com instance1.example.com
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1 -B maxmem=512 \
      -o debian-etch -n node1.example.com instance1.example.com
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1,param1=val1 \
      --disk 1:size=40g,provider=pvdr2,param2=val2,param3=val3 -B maxmem=512 \
      -o debian-etch -n node1.example.com instance1.example.com
930
931
932
933
934


BATCH-CREATE
^^^^^^^^^^^^

935
936
937
| **batch-create**
| [{-I|\--iallocator} *instance allocator*]
| {instances\_file.json}
938
939

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

946
947
948
949
The instance file must be a valid-formed JSON file, containing an
array of dictionaries with instance creation parameters. All parameters
(except ``iallocator``) which are valid for the instance creation
OP code are allowed. The most important ones are:
950

951
952
instance\_name
    The FQDN of the new instance.
953
954
955
956
957

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

958
959
960
961
962
disks
    Array of disk specifications. Each entry describes one disk as a
    dictionary of disk parameters.

beparams
963
964
965
    A dictionary of backend parameters.

hypervisor
966
    The hypervisor for the instance.
967

968
969
970
hvparams
    A dictionary with the hypervisor options. If not passed, the default
    hypervisor options will be inherited.
971
972

nics
Guido Trotter's avatar
Guido Trotter committed
973
    List of NICs that will be created for the instance. Each entry
974
975
    should be a dict, with mac, ip, mode and link as possible keys.
    Please don't provide the "mac, ip, mode, link" parent keys if you
Guido Trotter's avatar
Guido Trotter committed
976
    use this method for specifying NICs.
977

978
pnode, snode
979
    The primary and optionally the secondary node to use for the
980
981
982
    instance (in case an iallocator script is not used). If those
    parameters are given, they have to be given consistently for all
    instances in the batch operation.
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002

start
    whether to start the instance

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

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

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


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

1003
1004
1005
1006
1007
1008
1009
1010
1011
    [
      {
        "mode": "create",
        "instance_name": "instance1.example.com",
        "disk_template": "drbd",
        "os_type": "debootstrap",
        "disks": [{"size":"1024"}],
        "nics": [{}],
        "hypervisor": "xen-pvm"
1012
      },
1013
1014
1015
1016
1017
1018
1019
      {
        "mode": "create",
        "instance_name": "instance2.example.com",
        "disk_template": "drbd",
        "os_type": "debootstrap",
        "disks": [{"size":"4096", "mode": "rw", "vg": "xenvg"}],
        "nics": [{}],
1020
1021
        "hypervisor": "xen-hvm",
        "hvparams": {"acpi": true},
1022
        "beparams": {"maxmem": 512, "minmem": 256}
1023
      }
1024
    ]
1025
1026
1027
1028
1029

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

    # gnt-instance batch-create instances.json
1030
    Submitted jobs 37, 38
1031

1032
1033
1034
1035
1036
1037
1038
1039

Note: If the allocator is used for computing suitable nodes for the
instances, it will only take into account disk information for the
default disk template. That means, even if other disk templates are
specified for the instances, storage space information of these disk
templates will not be considered in the allocation computation.


1040
1041
1042
REMOVE
^^^^^^

1043
1044
| **remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
| [\--print-job-id] [\--force] {*instance*}
1045
1046
1047

Remove an instance. This will remove all data from the instance and
there is *no way back*. If you are not sure if you use an instance
1048
1049
again, use **shutdown** first and leave it in the shutdown state for a
while.
1050
1051
1052

The ``--ignore-failures`` option will cause the removal to proceed
even in the presence of errors during the removal of the instance
1053
1054
(e.g. during the shutdown or the disk removal). If this option is not
given, the command will stop at the first error.
1055
1056
1057
1058
1059
1060

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

1061
1062
The ``--force`` option is used to skip the interactive confirmation.

1063
See **ganeti**\(7) for a description of ``--submit`` and other common
1064
1065
options.

1066
1067
1068
1069
1070
1071
1072
1073
1074
Example::

    # gnt-instance remove instance1.example.com


LIST
^^^^

| **list**
Iustin Pop's avatar
Iustin Pop committed
1075
1076
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087

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

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

The units used to display the numeric values in the output varies,
depending on the options given. By default, the values will be
1088
1089
1090
1091
formatted in the most appropriate unit. If the ``--separator`` option
is given, then the values are shown in mebibytes to allow parsing by
scripts. In both cases, the ``--units`` option can be used to enforce
a given output unit.
1092

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

Iustin Pop's avatar
Iustin Pop committed
1096
1097
The ``-o (--output)`` option takes a comma-separated list of output
fields. The available fields and their meaning are:
1098

1099
@QUERY_FIELDS_INSTANCE@
1100
1101

If the value of the option starts with the character ``+``, the new
Iustin Pop's avatar
Iustin Pop committed
1102
1103
field(s) will be added to the default list. This allows one to quickly
see the default list plus a few other fields, instead of retyping the
1104
entire list of fields.
1105
1106
1107

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

1115
If exactly one argument is given and it appears to be a query filter
1116
(see **ganeti**\(7)), the query result is filtered accordingly. For
1117
1118
1119
1120
1121
1122
ambiguous cases (e.g. a single field name as a filter) the ``--filter``
(``-F``) option forces the argument to be treated as a filter (e.g.
``gnt-instance list -F admin_state``).

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

1124
1125

LIST-FIELDS
1126
^^^^^^^^^^^
1127
1128
1129
1130
1131
1132

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

Lists available fields for instances.


1133
1134
1135
INFO
^^^^

Iustin Pop's avatar
Iustin Pop committed
1136
**info** [-s \| \--static] [\--roman] {\--all \| *instance*}
1137
1138

Show detailed information about the given instance(s). This is
1139
1140
different from **list** as it shows detailed data about the instance's
disks (especially useful for the drbd disk template).
1141
1142
1143
1144
1145
1146
1147
1148

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

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

1149
1150
1151
The ``--roman`` option can be used to cause envy among people who like
ancient cultures, but are stuck with non-latin-friendly cluster
virtualization technologies.
1152
1153
1154
1155
1156

MODIFY
^^^^^^

| **modify**
Iustin Pop's avatar
Iustin Pop committed
1157
1158
1159
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
| [{-m|\--runtime-memory} *SIZE*]
1160
1161
1162
1163
1164
1165
1166
1167
1168
| [\--net add[:options...] \|
|  \--net [*N*:]add[,options...] \|
|  \--net [*ID*:]remove \|
|  \--net *ID*:modify[,options...]]
| [\--disk add:size=*SIZE*[,options...] \|
|  \--disk *N*:add,size=*SIZE*[,options...] \|
|  \--disk *N*:add,size=*SIZE*,provider=*PROVIDER*[,options...][,param=*value*... ] \|
|  \--disk *ID*:modify[,options...]
|  \--disk [*ID*:]remove]
1169
| [{-t|\--disk-template} plain \| {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
1170
| [\--new-primary=*node*]
Iustin Pop's avatar
Iustin Pop committed
1171
1172
1173
| [\--os-type=*OS* [\--force-variant]]
| [{-O|\--os-parameters} *param*=*value*... ]
| [\--offline \| \--online]
1174
| [\--submit] [\--print-job-id]
Iustin Pop's avatar
Iustin Pop committed
1175
| [\--ignore-ipolicy]
1176
| [\--hotplug]
1177
| [\--hotplug-if-possible]
1178
1179
1180
| {*instance*}

Modifies the memory size, number of vcpus, ip address, MAC address
Guido Trotter's avatar
Guido Trotter committed
1181
and/or NIC parameters for an instance. It can also add and remove
1182
1183
1184
disks and NICs to/from the instance. Note that you need to give at
least one of the arguments, otherwise the command complains.

Iustin Pop's avatar
Iustin Pop committed
1185
1186
1187
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
and ``-O (--os-parameters)`` options specifies hypervisor, backend and
OS parameter options in the form of name=value[,...]. For details
1188
which options can be specified, see the **add** command.
1189

Iustin Pop's avatar
Iustin Pop committed
1190
1191
1192
1193
1194
1195
1196
1197
The ``-t (--disk-template)`` option will change the disk template of
the instance.  Currently only conversions between the plain and drbd
disk templates are supported, and the instance must be stopped before
attempting the conversion. When changing from the plain to the drbd
disk template, a new secondary node must be specified via the ``-n``
option. The option ``--no-wait-for-sync`` can be used when converting
to the ``drbd`` template in order to make the instance available for
startup before DRBD has finished resyncing.
1198

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

1203
1204
1205
The ``--disk add:size=*SIZE*,[options..]`` option adds a disk to the
instance, and ``--disk *N*:add:size=*SIZE*,[options..]`` will add a disk
to the the instance at a specific index. The available options are the
1206
same as in the **add** command(``spindles``, ``mode``, ``name``, ``vg``,
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
``metavg``). Per default, gnt-instance waits for the disk mirror to sync.
If you do not want this behavior, use the ``--no-wait-for-sync`` option.
When adding an ExtStorage disk, the ``provider=*PROVIDER*`` option is
also mandatory and specifies the ExtStorage provider. Also, for
ExtStorage disks arbitrary parameters can be passed as additional comma
separated options, same as in the **add** command. The ``--disk remove``
option will remove the last disk of the instance. Use
``--disk `` *ID*``:remove`` to remove a disk by its identifier. *ID*
can be the index of the disk, the disks's name or the disks's UUID. The
``--disk *ID*:modify[,options...]`` will change the options of the disk.
1217
1218
1219
1220
1221
1222
Available options are:

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

name
1223
   This option specifies a name for the disk, which can be used as a disk
1224
1225
1226
1227
1228
1229
1230
1231
1232
   identifier. An instance can not have two disks with the same name.

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

Iustin Pop's avatar
Iustin Pop committed
1234
The option ``-o (--os-type)`` will change the OS name for the instance
1235
1236
(without reinstallation). In case an OS variant is specified that is
not found, then by default the modification is refused, unless
1237
1238
1239
``--force-variant`` is passed. An invalid OS will also be refused,
unless the ``--force`` option is given.

1240
1241
1242
1243
1244
The option ``--new-primary`` will set the new primary node of an instance
assuming the disks have already been moved manually. Unless the ``--force``
option is given, it is verified that the instance is no longer running
on its current primary node.

1245
1246
1247
1248
1249
1250
1251
The ``--online`` and ``--offline`` options are used to transition an
instance into and out of the ``offline`` state. An instance can be
turned offline only if it was previously down. The ``--online`` option
fails if the instance was not in the ``offline`` state, otherwise it
changes instance's state to ``down``. These modifications take effect
immediately.

1252
1253
1254
If ``--ignore-ipolicy`` is given any instance policy violations occuring
during this operation are ignored.

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

1265
1266
1267
1268
1269
If ``--hotplug-if-possible`` is given then ganeti won't abort in case
hotplug is not supported. It will continue execution and modification
will take place after reboot. This covers use cases where instances are
not running or hypervisor is not KVM.

1270
See **ganeti**\(7) for a description of ``--submit`` and other common
1271
1272
options.

1273
Most of the changes take effect at the next restart. If the instance is
1274
1275
1276
1277
1278
running, there is no effect on the instance.

REINSTALL
^^^^^^^^^

Iustin Pop's avatar
Iustin Pop committed
1279
1280
1281
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
| [\--force-multiple]
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1282
1283
| [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] [\--print-job-id]
| {*instance*...}
1284
1285

Reinstalls the operating system on the given instance(s). The
Iustin Pop's avatar
Iustin Pop committed
1286
1287
instance(s) must be stopped when running this command. If the ``-o
(--os-type)`` is specified, the operating system is changed.
1288
1289
1290

The ``--select-os`` option switches to an interactive OS reinstall.
The user is prompted to select the OS template from the list of
Iustin Pop's avatar
Iustin Pop committed
1291
1292
1293
available OS templates. OS parameters can be overridden using ``-O
(--os-parameters)`` (more documentation for this option under the
**add** command).
1294
1295
1296
1297

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

1302
See **ganeti**\(7) for a description of ``--submit`` and other common
1303
options.
1304
1305
1306
1307

RENAME
^^^^^^

1308
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit] [\--print-job-id]
1309
1310
| {*instance*} {*new\_name*}

1311
1312
1313
1314
1315
1316
Renames the given instance. The instance must be stopped when running
this command. The requirements for the new name are the same as for
adding an instance: the new name must be resolvable and the IP it
resolves to must not be reachable (in order to prevent duplicate IPs
the next time the instance is started). The IP test can be skipped if
the ``--no-ip-check`` option is passed.
1317

1318
1319
1320
1321
Note that you can rename an instance to its same name, to force
re-executing the os-specific rename script for that instance, if
needed.

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

1328
See **ganeti**\(7) for a description of ``--submit`` and other common
1329
options.
1330
1331
1332
1333
1334
1335
1336
1337

Starting/stopping/connecting to console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

STARTUP
^^^^^^^

| **startup**
Iustin Pop's avatar
Iustin Pop committed
1338
1339
1340
1341
1342
1343
| [\--force] [\--ignore-offline]
| [\--force-multiple] [\--no-remember]
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
| [{-H|\--hypervisor-parameters} ``key=value...``]
| [{-B|\--backend-parameters} ``key=value...``]
1344
| [\--submit] [\--print-job-id] [\--paused]
1345
1346
| {*name*...}

1347
1348
Starts one or more instances, depending on the following options.  The
four available modes are:
1349

Iustin Pop's avatar
Iustin Pop committed
1350
\--instance
1351
1352
1353
    will start the instances given as arguments (at least one argument
    required); this is the default selection

Iustin Pop's avatar
Iustin Pop committed
1354
\--node
1355
1356
1357
    will start the instances who have the given node as either primary
    or secondary

Iustin Pop's avatar
Iustin Pop committed
1358
\--primary
1359
1360
1361
    will start all instances whose primary node is in the list of nodes
    passed as arguments (at least one node required)

Iustin Pop's avatar
Iustin Pop committed
1362
\--secondary
1363
1364
1365
    will start all instances whose secondary node is in the list of
    nodes passed as arguments (at least one node required)

Iustin Pop's avatar
Iustin Pop committed
1366
\--all
1367
1368
    will start all instances in the cluster (no arguments accepted)

Iustin Pop's avatar
Iustin Pop committed
1369
\--tags
1370
1371
1372
    will start all instances in the cluster with the tags given as
    arguments

Iustin Pop's avatar
Iustin Pop committed
1373
\--node-tags
1374
1375
1376
    will start all instances in the cluster on nodes with the tags
    given as arguments

Iustin Pop's avatar
Iustin Pop committed
1377
\--pri-node-tags
1378
1379
1380
    will start all instances in the cluster on primary nodes with the
    tags given as arguments

Iustin Pop's avatar
Iustin Pop committed
1381
\--sec-node-tags
1382
1383
1384
1385
    will start all instances in the cluster on secondary nodes with the
    tags given as arguments

Note that although you can pass more than one selection option, the
1386
1387
last one wins, so in order to guarantee the desired result, don't pass
more than one such option.
1388
1389

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

1393
1394
The ``--force-multiple`` will skip the interactive confirmation in the
case the more than one instance will be affected.
1395

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

Iustin Pop's avatar
Iustin Pop committed
1402
1403
1404
1405
1406
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
options specify temporary hypervisor and backend parameters that can
be used to start an instance with modified parameters. They can be
useful for quick testing without having to modify an instance back and
forth, e.g.::
1407

Stephen Shirley's avatar
Stephen Shirley committed
1408
    # gnt-instance start -H kernel_args="single" instance1
1409
    # gnt-instance start -B maxmem=2048 instance2
1410
1411


1412
1413
1414
1415
The first form will start the instance instance1 in single-user mode,
and the instance instance2 with 2GB of RAM (this time only, unless
that is the actual instance memory size already). Note that the values
override the instance parameters (and not extend them): an instance
Stephen Shirley's avatar
Stephen Shirley committed
1416
with "kernel\_args=ro" when started with -H kernel\_args=single will
1417
result in "single", not "ro single".
1418

1419
1420
1421
1422
1423
The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
pauses the instance at the start of bootup, awaiting ``gnt-instance
console`` to unpause it, allowing the entire boot process to be
monitored for debugging.

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

1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
Example::

    # gnt-instance start instance1.example.com
    # gnt-instance start --node node1.example.com node2.example.com
    # gnt-instance start --all


SHUTDOWN
^^^^^^^^

| **shutdown**
Iustin Pop's avatar
Iustin Pop committed
1438
| [\--timeout=*N*]
1439
| [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember]
Iustin Pop's avatar
Iustin Pop committed
1440
1441
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1442
| [\--submit] [\--print-job-id]
1443
1444
| {*name*...}

1445
1446
1447
1448
Stops one or more instances. If the instance cannot be cleanly stopped
during a hardcoded interval (currently 2 minutes), it will forcibly
stop the instance (equivalent to switching off the power on a physical
machine).
1449
1450
1451
1452
1453
1454
1455
1456

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

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

1460
1461
1462
``--ignore-offline`` can be used to ignore offline primary nodes and
force the instance to be marked as stopped. This option should be used
with care as it can lead to an inconsistent cluster state.
1463

1464
1465
1466
1467
Use ``--force`` to be able to shutdown an instance even when it's marked
as offline. This is useful is an offline instance ends up in the
``ERROR_up`` state, for example.

1468
1469
1470
1471
1472
1473
1474
1475
1476
The ``--no-remember`` option will perform the shutdown but not change
the state of the instance in the configuration file (if it was running
before, Ganeti will still thinks it needs to be running). This can be
useful for a cluster-wide shutdown, where some instances are marked as
up and some as down, and you don't want to change the running state:
you just need to disable the watcher, shutdown all instances with
``--no-remember``, and when the watcher is activated again it will
restore the correct runtime state for all instances.

1477
See **ganeti**\(7) for a description of ``--submit`` and other common
1478
1479
options.

1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
Example::

    # gnt-instance shutdown instance1.example.com
    # gnt-instance shutdown --all


REBOOT
^^^^^^

| **reboot**
Iustin Pop's avatar
Iustin Pop committed
1490
1491
1492
1493
1494
1495
| [{-t|\--type} *REBOOT-TYPE*]
| [\--ignore-secondaries]
| [\--shutdown-timeout=*N*]
| [\--force-multiple]
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1496
| [\--submit] [\--print-job-id]
1497
1498
| [*name*...]

1499
Reboots one or more instances. The type of reboot depends on the value
Iustin Pop's avatar
Iustin Pop committed
1500
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1501
1502
1503
1504
does a instance stop, recreates the hypervisor config for the instance
and starts the instance. A full reboot does the equivalent of
**gnt-instance shutdown && gnt-instance startup**.  The default is
hard reboot.
1505

1506
1507
For the hard reboot the option ``--ignore-secondaries`` ignores errors
for the secondary node while re-assembling the instance disks.
1508
1509
1510

The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1511
1512
``--sec-node-tags`` options are similar as for the **startup** command
and they influence the actual instances being rebooted.
1513
1514
1515

The ``--shutdown-timeout`` is used to specify how much time to wait
before forcing the shutdown (xm destroy in xen, killing the kvm