vzdump.adoc

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