notifications: add note regarding when 'job-id' is set for backups

[pve-docs.git] / vzdump.1-synopsis.adoc

diff --git a/vzdump.1-synopsis.adoc b/vzdump.1-synopsis.adoc
index 6036647866aafa4f58c93f0a8ecf706b9863fafe..78d118d583e62dc886f8e30bc13b0a3f7820603b 100644 (file)
--- a/vzdump.1-synopsis.adoc
+++ b/vzdump.1-synopsis.adoc
@@ -14,7 +14,7 @@ Backup all known guest systems on this host.
 
 `--bwlimit` `<integer> (0 - N)` ('default =' `0`)::
 
 
 `--bwlimit` `<integer> (0 - N)` ('default =' `0`)::
 

-Limit I/O bandwidth (KBytes per second).
+Limit I/O bandwidth (in KiB/s).

 
 `--compress` `<0 | 1 | gzip | lzo | zstd>` ('default =' `0`)::
 
 
 `--compress` `<0 | 1 | gzip | lzo | zstd>` ('default =' `0`)::
 


@@ -28,13 +28,21 @@ Store resulting files to specified directory.
 
 Exclude specified guest systems (assumes --all)
 
 
 Exclude specified guest systems (assumes --all)
 

-`--exclude-path` `<string>` ::
+`--exclude-path` `<array>` ::

 
 

-Exclude certain files/directories (shell globs).
+Exclude certain files/directories (shell globs). Paths starting with '/' are anchored to the container's root, other paths match relative to each subdirectory.
+
+`--fleecing` `[[enabled=]<1|0>] [,storage=<storage ID>]` ::
+
+Options for backup fleecing (VM only).

 
 `--ionice` `<integer> (0 - 8)` ('default =' `7`)::
 
 
 `--ionice` `<integer> (0 - 8)` ('default =' `7`)::
 

-Set CFQ ionice priority.
+Set IO priority when using the BFQ scheduler. For snapshot and suspend mode backups of VMs, this only affects the compressor. A value of 8 means the idle priority is used, otherwise the best-effort priority is used with the specified value.
+
+`--job-id` `<string>` ::
+
+The ID of the backup job. If set, the 'backup-job' metadata field of the backup notification will be set to this value. Only root@pam can set this parameter.

 
 `--lockwait` `<integer> (0 - N)` ('default =' `180`)::
 
 
 `--lockwait` `<integer> (0 - N)` ('default =' `180`)::
 


@@ -42,15 +50,15 @@ Maximal time to wait for the global lock (minutes).
 
 `--mailnotification` `<always | failure>` ('default =' `always`)::
 
 
 `--mailnotification` `<always | failure>` ('default =' `always`)::
 

-Specify when to send an email
+Deprecated: use notification targets/matchers instead. Specify when to send a notification mail

 
 `--mailto` `<string>` ::
 
 
 `--mailto` `<string>` ::
 

-Comma-separated list of email addresses that should receive email notifications.
+Deprecated: Use notification targets/matchers instead. Comma-separated list of email addresses or users that should receive email notifications.

 
 

-`--maxfiles` `<integer> (1 - N)` ('default =' `1`)::
+`--maxfiles` `<integer> (1 - N)` ::

 
 

-Maximal number of backup files per guest system.
+Deprecated: use 'prune-backups' instead. Maximal number of backup files per guest system.

 
 `--mode` `<snapshot | stop | suspend>` ('default =' `snapshot`)::
 
 
 `--mode` `<snapshot | stop | suspend>` ('default =' `snapshot`)::
 


@@ -60,6 +68,32 @@ Backup mode.
 
 Only run if executed on this node.
 
 
 Only run if executed on this node.
 

+`--notes-template` `<string>` ::
+
+Template string for generating notes for the backup(s). It can contain variables which will be replaced by their values. Currently supported are \{\{cluster\}\}, \{\{guestname\}\}, \{\{node\}\}, and \{\{vmid\}\}, but more might be added in the future. Needs to be a single line, newline and backslash need to be escaped as '\n' and '\\' respectively.
++
+NOTE: Requires option(s): `storage`
+
+`--notification-mode` `<auto | legacy-sendmail | notification-system>` ('default =' `auto`)::
+
+Determine which notification system to use. If set to 'legacy-sendmail', vzdump will consider the mailto/mailnotification parameters and send emails to the specified address(es) via the 'sendmail' command. If set to 'notification-system', a notification will be sent via PVE's notification system, and the mailto and mailnotification will be ignored. If set to 'auto' (default setting), an email will be sent if mailto is set, and the notification system will be used if not.
+
+`--notification-policy` `<always | failure | never>` ('default =' `always`)::
+
+Deprecated: Do not use
+
+`--notification-target` `<string>` ::
+
+Deprecated: Do not use
+
+`--pbs-change-detection-mode` `<data | legacy | metadata>` ::
+
+PBS mode used to detect file changes and switch encoding. NOTE: `data` and `metadata` modes are experimental. format for container backups.
+
+`--performance` `[max-workers=<integer>] [,pbs-entries-max=<integer>]` ::
+
+Other performance-related settings.
+

 `--pigz` `<integer>` ('default =' `0`)::
 
 Use pigz instead of gzip when N>0. N=1 uses half of cores, N>1 uses N as thread count.
 `--pigz` `<integer>` ('default =' `0`)::
 
 Use pigz instead of gzip when N>0. N=1 uses half of cores, N>1 uses N as thread count.


@@ -68,7 +102,13 @@ Use pigz instead of gzip when N>0. N=1 uses half of cores, N>1 uses N as thread
 
 Backup all known guest systems included in the specified pool.
 
 
 Backup all known guest systems included in the specified pool.
 

-`--prune-backups` `[keep-all=<1|0>] [,keep-daily=<N>] [,keep-hourly=<N>] [,keep-last=<N>] [,keep-monthly=<N>] [,keep-weekly=<N>] [,keep-yearly=<N>]` ::
+`--protected` `<boolean>` ::
+
+If true, mark backup(s) as protected.
++
+NOTE: Requires option(s): `storage`
+
+`--prune-backups` `[keep-all=<1|0>] [,keep-daily=<N>] [,keep-hourly=<N>] [,keep-last=<N>] [,keep-monthly=<N>] [,keep-weekly=<N>] [,keep-yearly=<N>]` ('default =' `keep-all=1`)::

 
 Use these retention options instead of those from the storage configuration.
 
 
 Use these retention options instead of those from the storage configuration.
 


@@ -78,16 +118,12 @@ Be quiet.
 
 `--remove` `<boolean>` ('default =' `1`)::
 
 
 `--remove` `<boolean>` ('default =' `1`)::
 

-Remove old backup files if there are more than 'maxfiles' backup files.
+Prune older backups according to 'prune-backups'.

 
 `--script` `<string>` ::
 
 Use specified hook script.
 
 
 `--script` `<string>` ::
 
 Use specified hook script.
 

-`--size` `<integer> (500 - N)` ('default =' `1024`)::
-
-Unused, will be removed in a future release.
-

 `--stdexcludes` `<boolean>` ('default =' `1`)::
 
 Exclude temporary files and logs.
 `--stdexcludes` `<boolean>` ('default =' `1`)::
 
 Exclude temporary files and logs.


@@ -104,7 +140,7 @@ Stop running backup jobs on this host.
 
 Maximal time to wait until a guest system is stopped (minutes).
 
 
 Maximal time to wait until a guest system is stopped (minutes).
 

-`--storage` `<string>` ::
+`--storage` `<storage ID>` ::

 
 Store resulting file to this storage.
 
 
 Store resulting file to this storage.
 


@@ -114,5 +150,5 @@ Store temporary files to specified directory.
 
 `--zstd` `<integer>` ('default =' `1`)::
 
 
 `--zstd` `<integer>` ('default =' `1`)::
 

-Zstd threads. N=0 uses half of the available cores, N>0 uses N as thread count.
+Zstd threads. N=0 uses half of the available cores, if N is set to a value bigger than 0, N is used as thread count.