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