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

[pbs-devel] [PATCH proxmox-backup v2 1/2] 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>
---
v2: fixed spelling, thx @Gabriel

 docs/maintenance.rst   | 26 --------------------------
 docs/notifications.rst | 42 ++++++++++++++++++++++++++++++++++++++++++
 docs/storage.rst       |  4 ++--
 3 files changed, 44 insertions(+), 28 deletions(-)

diff --git a/docs/maintenance.rst b/docs/maintenance.rst
index 6dbb6941..1dd17ad0 100644
--- a/docs/maintenance.rst
+++ b/docs/maintenance.rst
@@ -272,32 +272,6 @@ datastores, backup groups or snapshots. To do this, navigate to the **Content**
 tab of the datastore and either click *Verify All* or select the *V.* icon from
 the **Actions** column in the table.
 
-.. _maintenance_notification:
-
-Notifications
--------------
-
-Proxmox Backup Server can send you notification emails 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
-
 .. _maintenance_mode:
 
 Maintenance Mode
diff --git a/docs/notifications.rst b/docs/notifications.rst
index 4f9b01b7..d2bc573f 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@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 v2 2/2] 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 v2 1/2] docs: document notification-mode and merge old notification section

[Thomas Lamprecht]

Am 25/04/2024 um 14:48 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>
> ---
> v2: fixed spelling, thx @Gabriel
> 
>  docs/maintenance.rst   | 26 --------------------------
>  docs/notifications.rst | 42 ++++++++++++++++++++++++++++++++++++++++++
>  docs/storage.rst       |  4 ++--
>  3 files changed, 44 insertions(+), 28 deletions(-)
> 
> diff --git a/docs/maintenance.rst b/docs/maintenance.rst
> index 6dbb6941..1dd17ad0 100644
> --- a/docs/maintenance.rst
> +++ b/docs/maintenance.rst
> @@ -272,32 +272,6 @@ datastores, backup groups or snapshots. To do this, navigate to the **Content**
>  tab of the datastore and either click *Verify All* or select the *V.* icon from
>  the **Actions** column in the table.
>  
> -.. _maintenance_notification:
> -
> -Notifications
> --------------


This is linked a few times in the forum, and so I'd like to avoid breaking the
anchor. Can we possibly keep this section in a minimal form that states that
this is now legacy and one should check out the new notification system, with
a link to that one.

I'd do so at least for the current major release. Not a huge thing, but IMO to
cheap to not do.

> -
> -Proxmox Backup Server can send you notification emails 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
> -
>  .. _maintenance_mode:
>  
>  Maintenance Mode
> diff --git a/docs/notifications.rst b/docs/notifications.rst
> index 4f9b01b7..d2bc573f 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.

Maybe starting out with something like "There exist two notifications modes:"
and then using bulletin points for the two notification modes would make this
a bit easier to read. As the sentence feels a tiny bit convoluted to me – I
know because, I write "worse" ones by default all the time ;-)

btw. a short section in the PBS 2 to 3 upgrade guide would be nice too, could
consist only of a short sentence for context and then just link to this one
here, once applied.

> +
> +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.

Not sure if we really do a hard-removal, or at least how soon that would be.
S o maybe s/removed/might be removed/ to hold out our options and avoid making
(responsible) users stumbling upon this might think "I must switch now or
things break".


_______________________________________________
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 v2 1/2] docs: document notification-mode and merge old notification section

[Lukas Wagner]

On  2024-04-26 09:18, Thomas Lamprecht wrote:
>>  
>> -.. _maintenance_notification:
>> -
>> -Notifications
>> --------------
> 
> 
> This is linked a few times in the forum, and so I'd like to avoid breaking the
> anchor. Can we possibly keep this section in a minimal form that states that
> this is now legacy and one should check out the new notification system, with
> a link to that one.
> 
> I'd do so at least for the current major release. Not a huge thing, but IMO to
> cheap to not do.
> 

Ah yeah, that makes sense for course - did not think about that ;)
>> -
>> -Proxmox Backup Server can send you notification emails 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
>> -
>>  .. _maintenance_mode:
>>  
>>  Maintenance Mode
>> diff --git a/docs/notifications.rst b/docs/notifications.rst
>> index 4f9b01b7..d2bc573f 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.
> 
> Maybe starting out with something like "There exist two notifications modes:"
> and then using bulletin points for the two notification modes would make this
> a bit easier to read. As the sentence feels a tiny bit convoluted to me – I
> know because, I write "worse" ones by default all the time ;-)

Coming up with way too convoluted sentences in English seems to be the eternal curse
of native German speakers, hehe. Will try to simplify it a bit, thanks!
> 
> btw. a short section in the PBS 2 to 3 upgrade guide would be nice too, could
> consist only of a short sentence for context and then just link to this one
> here, once applied.
> 

Seems good, will do
>> +
>> +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.
> 
> Not sure if we really do a hard-removal, or at least how soon that would be.
> S o maybe s/removed/might be removed/ to hold out our options and avoid making
> (responsible) users stumbling upon this might think "I must switch now or
> things break".

Okay, thanks for the feedback! Will submit a v3 asap :)

-- 
- Lukas


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