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