Statistics
| Branch: | Tag: | Revision:

root / man / gnt-backup.rst @ 11dc66f3

History | View | Annotate | Download (8.1 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*} [--shutdown-timeout=*N*] [--noshutdown]
28
[--remove-instance] [--ignore-remove-failures] {*instance*}
29

    
30
Exports an instance to the target node. All the instance data and
31
its configuration will be exported under the
32
``@CUSTOM_EXPORT_DIR@/``*instance* directory on the target node.
33

    
34
The ``--shutdown-timeout`` is used to specify how much time to wait
35
before forcing the shutdown (xm destroy in xen, killing the kvm
36
process, for kvm). By default two minutes are given to each
37
instance to stop.
38

    
39
The ``--noshutdown`` option will create a snapshot disk of the
40
instance without shutting it down first. While this is faster and
41
involves no downtime, it cannot be guaranteed that the instance
42
data will be in a consistent state in the exported dump.
43

    
44
The ``--remove`` option can be used to remove the instance after it
45
was exported. This is useful to make one last backup before
46
removing the instance.
47

    
48
The exit code of the command is 0 if all disks were backed up
49
successfully, 1 if no data was backed up or if the configuration
50
export failed, and 2 if just some of the disks failed to backup.
51
The exact details of the failures will be shown during the command
52
execution (and will be stored in the job log). It is recommended
53
that for any non-zero exit code, the backup is considered invalid,
54
and retried.
55

    
56
Example::
57

    
58
    # gnt-backup export -n node1.example.com instance3.example.com
59

    
60

    
61
IMPORT
62
~~~~~~
63

    
64
| **import**
65
| {-n *node[:secondary-node]* | --iallocator *name*}
66
| [--disk *N*:size=*VAL* [,vg=*VG*], [,mode=*ro|rw*]...]
67
| [--net *N* [:options...] | --no-nics]
68
| [-B *BEPARAMS*]
69
| [-H *HYPERVISOR* [: option=*value*... ]]
70
| [--src-node=*source-node*] [--src-dir=*source-dir*]
71
| [-t [diskless | plain | drbd | file]]
72
| [--identify-defaults]
73
| {*instance*}
74

    
75
Imports a new instance from an export residing on *source-node* in
76
*source-dir*. *instance* must be in DNS and resolve to a IP in the
77
same network as the nodes in the cluster. If the source node and
78
directory are not passed, the last backup in the cluster is used,
79
as visible with the **list** command.
80

    
81
The ``disk`` option specifies the parameters for the disks of the
82
instance. The numbering of disks starts at zero. For each disk, at
83
least the size needs to be given, and optionally the access mode
84
(read-only or the default of read-write) and LVM volume group can also
85
be specified. The size is interpreted (when no unit is given) in
86
mebibytes. You can also use one of the suffixes m, g or t to specificy
87
the exact the units used; these suffixes map to mebibytes, gibibytes
88
and tebibytes.
89

    
90
Alternatively, a single-disk instance can be created via the ``-s``
91
option which takes a single argument, the size of the disk. This is
92
similar to the Ganeti 1.2 version (but will only create one disk).
93

    
94
If no disk information is passed, the disk configuration saved at
95
export time will be used.
96

    
97
The minimum disk specification is therefore empty (export information
98
will be used), a single disk can be specified as ``--disk 0:size=20G``
99
(or ``-s 20G`` when using the ``-s`` option), and a three-disk
100
instance can be specified as ``--disk 0:size=20G --disk 1:size=4G
101
--disk 2:size=100G``.
102

    
103
The NICs of the instances can be specified via the ``--net``
104
option. By default, the NIC configuration of the original
105
(exported) instance will be reused. Each NIC can take up to three
106
parameters (all optional):
107

    
108
mac
109
    either a value or ``generate`` to generate a new unique MAC, or
110
    ``auto`` to reuse the old MAC
111

    
112
ip
113
    specifies the IP address assigned to the instance from the Ganeti
114
    side (this is not necessarily what the instance will use, but what
115
    the node expects the instance to use)
116

    
117
mode
118
    specifies the connection mode for this nic: ``routed`` or
119
    ``bridged``.
120

    
121
link
122
    in bridged mode specifies the bridge to attach this NIC to, in
123
    routed mode it's intended to differentiate between different
124
    routing tables/instance groups (but the meaning is dependent on
125
    the network script in use, see **gnt-cluster**(8) for more
126
    details)
127

    
128
Of these ``mode`` and ``link`` are nic parameters, and inherit their
129
default at cluster level.
130

    
131
If no network is desired for the instance, you should create a single
132
empty NIC and delete it afterwards via **gnt-instance modify --net
133
delete**.
134

    
135
The ``-B`` option specifies the backend parameters for the
136
instance. If no such parameters are specified, the values are
137
inherited from the export. Possible parameters are:
138

    
139
maxmem
140
    the maximum memory size of the instance; as usual, suffixes can be
141
    used to denote the unit, otherwise the value is taken in mebibytes
142

    
143
minmem
144
    the minimum memory size of the instance; as usual, suffixes can be
145
    used to denote the unit, otherwise the value is taken in mebibytes
146

    
147
vcpus
148
    the number of VCPUs to assign to the instance (if this value makes
149
    sense for the hypervisor)
150

    
151
auto_balance
152
    whether the instance is considered in the N+1 cluster checks
153
    (enough redundancy in the cluster to survive a node failure)
154

    
155
always\_failover
156
    ``True`` or ``False``, whether the instance must be failed over
157
    (shut down and rebooted) always or it may be migrated (briefly
158
    suspended)
159

    
160

    
161
The ``-t`` options specifies the disk layout type for the instance.
162
If not passed, the configuration of the original instance is used.
163
The available choices are:
164

    
165
diskless
166
    This creates an instance with no disks. Its useful for testing only
167
    (or other special cases).
168

    
169
plain
170
    Disk devices will be logical volumes.
171

    
172
drbd
173
    Disk devices will be drbd (version 8.x) on top of lvm volumes.
174

    
175
file
176
    Disk devices will be backed up by files, under the directory
177
    ``@RPL_FILE_STORAGE_DIR@``. By default, each instance will get a
178
    directory (as its own name) under this path, and each disk is
179
    stored as individual files in this (instance-specific) directory.
180

    
181

    
182
The ``--iallocator`` option specifies the instance allocator plugin
183
to use. If you pass in this option the allocator will select nodes
184
for this instance automatically, so you don't need to pass them
185
with the ``-n`` option. For more information please refer to the
186
instance allocator documentation.
187

    
188
The optional second value of the ``--node`` is used for the drbd
189
template and specifies the remote node.
190

    
191
The ``--src-dir`` option allows importing instances from a directory
192
below ``@CUSTOM_EXPORT_DIR@``.
193

    
194
Since many of the parameters are by default read from the exported
195
instance information and used as such, the new instance will have
196
all parameters explicitly specified, the opposite of a newly added
197
instance which has most parameters specified via cluster defaults.
198
To change the import behaviour to recognize parameters whose saved
199
value matches the current cluster default and mark it as such
200
(default value), pass the ``--identify-defaults`` option. This will
201
affect the hypervisor, backend and NIC parameters, both read from
202
the export file and passed in via the command line.
203

    
204
Example for identical instance import::
205

    
206
    # gnt-backup import -n node1.example.com instance3.example.com
207

    
208

    
209
Explicit configuration example::
210

    
211
    # gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
212
    > -n node1.example.com \
213
    > instance3.example.com
214

    
215

    
216
LIST
217
~~~~
218

    
219
**list** [--node=*NODE*]
220

    
221
Lists the exports currently available in the default directory in
222
all the nodes of the current cluster, or optionally only a subset
223
of them specified using the ``--node`` option (which can be used
224
multiple times)
225

    
226
Example::
227

    
228
    # gnt-backup list --nodes node1 --nodes node2
229

    
230

    
231
REMOVE
232
~~~~~~
233

    
234
**remove** {instance_name}
235

    
236
Removes the backup for the given instance name, if any. If the backup
237
was for a deleted instance, it is needed to pass the FQDN of the
238
instance, and not only the short hostname.
239

    
240
.. vim: set textwidth=72 :
241
.. Local Variables:
242
.. mode: rst
243
.. fill-column: 72
244
.. End: