<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!-- Please adjust the date whenever revising the manpage. -->
- <!ENTITY dhdate "<date>May 16, 2007</date>">
+ <!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>">
<copyright>
<year>2006</year>
<year>2007</year>
+ <year>2008</year>
+ <year>2009</year>
+ <year>2010</year>
<holder>Google Inc.</holder>
</copyright>
&dhdate;
&dhucpackage;
&dhsection;
- <refmiscinfo>ganeti 1.2</refmiscinfo>
+ <refmiscinfo>ganeti 2.0</refmiscinfo>
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<title>ADD</title>
<cmdsynopsis>
<command>add</command>
- <arg>-s <replaceable>disksize</replaceable></arg>
- <arg>--swap-size <replaceable>disksize</replaceable></arg>
- <arg>-m <replaceable>memsize</replaceable></arg>
<sbr>
- <arg>-o <replaceable>os-type</replaceable></arg>
- <arg>-b <replaceable>bridge</replaceable></arg>
- <sbr>
- <arg choice="req">-t<group>
+ <arg choice="req">-t<group choice="req">
<arg>diskless</arg>
+ <arg>file</arg>
<arg>plain</arg>
- <arg>local_raid1</arg>
- <arg>remote_raid1</arg>
- </group>
- </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 choice="req">-n <replaceable>node</replaceable></arg>
+
+ <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. <replaceable>instance</replaceable> must be in DNS and
- resolve to a IP in the same network as the nodes in the
- cluster.
+ 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>-s</option> option specifies the disk size for
- the instance, in mebibytes (defaults to
- <constant>20480MiB</constant> =
- <constant>20GiB</constant>). You can also use one of the
- suffixes <literal>m</literal>, <literal>g</literal> or
+ 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>
- The <option>--swap-size</option> option specifies the swap
- disk size (in mebibytes) for the instance (the one presented
- as <filename class="devicefile">/dev/sdb</filename>). The
- default is <constant>4096MiB</constant>. As for the disk
- size, you can specify other suffixes.
+ 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>
- The <option>-m</option> option specifies the memory size for
- the instance, in mebibytes (defaults to 128 MiB). Again, you
- can use other suffixes (e.g. <userinput>2g</userinput>).
+ 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 <option>-o</option> options specifies the operating
- system to be installed. The available operating systems can
- be listed with <command>gnt-os list</command>.
+ 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>-b</option> option specifies the bridge to which the
- instance will be connected. (defaults to the cluster-wide default
- bridge specified at cluster initialization time).
+ 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>-t</option> options specifies the disk layout type for
- the instance. The available choices are:
+ 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>diskless</term>
+ <term>mac</term>
<listitem>
- <para>
- This creates an instance with no disks. Its useful for
- testing only (or other special cases).
- </para>
+ <simpara>either a value or <constant>GENERATE</constant>
+ to generate a new unique MAC</simpara>
</listitem>
</varlistentry>
<varlistentry>
- <term>plain</term>
+ <term>ip</term>
<listitem>
- <para>Disk devices will be logical volumes.</para>
+ <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>local_raid1</term>
+ <term>mode</term>
<listitem>
- <para>
- Disk devices will be md raid1 arrays over two local
- logical volumes.
- </para>
+ <simpara>specifies the connection mode for this nic:
+ routed or bridged.</simpara>
</listitem>
</varlistentry>
<varlistentry>
- <term>remote_raid1</term>
+ <term>link</term>
<listitem>
- <para>
- Disk devices will be md raid1 arrays with one
- component (so it's not actually raid1): a drbd device
- between the instance's primary node and the node given
- by the option <option>--secondary-node</option>.
- </para>
+ <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>
- The <option>--secondary-node</option> option is used with
- the remote raid disk template type and specifies the remote
- node.
+ 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>
- 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.
+ 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>
- Example:
- <screen>
-# gnt-instance add -t plain -s 30g -m 512 -o debian-etch \
- -n node1.example.com instance1.example.com
-# gnt-instance add -t remote_raid1 --secondary-node node3.example.com \
- -s 30g -m 512 -o debian-etch \
- -n node1.example.com instance2.example.com
- </screen>
+ 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>
- </refsect3>
+ <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>
- <refsect3>
- <title>REMOVE</title>
+ <simpara>A string value denoting the boot order. This
+ has different meaning for the Xen HVM hypervisor and
+ for the KVM one.</simpara>
- <cmdsynopsis>
- <command>remove</command>
- <arg choice="req"><replaceable>instance</replaceable></arg>
- </cmdsynopsis>
+ <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>
- <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>
+ <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>
- <para>
- Example:
- <screen>
-# gnt-instance remove instance1.example.com
- </screen>
- </para>
- </refsect3>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>cdrom_image_path</term>
+ <listitem>
+ <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
- <refsect3>
- <title>LIST</title>
+ <simpara>The path to a CDROM image to attach to the
+ instance.</simpara>
- <cmdsynopsis>
- <command>list</command>
- <arg>--no-headers</arg>
- <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
- <arg>-o <replaceable>FIELD,...</replaceable></arg>
- </cmdsynopsis>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>nic_type</term>
+ <listitem>
+ <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
- <para>
- Shows the currently configured instances with memory usage,
- disk usage, the node they are running on, and the CPU time,
- counted in seconds, used by each instance since its latest
- restart.
- </para>
+ <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>
- 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>
+ 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>
- <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>
+ <term>vnc_tls</term>
<listitem>
- <simpara>the instance name</simpara>
+ <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>os</term>
+ <term>vnc_x509_path</term>
<listitem>
- <simpara>the OS of the instance</simpara>
+ <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>pnode</term>
+ <term>vnc_x509_verify</term>
<listitem>
- <simpara>the primary node of the instance</simpara>
+ <simpara>Valid for the KVM hypervisor.</simpara>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>snodes</term>
+ <term>acpi</term>
<listitem>
- <simpara>comma-separated list of secondary-nodes for the
- instance; usually this will be just one node</simpara>
+ <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>admin_state</term>
+ <term>pae</term>
<listitem>
- <simpara>the desired state of the instance (either "yes"
- or "no" denoting the instance should run or
- not)</simpara>
+ <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>admin_ram</term>
+ <term>use_localtime</term>
<listitem>
- <simpara>the desired memory for the instance</simpara>
+ <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>disk_template</term>
+ <term>kernel_path</term>
<listitem>
- <simpara>the disk template of the instance</simpara>
+ <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>oper_state</term>
+ <term>kernel_args</term>
<listitem>
- <simpara>the actual state of the instance; can take of
- the values "running", "stopped", "(node down)"</simpara>
+ <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>oper_ram</term>
+ <term>initrd_path</term>
<listitem>
- <simpara>the actual memory usage of the instance as seen
- by the hypervisor</simpara>
+ <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>ip</term>
+ <term>root_path</term>
<listitem>
- <simpara>the ip address ganeti recognizes as associated with
- the instance interface</simpara>
+ <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>mac</term>
+ <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>the instance interface MAC address</simpara>
+ <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>bridge</term>
+ <term>migration_downtime</term>
<listitem>
- <simpara>bridge the instance is connected to
+ <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>
+
</variablelist>
- </para>
- <para>
- There is a subtle grouping about the available output
- fields: all fields except for <option>oper_state</option>
- and <option>oper_ram</option> are configuration value and
- not run-time values. So if you don't select any of the
- <option>oper_*</option> 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>
+ 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>
- </refsect3>
-
- <refsect3>
- <title>INFO</title>
+
+ <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>
- <arg rep="repeat"><replaceable>instance</replaceable></arg>
+ <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>.
+ </para>
+
+ <para>
+ All the changes take effect at the next restart. If the
+ instance is running, there is no effect on the instance.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>REINSTALL</title>
+
+ <cmdsynopsis>
+ <command>reinstall</command>
+ <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
+ <arg>--select-os</arg>
+ <arg choice="opt">-f <replaceable>force</replaceable></arg>
+ <arg>--force-multiple</arg>
+ <sbr>
+ <group choice="opt">
+ <arg>--instance</arg>
+ <arg>--node</arg>
+ <arg>--primary</arg>
+ <arg>--secondary</arg>
+ <arg>--all</arg>
+ </group>
+ <arg>--submit</arg>
+ <arg choice="opt" rep="repeat"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ Reinstalls the operating system on the given instance(s). The
+ instance(s) must be stopped when running this command. If the
+ <option>--os-type</option> is specified, the operating
+ system is changed.
+ </para>
+
+ <para>
+ The <option>--select-os</option> option switches to an
+ interactive OS reinstall. The user is prompted to select the OS
+ template from the list of available OS templates.
+ </para>
+
+ <para>
+ Since this is a potentially dangerous command, the user will
+ be required to confirm this action, unless the
+ <option>-f</option> flag is passed. When multiple instances
+ are selected (either by passing multiple arguments or by
+ using the <option>--node</option>,
+ <option>--primary</option>, <option>--secondary</option> or
+ <option>--all</option> options), the user must pass both the
+ <option>--force</option> and
+ <option>--force-multiple</option> options to skip the
+ interactive confirmation.
+ </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>
+
+
+ </refsect3>
+
+ <refsect3>
+ <title>RENAME</title>
+
+ <cmdsynopsis>
+ <command>rename</command>
+ <arg>--no-ip-check</arg>
+ <arg>--submit</arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ <arg choice="req"><replaceable>new_name</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ 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
+ <option>--no-ip-check</option> option is passed.
+ </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>
+
+ </refsect3>
+
+ </refsect2>
+
+ <refsect2>
+ <title>Starting/stopping/connecting to console</title>
+
+ <refsect3>
+ <title>STARTUP</title>
+
+ <cmdsynopsis>
+ <command>startup</command>
+ <sbr>
+ <arg>--force</arg>
+ <sbr>
+ <arg>--force-multiple</arg>
+ <sbr>
+ <group choice="opt">
+ <arg>--instance</arg>
+ <arg>--node</arg>
+ <arg>--primary</arg>
+ <arg>--secondary</arg>
+ <arg>--all</arg>
+ <arg>--tags</arg>
+ <arg>--node-tags</arg>
+ <arg>--pri-node-tags</arg>
+ <arg>--sec-node-tags</arg>
+ </group>
+ <sbr>
+ <arg>-H <option>key=value...</option></arg>
+ <arg>-B <option>key=value...</option></arg>
+ <sbr>
+ <arg>--submit</arg>
+ <sbr>
+ <arg choice="opt"
+ rep="repeat"><replaceable>name</replaceable></arg>
</cmdsynopsis>
<para>
- Show detailed information about the (given) instances. This
- is different from <command>list</command> as it shows
- detailed data about the instance's disks (especially useful
- for remote raid templates).
+ Starts one or more instances, depending on the following
+ options. The four available modes are:
+ <variablelist>
+ <varlistentry>
+ <term><option>--instance</option></term>
+ <listitem>
+ <simpara>will start the instances given as arguments
+ (at least one argument required); this is the default
+ selection</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--node</term>
+ <listitem>
+ <simpara>will start the instances who have the given
+ node as either primary or secondary</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--primary</option></term>
+ <listitem>
+ <simpara>will start all instances whose primary node
+ is in the list of nodes passed as arguments (at least
+ one node required)</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--secondary</option></term>
+ <listitem>
+ <simpara>will start all instances whose secondary node
+ is in the list of nodes passed as arguments (at least
+ one node required)</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--all</term>
+ <listitem>
+ <simpara>will start all instances in the cluster (no
+ arguments accepted)</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--tags</term>
+ <listitem>
+ <simpara>will start all instances in the cluster with
+ the tags given as arguments</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--node-tags</term>
+ <listitem>
+ <simpara>will start all instances in the cluster on
+ nodes with the tags given as arguments</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--pri-node-tags</term>
+ <listitem>
+ <simpara>will start all instances in the cluster on
+ primary nodes with the tags given as
+ arguments</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--sec-node-tags</term>
+ <listitem>
+ <simpara>will start all instances in the cluster on
+ secondary nodes with the tags given as
+ arguments</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ Note that although you can pass more than one selection
+ option, the last one wins, so in order to guarantee the
+ desired result, don't pass more than one such option.
+ </para>
+
+ <para>
+ Use <option>--force</option> to start even if secondary disks are
+ failing.
+ </para>
+
+ <para>
+ The <option>--force-multiple</option> will skip the
+ interactive confirmation in the case the more than one
+ instance will be affected.
+ </para>
+
+ <para>
+ The <option>-H</option> and <option>-B</option> 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.:
+ <screen>
+# gnt-instance start -H root_args="single" instance1
+# gnt-instance start -B memory=2048 instance2
+ </screen>
+ The first form will start the instance
+ <userinput>instance1</userinput> in single-user mode, and
+ the instance <userinput>instance2</userinput> 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 with
+ "root_args=ro" when started with <userinput>-H
+ root_args=single</userinput> will result in "single", not
+ "ro single".
+ </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 start instance1.example.com
+# gnt-instance start --node node1.example.com node2.example.com
+# gnt-instance start --all
+ </screen>
</para>
</refsect3>
<refsect3>
- <title>MODIFY</title>
+ <title>SHUTDOWN</title>
<cmdsynopsis>
- <command>modify</command>
- <arg choice="opt">-m <replaceable>memsize</replaceable></arg>
- <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>
- <arg choice="opt">-i <replaceable>ip</replaceable></arg>
- <arg choice="opt">-b <replaceable>bridge</replaceable></arg>
- <arg choice="req"><replaceable>instance</replaceable></arg>
+ <command>shutdown</command>
+ <sbr>
+ <arg>--timeout=<replaceable>N</replaceable></arg>
+ <sbr>
+ <arg>--force-multiple</arg>
+ <sbr>
+ <group choice="opt">
+ <arg>--instance</arg>
+ <arg>--node</arg>
+ <arg>--primary</arg>
+ <arg>--secondary</arg>
+ <arg>--all</arg>
+ <arg>--tags</arg>
+ <arg>--node-tags</arg>
+ <arg>--pri-node-tags</arg>
+ <arg>--sec-node-tags</arg>
+ </group>
+ <sbr>
+ <arg>--submit</arg>
+ <sbr>
+ <arg choice="opt"
+ rep="repeat"><replaceable>name</replaceable></arg>
</cmdsynopsis>
<para>
- Modify the memory size, number of vcpus, ip address and/or bridge
- for an instance.
+ 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).
</para>
<para>
- The memory size is given in MiB. Note that you need to give
- at least one of the arguments, otherwise the command
- complains.
+ The <option>--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>
- All the changes take effect at the next restart. If the
- instance is running, there is no effect on the instance.
+ The <option>--instance</option>, <option>--node</option>,
+ <option>--primary</option>, <option>--secondary</option>,
+ <option>--all</option>, <option>--tags</option>,
+ <option>--node-tags</option>, <option>--pri-node-tags</option> and
+ <option>--sec-node-tags</option> options are similar as for the
+ <command>startup</command> command and they influence the
+ actual instances being shutdown.
</para>
- </refsect3>
- <refsect3>
- <title>REINSTALL</title>
+ <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>
- <cmdsynopsis>
- <command>reinstall</command>
- <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
- <arg choice="opt">-f <replaceable>force</replaceable></arg>
- <arg choice="req"><replaceable>instance</replaceable></arg>
- </cmdsynopsis>
<para>
- Reinstalls the operating system on the given instance. The instance
- must be stopped when running this command. If the
- <option>--os-type</option> is specified, the operating system is
- changed.
+ Example:
+ <screen>
+# gnt-instance shutdown instance1.example.com
+# gnt-instance shutdown --all
+ </screen>
</para>
</refsect3>
- </refsect2>
-
- <refsect2>
- <title>Starting/stopping/connecting to console</title>
-
<refsect3>
- <title>STARTUP</title>
+ <title>REBOOT</title>
<cmdsynopsis>
- <command>startup</command>
- <arg>--extra=<replaceable>PARAMS</replaceable></arg>
- <arg choice="req"><replaceable>instance</replaceable></arg>
+ <command>reboot</command>
+ <sbr>
+ <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
+ <sbr>
+ <arg>--ignore-secondaries</arg>
+ <sbr>
+ <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
+ <sbr>
+ <arg>--force-multiple</arg>
+ <sbr>
+ <group choice="opt">
+ <arg>--instance</arg>
+ <arg>--node</arg>
+ <arg>--primary</arg>
+ <arg>--secondary</arg>
+ <arg>--all</arg>
+ <arg>--tags</arg>
+ <arg>--node-tags</arg>
+ <arg>--pri-node-tags</arg>
+ <arg>--sec-node-tags</arg>
+ </group>
+ <sbr>
+ <arg>--submit</arg>
+ <sbr>
+ <arg choice="opt"
+ rep="repeat"><replaceable>name</replaceable></arg>
</cmdsynopsis>
<para>
- Starts an instance. The node where to start the instance is
- taken from the configuration.
+ Reboots one or more instances. The type of reboot depends on
+ the value of <option>--type</option>. A soft reboot does a
+ hypervisor reboot, a hard reboot does a instance stop,
+ recreates the hypervisor config for the instance and
+ starts the instance. A full reboot does the equivalent
+ of <command>gnt-instance shutdown && gnt-instance
+ startup</command>. The default is hard reboot.
</para>
<para>
- The <option>--extra</option> option is used to pass
- additional argument to the instance's kernel for this start
- only. Currently there is no way to specify a persistent set
- of arguments (beside the one hardcoded). Note that this may
- not apply to all virtualization types.
+ For the hard reboot the option
+ <option>--ignore-secondaries</option> ignores errors for the
+ secondary node while re-assembling the instance disks.
</para>
-
<para>
- Example:
- <screen>
-# gnt-instance start instance1.example.com
-# gnt-instance start --extra single test1.example.com
- </screen>
+ The <option>--instance</option>, <option>--node</option>,
+ <option>--primary</option>, <option>--secondary</option>,
+ <option>--all</option>, <option>--tags</option>,
+ <option>--node-tags</option>, <option>--pri-node-tags</option> and
+ <option>--sec-node-tags</option> options are similar as for the
+ <command>startup</command> command and they influence the
+ actual instances being rebooted.
</para>
- </refsect3>
-
- <refsect3>
- <title>SHUTDOWN</title>
- <cmdsynopsis>
- <command>shutdown</command>
- <arg choice="req"><replaceable>instance</replaceable></arg>
- </cmdsynopsis>
+ <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>
- Stops the instance. 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).
+ The <option>--force-multiple</option> will skip the
+ interactive confirmation in the case the more than one
+ instance will be affected.
</para>
<para>
Example:
<screen>
-# gnt-instance shutdown instance1.example.com
+# gnt-instance reboot instance1.example.com
+# gnt-instance reboot --type=full instance1.example.com
</screen>
</para>
</refsect3>
<title>CONSOLE</title>
<cmdsynopsis>
<command>console</command>
+ <arg choice="opt">--show-cmd</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<para>
- Connects to the console of the given instance. If the instance
- is not up, an error is returned.
+ Connects to the console of the given instance. If the
+ instance is not up, an error is returned. Use the
+ <option>--show-cmd</option> option to display the command
+ instead of executing it.
+ </para>
+
+ <para>
+ For HVM instances, this will attempt to connect to the
+ serial console of the instance. To connect to the
+ virtualized "physical" console of a HVM instance, use a VNC
+ client with the connection info from the
+ <command>info</command> command.
</para>
<para>
<cmdsynopsis>
<command>replace-disks</command>
- <arg choice="req">--new-secondary <replaceable>NODE</replaceable></arg>
+ <arg>--submit</arg>
+ <arg>--early-release</arg>
+ <arg choice="req">-p</arg>
+ <arg>--disks <replaceable>idx</replaceable></arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>replace-disks</command>
+ <arg>--submit</arg>
+ <arg>--early-release</arg>
+ <arg choice="req">-s</arg>
+ <arg>--disks <replaceable>idx</replaceable></arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>replace-disks</command>
+ <arg>--submit</arg>
+ <arg>--early-release</arg>
+ <group choice="req">
+ <arg>--iallocator <replaceable>name</replaceable></arg>
+ <arg>--new-secondary <replaceable>NODE</replaceable></arg>
+ </group>
+
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>replace-disks</command>
+ <arg>--submit</arg>
+ <arg>--early-release</arg>
+ <arg choice="req">--auto</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<para>
- This command does a full add and replace for both disks of
- an instance. It basically does an
- <command>addmirror</command> and
- <command>removemirror</command> for both disks of the
- instance.
+ This command is a generalized form for replacing disks. It
+ is currently only valid for the mirrored (DRBD) disk
+ template.
</para>
<para>
- If you also want to replace the secondary node during this
- process (for example to fix a broken secondary node), you
- can do so using the <option>--new-secondary</option> option.
+ The first form (when passing the <option>-p</option> option)
+ will replace the disks on the primary, while the second form
+ (when passing the <option>-s</option> option will replace
+ the disks on the secondary node. For these two cases (as the
+ node doesn't change), it is possible to only run the replace
+ for a subset of the disks, using the option
+ <option>--disks</option> which takes a list of
+ comma-delimited disk indices (zero-based),
+ e.g. <userinput>0,2</userinput> to replace only the first
+ and third disks.
</para>
- </refsect3>
- <refsect3>
- <title>ADD-MIRROR</title>
- <cmdsynopsis>
- <command>add-mirror</command>
- <arg choice="req">-b <replaceable>sdX</replaceable></arg>
- <arg choice="req">-n <replaceable>node</replaceable></arg>
- <arg choice="req"><replaceable>instance</replaceable></arg>
- </cmdsynopsis>
<para>
- Adds a new mirror to the disk layout of the instance, if the
- instance has a remote raid disk layout.
+ The third form (when passing either the
+ <option>--iallocator</option> or the
+ <option>--new-secondary</option> option) is designed to
+ change secondary node of the instance. Specifying
+ <option>--iallocator</option> makes the new secondary be
+ selected automatically by the specified allocator plugin,
+ otherwise the new secondary node will be the one chosen
+ manually via the <option>--new-secondary</option> option.
+ </para>
- The new mirror member will be between the instance's primary
- node and the node given with the <option>-n</option> option.
+ <para>
+ The fourth form (when using <option>--auto</option>) will
+ automatically determine which disks of an instance are faulty and
+ replace them within the same node. The <option>--auto</option>
+ option works only when an instance has only faulty disks on
+ either the primary or secondary node; it doesn't work when
+ both sides have faulty disks.
</para>
- </refsect3>
- <refsect3>
- <title>REMOVE-MIRROR</title>
+ <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>
- <cmdsynopsis>
- <command>removemirror</command>
- <arg choice="req">-b <replaceable>sdX</replaceable></arg>
- <arg choice="req">-p <replaceable>id</replaceable></arg>
- <arg choice="req"><replaceable>instance</replaceable></arg>
- </cmdsynopsis>
<para>
- Removes a mirror componenent from the disk layout of the
- instance, if the instance has a remote raid disk layout.
+ The <option>--early-release</option> changes the code so
+ that the old storage on secondary node(s) is removed early
+ (before the resync is completed) and the internal Ganeti
+ locks for the current (and new, if any) secondary node are
+ also released, thus allowing more parallelism in the cluster
+ operation. This should be used only when recovering from a
+ disk failure on the current secondary (thus the old storage
+ is already broken) or when the storage on the primary node
+ is known to be fine (thus we won't need the old storage for
+ potential recovery).
</para>
<para>
- You need to specifiy on which disk to act on using the
- <option>-b</option> option (either <filename>sda</filename>
- or <filename>sdb</filename>) and the mirror component, which
- is identified by the <option>-p</option> option. You can
- find the list of valid identifiers with the
- <command>info</command> command.
+ Note that it is not possible to select an offline or drained
+ node as a new secondary.
</para>
+ </refsect3>
+
<refsect3>
<title>ACTIVATE-DISKS</title>
<cmdsynopsis>
<command>activate-disks</command>
+ <arg>--submit</arg>
+ <arg>--ignore-size</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<para>
successful, the command will show the location and name of
the block devices:
<screen>
-node1.example.com:sda:/dev/md0
-node1.example.com:sdb:/dev/md1
+node1.example.com:disk/0:/dev/drbd0
+node1.example.com:disk/1:/dev/drbd1
</screen>
In this example, <emphasis>node1.example.com</emphasis> is
the name of the node on which the devices have been
- activated. The <emphasis>sda</emphasis> and
- <emphasis>sdb</emphasis> are the names of the block devices
- inside the instance. <emphasis>/dev/md0</emphasis> and
- <emphasis>/dev/md1</emphasis> are the names of the block
- devices as visible on the node.
+ activated. The <emphasis>disk/0</emphasis> and
+ <emphasis>disk/1</emphasis> are the Ganeti-names of the
+ instance disks; how they are visible inside the instance is
+ hypervisor-specific. <emphasis>/dev/drbd0</emphasis> and
+ <emphasis>/dev/drbd1</emphasis> are the actual block devices
+ as visible on the node.
+ </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>
+ The <option>--ignore-size</option> option can be used to
+ activate disks ignoring the currently configured size in
+ Ganeti. This can be used in cases where the configuration
+ has gotten out of sync with the real-world (e.g. after a
+ partially-failed grow-disk operation or due to rounding in
+ LVM devices). This should not be used in normal cases, but
+ only when activate-disks fails without it.
</para>
<para>
<cmdsynopsis>
<command>deactivate-disks</command>
+ <arg>--submit</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<para>
De-activates the block devices of the given instance. Note
- that if you run this command for a remote raid instance
- type, while it is running, it will not be able to shutdown
- the block devices on the primary node, but it will shutdown
- the block devices on the secondary nodes, thus breaking the
- replication.
+ that if you run this command for an instance with a drbd
+ disk template, while it is running, it will not be able to
+ shutdown the block devices on the primary node, but it will
+ shutdown the block devices on the secondary nodes, thus
+ breaking the replication.
+ </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>
+
+ </refsect3>
+
+ <refsect3>
+ <title>GROW-DISK</title>
+ <cmdsynopsis>
+ <command>grow-disk</command>
+ <arg>--no-wait-for-sync</arg>
+ <arg>--submit</arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ <arg choice="req"><replaceable>disk</replaceable></arg>
+ <arg choice="req"><replaceable>amount</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ Grows an instance's disk. This is only possible for
+ instances having a <literal>plain</literal> or
+ <literal>drbd</literal> disk template.
+ </para>
+
+ <para>
+ Note that this command only change the block device size; it
+ will not grow the actual filesystems, partitions, etc. that
+ live on that disk. Usually, you will need to:
+ <orderedlist>
+ <listitem>
+ <simpara>use <command>gnt-instance grow-disk</command></simpara>
+ </listitem>
+ <listitem>
+ <simpara>reboot the instance (later, at a convenient
+ time)</simpara>
+ </listitem>
+ <listitem>
+ <simpara>use a filesystem resizer, such as
+ <citerefentry> <refentrytitle>ext2online</refentrytitle>
+ <manvolnum>8</manvolnum> </citerefentry> or
+ <citerefentry> <refentrytitle>xfs_growfs</refentrytitle>
+ <manvolnum>8</manvolnum> </citerefentry> to resize the
+ filesystem, or use <citerefentry>
+ <refentrytitle>fdisk</refentrytitle>
+ <manvolnum>8</manvolnum> </citerefentry> to change the
+ partition table on the disk
+ </simpara>
+ </listitem>
+ </orderedlist>
+ </para>
+
+
+ <para>
+ The <replaceable>disk</replaceable> argument is the index of
+ the instance disk to grow. The
+ <replaceable>amount</replaceable> argument is given either
+ as a number (and it represents the amount to increase the
+ disk with in mebibytes) or can be given similar to the
+ arguments in the create instance operation, with a suffix
+ denoting the unit.
+ </para>
+
+ <para>
+ Note that the disk grow operation might complete on one node
+ but fail on the other; this will leave the instance with
+ different-sized LVs on the two nodes, but this will not
+ create problems (except for unused space).
+ </para>
+
+ <para>
+ If you do not want gnt-instance to wait for the new disk
+ region to be synced, use the
+ <option>--no-wait-for-sync</option> option.
+ </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 (increase the first disk for instance1 by 16GiB):
+ <screen>
+# gnt-instance grow-disk instance1.example.com 0 16g
+ </screen>
+ </para>
+
+ <para>
+ Also note that disk shrinking is not supported; use
+ <command>gnt-backup export</command> and then
+ <command>gnt-backup import</command> to reduce the disk size
+ of an instance.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>RECREATE-DISKS</title>
+
+ <cmdsynopsis>
+ <command>recreate-disks</command>
+ <arg>--submit</arg>
+ <arg>--disks=<option>indices</option></arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Recreates the disks of the given instance, or only a subset
+ of the disks (if the option <option>disks</option> is
+ passed, which must be a comma-separated list of disk
+ indices, starting from zero).
+ </para>
+
+ <para>
+ Note that this functionality should only be used for missing
+ disks; if any of the given disks already exists, the
+ operation will fail. While this is suboptimal,
+ recreate-disks should hopefully not be needed in normal
+ operation and as such the impact of this is low.
+ </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>
</refsect3>
<command>failover</command>
<arg>-f</arg>
<arg>--ignore-consistency</arg>
+ <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
+ <arg>--submit</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<para>
Failover will fail the instance over its secondary
- node. This works only for instances having a remote raid
- disk layout.
+ node. This works only for instances having a drbd disk
+ template.
</para>
<para>
disks before failing over the instance. If you are trying to
migrate instances off a dead node, this will fail. Use the
<option>--ignore-consistency</option> option for this
- purpose.
+ purpose. Note that this option can be dangerous as errors in
+ shutting down the instance will be ignored, resulting in
+ possibly having the instance running on two machines in
+ parallel (on disconnected DRBD drives).
+ </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>
</para>
</refsect3>
+ <refsect3>
+ <title>MIGRATE</title>
+
+ <cmdsynopsis>
+ <command>migrate</command>
+ <arg>-f</arg>
+ <arg choice="req">--cleanup</arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>migrate</command>
+ <arg>-f</arg>
+ <arg>--non-live</arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ Migrate will move the instance to its secondary node without
+ shutdown. It only works for instances having the drbd8 disk
+ template type.
+ </para>
+
+ <para>
+ The migration command needs a perfectly healthy instance, as
+ we rely on the dual-master capability of drbd8 and the disks
+ of the instance are not allowed to be degraded.
+ </para>
+
+ <para>
+ The <option>--non-live</option> option will switch (for the
+ hypervisors that support it) between a "fully live"
+ (i.e. the interruption is as minimal as possible) migration
+ and one in which the instance is frozen, its state saved and
+ transported to the remote node, and then resumed there. This
+ all depends on the hypervisor support for two different
+ methods. In any case, it is not an error to pass this
+ parameter (it will just be ignored if the hypervisor doesn't
+ support it).
+ </para>
+
+ <para>
+ If the <option>--cleanup</option> option is passed, the
+ operation changes from migration to attempting recovery from
+ a failed previous migration. In this mode, ganeti checks if
+ the instance runs on the correct node (and updates its
+ configuration if not) and ensures the instances's disks are
+ configured correctly. In this mode, the
+ <option>--non-live</option> option is ignored.
+ </para>
+
+ <para>
+ The option <option>-f</option> will skip the prompting for
+ confirmation.
+ </para>
+ <para>
+ Example (and expected output):
+ <screen>
+# gnt-instance migrate instance1
+Migrate will happen to the instance instance1. Note that migration is
+**experimental** in this version. This might impact the instance if
+anything goes wrong. Continue?
+y/[n]/?: y
+* checking disk consistency between source and target
+* ensuring the target is in secondary mode
+* changing disks into dual-master mode
+ - INFO: Waiting for instance instance1 to sync disks.
+ - INFO: Instance instance1's disks are in sync.
+* migrating instance to node2.example.com
+* changing the instance's disks on source node to secondary
+ - INFO: Waiting for instance instance1 to sync disks.
+ - INFO: Instance instance1's disks are in sync.
+* changing the instance's disks to single-master
+#
+ </screen>
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>MOVE</title>
+
+ <cmdsynopsis>
+ <command>move</command>
+ <arg>-f</arg>
+ <arg>-n <replaceable>node</replaceable></arg>
+ <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
+ <arg>--submit</arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ Move will move the instance to an arbitrary node in the
+ cluster. This works only for instances having a plain or
+ file disk template.
+ </para>
+
+ <para>
+ Note that since this operation is done via data copy, it
+ will take a long time for big disks (similar to
+ replace-disks for a drbd instance).
+ </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 move -n node3.example.com instance1.example.com
+ </screen>
+ </para>
+ </refsect3>
+
+ </refsect2>
+
+ <refsect2>
+ <title>TAGS</title>
+
+ <refsect3>
+ <title>ADD-TAGS</title>
+
+ <cmdsynopsis>
+ <command>add-tags</command>
+ <arg choice="opt">--from <replaceable>file</replaceable></arg>
+ <arg choice="req"><replaceable>instancename</replaceable></arg>
+ <arg choice="req"
+ rep="repeat"><replaceable>tag</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ Add tags to the given instance. If any of the tags contains
+ invalid characters, the entire operation will abort.
+ </para>
+ <para>
+ If the <option>--from</option> option is given, the list of
+ tags will be extended with the contents of that file (each
+ line becomes a tag). In this case, there is not need to pass
+ tags on the command line (if you do, both sources will be
+ used). A file name of - will be interpreted as stdin.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>LIST-TAGS</title>
+
+ <cmdsynopsis>
+ <command>list-tags</command>
+ <arg choice="req"><replaceable>instancename</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>List the tags of the given instance.</para>
+ </refsect3>
+
+ <refsect3>
+ <title>REMOVE-TAGS</title>
+ <cmdsynopsis>
+ <command>remove-tags</command>
+ <arg choice="opt">--from <replaceable>file</replaceable></arg>
+ <arg choice="req"><replaceable>instancename</replaceable></arg>
+ <arg choice="req"
+ rep="repeat"><replaceable>tag</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ Remove tags from the given instance. If any of the tags are
+ not existing on the node, the entire operation will abort.
+ </para>
+
+ <para>
+ If the <option>--from</option> option is given, the list of
+ tags will be extended with the contents of that file (each
+ line becomes a tag). In this case, there is not need to pass
+ tags on the command line (if you do, both sources will be
+ used). A file name of - will be interpreted as stdin.
+ </para>
+ </refsect3>
+
</refsect2>
</refsect1>
projects / ganeti-local / blobdiff