.Backup Storage
-Before a backup can run, a backup storage must be defined. Refer to
-the Storage documentation on how to add a storage. A backup storage
-must be a file level storage, as backups are stored as regular files.
-In most situations, using a NFS server is a good way to store backups.
-You can save those backups later to a tape drive, for off-site
-archiving.
+Before a backup can run, a backup storage must be defined. Refer to the
+xref:chapter_storage[storage documentation] on how to add a storage. It can
+either be a Proxmox Backup Server storage, where backups are stored as
+de-duplicated chunks and metadata, or a file-level storage, where backups are
+stored as regular files. Using Proxmox Backup Server on a dedicated host is
+recommended, because of its advanced features. Using an NFS server is a good
+alternative. In both cases, you might want to save those backups later to a tape
+drive, for off-site archiving.
.Scheduled Backup
-Backup jobs can be scheduled so that they are executed automatically
-on specific days and times, for selectable nodes and guest systems.
-Configuration of scheduled backups is done at the Datacenter level in
-the GUI, which will generate a cron entry in /etc/cron.d/vzdump.
+Backup jobs can be scheduled so that they are executed automatically on specific
+days and times, for selectable nodes and guest systems. See the
+xref:vzdump_jobs[Backup Jobs] section for more.
-Backup modes
+Backup Modes
------------
There are several ways to provide consistency (option `mode`),
If the backup file name doesn't end with one of the above file extensions, then
it was not compressed by vzdump.
+Backup Encryption
+-----------------
+
+For Proxmox Backup Server storages, you can optionally set up client-side
+encryption of backups, see xref:storage_pbs_encryption[the corresponding section.]
+
+[[vzdump_jobs]]
+Backup Jobs
+-----------
+
+Besides triggering a backup manually, you can also setup periodic jobs that
+backup all, or a selection of virtual guest to a storage. You can manage the
+jobs in the UI under 'Datacenter' -> 'Backup' or via the `/cluster/backup` API
+endpoint. Both will generate job entries in `/etc/pve/jobs.cfg`, which are
+parsed and executed by the `pvescheduler` daemon.
+
+A job is either configured for all cluster nodes or a specific node, and is
+executed according to a given schedule. The format for the schedule is very
+similar to `systemd` calendar events, see the
+xref:chapter_calendar_events[calendar events] section for details. The
+'Schedule' field in the UI can be freely edited, and it contains several
+examples that can be used as a starting point in its drop-down list.
+
+You can configure job-specific xref:vzdump_retention[retention options]
+overriding those from the storage or node configuration, as well as a
+xref:vzdump_notes[template for notes] for additional information to be saved
+together with the backup.
+
+Since scheduled backups miss their execution when the host was offline or the
+pvescheduler was disabled during the scheduled time, it is possible to configure
+the behaviour for catching up. By enabling the `Repeat missed` option
+(`repeat-missed` in the config), you can tell the scheduler that it should run
+missed jobs as soon as possible.
+
+There are a few settings for tuning backup performance not exposed in the UI.
+The most notable is `bwlimit` for limiting IO bandwidth. The amount of threads
+used for the compressor can be controlled with the `pigz` (replacing `gzip`),
+respectively, `zstd` setting. Furthermore, there are `ionice` and, as part of
+the `performance` setting, `max-workers` (affects VM backups only). See the
+xref:vzdump_configuration[configuration options] for details.
[[vzdump_retention]]
Backup Retention
`keep-last` or, in case `maxfiles` was `0` for unlimited retention, by
`keep-all`.
+
+Prune Simulator
+~~~~~~~~~~~~~~~
+
+You can use the https://pbs.proxmox.com/docs/prune-simulator[prune simulator
+of the Proxmox Backup Server documentation] to explore the effect of different
+retention options with various backup schedules.
+
Retention Settings Example
~~~~~~~~~~~~~~~~~~~~~~~~~~
by your environment; you can always reduce it if you find it is unnecessarily
high, but you cannot recreate backups once they have been removed.
+[[vzdump_protection]]
+Backup Protection
+-----------------
+
+You can mark a backup as `protected` to prevent its removal. Attempting to
+remove a protected backup via {pve}'s UI, CLI or API will fail. However, this
+is enforced by {pve} and not the file-system, that means that a manual removal
+of a backup file itself is still possible for anyone with write access to the
+underlying backup storage.
+
+NOTE: Protected backups are ignored by pruning and do not count towards the
+retention settings.
+
+For filesystem-based storages, the protection is implemented via a sentinel file
+`<backup-name>.protected`. For Proxmox Backup Server, it is handled on the
+server side (available since Proxmox Backup Server version 2.1).
+
+Use the storage option `max-protected-backups` to control how many protected
+backups per guest are allowed on the storage. Use `-1` for unlimited. The
+default is unlimited for users with `Datastore.Allocate` privilege and `5` for
+other users.
+
+[[vzdump_notes]]
+Backup Notes
+------------
+
+You can add notes to backups using the 'Edit Notes' button in the UI or via the
+storage content API.
+
+It is also possible to specify a template for generating notes dynamically for
+a backup job and for manual backup. The template string can contain variables,
+surrounded by two curly braces, which will be replaced by the corresponding
+value when the backup is executed.
+
+Currently supported are:
+
+* `{{cluster}}` the cluster name, if any
+* `{{guestname}}` the virtual guest's assigned name
+* `{{node}}` the host name of the node the backup is being created
+* `{{vmid}}` the numerical VMID of the guest
+
+When specified via API or CLI, it needs to be a single line, where newline and
+backslash need to be escaped as literal `\n` and `\\` respectively.
+
[[vzdump_restore]]
Restore
-------
# pvesm set STORAGEID --bwlimit restore=KIBs
----
+Live-Restore
+~~~~~~~~~~~~
+
+Restoring a large backup can take a long time, in which a guest is still
+unavailable. For VM backups stored on a Proxmox Backup Server, this wait
+time can be mitigated using the live-restore option.
+
+Enabling live-restore via either the checkbox in the GUI or the `--live-restore`
+argument of `qmrestore` causes the VM to start as soon as the restore
+begins. Data is copied in the background, prioritizing chunks that the VM is
+actively accessing.
+
+Note that this comes with two caveats:
+
+* During live-restore, the VM will operate with limited disk read speeds, as
+ data has to be loaded from the backup server (once loaded, it is immediately
+ available on the destination storage however, so accessing data twice only
+ incurs the penalty the first time). Write speeds are largely unaffected.
+* If the live-restore fails for any reason, the VM will be left in an
+ undefined state - that is, not all data might have been copied from the
+ backup, and it is _most likely_ not possible to keep any data that was written
+ during the failed restore operation.
+
+This mode of operation is especially useful for large VMs, where only a small
+amount of data is required for initial operation, e.g. web servers - once the OS
+and necessary services have been started, the VM is operational, while the
+background task continues copying seldom used data.
+
+Single File Restore
+~~~~~~~~~~~~~~~~~~~
+
+The 'File Restore' button in the 'Backups' tab of the storage GUI can be used to
+open a file browser directly on the data contained in a backup. This feature
+is only available for backups on a Proxmox Backup Server.
+
+For containers, the first layer of the file tree shows all included 'pxar'
+archives, which can be opened and browsed freely. For VMs, the first layer shows
+contained drive images, which can be opened to reveal a list of supported
+storage technologies found on the drive. In the most basic case, this will be an
+entry called 'part', representing a partition table, which contains entries for
+each partition found on the drive. Note that for VMs, not all data might be
+accessible (unsupported guest file systems, storage technologies, etc...).
+
+Files and directories can be downloaded using the 'Download' button, the latter
+being compressed into a zip archive on the fly.
+
+To enable secure access to VM images, which might contain untrusted data, a
+temporary VM (not visible as a guest) is started. This does not mean that data
+downloaded from such an archive is inherently safe, but it avoids exposing the
+hypervisor system to danger. The VM will stop itself after a timeout. This
+entire process happens transparently from a user's point of view.
+
[[vzdump_configuration]]
Configuration
-------------
# vzdump 777 --exclude-path /tmp/ --exclude-path '/var/foo*'
-(only excludes tmp directories)
+excludes the directory `/tmp/` and any file or directory named `/var/foo`,
+`/var/foobar`, and so on.
+
+Paths that do not start with a `/` are not anchored to the container's root,
+but will match relative to any subdirectory. For example:
+
+ # vzdump 777 --exclude-path bar
+
+excludes any file or directory named `/bar`, `/var/bar`, `/var/foo/bar`, and
+so on, but not `/bar2`.
Configuration files are also stored inside the backup archive
(in `./etc/vzdump/`) and will be correctly restored.
projects / pve-docs.git / blobdiff