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