1 gnt-instance(8) Ganeti | Version @GANETI_VERSION@
2 =================================================
7 gnt-instance - Ganeti instance administration
12 **gnt-instance** {command} [arguments...]
17 The **gnt-instance** command is used for instance administration in
23 Creation/removal/querying
24 ~~~~~~~~~~~~~~~~~~~~~~~~~
30 | {-t|\--disk-template {diskless \| file \| plain \| drbd \| rbd}}
31 | {\--disk=*N*: {size=*VAL*[,spindles=*VAL*] \| adopt=*LV*}[,options...]
32 | \| {size=*VAL*,provider=*PROVIDER*}[,param=*value*... ][,options...]
33 | \| {-s|\--os-size} *SIZE*}
34 | [\--no-ip-check] [\--no-name-check] [\--no-conflicts-check]
35 | [\--no-start] [\--no-install]
36 | [\--net=*N* [:options...] \| \--no-nics]
37 | [{-B|\--backend-parameters} *BEPARAMS*]
38 | [{-H|\--hypervisor-parameters} *HYPERVISOR* [: option=*value*... ]]
39 | [{-O|\--os-parameters} *param*=*value*... ]
40 | [\--file-storage-dir *dir\_path*] [\--file-driver {loop \| blktap}]
41 | {{-n|\--node} *node[:secondary-node]* \| {-I|\--iallocator} *name*}
42 | {{-o|\--os-type} *os-type*}
43 | [\--submit] [\--print-job-id]
47 Creates a new instance on the specified host. The *instance* argument
48 must be in DNS, but depending on the bridge/routing setup, need not be
49 in the same network as the nodes in the cluster.
51 The ``disk`` option specifies the parameters for the disks of the
52 instance. The numbering of disks starts at zero, and at least one disk
53 needs to be passed. For each disk, either the size or the adoption
54 source needs to be given. The size is interpreted (when no unit is
55 given) in mebibytes. You can also use one of the suffixes *m*, *g* or
56 *t* to specify the exact the units used; these suffixes map to
57 mebibytes, gibibytes and tebibytes. Each disk can also take these
58 parameters (all optional):
61 How many spindles (physical disks on the node) the disk should span.
64 The access mode. Either ``ro`` (read-only) or the default ``rw``
68 This option specifies a name for the disk, which can be used as a disk
69 identifier. An instance can not have two disks with the same name.
72 The LVM volume group. This works only for LVM and DRBD devices.
75 This options specifies a different VG for the metadata device. This
76 works only for DRBD devices
78 When creating ExtStorage disks, also arbitrary parameters can be passed,
79 to the ExtStorage provider. Those parameters are passed as additional
80 comma separated options. Therefore, an ExtStorage disk provided by
81 provider ``pvdr1`` with parameters ``param1``, ``param2`` would be
82 passed as ``--disk 0:size=10G,provider=pvdr1,param1=val1,param2=val2``.
84 When using the ``adopt`` key in the disk definition, Ganeti will
85 reuse those volumes (instead of creating new ones) as the
86 instance's disks. Ganeti will rename these volumes to the standard
87 format, and (without installing the OS) will use them as-is for the
88 instance. This allows migrating instances from non-managed mode
89 (e.g. plain KVM with LVM) to being managed via Ganeti. Please note that
90 this works only for the \`plain' disk template (see below for
93 Alternatively, a single-disk instance can be created via the ``-s``
94 option which takes a single argument, the size of the disk. This is
95 similar to the Ganeti 1.2 version (but will only create one disk).
97 The minimum disk specification is therefore ``--disk 0:size=20G`` (or
98 ``-s 20G`` when using the ``-s`` option), and a three-disk instance
99 can be specified as ``--disk 0:size=20G --disk 1:size=4G --disk
102 The minimum information needed to specify an ExtStorage disk are the
103 ``size`` and the ``provider``. For example:
104 ``--disk 0:size=20G,provider=pvdr1``.
106 The ``--no-ip-check`` skips the checks that are done to see if the
107 instance's IP is not already alive (i.e. reachable from the master
110 The ``--no-name-check`` skips the check for the instance name via
111 the resolver (e.g. in DNS or /etc/hosts, depending on your setup).
112 Since the name check is used to compute the IP address, if you pass
113 this option you must also pass the ``--no-ip-check`` option.
115 If you don't want the instance to automatically start after
116 creation, this is possible via the ``--no-start`` option. This will
117 leave the instance down until a subsequent **gnt-instance start**
120 The NICs of the instances can be specified via the ``--net``
121 option. By default, one NIC is created for the instance, with a
122 random MAC, and set up according the the cluster level NIC
123 parameters. Each NIC can take these parameters (all optional):
126 either a value or 'generate' to generate a new unique MAC
129 specifies the IP address assigned to the instance from the Ganeti
130 side (this is not necessarily what the instance will use, but what
131 the node expects the instance to use). Note that if an IP in the
132 range of a network configured with **gnt-network**\(8) is used,
133 and the NIC is not already connected to it, this network has to be
134 passed in the **network** parameter if this NIC is meant to be
135 connected to the said network. ``--no-conflicts-check`` can be used
136 to override this check. The special value **pool** causes Ganeti to
137 select an IP from the the network the NIC is or will be connected to.
140 specifies the connection mode for this NIC: routed, bridged or
144 in bridged or openvswitch mode specifies the interface to attach
145 this NIC to, in routed mode it's intended to differentiate between
146 different routing tables/instance groups (but the meaning is
147 dependent on the network script, see **gnt-cluster**\(8) for more
148 details). Note that openvswitch support is also hypervisor
152 derives the mode and the link from the settings of the network
153 which is identified by its name. If the network option is chosen,
154 link and mode must not be specified. Note that the mode and link
155 depend on the network-to-nodegroup connection, thus allowing
156 different nodegroups to be connected to the same network in
160 this option specifies a name for the NIC, which can be used as a NIC
161 identifier. An instance can not have two NICs with the same name.
164 Of these "mode" and "link" are NIC parameters, and inherit their
165 default at cluster level. Alternatively, if no network is desired for
166 the instance, you can prevent the default of one NIC with the
167 ``--no-nics`` option.
169 The ``-o (--os-type)`` option specifies the operating system to be
170 installed. The available operating systems can be listed with
171 **gnt-os list**. Passing ``--no-install`` will however skip the OS
172 installation, allowing a manual import if so desired. Note that the
173 no-installation mode will automatically disable the start-up of the
174 instance (without an OS, it most likely won't be able to start-up
177 The ``-B (--backend-parameters)`` option specifies the backend
178 parameters for the instance. If no such parameters are specified, the
179 values are inherited from the cluster. Possible parameters are:
182 the maximum memory size of the instance; as usual, suffixes can be
183 used to denote the unit, otherwise the value is taken in mebibytes
186 the minimum memory size of the instance; as usual, suffixes can be
187 used to denote the unit, otherwise the value is taken in mebibytes
190 the number of VCPUs to assign to the instance (if this value makes
191 sense for the hypervisor)
194 whether the instance is considered in the N+1 cluster checks
195 (enough redundancy in the cluster to survive a node failure)
198 ``True`` or ``False``, whether the instance must be failed over
199 (shut down and rebooted) always or it may be migrated (briefly
202 Note that before 2.6 Ganeti had a ``memory`` parameter, which was the
203 only value of memory an instance could have. With the
204 ``maxmem``/``minmem`` change Ganeti guarantees that at least the minimum
205 memory is always available for an instance, but allows more memory to be
206 used (up to the maximum memory) should it be free.
208 The ``-H (--hypervisor-parameters)`` option specified the hypervisor
209 to use for the instance (must be one of the enabled hypervisors on the
210 cluster) and optionally custom parameters for this instance. If not
211 other options are used (i.e. the invocation is just -H *NAME*) the
212 instance will inherit the cluster options. The defaults below show the
213 cluster defaults at cluster creation time.
215 The possible hypervisor options are as follows:
218 Valid for the Xen HVM and KVM hypervisors.
220 A string value denoting the boot order. This has different meaning
221 for the Xen HVM hypervisor and for the KVM one.
223 For Xen HVM, The boot order is a string of letters listing the boot
224 devices, with valid device letters being:
238 The default is not to set an HVM boot order, which is interpreted
241 For KVM the boot order is either "floppy", "cdrom", "disk" or
242 "network". Please note that older versions of KVM couldn't netboot
243 from virtio interfaces. This has been fixed in more recent versions
244 and is confirmed to work at least with qemu-kvm 0.11.1. Also note
245 that if you have set the ``kernel_path`` option, that will be used
246 for booting, and this setting will be silently ignored.
249 Valid for the Xen HVM and PVM hypervisors.
251 Relevant to non-pvops guest kernels, in which the disk device names
252 are given by the host. Allows one to specify 'xvd', which helps run
253 Red Hat based installers, driven by anaconda.
256 Valid for the KVM hypervisor.
258 The path to a floppy disk image to attach to the instance. This
259 is useful to install Windows operating systems on Virt/IO disks
260 because you can specify here the floppy for the drivers at
264 Valid for the Xen HVM and KVM hypervisors.
266 The path to a CDROM image to attach to the instance.
269 Valid for the KVM hypervisor.
271 The path to a second CDROM image to attach to the instance.
272 **NOTE**: This image can't be used to boot the system. To do that
273 you have to use the 'cdrom\_image\_path' option.
276 Valid for the Xen HVM and KVM hypervisors.
278 This parameter determines the way the network cards are presented
279 to the instance. The possible options are:
281 - rtl8139 (default for Xen HVM) (HVM & KVM)
282 - ne2k\_isa (HVM & KVM)
283 - ne2k\_pci (HVM & KVM)
289 - paravirtual (default for KVM) (HVM & KVM)
292 Valid for the Xen HVM hypervisor.
294 This parameter specifies the vif type of the nic configuration
295 of the instance. Unsetting the value leads to no type being specified
296 in the configuration. Note that this parameter only takes effect when
297 the 'nic_type' is not set. The possible options are:
303 Valid for the Xen HVM and KVM hypervisors.
305 This parameter determines the way the disks are presented to the
306 instance. The possible options are:
308 - ioemu [default] (HVM & KVM)
317 Valid for the KVM hypervisor.
319 This parameter determines the way the cdroms disks are presented
320 to the instance. The default behavior is to get the same value of
321 the earlier parameter (disk_type). The possible options are:
332 Valid for the Xen HVM and KVM hypervisors.
334 Specifies the address that the VNC listener for this instance
335 should bind to. Valid values are IPv4 addresses. Use the address
336 0.0.0.0 to bind to all available interfaces (this is the default)
337 or specify the address of one of the interfaces on the node to
338 restrict listening to that interface.
341 Valid for the KVM hypervisor.
343 A boolean option that controls whether the VNC connection is
347 Valid for the KVM hypervisor.
349 If ``vnc_tls`` is enabled, this options specifies the path to the
350 x509 certificate to use.
353 Valid for the KVM hypervisor.
356 Valid for the KVM hypervisor.
358 Specifies the address or interface on which the SPICE server will
359 listen. Valid values are:
361 - IPv4 addresses, including 0.0.0.0 and 127.0.0.1
362 - IPv6 addresses, including :: and ::1
363 - names of network interfaces
365 If a network interface is specified, the SPICE server will be bound
366 to one of the addresses of that interface.
369 Valid for the KVM hypervisor.
371 Specifies which version of the IP protocol should be used by the
374 It is mainly intended to be used for specifying what kind of IP
375 addresses should be used if a network interface with both IPv4 and
376 IPv6 addresses is specified via the ``spice_bind`` parameter. In
377 this case, if the ``spice_ip_version`` parameter is not used, the
378 default IP version of the cluster will be used.
380 spice\_password\_file
381 Valid for the KVM hypervisor.
383 Specifies a file containing the password that must be used when
384 connecting via the SPICE protocol. If the option is not specified,
385 passwordless connections are allowed.
387 spice\_image\_compression
388 Valid for the KVM hypervisor.
390 Configures the SPICE lossless image compression. Valid values are:
399 spice\_jpeg\_wan\_compression
400 Valid for the KVM hypervisor.
402 Configures how SPICE should use the jpeg algorithm for lossy image
403 compression on slow links. Valid values are:
409 spice\_zlib\_glz\_wan\_compression
410 Valid for the KVM hypervisor.
412 Configures how SPICE should use the zlib-glz algorithm for lossy image
413 compression on slow links. Valid values are:
419 spice\_streaming\_video
420 Valid for the KVM hypervisor.
422 Configures how SPICE should detect video streams. Valid values are:
428 spice\_playback\_compression
429 Valid for the KVM hypervisor.
431 Configures whether SPICE should compress audio streams or not.
434 Valid for the KVM hypervisor.
436 Specifies that the SPICE server must use TLS to encrypt all the
437 traffic with the client.
440 Valid for the KVM hypervisor.
442 Specifies a list of comma-separated ciphers that SPICE should use
443 for TLS connections. For the format, see man **cipher**\(1).
446 Valid for the KVM hypervisor.
448 Enables or disables passing mouse events via SPICE vdagent.
451 Valid for the KVM hypervisor.
453 This parameter determines the emulated cpu for the instance. If this
454 parameter is empty (which is the default configuration), it will not
457 Be aware of setting this parameter to ``"host"`` if you have nodes
458 with different CPUs from each other. Live migration may stop working
461 For more information please refer to the KVM manual.
464 Valid for the Xen HVM and KVM hypervisors.
466 A boolean option that specifies if the hypervisor should enable
467 ACPI support for this instance. By default, ACPI is disabled.
470 Valid for the Xen HVM and KVM hypervisors.
472 A boolean option that specifies if the hypervisor should enabled
473 PAE support for this instance. The default is false, disabling PAE
477 Valid for the Xen HVM and KVM hypervisors.
479 A boolean option that specifies if the instance should be started
480 with its clock set to the localtime of the machine (when true) or
481 to the UTC (When false). The default is false, which is useful for
482 Linux/Unix machines; for Windows OSes, it is recommended to enable
486 Valid for the Xen PVM and KVM hypervisors.
488 This option specifies the path (on the node) to the kernel to boot
489 the instance with. Xen PVM instances always require this, while for
490 KVM if this option is empty, it will cause the machine to load the
491 kernel from its disks (and the boot will be done accordingly to
495 Valid for the Xen PVM and KVM hypervisors.
497 This options specifies extra arguments to the kernel that will be
498 loaded. device. This is always used for Xen PVM, while for KVM it
499 is only used if the ``kernel_path`` option is also specified.
501 The default setting for this value is simply ``"ro"``, which
502 mounts the root disk (initially) in read-only one. For example,
503 setting this to single will cause the instance to start in
507 Valid for the Xen PVM and KVM hypervisors.
509 This option specifies the path (on the node) to the initrd to boot
510 the instance with. Xen PVM instances can use this always, while
511 for KVM if this option is only used if the ``kernel_path`` option
512 is also specified. You can pass here either an absolute filename
513 (the path to the initrd) if you want to use an initrd, or use the
514 format no\_initrd\_path for no initrd.
517 Valid for the Xen PVM and KVM hypervisors.
519 This options specifies the name of the root device. This is always
520 needed for Xen PVM, while for KVM it is only used if the
521 ``kernel_path`` option is also specified.
523 Please note, that if this setting is an empty string and the
524 hypervisor is Xen it will not be written to the Xen configuration
528 Valid for the KVM hypervisor.
530 This boolean option specifies whether to emulate a serial console
531 for the instance. Note that some versions of KVM have a bug that
532 will make an instance hang when configured to use the serial console
533 unless a connection is made to it within about 2 seconds of the
534 instance's startup. For such case it's recommended to disable this
535 option, which is enabled by default.
538 Valid for the KVM hypervisor.
540 This integer option specifies the speed of the serial console.
541 Common values are 9600, 19200, 38400, 57600 and 115200: choose the
542 one which works on your system. (The default is 38400 for historical
543 reasons, but newer versions of kvm/qemu work with 115200)
546 Valid for the KVM hypervisor.
548 The disk cache mode. It can be either default to not pass any
549 cache option to KVM, or one of the KVM cache modes: none (for
550 direct I/O), writethrough (to use the host cache but report
551 completion to the guest only when the host has committed the
552 changes to disk) or writeback (to use the host cache and report
553 completion as soon as the data is in the host cache). Note that
554 there are special considerations for the cache mode depending on
555 version of KVM used and disk type (always raw file under Ganeti),
556 please refer to the KVM documentation for more details.
559 Valid for the KVM hypervisor.
561 The security model for kvm. Currently one of *none*, *user* or
562 *pool*. Under *none*, the default, nothing is done and instances
563 are run as the Ganeti daemon user (normally root).
565 Under *user* kvm will drop privileges and become the user
566 specified by the security\_domain parameter.
568 Under *pool* a global cluster pool of users will be used, making
569 sure no two instances share the same user on the same node. (this
570 mode is not implemented yet)
573 Valid for the KVM hypervisor.
575 Under security model *user* the username to run the instance
576 under. It must be a valid username existing on the host.
578 Cannot be set under security model *none* or *pool*.
581 Valid for the KVM hypervisor.
583 If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
584 -disable-kvm is passed. If unset no flag is passed, and the
585 default running mode for your kvm binary will be used.
588 Valid for the KVM hypervisor.
590 This option passes the -mem-path argument to kvm with the path (on
591 the node) to the mount point of the hugetlbfs file system, along
592 with the -mem-prealloc argument too.
595 Valid for the KVM hypervisor.
597 This boolean option determines whether to run the KVM instance in a
600 If it is set to ``true``, an empty directory is created before
601 starting the instance and its path is passed via the -chroot flag
602 to kvm. The directory is removed when the instance is stopped.
604 It is set to ``false`` by default.
607 Valid for the KVM hypervisor.
609 The maximum amount of time (in ms) a KVM instance is allowed to be
610 frozen during a live migration, in order to copy dirty memory
611 pages. Default value is 30ms, but you may need to increase this
612 value for busy instances.
614 This option is only effective with kvm versions >= 87 and qemu-kvm
618 Valid for the Xen, KVM and LXC hypervisors.
620 The processes belonging to the given instance are only scheduled
621 on the specified CPUs.
623 The format of the mask can be given in three forms. First, the word
624 "all", which signifies the common case where all VCPUs can live on
625 any CPU, based on the hypervisor's decisions.
627 Second, a comma-separated list of CPU IDs or CPU ID ranges. The
628 ranges are defined by a lower and higher boundary, separated by a
629 dash, and the boundaries are inclusive. In this form, all VCPUs of
630 the instance will be mapped on the selected list of CPUs. Example:
631 ``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs
634 The last form is used for explicit control of VCPU-CPU pinnings. In
635 this form, the list of VCPU mappings is given as a colon (:)
636 separated list, whose elements are the possible values for the
637 second or first form above. In this form, the number of elements in
638 the colon-separated list _must_ equal the number of VCPUs of the
645 # Map the entire instance to CPUs 0-2
646 gnt-instance modify -H cpu_mask=0-2 my-inst
648 # Map vCPU 0 to physical CPU 1 and vCPU 1 to CPU 3 (assuming 2 vCPUs)
649 gnt-instance modify -H cpu_mask=1:3 my-inst
651 # Pin vCPU 0 to CPUs 1 or 2, and vCPU 1 to any CPU
652 gnt-instance modify -H cpu_mask=1-2:all my-inst
654 # Pin vCPU 0 to any CPU, vCPU 1 to CPUs 1, 3, 4 or 5, and CPU 2 to
655 # CPU 0 (backslashes for escaping the comma)
656 gnt-instance modify -H cpu_mask=all:1\\,3-5:0 my-inst
658 # Pin entire VM to CPU 0
659 gnt-instance modify -H cpu_mask=0 my-inst
661 # Turn off CPU pinning (default setting)
662 gnt-instance modify -H cpu_mask=all my-inst
665 Valid for the Xen hypervisor.
667 Set the maximum amount of cpu usage by the VM. The value is a percentage
668 between 0 and (100 * number of VCPUs). Default cap is 0: unlimited.
671 Valid for the Xen hypervisor.
673 Set the cpu time ratio to be allocated to the VM. Valid values are
674 between 1 and 65535. Default weight is 256.
677 Valid for the KVM hypervisor.
679 This option specifies the usb mouse type to be used. It can be
680 "mouse" or "tablet". When using VNC it's recommended to set it to
684 Valid for the KVM hypervisor.
686 This option specifies the keyboard mapping to be used. It is only
687 needed when using the VNC console. For example: "fr" or "en-gb".
690 Valid for Xen PVM, Xen HVM and KVM hypervisors.
692 Normally if an instance reboots, the hypervisor will restart it. If
693 this option is set to ``exit``, the hypervisor will treat a reboot
694 as a shutdown instead.
696 It is set to ``reboot`` by default.
699 Valid for the KVM hypervisor.
701 Number of emulated CPU cores.
704 Valid for the KVM hypervisor.
706 Number of emulated CPU threads.
709 Valid for the KVM hypervisor.
711 Number of emulated CPU sockets.
714 Valid for the KVM hypervisor.
716 Comma separated list of emulated sounds cards, or "all" to enable
717 all the available ones.
720 Valid for the KVM hypervisor.
722 Comma separated list of usb devices. These can be emulated devices
723 or passthrough ones, and each one gets passed to kvm with its own
724 ``-usbdevice`` option. See the **qemu**\(1) manpage for the syntax
725 of the possible components.
728 Valid for the KVM hypervisor.
730 Emulated vga mode, passed the the kvm -vga option.
733 Valid for the KVM hypervisor.
735 Any other option to the KVM hypervisor, useful tweaking anything
736 that Ganeti doesn't support. Note that values set with this
737 parameter are split on a space character and currently don't support
741 Valid for the KVM hypervisor.
743 Use in case an instance must be booted with an exact type of
744 machine version (due to e.g. outdated drivers). In case it's not set
745 the default version supported by your version of kvm is used.
748 Valid for the KVM hypervisor.
750 Path to the userspace KVM (or qemu) program.
752 The ``-O (--os-parameters)`` option allows customisation of the OS
753 parameters. The actual parameter names and values depends on the OS
754 being used, but the syntax is the same key=value. For example, setting
755 a hypothetical ``dhcp`` parameter to yes can be achieved by::
757 gnt-instance add -O dhcp=yes ...
759 The ``-I (--iallocator)`` option specifies the instance allocator plugin
760 to use (``.`` means the default allocator). If you pass in this option
761 the allocator will select nodes for this instance automatically, so you
762 don't need to pass them with the ``-n`` option. For more information
763 please refer to the instance allocator documentation.
765 The ``-t (--disk-template)`` options specifies the disk layout type
766 for the instance. The available choices are:
769 This creates an instance with no disks. Its useful for testing only
770 (or other special cases).
773 Disk devices will be regular files.
776 Disk devices will be regulare files on a shared directory.
779 Disk devices will be logical volumes.
782 Disk devices will be drbd (version 8.x) on top of lvm volumes.
785 Disk devices will be rbd volumes residing inside a RADOS cluster.
788 Disk devices will be adopted pre-existent block devices.
791 Disk devices will be provided by external shared storage,
792 through the ExtStorage Interface using ExtStorage providers.
794 The optional second value of the ``-n (--node)`` is used for the drbd
795 template type and specifies the remote node.
797 If you do not want gnt-instance to wait for the disk mirror to be
798 synced, use the ``--no-wait-for-sync`` option.
800 The ``--file-storage-dir`` specifies the relative path under the
801 cluster-wide file storage directory to store file-based disks. It is
802 useful for having different subdirectories for different
803 instances. The full path of the directory where the disk files are
804 stored will consist of cluster-wide file storage directory + optional
805 subdirectory + instance name. Example:
806 ``@RPL_FILE_STORAGE_DIR@/mysubdir/instance1.example.com``. This
807 option is only relevant for instances using the file storage backend.
809 The ``--file-driver`` specifies the driver to use for file-based
810 disks. Note that currently these drivers work with the xen hypervisor
811 only. This option is only relevant for instances using the file
812 storage backend. The available choices are:
815 Kernel loopback driver. This driver uses loopback devices to
816 access the filesystem within the file. However, running I/O
817 intensive applications in your instance using the loop driver
818 might result in slowdowns. Furthermore, if you use the loopback
819 driver consider increasing the maximum amount of loopback devices
820 (on most systems it's 8) using the max\_loop param.
823 The blktap driver (for Xen hypervisors). In order to be able to
824 use the blktap driver you should check if the 'blktapctrl' user
825 space disk agent is running (usually automatically started via
826 xend). This user-level disk I/O interface has the advantage of
827 better performance. Especially if you use a network file system
828 (e.g. NFS) to store your instances this is the recommended choice.
830 If ``--ignore-ipolicy`` is given any instance policy violations occuring
831 during this operation are ignored.
833 See **ganeti**\(7) for a description of ``--submit`` and other common
838 # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
839 -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
840 # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
841 -o debian-etch -n node1.example.com instance1.example.com
842 # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
843 -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
844 # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
845 -n node1.example.com:node2.example.com instance2.example.com
846 # gnt-instance add -t rbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
847 -n node1.example.com instance1.example.com
848 # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1 -B maxmem=512 \
849 -o debian-etch -n node1.example.com instance1.example.com
850 # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1,param1=val1 \
851 --disk 1:size=40g,provider=pvdr2,param2=val2,param3=val3 -B maxmem=512 \
852 -o debian-etch -n node1.example.com instance1.example.com
858 **batch-create** {instances\_file.json}
860 This command (similar to the Ganeti 1.2 **batcher** tool) submits
861 multiple instance creation jobs based on a definition file. The
862 instance configurations do not encompass all the possible options for
863 the **add** command, but only a subset.
865 The instance file should be a valid-formed JSON file, containing a
866 dictionary with instance name and instance parameters. The accepted
870 The size of the disks of the instance.
873 The disk template to use for the instance, the same as in the
877 A dictionary of backend parameters.
880 A dictionary with a single key (the hypervisor name), and as value
881 the hypervisor options. If not passed, the default hypervisor and
882 hypervisor options will be inherited.
885 Specifications for the one NIC that will be created for the
886 instance. 'bridge' is also accepted as a backwards compatible
890 List of NICs that will be created for the instance. Each entry
891 should be a dict, with mac, ip, mode and link as possible keys.
892 Please don't provide the "mac, ip, mode, link" parent keys if you
893 use this method for specifying NICs.
895 primary\_node, secondary\_node
896 The primary and optionally the secondary node to use for the
897 instance (in case an iallocator script is not used).
900 Instead of specifying the nodes, an iallocator script can be used
901 to automatically compute them.
904 whether to start the instance
907 Skip the check for already-in-use instance; see the description in
908 the **add** command for details.
911 Skip the name check for instances; see the description in the
912 **add** command for details.
914 file\_storage\_dir, file\_driver
915 Configuration for the file disk type, see the **add** command for
919 A simple definition for one instance can be (with most of the
920 parameters taken from the cluster defaults)::
926 "disk_size": ["25G"],
932 "disk_size": ["25G"],
933 "iallocator": "dumb",
934 "hypervisor": "xen-hvm",
935 "hvparams": {"acpi": true},
936 "backend": {"maxmem": 512, "minmem": 256}
940 The command will display the job id for each submitted instance, as
943 # gnt-instance batch-create instances.json
950 | **remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
951 | [\--print-job-id] [\--force] {*instance*}
953 Remove an instance. This will remove all data from the instance and
954 there is *no way back*. If you are not sure if you use an instance
955 again, use **shutdown** first and leave it in the shutdown state for a
958 The ``--ignore-failures`` option will cause the removal to proceed
959 even in the presence of errors during the removal of the instance
960 (e.g. during the shutdown or the disk removal). If this option is not
961 given, the command will stop at the first error.
963 The ``--shutdown-timeout`` is used to specify how much time to wait
964 before forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the
965 kvm process for KVM, etc.). By default two minutes are given to each
968 The ``--force`` option is used to skip the interactive confirmation.
970 See **ganeti**\(7) for a description of ``--submit`` and other common
975 # gnt-instance remove instance1.example.com
982 | [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
983 | [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
985 Shows the currently configured instances with memory usage, disk
986 usage, the node they are running on, and their run status.
988 The ``--no-headers`` option will skip the initial header line. The
989 ``--separator`` option takes an argument which denotes what will be
990 used between the output fields. Both these options are to help
993 The units used to display the numeric values in the output varies,
994 depending on the options given. By default, the values will be
995 formatted in the most appropriate unit. If the ``--separator`` option
996 is given, then the values are shown in mebibytes to allow parsing by
997 scripts. In both cases, the ``--units`` option can be used to enforce
1000 The ``-v`` option activates verbose mode, which changes the display of
1001 special field states (see **ganeti**\(7)).
1003 The ``-o (--output)`` option takes a comma-separated list of output
1004 fields. The available fields and their meaning are:
1006 @QUERY_FIELDS_INSTANCE@
1008 If the value of the option starts with the character ``+``, the new
1009 field(s) will be added to the default list. This allows one to quickly
1010 see the default list plus a few other fields, instead of retyping the
1011 entire list of fields.
1013 There is a subtle grouping about the available output fields: all
1014 fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and
1015 ``status`` are configuration value and not run-time values. So if you
1016 don't select any of the these fields, the query will be satisfied
1017 instantly from the cluster configuration, without having to ask the
1018 remote nodes for the data. This can be helpful for big clusters when
1019 you only want some data and it makes sense to specify a reduced set of
1022 If exactly one argument is given and it appears to be a query filter
1023 (see **ganeti**\(7)), the query result is filtered accordingly. For
1024 ambiguous cases (e.g. a single field name as a filter) the ``--filter``
1025 (``-F``) option forces the argument to be treated as a filter (e.g.
1026 ``gnt-instance list -F admin_state``).
1028 The default output field list is: ``name``, ``os``, ``pnode``,
1029 ``admin_state``, ``oper_state``, ``oper_ram``.
1035 **list-fields** [field...]
1037 Lists available fields for instances.
1043 **info** [-s \| \--static] [\--roman] {\--all \| *instance*}
1045 Show detailed information about the given instance(s). This is
1046 different from **list** as it shows detailed data about the instance's
1047 disks (especially useful for the drbd disk template).
1049 If the option ``-s`` is used, only information available in the
1050 configuration file is returned, without querying nodes, making the
1053 Use the ``--all`` to get info about all instances, rather than
1054 explicitly passing the ones you're interested in.
1056 The ``--roman`` option can be used to cause envy among people who like
1057 ancient cultures, but are stuck with non-latin-friendly cluster
1058 virtualization technologies.
1064 | [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
1065 | [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
1066 | [{-m|\--runtime-memory} *SIZE*]
1067 | [\--net add[:options...] \|
1068 | \--net [*N*:]add[,options...] \|
1069 | \--net [*ID*:]remove \|
1070 | \--net *ID*:modify[,options...]]
1071 | [\--disk add:size=*SIZE*[,options...] \|
1072 | \--disk *N*:add,size=*SIZE*[,options...] \|
1073 | \--disk *N*:add,size=*SIZE*,provider=*PROVIDER*[,options...][,param=*value*... ] \|
1074 | \--disk *ID*:modify[,options...]
1075 | \--disk [*ID*:]remove]
1076 | [{-t|\--disk-template} plain \| {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
1077 | [\--new-primary=*node*]
1078 | [\--os-type=*OS* [\--force-variant]]
1079 | [{-O|\--os-parameters} *param*=*value*... ]
1080 | [\--offline \| \--online]
1081 | [\--submit] [\--print-job-id]
1082 | [\--ignore-ipolicy]
1085 Modifies the memory size, number of vcpus, ip address, MAC address
1086 and/or NIC parameters for an instance. It can also add and remove
1087 disks and NICs to/from the instance. Note that you need to give at
1088 least one of the arguments, otherwise the command complains.
1090 The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)``
1091 and ``-O (--os-parameters)`` options specifies hypervisor, backend and
1092 OS parameter options in the form of name=value[,...]. For details
1093 which options can be specified, see the **add** command.
1095 The ``-t (--disk-template)`` option will change the disk template of
1096 the instance. Currently only conversions between the plain and drbd
1097 disk templates are supported, and the instance must be stopped before
1098 attempting the conversion. When changing from the plain to the drbd
1099 disk template, a new secondary node must be specified via the ``-n``
1100 option. The option ``--no-wait-for-sync`` can be used when converting
1101 to the ``drbd`` template in order to make the instance available for
1102 startup before DRBD has finished resyncing.
1104 The ``-m (--runtime-memory)`` option will change an instance's runtime
1105 memory to the given size (in MB if a different suffix is not specified),
1106 by ballooning it up or down to the new value.
1108 The ``--disk add:size=*SIZE*,[options..]`` option adds a disk to the
1109 instance, and ``--disk *N*:add:size=*SIZE*,[options..]`` will add a disk
1110 to the the instance at a specific index. The available options are the
1111 same as in the **add** command(``spindles``, ``mode``, ``name``, ``vg``,
1112 ``metavg``). When adding an ExtStorage disk the ``provider=*PROVIDER*``
1113 option is also mandatory and specifies the ExtStorage provider. Also,
1114 for ExtStorage disks arbitrary parameters can be passed as additional
1115 comma separated options, same as in the **add** command. -The ``--disk
1116 remove`` option will remove the last disk of the instance. Use ``--disk
1117 `` *ID*``:remove`` to remove a disk by its identifier. *ID* can be the
1118 index of the disk, the disks's name or the disks's UUID. The ``--disk
1119 *ID*:modify[,options...]`` will change the options of the disk.
1120 Available options are:
1123 The access mode. Either ``ro`` (read-only) or the default ``rw`` (read-write).
1126 This option specifies a name for the disk, which can be used as a disk
1127 identifier. An instance can not have two disks with the same name.
1129 The ``--net *N*:add[,options..]`` will add a new network interface to
1130 the instance. The available options are the same as in the **add**
1131 command (``mac``, ``ip``, ``link``, ``mode``, ``network``). The
1132 ``--net *ID*,remove`` will remove the intances' NIC with *ID* identifier,
1133 which can be the index of the NIC, the NIC's name or the NIC's UUID.
1134 The ``--net *ID*:modify[,options..]`` option will change the parameters of
1135 the instance network interface with the *ID* identifier.
1137 The option ``-o (--os-type)`` will change the OS name for the instance
1138 (without reinstallation). In case an OS variant is specified that is
1139 not found, then by default the modification is refused, unless
1140 ``--force-variant`` is passed. An invalid OS will also be refused,
1141 unless the ``--force`` option is given.
1143 The option ``--new-primary`` will set the new primary node of an instance
1144 assuming the disks have already been moved manually. Unless the ``--force``
1145 option is given, it is verified that the instance is no longer running
1146 on its current primary node.
1148 The ``--online`` and ``--offline`` options are used to transition an
1149 instance into and out of the ``offline`` state. An instance can be
1150 turned offline only if it was previously down. The ``--online`` option
1151 fails if the instance was not in the ``offline`` state, otherwise it
1152 changes instance's state to ``down``. These modifications take effect
1155 If ``--ignore-ipolicy`` is given any instance policy violations occuring
1156 during this operation are ignored.
1158 See **ganeti**\(7) for a description of ``--submit`` and other common
1161 Most of the changes take effect at the next restart. If the instance is
1162 running, there is no effect on the instance.
1167 | **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
1168 | [\--force-multiple]
1169 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1170 | [{-O|\--os-parameters} *OS\_PARAMETERS*] [\--submit] [\--print-job-id]
1173 Reinstalls the operating system on the given instance(s). The
1174 instance(s) must be stopped when running this command. If the ``-o
1175 (--os-type)`` is specified, the operating system is changed.
1177 The ``--select-os`` option switches to an interactive OS reinstall.
1178 The user is prompted to select the OS template from the list of
1179 available OS templates. OS parameters can be overridden using ``-O
1180 (--os-parameters)`` (more documentation for this option under the
1183 Since this is a potentially dangerous command, the user will be
1184 required to confirm this action, unless the ``-f`` flag is passed.
1185 When multiple instances are selected (either by passing multiple
1186 arguments or by using the ``--node``, ``--primary``, ``--secondary``
1187 or ``--all`` options), the user must pass the ``--force-multiple``
1188 options to skip the interactive confirmation.
1190 See **ganeti**\(7) for a description of ``--submit`` and other common
1196 | **rename** [\--no-ip-check] [\--no-name-check] [\--submit] [\--print-job-id]
1197 | {*instance*} {*new\_name*}
1199 Renames the given instance. The instance must be stopped when running
1200 this command. The requirements for the new name are the same as for
1201 adding an instance: the new name must be resolvable and the IP it
1202 resolves to must not be reachable (in order to prevent duplicate IPs
1203 the next time the instance is started). The IP test can be skipped if
1204 the ``--no-ip-check`` option is passed.
1206 Note that you can rename an instance to its same name, to force
1207 re-executing the os-specific rename script for that instance, if
1210 The ``--no-name-check`` skips the check for the new instance name via
1211 the resolver (e.g. in DNS or /etc/hosts, depending on your setup) and
1212 that the resolved name matches the provided name. Since the name check
1213 is used to compute the IP address, if you pass this option you must also
1214 pass the ``--no-ip-check`` option.
1216 See **ganeti**\(7) for a description of ``--submit`` and other common
1219 Starting/stopping/connecting to console
1220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1226 | [\--force] [\--ignore-offline]
1227 | [\--force-multiple] [\--no-remember]
1228 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1229 | \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1230 | [{-H|\--hypervisor-parameters} ``key=value...``]
1231 | [{-B|\--backend-parameters} ``key=value...``]
1232 | [\--submit] [\--print-job-id] [\--paused]
1235 Starts one or more instances, depending on the following options. The
1236 four available modes are:
1239 will start the instances given as arguments (at least one argument
1240 required); this is the default selection
1243 will start the instances who have the given node as either primary
1247 will start all instances whose primary node is in the list of nodes
1248 passed as arguments (at least one node required)
1251 will start all instances whose secondary node is in the list of
1252 nodes passed as arguments (at least one node required)
1255 will start all instances in the cluster (no arguments accepted)
1258 will start all instances in the cluster with the tags given as
1262 will start all instances in the cluster on nodes with the tags
1266 will start all instances in the cluster on primary nodes with the
1267 tags given as arguments
1270 will start all instances in the cluster on secondary nodes with the
1271 tags given as arguments
1273 Note that although you can pass more than one selection option, the
1274 last one wins, so in order to guarantee the desired result, don't pass
1275 more than one such option.
1277 Use ``--force`` to start even if secondary disks are failing.
1278 ``--ignore-offline`` can be used to ignore offline primary nodes and
1279 mark the instance as started even if the primary is not available.
1281 The ``--force-multiple`` will skip the interactive confirmation in the
1282 case the more than one instance will be affected.
1284 The ``--no-remember`` option will perform the startup but not change
1285 the state of the instance in the configuration file (if it was stopped
1286 before, Ganeti will still think it needs to be stopped). This can be
1287 used for testing, or for a one shot-start where you don't want the
1288 watcher to restart the instance if it crashes.
1290 The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
1291 options specify temporary hypervisor and backend parameters that can
1292 be used to start an instance with modified parameters. They can be
1293 useful for quick testing without having to modify an instance back and
1296 # gnt-instance start -H kernel_args="single" instance1
1297 # gnt-instance start -B maxmem=2048 instance2
1300 The first form will start the instance instance1 in single-user mode,
1301 and the instance instance2 with 2GB of RAM (this time only, unless
1302 that is the actual instance memory size already). Note that the values
1303 override the instance parameters (and not extend them): an instance
1304 with "kernel\_args=ro" when started with -H kernel\_args=single will
1305 result in "single", not "ro single".
1307 The ``--paused`` option is only valid for Xen and kvm hypervisors. This
1308 pauses the instance at the start of bootup, awaiting ``gnt-instance
1309 console`` to unpause it, allowing the entire boot process to be
1310 monitored for debugging.
1312 See **ganeti**\(7) for a description of ``--submit`` and other common
1317 # gnt-instance start instance1.example.com
1318 # gnt-instance start --node node1.example.com node2.example.com
1319 # gnt-instance start --all
1327 | [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember]
1328 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1329 | \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1330 | [\--submit] [\--print-job-id]
1333 Stops one or more instances. If the instance cannot be cleanly stopped
1334 during a hardcoded interval (currently 2 minutes), it will forcibly
1335 stop the instance (equivalent to switching off the power on a physical
1338 The ``--timeout`` is used to specify how much time to wait before
1339 forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the kvm
1340 process for KVM, etc.). By default two minutes are given to each
1343 The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1344 ``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1345 ``--sec-node-tags`` options are similar as for the **startup** command
1346 and they influence the actual instances being shutdown.
1348 ``--ignore-offline`` can be used to ignore offline primary nodes and
1349 force the instance to be marked as stopped. This option should be used
1350 with care as it can lead to an inconsistent cluster state.
1352 Use ``--force`` to be able to shutdown an instance even when it's marked
1353 as offline. This is useful is an offline instance ends up in the
1354 ``ERROR_up`` state, for example.
1356 The ``--no-remember`` option will perform the shutdown but not change
1357 the state of the instance in the configuration file (if it was running
1358 before, Ganeti will still thinks it needs to be running). This can be
1359 useful for a cluster-wide shutdown, where some instances are marked as
1360 up and some as down, and you don't want to change the running state:
1361 you just need to disable the watcher, shutdown all instances with
1362 ``--no-remember``, and when the watcher is activated again it will
1363 restore the correct runtime state for all instances.
1365 See **ganeti**\(7) for a description of ``--submit`` and other common
1370 # gnt-instance shutdown instance1.example.com
1371 # gnt-instance shutdown --all
1378 | [{-t|\--type} *REBOOT-TYPE*]
1379 | [\--ignore-secondaries]
1380 | [\--shutdown-timeout=*N*]
1381 | [\--force-multiple]
1382 | [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
1383 | \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1384 | [\--submit] [\--print-job-id]
1387 Reboots one or more instances. The type of reboot depends on the value
1388 of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1389 does a instance stop, recreates the hypervisor config for the instance
1390 and starts the instance. A full reboot does the equivalent of
1391 **gnt-instance shutdown && gnt-instance startup**. The default is
1394 For the hard reboot the option ``--ignore-secondaries`` ignores errors
1395 for the secondary node while re-assembling the instance disks.
1397 The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
1398 ``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1399 ``--sec-node-tags`` options are similar as for the **startup** command
1400 and they influence the actual instances being rebooted.
1402 The ``--shutdown-timeout`` is used to specify how much time to wait
1403 before forcing the shutdown (xm destroy in xen, killing the kvm
1404 process, for kvm). By default two minutes are given to each instance
1407 The ``--force-multiple`` will skip the interactive confirmation in the
1408 case the more than one instance will be affected.
1410 See **ganeti**\(7) for a description of ``--submit`` and other common
1415 # gnt-instance reboot instance1.example.com
1416 # gnt-instance reboot --type=full instance1.example.com
1422 **console** [\--show-cmd] {*instance*}
1424 Connects to the console of the given instance. If the instance is not
1425 up, an error is returned. Use the ``--show-cmd`` option to display the
1426 command instead of executing it.
1428 For HVM instances, this will attempt to connect to the serial console
1429 of the instance. To connect to the virtualized "physical" console of a
1430 HVM instance, use a VNC client with the connection info from the
1433 For Xen/kvm instances, if the instance is paused, this attempts to
1434 unpause the instance after waiting a few seconds for the connection to
1435 the console to be made.
1439 # gnt-instance console instance1.example.com
1448 | **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1449 | [\--ignore-ipolicy] {-p} [\--disks *idx*] {*instance*}
1451 | **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1452 | [\--ignore-ipolicy] {-s} [\--disks *idx*] {*instance*}
1454 | **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1455 | [\--ignore-ipolicy]
1456 | {{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*}
1458 | **replace-disks** [\--submit] [\--print-job-id] [\--early-release]
1459 | [\--ignore-ipolicy] {-a\|\--auto} {*instance*}
1461 This command is a generalized form for replacing disks. It is
1462 currently only valid for the mirrored (DRBD) disk template.
1464 The first form (when passing the ``-p`` option) will replace the disks
1465 on the primary, while the second form (when passing the ``-s`` option
1466 will replace the disks on the secondary node. For these two cases (as
1467 the node doesn't change), it is possible to only run the replace for a
1468 subset of the disks, using the option ``--disks`` which takes a list
1469 of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only
1470 the first and third disks.
1472 The third form (when passing either the ``--iallocator`` or the
1473 ``--new-secondary`` option) is designed to change secondary node of the
1474 instance. Specifying ``--iallocator`` makes the new secondary be
1475 selected automatically by the specified allocator plugin (use ``.`` to
1476 indicate the default allocator), otherwise the new secondary node will
1477 be the one chosen manually via the ``--new-secondary`` option.
1479 Note that it is not possible to select an offline or drained node as a
1482 The fourth form (when using ``--auto``) will automatically determine
1483 which disks of an instance are faulty and replace them within the same
1484 node. The ``--auto`` option works only when an instance has only
1485 faulty disks on either the primary or secondary node; it doesn't work
1486 when both sides have faulty disks.
1488 The ``--early-release`` changes the code so that the old storage on
1489 secondary node(s) is removed early (before the resync is completed)
1490 and the internal Ganeti locks for the current (and new, if any)
1491 secondary node are also released, thus allowing more parallelism in
1492 the cluster operation. This should be used only when recovering from a
1493 disk failure on the current secondary (thus the old storage is already
1494 broken) or when the storage on the primary node is known to be fine
1495 (thus we won't need the old storage for potential recovery).
1497 The ``--ignore-ipolicy`` let the command ignore instance policy
1498 violations if replace-disks changes groups and the instance would
1499 violate the new groups instance policy.
1501 See **ganeti**\(7) for a description of ``--submit`` and other common
1507 | **activate-disks** [\--submit] [\--print-job-id] [\--ignore-size]
1508 | [\--wait-for-sync] {*instance*}
1510 Activates the block devices of the given instance. If successful, the
1511 command will show the location and name of the block devices::
1513 node1.example.com:disk/0:/dev/drbd0
1514 node1.example.com:disk/1:/dev/drbd1
1517 In this example, *node1.example.com* is the name of the node on which
1518 the devices have been activated. The *disk/0* and *disk/1* are the
1519 Ganeti-names of the instance disks; how they are visible inside the
1520 instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the
1521 actual block devices as visible on the node.
1523 The ``--ignore-size`` option can be used to activate disks ignoring
1524 the currently configured size in Ganeti. This can be used in cases
1525 where the configuration has gotten out of sync with the real-world
1526 (e.g. after a partially-failed grow-disk operation or due to rounding
1527 in LVM devices). This should not be used in normal cases, but only
1528 when activate-disks fails without it.
1530 The ``--wait-for-sync`` option will ensure that the command returns only
1531 after the instance's disks are synchronised (mostly for DRBD); this can
1532 be useful to ensure consistency, as otherwise there are no commands that
1533 can wait until synchronisation is done. However when passing this
1534 option, the command will have additional output, making it harder to
1535 parse the disk information.
1537 Note that it is safe to run this command while the instance is already
1540 See **ganeti**\(7) for a description of ``--submit`` and other common
1546 **deactivate-disks** [-f] [\--submit] [\--print-job-id] {*instance*}
1548 De-activates the block devices of the given instance. Note that if you
1549 run this command for an instance with a drbd disk template, while it
1550 is running, it will not be able to shutdown the block devices on the
1551 primary node, but it will shutdown the block devices on the secondary
1552 nodes, thus breaking the replication.
1554 The ``-f``/``--force`` option will skip checks that the instance is
1555 down; in case the hypervisor is confused and we can't talk to it,
1556 normally Ganeti will refuse to deactivate the disks, but with this
1557 option passed it will skip this check and directly try to deactivate
1558 the disks. This can still fail due to the instance actually running or
1561 See **ganeti**\(7) for a description of ``--submit`` and other common
1567 | **grow-disk** [\--no-wait-for-sync] [\--submit] [\--print-job-id]
1569 | {*instance*} {*disk*} {*amount*}
1571 Grows an instance's disk. This is only possible for instances having a
1572 plain, drbd, file, sharedfile, rbd or ext disk template. For the ext
1573 template to work, the ExtStorage provider should also support growing.
1574 This means having a ``grow`` script that actually grows the volume of
1575 the external shared storage.
1577 Note that this command only change the block device size; it will not
1578 grow the actual filesystems, partitions, etc. that live on that
1579 disk. Usually, you will need to:
1581 #. use **gnt-instance grow-disk**
1583 #. reboot the instance (later, at a convenient time)
1585 #. use a filesystem resizer, such as **ext2online**\(8) or
1586 **xfs\_growfs**\(8) to resize the filesystem, or use **fdisk**\(8) to
1587 change the partition table on the disk
1589 The *disk* argument is the index of the instance disk to grow. The
1590 *amount* argument is given as a number which can have a suffix (like the
1591 disk size in instance create); if the suffix is missing, the value will
1592 be interpreted as mebibytes.
1594 By default, the *amount* value represents the desired increase in the
1595 disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If
1596 the optional ``--absolute`` parameter is passed, then the *amount*
1597 argument doesn't represent the delta, but instead the desired final disk
1598 size (e.g. an amount of 8G will take a disk of size 4G to 8G).
1600 For instances with a drbd template, note that the disk grow operation
1601 might complete on one node but fail on the other; this will leave the
1602 instance with different-sized LVs on the two nodes, but this will not
1603 create problems (except for unused space).
1605 If you do not want gnt-instance to wait for the new disk region to be
1606 synced, use the ``--no-wait-for-sync`` option.
1608 See **ganeti**\(7) for a description of ``--submit`` and other common
1611 Example (increase the first disk for instance1 by 16GiB)::
1613 # gnt-instance grow-disk instance1.example.com 0 16g
1615 Example for increasing the disk size to a certain size::
1617 # gnt-instance grow-disk --absolute instance1.example.com 0 32g
1619 Also note that disk shrinking is not supported; use **gnt-backup
1620 export** and then **gnt-backup import** to reduce the disk size of an
1626 | **recreate-disks** [\--submit] [\--print-job-id]
1627 | [{-n node1:[node2] \| {-I\|\--iallocator *name*}}]
1628 | [\--disk=*N*[:[size=*VAL*][,spindles=*VAL*][,mode=*ro\|rw*]]] {*instance*}
1630 Recreates all or a subset of disks of the given instance.
1632 Note that this functionality should only be used for missing disks; if
1633 any of the given disks already exists, the operation will fail. While
1634 this is suboptimal, recreate-disks should hopefully not be needed in
1635 normal operation and as such the impact of this is low.
1637 If only a subset should be recreated, any number of ``disk`` options can
1638 be specified. It expects a disk index and an optional list of disk
1639 parameters to change. Only ``size``, ``spindles``, and ``mode`` can be
1640 changed while recreating disks. To recreate all disks while changing
1641 parameters on a subset only, a ``--disk`` option must be given for every
1642 disk of the instance.
1644 Optionally the instance's disks can be recreated on different
1645 nodes. This can be useful if, for example, the original nodes of the
1646 instance have gone down (and are marked offline), so we can't recreate
1647 on the same nodes. To do this, pass the new node(s) via ``-n`` option,
1648 with a syntax similar to the **add** command. The number of nodes
1649 passed must equal the number of nodes that the instance currently
1650 has. Note that changing nodes is only allowed when all disks are
1651 replaced, e.g. when no ``--disk`` option is passed.
1653 Another method of choosing which nodes to place the instance on is by
1654 using the specified iallocator, passing the ``--iallocator`` option.
1655 The primary and secondary nodes will be chosen by the specified
1656 iallocator plugin, or by the default allocator if ``.`` is specified.
1658 See **ganeti**\(7) for a description of ``--submit`` and other common
1667 | **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy]
1668 | [\--shutdown-timeout=*N*]
1669 | [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*]
1670 | [\--submit] [\--print-job-id]
1673 Failover will stop the instance (if running), change its primary node,
1674 and if it was originally running it will start it again (on the new
1675 primary). This works for instances with drbd template (in which case you
1676 can only fail to the secondary node) and for externally mirrored
1677 templates (sharedfile, blockdev, rbd and ext) (in which case you can
1678 fail to any other node).
1680 If the instance's disk template is of type sharedfile, blockdev, rbd or
1681 ext, then you can explicitly specify the target node (which can be any
1682 node) using the ``-n`` or ``--target-node`` option, or specify an
1683 iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
1684 omit both, the default iallocator will be used to specify the target
1687 If the instance's disk template is of type drbd, the target node is
1688 automatically selected as the drbd's secondary node. Changing the
1689 secondary node is possible with a replace-disks operation.
1691 Normally the failover will check the consistency of the disks before
1692 failing over the instance. If you are trying to migrate instances off
1693 a dead node, this will fail. Use the ``--ignore-consistency`` option
1694 for this purpose. Note that this option can be dangerous as errors in
1695 shutting down the instance will be ignored, resulting in possibly
1696 having the instance running on two machines in parallel (on
1697 disconnected DRBD drives).
1699 The ``--shutdown-timeout`` is used to specify how much time to wait
1700 before forcing the shutdown (xm destroy in xen, killing the kvm
1701 process, for kvm). By default two minutes are given to each instance
1704 If ``--ignore-ipolicy`` is given any instance policy violations occuring
1705 during this operation are ignored.
1707 See **ganeti**\(7) for a description of ``--submit`` and other common
1712 # gnt-instance failover instance1.example.com
1714 For externally mirrored templates also ``-n`` is available::
1716 # gnt-instance failover -n node3.example.com instance1.example.com
1722 | **migrate** [-f] [\--allow-failover] [\--non-live]
1723 | [\--migration-mode=live\|non-live] [\--ignore-ipolicy]
1724 | [\--no-runtime-changes] [\--submit] [\--print-job-id]
1725 | [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*}
1727 | **migrate** [-f] \--cleanup [\--submit] [\--print-job-id] {*instance*}
1729 Migrate will move the instance to its secondary node without shutdown.
1730 As with failover, it works for instances having the drbd disk template
1731 or an externally mirrored disk template type such as sharedfile,
1732 blockdev, rbd or ext.
1734 If the instance's disk template is of type sharedfile, blockdev, rbd or
1735 ext, then you can explicitly specify the target node (which can be any
1736 node) using the ``-n`` or ``--target-node`` option, or specify an
1737 iallocator plugin using the ``-I`` or ``--iallocator`` option. If you
1738 omit both, the default iallocator will be used to specify the target
1739 node. Alternatively, the default iallocator can be requested by
1740 specifying ``.`` as the name of the plugin.
1742 If the instance's disk template is of type drbd, the target node is
1743 automatically selected as the drbd's secondary node. Changing the
1744 secondary node is possible with a replace-disks operation.
1746 The migration command needs a perfectly healthy instance for drbd
1747 instances, as we rely on the dual-master capability of drbd8 and the
1748 disks of the instance are not allowed to be degraded.
1750 The ``--non-live`` and ``--migration-mode=non-live`` options will
1751 switch (for the hypervisors that support it) between a "fully live"
1752 (i.e. the interruption is as minimal as possible) migration and one in
1753 which the instance is frozen, its state saved and transported to the
1754 remote node, and then resumed there. This all depends on the
1755 hypervisor support for two different methods. In any case, it is not
1756 an error to pass this parameter (it will just be ignored if the
1757 hypervisor doesn't support it). The option ``--migration-mode=live``
1758 option will request a fully-live migration. The default, when neither
1759 option is passed, depends on the hypervisor parameters (and can be
1760 viewed with the **gnt-cluster info** command).
1762 If the ``--cleanup`` option is passed, the operation changes from
1763 migration to attempting recovery from a failed previous migration. In
1764 this mode, Ganeti checks if the instance runs on the correct node (and
1765 updates its configuration if not) and ensures the instances' disks
1766 are configured correctly. In this mode, the ``--non-live`` option is
1769 The option ``-f`` will skip the prompting for confirmation.
1771 If ``--allow-failover`` is specified it tries to fallback to failover if
1772 it already can determine that a migration won't work (e.g. if the
1773 instance is shut down). Please note that the fallback will not happen
1774 during execution. If a migration fails during execution it still fails.
1776 If ``--ignore-ipolicy`` is given any instance policy violations occuring
1777 during this operation are ignored.
1779 The ``--no-runtime-changes`` option forbids migrate to alter an
1780 instance's runtime before migrating it (eg. ballooning an instance
1781 down because the target node doesn't have enough available memory).
1783 If an instance has the backend parameter ``always_failover`` set to
1784 true, then the migration is automatically converted into a failover.
1786 See **ganeti**\(7) for a description of ``--submit`` and other common
1789 Example (and expected output)::
1791 # gnt-instance migrate instance1
1792 Instance instance1 will be migrated. Note that migration
1793 might impact the instance if anything goes wrong (e.g. due to bugs in
1794 the hypervisor). Continue?
1796 Migrating instance instance1.example.com
1797 * checking disk consistency between source and target
1798 * switching node node2.example.com to secondary mode
1799 * changing into standalone mode
1800 * changing disks into dual-master mode
1801 * wait until resync is done
1802 * preparing node2.example.com to accept the instance
1803 * migrating instance to node2.example.com
1804 * switching node node1.example.com to secondary mode
1805 * wait until resync is done
1806 * changing into standalone mode
1807 * changing disks into single-master mode
1808 * wait until resync is done
1816 | **move** [-f] [\--ignore-consistency]
1817 | [-n *node*] [\--shutdown-timeout=*N*] [\--submit] [\--print-job-id]
1818 | [\--ignore-ipolicy]
1821 Move will move the instance to an arbitrary node in the cluster. This
1822 works only for instances having a plain or file disk template.
1824 Note that since this operation is done via data copy, it will take a
1825 long time for big disks (similar to replace-disks for a drbd
1828 The ``--shutdown-timeout`` is used to specify how much time to wait
1829 before forcing the shutdown (e.g. ``xm destroy`` in XEN, killing the
1830 kvm process for KVM, etc.). By default two minutes are given to each
1833 The ``--ignore-consistency`` option will make Ganeti ignore any errors
1834 in trying to shutdown the instance on its node; useful if the
1835 hypervisor is broken and you want to recover the data.
1837 If ``--ignore-ipolicy`` is given any instance policy violations occuring
1838 during this operation are ignored.
1840 See **ganeti**\(7) for a description of ``--submit`` and other common
1845 # gnt-instance move -n node3.example.com instance1.example.com
1851 | **change-group** [\--submit] [\--print-job-id]
1852 | [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*}
1854 This command moves an instance to another node group. The move is
1855 calculated by an iallocator, either given on the command line or as a
1858 If no specific destination groups are specified using ``--to``, all
1859 groups except the one containing the instance are considered.
1861 See **ganeti**\(7) for a description of ``--submit`` and other common
1866 # gnt-instance change-group -I hail --to rack2 inst1.example.com
1875 **add-tags** [\--from *file*] {*instancename*} {*tag*...}
1877 Add tags to the given instance. If any of the tags contains invalid
1878 characters, the entire operation will abort.
1880 If the ``--from`` option is given, the list of tags will be extended
1881 with the contents of that file (each line becomes a tag). In this
1882 case, there is not need to pass tags on the command line (if you do,
1883 both sources will be used). A file name of ``-`` will be interpreted
1889 **list-tags** {*instancename*}
1891 List the tags of the given instance.
1896 **remove-tags** [\--from *file*] {*instancename*} {*tag*...}
1898 Remove tags from the given instance. If any of the tags are not
1899 existing on the node, the entire operation will abort.
1901 If the ``--from`` option is given, the list of tags to be removed will
1902 be extended with the contents of that file (each line becomes a tag).
1903 In this case, there is not need to pass tags on the command line (if
1904 you do, tags from both sources will be removed). A file name of ``-``
1905 will be interpreted as stdin.
1907 .. vim: set textwidth=72 :