vzdump.adoc

   1 ifdef::manvolnum[]
   2 PVE(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
  29 ifdef::wiki[]
  30 :pve-toplevel:
  31 endif::wiki[]
  32
  33 Backups are a requirements for any sensible IT deployment, and {pve}
  34 provides a fully integrated solution, using the capabilities of each
  35 storage and each guest system type. This allows the system
  36 administrator to fine tune via the `mode` option between consistency
  37 of the backups and downtime of the guest system.
  38
  39 {pve} backups are always full backups - containing the VM/CT
  40 configuration and all data.  Backups can be started via the GUI or via
  41 the `vzdump` command line tool.
  42
  43 .Backup Storage
  44
  45 Before a backup can run, a backup storage must be defined. Refer to
  46 the Storage documentation on how to add a storage. A backup storage
  47 must be a file level storage, as backups are stored as regular files.
  48 In most situations, using a NFS server is a good way to store backups.
  49 You can save those backups later to a tape drive, for off-site
  50 archiving.
  51
  52 .Scheduled Backup
  53
  54 Backup jobs can be scheduled so that they are executed automatically
  55 on specific days and times, for selectable nodes and guest systems.
  56 Configuration of scheduled backups is done at the Datacenter level in
  57 the GUI, which will generate a cron entry in /etc/cron.d/vzdump.
  58
  59 Backup modes
  60 ------------
  61
  62 There are several ways to provide consistency (option `mode`),
  63 depending on the guest type.
  64
  65 .Backup modes for VMs:
  66
  67 `stop` mode::
  68
  69 This mode provides the highest consistency of the backup, at the cost
  70 of a downtime in the VM operation.  It works by executing an orderly
  71 shutdown of the VM, and then runs a background Qemu process to backup
  72 the VM data. After the backup is complete, the Qemu process resumes
  73 the VM to full operation mode if it was previously running.
  74
  75 `suspend` mode::
  76
  77 This mode is provided for compatibility reason, and suspends the VM
  78 before calling the `snapshot` mode. Since suspending the VM results in
  79 a longer downtime and does not necessarily improve the data
  80 consistency, the use of the `snapshot` mode is recommended instead.
  81
  82 `snapshot` mode::
  83
  84 This mode provides the lowest operation downtime, at the cost of a
  85 small inconstancy risk.  It works by performing a Proxmox VE live
  86 backup, in which data blocks are copied while the VM is running. If the
  87 guest agent is enabled (`agent: 1`) and running, it calls
  88 `guest-fsfreeze-freeze` and `guest-fsfreeze-thaw` to improve
  89 consistency.
  90
  91 A technical overview of the Proxmox VE live backup for QemuServer can
  92 be found online
  93 https://git.proxmox.com/?p=pve-qemu-kvm.git;a=blob;f=backup.txt[here].
  94
  95 NOTE: Proxmox VE live backup provides snapshot-like semantics on any
  96 storage type. It does not require that the underlying storage supports
  97 snapshots.
  98
  99 .Backup modes for Containers:
 100
 101 `stop` mode::
 102
 103 Stop the container for the duration of the backup. This potentially
 104 results in a very long downtime.
 105
 106 `suspend` mode::
 107
 108 This mode uses rsync to copy the container data to a temporary
 109 location (see option `--tmpdir`). Then the container is suspended and
 110 a second rsync copies changed files. After that, the container is
 111 started (resumed) again. This results in minimal downtime, but needs
 112 additional space to hold the container copy.
 113 +
 114 When the container is on a local file system and the target storage of
 115 the backup is an NFS server, you should set `--tmpdir` to reside on a
 116 local file system too, as this will result in a many fold performance
 117 improvement.  Use of a local `tmpdir` is also required if you want to
 118 backup a local container using ACLs in suspend mode if the backup
 119 storage is an NFS server.
 120
 121 `snapshot` mode::
 122
 123 This mode uses the snapshotting facilities of the underlying
 124 storage. First, the container will be suspended to ensure data consistency.
 125 A temporary snapshot of the container's volumes will be made and the
 126 snapshot content will be archived in a tar file. Finally, the temporary
 127 snapshot is deleted again.
 128
 129 NOTE: `snapshot` mode requires that all backed up volumes are on a storage that
 130 supports snapshots. Using the `backup=no` mount point option individual volumes
 131 can be excluded from the backup (and thus this requirement).
 132
 133 NOTE: bind and device mount points are skipped during backup operations, like
 134 volume mount points with the backup option disabled.
 135
 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