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 | {*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 memory
 140     the memory size of the instance; as usual, suffixes can be used to
 141     denote the unit, otherwise the value is taken in mebibites
 142
 143 vcpus
 144     the number of VCPUs to assign to the instance (if this value makes
 145     sense for the hypervisor)
 146
 147 auto_balance
 148     whether the instance is considered in the N+1 cluster checks
 149     (enough redundancy in the cluster to survive a node failure)
 150
 151
 152 The ``-t`` options specifies the disk layout type for the instance.
 153 If not passed, the configuration of the original instance is used.
 154 The available choices are:
 155
 156 diskless
 157     This creates an instance with no disks. Its useful for testing only
 158     (or other special cases).
 159
 160 plain
 161     Disk devices will be logical volumes.
 162
 163 drbd
 164     Disk devices will be drbd (version 8.x) on top of lvm volumes.
 165
 166 file
 167     Disk devices will be backed up by files, under the directory
 168     ``@RPL_FILE_STORAGE_DIR@``. By default, each instance will get a
 169     directory (as its own name) under this path, and each disk is
 170     stored as individual files in this (instance-specific) directory.
 171
 172
 173 The ``--iallocator`` option specifies the instance allocator plugin
 174 to use. If you pass in this option the allocator will select nodes
 175 for this instance automatically, so you don't need to pass them
 176 with the ``-n`` option. For more information please refer to the
 177 instance allocator documentation.
 178
 179 The optional second value of the ``--node`` is used for the drbd
 180 template and specifies the remote node.
 181
 182 The ``--src-dir`` option allows importing instances from a directory
 183 below ``@CUSTOM_EXPORT_DIR@``.
 184
 185 Since many of the parameters are by default read from the exported
 186 instance information and used as such, the new instance will have
 187 all parameters explicitly specified, the opposite of a newly added
 188 instance which has most parameters specified via cluster defaults.
 189 To change the import behaviour to recognize parameters whose saved
 190 value matches the current cluster default and mark it as such
 191 (default value), pass the ``--identify-defaults`` option. This will
 192 affect the hypervisor, backend and NIC parameters, both read from
 193 the export file and passed in via the command line.
 194
 195 Example for identical instance import::
 196
 197     # gnt-backup import -n node1.example.com instance3.example.com
 198
 199
 200 Explicit configuration example::
 201
 202     # gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
 203     > -n node1.example.com \
 204     > instance3.example.com
 205
 206
 207 LIST
 208 ~~~~
 209
 210 **list** [--node=*NODE*]
 211
 212 Lists the exports currently available in the default directory in
 213 all the nodes of the current cluster, or optionally only a subset
 214 of them specified using the ``--node`` option (which can be used
 215 multiple times)
 216
 217 Example::
 218
 219     # gnt-backup list --nodes node1 --nodes node2
 220
 221
 222 REMOVE
 223 ~~~~~~
 224
 225 **remove** {instance_name}
 226
 227 Removes the backup for the given instance name, if any. If the backup
 228 was for a deleted instance, it is needed to pass the FQDN of the
 229 instance, and not only the short hostname.
 230
 231 .. vim: set textwidth=72 :
 232 .. Local Variables:
 233 .. mode: rst
 234 .. fill-column: 72
 235 .. End: