<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!-- Please adjust the date whenever revising the manpage. -->
- <!ENTITY dhdate "<date>February 11, 2009</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>">
<year>2007</year>
<year>2008</year>
<year>2009</year>
+ <year>2010</year>
<holder>Google Inc.</holder>
</copyright>
&dhdate;
<sbr>
<group choice="req">
- <arg rep="repeat">--disk=<replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
+ <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>
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, at least the size 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
+ disk, either the size or the adoption source needs to be
+ given, and optionally the access mode (read-only or the
+ default of read-write) can also be specified. The size is
+ interpreted (when no unit is given) in mebibytes. You can
+ also use one of the suffixes
<literal>m</literal>, <literal>g</literal> or
<literal>t</literal> to specificy the exact the units used;
these suffixes map to mebibytes, gibibytes and tebibytes.
</para>
<para>
+ When using the <option>adopt</option> key in the disk
+ definition, Ganeti will reuse those volumes (instead of
+ creating new ones) as the instance's disks. Ganeti will
+ rename these volumes to the standard format, and (without
+ installing the OS) will use them as-is for the
+ instance. This allows migrating instances from non-managed
+ mode (e.q. plain KVM with LVM) to being managed via
+ Ganeti. Note that this works only for the `plain' disk
+ template (see below for template details).
+ </para>
+
+ <para>
Alternatively, a single-disk instance can be created via the
<option>-s</option> option which takes a single argument,
the size of the disk. This is similar to the Ganeti 1.2
</para>
<para>
+ The <option>--no-ip-check</option> skips the checks that are
+ done to see if the instance's IP is not already alive
+ (i.e. reachable from the master node).
+ </para>
+
+ <para>
+ The <option>--no-name-check</option> skips the check for the
+ instance name via the resolver (e.g. in DNS or /etc/hosts,
+ depending on your setup). Since the name check is used to
+ compute the IP address, if you pass this option you must
+ also pass the <option>--no-ip-check</option> option.
+ </para>
+
+ <para>
+ If you don't wat the instance to automatically start after
+ creation, this is possible via the
+ <option>--no-start</option> option. This will leave the
+ instance down until a subsequent <command>gnt-instance
+ start</command> command.
+ </para>
+
+ <para>
The NICs of the instances can be specified via the
<option>--net</option> option. By default, one NIC is
created for the instance, with a random MAC, and set
<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>.
+ 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>
interpreted as 'dc'.
</simpara>
+ <simpara>
+ For KVM the boot order is either
+ <quote>cdrom</quote>, <quote>disk</quote> or
+ <quote>network</quote>. Please note that older
+ versions of KVM couldn't netboot from virtio
+ interfaces. This has been fixed in more recent
+ versions and is confirmed to work at least with
+ qemu-kvm 0.11.1.
+ </simpara>
+
</listitem>
</varlistentry>
<varlistentry>
</varlistentry>
<varlistentry>
+ <term>use_localtime</term>
+ <listitem>
+ <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>
+
+ <para>
+ A boolean option that specifies if the instance
+ should be started with its clock set to the
+ localtime of the machine (when true) or to the UTC
+ (When false). The default is false, which is useful
+ for Linux/Unix machines; for Windows OSes, it is
+ recommended to enable this parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>kernel_path</term>
<listitem>
<simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
emulate a serial console for the instance.</simpara>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>disk_cache</term>
+ <listitem>
+ <simpara>Valid for the KVM hypervisor.</simpara>
+
+ <simpara>The disk cache mode. It can be either
+ <userinput>default</userinput> to not pass any cache
+ option to KVM, or one of the KVM cache modes: none
+ (for direct I/O), writethrough (to use the host cache
+ but report completion to the guest only when the host
+ has committed the changes to disk) or writeback (to
+ use the host cache and report completion as soon as
+ the data is in the host cache). Note that there are
+ special considerations for the cache mode depending on
+ version of KVM used and disk type (always raw file
+ under Ganeti), please refer to the KVM documentation
+ for more details.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>security_model</term>
+ <listitem>
+ <simpara>Valid for the KVM hypervisor.</simpara>
+
+ <simpara>The security model for kvm. Currently one of
+ <quote>none</quote>, <quote>user</quote> or
+ <quote>pool</quote>. Under <quote>none</quote>, the
+ default, nothing is done and instances are run as
+ the ganeti daemon user (normally root).
+ </simpara>
+
+ <simpara>Under <quote>user</quote> kvm will drop
+ privileges and become the user specified by the
+ security_domain parameter.
+ </simpara>
+
+ <simpara>Under <quote>pool</quote> a global cluster
+ pool of users will be used, making sure no two
+ instances share the same user on the same node.
+ (this mode is not implemented yet)
+ </simpara>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>security_domain</term>
+ <listitem>
+ <simpara>Valid for the KVM hypervisor.</simpara>
+
+ <simpara>Under security model <quote>user</quote> the username to
+ run the instance under. It must be a valid username
+ existing on the host.
+ </simpara>
+ <simpara>Cannot be set under security model <quote>none</quote>
+ or <quote>pool</quote>.
+ </simpara>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>kvm_flag</term>
+ <listitem>
+ <simpara>Valid for the KVM hypervisor.</simpara>
+
+ <simpara>If <quote>enabled</quote> the -enable-kvm flag is
+ passed to kvm. If <quote>disabled</quote> -disable-kvm is
+ passed. If unset no flag is passed, and the default running
+ mode for your kvm binary will be used.
+ </simpara>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>migration_downtime</term>
+ <listitem>
+ <simpara>Valid for the KVM hypervisor.</simpara>
+
+ <simpara>The maximum amount of time (in ms) a KVM instance is
+ allowed to be frozen during a live migration, in order to copy
+ dirty memory pages. Default value is 30ms, but you may need to
+ increase this value for busy instances.
+ </simpara>
+
+ <simpara>This option is only effective with kvm versions >= 87
+ and qemu-kvm versions >= 0.11.0.
+ </simpara>
+
+ </listitem>
+ </varlistentry>
+
</variablelist>
- </para>
- <para>
</para>
<para>
</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>
<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>
<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
<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>
<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:
</varlistentry>
<varlistentry>
- <term>mode</term>
+ <term>nic_mode</term>
<listitem>
<simpara>the mode of the first instance NIC
(routed or bridged)</simpara>
</listitem>
</varlistentry>
<varlistentry>
- <term>link</term>
+ <term>nic_link</term>
<listitem>
<simpara>the link of the first instance NIC
</simpara>
<arg>-s</arg>
<arg>--static</arg>
</group>
+ <arg>--roman</arg>
<group choice="req">
<arg>--all</arg>
<arg rep="repeat"><replaceable>instance</replaceable></arg>
<para>
Use the <option>--all</option> to get info about all instances,
- rather than explicitely passing the ones you're interested in.
+ 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>
</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>
</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
</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
<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>
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>
The <option>-H</option> and <option>-B</option> options
- specify extra, 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.:
+ 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
<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).
+ 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>
<cmdsynopsis>
<command>shutdown</command>
<sbr>
+ <arg>--timeout=<replaceable>N</replaceable></arg>
+ <sbr>
<arg>--force-multiple</arg>
<sbr>
<group choice="opt">
<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>
</para>
<para>
+ 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>
The <option>--instance</option>, <option>--node</option>,
- <option>--primary</option>, <option>--secondary</option> and
- <option>--all</option> options are similar as for the
+ <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>
<sbr>
<arg>--ignore-secondaries</arg>
<sbr>
+ <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
+ <sbr>
<arg>--force-multiple</arg>
<sbr>
<group choice="opt">
<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>
<para>
The <option>--instance</option>, <option>--node</option>,
- <option>--primary</option>, <option>--secondary</option> and
- <option>--all</option> options are similar as for the
+ <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>
<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>--force-multiple</option> will skip the
interactive confirmation in the case the more than one
instance will be affected.
<cmdsynopsis>
<command>replace-disks</command>
<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>
<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>
<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>
<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>
<para>
+ 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>
Note that it is not possible to select an offline or drained
node as a new secondary.
</para>
</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>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>
<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>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>
<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