[PATCH pve-docs v2 4/4] vzdump: document backup retry options

[Jakob Klocker <j.klocker@proxmox.com>]

Describe the new `error-behavior` and `max-retries` options, the
exponential backoff between attempts, and which failures are retried.

Signed-off-by: Jakob Klocker <j.klocker@proxmox.com>
---
 vzdump.adoc | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/vzdump.adoc b/vzdump.adoc
index 44db027..872ff16 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -308,6 +308,55 @@ the `performance` setting, `max-workers` (affects VM backups only) and
 `pbs-entries-max` (affects container backups only). See the
 xref:vzdump_configuration[configuration options] for details.
 
+[[vzdump_retry]]
+Backup Retries
+--------------
+
+The backup of a single guest can fail because of a temporary problem, for
+example when the guest is locked by another operation, or when the connection
+to the backup server is interrupted during the backup. To avoid a failed backup
+in such cases, the `error-behavior` option allows a job to retry failed guest
+backups automatically:
+
+`ignore` ::
+Does not retry failed guests. This is the default.
+
+`retry` ::
+Defers failed guests until all other guests have been processed and then
+retries them in the order in which they failed.
+
+`retry-immediately` ::
+Retries a failed guest right away, before continuing with the next guest.
+
+The `max-retries` option (1 to 10, default 5) limits how often a guest is
+retried. Between attempts, the job uses exponential backoff: the delay starts
+at 30 seconds, doubles with every retry and is capped at 30 minutes. With
+`retry`, the delay is counted from the last failed attempt of that guest, so
+other guests can be retried in the meantime.
+
+If a retry succeeds, the guest is reported as successful in the notification
+and does not count as an error. If the last retry fails as well, the job
+finishes with errors. The task log of the guest contains all attempts.
+
+For example, to back up three guests and retry each failed guest at most three
+times at the end of the job, run:
+
+ # vzdump 101 102 103 --error-behavior retry --max-retries 3
+
+In the UI, the options for backup jobs can be set in the 'Advanced' tab of the
+backup job window. For a manual backup, they are available directly in the
+backup window ('Backup now'). For new backup jobs and manual backups, the UI
+preselects `retry` with 5 retries. The manual backup window only offers `retry`
+and `ignore`, as both retry strategies behave the same for a single guest.
+
+Only failures while backing up a guest are retried. Errors that prevent the
+whole job from starting, for example a backup storage that cannot be activated,
+are not retried.
+
+NOTE: Retries can make a backup job take considerably longer. With the default
+of 5 retries, the delays alone add up to more than 15 minutes for a guest that
+keeps failing, and about 2.5 hours with the maximum of 10 retries.
+
 [[vzdump_retention]]
 Backup Retention
 ----------------
-- 
2.47.3