vzdump.adoc

   1 ifdef::manvolnum[]
   2 vzdump(1)
   3 =========
   4 include::attributes.txt[]
   5 :pve-toplevel:
   6
   7 NAME
   8 ----
   9
  10 vzdump - Backup Utility for VMs and Containers
  11
  12
  13 SYNOPSIS
  14 --------
  15
  16 include::vzdump.1-synopsis.adoc[]
  17
  18
  19 DESCRIPTION
  20 -----------
  21 endif::manvolnum[]
  22
  23 ifndef::manvolnum[]
  24 Backup and Restore
  25 ==================
  26 include::attributes.txt[]
  27 endif::manvolnum[]
  28 ifdef::wiki[]
  29 :pve-toplevel:
  30 endif::wiki[]
  31
  32 Backups are a requirements for any sensible IT deployment, and {pve}
  33 provides a fully integrated solution, using the capabilities of each
  34 storage and each guest system type. This allows the system
  35 administrator to fine tune via the `mode` option between consistency
  36 of the backups and downtime of the guest system.
  37
  38 {pve} backups are always full backups - containing the VM/CT
  39 configuration and all data.  Backups can be started via the GUI or via
  40 the `vzdump` command line tool.
  41
  42 .Backup Storage
  43
  44 Before a backup can run, a backup storage must be defined. Refer to
  45 the Storage documentation on how to add a storage. A backup storage
  46 must be a file level storage, as backups are stored as regular files.
  47 In most situations, using a NFS server is a good way to store backups.
  48 You can save those backups later to a tape drive, for off-site
  49 archiving.
  50
  51 .Scheduled Backup
  52
  53 Backup jobs can be scheduled so that they are executed automatically
  54 on specific days and times, for selectable nodes and guest systems.
  55 Configuration of scheduled backups is done at the Datacenter level in
  56 the GUI, which will generate a cron entry in /etc/cron.d/vzdump.
  57
  58 Backup modes
  59 ------------
  60
  61 There are several ways to provide consistency (option `mode`),
  62 depending on the guest type.
  63
  64 .Backup modes for VMs:
  65
  66 `stop` mode::
  67
  68 This mode provides the highest consistency of the backup, at the cost
  69 of a downtime in the VM operation.  It works by executing an orderly
  70 shutdown of the VM, and then runs a background Qemu process to backup
  71 the VM data. After the backup is complete, the Qemu process resumes
  72 the VM to full operation mode if it was previously running.
  73
  74 `suspend` mode::
  75
  76 This mode is provided for compatibility reason, and suspends the VM
  77 before calling the `snapshot` mode. Since suspending the VM results in
  78 a longer downtime and does not necessarily improve the data
  79 consistency, the use of the `snapshot` mode is recommended instead.
  80
  81 `snapshot` mode::
  82
  83 This mode provides the lowest operation downtime, at the cost of a
  84 small inconstancy risk.  It works by performing a Proxmox VE live
  85 backup, in which data blocks are copied while the VM is running. If the
  86 guest agent is enabled (`agent: 1`) and running, it calls
  87 `guest-fsfreeze-freeze` and `guest-fsfreeze-thaw` to improve
  88 consistency.
  89
  90 A technical overview of the Proxmox VE live backup for QemuServer can
  91 be found online
  92 https://git.proxmox.com/?p=pve-qemu-kvm.git;a=blob;f=backup.txt[here].
  93
  94 NOTE: Proxmox VE live backup provides snapshot-like semantics on any
  95 storage type. It does not require that the underlying storage supports
  96 snapshots.
  97
  98 .Backup modes for Containers:
  99
 100 `stop` mode::
 101
 102 Stop the container for the duration of the backup. This potentially
 103 results in a very long downtime.
 104
 105 `suspend` mode::
 106
 107 This mode uses rsync to copy the container data to a temporary
 108 location (see option `--tmpdir`). Then the container is suspended and
 109 a second rsync copies changed files. After that, the container is
 110 started (resumed) again. This results in minimal downtime, but needs
 111 additional space to hold the container copy.
 112 +
 113 When the container is on a local file system and the target storage of
 114 the backup is an NFS server, you should set `--tmpdir` to reside on a
 115 local file system too, as this will result in a many fold performance
 116 improvement.  Use of a local `tmpdir` is also required if you want to
 117 backup a local container using ACLs in suspend mode if the backup
 118 storage is an NFS server.
 119
 120 `snapshot` mode::
 121
 122 This mode uses the snapshotting facilities of the underlying
 123 storage. First, the container will be suspended to ensure data consistency.
 124 A temporary snapshot of the container's volumes will be made and the
 125 snapshot content will be archived in a tar file. Finally, the temporary
 126 snapshot is deleted again.
 127
 128 NOTE: `snapshot` mode requires that all backed up volumes are on a storage that
 129 supports snapshots. Using the `backup=no` mount point option individual volumes
 130 can be excluded from the backup (and thus this requirement).
 131
 132 NOTE: bind and device mount points are skipped during backup operations, like
 133 volume mount points with the backup option disabled.
 134
 135
 136 Backup File Names
 137 -----------------
 138
 139 Newer versions of vzdump encode the guest type and the
 140 backup time into the filename, for example
 141
 142  vzdump-lxc-105-2009_10_09-11_04_43.tar
 143
 144 That way it is possible to store several backup in the same
 145 directory. The parameter `maxfiles` can be used to specify the
 146 maximum number of backups to keep.
 147
 148 Restore
 149 -------
 150
 151 The resulting archive files can be restored with the following programs.
 152
 153
 154 `pct restore`:: Container restore utility
 155
 156 `qmrestore`:: QemuServer restore utility
 157
 158 For details see the corresponding manual pages.
 159
 160 Configuration
 161 -------------
 162
 163 Global configuration is stored in `/etc/vzdump.conf`. The file uses a
 164 simple colon separated key/value format. Each line has the following
 165 format:
 166
 167  OPTION: value
 168
 169 Blank lines in the file are ignored, and lines starting with a `#`
 170 character are treated as comments and are also ignored. Values from
 171 this file are used as default, and can be overwritten on the command
 172 line.
 173
 174 We currently support the following options:
 175
 176 include::vzdump.conf.5-opts.adoc[]
 177
 178
 179 .Example `vzdump.conf` Configuration
 180 ----
 181 tmpdir: /mnt/fast_local_disk
 182 storage: my_backup_storage
 183 mode: snapshot
 184 bwlimit: 10000
 185 ----
 186
 187 Hook Scripts
 188 ------------
 189
 190 You can specify a hook script with option `--script`. This script is
 191 called at various phases of the backup process, with parameters
 192 accordingly set. You can find an example in the documentation
 193 directory (`vzdump-hook-script.pl`).
 194
 195 File Exclusions
 196 ---------------
 197
 198 NOTE: this option is only available for container backups.
 199
 200 `vzdump` skips the following files by default (disable with the option
 201 `--stdexcludes 0`)
 202
 203  /tmp/?*
 204  /var/tmp/?*
 205  /var/run/?*pid
 206
 207 You can also manually specify (additional) exclude paths, for example:
 208
 209  # vzdump 777 --exclude-path /tmp/ --exclude-path '/var/foo*'
 210
 211 (only excludes tmp directories)
 212
 213 Configuration files are also stored inside the backup archive
 214 (in `./etc/vzdump/`) and will be correctly restored.
 215
 216 Examples
 217 --------
 218
 219 Simply dump guest 777 - no snapshot, just archive the guest private area and
 220 configuration files to the default dump directory (usually
 221 `/var/lib/vz/dump/`).
 222
 223  # vzdump 777
 224
 225 Use rsync and suspend/resume to create a snapshot (minimal downtime).
 226
 227  # vzdump 777 --mode suspend
 228
 229 Backup all guest systems and send notification mails to root and admin.
 230
 231  # vzdump --all --mode suspend --mailto root --mailto admin
 232
 233 Use snapshot mode (no downtime) and non-default dump directory.
 234
 235  # vzdump 777 --dumpdir /mnt/backup --mode snapshot
 236
 237 Backup more than one guest (selectively)
 238
 239  # vzdump 101 102 103 --mailto root
 240
 241 Backup all guests excluding 101 and 102
 242
 243  # vzdump --mode suspend --exclude 101,102
 244
 245 Restore a container to a new CT 600
 246
 247  # pct restore 600 /mnt/backup/vzdump-lxc-777.tar
 248
 249 Restore a QemuServer VM to VM 601
 250
 251  # qmrestore /mnt/backup/vzdump-qemu-888.vma 601
 252
 253 Clone an existing container 101 to a new container 300 with a 4GB root
 254 file system, using pipes
 255
 256  # vzdump 101 --stdout | pct restore --rootfs 4 300 -
 257
 258
 259 ifdef::manvolnum[]
 260 include::pve-copyright.adoc[]
 261 endif::manvolnum[]
 262