vzdump: minimally rework backup notes, mostly formatting

[pve-docs.git] / vzdump.adoc

diff --git a/vzdump.adoc b/vzdump.adoc
index 96ae70dff319d1436ad95d48363302567bf561bb..544ed5e0d4541d4fd986ce9c5e1c31779c34dc89 100644 (file)
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -284,6 +284,50 @@ We recommend that you use a higher retention period than is minimally required
 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
 -------