[pve-devel] applied: [PATCH docs v7 19/19] notifications: backport some rephrased parts from PBS docs

[Fabian Grünbichler]

Quoting Lukas Wagner (2024-06-10 10:40:38)
> Most of the changes were done when adapting the PVE docs to
> the new PBS notification system, so now we 'backport' those
> improvements.
> 
> Signed-off-by: Lukas Wagner <l.wagner at proxmox.com>
> ---
>  notifications.adoc | 99 +++++++++++++++++++++++++++++++---------------
>  1 file changed, 67 insertions(+), 32 deletions(-)
> 
> diff --git a/notifications.adoc b/notifications.adoc
> index 9c5228c..bdfebd0 100644
> --- a/notifications.adoc
> +++ b/notifications.adoc
> @@ -9,37 +9,38 @@ Overview
>  --------
>  [thumbnail="screenshot/gui-datacenter-notification-overview.png"]
>  
> -{pve} will send notifications if case of noteworthy events in the system.
> -
> -There are a number of different xref:notification_events[notification events],
> -each with their own set of metadata fields that can be used in
> -notification matchers.
> -
> -A xref:notification_matchers[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 configurable set of notification targets.
> -
> -A xref:notification_targets[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.
> +* {pve} emits xref:notification_events[Notification Events] in case of
> +  storage replication failures, node fencing, finished/failed backups
> +  and other events.
> +  These events are handled by the notification system. A notification
> +  event has metadata, for example a timestamp, a severity level,
> +  a type, and other optional metadata fields.
> +* xref:notification_matchers[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.
> +* xref:notification_targets[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.
> +
> +Backup jobs have a configurable xref:notification_mode[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 {pve} 8.1.
>  
>  The notification system can be configured in the GUI under
> -Datacenter -> Notifications. The configuration is stored in
> +Datacenter → Notifications. The configuration is stored in
>  `/etc/pve/notifications.cfg` and `/etc/pve/priv/notifications.cfg` -
>  the latter contains sensitive configuration options such as
> -passwords or authentication tokens for notification targets.
> +passwords or authentication tokens for notification targets and can
> +only be read by `root`.
>  
>  [[notification_targets]]
>  Notification Targets
>  --------------------
>  
> +{pve} offers multiple types of notification targets.
> +
>  [[notification_targets_sendmail]]
>  Sendmail
>  ~~~~~~~~
> @@ -50,14 +51,19 @@ that handles the sending of email messages.
>  It is a command-line utility that allows users and applications to send emails
>  directly from the command line or from within scripts.
>  
> -The sendmail notification target uses the `sendmail` binary to send emails.
> -
> +The sendmail notification target uses the `sendmail` binary to send emails to a
> +list of configured users or email addresses. If a user is selected as a recipient,
> +the email address configured in user's settings will be used.
> +For the `root at pam` user, this is the email address entered during installation.
> +A user's email address can be configured in
> +`Datacenter → Permissions → Users`.
> +If a user has no associated email address, no email will be sent.
>  
>  NOTE: In standard {pve} installations, the `sendmail` binary is provided by
> -Postfix. For this type of target to work correctly, it might be necessary to
> -change Postfix's configuration so that it can correctly deliver emails.
> -For cluster setups it is necessary to have a working Postfix configuration on
> -every single cluster node.
> +Postfix. It may be necessary to configure Postfix so that it can deliver
> +mails correctly - for example by setting an external mail relay (smart host).
> +In case of failed delivery, check the system logs for messages logged by
> +the Postfix daemon.
>  
>  The configuration for Sendmail target plugins has the following options:
>  
> @@ -90,6 +96,12 @@ SMTP
>  [thumbnail="screenshot/gui-datacenter-notification-smtp.png"]
>  
>  SMTP notification targets can send emails directly to an SMTP mail relay.
> +This target does not use the system's MTA to deliver emails.
> +Similar to sendmail targets, if a user is selected as a recipient, the user's configured
> +email address will be used.
> +
> +NOTE: Unlike sendmail targets, SMTP targets do not have any queuing/retry mechanism
> +in case of a failed mail delivery.
>  
>  The configuration for SMTP target plugins has the following options:
>  
> @@ -308,9 +320,8 @@ that are initially directed to the local `root` user. {pve} will
>  feed these mails into the notification system as a notification of
>  type `system-mail` and with severity `unknown`.
>  
> -When the forwarding process involves an email-based target
> -(like `sendmail` or `smtp`), the email is forwarded exactly as received, with all
> -original mail headers remaining intact. For all other targets,
> +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 both a subject line and the main text body
>  from the email content. In instances where emails solely consist of HTML
>  content, they will be transformed into plain text format during this process.
> @@ -318,9 +329,33 @@ content, they will be transformed into plain text format during this process.
>  Permissions
>  -----------
>  
> -In order to modify/view the configuration for notification targets,
> +To modify/view the configuration for notification targets,
>  the `Mapping.Modify/Mapping.Audit` permissions are required for the
>  `/mapping/notifications` ACL node.
>  
>  Testing a target requires `Mapping.Use`, `Mapping.Audit` or `Mapping.Modify`
>  permissions on `/mapping/notifications`
> +
> +[[notification_mode]]
> +Notification Mode
> +-----------------
> +A backup job configuration has the `notification-mode`
> +option which can have one of three values.
> +
> +* `auto`: Use the `legacy-sendmail` mode if no email address is entered in the
> +  `mailto`/`Send email to` field. If no email address is entered,
> +  the `notification-system` mode is used.
> +
> +* `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
> +  {pve} 8.1 .
> +
> +* `notification-system`: Use the new, flexible notification system.
> +
> +If the `notification-mode` option is not set, {pve} will default
> +to `auto`.
> +
> +The `legacy-sendmail` mode might be removed in a later release of
> +{pve}.
> -- 
> 2.39.2
> 
> 
> 
> _______________________________________________
> pve-devel mailing list
> pve-devel at lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel