Synnefo » snf-ganeti

<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->

  <!-- Please adjust the date whenever revising the manpage. -->

  <!ENTITY dhdate      "<date>January 22, 2010</date>">

  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are

       allowed: see man(7), man(1). -->

  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">

  <!ENTITY dhucpackage "<refentrytitle>gnt-instance</refentrytitle>">

  <!ENTITY dhpackage   "gnt-instance">

  <!ENTITY debian      "<productname>Debian</productname>">

  <!ENTITY gnu         "<acronym>GNU</acronym>">

  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">

  <!ENTITY footer SYSTEM "footer.sgml">

]>

<refentry>

  <refentryinfo>

    <copyright>

      <year>2006</year>

      <year>2007</year>

      <year>2008</year>

      <year>2009</year>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>ganeti 2.0</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>&dhpackage;</refname>

    <refpurpose>ganeti instance administration</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&dhpackage; </command>

      <arg choice="req">command</arg>

      <arg>arguments...</arg>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1>

    <title>DESCRIPTION</title>

    <para>

      The <command>&dhpackage;</command> is used for instance

      administration in the ganeti system.

    </para>

  </refsect1>

  <refsect1>

    <title>COMMANDS</title>

    <refsect2>

      <title>Creation/removal/querying</title>

      <refsect3>

        <title>ADD</title>

        <cmdsynopsis>

          <command>add</command>

          <sbr>

          <arg choice="req">-t<group choice="req">

              <arg>diskless</arg>

              <arg>file</arg>

              <arg>plain</arg>

              <arg>drbd</arg>

            </group></arg>

          <sbr>

          <group choice="req">

            <arg rep="repeat">--disk=<replaceable>N</replaceable>:<group choice="req">

                <arg>size=<replaceable>VAL</replaceable></arg>

                <arg>adopt=<replaceable>LV</replaceable></arg>

              </group>,mode=<replaceable>ro|rw</replaceable></arg>

            <arg>-s <replaceable>SIZE</replaceable></arg>

          </group>

          <sbr>

          <arg>--no-ip-check</arg>

          <arg>--no-name-check</arg>

          <arg>--no-start</arg>

          <arg>--no-install</arg>

          <sbr>

          <group>

            <arg rep="repeat">--net=<replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>

            <arg>--no-nics</arg>

          </group>

          <sbr>

          <arg>-B <replaceable>BEPARAMS</replaceable></arg>

          <sbr>

          <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>

          <sbr>

          <arg>--file-storage-dir <replaceable>dir_path</replaceable></arg>

          <arg>--file-driver<group choice="req">

              <arg>loop</arg>

              <arg>blktap</arg>

            </group></arg>

          <sbr>

          <group choice="req">

            <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>

            <arg>--iallocator <replaceable>name</replaceable></arg>

          </group>

          <sbr>

          <arg choice="req">-o <replaceable>os-type</replaceable></arg>

          <sbr>

          <arg>--submit</arg>

          <sbr>

          <arg choice="req"><replaceable>instance</replaceable></arg>

        </cmdsynopsis>

        <para>

          Creates a new instance on the specified host. The

          <replaceable>instance</replaceable> 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.

        </para>

        <para>

          The <option>disk</option> 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 source needs to be

          given, and optionally the access mode (read-only or the

          default of read-write) can also be specified.  The size is

          interpreted (when no unit is given) in mebibytes. You can

          also use one of the suffixes

          <literal>m</literal>, <literal>g</literal> or

          <literal>t</literal> to specificy the exact the units used;

          these suffixes map to mebibytes, gibibytes and tebibytes.

        </para>

        <para>

          When using the <option>adopt</option> 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 (e.q. plain KVM with LVM) to being managed via

          Ganeti. Note that this works only for the `plain' disk

          template (see below for template details).

        </para>

        <para>

          Alternatively, a single-disk instance can be created via the

          <option>-s</option> 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).

        </para>

        <para>

          The minimum disk specification is therefore

          <userinput>--disk 0:size=20G</userinput> (or <userinput>-s

          20G</userinput> when using the <option>-s</option> option),

          and a three-disk instance can be specified as

          <userinput>--disk 0:size=20G --disk 1:size=4G --disk

          2:size=100G</userinput>.

        </para>

        <para>

          The <option>--no-ip-check</option> skips the checks that are

          done to see if the instance's IP is not already alive

          (i.e. reachable from the master node).

        </para>

        <para>

          The <option>--no-name-check</option> 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 <option>--no-ip-check</option> option.

        </para>

        <para>

          If you don't wat the instance to automatically start after

          creation, this is possible via the

          <option>--no-start</option> option. This will leave the

          instance down until a subsequent <command>gnt-instance

          start</command> command.

        </para>

        <para>

          The NICs of the instances can be specified via the

          <option>--net</option> option. By default, one NIC is

          created for the instance, with a random MAC, and set

          up according the the cluster level nic parameters.

          Each NIC can take these parameters (all optional):

          <variablelist>

            <varlistentry>

              <term>mac</term>

              <listitem>

                <simpara>either a value or <constant>GENERATE</constant>

                  to generate a new unique MAC</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>ip</term>

              <listitem>

                <simpara>specifies the IP address assigned to the

                  instance from the Ganeti side (this is not necessarily

                  what the instance will use, but what the node expects

                  the instance to use)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>mode</term>

              <listitem>

                <simpara>specifies the connection mode for this nic:

                  routed or bridged.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>link</term>

              <listitem>

                <simpara>in bridged mode specifies the bridge to attach

                  this NIC to, in routed mode it's intended to

                  differentiate between different routing tables/instance

                  groups (but the meaning is dependent on the network

                  script, see gnt-cluster(8) for more details)</simpara>

              </listitem>

            </varlistentry>

          </variablelist>

          Of these "mode" and "link" are nic parameters, and inherit their

          default at cluster level.

        </para>

        <para>

          Alternatively, if no network is desired for the instance, you

          can prevent the default of one NIC with the

          <option>--no-nics</option> option.

        </para>

        <para>

          The <option>-o</option> options specifies the operating

          system to be installed. The available operating systems can

          be listed with <command>gnt-os

          list</command>. Passing <option>--no-install</option> will

          however skip the OS installation, allowing a manual import

          if so desired. Note that the 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).

        </para>

        <para>

          The <option>-B</option> option specifies the backend

          parameters for the instance. If no such parameters are

          specified, the values are inherited from the cluster. Possible

          parameters are:

          <variablelist>

            <varlistentry>

              <term>memory</term>

              <listitem>

                <simpara>the memory size of the instance; as usual,

                  suffixes can be used to denote the unit, otherwise the

                  value is taken in mebibites</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>vcpus</term>

              <listitem>

                <simpara>the number of VCPUs to assign to the instance

                  (if this value makes sense for the hypervisor)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>auto_balance</term>

              <listitem>

                <simpara>whether the instance is considered in the N+1

                  cluster checks (enough redundancy in the cluster to

                  survive a node failure)</simpara>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          The <option>-H</option> 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 <userinput>-H

          <replaceable>NAME</replaceable></userinput>) the instance

          will inherit the cluster options. The defaults below show

          the cluster defaults at cluster creation time.

        </para>

        <para>

          The possible hypervisor options are as follows:

          <variablelist>

            <varlistentry>

              <term>boot_order</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM

                hypervisors.</simpara>

                <simpara>A string value denoting the boot order. This

                has different meaning for the Xen HVM hypervisor and

                for the KVM one.</simpara>

                <simpara>

                  For Xen HVM, The boot order is a string of letters

                  listing the boot devices, with valid device letters

                  being:

                </simpara>

                  <variablelist>

                    <varlistentry>

                      <term>a</term>

                      <listitem>

                        <para>

                          floppy drive

                        </para>

                      </listitem>

                    </varlistentry>

                    <varlistentry>

                      <term>c</term>

                      <listitem>

                        <para>

                          hard disk

                        </para>

                      </listitem>

                    </varlistentry>

                    <varlistentry>

                      <term>d</term>

                      <listitem>

                        <para>

                          CDROM drive

                        </para>

                      </listitem>

                    </varlistentry>

                    <varlistentry>

                      <term>n</term>

                      <listitem>

                        <para>

                          network boot (PXE)

                        </para>

                      </listitem>

                    </varlistentry>

                  </variablelist>

                <simpara>

                  The default is not to set an HVM boot order which is

                  interpreted as 'dc'.

                </simpara>

                <simpara>

                  For KVM the boot order is either

                  <quote>cdrom</quote>, <quote>disk</quote> or

                  <quote>network</quote>. 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.

                </simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>cdrom_image_path</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <simpara>The path to a CDROM image to attach to the

                instance.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic_type</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <para>

                  This parameter determines the way the network cards

                  are presented to the instance. The possible options are:

                  <simplelist>

                    <member>rtl8139 (default for Xen HVM) (HVM & KVM)</member>

                    <member>ne2k_isa (HVM & KVM)</member>

                    <member>ne2k_pci (HVM & KVM)</member>

                    <member>i82551 (KVM)</member>

                    <member>i82557b (KVM)</member>

                    <member>i82559er (KVM)</member>

                    <member>pcnet (KVM)</member>

                    <member>e1000 (KVM)</member>

                    <member>paravirtual (default for KVM) (HVM & KVM)</member>

                  </simplelist>

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk_type</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <para>

                  This parameter determines the way the disks are

                  presented to the instance. The possible options are:

                  <simplelist>

                    <member>ioemu (default for HVM & KVM) (HVM & KVM)</member>

                    <member>ide (HVM & KVM)</member>

                    <member>scsi (KVM)</member>

                    <member>sd (KVM)</member>

                    <member>mtd (KVM)</member>

                    <member>pflash (KVM)</member>

                  </simplelist>

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>vnc_bind_address</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <para>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.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>vnc_tls</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>A boolean option that controls whether the

                VNC connection is secured with TLS.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>vnc_x509_path</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <para>If <option>vnc_tls</option> is enabled, this

                options specifies the path to the x509 certificate to

                use.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>vnc_x509_verify</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>acpi</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <para>

                  A boolean option that specifies if the hypervisor

                  should enable ACPI support for this instance. By

                  default, ACPI is disabled.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>pae</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <para>

                  A boolean option that specifies if the hypervisor

                  should enabled PAE support for this instance. The

                  default is false, disabling PAE support.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>use_localtime</term>

              <listitem>

                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <para>

                  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.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>kernel_path</term>

              <listitem>

                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>

                <para>

                  This option specifies the path (on the node) to the

                  kernel to boot 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.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>kernel_args</term>

              <listitem>

                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>

                <para>

                  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

                  <option>kernel_path</option> option is also

                  specified.

                </para>

                <para>

                  The default setting for this value is simply

                  <constant>"ro"</constant>, which mounts the root

                  disk (initially) in read-only one. For example,

                  setting this to <userinput>single</userinput> will

                  cause the instance to start in single-user mode.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>initrd_path</term>

              <listitem>

                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>

                <para>

                  This option specifies the path (on the node) to the

                  initrd to boot the instance with. Xen PVM instances

                  can use this always, while for KVM if this option is

                  only used if the <option>kernel_path</option> 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

                  <userinput>no_initrd_path</userinput> for no initrd.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>root_path</term>

              <listitem>

                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>

                <para>

                  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

                  <option>kernel_path</option> option is also

                  specified.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>serial_console</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>This boolean option specifies whether to

                emulate a serial console for the instance.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk_cache</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>The disk cache mode. It can be either

                <userinput>default</userinput> 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.

                </simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>security_model</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>The security model for kvm. Currently one of

                <quote>none</quote>, <quote>user</quote> or

                <quote>pool</quote>. Under <quote>none</quote>, the

                default, nothing is done and instances are run as

                the ganeti daemon user (normally root).

                </simpara>

                <simpara>Under <quote>user</quote> kvm will drop

                privileges and become the user specified by the

                security_domain parameter.

                </simpara>

                <simpara>Under <quote>pool</quote> a global cluster

                pool of users will be used, making sure no two

                instances share the same user on the same node.

                (this mode is not implemented yet)

                </simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>security_domain</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>Under security model <quote>user</quote> the username to

                run the instance under. It must be a valid username

                existing on the host.

                </simpara>

                <simpara>Cannot be set under security model <quote>none</quote>

                or <quote>pool</quote>.

                </simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>kvm_flag</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>If <quote>enabled</quote> the -enable-kvm flag is

                passed to kvm. If <quote>disabled</quote> -disable-kvm is

                passed. If unset no flag is passed, and the default running

                mode for your kvm binary will be used.

                </simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>migration_downtime</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>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.

                </simpara>

                <simpara>This option is only effective with kvm versions >= 87

                and qemu-kvm versions >= 0.11.0.

                </simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>use_chroot</term>

              <listitem>

                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>This boolean option determines wether to run the KVM

                instance in a chroot directory.

                </simpara>

                <para>If it is set to <quote>true</quote>, 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.

                </para>

                <simpara>It is set to <quote>false</quote> by default.</simpara>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          The <option>--iallocator</option> option specifies the instance

          allocator plugin to use. 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 <option>-n</option> option. For more

          information please refer to the instance allocator documentation.

        </para>

        <para>

          The <option>-t</option> options specifies the disk layout type for

          the instance. The available choices are:

          <variablelist>

            <varlistentry>

              <term>diskless</term>

              <listitem>

                <para>

                  This creates an instance with no disks. Its useful for

                  testing only (or other special cases).

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>file</term>

              <listitem>

                <para>Disk devices will be regular files.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>plain</term>

              <listitem>

                <para>Disk devices will be logical volumes.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>drbd</term>

              <listitem>

                <para>

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

                  lvm volumes.

                </para>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          The optional second value of the <option>--node</option> is used for

          the drbd template type and specifies the remote node.

        </para>

        <para>

          If you do not want gnt-instance to wait for the disk mirror

          to be synced, use the <option>--no-wait-for-sync</option>

          option.

        </para>

        <para>

          The <option>--file-storage-dir</option> specifies the relative path

          under the cluster-wide file storage directory to store file-based

          disks. It is useful for having different subdirectories for

          different instances. The full path of the directory where the disk

          files are stored will consist of cluster-wide file storage directory

          + optional subdirectory + instance name. Example:

          /srv/ganeti/file-storage/mysubdir/instance1.example.com. This option

          is only relevant for instances using the file storage backend.

        </para>

        <para>

          The <option>--file-driver</option> specifies the driver to use for

          file-based 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:

          <variablelist>

            <varlistentry>

              <term>loop</term>

              <listitem>

                <para>

                  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.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>blktap</term>

              <listitem>

                <para>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.

                </para>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          The <option>--submit</option> option is used to send the job to

          the master daemon but not wait for its completion. The job

          ID will be shown so that it can be examined via

          <command>gnt-job info</command>.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance add -t file --disk 0:size=30g -B memory=512 -o debian-etch \

  -n node1.example.com --file-storage-dir=mysubdir instance1.example.com

# gnt-instance add -t plain --disk 0:size=30g -B memory=512 -o debian-etch \

  -n node1.example.com instance1.example.com

# gnt-instance add -t drbd --disk 0:size=30g -B memory=512 -o debian-etch \

  -n node1.example.com:node2.example.com instance2.example.com

          </screen>

        </para>

      </refsect3>

      <refsect3>

        <title>BATCH-CREATE</title>

        <cmdsynopsis>

          <command>batch-create</command>

          <arg choice="req">instances_file.json</arg>

        </cmdsynopsis>

        <para>

          This command (similar to the Ganeti 1.2

          <command>batcher</command> tool) submits multiple instance

          creation jobs based on a definition file. The instance

          configurations do not encompass all the possible options for

          the <command>add</command> command, but only a subset.

        </para>

        <para>

          The instance file should be a valid-formed JSON file,

          containing a dictionary with instance name and instance

          parameters. The accepted parameters are:

          <variablelist>

            <varlistentry>

              <term>disk_size</term>

              <listitem>

                <simpara>The size of the disks of the instance.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk_templace</term>

              <listitem>

                <simpara>The disk template to use for the instance,

                the same as in the <command>add</command>

                command.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>backend</term>

              <listitem>

                <simpara>A dictionary of backend parameters.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>hypervisor</term>

              <listitem>

                <simpara>A dictionary with a single key (the

                hypervisor name), and as value the hypervisor

                options. If not passed, the default hypervisor and

                hypervisor options will be inherited.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>mac, ip, mode, link</term>

              <listitem>

                <simpara>Specifications for the one NIC that will be

                created for the instance. 'bridge' is also accepted

                as a backwards compatibile key.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nics</term>

              <listitem>

                <simpara>List of nics that will be created for the

                instance. Each entry 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 use this method for

                specifying nics.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>primary_node, secondary_node</term>

              <listitem>

                <simpara>The primary and optionally the secondary node

                to use for the instance (in case an iallocator script

                is not used).</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>iallocator</term>

              <listitem>

                <simpara>Instead of specifying the nodes, an

                iallocator script can be used to automatically compute

                them.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>start</term>

              <listitem>

                <simpara>whether to start the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>ip_check</term>

              <listitem>

                <simpara>Skip the check for already-in-use instance;

                see the description in the <command>add</command>

                command for details.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>name_check</term>

              <listitem>

                <simpara>Skip the name check for instances;

                see the description in the <command>add</command>

                command for details.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>file_storage_dir, file_driver</term>

              <listitem>

                <simpara>Configuration for the <literal>file</literal>

                disk type, see the <command>add</command> command for

                details.</simpara>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          A simple definition for one instance can be (with most of

          the parameters taken from the cluster defaults):

          <screen>

{

  "instance3": {

    "template": "drbd",

    "os": "debootstrap",

    "disk_size": ["25G"],

    "iallocator": "dumb"

  },

  "instance5": {

    "template": "drbd",

    "os": "debootstrap",

    "disk_size": ["25G"],

    "iallocator": "dumb",

    "hypervisor": "xen-hvm",

    "hvparams": {"acpi": true},

    "backend": {"memory": 512}

  }

}

</screen>

        </para>

        <para>

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

          <screen>

# gnt-instance batch-create instances.json

instance3: 11224

instance5: 11225

</screen>

        </para>

      </refsect3>

      <refsect3>

        <title>REMOVE</title>

        <cmdsynopsis>

          <command>remove</command>

          <arg>--ignore-failures</arg>

          <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>

          <arg>--submit</arg>

          <arg choice="req"><replaceable>instance</replaceable></arg>

        </cmdsynopsis>

        <para>

          Remove an instance. This will remove all data from the

          instance and there is <emphasis>no way back</emphasis>. If

          you are not sure if you use an instance again, use

          <command>shutdown</command> first and leave it in the

          shutdown state for a while.

        </para>

        <para>

          The <option>--ignore-failures</option> option will cause the

          removal to proceed even in the presence of errors during the

          removal of the instance (e.g. during the shutdown or the

          disk removal). If this option is not given, the command will

          stop at the first error.

        </para>

        <para>

          The <option>--shutdown-timeout</option> is used to specify how

          much time to wait before forcing the shutdown (xm destroy in xen,

          killing the kvm process, for kvm). By default two minutes are

          given to each instance to stop.

        </para>

        <para>

          The <option>--submit</option> option is used to send the job to

          the master daemon but not wait for its completion. The job

          ID will be shown so that it can be examined via

          <command>gnt-job info</command>.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance remove instance1.example.com

          </screen>

        </para>

      </refsect3>

      <refsect3>

        <title>LIST</title>

        <cmdsynopsis>

          <command>list</command>

          <arg>--no-headers</arg>

          <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>

          <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>

          <arg>--roman</arg>

          <arg rep="repeat">instance</arg>

        </cmdsynopsis>

        <para>

          Shows the currently configured instances with memory usage,

          disk usage, the node they are running on, and their run

          status.

        </para>

        <para>

          The <option>--no-headers</option> option will skip the

          initial header line. The <option>--separator</option> option

          takes an argument which denotes what will be used between

          the output fields. Both these options are to help scripting.

        </para>

        <para>

          The <option>--roman</option> option allows latin people to better

          understand the cluster instances' status.

        </para>

        <para>

          The <option>-o</option> option takes a comma-separated list

          of output fields. The available fields and their meaning

          are:

          <variablelist>

            <varlistentry>

              <term>name</term>

              <listitem>

                <simpara>the instance name</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>os</term>

              <listitem>

                <simpara>the OS of the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>pnode</term>

              <listitem>

                <simpara>the primary node of the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>snodes</term>

              <listitem>

                <simpara>comma-separated list of secondary nodes for the

                  instance; usually this will be just one node</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>admin_state</term>

              <listitem>

                <simpara>the desired state of the instance (either "yes"

                  or "no" denoting the instance should run or

                  not)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk_template</term>

              <listitem>

                <simpara>the disk template of the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>oper_state</term>

              <listitem>

                <simpara>the actual state of the instance; can be

                one of the values "running", "stopped", "(node

                down)"</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>status</term>

              <listitem>

                <simpara>combined form of admin_state and oper_stat;

                this can be one of:

                <computeroutput>ERROR_nodedown</computeroutput> if the

                node of the instance is down,

                <computeroutput>ERROR_down</computeroutput> if the

                instance should run but is down,

                <computeroutput>ERROR_up</computeroutput> if the

                instance should be stopped but is actually running,

                <computeroutput>ADMIN_down</computeroutput> if the

                instance has been stopped (and is stopped) and

                <computeroutput>running</computeroutput> if the

                instance is set to be running (and is

                running)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>oper_ram</term>

              <listitem>

                <simpara>the actual memory usage of the instance as seen

                  by the hypervisor</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>ip</term>

              <listitem>

                <simpara>the ip address ganeti recognizes as associated with

                the first instance interface</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>mac</term>

              <listitem>

                <simpara>the first instance interface MAC address</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic_mode</term>

              <listitem>

                <simpara>the mode of the first instance NIC

                (routed or bridged)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic_link</term>

              <listitem>

                <simpara>the link of the first instance NIC

                </simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>sda_size</term>

              <listitem>

                <simpara>the size of the instance's first disk</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>sdb_size</term>

              <listitem>

                <simpara>the size of the instance's second disk, if

                any</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>vcpus</term>

              <listitem>

                <simpara>the number of VCPUs allocated to the

                instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>tags</term>

              <listitem>

                <simpara>comma-separated list of the instances's

                tags</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>serial_no</term>

              <listitem>

                <simpara>the so called 'serial number' of the

                instance; this is a numeric field that is incremented

                each time the instance is modified, and it can be used

                to track modifications</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>ctime</term>

              <listitem>

                <para>

                  the creation time of the instance; note that this

                  field contains spaces and as such it's harder to

                  parse

                </para>

                <para>

                  if this attribute is not present (e.g. when

                  upgrading from older versions), then "N/A" will be

                  shown instead

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>mtime</term>

              <listitem>

                <para>

                  the last modification time of the instance; note

                  that this field contains spaces and as such it's

                  harder to parse

                </para>

                <para>

                  if this attribute is not present (e.g. when

                  upgrading from older versions), then "N/A" will be

                  shown instead

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>uuid</term>

              <listitem>

                <simpara>Show the UUID of the instance (generated

                automatically by Ganeti)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>network_port</term>

              <listitem>

                <simpara>If the instance has a network port assigned

                to it (e.g. for VNC connections), this will be shown,

                otherwise <literal>-</literal> will be

                displayed.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>beparams</term>

              <listitem>

                <simpara>A text format of the entire beparams for the

                instance. It's more useful to select individual fields

                from this dictionary, see below.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk.count</term>

              <listitem>

                <simpara>The number of instance disks.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk.size/N</term>

              <listitem>

                <simpara>The size of the instance's Nth disk. This is

                a more generic form of the <literal>sda_size</literal>

                and <literal>sdb_size</literal> fields.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk.sizes</term>

              <listitem>

                <simpara>A comma-separated list of the disk sizes for

                this instance.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk_usage</term>

              <listitem>

                <simpara>The total disk space used by this instance on

                each of its nodes. This is not the instance-visible

                disk size, but the actual disk "cost" of the

                instance.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.mac/N</term>

              <listitem>

                <simpara>The MAC of the Nth instance NIC.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.ip/N</term>

              <listitem>

                <simpara>The IP address of the Nth instance NIC.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.mode/N</term>

              <listitem>

                <simpara>The mode of the Nth instance NIC</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.link/N</term>

              <listitem>

                <simpara>The link of the Nth instance NIC</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.macs</term>

              <listitem>

                <simpara>A comma-separated list of all the MACs of the

                instance's NICs.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.ips</term>

              <listitem>

                <simpara>A comma-separated list of all the IP

                addresses of the instance's NICs.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.modes</term>

              <listitem>

                <simpara>A comma-separated list of all the modes of the

                instance's NICs.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.links</term>

              <listitem>

                <simpara>A comma-separated list of all the link parameters

                of the instance's NICs.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>nic.count</term>

              <listitem>

                <simpara>The number of instance nics.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>hv/<replaceable>NAME</replaceable></term>

              <listitem>

                <simpara>The value of the hypervisor parameter called

                <replaceable>NAME</replaceable>. For details of what

                hypervisor parameters exist and their meaning, see the

                <command>add</command> command.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>be/memory</term>

              <listitem>

                <simpara>The configured memory for the instance.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>be/vcpus</term>

              <listitem>

                <simpara>The configured number of VCPUs for the

                instance.</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>be/auto_balance</term>

              <listitem>

                <simpara>Whether the instance is considered in N+1

                checks.</simpara>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          If the value of the option starts with the character

          <constant>+</constant>, the new field(s) will be added to the

          default list. This allows to quickly see the default list

          plus a few other fields, instead of retyping the entire list

          of fields.

        </para>

        <para>

          There is a subtle grouping about the available output

          fields: all fields except for <option>oper_state</option>,

          <option>oper_ram</option> and <option>status</option> 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.

        </para>

        <para>The default output field list is:

          <simplelist type="inline">

            <member>name</member>

            <member>os</member>

            <member>pnode</member>

            <member>admin_state</member>

            <member>oper_state</member>

            <member>oper_ram</member>

          </simplelist>.

        </para>

      </refsect3>

      <refsect3>

        <title>INFO</title>

        <cmdsynopsis>

          <command>info</command>

          <group>

            <arg>-s</arg>

            <arg>--static</arg>

          </group>

          <arg>--roman</arg>

          <group choice="req">

            <arg>--all</arg>

            <arg rep="repeat"><replaceable>instance</replaceable></arg>

          </group>

        </cmdsynopsis>

        <para>

          Show detailed information about the given instance(s). This is

          different from <command>list</command> as it shows detailed data

          about the instance's disks (especially useful for the drbd disk

          template).

        </para>

        <para>

          If the option <option>-s</option> is used, only information

          available in the configuration file is returned, without

          querying nodes, making the operation faster.

        </para>

        <para>

          Use the <option>--all</option> to get info about all instances,

          rather than explicitly passing the ones you're interested in.

        </para>

        <para>

          The <option>--roman</option> option can be used to cause envy among

          people who like ancient cultures, but are stuck with non-latin-friendly

          cluster virtualization technologies.

        </para>

      </refsect3>

      <refsect3>

        <title>MODIFY</title>

        <cmdsynopsis>

          <command>modify</command>

          <sbr>

          <arg choice="opt">-H <replaceable>HYPERVISOR_PARAMETERS</replaceable></arg>

          <sbr>

          <arg choice="opt">-B <replaceable>BACKEND_PARAMETERS</replaceable></arg>

          <sbr>

          <group>

            <arg>--net add<replaceable><optional>:options</optional></replaceable></arg>

            <arg>--net remove</arg>

            <arg>--net <replaceable>N:options</replaceable></arg>

          </group>

          <sbr>

          <group>

            <arg>--disk add:size=<replaceable>SIZE</replaceable></arg>

            <arg>--disk remove</arg>

            <arg>--disk <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></arg>

          </group>

          <sbr>

          <arg>-t<group choice="req">

              <arg>plain</arg>

              <arg>drbd</arg>

            </group></arg>

          <sbr>

            <arg>--os-name=<replaceable>OS</replaceable> <arg>--force-variant</arg></arg>

          <sbr>

          <arg>--submit</arg>

          <sbr>

          <arg choice="req"><replaceable>instance</replaceable></arg>

        </cmdsynopsis>

        <para>

          Modifies the memory size, number of vcpus, ip address, MAC

          address and/or nic parameters for an instance. It can also

          add and remove disks and NICs to/from the instance. Note

          that you need to give at least one of the arguments, otherwise

          the command complains.

        </para>

        <para>

          The <option>-H</option> option specifies hypervisor options

          in the form of <userinput>name=value[,...]</userinput>. For details which options can be specified, see the <command>add</command> command.

        </para>

        <para>

          The <option>-t</option> 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.

        </para>

        <para>

          The <option>--disk

          add:size=<replaceable>SIZE</replaceable></option> option

          adds a disk to the instance. The <option>--disk

          remove</option> will remove the last disk of the

          instance. The <option>--disk

          <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></option>

          option will change the mode of the Nth disk of the instance

          between read-only (<literal>ro</literal>) and read-write

          (<literal>rw</literal>).

        </para>

        <para>

          The <option>--net

          add:<replaceable>options</replaceable></option> option will

          add a new NIC to the instance. The available options are the

          same as in the <command>add</command> command (mac, ip, link,

          mode). The <option>--net remove</option> will remove the

          last NIC of the instance, while the <option>--net

          <replaceable>N</replaceable>:<replaceable>options</replaceable></option>

          option will change the parameters of the Nth instance NIC.

        </para>

        <para>

          The option <option>--os-name</option> will change the OS

          name for the instance (without reinstallation). In case an

          OS variant is specified that is not found, then by default

          the modification is refused,

          unless <option>--force-variant</option> is passed. An

          invalid OS will also be refused, unless

          the <option>--force</option> option is given.

        </para>

        <para>

          The <option>--submit</option> option is used to send the job to

          the master daemon but not wait for its completion. The job

          ID will be shown so that it can be examined via

          <command>gnt-job info</command>.