1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
3 <!-- Fill in your name for FIRSTNAME and SURNAME. -->
4 <!-- Please adjust the date whenever revising the manpage. -->
5 <!ENTITY dhdate "<date>June 08, 2010</date>">
6 <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
7 allowed: see man(7), man(1). -->
8 <!ENTITY dhsection "<manvolnum>8</manvolnum>">
9 <!ENTITY dhucpackage "<refentrytitle>gnt-backup</refentrytitle>">
10 <!ENTITY dhpackage "gnt-backup">
12 <!ENTITY debian "<productname>Debian</productname>">
13 <!ENTITY gnu "<acronym>GNU</acronym>">
14 <!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
15 <!ENTITY footer SYSTEM "footer.sgml">
25 <holder>Google Inc.</holder>
33 <refmiscinfo>Ganeti 2.2</refmiscinfo>
36 <refname>&dhpackage;</refname>
38 <refpurpose>Ganeti instance import/export</refpurpose>
42 <command>&dhpackage; </command>
44 <arg choice="req">command</arg>
45 <arg>arguments...</arg>
49 <title>DESCRIPTION</title>
52 The <command>&dhpackage;</command> is used for importing and exporting
53 instances and their configuration from a Ganeti system. It is useful for
54 backing up instances and also to migrate them between clusters.
59 <title>COMMANDS</title>
65 <command>export</command>
66 <arg choice="req">-n <replaceable>node</replaceable></arg>
67 <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
68 <arg>--noshutdown</arg>
69 <arg>--remove-instance</arg>
70 <arg>--ignore-remove-failures</arg>
71 <arg choice="req"><replaceable>instance</replaceable></arg>
76 Exports an instance to the target node. All the instance data
77 and its configuration will be exported under the
78 /srv/ganeti/export/<replaceable>instance</replaceable>
79 directory on the target node.
83 The <option>--shutdown-timeout</option> is used to specify how
84 much time to wait before forcing the shutdown (xm destroy in xen,
85 killing the kvm process, for kvm). By default two minutes are
86 given to each instance to stop.
90 The <option>--noshutdown</option> option will create a
91 snapshot disk of the instance without shutting it down first.
92 While this is faster and involves no downtime, it cannot be
93 guaranteed that the instance data will be in a consistent state
98 The <option>--remove</option> option can be used to remove the
99 instance after it was exported. This is useful to make one last
100 backup before removing the instance.
104 The exit code of the command is 0 if all disks were backed up
105 successfully, 1 if no data was backed up or if the
106 configuration export failed, and 2 if just some of the disks
107 failed to backup. The exact details of the failures will be
108 shown during the command execution (and will be stored in the
109 job log). It is recommended that for any non-zero exit code,
110 the backup is considered invalid, and retried.
116 # gnt-backup export -n node1.example.com instance3.example.com
122 <title>IMPORT</title>
124 <command>import</command>
127 <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg> <arg>--iallocator
128 <replaceable>name</replaceable></arg>
132 <arg rep="repeat">--disk <replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
135 <arg rep="repeat">--net <replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>
139 <arg>-B <replaceable>BEPARAMS</replaceable></arg>
141 <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>
143 <arg>--src-node=<replaceable>source-node</replaceable></arg>
144 <arg>--src-dir=<replaceable>source-dir</replaceable></arg>
147 <arg choice="opt">-t<group>
155 <arg choice="opt">--identify-defaults</arg>
158 <arg choice="req"><replaceable>instance</replaceable></arg>
162 Imports a new instance from an export residing on
163 <replaceable>source-node</replaceable> in
164 <replaceable>source-dir</replaceable>.
165 <replaceable>instance</replaceable> must be in DNS and resolve
166 to a IP in the same network as the nodes in the cluster. If
167 the source node and directory are not passed, the last backup
168 in the cluster is used, as visible with the
169 <command>list</command> command.
173 The <option>disk</option> option specifies the parameters for
174 the disks of the instance. The numbering of disks starts at
175 zero. For each disk, at least the size needs to be given, and
176 optionally the access mode (read-only or the default of
177 read-write) can also be specified. The size is interpreted
178 (when no unit is given) in mebibytes. You can also use one of
180 <literal>m</literal>, <literal>g</literal> or
181 <literal>t</literal> to specificy the exact the units used;
182 these suffixes map to mebibytes, gibibytes and tebibytes.
186 Alternatively, a single-disk instance can be created via the
187 <option>-s</option> option which takes a single argument,
188 the size of the disk. This is similar to the Ganeti 1.2
189 version (but will only create one disk).
193 If no disk information is passed, the disk configuration saved
194 at export time will be used.
198 The minimum disk specification is therefore empty (export
199 information will be used), a single disk can be specified as
200 <userinput>--disk 0:size=20G</userinput> (or <userinput>-s
201 20G</userinput> when using the <option>-s</option> option),
202 and a three-disk instance can be specified as
203 <userinput>--disk 0:size=20G --disk 1:size=4G --disk
204 2:size=100G</userinput>.
208 The NICs of the instances can be specified via the
209 <option>--net</option> option. By default, the NIC
210 configuration of the original (exported) instance will be
211 reused. Each NIC can take up to three parameters (all
217 <simpara>either a value or 'generate' to generate a new
218 unique MAC, or 'auto' to reuse the old MAC</simpara>
224 <simpara>specifies the IP address assigned to the
225 instance from the Ganeti side (this is not necessarily
226 what the instance will use, but what the node expects
227 the instance to use)</simpara>
233 <simpara>specifies the connection mode for this nic:
234 routed or bridged.</simpara>
240 <simpara>in bridged mode specifies the bridge to attach
241 this NIC to, in routed mode it's intended to
242 differentiate between different routing tables/instance
243 groups (but the meaning is dependent on the network
244 script, see gnt-cluster(8) for more details)</simpara>
248 Of these "mode" and "link" are nic parameters, and inherit their
249 default at cluster level.
253 If no network is desired for the instance, you should create a
254 single empty NIC and delete it afterwards
255 via <command>gnt-instance modify --net delete</command>.
259 The <option>-B</option> option specifies the backend
260 parameters for the instance. If no such parameters are
261 specified, the values are inherited from the export. Possible
267 <simpara>the memory size of the instance; as usual,
268 suffixes can be used to denote the unit, otherwise the
269 value is taken in mebibites</simpara>
275 <simpara>the number of VCPUs to assign to the instance
276 (if this value makes sense for the hypervisor)</simpara>
280 <term>auto_balance</term>
282 <simpara>whether the instance is considered in the N+1
283 cluster checks (enough redundancy in the cluster to
284 survive a node failure)</simpara>
291 The <option>-t</option> options specifies the disk layout type
292 for the instance. If not passed, the configuration of the
293 original instance is used. The available choices are:
296 <term>diskless</term>
299 This creates an instance with no disks. Its useful for
300 testing only (or other special cases).
307 <para>Disk devices will be logical volumes.</para>
314 Disk devices will be drbd (version 8.x) on top of lvm
322 <para>Disk devices will be backed up by files, under the
324 class="directory">@RPL_FILE_STORAGE_DIR@</filename>. By
325 default, each instance will get a directory (as its own
326 name) under this path, and each disk is stored as
327 individual files in this (instance-specific)
335 The <option>--iallocator</option> option specifies the instance
336 allocator plugin to use. If you pass in this option the allocator will
337 select nodes for this instance automatically, so you don't need to pass
338 them with the <option>-n</option> option. For more information please
339 refer to the instance allocator documentation.
343 The optional second value of the <option>--node</option> is used for
344 the drbd template and specifies the remote node.
348 Since many of the parameters are by default read from the
349 exported instance information and used as such, the new
350 instance will have all parameters explicitly specified, the
351 opposite of a newly added instance which has most parameters
352 specified via cluster defaults. To change the import behaviour
353 to recognize parameters whose saved value matches the current
354 cluster default and mark it as such (default value), pass
355 the <option>--identify-defaults</option> option. This will
356 affect the hypervisor, backend and NIC parameters, both read
357 from the export file and passed in via the command line.
361 Example for identical instance import:
363 # gnt-backup import -n node1.example.com instance3.example.com
367 Explicit configuration example:
369 # gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
370 > -n node1.example.com \
371 > instance3.example.com
381 <command>list</command>
382 <arg>--node=<replaceable>NODE</replaceable></arg>
386 Lists the exports currently available in the default directory
387 in all the nodes of the current cluster, or optionally only a
388 subset of them specified using the <option>--node</option>
389 option (which can be used multiple times)
395 # gnt-backup list --nodes node1 --nodes node2
401 <title>REMOVE</title>
403 <command>remove</command>
404 <arg choice="req">instance_name</arg>
408 Removes the backup for the given instance name, if any. If the
409 backup was for a deleted instances, it is needed to pass the
410 <acronym>FQDN</acronym> of the instance, and not only the
422 <!-- Keep this comment at the end of the file
427 sgml-minimize-attributes:nil
428 sgml-always-quote-attributes:t
431 sgml-parent-document:nil
432 sgml-default-dtd-file:nil
433 sgml-exposed-tags:nil
434 sgml-local-catalogs:nil
435 sgml-local-ecat-files:nil