<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!-- Please adjust the date whenever revising the manpage. -->
- <!ENTITY dhdate "<date>Jul 6, 2007</date>">
+ <!ENTITY dhdate "<date>June 08, 2010</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY dhsection "<manvolnum>8</manvolnum>">
<refentryinfo>
<copyright>
<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.2</refmiscinfo>
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
- <refpurpose>ganeti instance import/export</refpurpose>
+ <refpurpose>Ganeti instance import/export</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<para>
The <command>&dhpackage;</command> is used for importing and exporting
- instances and their configuration from a ganeti system. It is useful for
- backing instances up and also to migrate them between clusters.
+ instances and their configuration from a Ganeti system. It is useful for
+ backing up instances and also to migrate them between clusters.
</para>
</refsect1>
<cmdsynopsis>
<command>export</command>
<arg choice="req">-n <replaceable>node</replaceable></arg>
+ <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
<arg>--noshutdown</arg>
+ <arg>--remove-instance</arg>
+ <arg>--ignore-remove-failures</arg>
<arg choice="req"><replaceable>instance</replaceable></arg>
+
</cmdsynopsis>
<para>
Exports an instance to the target node. All the instance data
and its configuration will be exported under the
- /srv/ganeti/exports/<replaceable>instance</replaceable>
+ /srv/ganeti/export/<replaceable>instance</replaceable>
directory on the target node.
</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>--noshutdown</option> option will create a
snapshot disk of the instance without shutting it down first.
While this is faster and involves no downtime, it cannot be
</para>
<para>
+ The <option>--remove</option> option can be used to remove the
+ instance after it was exported. This is useful to make one last
+ backup before removing the instance.
+ </para>
+
+ <para>
+ The exit code of the command is 0 if all disks were backed up
+ successfully, 1 if no data was backed up or if the
+ configuration export failed, and 2 if just some of the disks
+ failed to backup. The exact details of the failures will be
+ shown during the command execution (and will be stored in the
+ job log). It is recommended that for any non-zero exit code,
+ the backup is considered invalid, and retried.
+ </para>
+
+ <para>
Example:
<screen>
# gnt-backup export -n node1.example.com instance3.example.com
<title>IMPORT</title>
<cmdsynopsis>
<command>import</command>
- <arg choice="req">-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
- <arg>-s <replaceable>disksize</replaceable></arg>
- <arg>--swap-size <replaceable>disksize</replaceable></arg>
- <arg>-m <replaceable>memsize</replaceable></arg>
- <arg>-b <replaceable>bridge</replaceable></arg>
<sbr>
- <arg choice="req">-t<group>
+ <group choice="req">
+ <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg> <arg>--iallocator
+ <replaceable>name</replaceable></arg>
+ </group>
+ <sbr>
+
+ <arg rep="repeat">--disk <replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></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>--src-node=<replaceable>source-node</replaceable></arg>
+ <arg>--src-dir=<replaceable>source-dir</replaceable></arg>
+ <sbr>
+
+ <arg choice="opt">-t<group>
<arg>diskless</arg>
<arg>plain</arg>
- <arg>local_raid1</arg>
- <arg>remote_raid1</arg>
<arg>drbd</arg>
- </group>
- </arg>
+ <arg>file</arg>
+ </group></arg>
+ <sbr>
+
+ <arg choice="opt">--identify-defaults</arg>
<sbr>
- <arg choice="req">--src-node=<replaceable>source-node</replaceable></arg>
- <arg choice="req">--src-dir=<replaceable>source-dir</replaceable></arg>
+
<arg choice="req"><replaceable>instance</replaceable></arg>
</cmdsynopsis>
+
<para>
Imports a new instance from an export residing on
<replaceable>source-node</replaceable> in
<replaceable>source-dir</replaceable>.
- <replaceable>instance</replaceable> must be in DNS and
- resolve to a IP in the same network as the nodes in the
- cluster.
+ <replaceable>instance</replaceable> must be in DNS and resolve
+ to a IP in the same network as the nodes in the cluster. If
+ the source node and directory are not passed, the last backup
+ in the cluster is used, as visible with the
+ <command>list</command> command.
</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. 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
+ <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.
+ 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>-m</option> option specifies the memory size for
- the instance, in mebibytes (defaults to 128 MiB).
+ If no disk information is passed, the disk configuration saved
+ at export time will be used.
</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 intialization time).
+ The minimum disk specification is therefore empty (export
+ information will be used), a single disk can be specified as
+ <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>-t</option> options specifies the disk layout type for
- the instance. The available choices are:
+ The NICs of the instances can be specified via the
+ <option>--net</option> option. By default, the NIC
+ configuration of the original (exported) instance will be
+ reused. Each NIC can take up to three 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 'generate' to generate a new
+ unique MAC, or 'auto' to reuse the old 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>mode</term>
+ <listitem>
+ <simpara>specifies the connection mode for this nic:
+ routed or bridged.</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>link</term>
+ <listitem>
+ <simpara>in bridged mode specifies the bridge to attach
+ this NIC to, in routed mode it's intended to
+ differentiate between different routing tables/instance
+ groups (but the meaning is dependent on the network
+ script, see gnt-cluster(8) for more details)</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Of these "mode" and "link" are nic parameters, and inherit their
+ default at cluster level.
+ </para>
+
+ <para>
+ If no network is desired for the instance, you should create a
+ single empty NIC and delete it afterwards
+ via <command>gnt-instance modify --net delete</command>.
+ </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 export. Possible
+ parameters are:
+ <variablelist>
<varlistentry>
- <term>local_raid1</term>
+ <term>memory</term>
<listitem>
- <para>
- Disk devices will be md raid1 arrays over two local
- logical volumes.
- </para>
+ <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>remote_raid1</term>
+ <term>vcpus</term>
+ <listitem>
+ <simpara>the number of VCPUs to assign to the instance
+ (if this value makes sense for the hypervisor)</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>auto_balance</term>
+ <listitem>
+ <simpara>whether the instance is considered in the N+1
+ cluster checks (enough redundancy in the cluster to
+ survive a node failure)</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ The <option>-t</option> options specifies the disk layout type
+ for the instance. If not passed, the configuration of the
+ original instance is used. The available choices are:
+ <variablelist>
+ <varlistentry>
+ <term>diskless</term>
<listitem>
<para>
- Disk devices will be md raid1 arrays with one
- component (so it's not actually raid1): a drbd (0.7.x)
- device between the instance's primary node and the
- node given by the second value of the
- <option>--node</option> option.
+ This creates an instance with no disks. Its useful for
+ testing only (or other special cases).
</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. They are equivalent in functionality to
- <replaceable>remote_raid1</replaceable>, but are
- recommended for new instances (if you have drbd 8.x
- installed).
+ volumes.
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>file</term>
+ <listitem>
+ <para>Disk devices will be backed up by files, under the
+ <filename
+ class="directory">@RPL_FILE_STORAGE_DIR@</filename>. By
+ default, each instance will get a directory (as its own
+ name) under this path, and each disk is stored as
+ individual files in this (instance-specific)
+ directory.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
<para>
- If you do not want gnt-backup to wait for the disk mirror
- to be synced, use the <option>--no-wait-for-sync</option>
- option.
+ 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>
- Example:
+ The optional second value of the <option>--node</option> is used for
+ the drbd template and specifies the remote node.
+ </para>
+
+ <para>
+ Since many of the parameters are by default read from the
+ exported instance information and used as such, the new
+ instance will have all parameters explicitly specified, the
+ opposite of a newly added instance which has most parameters
+ specified via cluster defaults. To change the import behaviour
+ to recognize parameters whose saved value matches the current
+ cluster default and mark it as such (default value), pass
+ the <option>--identify-defaults</option> option. This will
+ affect the hypervisor, backend and NIC parameters, both read
+ from the export file and passed in via the command line.
+ </para>
+
+ <para>
+ Example for identical instance import:
+ <screen>
+# gnt-backup import -n node1.example.com instance3.example.com
+ </screen>
+ </para>
+ <para>
+ Explicit configuration example:
<screen>
-# gnt-backup import -t plain -s 30 -m 512 -n node1.example.com \
-> --src-node=node2.example.com \
-> --src-dir=/srv/ganeti/exports/instance3.example.com \
+# gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
+> -n node1.example.com \
> instance3.example.com
</screen>
</para>
<screen>
# gnt-backup list --nodes node1 --nodes node2
</screen>
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>REMOVE</title>
+ <cmdsynopsis>
+ <command>remove</command>
+ <arg choice="req">instance_name</arg>
+ </cmdsynopsis>
+
+ <para>
+ Removes the backup for the given instance name, if any. If the
+ backup was for a deleted instances, it is needed to pass the
+ <acronym>FQDN</acronym> of the instance, and not only the
+ short hostname.
+ </para>
+
</refsect2>
</refsect1>