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

Name
----

gnt-instance - Ganeti instance administration

Synopsis
--------

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

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

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

COMMANDS
--------

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

ADD
^^^

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

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

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

64 65 66
spindles
  How many spindles (physical disks on the node) the disk should span.

67 68 69 70 71
mode
  The access mode. Either ``ro`` (read-only) or the default ``rw``
  (read-write).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mode
Guido Trotter's avatar
Guido Trotter committed
149
    specifies the connection mode for this NIC: routed, bridged or
150
    openvswitch.
151 152

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The possible hypervisor options are as follows:

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

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

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

    a
        floppy drive

    c
        hard disk

    d
        CDROM drive

    n
        network boot (PXE)

252
    The default is not to set an HVM boot order, which is interpreted
253
    as 'dc'.
254

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

262 263 264
blockdev\_prefix
    Valid for the Xen HVM and PVM hypervisors.

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

269 270 271
floppy\_image\_path
    Valid for the KVM hypervisor.

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

277 278 279 280 281
cdrom\_image\_path
    Valid for the Xen HVM and KVM hypervisors.

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

282 283 284 285 286 287 288
cdrom2\_image\_path
    Valid for the KVM hypervisor.

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

289 290 291 292 293 294
nic\_type
    Valid for the Xen HVM and KVM hypervisors.

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

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

305 306 307 308 309 310 311 312 313 314 315
vif\_type
    Valid for the Xen HVM hypervisor.

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

    - ioemu
    - vif

316 317 318 319 320 321
disk\_type
    Valid for the Xen HVM and KVM hypervisors.

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

322
    - ioemu [default] (HVM & KVM)
323 324
    - paravirtual (HVM & KVM)
    - ide (KVM)
325 326 327 328
    - scsi (KVM)
    - sd (KVM)
    - mtd (KVM)
    - pflash (KVM)
329 330


331 332
cdrom\_disk\_type
    Valid for the KVM hypervisor.
333

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

338 339 340 341 342 343
    - paravirtual
    - ide
    - scsi
    - sd
    - mtd
    - pflash
344 345 346 347 348 349 350 351 352 353 354


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

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

355 356 357 358 359 360 361 362
vnc\_password\_file
    Valid for the Xen HVM and KVM hypervisors.

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

363 364 365 366 367 368 369 370 371 372 373 374 375 376 377
vnc\_tls
    Valid for the KVM hypervisor.

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

vnc\_x509\_path
    Valid for the KVM hypervisor.

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

vnc\_x509\_verify
    Valid for the KVM hypervisor.

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

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

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

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

spice\_ip\_version
    Valid for the KVM hypervisor.

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

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

403 404 405 406 407 408 409
spice\_password\_file
    Valid for the KVM hypervisor.

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

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

    Configures the SPICE lossless image compression. Valid values are:

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

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

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

    - auto
    - never
    - always

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

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

    - auto
    - never
    - always

spice\_streaming\_video
    Valid for the KVM hypervisor.

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

    - off
    - all
    - filter

spice\_playback\_compression
    Valid for the KVM hypervisor.

    Configures whether SPICE should compress audio streams or not.

456 457 458 459 460 461
spice\_use\_tls
    Valid for the KVM hypervisor.

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

462 463 464 465
spice\_tls\_ciphers
    Valid for the KVM hypervisor.

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

spice\_use\_vdagent
    Valid for the KVM hypervisor.

    Enables or disables passing mouse events via SPICE vdagent.

473 474 475 476 477 478 479 480 481 482 483 484 485
cpu\_type
    Valid for the KVM hypervisor.

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

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

    For more information please refer to the KVM manual.

486 487 488 489 490 491
acpi
    Valid for the Xen HVM and KVM hypervisors.

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

Jose A. Lopes's avatar
Jose A. Lopes committed
492 493 494
    ACPI should be enabled for user shutdown detection.  See
    ``user_shutdown``.

495 496 497
pae
    Valid for the Xen HVM and KVM hypervisors.

498
    A boolean option that specifies if the hypervisor should enable
499 500 501
    PAE support for this instance. The default is false, disabling PAE
    support.

502 503 504 505 506 507 508
viridian
    Valid for the Xen HVM hypervisor.

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

509 510 511 512 513 514 515 516 517 518 519 520 521
use\_localtime
    Valid for the Xen HVM and KVM hypervisors.

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

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

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

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

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

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

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

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

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

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

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

560 561 562 563
serial\_console
    Valid for the KVM hypervisor.

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

Guido Trotter's avatar
Guido Trotter committed
570 571 572 573 574 575 576 577
serial\_speed
    Valid for the KVM hypervisor.

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

578 579 580
disk\_cache
    Valid for the KVM hypervisor.

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

591 592 593 594 595 596 597 598
disk\_aio
    Valid for the KVM hypervisor.

    This is an optional parameter that specifies the aio mode
    for the disks. KVM default is to use the 'threads' mode,
    so if not explicitly specified, the native mode will not
    be used. Possible values are: threads or native.

599 600 601
security\_model
    Valid for the KVM hypervisor.

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

606 607
    Under *user* kvm will drop privileges and become the user
    specified by the security\_domain parameter.
608

609
    Under *pool* a global cluster pool of users will be used, making
610 611 612 613 614 615
    sure no two instances share the same user on the same node. (this
    mode is not implemented yet)

security\_domain
    Valid for the KVM hypervisor.

616 617
    Under security model *user* the username to run the instance
    under.  It must be a valid username existing on the host.
618

619
    Cannot be set under security model *none* or *pool*.
620 621 622 623

kvm\_flag
    Valid for the KVM hypervisor.

624 625 626
    If *enabled* the -enable-kvm flag is passed to kvm. If *disabled*
    -disable-kvm is passed. If unset no flag is passed, and the
    default running mode for your kvm binary will be used.
627 628 629 630 631 632 633 634 635 636 637

mem\_path
    Valid for the KVM hypervisor.

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

use\_chroot
    Valid for the KVM hypervisor.

638
    This boolean option determines whether to run the KVM instance in a
639 640 641 642 643 644 645 646
    chroot directory.

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

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

Jose A. Lopes's avatar
Jose A. Lopes committed
647 648 649 650 651 652 653 654 655 656 657 658 659
user\_shutdown
    Valid for the KVM hypervisor.

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

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

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

660 661 662 663 664 665 666 667 668 669 670 671
migration\_downtime
    Valid for the KVM hypervisor.

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

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

cpu\_mask
672
    Valid for the Xen, KVM and LXC hypervisors.
673

674 675
    The processes belonging to the given instance are only scheduled
    on the specified CPUs.
676

677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694
    The format of the mask can be given in three forms. First, the word
    "all", which signifies the common case where all VCPUs can live on
    any CPU, based on the hypervisor's decisions.

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

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

695 696
    Example:

697
    .. code-block:: bash
698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716

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

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

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

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

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

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

718 719 720 721 722 723 724 725 726 727 728 729
cpu\_cap
    Valid for the Xen hypervisor.

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

cpu\_weight
    Valid for the Xen hypervisor.

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

730 731 732 733 734 735 736
usb\_mouse
    Valid for the KVM hypervisor.

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

737 738 739 740 741 742
keymap
    Valid for the KVM hypervisor.

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

743 744 745 746 747 748 749 750 751
reboot\_behavior
    Valid for Xen PVM, Xen HVM and KVM hypervisors.

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

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

752 753 754 755 756 757 758 759 760 761 762 763 764 765 766
cpu\_cores
    Valid for the KVM hypervisor.

    Number of emulated CPU cores.

cpu\_threads
    Valid for the KVM hypervisor.

    Number of emulated CPU threads.

cpu\_sockets
    Valid for the KVM hypervisor.

    Number of emulated CPU sockets.

Guido Trotter's avatar
Guido Trotter committed
767
soundhw
768
    Valid for the KVM and XEN hypervisors.
Guido Trotter's avatar
Guido Trotter committed
769 770 771 772

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

773 774 775 776 777 778 779 780 781 782 783 784 785
cpuid
    Valid for the XEN hypervisor.

    Modify the values returned by CPUID_ instructions run within instances.

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

    See the XEN documentation for syntax and more information.

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

Guido Trotter's avatar
Guido Trotter committed
786 787 788
usb\_devices
    Valid for the KVM hypervisor.

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

Guido Trotter's avatar
Guido Trotter committed
797 798 799 800 801
vga
    Valid for the KVM hypervisor.

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

Guido Trotter's avatar
Guido Trotter committed
802 803 804 805
kvm\_extra
    Valid for the KVM hypervisor.

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

810 811 812 813 814 815
machine\_version
    Valid for the KVM hypervisor.

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

817 818 819 820 821 822 823 824 825 826
migration\_caps
    Valid for the KVM hypervisor.

    Enable specific migration capabilities by providing a ":" separated
    list of supported capabilites. QEMU version 1.7.0 defines
    x-rdma-pin-all, auto-converge, zero-blocks, and xbzrle. Please note
    that while a combination of xbzrle and auto-converge might speed up
    the migration process significantly, the first may cause BSOD on
    Windows8r2 instances running on drbd.

827 828 829 830 831
kvm\_path
    Valid for the KVM hypervisor.

    Path to the userspace KVM (or qemu) program.

832 833 834 835 836 837 838 839 840 841 842 843 844
vnet\_hdr
    Valid for the KVM hypervisor.

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

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

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

845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863
virtio\_net\_queues
    Valid for the KVM hypervisor.

    Set a number of queues (file descriptors) for tap device to
    parallelize packets sending or receiving. Tap devices will be
    created with MULTI_QUEUE (IFF_MULTI_QUEUE) support. This only
    works with KVM paravirtual nics (virtio-net) and the maximum
    number of queues is limited to ``8``. Tehnically this is an
    extension of ``vnet_hdr`` which must be enabled for multiqueue
    support.

    If set to ``1`` queue, it effectively disables multiqueue support
    on the tap and virio-net devices.

    For instances it is necessary to manually set number of queues (on
    Linux using: ``ethtool -L ethX combined $queues``).

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

Iustin Pop's avatar
Iustin Pop committed
864
The ``-O (--os-parameters)`` option allows customisation of the OS
865 866 867
parameters. The actual parameter names and values depend on the OS being
used, but the syntax is the same key=value. For example, setting a
hypothetical ``dhcp`` parameter to yes can be achieved by::
868 869 870

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

871 872 873 874 875 876 877 878 879 880 881 882
You can also specify OS parameters that should not be logged but reused
at the next reinstall with ``--os-parameters-private`` and OS parameters
that should not be logged or saved to configuration with
``--os-parameters-secret``. Bear in mind that:

  * Launching the daemons in debug mode will cause debug logging to
    happen, which leaks private and secret parameters to the log files.
    Do not use the debug mode in production. Deamons will emit a warning
    on startup if they are in debug mode.
  * You will have to pass again all ``--os-parameters-secret`` parameters
    should you want to reinstall this instance.

883 884 885 886 887
The ``-I (--iallocator)`` option specifies the instance allocator plugin
to use (``.`` means the default allocator). If you pass in this option
the allocator will select nodes for this instance automatically, so you
don't need to pass them with the ``-n`` option. For more information
please refer to the instance allocator documentation.
888

Iustin Pop's avatar
Iustin Pop committed
889
The ``-t (--disk-template)`` options specifies the disk layout type
890 891 892 893
for the instance. If no disk template is specified, the default disk
template is used. The default disk template is the first in the list
of enabled disk templates, which can be adjusted cluster-wide with
``gnt-cluster modify``. The available choices for disk templates are:
894 895 896 897 898 899 900 901

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

file
    Disk devices will be regular files.

902 903 904
sharedfile
    Disk devices will be regulare files on a shared directory.

905 906 907 908 909 910
plain
    Disk devices will be logical volumes.

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

911 912 913
rbd
    Disk devices will be rbd volumes residing inside a RADOS cluster.

914 915 916 917 918 919
blockdev
    Disk devices will be adopted pre-existent block devices.

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

Iustin Pop's avatar
Iustin Pop committed
921
The optional second value of the ``-n (--node)`` is used for the drbd
922 923 924 925 926 927
template type and specifies the remote node.

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

The ``--file-storage-dir`` specifies the relative path under the
Iustin Pop's avatar
Iustin Pop committed
928 929
cluster-wide file storage directory to store file-based disks. It is
useful for having different subdirectories for different
930
instances. The full path of the directory where the disk files are
Iustin Pop's avatar
Iustin Pop committed
931
stored will consist of cluster-wide file storage directory + optional
932 933
subdirectory + instance name. This option is only relevant for
instances using the file storage backend.
934 935

The ``--file-driver`` specifies the driver to use for file-based
936 937 938
disks. Note that currently these drivers work with the xen hypervisor
only. This option is only relevant for instances using the file
storage backend. The available choices are:
939 940

loop
941 942 943 944 945 946
    Kernel loopback driver. This driver uses loopback devices to
    access the filesystem within the file. However, running I/O
    intensive applications in your instance using the loop driver
    might result in slowdowns. Furthermore, if you use the loopback
    driver consider increasing the maximum amount of loopback devices
    (on most systems it's 8) using the max\_loop param.
947 948

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

956 957 958
blktap2
    Analogous to the blktap driver, but used by newer versions of Xen.

959 960 961
If ``--ignore-ipolicy`` is given any instance policy violations occuring
during this operation are ignored.

962 963 964 965
The ``-c`` and ``--communication`` specify whether to enable/disable
instance communication, which is a communication mechanism between the
instance and the host.

966
See **ganeti**\(7) for a description of ``--submit`` and other common
967 968
options.

969 970
Example::

971
    # gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \
972
      -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
973 974
    # gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \
      -o debian-etch -n node1.example.com instance1.example.com
975
    # gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \
976 977
      -B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com
    # gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
978
      -n node1.example.com:node2.example.com instance2.example.com
979 980 981 982 983 984 985
    # gnt-instance add -t rbd --disk 0:size=30g -B maxmem=512 -o debian-etch \
      -n node1.example.com instance1.example.com
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1 -B maxmem=512 \
      -o debian-etch -n node1.example.com instance1.example.com
    # gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1,param1=val1 \
      --disk 1:size=40g,provider=pvdr2,param2=val2,param3=val3 -B maxmem=512 \
      -o debian-etch -n node1.example.com instance1.example.com
986 987 988 989 990


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

991 992 993
| **batch-create**
| [{-I|\--iallocator} *instance allocator*]
| {instances\_file.json}
994 995

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

1002 1003 1004 1005
The instance file must be a valid-formed JSON file, containing an
array of dictionaries with instance creation parameters. All parameters
(except ``iallocator``) which are valid for the instance creation
OP code are allowed. The most important ones are:
1006

1007 1008
instance\_name
    The FQDN of the new instance.
1009 1010 1011 1012 1013

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

1014 1015 1016 1017 1018
disks
    Array of disk specifications. Each entry describes one disk as a
    dictionary of disk parameters.

beparams
1019 1020 1021
    A dictionary of backend parameters.

hypervisor
1022
    The hypervisor for the instance.
1023

1024 1025 1026
hvparams
    A dictionary with the hypervisor options. If not passed, the default
    hypervisor options will be inherited.
1027 1028

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

1034
pnode, snode
1035
    The primary and optionally the secondary node to use for the
1036 1037 1038
    instance (in case an iallocator script is not used). If those
    parameters are given, they have to be given consistently for all
    instances in the batch operation.
1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058

start
    whether to start the instance

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

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

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


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

1059 1060 1061 1062 1063 1064 1065 1066 1067
    [
      {
        "mode": "create",
        "instance_name": "instance1.example.com",
        "disk_template": "drbd",
        "os_type": "debootstrap",
        "disks": [{"size":"1024"}],
        "nics": [{}],
        "hypervisor": "xen-pvm"
1068
      },
1069 1070 1071 1072 1073 1074 1075
      {
        "mode": "create",
        "instance_name": "instance2.example.com",
        "disk_template": "drbd",
        "os_type": "debootstrap",
        "disks": [{"size":"4096", "mode": "rw", "vg": "xenvg"}],
        "nics": [{}],
1076 1077
        "hypervisor": "xen-hvm",
        "hvparams": {"acpi": true},
1078
        "beparams": {"maxmem": 512, "minmem": 256}
1079
      }
1080
    ]
1081 1082 1083 1084 1085

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

    # gnt-instance batch-create instances.json
1086
    Submitted jobs 37, 38
1087

1088 1089 1090 1091 1092 1093 1094 1095

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


1096 1097 1098
REMOVE
^^^^^^

1099 1100
| **remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit]
| [\--print-job-id] [\--force] {*instance*}
1101 1102 1103

Remove an instance. This will remove all data from the instance and
there is *no way back*. If you are not sure if you use an instance
1104 1105
again, use **shutdown** first and leave it in the shutdown state for a
while.
1106 1107 1108

The ``--ignore-failures`` option will cause the removal to proceed
even in the presence of errors during the removal of the instance
1109 1110
(e.g. during the shutdown or the disk removal). If this option is not
given, the command will stop at the first error.
1111 1112 1113 1114 1115 1116

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

1117 1118
The ``--force`` option is used to skip the interactive confirmation.

1119
See **ganeti**\(7) for a description of ``--submit`` and other common
1120 1121
options.

1122 1123 1124 1125 1126 1127 1128 1129 1130
Example::

    # gnt-instance remove instance1.example.com


LIST
^^^^

| **list**
Iustin Pop's avatar
Iustin Pop committed
1131 1132
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v]
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...]
1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143

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

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

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

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

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

1155
@QUERY_FIELDS_INSTANCE@
1156 1157

If the value of the option starts with the character ``+``, the new
Iustin Pop's avatar
Iustin Pop committed
1158 1159
field(s) will be added to the default list. This allows one to quickly
see the default list plus a few other fields, instead of retyping the
1160
entire list of fields.
1161 1162 1163

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

1171
If exactly one argument is given and it appears to be a query filter
1172
(see **ganeti**\(7)), the query result is filtered accordingly. For
1173 1174 1175 1176 1177 1178
ambiguous cases (e.g. a single field name as a filter) the ``--filter``
(``-F``) option forces the argument to be treated as a filter (e.g.
``gnt-instance list -F admin_state``).

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

1180 1181

LIST-FIELDS
1182
^^^^^^^^^^^
1183 1184 1185 1186 1187 1188

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

Lists available fields for instances.


1189 1190 1191
INFO
^^^^

Iustin Pop's avatar
Iustin Pop committed
1192
**info** [-s \| \--static] [\--roman] {\--all \| *instance*}
1193 1194

Show detailed information about the given instance(s). This is
1195 1196
different from **list** as it shows detailed data about the instance's
disks (especially useful for the drbd disk template).
1197 1198 1199 1200 1201 1202 1203 1204

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

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

1205 1206 1207
The ``--roman`` option can be used to cause envy among people who like
ancient cultures, but are stuck with non-latin-friendly cluster
virtualization technologies.
1208 1209 1210 1211 1212

MODIFY
^^^^^^

| **modify**
Iustin Pop's avatar
Iustin Pop committed
1213 1214 1215
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*]
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*]
| [{-m|\--runtime-memory} *SIZE*]
1216 1217 1218 1219 1220 1221 1222 1223 1224
| [\--net add[:options...] \|
|  \--net [*N*:]add[,options...] \|
|  \--net [*ID*:]remove \|
|  \--net *ID*:modify[,options...]]
| [\--disk add:size=*SIZE*[,options...] \|
|  \--disk *N*:add,size=*SIZE*[,options...] \|
|  \--disk *N*:add,size=*SIZE*,provider=*PROVIDER*[,options...][,param=*value*... ] \|
|  \--disk *ID*:modify[,options...]
|  \--disk [*ID*:]remove]
1225
| [{-t|\--disk-template} plain \| {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync]
1226
| [\--new-primary=*node*]
Iustin Pop's avatar
Iustin Pop committed
1227 1228
| [\--os-type=*OS* [\--force-variant]]
| [{-O|\--os-parameters} *param*=*value*... ]
1229
| [--os-parameters-private *param*=*value*... ]
Iustin Pop's avatar
Iustin Pop committed
1230
| [\--offline \| \--online]
1231
| [\--submit] [\--print-job-id]
Iustin Pop's avatar
Iustin Pop committed
1232
| [\--ignore-ipolicy]
1233
| [\--hotplug]
1234
| [\--hotplug-if-possible]
1235 1236 1237
| {*instance*}

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

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

Iustin Pop's avatar
Iustin Pop committed
1247 1248 1249 1250 1251 1252 1253 1254
The ``-t (--disk-template)`` option will change the disk template of
the instance.  Currently only conversions between the plain and drbd
disk templates are supported, and the instance must be stopped before
attempting the conversion. When changing from the plain to the drbd
disk template, a new secondary node must be specified via the ``-n``
option. The option ``--no-wait-for-sync`` can be used when converting
to the ``drbd`` template in order to make the instance available for
startup before DRBD has finished resyncing.
1255

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

1260 1261 1262
The ``--disk add:size=*SIZE*,[options..]`` option adds a disk to the
instance, and ``--disk *N*:add:size=*SIZE*,[options..]`` will add a disk
to the the instance at a specific index. The available options are the
1263
same as in the **add** command(``spindles``, ``mode``, ``name``, ``vg``,
1264 1265 1266 1267 1268 1269 1270 1271 1272 1273
``metavg``). Per default, gnt-instance waits for the disk mirror to sync.
If you do not want this behavior, use the ``--no-wait-for-sync`` option.
When adding an ExtStorage disk, the ``provider=*PROVIDER*`` option is
also mandatory and specifies the ExtStorage provider. Also, for
ExtStorage disks arbitrary parameters can be passed as additional comma
separated options, same as in the **add** command. The ``--disk remove``
option will remove the last disk of the instance. Use
``--disk `` *ID*``:remove`` to remove a disk by its identifier. *ID*
can be the index of the disk, the disks's name or the disks's UUID. The
``--disk *ID*:modify[,options...]`` will change the options of the disk.
1274 1275 1276 1277 1278 1279
Available options are:

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

name
1280
   This option specifies a name for the disk, which can be used as a disk
1281 1282 1283 1284 1285 1286 1287 1288 1289
   identifier. An instance can not have two disks with the same name.

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

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

1297 1298 1299 1300 1301
The option ``--new-primary`` will set the new primary node of an instance
assuming the disks have already been moved manually. Unless the ``--force``
option is given, it is verified that the instance is no longer running
on its current primary node.

1302 1303 1304 1305 1306 1307 1308
The ``--online`` and ``--offline`` options are used to transition an
instance into and out of the ``offline`` state. An instance can be
turned offline only if it was previously down. The ``--online`` option
fails if the instance was not in the ``offline`` state, otherwise it
changes instance's state to ``down``. These modifications take effect
immediately.

1309 1310 1311
If ``--ignore-ipolicy`` is given any instance policy violations occuring
during this operation are ignored.

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

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

1327
See **ganeti**\(7) for a description of ``--submit`` and other common
1328 1329
options.

1330
Most of the changes take effect at the next restart. If the instance is
1331 1332 1333 1334 1335
running, there is no effect on the instance.

REINSTALL
^^^^^^^^^

Iustin Pop's avatar
Iustin Pop committed
1336 1337 1338
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*]
| [\--force-multiple]
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all]
1339 1340 1341 1342
| [{-O|\--os-parameters} *OS\_PARAMETERS*]
| [--os-parameters-private} *OS\_PARAMETERS*]
| [--os-parameters-secret} *OS\_PARAMETERS*]
| [\--submit] [\--print-job-id]
1343
| {*instance*...}
1344 1345

Reinstalls the operating system on the given instance(s). The
Iustin Pop's avatar
Iustin Pop committed
1346 1347
instance(s) must be stopped when running this command. If the ``-o
(--os-type)`` is specified, the operating system is changed.
1348 1349 1350

The ``--select-os`` option switches to an interactive OS reinstall.
The user is prompted to select the OS template from the list of
Iustin Pop's avatar
Iustin Pop committed
1351 1352 1353
available OS templates. OS parameters can be overridden using ``-O
(--os-parameters)`` (more documentation for this option under the
**add** command).
1354 1355 1356 1357

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

1362
See **ganeti**\(7) for a description of ``--submit`` and other common
1363
options.
1364 1365 1366 1367

RENAME
^^^^^^

1368
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit] [\--print-job-id]
1369 1370
| {*instance*} {*new\_name*}

1371 1372 1373 1374 1375 1376
Renames the given instance. The instance must be stopped when running
this command. The requirements for the new name are the same as for
adding an instance: the new name must be resolvable and the IP it
resolves to must not be reachable (in order to prevent duplicate IPs
the next time the instance is started). The IP test can be skipped if
the ``--no-ip-check`` option is passed.
1377

1378 1379 1380 1381
Note that you can rename an instance to its same name, to force
re-executing the os-specific rename script for that instance, if
needed.

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

1388
See **ganeti**\(7) for a description of ``--submit`` and other common
1389
options.
1390 1391 1392 1393 1394 1395 1396 1397

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

STARTUP
^^^^^^^

| **startup**
Iustin Pop's avatar
Iustin Pop committed
1398 1399 1400 1401 1402 1403
| [\--force] [\--ignore-offline]
| [\--force-multiple] [\--no-remember]
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
| [{-H|\--hypervisor-parameters} ``key=value...``]
| [{-B|\--backend-parameters} ``key=value...``]
1404
| [\--submit] [\--print-job-id] [\--paused]
1405 1406
| {*name*...}

1407 1408
Starts one or more instances, depending on the following options.  The
four available modes are:
1409

Iustin Pop's avatar
Iustin Pop committed
1410
\--instance
1411 1412 1413
    will start the instances given as arguments (at least one argument
    required); this is the default selection

Iustin Pop's avatar
Iustin Pop committed
1414
\--node
1415 1416 1417
    will start the instances who have the given node as either primary
    or secondary

Iustin Pop's avatar
Iustin Pop committed
1418
\--primary
1419 1420 1421
    will start all instances whose primary node is in the list of nodes
    passed as arguments (at least one node required)

Iustin Pop's avatar
Iustin Pop committed
1422
\--secondary
1423 1424 1425
    will start all instances whose secondary node is in the list of
    nodes passed as arguments (at least one node required)

Iustin Pop's avatar
Iustin Pop committed
1426
\--all
1427 1428
    will start all instances in the cluster (no arguments accepted)

Iustin Pop's avatar
Iustin Pop committed
1429
\--tags
1430 1431 1432
    will start all instances in the cluster with the tags given as
    arguments

Iustin Pop's avatar
Iustin Pop committed
1433
\--node-tags
1434 1435 1436
    will start all instances in the cluster on nodes with the tags
    given as arguments

Iustin Pop's avatar
Iustin Pop committed
1437
\--pri-node-tags
1438 1439 1440
    will start all instances in the cluster on primary nodes with the
    tags given as arguments

Iustin Pop's avatar
Iustin Pop committed
1441
\--sec-node-tags
1442 1443 1444 1445
    will start all instances in the cluster on secondary nodes with the
    tags given as arguments

Note that although you can pass more than one selection option, the
1446 1447
last one wins, so in order to guarantee the desired result, don't pass
more than one such option.
1448 1449

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

1453 1454
The ``--force-multiple`` will skip the interactive confirmation in the
case the more than one instance will be affected.
1455

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

Iustin Pop's avatar
Iustin Pop committed
1462 1463 1464 1465 1466
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)``
options specify temporary hypervisor and backend parameters that can
be used to start an instance with modified parameters. They can be
useful for quick testing without having to modify an instance back and
forth, e.g.::
1467

Stephen Shirley's avatar
Stephen Shirley committed
1468
    # gnt-instance start -H kernel_args="single" instance1
1469
    # gnt-instance start -B maxmem=2048 instance2
1470 1471


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

1479 1480 1481 1482 1483
The ``--paused`` option is only valid for Xen and kvm hypervisors.  This
pauses the instance at the start of bootup, awaiting ``gnt-instance
console`` to unpause it, allowing the entire boot process to be
monitored for debugging.

1484
See **ganeti**\(7) for a description of ``--submit`` and other common
1485 1486
options.

1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497
Example::

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


SHUTDOWN
^^^^^^^^

| **shutdown**
Iustin Pop's avatar
Iustin Pop committed
1498
| [\--timeout=*N*]
1499
| [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember]
Iustin Pop's avatar
Iustin Pop committed
1500 1501
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1502
| [\--submit] [\--print-job-id]
1503 1504
| {*name*...}

1505 1506 1507 1508
Stops one or more instances. If the instance cannot be cleanly stopped
during a hardcoded interval (currently 2 minutes), it will forcibly
stop the instance (equivalent to switching off the power on a physical
machine).
1509 1510 1511 1512 1513 1514 1515 1516

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

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

1520 1521 1522
``--ignore-offline`` can be used to ignore offline primary nodes and
force the instance to be marked as stopped. This option should be used
with care as it can lead to an inconsistent cluster state.
1523

1524 1525 1526 1527
Use ``--force`` to be able to shutdown an instance even when it's marked
as offline. This is useful is an offline instance ends up in the
``ERROR_up`` state, for example.

1528 1529 1530 1531 1532 1533 1534 1535 1536
The ``--no-remember`` option will perform the shutdown but not change
the state of the instance in the configuration file (if it was running
before, Ganeti will still thinks it needs to be running). This can be
useful for a cluster-wide shutdown, where some instances are marked as
up and some as down, and you don't want to change the running state:
you just need to disable the watcher, shutdown all instances with
``--no-remember``, and when the watcher is activated again it will
restore the correct runtime state for all instances.

1537
See **ganeti**\(7) for a description of ``--submit`` and other common
1538 1539
options.

1540 1541 1542 1543 1544 1545 1546 1547 1548 1549
Example::

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


REBOOT
^^^^^^

| **reboot**
Iustin Pop's avatar
Iustin Pop committed
1550 1551 1552 1553 1554 1555
| [{-t|\--type} *REBOOT-TYPE*]
| [\--ignore-secondaries]
| [\--shutdown-timeout=*N*]
| [\--force-multiple]
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \|
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags]
1556
| [\--submit] [\--print-job-id]
1557 1558
| [*name*...]

1559
Reboots one or more instances. The type of reboot depends on the value
Iustin Pop's avatar
Iustin Pop committed
1560
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot
1561 1562 1563 1564
does a instance stop, recreates the hypervisor config for the instance
and starts the instance. A full reboot does the equivalent of
**gnt-instance shutdown && gnt-instance startup**.  The default is
hard reboot.
1565

1566 1567
For the hard reboot the option ``--ignore-secondaries`` ignores errors
for the secondary node while re-assembling the instance disks.
1568 1569 1570

The ``--instance``, ``--node``, ``--primary``, ``--secondary``,
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and
1571 1572
``--sec-node-tags`` options are similar as for the **startup** command
and they influence the actual instances being rebooted.
1573 1574 1575

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

1579 1580
The ``--force-multiple`` will skip the interactive confirmation in the
case the more than one instance will be affected.
1581

1582
See **ganeti**\(7) for a description of ``--submit`` and other common
1583 1584
options.