[pbs-devel] [PATCH proxmox-backup] docs: notifications: adapt to latest notification system UI changes

[pbs-devel] [PATCH proxmox-backup] docs: notifications: adapt to latest notification system UI changes

[Lukas Wagner]

The latest updates to the backup-job UI completely drop the term
"Notification System" from the UI, instead we now use "Global
notification settings", which should be hopefully a bit clearer to users
with regards to what this actually means.

Some of the touched sections were slightly rephrased to improve clarity.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 docs/notifications.rst | 45 ++++++++++++++----------------------------
 1 file changed, 15 insertions(+), 30 deletions(-)

diff --git a/docs/notifications.rst b/docs/notifications.rst
index 5669dab06..190408592 100644
--- a/docs/notifications.rst
+++ b/docs/notifications.rst
@@ -7,9 +7,9 @@ Overview
 --------
 
 * Proxmox Backup Server emits :ref:`notification_events` in case of noteworthy
-  events in the system. These events are handled by the notification system. A
-  notification event has metadata, for example a timestamp, a severity level, a
-  type and other metadata fields.
+  events in the system. These events are processed based on the global
+  notification settings. Each notification event includes metadata, such as a
+  timestamp, severity level, type, and additional event-specific fields.
 * :ref:`notification_matchers` route a notification event to one or more
   notification targets. A matcher can have match rules to selectively route
   based on the metadata of a notification event.
@@ -17,12 +17,7 @@ Overview
   is routed to by a matcher. There are multiple types of target, mail-based
   (Sendmail and SMTP) and Gotify.
 
-Datastores and tape backup jobs have a configurable :ref:`notification_mode`.
-It allows you to choose between the notification system and a legacy mode for
-sending notification emails. The legacy mode is equivalent to the way
-notifications were handled before Proxmox Backup Server 3.2.
-
-The notification system can be configured in the GUI under *Configuration →
+Global notification settings can be configured in the GUI under *Configuration →
 Notifications*. The configuration is stored in :ref:`notifications.cfg` and
 :ref:`notifications_priv.cfg` - the latter contains sensitive configuration
 options such as passwords or authentication tokens for notification targets and
@@ -304,9 +299,8 @@ Metadata field       Description
 System Mail Forwarding
 ----------------------
 Certain local system daemons, such as ``smartd``, send notification emails to
-the local ``root`` user. Proxmox Backup Server will feed these mails into the
-notification system as a notification of type ``system-mail`` and with severity
-``unknown``.
+the local ``root`` user. These mails are converted into notification events
+with the type ``system-mail`` and with a severity of ``unknown``.
 
 When the email is forwarded to a sendmail target, the mail's content and
 headers are forwarded as-is. For all other targets, the system tries to extract
@@ -327,24 +321,14 @@ 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.
+* Send notifications based on the global notification settings (``notification-system``).
 
-* ``notification-system``: Use the new, flexible notification system.
+* Send notification emails via the system's ``sendmail`` command
+  (``legacy-sendmail``). Any targets or matchers from the global notification
+  settings are ignored. This mode is equivalent to the notification behavior
+  for version before Proxmox Backup Server 3.2. It might be removed in a
+  later release of Proxmox Backup Server.
 
-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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -364,8 +348,9 @@ task type via the ``notify`` option.
 
 * Never: do not send any notification at all
 
-The ``notify-user`` and ``notify`` options are ignored if ``notification-mode``
-is set to ``notification-system``.
+The ``notify-user`` and ``notify`` options are ignored when using the global
+notification settings (``notification-mode`` is set to
+``notification-system``).
 
 Overriding Notification Templates
 ---------------------------------
-- 
2.47.2



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

Re: [pbs-devel] [PATCH proxmox-backup] docs: notifications: adapt to latest notification system UI changes

[Michael Köppl]

IMO the changed sections are now more informative and better to read.
Added one suggestion inline. Did not notice any typos or grammatical errors.

Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>

On 7/23/25 13:22, Lukas Wagner wrote:
> The latest updates to the backup-job UI completely drop the term
> "Notification System" from the UI, instead we now use "Global
> notification settings", which should be hopefully a bit clearer to users
> with regards to what this actually means.
> 
> Some of the touched sections were slightly rephrased to improve clarity.
> 
> Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
> ---
>  docs/notifications.rst | 45 ++++++++++++++----------------------------
>  1 file changed, 15 insertions(+), 30 deletions(-)
> 
> diff --git a/docs/notifications.rst b/docs/notifications.rst
> index 5669dab06..190408592 100644
> --- a/docs/notifications.rst
> +++ b/docs/notifications.rst
> @@ -7,9 +7,9 @@ Overview
>  --------
>  
>  * Proxmox Backup Server emits :ref:`notification_events` in case of noteworthy
> -  events in the system. These events are handled by the notification system. A
> -  notification event has metadata, for example a timestamp, a severity level, a
> -  type and other metadata fields.
> +  events in the system. These events are processed based on the global
> +  notification settings. Each notification event includes metadata, such as a
> +  timestamp, severity level, type, and additional event-specific fields.
>  * :ref:`notification_matchers` route a notification event to one or more
>    notification targets. A matcher can have match rules to selectively route
>    based on the metadata of a notification event.
> @@ -17,12 +17,7 @@ Overview
>    is routed to by a matcher. There are multiple types of target, mail-based
>    (Sendmail and SMTP) and Gotify.
>  
> -Datastores and tape backup jobs have a configurable :ref:`notification_mode`.
> -It allows you to choose between the notification system and a legacy mode for
> -sending notification emails. The legacy mode is equivalent to the way
> -notifications were handled before Proxmox Backup Server 3.2.
> -
> -The notification system can be configured in the GUI under *Configuration →
> +Global notification settings can be configured in the GUI under *Configuration →
>  Notifications*. The configuration is stored in :ref:`notifications.cfg` and
>  :ref:`notifications_priv.cfg` - the latter contains sensitive configuration
>  options such as passwords or authentication tokens for notification targets and
> @@ -304,9 +299,8 @@ Metadata field       Description
>  System Mail Forwarding
>  ----------------------
>  Certain local system daemons, such as ``smartd``, send notification emails to
> -the local ``root`` user. Proxmox Backup Server will feed these mails into the
> -notification system as a notification of type ``system-mail`` and with severity
> -``unknown``.
> +the local ``root`` user. These mails are converted into notification events
> +with the type ``system-mail`` and with a severity of ``unknown``.
>  
>  When the email is forwarded to a sendmail target, the mail's content and
>  headers are forwarded as-is. For all other targets, the system tries to extract
> @@ -327,24 +321,14 @@ 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.
> +* Send notifications based on the global notification settings (``notification-system``).
>  
> -* ``notification-system``: Use the new, flexible notification system.
> +* Send notification emails via the system's ``sendmail`` command
> +  (``legacy-sendmail``). Any targets or matchers from the global notification
> +  settings are ignored. This mode is equivalent to the notification behavior
> +  for version before Proxmox Backup Server 3.2. It might be removed in a

Maybe something like "for Proxmox Backup Server versions before 3.2" or
"for versions of Proxmox Backup Server before 3.2" instead? Just a
suggestion, though.

> +  later release of Proxmox Backup Server.
>  
> -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
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> @@ -364,8 +348,9 @@ task type via the ``notify`` option.
>  
>  * Never: do not send any notification at all
>  
> -The ``notify-user`` and ``notify`` options are ignored if ``notification-mode``
> -is set to ``notification-system``.
> +The ``notify-user`` and ``notify`` options are ignored when using the global
> +notification settings (``notification-mode`` is set to
> +``notification-system``).
>  
>  Overriding Notification Templates
>  ---------------------------------



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

[pbs-devel] applied: [PATCH proxmox-backup] docs: notifications: adapt to latest notification system UI changes

[Thomas Lamprecht]

On Wed, 23 Jul 2025 13:22:09 +0200, Lukas Wagner wrote:
> The latest updates to the backup-job UI completely drop the term
> "Notification System" from the UI, instead we now use "Global
> notification settings", which should be hopefully a bit clearer to users
> with regards to what this actually means.
> 
> Some of the touched sections were slightly rephrased to improve clarity.
> 
> [...]

Applied, thanks!

[1/1] docs: notifications: adapt to latest notification system UI changes
      commit: 948dd68daf932688912737550073b167719bfbdb


_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

Re: [pbs-devel] [PATCH proxmox-backup] docs: notifications: adapt to latest notification system UI changes

[Lukas Wagner]

On Wed Jul 23, 2025 at 3:14 PM CEST, Michael Köppl wrote:
>> -* ``notification-system``: Use the new, flexible notification system.
>> +* Send notification emails via the system's ``sendmail`` command
>> +  (``legacy-sendmail``). Any targets or matchers from the global notification
>> +  settings are ignored. This mode is equivalent to the notification behavior
>> +  for version before Proxmox Backup Server 3.2. It might be removed in a
>
> Maybe something like "for Proxmox Backup Server versions before 3.2" or
> "for versions of Proxmox Backup Server before 3.2" instead? Just a
> suggestion, though.
>

Sent a follow-up patch to improve this, thank you for the suggestion!

https://lore.proxmox.com/pbs-devel/20250725080236.32318-1-l.wagner@proxmox.com/T/#u



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel