[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 at 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