<!-- 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>May 29, 2008</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>
<holder>Google Inc.</holder>
</copyright>
&dhdate;
<replaceable>cdrom-image-path</replaceable></arg>
<sbr>
+ <arg>--hvm-nic-type <replaceable>NICTYPE</replaceable></arg>
+ <sbr>
+
+ <arg>--hvm-disk-type
+ <replaceable>DISKTYPE</replaceable></arg>
+ <sbr>
+
<arg>--vnc-bind-address
<replaceable>vnc-bind-address</replaceable></arg>
<sbr>
</group></arg>
<sbr>
- <arg choice="req">-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
+ <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>
</para>
<para>
- The option is only relevant for Xen HVM instances and
- ignored by all other instances types.
+ The default is not to set an HVM boot order which is
+ interpreted as 'dc'. This option, like all options starting
+ with 'hvm', is only relevant for Xen HVM instances and
+ ignored by all other instance types.
</para>
<para>
The <option>--hvm-acpi</option> option specifies if Xen
should enable ACPI support for this HVM instance. Valid
- values are true or false.
+ values are true or false. The default value is false,
+ disabling ACPI support for this instance.
</para>
<para>
The <option>--hvm-pae</option> option specifies if Xen
should enabled PAE support for this HVM instance. Valid
- values are true or false.
+ values are true or false. The default is false, disabling
+ PAE support for this instance.
</para>
<para>
- The <option>--hvm-cdrom-image-path</option> specifies the
- path to the file xen uses to emulate a virtual CDROM drive
+ The <option>--hvm-cdrom-image-path</option> option specifies the
+ path to the file Xen uses to emulate a virtual CDROM drive
for this HVM instance. Valid values are either an
absolute path to an existing file or None, which disables
- virtual CDROM support for this instance.
+ virtual CDROM support for this instance. The default is
+ None, disabling virtual CDROM support.
</para>
<para>
- The <option>--vnc-bind-address</option> specifies the
+ The <option>--hvm-nic-type</option> specifies the NIC type
+ Xen should use for this HVM instance. Valid choices are
+ rtl8139, ne2k_pci, ne2k_isa and paravirtual with rtl8139
+ as the default. The paravirtual setting is intended for use
+ with the GPL PV drivers inside HVM Windows instances.
+ </para>
+
+ <para>
+ The <option>--hvm-disk-type</option> specifies the disk type
+ Xen should use for the HVM instance. Valid choices are ioemu
+ and paravirtual with ioemu as the default. The paravirtual
+ setting is intended for use with the GPL PV drivers inside
+ HVM Windows instances.
+ </para>
+
+ <para>
+ The <option>--vnc-bind-address</option> option 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.
+ 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>
+
+ <para>
+ The <option>--iallocator</option> option specifies the instance
+ allocator plugin to use. If you pass in this option the allocator
+ will select nodes for this instance automatically, so you don't need
+ to pass them with the <option>-n</option> option. For more
+ information please refer to the instance allocator documentation.
</para>
<para>
- The <option>--kernel</option> options allows the instance to
+ The <option>--kernel</option> option 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>blktap driver.</para>
</listitem>
</varlistentry>
- <variablelist>
+ </variablelist>
</para>
<para>
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 detect modifications</simpara>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
<cmdsynopsis>
<command>info</command>
+ <group>
+ <arg>-s</arg>
+ <arg>--static</arg>
+ </group>
<arg rep="repeat"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
detailed data about the instance's disks (especially useful
for 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>
</refsect3>
<refsect3>
<arg>--hvm-pae <replaceable>PAE-support</replaceable></arg>
<arg>--hvm-cdrom-image-path
<replaceable>cdrom-image-path</replaceable></arg>
+ <arg>--hvm-nic-type <replaceable>NICTYPE</replaceable></arg>
+ <arg>--hvm-disk-type <replaceable>DISKTYPE</replaceable></arg>
<arg>--vnc-bind-address
<replaceable>vnc-bind-address</replaceable></arg>
</para>
<para>
+ The <option>--hvm-nic-type</option> specifies the NIC type
+ Xen should use for this HVM instance. Valid choices are
+ rtl8139, ne2k_pci, ne2k_isa and paravirtual with rtl8139
+ as the default. The paravirtual setting is intended for use
+ with the GPL PV drivers inside HVM Windows instances.
+ </para>
+
+ <para>
+ The <option>--hvm-disk-type</option> specifies the disk type
+ Xen should use for the HVM instance. Valid choices are ioemu
+ and paravirtual with ioemu as the default. The paravirtual
+ setting is intended for use with the GPL PV drivers inside
+ HVM Windows instances.
+ </para>
+
+ <para>
The <option>--vnc-bind-address</option> 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
<command>reinstall</command>
<arg choice="opt">-o <replaceable>os-type</replaceable></arg>
<arg choice="opt">-f <replaceable>force</replaceable></arg>
+ <arg>--select-os</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<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>
</refsect3>
<refsect3>
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 soft reboot.
+ startup</command>. The default is hard reboot.
</para>
<para>
</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 gnt-instance info.
+ </para>
+
+ <para>
Example:
<screen>
# gnt-instance console instance1.example.com
<cmdsynopsis>
<command>replace-disks</command>
- <arg choice="opt">-s</arg>
- <arg choice="req">--new-secondary <replaceable>NODE</replaceable></arg>
+ <arg choice="req">-p</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>replace-disks</command>
- <group>
+
<arg choice="req">-s</arg>
- <arg choice="req">-p</arg>
+ <arg choice="req"><replaceable>instance</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>replace-disks</command>
+
+ <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>
</para>
<para>
- 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.
+ 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.
</para>
+ <para>
+ 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>
</refsect3>
<refsect3>
</refsect3>
+ <refsect3>
+ <title>GROW-DISK</title>
+ <cmdsynopsis>
+ <command>grow-disk</command>
+ <arg>--no-wait-for-sync</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 either
+ <literal>sda</literal> or <literal>sdb</literal>. 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>Example (increase sda for instance1 by 16GiB):
+ <screen>
+# gnt-instance grow-disk instance1.example.com sda 16g
+ </screen>
+ </para>
+
+ <para>
+ Also note that disk shrinking will not be supported; use
+ <command>gnt-backup export</command> and then
+ <command>gnt-backup import</command> to reduce the disk size
+ of an instance.
+ </para>
+ </refsect3>
+
</refsect2>
<refsect2>