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 complete, the Qemu process resumes
  68 the VM to full 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-kvm.git;a=blob;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.
  93
  94 .Backup modes for Containers:
  95
  96 `stop` mode::
  97
  98 Stop the container for the duration of the backup. This potentially
  99 results in a very long downtime.
 100
 101 `suspend` mode::
 102
 103 This mode uses rsync to copy the container data to a temporary
 104 location (see option `--tmpdir`). Then the container is suspended and
 105 a second rsync copies changed files. After that, the container is
 106 started (resumed) again. This results in minimal downtime, but needs
 107 additional space to hold the container copy.
 108 +
 109 When the container is on a local file system and the target storage of
 110 the backup is an NFS server, you should set `--tmpdir` to reside on a
 111 local file system too, as this will result in a many fold performance
 112 improvement.  Use of a local `tmpdir` is also required if you want to
 113 backup a local container using ACLs in suspend mode if the backup
 114 storage is an NFS server.
 115
 116 `snapshot` mode::
 117
 118 This mode uses the snapshotting facilities of the underlying
 119 storage. First, the container will be suspended to ensure data consistency.
 120 A temporary snapshot of the container's volumes will be made and the
 121 snapshot content will be archived in a tar file. Finally, the temporary
 122 snapshot is deleted again.
 123
 124 NOTE: `snapshot` mode requires that all backed up volumes are on a storage that
 125 supports snapshots. Using the `backup=no` mount point option individual volumes
 126 can be excluded from the backup (and thus this requirement).
 127
 128 // see PVE::VZDump::LXC::prepare()
 129 NOTE: By default additional mount points besides the RootDisk mount point are
 130 not included in backups. For volume mount points you can set the *Backup* option
 131 to include the mount point in the backup. Device and bind mounts are never
 132 backed up as their content is managed outside the {pve} storage library.
 133
 134 Backup File Names
 135 -----------------
 136
 137 Newer versions of vzdump encode the guest type and the
 138 backup time into the filename, for example
 139
 140  vzdump-lxc-105-2009_10_09-11_04_43.tar
 141
 142 That way it is possible to store several backup in the same
 143 directory. The parameter `maxfiles` can be used to specify the
 144 maximum number of backups to keep.
 145
 146 Restore
 147 -------
 148
 149 The resulting archive files can be restored with the following programs.
 150
 151
 152 `pct restore`:: Container restore utility
 153
 154 `qmrestore`:: QemuServer restore utility
 155
 156 For details see the corresponding manual pages.
 157
 158 Configuration
 159 -------------
 160
 161 Global configuration is stored in `/etc/vzdump.conf`. The file uses a
 162 simple colon separated key/value format. Each line has the following
 163 format:
 164
 165  OPTION: value
 166
 167 Blank lines in the file are ignored, and lines starting with a `#`
 168 character are treated as comments and are also ignored. Values from
 169 this file are used as default, and can be overwritten on the command
 170 line.
 171
 172 We currently support the following options:
 173
 174 include::vzdump.conf.5-opts.adoc[]
 175
 176
 177 .Example `vzdump.conf` Configuration
 178 ----
 179 tmpdir: /mnt/fast_local_disk
 180 storage: my_backup_storage
 181 mode: snapshot
 182 bwlimit: 10000
 183 ----
 184
 185 Hook Scripts
 186 ------------
 187
 188 You can specify a hook script with option `--script`. This script is
 189 called at various phases of the backup process, with parameters
 190 accordingly set. You can find an example in the documentation
 191 directory (`vzdump-hook-script.pl`).
 192
 193 File Exclusions
 194 ---------------
 195
 196 NOTE: this option is only available for container backups.
 197
 198 `vzdump` skips the following files by default (disable with the option
 199 `--stdexcludes 0`)
 200
 201  /tmp/?*
 202  /var/tmp/?*
 203  /var/run/?*pid
 204
 205 You can also manually specify (additional) exclude paths, for example:
 206
 207  # vzdump 777 --exclude-path /tmp/ --exclude-path '/var/foo*'
 208
 209 (only excludes tmp directories)
 210
 211 Configuration files are also stored inside the backup archive
 212 (in `./etc/vzdump/`) and will be correctly restored.
 213
 214 Examples
 215 --------
 216
 217 Simply dump guest 777 - no snapshot, just archive the guest private area and
 218 configuration files to the default dump directory (usually
 219 `/var/lib/vz/dump/`).
 220
 221  # vzdump 777
 222
 223 Use rsync and suspend/resume to create a snapshot (minimal downtime).
 224
 225  # vzdump 777 --mode suspend
 226
 227 Backup all guest systems and send notification mails to root and admin.
 228
 229  # vzdump --all --mode suspend --mailto root --mailto admin
 230
 231 Use snapshot mode (no downtime) and non-default dump directory.
 232
 233  # vzdump 777 --dumpdir /mnt/backup --mode snapshot
 234
 235 Backup more than one guest (selectively)
 236
 237  # vzdump 101 102 103 --mailto root
 238
 239 Backup all guests excluding 101 and 102
 240
 241  # vzdump --mode suspend --exclude 101,102
 242
 243 Restore a container to a new CT 600
 244
 245  # pct restore 600 /mnt/backup/vzdump-lxc-777.tar
 246
 247 Restore a QemuServer VM to VM 601
 248
 249  # qmrestore /mnt/backup/vzdump-qemu-888.vma 601
 250
 251 Clone an existing container 101 to a new container 300 with a 4GB root
 252 file system, using pipes
 253
 254  # vzdump 101 --stdout | pct restore --rootfs 4 300 -
 255
 256
 257 ifdef::manvolnum[]
 258 include::pve-copyright.adoc[]
 259 endif::manvolnum[]
 260