<!-- 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>
</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>
-
+ <sbr>
<group choice="req">
- <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
- <arg>--iallocator <replaceable>name</replaceable></arg>
+ <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg> <arg>--iallocator
+ <replaceable>name</replaceable></arg>
</group>
<sbr>
- <arg>-s <replaceable>disksize</replaceable></arg>
- <arg>--swap-size <replaceable>disksize</replaceable></arg>
- <arg>-m <replaceable>memsize</replaceable></arg>
+ <arg rep="repeat">--disk <replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
<sbr>
-
- <arg>-b <replaceable>bridge</replaceable></arg>
- <arg>--mac <replaceable>mac</replaceable></arg>
+ <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 choice="req">--src-node=<replaceable>source-node</replaceable></arg>
- <arg choice="req">--src-dir=<replaceable>source-dir</replaceable></arg>
+ <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="req">-t<group>
+ <arg choice="opt">-t<group>
<arg>diskless</arg>
<arg>plain</arg>
<arg>drbd</arg>
+ <arg>file</arg>
</group></arg>
<sbr>
+ <arg choice="opt">--identify-defaults</arg>
+ <sbr>
+
<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). Again, you
- can use other suffixes (e.g. <userinput>2g</userinput>).
+ 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>--mac</option> option specifies the mac address for the
- instance. The default is 'auto' which is reusing the previous mac
- address if the instance is being imported with the same name, and
- generating a new one otherwise. You can also force generation by
- specifying 'generate'.
+ 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>mac</term>
+ <listitem>
+ <simpara>either a value or <constant>GENERATE</constant>
+ to generate a new unique MAC, or
+ <constant>AUTO</constant> to reuse the old MAC</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ip</term>
+ <listitem>
+ <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>-t</option> options specifies the disk layout type for
- the instance. The available choices are:
+ 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>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>
+ 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>
</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>
The optional second value of the <option>--node</option> is used for
- the remote raid template type and specifies the remote node.
+ the drbd template and specifies the remote node.
</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.
+ 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:
+ 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/export/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>
projects / ganeti-local / blobdiff