From 4ce196212409f3ef87ffb64f19c7beba9024d428 Mon Sep 17 00:00:00 2001 From: Lukas Wagner Date: Fri, 26 Apr 2024 13:23:33 +0200 Subject: [PATCH] docs: document notification-mode and merge old notification section This new section describes how the notification-mode parameter works. The section also contains also parts of the old notification section from the maintenance chapter, reusing the description of the `notify` and `notify-user` parameters. Signed-off-by: Lukas Wagner Reviewed-by: Gabriel Goller --- docs/maintenance.rst | 20 ++-------------- docs/notifications.rst | 53 ++++++++++++++++++++++++++++++++++++++++++ docs/storage.rst | 4 ++-- 3 files changed, 57 insertions(+), 20 deletions(-) diff --git a/docs/maintenance.rst b/docs/maintenance.rst index 6dbb6941c..4bb135e4e 100644 --- a/docs/maintenance.rst +++ b/docs/maintenance.rst @@ -277,26 +277,10 @@ the **Actions** column in the table. Notifications ------------- -Proxmox Backup Server can send you notification emails about automatically +Proxmox Backup Server can send you notifications about automatically scheduled verification, garbage-collection and synchronization tasks results. -By default, notifications are sent to the email address configured for the -`root@pam` user. You can instead set this user for each datastore. - -.. image:: images/screenshots/pbs-gui-datastore-options.png - :target: _images/pbs-gui-datastore-options.png - :align: right - :alt: Datastore Options - -You can also change the level of notification received per task type, the -following options are available: - -* 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 +Refer to the :ref:`notifications` chapter for more details. .. _maintenance_mode: diff --git a/docs/notifications.rst b/docs/notifications.rst index 4f9b01b74..7bc3db829 100644 --- a/docs/notifications.rst +++ b/docs/notifications.rst @@ -1,3 +1,5 @@ +.. _notifications: + Notifications ============= @@ -33,6 +35,10 @@ the latter contains sensitive configuration options such as passwords or authentication tokens for notification targets and can only be read by ``root``. +Datastores and tape backup jobs have a configurable :ref:`notification_mode`, +which allows you to choose between the notification system and a legacy mode +for sending notification emails. + Notification Targets -------------------- @@ -211,3 +217,50 @@ 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 +----------------- +Datastores and tape backup/restore job configuration have a ``notification-mode`` +option which can have one of two values: + +* ``legacy-sendmail``: Send notification emails via the system's ``sendmail`` command. + The notification system will be bypassed and any configured targets/matchers will be ignored. + This mode is equivalent to the notification behavior for version before + Proxmox Backup Server 3.2. + +* ``notification-system``: Use the new, flexible notification system. + +If the ``notification-mode`` option is not set, Proxmox Backup Server will default +to ``legacy-sendmail``. + +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-mode`` +option has to be set explicitly to ``notification-system`` if the +notification system shall be used. + +The ``legacy-sendmail`` mode might be 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@pam`` if not set). + +For datastores, you can also change the level of notifications received per task +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 4444c4230..f1e15d522 100644 --- a/docs/storage.rst +++ b/docs/storage.rst @@ -314,7 +314,7 @@ Options There are a few per-datastore options: -* :ref:`Notifications ` +* :ref:`Notification mode and legacy notification settings ` * :ref:`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 -`. +`. It is also possible to create :ref:`tape backups ` as a second storage medium. This way, you get an additional copy of your data on a