verify-disks: Explicitely state nothing has to be done
[ganeti-local] / man / gnt-backup.rst
1 gnt-backup(8) Ganeti | Version @GANETI_VERSION@
2 ===============================================
3
4 Name
5 ----
6
7 gnt-backup - Ganeti instance import/export
8
9 Synopsis
10 --------
11
12 **gnt-backup** {command} [arguments...]
13
14 DESCRIPTION
15 -----------
16
17 The **gnt-backup** is used for importing and exporting instances
18 and their configuration from a Ganeti system. It is useful for
19 backing up instances and also to migrate them between clusters.
20
21 COMMANDS
22 --------
23
24 EXPORT
25 ~~~~~~
26
27 | **export** {-n *node*} [\--shutdown-timeout=*N*] [\--noshutdown]
28 | [\--remove-instance] [\--ignore-remove-failures] [\--submit]
29 | {*instance*}
30
31 Exports an instance to the target node. All the instance data and
32 its configuration will be exported under the
33 ``@CUSTOM_EXPORT_DIR@/``*instance* directory on the target node.
34
35 The ``--shutdown-timeout`` is used to specify how much time to wait
36 before forcing the shutdown (xm destroy in xen, killing the kvm
37 process, for kvm). By default two minutes are given to each
38 instance to stop.
39
40 The ``--noshutdown`` option will create a snapshot disk of the
41 instance without shutting it down first. While this is faster and
42 involves no downtime, it cannot be guaranteed that the instance
43 data will be in a consistent state in the exported dump.
44
45 The ``--remove`` option can be used to remove the instance after it
46 was exported. This is useful to make one last backup before
47 removing the instance.
48
49 The exit code of the command is 0 if all disks were backed up
50 successfully, 1 if no data was backed up or if the configuration
51 export failed, and 2 if just some of the disks failed to backup.
52 The exact details of the failures will be shown during the command
53 execution (and will be stored in the job log). It is recommended
54 that for any non-zero exit code, the backup is considered invalid,
55 and retried.
56
57 See **ganeti(7)** for a description of ``--submit`` and other common
58 options.
59
60 Example::
61
62     # gnt-backup export -n node1.example.com instance3.example.com
63
64
65 IMPORT
66 ~~~~~~
67
68 | **import**
69 | {-n *node[:secondary-node]* | \--iallocator *name*}
70 | [\--disk *N*:size=*VAL* [,vg=*VG*], [,mode=*ro|rw*]...]
71 | [\--net *N* [:options...] | \--no-nics]
72 | [-B *BEPARAMS*]
73 | [-H *HYPERVISOR* [: option=*value*... ]]
74 | [\--src-node=*source-node*] [\--src-dir=*source-dir*]
75 | [-t [diskless | plain | drbd | file]]
76 | [\--identify-defaults]
77 | [\--ignore-ipolicy]
78 | [\--submit]
79 | {*instance*}
80
81 Imports a new instance from an export residing on *source-node* in
82 *source-dir*. *instance* must be in DNS and resolve to a IP in the
83 same network as the nodes in the cluster. If the source node and
84 directory are not passed, the last backup in the cluster is used,
85 as visible with the **list** command.
86
87 The ``disk`` option specifies the parameters for the disks of the
88 instance. The numbering of disks starts at zero. For each disk, at
89 least the size needs to be given, and optionally the access mode
90 (read-only or the default of read-write) and LVM volume group can also
91 be specified. The size is interpreted (when no unit is given) in
92 mebibytes. You can also use one of the suffixes m, g or t to specificy
93 the exact the units used; these suffixes map to mebibytes, gibibytes
94 and tebibytes.
95
96 Alternatively, a single-disk instance can be created via the ``-s``
97 option which takes a single argument, the size of the disk. This is
98 similar to the Ganeti 1.2 version (but will only create one disk).
99
100 If no disk information is passed, the disk configuration saved at
101 export time will be used.
102
103 The minimum disk specification is therefore empty (export information
104 will be used), a single disk can be specified as ``--disk 0:size=20G``
105 (or ``-s 20G`` when using the ``-s`` option), and a three-disk
106 instance can be specified as ``--disk 0:size=20G --disk 1:size=4G
107 --disk 2:size=100G``.
108
109 The NICs of the instances can be specified via the ``--net``
110 option. By default, the NIC configuration of the original
111 (exported) instance will be reused. Each NIC can take up to three
112 parameters (all optional):
113
114 mac
115     either a value or ``generate`` to generate a new unique MAC, or
116     ``auto`` to reuse the old MAC
117
118 ip
119     specifies the IP address assigned to the instance from the Ganeti
120     side (this is not necessarily what the instance will use, but what
121     the node expects the instance to use)
122
123 mode
124     specifies the connection mode for this nic: ``routed`` or
125     ``bridged``.
126
127 link
128     in bridged mode specifies the bridge to attach this NIC to, in
129     routed mode it's intended to differentiate between different
130     routing tables/instance groups (but the meaning is dependent on
131     the network script in use, see **gnt-cluster**(8) for more
132     details)
133
134 Of these ``mode`` and ``link`` are nic parameters, and inherit their
135 default at cluster level.
136
137 If no network is desired for the instance, you should create a single
138 empty NIC and delete it afterwards via **gnt-instance modify \--net
139 delete**.
140
141 The ``-B`` option specifies the backend parameters for the
142 instance. If no such parameters are specified, the values are
143 inherited from the export. Possible parameters are:
144
145 maxmem
146     the maximum memory size of the instance; as usual, suffixes can be
147     used to denote the unit, otherwise the value is taken in mebibytes
148
149 minmem
150     the minimum memory size of the instance; as usual, suffixes can be
151     used to denote the unit, otherwise the value is taken in mebibytes
152
153 vcpus
154     the number of VCPUs to assign to the instance (if this value makes
155     sense for the hypervisor)
156
157 auto_balance
158     whether the instance is considered in the N+1 cluster checks
159     (enough redundancy in the cluster to survive a node failure)
160
161 always\_failover
162     ``True`` or ``False``, whether the instance must be failed over
163     (shut down and rebooted) always or it may be migrated (briefly
164     suspended)
165
166
167 The ``-t`` options specifies the disk layout type for the instance.
168 If not passed, the configuration of the original instance is used.
169 The available choices are:
170
171 diskless
172     This creates an instance with no disks. Its useful for testing only
173     (or other special cases).
174
175 plain
176     Disk devices will be logical volumes.
177
178 drbd
179     Disk devices will be drbd (version 8.x) on top of lvm volumes.
180
181 file
182     Disk devices will be backed up by files, under the directory
183     ``@RPL_FILE_STORAGE_DIR@``. By default, each instance will get a
184     directory (as its own name) under this path, and each disk is
185     stored as individual files in this (instance-specific) directory.
186
187
188 The ``--iallocator`` option specifies the instance allocator plugin
189 to use. If you pass in this option the allocator will select nodes
190 for this instance automatically, so you don't need to pass them
191 with the ``-n`` option. For more information please refer to the
192 instance allocator documentation.
193
194 The optional second value of the ``--node`` is used for the drbd
195 template and specifies the remote node.
196
197 The ``--src-dir`` option allows importing instances from a directory
198 below ``@CUSTOM_EXPORT_DIR@``.
199
200 If ``--ignore-ipolicy`` is given any instance policy violations occuring
201 during this operation are ignored.
202
203 Since many of the parameters are by default read from the exported
204 instance information and used as such, the new instance will have
205 all parameters explicitly specified, the opposite of a newly added
206 instance which has most parameters specified via cluster defaults.
207 To change the import behaviour to recognize parameters whose saved
208 value matches the current cluster default and mark it as such
209 (default value), pass the ``--identify-defaults`` option. This will
210 affect the hypervisor, backend and NIC parameters, both read from
211 the export file and passed in via the command line.
212
213 See **ganeti(7)** for a description of ``--submit`` and other common
214 options.
215
216 Example for identical instance import::
217
218     # gnt-backup import -n node1.example.com instance3.example.com
219
220
221 Explicit configuration example::
222
223     # gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
224     > -n node1.example.com \
225     > instance3.example.com
226
227
228 LIST
229 ~~~~
230
231 | **list** [\--node=*NODE*] [\--no-headers] [\--separator=*SEPARATOR*]
232 | [-o *[+]FIELD,...*]
233
234 Lists the exports currently available in the default directory in
235 all the nodes of the current cluster, or optionally only a subset
236 of them specified using the ``--node`` option (which can be used
237 multiple times)
238
239 The ``--no-headers`` option will skip the initial header line. The
240 ``--separator`` option takes an argument which denotes what will be
241 used between the output fields. Both these options are to help
242 scripting.
243
244 The ``-o`` option takes a comma-separated list of output fields.
245 The available fields and their meaning are:
246
247 @QUERY_FIELDS_EXPORT@
248
249 If the value of the option starts with the character ``+``, the new
250 fields will be added to the default list. This allows one to quickly
251 see the default list plus a few other fields, instead of retyping
252 the entire list of fields.
253
254 Example::
255
256     # gnt-backup list --node node1 --node node2
257
258
259 LIST-FIELDS
260 ~~~~~~~~~~~
261
262 **list-fields** [field...]
263
264 Lists available fields for exports.
265
266
267 REMOVE
268 ~~~~~~
269
270 **remove** {instance_name}
271
272 Removes the backup for the given instance name, if any. If the backup
273 was for a deleted instance, it is needed to pass the FQDN of the
274 instance, and not only the short hostname.
275
276 .. vim: set textwidth=72 :
277 .. Local Variables:
278 .. mode: rst
279 .. fill-column: 72
280 .. End: