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

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

[Lukas Wagner]

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 <l.wagner@proxmox.com>
Reviewed-by: Gabriel Goller <g.goller@proxmox.com>
---
 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 6dbb6941..4bb135e4 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 4f9b01b7..7bc3db82 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 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
-- 
2.39.2



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

[pbs-devel] [PATCH proxmox-backup v3 2/3] docs: notifications: rewrite overview for more clarity

[Lukas Wagner]

Also link to the following subsections where applicable.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 docs/configuration-files.rst |  2 ++
 docs/notifications.rst       | 47 +++++++++++++++---------------------
 2 files changed, 21 insertions(+), 28 deletions(-)

diff --git a/docs/configuration-files.rst b/docs/configuration-files.rst
index ee8367e5..b296e119 100644
--- a/docs/configuration-files.rst
+++ b/docs/configuration-files.rst
@@ -83,6 +83,8 @@ Options
 
 .. include:: config/notifications/config.rst
 
+.. _notifications_priv.cfg:
+
 ``notifications-priv.cfg``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/notifications.rst b/docs/notifications.rst
index 7bc3db82..4ba8db86 100644
--- a/docs/notifications.rst
+++ b/docs/notifications.rst
@@ -6,39 +6,30 @@ Notifications
 Overview
 --------
 
-Proxmox Backup Server will send notifications if case of noteworthy
-events.
-
-There are a number of different :ref:`Notification Events`,
-each with their own set of metadata fields that can be used in
-notification matchers.
-
-A notification matcher determines *which* notifications shall be sent *where*.
-A matcher has *match rules*, that can be used to
-match on certain notification properties (e.g. timestamp, severity,
-metadata fields).
-If a matcher matches a notification, the notification will be routed
-to a configured set of notification targets.
-
-A notification target is an abstraction for a destination where a
-notification should be sent to - for instance a Gotify server instance,
-or a set of email addresses.
-There are multiple types of notification targets, including
-sendmail, which uses the system's sendmail command to send emails,
-or gotify, which sends a notification to a Gotify instance.
+* 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.
+* :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.
+* :ref:`notification_targets` are a destination to which a notification event
+  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 -> Notifications``. The configuration is stored in
-``/etc/proxmox-backup/notifications.cfg`` and
-``/etc/proxmox-backup/notifications-priv.cfg`` -
+*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
 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:
 
 Notification Targets
 --------------------
@@ -156,7 +147,7 @@ Examples:
 The following severities are in use:
 ``info``, ``notice``, ``warning``, ``error``, ``unknown``.
 
-.. _Notification Events:
+.. _notification_events:
 
 Notification Events
 -------------------
-- 
2.39.2



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

[pbs-devel] [PATCH proxmox-backup v3 3/3] ui: datastore options: link to 'notification-mode' section

[Lukas Wagner]

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 www/window/NotifyOptions.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/www/window/NotifyOptions.js b/www/window/NotifyOptions.js
index 57e8ba44..6590df4a 100644
--- a/www/window/NotifyOptions.js
+++ b/www/window/NotifyOptions.js
@@ -27,7 +27,7 @@ Ext.define('PBS.window.NotifyOptions', {
     xtype: 'pbsNotifyOptionEdit',
     mixins: ['Proxmox.Mixin.CBind'],
 
-    onlineHelp: 'maintenance_notification',
+    onlineHelp: 'notification_mode',
 
     user: undefined,
     tokenname: undefined,
-- 
2.39.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 v3 1/3] docs: document notification-mode and merge old notification section

[Lukas Wagner]

ping...

On  2024-04-26 13:23, Lukas Wagner wrote:
> 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 <l.wagner@proxmox.com>
> Reviewed-by: Gabriel Goller <g.goller@proxmox.com>
> ---
>  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 6dbb6941..4bb135e4 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 4f9b01b7..7bc3db82 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 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

-- 
- Lukas


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

[pbs-devel] applied-series: [PATCH proxmox-backup v3 1/3] docs: document notification-mode and merge old notification section

[Thomas Lamprecht]

Am 26/04/2024 um 13:23 schrieb Lukas Wagner:
> 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 <l.wagner@proxmox.com>
> Reviewed-by: Gabriel Goller <g.goller@proxmox.com>
> ---
>  docs/maintenance.rst   | 20 ++--------------
>  docs/notifications.rst | 53 ++++++++++++++++++++++++++++++++++++++++++
>  docs/storage.rst       |  4 ++--
>  3 files changed, 57 insertions(+), 20 deletions(-)
> 
>

applied all three patches, thanks!

But I could not find any changelog for v2 -> v3, I'd appreciate one the
next time.


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