Update documentation of --print-jobid
[ganeti-github.git] / man / gnt-instance.rst
1 gnt-instance(8) Ganeti | Version @GANETI_VERSION@
2 =================================================
3
4 Name
5 ----
6
7 gnt-instance - Ganeti instance administration
8
9 Synopsis
10 --------
11
12 **gnt-instance** {command} [arguments...]
13
14 DESCRIPTION
15 -----------
16
17 The **gnt-instance** command is used for instance administration in
18 the Ganeti system.
19
20 COMMANDS
21 --------
22
23 Creation/removal/querying
24 ~~~~~~~~~~~~~~~~~~~~~~~~~
25
26 ADD
27 ^^^
28
29 | **add**
30 | {-t|\--disk-template {diskless \| file \| plain \| drbd \| rbd}}
31 | {\--disk=*N*: {size=*VAL*[,spindles=*VAL*] \| adopt=*LV*}[,options...]
32 |  \| {size=*VAL*,provider=*PROVIDER*}[,param=*value*... ][,options...]
33 |  \| {-s|\--os-size} *SIZE*}
34 | [\--no-ip-check] [\--no-name-check] [\--no-conflicts-check]
35 | [\--no-start] [\--no-install]
36 | [\--net=*N* [:options...] \| \--no-nics]
37 | [{-B|\--backend-parameters} *BEPARAMS*]
38 | [{-H|\--hypervisor-parameters} *HYPERVISOR* [: option=*value*... ]]
39 | [{-O|\--os-parameters} *param*=*value*... ]
40 | [--os-parameters-private *param*=*value*... ]
41 | [--os-parameters-secret *param*=*value*... ]
42 | [\--file-storage-dir *dir\_path*] [\--file-driver {loop \| blktap \| blktap2}]
43 | {{-n|\--node} *node[:secondary-node]* \| {-I|\--iallocator} *name*
44    \| {-g|--node-group} *nodegroup*}
45 | {{-o|\--os-type} *os-type*}
46 | [\--submit] [\--print-jobid]
47 | [\--ignore-ipolicy]
48 | [\--no-wait-for-sync]
49 | [{-c|\--communication=yes|no}]
50 | {*instance*}
51
52 Creates a new instance on the specified host. The *instance* argument
53 must be in DNS, but depending on the bridge/routing setup, need not be
54 in the same network as the nodes in the cluster.
55
56 The ``disk`` option specifies the parameters for the disks of the
57 instance. The numbering of disks starts at zero, and at least one disk
58 needs to be passed. For each disk, either the size or the adoption
59 source needs to be given. The size is interpreted (when no unit is
60 given) in mebibytes. You can also use one of the suffixes *m*, *g* or
61 *t* to specify the exact the units used; these suffixes map to
62 mebibytes, gibibytes and tebibytes. Each disk can also take these
63 parameters (all optional):
64
65 spindles
66   How many spindles (physical disks on the node) the disk should span.
67
68 mode
69   The access mode. Either ``ro`` (read-only) or the default ``rw``
70   (read-write).
71
72 name
73    This option specifies a name for the disk, which can be used as a disk
74    identifier. An instance can not have two disks with the same name.
75
76 vg
77    The LVM volume group. This works only for LVM and DRBD devices.
78
79 metavg
80    This option specifies a different VG for the metadata device. This
81    works only for DRBD devices. If not specified, the default metavg
82    of the node-group (possibly inherited from the cluster-wide settings)
83    will be used.
84
85 access
86    If 'userspace', instance will access this disk directly without going
87    through a block device, avoiding expensive context switches with
88    kernel space. This option works only for RBD, Gluster and ExtStorage
89    devices. If not specified, the default access of the node-group (possibly
90    inherited from the cluster-wide settings) will be used.
91
92 When creating ExtStorage disks, also arbitrary parameters can be passed,
93 to the ExtStorage provider. Those parameters are passed as additional
94 comma separated options. Therefore, an ExtStorage disk provided by
95 provider ``pvdr1`` with parameters ``param1``, ``param2`` would be
96 passed as ``--disk 0:size=10G,provider=pvdr1,param1=val1,param2=val2``.
97
98 When using the ``adopt`` key in the disk definition, Ganeti will
99 reuse those volumes (instead of creating new ones) as the
100 instance's disks. Ganeti will rename these volumes to the standard
101 format, and (without installing the OS) will use them as-is for the
102 instance. This allows migrating instances from non-managed mode
103 (e.g. plain KVM with LVM) to being managed via Ganeti. Please note that
104 this works only for the \`plain' disk template (see below for
105 template details).
106
107 Alternatively, a single-disk instance can be created via the ``-s``
108 option which takes a single argument, the size of the disk. This is
109 similar to the Ganeti 1.2 version (but will only create one disk).
110
111 The minimum disk specification is therefore ``--disk 0:size=20G`` (or
112 ``-s 20G`` when using the ``-s`` option), and a three-disk instance
113 can be specified as ``--disk 0:size=20G --disk 1:size=4G --disk
114 2:size=100G``.
115
116 The minimum information needed to specify an ExtStorage disk are the
117 ``size`` and the ``provider``. For example:
118 ``--disk 0:size=20G,provider=pvdr1``.
119
120 The ``--no-ip-check`` skips the checks that are done to see if the
121 instance's IP is not already alive (i.e. reachable from the master
122 node).
123
124 The ``--no-name-check`` skips the check for the instance name via
125 the resolver (e.g. in DNS or /etc/hosts, depending on your setup).
126 Since the name check is used to compute the IP address, if you pass
127 this option you must also pass the ``--no-ip-check`` option.
128
129 If you don't want the instance to automatically start after
130 creation, this is possible via the ``--no-start`` option. This will
131 leave the instance down until a subsequent **gnt-instance start**
132 command.
133
134 The NICs of the instances can be specified via the ``--net``
135 option. By default, one NIC is created for the instance, with a
136 random MAC, and set up according to the cluster level NIC
137 parameters. Each NIC can take these parameters (all optional):
138
139 mac
140     either a value or 'generate' to generate a new unique MAC
141
142 ip
143     specifies the IP address assigned to the instance from the Ganeti
144     side (this is not necessarily what the instance will use, but what
145     the node expects the instance to use). Note that if an IP in the
146     range of a network configured with **gnt-network**\(8) is used,
147     and the NIC is not already connected to it, this network has to be
148     passed in the **network** parameter if this NIC is meant to be
149     connected to the said network. ``--no-conflicts-check`` can be used
150     to override this check. The special value **pool** causes Ganeti to
151     select an IP from the network the NIC is or will be connected to.
152     One can pick an externally reserved IP of a network along with
153     ``--no-conflict-check``. Note that this IP cannot be assigned to
154     any other instance until it gets released.
155
156 mode
157     specifies the connection mode for this NIC: routed, bridged or
158     openvswitch.
159
160 link
161     in bridged or openvswitch mode specifies the interface to attach
162     this NIC to, in routed mode it's intended to differentiate between
163     different routing tables/instance groups (but the meaning is
164     dependent on the network script, see **gnt-cluster**\(8) for more
165     details). Note that openvswitch support is also hypervisor
166     dependent.
167
168 network
169     derives the mode and the link from the settings of the network
170     which is identified by its name. If the network option is chosen,
171     link and mode must not be specified. Note that the mode and link
172     depend on the network-to-nodegroup connection, thus allowing
173     different nodegroups to be connected to the same network in
174     different ways.
175
176 name
177    this option specifies a name for the NIC, which can be used as a NIC
178    identifier. An instance can not have two NICs with the same name.
179
180 vlan
181    in openvswitch mode specifies the VLANs that the NIC will be
182    connected to. To connect as an access port use ``n`` or ``.n`` with
183    **n** being the VLAN ID. To connect as an trunk port use ``:n[:n]``.
184    A hybrid port can be created with ``.n:n[:n]``
185
186 Of these "mode" and "link" are NIC parameters, and inherit their
187 default at cluster level.  Alternatively, if no network is desired for
188 the instance, you can prevent the default of one NIC with the
189 ``--no-nics`` option.
190
191 The ``-o (--os-type)`` option specifies the operating system to be
192 installed.  The available operating systems can be listed with
193 **gnt-os list**.  Passing ``--no-install`` will however skip the OS
194 installation, allowing a manual import if so desired. Note that the
195 no-installation mode will automatically disable the start-up of the
196 instance (without an OS, it most likely won't be able to start-up
197 successfully).
198
199 The ``-B (--backend-parameters)`` option specifies the backend
200 parameters for the instance. If no such parameters are specified, the
201 values are inherited from the cluster. Possible parameters are:
202
203 maxmem
204     the maximum memory size of the instance; as usual, suffixes can be
205     used to denote the unit, otherwise the value is taken in mebibytes
206
207 minmem
208     the minimum memory size of the instance; as usual, suffixes can be
209     used to denote the unit, otherwise the value is taken in mebibytes
210
211 vcpus
212     the number of VCPUs to assign to the instance (if this value makes
213     sense for the hypervisor)
214
215 auto\_balance
216     whether the instance is considered in the N+1 cluster checks
217     (enough redundancy in the cluster to survive a node failure)
218
219 always\_failover
220     ``True`` or ``False``, whether the instance must be failed over
221     (shut down and rebooted) always or it may be migrated (briefly
222     suspended)
223
224 Note that before 2.6 Ganeti had a ``memory`` parameter, which was the
225 only value of memory an instance could have. With the
226 ``maxmem``/``minmem`` change Ganeti guarantees that at least the minimum
227 memory is always available for an instance, but allows more memory to be
228 used (up to the maximum memory) should it be free.
229
230 The ``-H (--hypervisor-parameters)`` option specified the hypervisor
231 to use for the instance (must be one of the enabled hypervisors on the
232 cluster) and optionally custom parameters for this instance. If not
233 other options are used (i.e. the invocation is just -H *NAME*) the
234 instance will inherit the cluster options. The defaults below show the
235 cluster defaults at cluster creation time.
236
237 The possible hypervisor options are as follows:
238
239 boot\_order
240     Valid for the Xen HVM and KVM hypervisors.
241
242     A string value denoting the boot order. This has different meaning
243     for the Xen HVM hypervisor and for the KVM one.
244
245     For Xen HVM, The boot order is a string of letters listing the boot
246     devices, with valid device letters being:
247
248     a
249         floppy drive
250
251     c
252         hard disk
253
254     d
255         CDROM drive
256
257     n
258         network boot (PXE)
259
260     The default is not to set an HVM boot order, which is interpreted
261     as 'dc'.
262
263     For KVM the boot order is either "floppy", "cdrom", "disk" or
264     "network".  Please note that older versions of KVM couldn't netboot
265     from virtio interfaces. This has been fixed in more recent versions
266     and is confirmed to work at least with qemu-kvm 0.11.1. Also note
267     that if you have set the ``kernel_path`` option, that will be used
268     for booting, and this setting will be silently ignored.
269
270 blockdev\_prefix
271     Valid for the Xen HVM and PVM hypervisors.
272
273     Relevant to non-pvops guest kernels, in which the disk device names
274     are given by the host.  Allows one to specify 'xvd', which helps run
275     Red Hat based installers, driven by anaconda.
276
277 floppy\_image\_path
278     Valid for the KVM hypervisor.
279
280     The path to a floppy disk image to attach to the instance.  This
281     is useful to install Windows operating systems on Virt/IO disks
282     because you can specify here the floppy for the drivers at
283     installation time.
284
285 cdrom\_image\_path
286     Valid for the Xen HVM and KVM hypervisors.
287
288     The path to a CDROM image to attach to the instance.
289
290 cdrom2\_image\_path
291     Valid for the KVM hypervisor.
292
293     The path to a second CDROM image to attach to the instance.
294     **NOTE**: This image can't be used to boot the system. To do that
295     you have to use the 'cdrom\_image\_path' option.
296
297 nic\_type
298     Valid for the Xen HVM and KVM hypervisors.
299
300     This parameter determines the way the network cards are presented
301     to the instance. The possible options are:
302
303     - rtl8139 (default for Xen HVM) (HVM & KVM)
304     - ne2k\_isa (HVM & KVM)
305     - ne2k\_pci (HVM & KVM)
306     - i82551 (KVM)
307     - i82557b (KVM)
308     - i82559er (KVM)
309     - pcnet (KVM)
310     - e1000 (KVM)
311     - paravirtual (default for KVM) (HVM & KVM)
312
313 vif\_type
314     Valid for the Xen HVM hypervisor.
315
316     This parameter specifies the vif type of the nic configuration
317     of the instance. Unsetting the value leads to no type being specified
318     in the configuration. Note that this parameter only takes effect when
319     the 'nic_type' is not set. The possible options are:
320
321     - ioemu
322     - vif
323
324 disk\_type
325     Valid for the Xen HVM and KVM hypervisors.
326
327     This parameter determines the way the disks are presented to the
328     instance. The possible options are:
329
330     - ioemu [default] (HVM & KVM)
331     - paravirtual (HVM & KVM)
332     - ide (KVM)
333     - scsi (KVM)
334     - sd (KVM)
335     - mtd (KVM)
336     - pflash (KVM)
337
338
339 cdrom\_disk\_type
340     Valid for the KVM hypervisor.
341
342     This parameter determines the way the cdroms disks are presented
343     to the instance. The default behavior is to get the same value of
344     the earlier parameter (disk_type). The possible options are:
345
346     - paravirtual
347     - ide
348     - scsi
349     - sd
350     - mtd
351     - pflash
352
353
354 vnc\_bind\_address
355     Valid for the Xen HVM and KVM hypervisors.
356
357     Specifies the address that the VNC listener for this instance
358     should bind to. Valid values are IPv4 addresses. Use the address
359     0.0.0.0 to bind to all available interfaces (this is the default)
360     or specify the address of one of the interfaces on the node to
361     restrict listening to that interface.
362
363 vnc\_password\_file
364     Valid for the Xen HVM and KVM hypervisors.
365
366     Specifies the location of the file containing the password for
367     connections using VNC. The default is a file named
368     vnc-cluster-password which can be found in the configuration
369     directory.
370
371 vnc\_tls
372     Valid for the KVM hypervisor.
373
374     A boolean option that controls whether the VNC connection is
375     secured with TLS.
376
377 vnc\_x509\_path
378     Valid for the KVM hypervisor.
379
380     If ``vnc_tls`` is enabled, this options specifies the path to the
381     x509 certificate to use.
382
383 vnc\_x509\_verify
384     Valid for the KVM hypervisor.
385
386 spice\_bind
387     Valid for the KVM hypervisor.
388
389     Specifies the address or interface on which the SPICE server will
390     listen. Valid values are:
391
392     - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
393     - IPv6 addresses, including :: and ::1
394     - names of network interfaces
395
396     If a network interface is specified, the SPICE server will be bound
397     to one of the addresses of that interface.
398
399 spice\_ip\_version
400     Valid for the KVM hypervisor.
401
402     Specifies which version of the IP protocol should be used by the
403     SPICE server.
404
405     It is mainly intended to be used for specifying what kind of IP
406     addresses should be used if a network interface with both IPv4 and
407     IPv6 addresses is specified via the ``spice_bind`` parameter. In
408     this case, if the ``spice_ip_version`` parameter is not used, the
409     default IP version of the cluster will be used.
410
411 spice\_password\_file
412     Valid for the KVM hypervisor.
413
414     Specifies a file containing the password that must be used when
415     connecting via the SPICE protocol. If the option is not specified,
416     passwordless connections are allowed.
417
418 spice\_image\_compression
419     Valid for the KVM hypervisor.
420
421     Configures the SPICE lossless image compression. Valid values are:
422
423     - auto_glz
424     - auto_lz
425     - quic
426     - glz
427     - lz
428     - off
429
430 spice\_jpeg\_wan\_compression
431     Valid for the KVM hypervisor.
432
433     Configures how SPICE should use the jpeg algorithm for lossy image
434     compression on slow links. Valid values are:
435
436     - auto
437     - never
438     - always
439
440 spice\_zlib\_glz\_wan\_compression
441     Valid for the KVM hypervisor.
442
443     Configures how SPICE should use the zlib-glz algorithm for lossy image
444     compression on slow links. Valid values are:
445
446     - auto
447     - never
448     - always
449
450 spice\_streaming\_video
451     Valid for the KVM hypervisor.
452
453     Configures how SPICE should detect video streams. Valid values are:
454
455     - off
456     - all
457     - filter
458
459 spice\_playback\_compression
460     Valid for the KVM hypervisor.
461
462     Configures whether SPICE should compress audio streams or not.
463
464 spice\_use\_tls
465     Valid for the KVM hypervisor.
466
467     Specifies that the SPICE server must use TLS to encrypt all the
468     traffic with the client.
469
470 spice\_tls\_ciphers
471     Valid for the KVM hypervisor.
472
473     Specifies a list of comma-separated ciphers that SPICE should use
474     for TLS connections. For the format, see man **cipher**\(1).
475
476 spice\_use\_vdagent
477     Valid for the KVM hypervisor.
478
479     Enables or disables passing mouse events via SPICE vdagent.
480
481 cpu\_type
482     Valid for the KVM hypervisor.
483
484     This parameter determines the emulated cpu for the instance. If this
485     parameter is empty (which is the default configuration), it will not
486     be passed to KVM.
487
488     Be aware of setting this parameter to ``"host"`` if you have nodes
489     with different CPUs from each other. Live migration may stop working
490     in this situation.
491
492     For more information please refer to the KVM manual.
493
494 acpi
495     Valid for the Xen HVM and KVM hypervisors.
496
497     A boolean option that specifies if the hypervisor should enable
498     ACPI support for this instance. By default, ACPI is disabled.
499
500     ACPI should be enabled for user shutdown detection.  See
501     ``user_shutdown``.
502
503 pae
504     Valid for the Xen HVM and KVM hypervisors.
505
506     A boolean option that specifies if the hypervisor should enable
507     PAE support for this instance. The default is false, disabling PAE
508     support.
509
510 viridian
511     Valid for the Xen HVM hypervisor.
512
513     A boolean option that specifies if the hypervisor should enable
514     viridian (Hyper-V) for this instance. The default is false,
515     disabling viridian support.
516
517 use\_localtime
518     Valid for the Xen HVM and KVM hypervisors.
519
520     A boolean option that specifies if the instance should be started
521     with its clock set to the localtime of the machine (when true) or
522     to the UTC (When false). The default is false, which is useful for
523     Linux/Unix machines; for Windows OSes, it is recommended to enable
524     this parameter.
525
526 kernel\_path
527     Valid for the Xen PVM and KVM hypervisors.
528
529     This option specifies the path (on the node) to the kernel to boot
530     the instance with. Xen PVM instances always require this, while for
531     KVM if this option is empty, it will cause the machine to load the
532     kernel from its disks (and the boot will be done accordingly to
533     ``boot_order``).
534
535 kernel\_args
536     Valid for the Xen PVM and KVM hypervisors.
537
538     This options specifies extra arguments to the kernel that will be
539     loaded. This is always used for Xen PVM, while for KVM it
540     is only used if the ``kernel_path`` option is also specified.
541
542     The default setting for this value is simply ``"ro"``, which
543     mounts the root disk (initially) in read-only one. For example,
544     setting this to single will cause the instance to start in
545     single-user mode.
546
547     Note that the hypervisor setting ``serial_console`` appends
548     ``"console=ttyS0,<serial_speed>"`` to the end of ``kernel_args`` in KVM.
549
550 initrd\_path
551     Valid for the Xen PVM and KVM hypervisors.
552
553     This option specifies the path (on the node) to the initrd to boot
554     the instance with. Xen PVM instances can use this always, while
555     for KVM if this option is only used if the ``kernel_path`` option
556     is also specified. You can pass here either an absolute filename
557     (the path to the initrd) if you want to use an initrd, or use the
558     format no\_initrd\_path for no initrd.
559
560 root\_path
561     Valid for the Xen PVM and KVM hypervisors.
562
563     This options specifies the name of the root device. This is always
564     needed for Xen PVM, while for KVM it is only used if the
565     ``kernel_path`` option is also specified.
566
567     Please note, that if this setting is an empty string and the
568     hypervisor is Xen it will not be written to the Xen configuration
569     file
570
571 serial\_console
572     Valid for the KVM hypervisor.
573
574     This boolean option specifies whether to emulate a serial console
575     for the instance. Note that some versions of KVM have a bug that
576     will make an instance hang when configured to use the serial console
577     unless a connection is made to it within about 2 seconds of the
578     instance's startup. For such case it's recommended to disable this
579     option, which is enabled by default.
580
581     Enabling serial console emulation also appends
582     ``"console=ttyS0,<serial_speed>"`` to the end of ``kernel_args`` in KVM and
583     may infere with previous settings.
584
585 serial\_speed
586     Valid for the KVM hypervisor.
587
588     This integer option specifies the speed of the serial console.
589     Common values are 9600, 19200, 38400, 57600 and 115200: choose the
590     one which works on your system. (The default is 38400 for historical
591     reasons, but newer versions of kvm/qemu work with 115200)
592
593 disk\_cache
594     Valid for the KVM hypervisor.
595
596     The disk cache mode. It can be either default to not pass any
597     cache option to KVM, or one of the KVM cache modes: none (for
598     direct I/O), writethrough (to use the host cache but report
599     completion to the guest only when the host has committed the
600     changes to disk) or writeback (to use the host cache and report
601     completion as soon as the data is in the host cache). Note that
602     there are special considerations for the cache mode depending on
603     version of KVM used and disk type (always raw file under Ganeti),
604     please refer to the KVM documentation for more details.
605
606 disk\_aio
607     Valid for the KVM hypervisor.
608
609     This is an optional parameter that specifies the aio mode
610     for the disks. KVM default is to use the 'threads' mode,
611     so if not explicitly specified, the native mode will not
612     be used. Possible values are: threads or native.
613
614 security\_model
615     Valid for the KVM hypervisor.
616
617     The security model for kvm. Currently one of *none*, *user* or
618     *pool*. Under *none*, the default, nothing is done and instances
619     are run as the Ganeti daemon user (normally root).
620
621     Under *user* kvm will drop privileges and become the user
622     specified by the security\_domain parameter.
623
624     Under *pool* a global cluster pool of users will be used, making
625     sure no two instances share the same user on the same node. (this
626     mode is not implemented yet)
627
628 security\_domain
629     Valid for the KVM hypervisor.
630
631     Under security model *user* the username to run the instance
632     under.  It must be a valid username existing on the host.
633
634     Cannot be set under security model *none* or *pool*.
635
636 kvm\_flag
637     Valid for the KVM hypervisor.
638
639     If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
640     -disable-kvm is passed. If unset no flag is passed, and the
641     default running mode for your kvm binary will be used.
642
643 mem\_path
644     Valid for the KVM hypervisor.
645
646     This option passes the -mem-path argument to kvm with the path (on
647     the node) to the mount point of the hugetlbfs file system, along
648     with the -mem-prealloc argument too.
649
650 use\_chroot
651     Valid for the KVM hypervisor.
652
653     This boolean option determines whether to run the KVM instance in a
654     chroot directory.
655
656     If it is set to ``true``, an empty directory is created before
657     starting the instance and its path is passed via the -chroot flag
658     to kvm. The directory is removed when the instance is stopped.
659
660     It is set to ``false`` by default.
661
662 user\_shutdown
663     Valid for the KVM hypervisor.
664
665     This boolean option determines whether the KVM instance suports user
666     shutdown detection.  This option does not necessarily require ACPI
667     enabled, but ACPI must be enabled for users to poweroff their KVM
668     instances.
669
670     If it is set to ``true``, the user can shutdown this KVM instance
671     and its status is reported as ``USER_down``.
672
673     It is set to ``false`` by default.
674
675 migration\_downtime
676     Valid for the KVM hypervisor.
677
678     The maximum amount of time (in ms) a KVM instance is allowed to be
679     frozen during a live migration, in order to copy dirty memory
680     pages. Default value is 30ms, but you may need to increase this
681     value for busy instances.
682
683     This option is only effective with kvm versions >= 87 and qemu-kvm
684     versions >= 0.11.0.
685
686 cpu\_mask
687     Valid for the Xen, KVM and LXC hypervisors.
688
689     The processes belonging to the given instance are only scheduled
690     on the specified CPUs.
691
692     The format of the mask can be given in three forms. First, the word
693     "all", which signifies the common case where all VCPUs can live on
694     any CPU, based on the hypervisor's decisions.
695
696     Second, a comma-separated list of CPU IDs or CPU ID ranges. The
697     ranges are defined by a lower and higher boundary, separated by a
698     dash, and the boundaries are inclusive. In this form, all VCPUs of
699     the instance will be mapped on the selected list of CPUs. Example:
700     ``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs
701     0, 1, 2 and 5.
702
703     The last form is used for explicit control of VCPU-CPU pinnings. In
704     this form, the list of VCPU mappings is given as a colon (:)
705     separated list, whose elements are the possible values for the
706     second or first form above. In this form, the number of elements in
707     the colon-separated list _must_ equal the number of VCPUs of the
708     instance.
709
710     Example:
711
712     .. code-block:: bash
713
714       # Map the entire instance to CPUs 0-2
715       gnt-instance modify -H cpu_mask=0-2 my-inst
716
717       # Map vCPU 0 to physical CPU 1 and vCPU 1 to CPU 3 (assuming 2 vCPUs)
718       gnt-instance modify -H cpu_mask=1:3 my-inst
719
720       # Pin vCPU 0 to CPUs 1 or 2, and vCPU 1 to any CPU
721       gnt-instance modify -H cpu_mask=1-2:all my-inst
722
723       # Pin vCPU 0 to any CPU, vCPU 1 to CPUs 1, 3, 4 or 5, and CPU 2 to
724       # CPU 0 (backslashes for escaping the comma)
725       gnt-instance modify -H cpu_mask=all:1\\,3-5:0 my-inst
726
727       # Pin entire VM to CPU 0
728       gnt-instance modify -H cpu_mask=0 my-inst
729
730       # Turn off CPU pinning (default setting)
731       gnt-instance modify -H cpu_mask=all my-inst
732
733 cpu\_cap
734     Valid for the Xen hypervisor.
735
736     Set the maximum amount of cpu usage by the VM. The value is a percentage
737     between 0 and (100 * number of VCPUs). Default cap is 0: unlimited.
738
739 cpu\_weight
740     Valid for the Xen hypervisor.
741
742     Set the cpu time ratio to be allocated to the VM. Valid values are
743     between 1 and 65535. Default weight is 256.
744
745 usb\_mouse
746     Valid for the KVM hypervisor.
747
748     This option specifies the usb mouse type to be used. It can be
749     "mouse" or "tablet". When using VNC it's recommended to set it to
750     "tablet".
751
752 keymap
753     Valid for the KVM hypervisor.
754
755     This option specifies the keyboard mapping to be used. It is only
756     needed when using the VNC console. For example: "fr" or "en-gb".
757
758 reboot\_behavior
759     Valid for Xen PVM, Xen HVM and KVM hypervisors.
760
761     Normally if an instance reboots, the hypervisor will restart it. If
762     this option is set to ``exit``, the hypervisor will treat a reboot
763     as a shutdown instead.
764
765     It is set to ``reboot`` by default.
766
767 cpu\_cores
768     Valid for the KVM hypervisor.
769
770     Number of emulated CPU cores.
771
772 cpu\_threads
773     Valid for the KVM hypervisor.
774
775     Number of emulated CPU threads.
776
777 cpu\_sockets
778     Valid for the KVM hypervisor.
779
780     Number of emulated CPU sockets.
781
782 soundhw
783     Valid for Xen PVM, Xen HVM and KVM hypervisors.
784
785     Comma separated list of emulated sounds cards, or "all" to enable
786     all the available ones. See the **qemu**\(1) manpage for valid options and
787     additional details.
788
789 cpuid
790     Valid for the XEN hypervisor.
791
792     Modify the values returned by CPUID_ instructions run within instances.
793
794     This allows you to enable migration between nodes with different CPU
795     attributes like cores, threads, hyperthreading or SS4 support by hiding
796     the extra features where needed.
797
798     See the XEN documentation for syntax and more information.
799
800 .. _CPUID: http://en.wikipedia.org/wiki/CPUID
801
802 usb\_devices
803     Valid for the KVM hypervisor.
804
805     Space separated list of usb devices. These can be emulated devices
806     or passthrough ones, and each one gets passed to kvm with its own
807     ``-usbdevice`` option. See the **qemu**\(1) manpage for the syntax
808     of the possible components. Note that values set with this
809     parameter are split on a space character and currently don't support
810     quoting. For backwards compatibility reasons, the RAPI interface keeps
811     accepting comma separated lists too.
812
813 vga
814     Valid for the KVM hypervisor.
815
816     Emulated vga mode, passed the the kvm -vga option.
817
818 kvm\_extra
819     Valid for the KVM hypervisor.
820
821     Any other option to the KVM hypervisor, useful tweaking anything
822     that Ganeti doesn't support. Note that values set with this
823     parameter are split on a space character and currently don't support
824     quoting.
825
826 machine\_version
827     Valid for the KVM hypervisor.
828
829     Use in case an instance must be booted with an exact type of
830     machine version (due to e.g. outdated drivers). In case it's not set
831     the default version supported by your version of kvm is used.
832
833 migration\_caps
834     Valid for the KVM hypervisor.
835
836     Enable specific migration capabilities by providing a ":" separated
837     list of supported capabilites. QEMU version 1.7.0 defines
838     x-rdma-pin-all, auto-converge, zero-blocks, and xbzrle. Please note
839     that while a combination of xbzrle and auto-converge might speed up
840     the migration process significantly, the first may cause BSOD on
841     Windows8r2 instances running on drbd.
842
843 kvm\_path
844     Valid for the KVM hypervisor.
845
846     Path to the userspace KVM (or qemu) program.
847
848 vnet\_hdr
849     Valid for the KVM hypervisor.
850
851     This boolean option determines whether the tap devices used by the
852     KVM paravirtual nics (virtio-net) will get created with VNET_HDR
853     (IFF_VNET_HDR) support.
854
855     If set to false, it effectively disables offloading on the virio-net
856     interfaces, which prevents host kernel tainting and log flooding,
857     when dealing with broken or malicious virtio-net drivers.
858
859     It is set to ``true`` by default.
860
861 virtio\_net\_queues
862     Valid for the KVM hypervisor.
863
864     Set a number of queues (file descriptors) for tap device to
865     parallelize packets sending or receiving. Tap devices will be
866     created with MULTI_QUEUE (IFF_MULTI_QUEUE) support. This only
867     works with KVM paravirtual nics (virtio-net) and the maximum
868     number of queues is limited to ``8``. Tehnically this is an
869     extension of ``vnet_hdr`` which must be enabled for multiqueue
870     support.
871
872     If set to ``1`` queue, it effectively disables multiqueue support
873     on the tap and virio-net devices.
874
875     For instances it is necessary to manually set number of queues (on
876     Linux using: ``ethtool -L ethX combined $queues``).
877
878     It is set to ``1`` by default.
879
880 startup\_timeout
881     Valid for the LXC hypervisor.
882
883     This integer option specifies the number of seconds to wait
884     for the state of an LXC container changes to "RUNNING" after
885     startup, as reported by lxc-wait.
886     Otherwise we assume an error has occurred and report it.
887
888     It is set to ``30`` by default.
889
890 extra\_cgroups
891     Valid for the LXC hypervisor.
892
893     This option specifies the list of cgroup subsystems that will be
894     mounted alongside the needed ones before starting LXC containers.
895
896     Since LXC version >= 1.0.0, LXC strictly requires all cgroup
897     subsystems to be mounted before starting a container. Users can
898     control the list of desired cgroup subsystems for LXC containers
899     by specifying the lxc.cgroup.use parameter in the LXC system
900     configuration file(see: **lxc.system.conf**\(5)). Its default value
901     is "@kernel" which means all cgroup kernel subsystems.
902
903     The LXC hypervisor of Ganeti ensures that all cgroup subsystems
904     needed to start an LXC container are mounted, as well as the
905     subsystems specified in this parameter. The needed subsystems are
906     currently ``cpuset``, ``memory``, ``devices``, and ``cpuacct``.
907
908     The value of this parameter should be a list of cgroup subsystems
909     separated by a comma(e.g., "net_cls,perf_event,blkio").
910
911     If this parameter is not specified, a list of subsystems will be
912     taken from /proc/cgroups instead.
913
914 drop\_capabilities
915     Valid for the LXC hypervisor.
916
917     This option specifies the list of capabilities which should be
918     dropped for a LXC container.
919     Each value of this option must be in the same form as the
920     lxc.cap.drop configuration parameter of
921     **lxc.container.conf**\(5). It is the lower case of the capability
922     name without the "CAP\_" prefix (e.g., "sys_module,sys_time").
923     See **capabilities**\(7) for more details about Linux capabilities.
924     Note that some capabilities are required by the LXC container
925     (see: **lxc.container.conf**\(5)).
926     Also note that the CAP_SYS_BOOT is required(should not be dropped)
927     to perform the soft reboot for the LXC container.
928
929     The default value is ``mac_override,sys_boot,sys_module,sys_time``.
930
931 devices
932     Valid for the LXC hypervisor.
933
934     This option specifies the list of devices that can be accessed
935     from inside of the LXC container.
936     Each value of this option must have the same form as the
937     lxc.cgroup.devices.allow configuration parameter of
938     **lxc.container.conf**\(5). It consists of the type(a: all,
939     b: block, c: character), the major-minor pair, and the access type
940     sequence(r: read, w: write, m: mknod), e.g. "c 1:3 rw".
941     If you'd like to allow the LXC container to access /dev/null and
942     /dev/zero with read-write access, you can set this parameter to:
943     "c 1:3 rw,c 1:5 rw".
944     The LXC hypervisor drops all direct device access by default, so
945     if you want to allow the LXC container to access an additional
946     device which is not included in the default value of this
947     parameter, you have to set this parameter manually.
948
949     By default, this parameter contains (/dev/null, /dev/zero,
950     /dev/full, /dev/random, /dev/urandom, /dev/aio, /dev/tty,
951     /dev/console, /dev/ptmx and first block of Unix98 PTY slaves) with
952     read-write(rw) access.
953
954 extra\_config
955     Valid for the LXC hypervisor.
956
957     This option specifies the list of extra config parameters which
958     are not supported by the Ganeti LXC hypervisor natively.
959     Each value of this option must be a valid line of the LXC
960     container config file(see: **lxc.container.conf**\(5)).
961
962     This parameter is not set by default.
963
964 num_ttys
965     Valid for the LXC hypervisor.
966
967     This option specifies the number of ttys(actually ptys) that
968     should be allocated for the LXC container.
969     You can disable pty devices allocation for the LXC container by
970     setting this parameter to 0, but you can't use
971     **gnt-instance console** in this case.
972
973     It is set to ``6`` by default.
974
975 The ``-O (--os-parameters)`` option allows customisation of the OS
976 parameters. The actual parameter names and values depend on the OS being
977 used, but the syntax is the same key=value. For example, setting a
978 hypothetical ``dhcp`` parameter to yes can be achieved by::
979
980     gnt-instance add -O dhcp=yes ...
981
982 You can also specify OS parameters that should not be logged but reused
983 at the next reinstall with ``--os-parameters-private`` and OS parameters
984 that should not be logged or saved to configuration with
985 ``--os-parameters-secret``. Bear in mind that:
986
987   * Launching the daemons in debug mode will cause debug logging to
988     happen, which leaks private and secret parameters to the log files.
989     Do not use the debug mode in production. Deamons will emit a warning
990     on startup if they are in debug mode.
991   * You will have to pass again all ``--os-parameters-secret`` parameters
992     should you want to reinstall this instance.
993
994 The ``-I (--iallocator)`` option specifies the instance allocator plugin
995 to use (``.`` means the default allocator). If you pass in this option
996 the allocator will select nodes for this instance automatically, so you
997 don't need to pass them with the ``-n`` option. For more information
998 please refer to the instance allocator documentation.
999
1000 The ``-g (--node-group)`` option can be used to create the instance
1001 in a particular node group, specified by name.
1002
1003 The ``-t (--disk-template)`` options specifies the disk layout type
1004 for the instance. If no disk template is specified, the default disk
1005 template is used. The default disk template is the first in the list
1006 of enabled disk templates, which can be adjusted cluster-wide with
1007 ``gnt-cluster modify``. The available choices for disk templates are:
1008
1009 diskless
1010     This creates an instance with no disks. Its useful for testing only
1011     (or other special cases).
1012
1013 file
1014     Disk devices will be regular files.
1015
1016 sharedfile
1017     Disk devices will be regulare files on a shared directory.
1018
1019 plain
1020     Disk devices will be logical volumes.
1021
1022 drbd
1023     Disk devices will be drbd (version 8.x) on top of lvm volumes.
1024
1025 rbd
1026     Disk devices will be rbd volumes residing inside a RADOS cluster.
1027
1028 blockdev
1029     Disk devices will be adopted pre-existent block devices.
1030
1031 ext
1032     Disk devices will be provided by external shared storage,
1033     through the ExtStorage Interface using ExtStorage providers.
1034
1035 The optional second value of the ``-n (--node)`` is used for the drbd
1036 template type and specifies the remote node.
1037
1038 If you do not want gnt-instance to wait for the disk mirror to be
1039 synced, use the ``--no-wait-for-sync`` option.
1040
1041 The ``--file-storage-dir`` specifies the relative path under the
1042 cluster-wide file storage directory to store file-based disks. It is
1043 useful for having different subdirectories for different
1044 instances. The full path of the directory where the disk files are
1045 stored will consist of cluster-wide file storage directory + optional
1046 subdirectory + instance name. This option is only relevant for
1047 instances using the file storage backend.
1048
1049 The ``--file-driver`` specifies the driver to use for file-based
1050 disks. Note that currently these drivers work with the xen hypervisor
1051 only. This option is only relevant for instances using the file
1052 storage backend. The available choices are:
1053
1054 loop
1055     Kernel loopback driver. This driver uses loopback devices to
1056     access the filesystem within the file. However, running I/O
1057     intensive applications in your instance using the loop driver
1058     might result in slowdowns. Furthermore, if you use the loopback
1059     driver consider increasing the maximum amount of loopback devices
1060     (on most systems it's 8) using the max\_loop param.
1061
1062 blktap
1063     The blktap driver (for Xen hypervisors). In order to be able to
1064     use the blktap driver you should check if the 'blktapctrl' user
1065     space disk agent is running (usually automatically started via
1066     xend).  This user-level disk I/O interface has the advantage of
1067     better performance. Especially if you use a network file system
1068     (e.g. NFS) to store your instances this is the recommended choice.
1069
1070 blktap2
1071     Analogous to the blktap driver, but used by newer versions of Xen.
1072
1073 If ``--ignore-ipolicy`` is given any instance policy violations occuring
1074 during this operation are ignored.
1075
1076 The ``-c`` and ``--communication`` specify whether to enable/disable
1077 instance communication, which is a communication mechanism between the
1078 instance and the host.
1079
1080 See **ganeti**\(7) for a description of ``--submit`` and other common
1081 options.
1082
1083 Example::
1084
1085     # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
1086       -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
1087     # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
1088       -o debian-etch -n node1.example.com instance1.example.com
1089     # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
1090       -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
1091     # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
1092       -n node1.example.com:node2.example.com instance2.example.com
1093     # gnt-instance add -t rbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
1094       -n node1.example.com instance1.example.com
1095     # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1 -B maxmem=512 \
1096       -o debian-etch -n node1.example.com instance1.example.com
1097     # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1,param1=val1 \
1098       --disk 1:size=40g,provider=pvdr2,param2=val2,param3=val3 -B maxmem=512 \
1099       -o debian-etch -n node1.example.com instance1.example.com
1100
1101
1102 BATCH-CREATE
1103 ^^^^^^^^^^^^
1104
1105 | **batch-create**
1106 | [{-I|\--iallocator} *instance allocator*]
1107 | {instances\_file.json}
1108
1109 This command (similar to the Ganeti 1.2 **batcher** tool) submits
1110 multiple instance creation jobs based on a definition file. This
1111 file can contain all options which are valid when adding an instance
1112 with the exception of the ``iallocator`` field. The IAllocator is,
1113 for optimization purposes, only allowed to be set for the whole batch
1114 operation using the ``--iallocator`` parameter.
1115
1116 The instance file must be a valid-formed JSON file, containing an
1117 array of dictionaries with instance creation parameters. All parameters
1118 (except ``iallocator``) which are valid for the instance creation
1119 OP code are allowed. The most important ones are:
1120
1121 instance\_name
1122     The FQDN of the new instance.
1123
1124 disk\_template
1125     The disk template to use for the instance, the same as in the
1126     **add** command.
1127
1128 disks
1129     Array of disk specifications. Each entry describes one disk as a
1130     dictionary of disk parameters.
1131
1132 beparams
1133     A dictionary of backend parameters.
1134
1135 hypervisor
1136     The hypervisor for the instance.
1137
1138 hvparams
1139     A dictionary with the hypervisor options. If not passed, the default
1140     hypervisor options will be inherited.
1141
1142 nics
1143     List of NICs that will be created for the instance. Each entry
1144     should be a dict, with mac, ip, mode and link as possible keys.
1145     Please don't provide the "mac, ip, mode, link" parent keys if you
1146     use this method for specifying NICs.
1147
1148 pnode, snode
1149     The primary and optionally the secondary node to use for the
1150     instance (in case an iallocator script is not used). If those
1151     parameters are given, they have to be given consistently for all
1152     instances in the batch operation.
1153
1154 start
1155     whether to start the instance
1156
1157 ip\_check
1158     Skip the check for already-in-use instance; see the description in
1159     the **add** command for details.
1160
1161 name\_check
1162     Skip the name check for instances; see the description in the
1163     **add** command for details.
1164
1165 file\_storage\_dir, file\_driver
1166     Configuration for the file disk type, see the **add** command for
1167     details.
1168
1169
1170 A simple definition for one instance can be (with most of the
1171 parameters taken from the cluster defaults)::
1172
1173     [
1174       {
1175         "mode": "create",
1176         "instance_name": "instance1.example.com",
1177         "disk_template": "drbd",
1178         "os_type": "debootstrap",
1179         "disks": [{"size":"1024"}],
1180         "nics": [{}],
1181         "hypervisor": "xen-pvm"
1182       },
1183       {
1184         "mode": "create",
1185         "instance_name": "instance2.example.com",
1186         "disk_template": "drbd",
1187         "os_type": "debootstrap",
1188         "disks": [{"size":"4096", "mode": "rw", "vg": "xenvg"}],
1189         "nics": [{}],
1190         "hypervisor": "xen-hvm",
1191         "hvparams": {"acpi": true},
1192         "beparams": {"maxmem": 512, "minmem": 256}
1193       }
1194     ]
1195
1196 The command will display the job id for each submitted instance, as
1197 follows::
1198
1199     # gnt-instance batch-create instances.json
1200     Submitted jobs 37, 38
1201
1202
1203 Note: If the allocator is used for computing suitable nodes for the
1204 instances, it will only take into account disk information for the
1205 default disk template. That means, even if other disk templates are
1206 specified for the instances, storage space information of these disk
1207 templates will not be considered in the allocation computation.
1208
1209
1210 REMOVE
1211 ^^^^^^
1212
1213 | **remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
1214 | [\--print-jobid] [\--force] {*instance*}
1215
1216 Remove an instance. This will remove all data from the instance and
1217 there is *no way back*. If you are not sure if you use an instance
1218 again, use **shutdown** first and leave it in the shutdown state for a
1219 while.
1220
1221 The ``--ignore-failures`` option will cause the removal to proceed
1222 even in the presence of errors during the removal of the instance
1223 (e.g. during the shutdown or the disk removal). If this option is not
1224 given, the command will stop at the first error.
1225
1226 The ``--shutdown-timeout`` is used to specify how much time to wait
1227 before forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the
1228 kvm process for KVM, etc.). By default two minutes are given to each
1229 instance to stop.
1230
1231 The ``--force`` option is used to skip the interactive confirmation.
1232
1233 See **ganeti**\(7) for a description of ``--submit`` and other common
1234 options.
1235
1236 Example::
1237
1238     # gnt-instance remove instance1.example.com
1239
1240
1241 LIST
1242 ^^^^
1243
1244 | **list**
1245 | [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
1246 | [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
1247
1248 Shows the currently configured instances with memory usage, disk
1249 usage, the node they are running on, and their run status.
1250
1251 The ``--no-headers`` option will skip the initial header line. The
1252 ``--separator`` option takes an argument which denotes what will be
1253 used between the output fields. Both these options are to help
1254 scripting.
1255
1256 The units used to display the numeric values in the output varies,
1257 depending on the options given. By default, the values will be
1258 formatted in the most appropriate unit. If the ``--separator`` option
1259 is given, then the values are shown in mebibytes to allow parsing by
1260 scripts. In both cases, the ``--units`` option can be used to enforce
1261 a given output unit.
1262
1263 The ``-v`` option activates verbose mode, which changes the display of
1264 special field states (see **ganeti**\(7)).
1265
1266 The ``-o (--output)`` option takes a comma-separated list of output
1267 fields. The available fields and their meaning are:
1268
1269 @QUERY_FIELDS_INSTANCE@
1270
1271 If the value of the option starts with the character ``+``, the new
1272 field(s) will be added to the default list. This allows one to quickly
1273 see the default list plus a few other fields, instead of retyping the
1274 entire list of fields.
1275
1276 There is a subtle grouping about the available output fields: all
1277 fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
1278 ``status`` are configuration value and not run-time values. So if you
1279 don't select any of the these fields, the query will be satisfied
1280 instantly from the cluster configuration, without having to ask the
1281 remote nodes for the data. This can be helpful for big clusters when
1282 you only want some data and it makes sense to specify a reduced set of
1283 output fields.
1284
1285 If exactly one argument is given and it appears to be a query filter
1286 (see **ganeti**\(7)), the query result is filtered accordingly. For
1287 ambiguous cases (e.g. a single field name as a filter) the ``--filter``
1288 (``-F``) option forces the argument to be treated as a filter (e.g.
1289 ``gnt-instance list -F admin_state``).
1290
1291 The default output field list is: ``name``, ``os``, ``pnode``,
1292 ``admin_state``, ``oper_state``, ``oper_ram``.
1293
1294
1295 LIST-FIELDS
1296 ^^^^^^^^^^^
1297
1298 **list-fields** [field...]
1299
1300 Lists available fields for instances.
1301
1302
1303 INFO
1304 ^^^^
1305
1306 **info** [-s \| \--static] [\--roman] {\--all \| *instance*}
1307
1308 Show detailed information about the given instance(s). This is
1309 different from **list** as it shows detailed data about the instance's
1310 disks (especially useful for the drbd disk template).
1311
1312 If the option ``-s`` is used, only information available in the
1313 configuration file is returned, without querying nodes, making the
1314 operation faster.
1315
1316 Use the ``--all`` to get info about all instances, rather than
1317 explicitly passing the ones you're interested in.
1318
1319 The ``--roman`` option can be used to cause envy among people who like
1320 ancient cultures, but are stuck with non-latin-friendly cluster
1321 virtualization technologies.
1322
1323 MODIFY
1324 ^^^^^^
1325
1326 | **modify**
1327 | [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
1328 | [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
1329 | [{-m|\--runtime-memory} *SIZE*]
1330 | [\--net add[:options...] \|
1331 |  \--net [*N*:]add[,options...] \|
1332 |  \--net [*ID*:]remove \|
1333 |  \--net *ID*:modify[,options...]]
1334 | [\--disk add:size=*SIZE*[,options...] \|
1335 |  \--disk *N*:add,size=*SIZE*[,options...] \|
1336 |  \--disk *N*:add,size=*SIZE*,provider=*PROVIDER*[,options...][,param=*value*... ] \|
1337 |  \--disk *ID*:modify[,options...]
1338 |  \--disk [*ID*:]remove]
1339 | [\{-t|\--disk-template} { plain | rbd } \|
1340 |  \{-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync] \|
1341 |  \{-t|\--disk-template} ext {-e|--ext-params} {provider=*PROVIDER*}[,param=*value*... ] \|
1342 |  \{-t|\--disk-template} { file | sharedfile | gluster }
1343 |  \| [--file-storage-dir dir_path] [--file-driver {loop | blktap | blktap2}]
1344 | [\--new-primary=*node*]
1345 | [\--os-type=*OS* [\--force-variant]]
1346 | [{-O|\--os-parameters} *param*=*value*... ]
1347 | [--os-parameters-private *param*=*value*... ]
1348 | [\--offline \| \--online]
1349 | [\--submit] [\--print-jobid]
1350 | [\--ignore-ipolicy]
1351 | [\--hotplug]
1352 | [\--hotplug-if-possible]
1353 | {*instance*}
1354
1355 Modifies the memory size, number of vcpus, ip address, MAC address
1356 and/or NIC parameters for an instance. It can also add and remove
1357 disks and NICs to/from the instance. Note that you need to give at
1358 least one of the arguments, otherwise the command complains.
1359
1360 The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
1361 and ``-O (--os-parameters)`` options specifies hypervisor, backend and
1362 OS parameter options in the form of name=value[,...]. For details
1363 which options can be specified, see the **add** command.
1364
1365 The ``-t (--disk-template)`` option will change the disk template of
1366 the instance.  Currently, conversions between all the available
1367 templates are supported, except the ``diskless`` and the ``blockdev``
1368 templates. For the ``blockdev`` disk template, only partial support is
1369 provided and acts only as a source template. Since these volumes are
1370 adopted pre-existent block devices, conversions targeting this template
1371 are not supported. Also, there is no support for conversions to or from
1372 the ``diskless`` template. The instance must be stopped before
1373 attempting the conversion. When changing from the plain to the drbd
1374 disk template, a new secondary node must be specified via the ``-n``
1375 option. The option ``--no-wait-for-sync`` can be used when converting
1376 to the ``drbd`` template in order to make the instance available for
1377 startup before DRBD has finished resyncing. When changing to a
1378 file-based disk template, i.e., ``file``, ``sharedfile`` and
1379 ``gluster``, the file storage directory and the file driver can be
1380 specified via the ``--file-storage-dir`` and ``--file-driver`` options,
1381 respectively. For more details on these options please refer to the
1382 **add** command section. When changing to an ``ext`` template, the
1383 provider's name must be specified. Also, arbitrary parameters can be
1384 passed, as additional comma separated options. Those parameters along
1385 with the ExtStorage provider must be passed using either the
1386 ``--ext-params`` or ``-e`` option. It is not allowed specifying existing
1387 disk parameters such as the size, mode, name, access, adopt, vg, metavg,
1388 provider, or spindles options.
1389
1390 The ``-m (--runtime-memory)`` option will change an instance's runtime
1391 memory to the given size (in MB if a different suffix is not specified),
1392 by ballooning it up or down to the new value.
1393
1394 The ``--disk add:size=*SIZE*,[options..]`` option adds a disk to the
1395 instance, and ``--disk *N*:add:size=*SIZE*,[options..]`` will add a disk
1396 to the the instance at a specific index. The available options are the
1397 same as in the **add** command (``spindles``, ``mode``, ``name``, ``vg``,
1398 ``metavg`` and ``access``). Per default, gnt-instance waits for the disk
1399 mirror to sync.
1400 If you do not want this behavior, use the ``--no-wait-for-sync`` option.
1401 When adding an ExtStorage disk, the ``provider=*PROVIDER*`` option is
1402 also mandatory and specifies the ExtStorage provider. Also, for
1403 ExtStorage disks arbitrary parameters can be passed as additional comma
1404 separated options, same as in the **add** command. The ``--disk remove``
1405 option will remove the last disk of the instance. Use
1406 ``--disk `` *ID*``:remove`` to remove a disk by its identifier. *ID*
1407 can be the index of the disk, the disks's name or the disks's UUID. The
1408 ``--disk *ID*:modify[,options...]`` will change the options of the disk.
1409 Available options are:
1410
1411 mode
1412   The access mode. Either ``ro`` (read-only) or the default ``rw`` (read-write).
1413
1414 name
1415    This option specifies a name for the disk, which can be used as a disk
1416    identifier. An instance can not have two disks with the same name.
1417
1418 The ``--net *N*:add[,options..]`` will add a new network interface to
1419 the instance. The available options are the same as in the **add**
1420 command (``mac``, ``ip``, ``link``, ``mode``, ``network``). The
1421 ``--net *ID*,remove`` will remove the intances' NIC with *ID* identifier,
1422 which can be the index of the NIC, the NIC's name or the NIC's UUID.
1423 The ``--net *ID*:modify[,options..]`` option will change the parameters of
1424 the instance network interface with the *ID* identifier.
1425
1426 The option ``-o (--os-type)`` will change the OS name for the instance
1427 (without reinstallation). In case an OS variant is specified that is
1428 not found, then by default the modification is refused, unless
1429 ``--force-variant`` is passed. An invalid OS will also be refused,
1430 unless the ``--force`` option is given.
1431
1432 The option ``--new-primary`` will set the new primary node of an instance
1433 assuming the disks have already been moved manually. Unless the ``--force``
1434 option is given, it is verified that the instance is no longer running
1435 on its current primary node.
1436
1437 The ``--online`` and ``--offline`` options are used to transition an
1438 instance into and out of the ``offline`` state. An instance can be
1439 turned offline only if it was previously down. The ``--online`` option
1440 fails if the instance was not in the ``offline`` state, otherwise it
1441 changes instance's state to ``down``. These modifications take effect
1442 immediately.
1443
1444 If ``--ignore-ipolicy`` is given any instance policy violations occuring
1445 during this operation are ignored.
1446
1447 If ``--hotplug`` is given any disk and NIC modifications will take
1448 effect without the need of actual reboot. Please note that this feature
1449 is currently supported only for KVM hypervisor and there are some
1450 restrictions: a) NIC/Disk hot-remove should work for QEMU versions >= 1.0
1451 b) instances with chroot or pool/user security model support disk
1452 hot-add only for QEMU version > 1.7 where add-fd QMP command exists c) For
1453 the previous case as well as for NIC hot-add, python-fdsend package must
1454 be installed d) if hotplug fails (for any reason) a warning is printed
1455 but execution is continued e) for existing NIC modification interactive
1456 verification is needed unless ``--force`` option is passed.
1457
1458 If ``--hotplug-if-possible`` is given then ganeti won't abort in case
1459 hotplug is not supported. It will continue execution and modification
1460 will take place after reboot. This covers use cases where instances are
1461 not running or hypervisor is not KVM.
1462
1463 See **ganeti**\(7) for a description of ``--submit`` and other common
1464 options.
1465
1466 Most of the changes take effect at the next restart. If the instance is
1467 running, there is no effect on the instance.
1468
1469 REINSTALL
1470 ^^^^^^^^^
1471
1472 | **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
1473 | [\--force-multiple]
1474 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1475 | [{-O|\--os-parameters} *OS\_PARAMETERS*]
1476 | [--os-parameters-private} *OS\_PARAMETERS*]
1477 | [--os-parameters-secret} *OS\_PARAMETERS*]
1478 | [\--submit] [\--print-jobid]
1479 | {*instance*...}
1480
1481 Reinstalls the operating system on the given instance(s). The
1482 instance(s) must be stopped when running this command. If the ``-o
1483 (--os-type)`` is specified, the operating system is changed.
1484
1485 The ``--select-os`` option switches to an interactive OS reinstall.
1486 The user is prompted to select the OS template from the list of
1487 available OS templates. OS parameters can be overridden using ``-O
1488 (--os-parameters)`` (more documentation for this option under the
1489 **add** command).
1490
1491 Since this is a potentially dangerous command, the user will be
1492 required to confirm this action, unless the ``-f`` flag is passed.
1493 When multiple instances are selected (either by passing multiple
1494 arguments or by using the ``--node``, ``--primary``, ``--secondary``
1495 or ``--all`` options), the user must pass the ``--force-multiple``
1496 options to skip the interactive confirmation.
1497
1498 See **ganeti**\(7) for a description of ``--submit`` and other common
1499 options.
1500
1501 RENAME
1502 ^^^^^^
1503
1504 | **rename** [\--no-ip-check] [\--no-name-check] [\--submit] [\--print-jobid]
1505 | {*instance*} {*new\_name*}
1506
1507 Renames the given instance. The instance must be stopped when running
1508 this command. The requirements for the new name are the same as for
1509 adding an instance: the new name must be resolvable and the IP it
1510 resolves to must not be reachable (in order to prevent duplicate IPs
1511 the next time the instance is started). The IP test can be skipped if
1512 the ``--no-ip-check`` option is passed.
1513
1514 Note that you can rename an instance to its same name, to force
1515 re-executing the os-specific rename script for that instance, if
1516 needed.
1517
1518 The ``--no-name-check`` skips the check for the new instance name via
1519 the resolver (e.g. in DNS or /etc/hosts, depending on your setup) and
1520 that the resolved name matches the provided name. Since the name check
1521 is used to compute the IP address, if you pass this option you must also
1522 pass the ``--no-ip-check`` option.
1523
1524 See **ganeti**\(7) for a description of ``--submit`` and other common
1525 options.
1526
1527 Starting/stopping/connecting to console
1528 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1529
1530 STARTUP
1531 ^^^^^^^
1532
1533 | **startup**
1534 | [\--force] [\--ignore-offline]
1535 | [\--force-multiple] [\--no-remember]
1536 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1537 | \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1538 | [{-H|\--hypervisor-parameters} ``key=value...``]
1539 | [{-B|\--backend-parameters} ``key=value...``]
1540 | [\--submit] [\--print-jobid] [\--paused]
1541 | {*name*...}
1542
1543 Starts one or more instances, depending on the following options.  The
1544 four available modes are:
1545
1546 \--instance
1547     will start the instances given as arguments (at least one argument
1548     required); this is the default selection
1549
1550 \--node
1551     will start the instances who have the given node as either primary
1552     or secondary
1553
1554 \--primary
1555     will start all instances whose primary node is in the list of nodes
1556     passed as arguments (at least one node required)
1557
1558 \--secondary
1559     will start all instances whose secondary node is in the list of
1560     nodes passed as arguments (at least one node required)
1561
1562 \--all
1563     will start all instances in the cluster (no arguments accepted)
1564
1565 \--tags
1566     will start all instances in the cluster with the tags given as
1567     arguments
1568
1569 \--node-tags
1570     will start all instances in the cluster on nodes with the tags
1571     given as arguments
1572
1573 \--pri-node-tags
1574     will start all instances in the cluster on primary nodes with the
1575     tags given as arguments
1576
1577 \--sec-node-tags
1578     will start all instances in the cluster on secondary nodes with the
1579     tags given as arguments
1580
1581 Note that although you can pass more than one selection option, the
1582 last one wins, so in order to guarantee the desired result, don't pass
1583 more than one such option.
1584
1585 Use ``--force`` to start even if secondary disks are failing.
1586 ``--ignore-offline`` can be used to ignore offline primary nodes and
1587 mark the instance as started even if the primary is not available.
1588
1589 The ``--force-multiple`` will skip the interactive confirmation in the
1590 case the more than one instance will be affected.
1591
1592 The ``--no-remember`` option will perform the startup but not change
1593 the state of the instance in the configuration file (if it was stopped
1594 before, Ganeti will still think it needs to be stopped). This can be
1595 used for testing, or for a one shot-start where you don't want the
1596 watcher to restart the instance if it crashes.
1597
1598 The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
1599 options specify temporary hypervisor and backend parameters that can
1600 be used to start an instance with modified parameters. They can be
1601 useful for quick testing without having to modify an instance back and
1602 forth, e.g.::
1603
1604     # gnt-instance start -H kernel_args="single" instance1
1605     # gnt-instance start -B maxmem=2048 instance2
1606
1607
1608 The first form will start the instance instance1 in single-user mode,
1609 and the instance instance2 with 2GB of RAM (this time only, unless
1610 that is the actual instance memory size already). Note that the values
1611 override the instance parameters (and not extend them): an instance
1612 with "kernel\_args=ro" when started with -H kernel\_args=single will
1613 result in "single", not "ro single".
1614
1615 The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
1616 pauses the instance at the start of bootup, awaiting ``gnt-instance
1617 console`` to unpause it, allowing the entire boot process to be
1618 monitored for debugging.
1619
1620 See **ganeti**\(7) for a description of ``--submit`` and other common
1621 options.
1622
1623 Example::
1624
1625     # gnt-instance start instance1.example.com
1626     # gnt-instance start --node node1.example.com node2.example.com
1627     # gnt-instance start --all
1628
1629
1630 SHUTDOWN
1631 ^^^^^^^^
1632
1633 | **shutdown**
1634 | [\--timeout=*N*]
1635 | [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember]
1636 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1637 | \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1638 | [\--submit] [\--print-jobid]
1639 | {*name*...}
1640
1641 Stops one or more instances. If the instance cannot be cleanly stopped
1642 during a hardcoded interval (currently 2 minutes), it will forcibly
1643 stop the instance (equivalent to switching off the power on a physical
1644 machine).
1645
1646 The ``--timeout`` is used to specify how much time to wait before
1647 forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the kvm
1648 process for KVM, etc.). By default two minutes are given to each
1649 instance to stop.
1650
1651 The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1652 ``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1653 ``--sec-node-tags`` options are similar as for the **startup** command
1654 and they influence the actual instances being shutdown.
1655
1656 ``--ignore-offline`` can be used to ignore offline primary nodes and
1657 force the instance to be marked as stopped. This option should be used
1658 with care as it can lead to an inconsistent cluster state.
1659
1660 Use ``--force`` to be able to shutdown an instance even when it's marked
1661 as offline. This is useful is an offline instance ends up in the
1662 ``ERROR_up`` state, for example.
1663
1664 The ``--no-remember`` option will perform the shutdown but not change
1665 the state of the instance in the configuration file (if it was running
1666 before, Ganeti will still thinks it needs to be running). This can be
1667 useful for a cluster-wide shutdown, where some instances are marked as
1668 up and some as down, and you don't want to change the running state:
1669 you just need to disable the watcher, shutdown all instances with
1670 ``--no-remember``, and when the watcher is activated again it will
1671 restore the correct runtime state for all instances.
1672
1673 See **ganeti**\(7) for a description of ``--submit`` and other common
1674 options.
1675
1676 Example::
1677
1678     # gnt-instance shutdown instance1.example.com
1679     # gnt-instance shutdown --all
1680
1681
1682 REBOOT
1683 ^^^^^^
1684
1685 | **reboot**
1686 | [{-t|\--type} *REBOOT-TYPE*]
1687 | [\--ignore-secondaries]
1688 | [\--shutdown-timeout=*N*]
1689 | [\--force-multiple]
1690 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1691 | \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1692 | [\--submit] [\--print-jobid]
1693 | [*name*...]
1694
1695 Reboots one or more instances. The type of reboot depends on the value
1696 of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1697 does a instance stop, recreates the hypervisor config for the instance
1698 and starts the instance. A full reboot does the equivalent of
1699 **gnt-instance shutdown && gnt-instance startup**.  The default is
1700 hard reboot.
1701
1702 For the hard reboot the option ``--ignore-secondaries`` ignores errors
1703 for the secondary node while re-assembling the instance disks.
1704
1705 The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1706 ``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1707 ``--sec-node-tags`` options are similar as for the **startup** command
1708 and they influence the actual instances being rebooted.
1709
1710 The ``--shutdown-timeout`` is used to specify how much time to wait
1711 before forcing the shutdown (xm destroy in xen, killing the kvm
1712 process, for kvm). By default two minutes are given to each instance
1713 to stop.
1714
1715 The ``--force-multiple`` will skip the interactive confirmation in the
1716 case the more than one instance will be affected.
1717
1718 See **ganeti**\(7) for a description of ``--submit`` and other common
1719 options.
1720
1721 Example::
1722
1723     # gnt-instance reboot instance1.example.com
1724     # gnt-instance reboot --type=full instance1.example.com
1725
1726
1727 CONSOLE
1728 ^^^^^^^
1729
1730 **console** [\--show-cmd] {*instance*}
1731
1732 Connects to the console of the given instance. If the instance is not
1733 up, an error is returned. Use the ``--show-cmd`` option to display the
1734 command instead of executing it.
1735
1736 For HVM instances, this will attempt to connect to the serial console
1737 of the instance. To connect to the virtualized "physical" console of a
1738 HVM instance, use a VNC client with the connection info from the
1739 **info** command.
1740
1741 For Xen/kvm instances, if the instance is paused, this attempts to
1742 unpause the instance after waiting a few seconds for the connection to
1743 the console to be made.
1744
1745 Example::
1746
1747     # gnt-instance console instance1.example.com
1748
1749
1750 Disk management
1751 ~~~~~~~~~~~~~~~
1752
1753 REPLACE-DISKS
1754 ^^^^^^^^^^^^^
1755
1756 | **replace-disks** [\--submit] [\--print-jobid] [\--early-release]
1757 | [\--ignore-ipolicy] {-p} [\--disks *idx*] {*instance*}
1758
1759 | **replace-disks** [\--submit] [\--print-jobid] [\--early-release]
1760 | [\--ignore-ipolicy] {-s} [\--disks *idx*] {*instance*}
1761
1762 | **replace-disks** [\--submit] [\--print-jobid] [\--early-release]
1763 | [\--ignore-ipolicy]
1764 | {{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*}
1765
1766 | **replace-disks** [\--submit] [\--print-jobid] [\--early-release]
1767 | [\--ignore-ipolicy] {-a\|\--auto} {*instance*}
1768
1769 This command is a generalized form for replacing disks. It is
1770 currently only valid for the mirrored (DRBD) disk template.
1771
1772 The first form (when passing the ``-p`` option) will replace the disks
1773 on the primary, while the second form (when passing the ``-s`` option
1774 will replace the disks on the secondary node. For these two cases (as
1775 the node doesn't change), it is possible to only run the replace for a
1776 subset of the disks, using the option ``--disks`` which takes a list
1777 of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only
1778 the first and third disks.
1779
1780 The third form (when passing either the ``--iallocator`` or the
1781 ``--new-secondary`` option) is designed to change secondary node of the
1782 instance. Specifying ``--iallocator`` makes the new secondary be
1783 selected automatically by the specified allocator plugin (use ``.`` to
1784 indicate the default allocator), otherwise the new secondary node will
1785 be the one chosen manually via the ``--new-secondary`` option.
1786
1787 Note that it is not possible to select an offline or drained node as a
1788 new secondary.
1789
1790 The fourth form (when using ``--auto``) will automatically determine
1791 which disks of an instance are faulty and replace them within the same
1792 node. The ``--auto`` option works only when an instance has only
1793 faulty disks on either the primary or secondary node; it doesn't work
1794 when both sides have faulty disks.
1795
1796 The ``--early-release`` changes the code so that the old storage on
1797 secondary node(s) is removed early (before the resync is completed)
1798 and the internal Ganeti locks for the current (and new, if any)
1799 secondary node are also released, thus allowing more parallelism in
1800 the cluster operation. This should be used only when recovering from a
1801 disk failure on the current secondary (thus the old storage is already
1802 broken) or when the storage on the primary node is known to be fine
1803 (thus we won't need the old storage for potential recovery).
1804
1805 The ``--ignore-ipolicy`` let the command ignore instance policy
1806 violations if replace-disks changes groups and the instance would
1807 violate the new groups instance policy.
1808
1809 See **ganeti**\(7) for a description of ``--submit`` and other common
1810 options.
1811
1812 ACTIVATE-DISKS
1813 ^^^^^^^^^^^^^^
1814
1815 | **activate-disks** [\--submit] [\--print-jobid] [\--ignore-size]
1816 | [\--wait-for-sync] {*instance*}
1817
1818 Activates the block devices of the given instance. If successful, the
1819 command will show the location and name of the block devices::
1820
1821     node1.example.com:disk/0:/dev/drbd0
1822     node1.example.com:disk/1:/dev/drbd1
1823
1824
1825 In this example, *node1.example.com* is the name of the node on which
1826 the devices have been activated. The *disk/0* and *disk/1* are the
1827 Ganeti-names of the instance disks; how they are visible inside the
1828 instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the
1829 actual block devices as visible on the node.
1830
1831 The ``--ignore-size`` option can be used to activate disks ignoring
1832 the currently configured size in Ganeti. This can be used in cases
1833 where the configuration has gotten out of sync with the real-world
1834 (e.g. after a partially-failed grow-disk operation or due to rounding
1835 in LVM devices). This should not be used in normal cases, but only
1836 when activate-disks fails without it.
1837
1838 The ``--wait-for-sync`` option will ensure that the command returns only
1839 after the instance's disks are synchronised (mostly for DRBD); this can
1840 be useful to ensure consistency, as otherwise there are no commands that
1841 can wait until synchronisation is done. However when passing this
1842 option, the command will have additional output, making it harder to
1843 parse the disk information.
1844
1845 Note that it is safe to run this command while the instance is already
1846 running.
1847
1848 See **ganeti**\(7) for a description of ``--submit`` and other common
1849 options.
1850
1851 DEACTIVATE-DISKS
1852 ^^^^^^^^^^^^^^^^
1853
1854 **deactivate-disks** [-f] [\--submit] [\--print-jobid] {*instance*}
1855
1856 De-activates the block devices of the given instance. Note that if you
1857 run this command for an instance with a drbd disk template, while it
1858 is running, it will not be able to shutdown the block devices on the
1859 primary node, but it will shutdown the block devices on the secondary
1860 nodes, thus breaking the replication.
1861
1862 The ``-f``/``--force`` option will skip checks that the instance is
1863 down; in case the hypervisor is confused and we can't talk to it,
1864 normally Ganeti will refuse to deactivate the disks, but with this
1865 option passed it will skip this check and directly try to deactivate
1866 the disks. This can still fail due to the instance actually running or
1867 other issues.
1868
1869 See **ganeti**\(7) for a description of ``--submit`` and other common
1870 options.
1871
1872 GROW-DISK
1873 ^^^^^^^^^
1874
1875 | **grow-disk** [\--no-wait-for-sync] [\--submit] [\--print-jobid]
1876 | [\--absolute]
1877 | {*instance*} {*disk*} {*amount*}
1878
1879 Grows an instance's disk. This is only possible for instances having a
1880 plain, drbd, file, sharedfile, rbd or ext disk template. For the ext
1881 template to work, the ExtStorage provider should also support growing.
1882 This means having a ``grow`` script that actually grows the volume of
1883 the external shared storage.
1884
1885 Note that this command only change the block device size; it will not
1886 grow the actual filesystems, partitions, etc. that live on that
1887 disk. Usually, you will need to:
1888
1889 #. use **gnt-instance grow-disk**
1890
1891 #. reboot the instance (later, at a convenient time)
1892
1893 #. use a filesystem resizer, such as **ext2online**\(8) or
1894    **xfs\_growfs**\(8) to resize the filesystem, or use **fdisk**\(8) to
1895    change the partition table on the disk
1896
1897 The *disk* argument is the index of the instance disk to grow. The
1898 *amount* argument is given as a number which can have a suffix (like the
1899 disk size in instance create); if the suffix is missing, the value will
1900 be interpreted as mebibytes.
1901
1902 By default, the *amount* value represents the desired increase in the
1903 disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If
1904 the optional ``--absolute`` parameter is passed, then the *amount*
1905 argument doesn't represent the delta, but instead the desired final disk
1906 size (e.g. an amount of 8G will take a disk of size 4G to 8G).
1907
1908 For instances with a drbd template, note that the disk grow operation
1909 might complete on one node but fail on the other; this will leave the
1910 instance with different-sized LVs on the two nodes, but this will not
1911 create problems (except for unused space).
1912
1913 If you do not want gnt-instance to wait for the new disk region to be
1914 synced, use the ``--no-wait-for-sync`` option.
1915
1916 See **ganeti**\(7) for a description of ``--submit`` and other common
1917 options.
1918
1919 Example (increase the first disk for instance1 by 16GiB)::
1920
1921     # gnt-instance grow-disk instance1.example.com 0 16g
1922
1923 Example for increasing the disk size to a certain size::
1924
1925    # gnt-instance grow-disk --absolute instance1.example.com 0 32g
1926
1927 Also note that disk shrinking is not supported; use **gnt-backup
1928 export** and then **gnt-backup import** to reduce the disk size of an
1929 instance.
1930
1931 RECREATE-DISKS
1932 ^^^^^^^^^^^^^^
1933
1934 | **recreate-disks** [\--submit] [\--print-jobid]
1935 | [{-n node1:[node2] \| {-I\|\--iallocator *name*}}]
1936 | [\--disk=*N*[:[size=*VAL*][,spindles=*VAL*][,mode=*ro\|rw*]]] {*instance*}
1937
1938 Recreates all or a subset of disks of the given instance.
1939
1940 Note that this functionality should only be used for missing disks; if
1941 any of the given disks already exists, the operation will fail.  While
1942 this is suboptimal, recreate-disks should hopefully not be needed in
1943 normal operation and as such the impact of this is low.
1944
1945 If only a subset should be recreated, any number of ``disk`` options can
1946 be specified. It expects a disk index and an optional list of disk
1947 parameters to change. Only ``size``, ``spindles``, and ``mode`` can be
1948 changed while recreating disks. To recreate all disks while changing
1949 parameters on a subset only, a ``--disk`` option must be given for every
1950 disk of the instance.
1951
1952 Optionally the instance's disks can be recreated on different
1953 nodes. This can be useful if, for example, the original nodes of the
1954 instance have gone down (and are marked offline), so we can't recreate
1955 on the same nodes. To do this, pass the new node(s) via ``-n`` option,
1956 with a syntax similar to the **add** command. The number of nodes
1957 passed must equal the number of nodes that the instance currently
1958 has. Note that changing nodes is only allowed when all disks are
1959 replaced, e.g. when no ``--disk`` option is passed.
1960
1961 Another method of choosing which nodes to place the instance on is by
1962 using the specified iallocator, passing the ``--iallocator`` option.
1963 The primary and secondary nodes will be chosen by the specified
1964 iallocator plugin, or by the default allocator if ``.`` is specified.
1965
1966 See **ganeti**\(7) for a description of ``--submit`` and other common
1967 options.
1968
1969 Recovery/moving
1970 ~~~~~~~~~~~~~~~
1971
1972 FAILOVER
1973 ^^^^^^^^
1974
1975 | **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy]
1976 | [\--shutdown-timeout=*N*]
1977 | [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*]
1978 | [\--cleanup]
1979 | [\--submit] [\--print-jobid]
1980 | {*instance*}
1981
1982 Failover will stop the instance (if running), change its primary node,
1983 and if it was originally running it will start it again (on the new
1984 primary). This works for instances with drbd template (in which case you
1985 can only fail to the secondary node) and for externally mirrored
1986 templates (sharedfile, blockdev, rbd and ext) (in which case you can
1987 fail to any other node).
1988
1989 If the instance's disk template is of type sharedfile, blockdev, rbd or
1990 ext, then you can explicitly specify the target node (which can be any
1991 node) using the ``-n`` or ``--target-node`` option, or specify an
1992 iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
1993 omit both, the default iallocator will be used to specify the target
1994 node.
1995
1996 If the instance's disk template is of type drbd, the target node is
1997 automatically selected as the drbd's secondary node. Changing the
1998 secondary node is possible with a replace-disks operation.
1999
2000 Normally the failover will check the consistency of the disks before
2001 failing over the instance. If you are trying to migrate instances off
2002 a dead node, this will fail. Use the ``--ignore-consistency`` option
2003 for this purpose. Note that this option can be dangerous as errors in
2004 shutting down the instance will be ignored, resulting in possibly
2005 having the instance running on two machines in parallel (on
2006 disconnected DRBD drives).
2007
2008 The ``--shutdown-timeout`` is used to specify how much time to wait
2009 before forcing the shutdown (xm destroy in xen, killing the kvm
2010 process, for kvm). By default two minutes are given to each instance
2011 to stop.
2012
2013 If ``--ignore-ipolicy`` is given any instance policy violations occuring
2014 during this operation are ignored.
2015
2016 If the ``--cleanup`` option is passed, the operation changes from
2017 performin a failover to attempting recovery from a failed previous failover.
2018 In this mode, Ganeti checks if the instance runs on the correct node (and
2019 updates its configuration if not) and ensures the instances' disks
2020 are configured correctly.
2021
2022 See **ganeti**\(7) for a description of ``--submit`` and other common
2023 options.
2024
2025 Example::
2026
2027     # gnt-instance failover instance1.example.com
2028
2029 For externally mirrored templates also ``-n`` is available::
2030
2031     # gnt-instance failover -n node3.example.com instance1.example.com
2032
2033
2034 MIGRATE
2035 ^^^^^^^
2036
2037 | **migrate** [-f] [\--allow-failover] [\--non-live]
2038 | [\--migration-mode=live\|non-live] [\--ignore-ipolicy] [\--ignore-hvversions]
2039 | [\--no-runtime-changes] [\--submit] [\--print-jobid]
2040 | [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*}
2041
2042 | **migrate** [-f] \--cleanup [\--submit] [\--print-jobid] {*instance*}
2043
2044 Migrate will move the instance to its secondary node without shutdown.
2045 As with failover, it works for instances having the drbd disk template
2046 or an externally mirrored disk template type such as sharedfile,
2047 blockdev, rbd or ext.
2048
2049 If the instance's disk template is of type sharedfile, blockdev, rbd or
2050 ext, then you can explicitly specify the target node (which can be any
2051 node) using the ``-n`` or ``--target-node`` option, or specify an
2052 iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
2053 omit both, the default iallocator will be used to specify the target
2054 node.  Alternatively, the default iallocator can be requested by
2055 specifying ``.`` as the name of the plugin.
2056
2057 If the instance's disk template is of type drbd, the target node is
2058 automatically selected as the drbd's secondary node. Changing the
2059 secondary node is possible with a replace-disks operation.
2060
2061 The migration command needs a perfectly healthy instance for drbd
2062 instances, as we rely on the dual-master capability of drbd8 and the
2063 disks of the instance are not allowed to be degraded.
2064
2065 The ``--non-live`` and ``--migration-mode=non-live`` options will
2066 switch (for the hypervisors that support it) between a "fully live"
2067 (i.e. the interruption is as minimal as possible) migration and one in
2068 which the instance is frozen, its state saved and transported to the
2069 remote node, and then resumed there. This all depends on the
2070 hypervisor support for two different methods. In any case, it is not
2071 an error to pass this parameter (it will just be ignored if the
2072 hypervisor doesn't support it). The option ``--migration-mode=live``
2073 option will request a fully-live migration. The default, when neither
2074 option is passed, depends on the hypervisor parameters (and can be
2075 viewed with the **gnt-cluster info** command).
2076
2077 If the ``--cleanup`` option is passed, the operation changes from
2078 migration to attempting recovery from a failed previous migration. In
2079 this mode, Ganeti checks if the instance runs on the correct node (and
2080 updates its configuration if not) and ensures the instances' disks
2081 are configured correctly. In this mode, the ``--non-live`` option is
2082 ignored.
2083
2084 The option ``-f`` will skip the prompting for confirmation.
2085
2086 If ``--allow-failover`` is specified it tries to fallback to failover if
2087 it already can determine that a migration won't work (e.g. if the
2088 instance is shut down). Please note that the fallback will not happen
2089 during execution. If a migration fails during execution it still fails.
2090
2091 If ``--ignore-ipolicy`` is given any instance policy violations occuring
2092 during this operation are ignored.
2093
2094 Normally, Ganeti will verify that the hypervisor versions on source
2095 and target are compatible and error out if they are not. If
2096 ``--ignore-hvversions`` is given, Ganeti will only warn in this case.
2097
2098 The ``--no-runtime-changes`` option forbids migrate to alter an
2099 instance's runtime before migrating it (eg. ballooning an instance
2100 down because the target node doesn't have enough available memory).
2101
2102 If an instance has the backend parameter ``always_failover`` set to
2103 true, then the migration is automatically converted into a failover.
2104
2105 See **ganeti**\(7) for a description of ``--submit`` and other common
2106 options.
2107
2108 Example (and expected output)::
2109
2110     # gnt-instance migrate instance1
2111     Instance instance1 will be migrated. Note that migration
2112     might impact the instance if anything goes wrong (e.g. due to bugs in
2113     the hypervisor). Continue?
2114     y/[n]/?: y
2115     Migrating instance instance1.example.com
2116     * checking disk consistency between source and target
2117     * switching node node2.example.com to secondary mode
2118     * changing into standalone mode
2119     * changing disks into dual-master mode
2120     * wait until resync is done
2121     * preparing node2.example.com to accept the instance
2122     * migrating instance to node2.example.com
2123     * switching node node1.example.com to secondary mode
2124     * wait until resync is done
2125     * changing into standalone mode
2126     * changing disks into single-master mode
2127     * wait until resync is done
2128     * done
2129     #
2130
2131
2132 MOVE
2133 ^^^^
2134
2135 | **move** [-f] [\--ignore-consistency]
2136 | [-n *node*] [\--compress=*compression-mode*] [\--shutdown-timeout=*N*]
2137 | [\--submit] [\--print-jobid] [\--ignore-ipolicy]
2138 | {*instance*}
2139
2140 Move will move the instance to an arbitrary node in the cluster. This
2141 works only for instances having a plain or file disk template.
2142
2143 Note that since this operation is done via data copy, it will take a
2144 long time for big disks (similar to replace-disks for a drbd
2145 instance).
2146
2147 The ``--compress`` option is used to specify which compression mode
2148 is used during the move. Valid values are 'none' (the default) and any
2149 values specified in the 'compression_tools' cluster parameter.
2150
2151 The ``--shutdown-timeout`` is used to specify how much time to wait
2152 before forcing the shutdown (e.g. ``xm destroy`` in XEN, killing the
2153 kvm process for KVM, etc.). By default two minutes are given to each
2154 instance to stop.
2155
2156 The ``--ignore-consistency`` option will make Ganeti ignore any errors
2157 in trying to shutdown the instance on its node; useful if the
2158 hypervisor is broken and you want to recover the data.
2159
2160 If ``--ignore-ipolicy`` is given any instance policy violations occuring
2161 during this operation are ignored.
2162
2163 See **ganeti**\(7) for a description of ``--submit`` and other common
2164 options.
2165
2166 Example::
2167
2168     # gnt-instance move -n node3.example.com instance1.example.com
2169
2170
2171 CHANGE-GROUP
2172 ^^^^^^^^^^^^
2173
2174 | **change-group** [\--submit] [\--print-jobid]
2175 | [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
2176
2177 This command moves an instance to another node group. The move is
2178 calculated by an iallocator, either given on the command line or as a
2179 cluster default. Note that the iallocator does only consider disk
2180 information of the default disk template, even if the instances'
2181 disk templates differ from that.
2182
2183 If no specific destination groups are specified using ``--to``, all
2184 groups except the one containing the instance are considered.
2185
2186 See **ganeti**\(7) for a description of ``--submit`` and other common
2187 options.
2188
2189 Example::
2190
2191     # gnt-instance change-group -I hail --to rack2 inst1.example.com
2192
2193
2194 Tags
2195 ~~~~
2196
2197 ADD-TAGS
2198 ^^^^^^^^
2199
2200 **add-tags** [\--from *file*] {*instancename*} {*tag*...}
2201
2202 Add tags to the given instance. If any of the tags contains invalid
2203 characters, the entire operation will abort.
2204
2205 If the ``--from`` option is given, the list of tags will be extended
2206 with the contents of that file (each line becomes a tag).  In this
2207 case, there is not need to pass tags on the command line (if you do,
2208 both sources will be used). A file name of ``-`` will be interpreted
2209 as stdin.
2210
2211 LIST-TAGS
2212 ^^^^^^^^^
2213
2214 **list-tags** {*instancename*}
2215
2216 List the tags of the given instance.
2217
2218 REMOVE-TAGS
2219 ^^^^^^^^^^^
2220
2221 **remove-tags** [\--from *file*] {*instancename*} {*tag*...}
2222
2223 Remove tags from the given instance. If any of the tags are not
2224 existing on the node, the entire operation will abort.
2225
2226 If the ``--from`` option is given, the list of tags to be removed will
2227 be extended with the contents of that file (each line becomes a tag).
2228 In this case, there is not need to pass tags on the command line (if
2229 you do, tags from both sources will be removed). A file name of ``-``
2230 will be interpreted as stdin.
2231
2232 .. vim: set textwidth=72 :
2233 .. Local Variables:
2234 .. mode: rst
2235 .. fill-column: 72
2236 .. End: