[pbs-devel] [PATCH proxmox-backup 1/2] docs: document notification-mode and merge old notification section

[Gabriel Goller]

On Thu Apr 25, 2024 at 2:30 PM CEST, Lukas Wagner wrote:
> diff --git a/docs/notifications.rst b/docs/notifications.rst
> index 4f9b01b7..e5ec74b7 100644
> --- a/docs/notifications.rst
> +++ b/docs/notifications.rst
> @@ -211,3 +211,45 @@ Permissions
>  In order to modify/view the configuration for notification targets,
>  the ``Sys.Modify/Sys.Audit`` permissions are required for the
>  ``/system/notifications`` ACL node.
> +
> +.. _notification_mode:
> +
> +Notification Mode
> +-----------------
> +
> +To ensure a smooth transition from the old, purely email based system to
> +the new configurable notification system introduced in Proxmox Backup Server 3.2,
> +datastore options, tape backup jobs and tape restore jobs gain a new option:
> +``notification-mode``. This option must be set to ``notification-system``
> +to opt in to the new notification system. If the option is not set, or
> +set to ``legacy-sendmail``, Proxmox Backup Server will use the old
> +system.
> +
> +Starting with Proxmox Backup Server 3.2, a datastore created in the UI will
> +automatically opt in to the new notification system. If the datastore is created
> +via the API or the ``proxmox-backup-manager`` CLI, the ``notification-system``
> +option has to be set explicitly.
> +
> +The ``legacy-sendmail`` mode will be deprecated and removed in a later
> +release of Proxmox Backup Server.
> +
> +Settings for ``legacy-sendmail`` notification mode
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +If ``notification-mode`` is set to ``legacy-sendmail``,  Proxmox Backup Server
> +will send notification emails via the system's ``sendmail`` command to the email
> +address configured for the user set in the ``notify-user`` option
> +(falling back to ``root at pam`` if not set)

A period is missing in the last sentence above.

> +
> +For datastores, you can also change the level of notification received per task

'notification' -> 'notifications'

> +type via the ``notify`` option.
> +
> +* Always: send a notification for any scheduled task, independent of the
> +  outcome
> +
> +* Errors: send a notification for any scheduled task that results in an error
> +
> +* Never: do not send any notification at all
> +
> +The ``notify-user`` and ``notify`` options are ignored if ``notification-mode``
> +is set to ``notification-system``.
> diff --git a/docs/storage.rst b/docs/storage.rst
> index 4444c423..f1e15d52 100644
> --- a/docs/storage.rst
> +++ b/docs/storage.rst
> @@ -314,7 +314,7 @@ Options
>  
>  There are a few per-datastore options:
>  
> -* :ref:`Notifications <maintenance_notification>`
> +* :ref:`Notification mode and legacy notification settings <notification_mode>`
>  * :ref:`Maintenance Mode <maintenance_mode>`
>  * Verification of incoming backups
>  
> @@ -419,7 +419,7 @@ remote-source to avoid that an attacker that took over the source can cause
>  deletions of backups on the target hosts.
>  If the source-host became victim of a ransomware attack, there is a good chance
>  that sync jobs will fail, triggering an :ref:`error notification
> -<maintenance_notification>`.
> +<Notification Events>`.
>  
>  It is also possible to create :ref:`tape backups <tape_backup>` as a second
>  storage medium. This way, you get an additional copy of your data on a

Otherwise this looks good!

Reviewed-by: Gabriel Goller <g.goller at proxmox.com>