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] {*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 | [--ignore-ipolicy]
  74 | {*instance*}
  75
  76 Imports a new instance from an export residing on *source-node* in
  77 *source-dir*. *instance* must be in DNS and resolve to a IP in the
  78 same network as the nodes in the cluster. If the source node and
  79 directory are not passed, the last backup in the cluster is used,
  80 as visible with the **list** command.
  81
  82 The ``disk`` option specifies the parameters for the disks of the
  83 instance. The numbering of disks starts at zero. For each disk, at
  84 least the size needs to be given, and optionally the access mode
  85 (read-only or the default of read-write) and LVM volume group can also
  86 be specified. The size is interpreted (when no unit is given) in
  87 mebibytes. You can also use one of the suffixes m, g or t to specificy
  88 the exact the units used; these suffixes map to mebibytes, gibibytes
  89 and tebibytes.
  90
  91 Alternatively, a single-disk instance can be created via the ``-s``
  92 option which takes a single argument, the size of the disk. This is
  93 similar to the Ganeti 1.2 version (but will only create one disk).
  94
  95 If no disk information is passed, the disk configuration saved at
  96 export time will be used.
  97
  98 The minimum disk specification is therefore empty (export information
  99 will be used), a single disk can be specified as ``--disk 0:size=20G``
 100 (or ``-s 20G`` when using the ``-s`` option), and a three-disk
 101 instance can be specified as ``--disk 0:size=20G --disk 1:size=4G
 102 --disk 2:size=100G``.
 103
 104 The NICs of the instances can be specified via the ``--net``
 105 option. By default, the NIC configuration of the original
 106 (exported) instance will be reused. Each NIC can take up to three
 107 parameters (all optional):
 108
 109 mac
 110     either a value or ``generate`` to generate a new unique MAC, or
 111     ``auto`` to reuse the old MAC
 112
 113 ip
 114     specifies the IP address assigned to the instance from the Ganeti
 115     side (this is not necessarily what the instance will use, but what
 116     the node expects the instance to use)
 117
 118 mode
 119     specifies the connection mode for this nic: ``routed`` or
 120     ``bridged``.
 121
 122 link
 123     in bridged mode specifies the bridge to attach this NIC to, in
 124     routed mode it's intended to differentiate between different
 125     routing tables/instance groups (but the meaning is dependent on
 126     the network script in use, see **gnt-cluster**(8) for more
 127     details)
 128
 129 Of these ``mode`` and ``link`` are nic parameters, and inherit their
 130 default at cluster level.
 131
 132 If no network is desired for the instance, you should create a single
 133 empty NIC and delete it afterwards via **gnt-instance modify --net
 134 delete**.
 135
 136 The ``-B`` option specifies the backend parameters for the
 137 instance. If no such parameters are specified, the values are
 138 inherited from the export. Possible parameters are:
 139
 140 maxmem
 141     the maximum memory size of the instance; as usual, suffixes can be
 142     used to denote the unit, otherwise the value is taken in mebibytes
 143
 144 minmem
 145     the minimum memory size of the instance; as usual, suffixes can be
 146     used to denote the unit, otherwise the value is taken in mebibytes
 147
 148 vcpus
 149     the number of VCPUs to assign to the instance (if this value makes
 150     sense for the hypervisor)
 151
 152 auto_balance
 153     whether the instance is considered in the N+1 cluster checks
 154     (enough redundancy in the cluster to survive a node failure)
 155
 156 always\_failover
 157     ``True`` or ``False``, whether the instance must be failed over
 158     (shut down and rebooted) always or it may be migrated (briefly
 159     suspended)
 160
 161
 162 The ``-t`` options specifies the disk layout type for the instance.
 163 If not passed, the configuration of the original instance is used.
 164 The available choices are:
 165
 166 diskless
 167     This creates an instance with no disks. Its useful for testing only
 168     (or other special cases).
 169
 170 plain
 171     Disk devices will be logical volumes.
 172
 173 drbd
 174     Disk devices will be drbd (version 8.x) on top of lvm volumes.
 175
 176 file
 177     Disk devices will be backed up by files, under the directory
 178     ``@RPL_FILE_STORAGE_DIR@``. By default, each instance will get a
 179     directory (as its own name) under this path, and each disk is
 180     stored as individual files in this (instance-specific) directory.
 181
 182
 183 The ``--iallocator`` option specifies the instance allocator plugin
 184 to use. If you pass in this option the allocator will select nodes
 185 for this instance automatically, so you don't need to pass them
 186 with the ``-n`` option. For more information please refer to the
 187 instance allocator documentation.
 188
 189 The optional second value of the ``--node`` is used for the drbd
 190 template and specifies the remote node.
 191
 192 The ``--src-dir`` option allows importing instances from a directory
 193 below ``@CUSTOM_EXPORT_DIR@``.
 194
 195 If ``--ignore-ipolicy`` is given any instance policy violations occuring
 196 during this operation are ignored.
 197
 198 Since many of the parameters are by default read from the exported
 199 instance information and used as such, the new instance will have
 200 all parameters explicitly specified, the opposite of a newly added
 201 instance which has most parameters specified via cluster defaults.
 202 To change the import behaviour to recognize parameters whose saved
 203 value matches the current cluster default and mark it as such
 204 (default value), pass the ``--identify-defaults`` option. This will
 205 affect the hypervisor, backend and NIC parameters, both read from
 206 the export file and passed in via the command line.
 207
 208 Example for identical instance import::
 209
 210     # gnt-backup import -n node1.example.com instance3.example.com
 211
 212
 213 Explicit configuration example::
 214
 215     # gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
 216     > -n node1.example.com \
 217     > instance3.example.com
 218
 219
 220 LIST
 221 ~~~~
 222
 223 **list** [--node=*NODE*]
 224
 225 Lists the exports currently available in the default directory in
 226 all the nodes of the current cluster, or optionally only a subset
 227 of them specified using the ``--node`` option (which can be used
 228 multiple times)
 229
 230 Example::
 231
 232     # gnt-backup list --nodes node1 --nodes node2
 233
 234
 235 REMOVE
 236 ~~~~~~
 237
 238 **remove** {instance_name}
 239
 240 Removes the backup for the given instance name, if any. If the backup
 241 was for a deleted instance, it is needed to pass the FQDN of the
 242 instance, and not only the short hostname.
 243
 244 .. vim: set textwidth=72 :
 245 .. Local Variables:
 246 .. mode: rst
 247 .. fill-column: 72
 248 .. End: