gnt-backup.rst 10.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
gnt-backup(8) Ganeti | Version @GANETI_VERSION@
===============================================

Name
----

gnt-backup - Ganeti instance import/export

Synopsis
--------

**gnt-backup** {command} [arguments...]

DESCRIPTION
-----------

The **gnt-backup** is used for importing and exporting instances
and their configuration from a Ganeti system. It is useful for
backing up instances and also to migrate them between clusters.

COMMANDS
--------

EXPORT
~~~~~~

27
| **export** {-n *node*}
28 29
| [\--shutdown-timeout=*N*] [\--noshutdown] [\--remove-instance]
| [\--ignore-remove-failures] [\--submit] [\--print-job-id]
30
| [\--transport-compression=*compression-mode*]
31 32
| [\--zero-free-space] [\--zeroing-timeout-fixed]
| [\--zeroing-timeout-per-mib]
33
| {*instance*}
34 35 36

Exports an instance to the target node. All the instance data and
its configuration will be exported under the
37
``@CUSTOM_EXPORT_DIR@/$instance`` directory on the target node.
38

39 40
The ``--transport-compression`` option is used to specify which
compression mode is used to try and speed up moves during the export.
Hrvoje Ribicic's avatar
Hrvoje Ribicic committed
41 42
Valid values are 'none', and any values defined in the
'compression_tools' cluster parameter.
43

44 45 46 47 48 49 50 51 52 53 54 55 56 57
The ``--shutdown-timeout`` 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.

The ``--noshutdown`` 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 guaranteed that the instance
data will be in a consistent state in the exported dump.

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

58 59
The ``--zero-free-space`` option can be used to zero the free space
of the instance prior to exporting it, saving space if compression
60 61 62 63
is used. The ``--zeroing-timeout-fixed`` and
``--zeroing-timeout-per-mib`` options control the timeout, the former
determining the minimum time to wait, and the latter how much longer
to wait per MiB of data the instance has.
64

65 66 67 68 69 70
Should the snapshotting or transfer of any of the instance disks
fail, the backup will not complete and any previous backups will be
preserved. 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.
71

72
See **ganeti**\(7) for a description of ``--submit`` and other common
73 74
options.

75 76 77 78 79 80 81 82 83
Example::

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


IMPORT
~~~~~~

| **import**
84
| {-n *node[:secondary-node]* | \--iallocator *name*}
85
| [\--compress=*compression-mode*]
86 87
| [\--disk *N*:size=*VAL* [,vg=*VG*], [,mode=*ro|rw*]...]
| [\--net *N* [:options...] | \--no-nics]
88 89
| [-B *BEPARAMS*]
| [-H *HYPERVISOR* [: option=*value*... ]]
90
| [\--src-node=*source-node*] [\--src-dir=*source-dir*]
91
| [-t [diskless | plain | drbd | file]]
92 93
| [\--identify-defaults]
| [\--ignore-ipolicy]
94
| [\--submit] [\--print-job-id]
95 96 97 98 99 100 101 102 103 104 105
| {*instance*}

Imports a new instance from an export residing on *source-node* in
*source-dir*. *instance* 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 **list** command.

The ``disk`` 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
106 107 108 109 110
(read-only or the default of read-write) and LVM volume group can also
be specified. The size is interpreted (when no unit is given) in
mebibytes. You can also use one of the suffixes m, g or t to specificy
the exact the units used; these suffixes map to mebibytes, gibibytes
and tebibytes.
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139

Alternatively, a single-disk instance can be created via the ``-s``
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).

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

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

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

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

ip
    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)

mode
Guido Trotter's avatar
Guido Trotter committed
140
    specifies the connection mode for this NIC: ``routed``,
141
    ``bridged`` or ``openvswitch``
142 143

link
144 145 146
    in bridged and openvswitch mode specifies the interface to attach
    this NIC to, in routed mode it's intended to differentiate between
    different routing tables/instance groups (but the meaning is
147
    dependent on the network script in use, see **gnt-cluster**\(8) for
148
    more details)
149

Guido Trotter's avatar
Guido Trotter committed
150
Of these ``mode`` and ``link`` are NIC parameters, and inherit their
151 152 153
default at cluster level.

If no network is desired for the instance, you should create a single
154
empty NIC and delete it afterwards via **gnt-instance modify \--net
155 156 157 158 159 160
delete**.

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

161 162
maxmem
    the maximum memory size of the instance; as usual, suffixes can be
163
    used to denote the unit, otherwise the value is taken in mebibytes
164 165 166

minmem
    the minimum memory size of the instance; as usual, suffixes can be
167
    used to denote the unit, otherwise the value is taken in mebibytes
168 169 170 171 172 173 174 175 176

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

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

177 178 179 180 181
always\_failover
    ``True`` or ``False``, whether the instance must be failed over
    (shut down and rebooted) always or it may be migrated (briefly
    suspended)

182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197

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

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

plain
    Disk devices will be logical volumes.

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

file
198 199 200 201
    Disk devices will be backed up by files, under the cluster's
    default file storage directory. 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.
202 203 204 205 206 207 208 209 210 211

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

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

212 213 214 215
The ``--compress`` option is used to specify which compression mode
is used for moves during the import. Valid values are 'none'
(the default) and 'gzip'.

216 217 218
The ``--src-dir`` option allows importing instances from a directory
below ``@CUSTOM_EXPORT_DIR@``.

219 220 221
If ``--ignore-ipolicy`` is given any instance policy violations occuring
during this operation are ignored.

222 223 224 225 226 227 228 229 230 231
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 ``--identify-defaults`` option. This will
affect the hypervisor, backend and NIC parameters, both read from
the export file and passed in via the command line.

232
See **ganeti**\(7) for a description of ``--submit`` and other common
233 234
options.

235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
Example for identical instance import::

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


Explicit configuration example::

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


LIST
~~~~

250 251
| **list** [\--node=*NODE*] [\--no-headers] [\--separator=*SEPARATOR*]
| [-o *[+]FIELD,...*]
252 253 254 255 256 257

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

258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
The ``--no-headers`` option will skip the initial header line. The
``--separator`` option takes an argument which denotes what will be
used between the output fields. Both these options are to help
scripting.

The ``-o`` option takes a comma-separated list of output fields.
The available fields and their meaning are:

@QUERY_FIELDS_EXPORT@

If the value of the option starts with the character ``+``, the new
fields will be added to the default list. This allows one to quickly
see the default list plus a few other fields, instead of retyping
the entire list of fields.

273 274
Example::

275 276 277 278 279 280 281 282 283
    # gnt-backup list --node node1 --node node2


LIST-FIELDS
~~~~~~~~~~~

**list-fields** [field...]

Lists available fields for exports.
284 285 286 287 288 289 290 291 292 293


REMOVE
~~~~~~

**remove** {instance_name}

Removes the backup for the given instance name, if any. If the backup
was for a deleted instance, it is needed to pass the FQDN of the
instance, and not only the short hostname.
294 295 296 297 298 299

.. vim: set textwidth=72 :
.. Local Variables:
.. mode: rst
.. fill-column: 72
.. End: