vzdump.adoc

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