<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>
+ <arg>--mac <replaceable>MAC-address</replaceable></arg>
+ <sbr>
+
+ <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
<sbr>
- <arg choice="req">-t<group>
+
+ <arg>--kernel<group choice="req">
+ <arg>default</arg>
+ <arg><replaceable>kernel_path</replaceable></arg>
+ </group></arg>
+ <sbr>
+
+ <arg>--initrd<group choice="req">
+ <arg>default</arg>
+ <arg>none</arg>
+ <arg><replaceable>initrd_path</replaceable></arg>
+ </group></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>
+
+ <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>
+
+ <arg choice="req">-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
+ <arg choice="req">-o <replaceable>os-type</replaceable></arg>
<sbr>
- <arg choice="req">-n <replaceable>node</replaceable></arg>
+
<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
</para>
<para>
+ The <option>--mac</option> option specifies the MAC address
+ of the ethernet interface for the instance. If this option
+ is not specified, a new MAC address is generated randomly with
+ the configured MAC prefix. The randomly generated MAC
+ address is guaranteed to be unique among the instances of
+ this cluster.
+ </para>
+
+ <para>
+ The <option>--hvm-boot-order</option> option specifies the
+ boot device order for Xen HVM instances. The boot order is a
+ string of letters listing the boot devices, with valid
+ device letters being:
+ </para>
+
+ <para>
+ <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>
+ </para>
+
+ <para>
+ The option is only relevant for Xen HVM instances and
+ ignored by all other instances types.
+ </para>
+
+ <para>
+ The <option>--kernel</option> options allows the instance to
+ use a custom kernel (if a filename is passed) or to use the
+ default kernel (<filename>@CUSTOM_XEN_KERNEL@</filename>), if the
+ string <constant>default</constant> is passed.
+ </para>
+
+ <para>
+ The <option>--initrd</option> option is similar: it allows
+ the instance to use a custom initrd (if a filename is
+ passed) or to use the default initrd
+ (<filename>@CUSTOM_XEN_INITRD@</filename>), if the string
+ <constant>default</constant> is passed, or to disable the
+ use of an initrd, if the string <constant>none</constant> is
+ passed. Note that in the case the instance is set to use the
+ default initrd and it doesn't exist, it will be silently
+ ignored; if the instance is set to use a custom initrd and
+ it doesn't exist, this will be treated as an error and will
+ prevent the startup of the instance.
+ </para>
+
+ <para>
The <option>-t</option> options specifies the disk layout type for
the instance. The available choices are:
<variablelist>
</listitem>
</varlistentry>
<varlistentry>
- <term>plain</term>
+ <term>file</term>
<listitem>
- <para>Disk devices will be logical volumes.</para>
+ <para>Disk devices will be regular files.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>local_raid1</term>
+ <term>plain</term>
<listitem>
- <para>
- Disk devices will be md raid1 arrays over two local
- logical volumes.
- </para>
+ <para>Disk devices will be logical volumes.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>remote_raid1</term>
+ <term>drbd</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>.
+ Disk devices will be drbd (version 8.x) on top of
+ lvm volumes.
</para>
</listitem>
</varlistentry>
</para>
<para>
- The <option>--secondary-node</option> option is used with
- the remote raid disk template type and specifies the remote
- node.
+ The optional second value of the <option>--node</option> is used for
+ the drbd template type and specifies the remote node.
</para>
<para>
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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>blktap</term>
+ <listitem>
+ <para>blktap driver.</para>
+ </listitem>
+ </varlistentry>
+ <variablelist>
+ </para>
+
+ <para>
+ The loop 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>
+
+ <para>
+ 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>
<para>
Example:
<screen>
+# gnt-instance add -t file -s 30g -m 512 -o debian-etch \
+ -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
# 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
+# gnt-instance add -t drbd -s 30g -m 512 -o debian-etch \
+ -n node1.example.com:node2.example.com instance2.example.com
</screen>
</para>
-
</refsect3>
<refsect3>
<command>list</command>
<arg>--no-headers</arg>
<arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
- <arg>-o <replaceable>FIELD,...</replaceable></arg>
+ <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
</cmdsynopsis>
<para>
<varlistentry>
<term>snodes</term>
<listitem>
- <simpara>comma-separated list of secondary-nodes for the
+ <simpara>comma-separated list of secondary nodes for the
instance; usually this will be just one node</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>oper_state</term>
<listitem>
- <simpara>the actual state of the instance; can take of
- the values "running", "stopped", "(node down)"</simpara>
+ <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>
</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</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>vcpus</term>
+ <listitem>
+ <simpara>the number of VCPUs allocated to the
+ instance</simpara>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
<para>
+ If the value of the option starts with the character
+ <constant>+</constant>, the new fields 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>
- 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
+ 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
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).
+ for drbd disk template).
</para>
</refsect3>
<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="opt">--mac <replaceable>MAC-address</replaceable></arg>
+ <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
+ <sbr>
+ <arg>--kernel <group choice="req">
+ <arg>default</arg>
+ <arg><replaceable>kernel_path</replaceable></arg>
+ </group></arg>
+ <sbr>
+ <arg>--initrd <group choice="req">
+ <arg>default</arg>
+ <arg>none</arg>
+ <arg><replaceable>initrd_path</replaceable></arg>
+ </group> </arg>
+ <sbr>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<para>
- Modify the memory size, number of vcpus, ip address and/or bridge
- for an instance.
+ Modify the memory size, number of vcpus, ip address, MAC
+ address and/or bridge for an instance.
</para>
<para>
</para>
<para>
+ The <option>--kernel</option>, <option>--initrd</option>
+ and <option>--hvm-boot-order</option>
+ options are described in the <command>add</command> command.
+ </para>
+
+ <para>
+ Additionally, the HVM boot order can be reset to the default
+ values by using <option>--hvm-boot-order=default</option>.
+ </para>
+
+ <para>
All the changes take effect at the next restart. If the
instance is running, there is no effect on the instance.
</para>
<cmdsynopsis>
<command>startup</command>
<arg>--extra=<replaceable>PARAMS</replaceable></arg>
+ <arg>--force</arg>
<sbr>
<group choice="opt">
<arg>--instance</arg>
</cmdsynopsis>
<para>
- Starts one or more instances, depending on the
- <option>--by-*</option> mode. The four available modes are:
+ Starts one or more instances, depending on the following
+ options. The four available modes are:
<variablelist>
<varlistentry>
<term><option>--instance</option></term>
</para>
<para>
- Note that although you can pass more than one
- <option>--by-</option> option, the last one wins, so in
- order to guarantee the desired result, don't pass more than
- one such option.
+ 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>
not apply to all virtualization types.
</para>
+ <para>
+ Use <option>--force</option> to start even if secondary disks are
+ failing.
+ </para>
<para>
Example:
<screen>
# gnt-instance start instance1.example.com
# gnt-instance start --extra single test1.example.com
-# gnt-instance start --by-node node1.example.com node2.example.com
-# gnt-instance start --by-cluster
+# gnt-instance start --node node1.example.com node2.example.com
+# gnt-instance start --all
</screen>
</para>
</refsect3>
Example:
<screen>
# gnt-instance shutdown instance1.example.com
-# gnt-instance shutdown --by-cluster
+# gnt-instance shutdown --all
</screen>
</para>
</refsect3>
</para>
<para>
- Use the <option>--force-multiple</option> to keep
+ Use the <option>--force-multiple</option> option to keep
gnt-instance from asking for confirmation when more than one
instance is affected.
</para>
<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.
+ is not up, an error is returned. Use the <option>--show-cmd</option>
+ option to display the command instead of executing it.
</para>
<para>
<cmdsynopsis>
<command>replace-disks</command>
+ <arg choice="opt">-s</arg>
<arg choice="req">--new-secondary <replaceable>NODE</replaceable></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.
- </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.
- </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>
+ <command>replace-disks</command>
+ <group>
+ <arg choice="req">-s</arg>
+ <arg choice="req">-p</arg>
+ </group>
<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 new mirror member will be between the instance's primary
- node and the node given with the <option>-n</option> option.
- </para>
- </refsect3>
-
- <refsect3>
- <title>REMOVE-MIRROR</title>
-
- <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.
+ This command is a generalized form for adding and replacing
+ disks. It is currently only valid for the mirrored (DRBD)
+ disk template.
</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.
+ The first form will do a secondary node change, while the
+ second form will replace the disks on either the primary
+ (<option>-p</option>) or the secondary (<option>-s</option>)
+ node of the instance only, without changing the node.
</para>
+ </refsect3>
+
<refsect3>
<title>ACTIVATE-DISKS</title>
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:sda:/dev/drbd0
+node1.example.com:sdb:/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
+ inside the instance. <emphasis>/dev/drbd0</emphasis> and
+ <emphasis>/dev/drbd1</emphasis> are the names of the block
devices as visible on the node.
</para>
</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>
</refsect3>
<command>failover</command>
<arg>-f</arg>
<arg>--ignore-consistency</arg>
- <sbr>
- <group choice="opt">
- <arg>--instance</arg>
- <arg>--primary</arg>
- <arg>--secondary</arg>
- </group>
- <sbr>
- <arg choice="req" rep="repeat"><replaceable>name</replaceable></arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<para>
- Failover will fail the selected instances to their secondary
- node. This works only for instances having a remote raid
- disk layout.
- </para>
-
- <para>
- The selection of which instances to failover is done via the
- following options:
- <variablelist>
- <varlistentry>
- <term><option>--instance</option></term>
- <listitem>
- <simpara>will select the instances given as arguments
- (at least one argument required); this is the default
- selection</simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--primary</option></term>
- <listitem>
- <simpara>will select 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 select all instances whose secondary
- node is in the list of nodes passed as arguments (at
- least one node required)</simpara>
- </listitem>
- </varlistentry>
- </variablelist>
+ Failover will fail the instance over its secondary
+ node. This works only for instances having a drbd disk
+ template.
</para>
<para>
Normally the failover will check the consistency of the
- disks before failing over an instance. If you are trying to
+ 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. Note that this option can be dangerous as errors in
Example:
<screen>
# gnt-instance failover instance1.example.com
-# gnt-instance failover --primary node4.example.com
</screen>
</para>
</refsect3>
projects / ganeti-local / blobdiff