From 6d193b9a1e7075b5773b44dc43a30ea669c9e1b9 Mon Sep 17 00:00:00 2001 From: Lukas Wagner Date: Wed, 9 Apr 2025 10:46:27 +0200 Subject: [PATCH] docs: notifications: reflow text to 80 characters Signed-off-by: Lukas Wagner Link: https://lore.proxmox.com/20250409084628.125951-2-l.wagner@proxmox.com --- docs/notifications.rst | 202 +++++++++++++++++++++-------------------- 1 file changed, 103 insertions(+), 99 deletions(-) diff --git a/docs/notifications.rst b/docs/notifications.rst index 2781dc1e..ae3f4ad6 100644 --- a/docs/notifications.rst +++ b/docs/notifications.rst @@ -7,26 +7,25 @@ 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. -* :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. + 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. +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 -:ref:`notifications.cfg` and :ref:`notifications_priv.cfg` - -the latter contains sensitive configuration options such as -passwords or authentication tokens for notification targets and +The notification system 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 can only be read by ``root``. .. _notification_targets: @@ -41,22 +40,23 @@ Proxmox Backup Server offers multiple types of notification targets. Sendmail ^^^^^^^^ The sendmail binary is a program commonly found on Unix-like operating systems -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. +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 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@pam`` user, this is the email address entered during installation. -A user's email address can be configured in ``Configuration -> Access Control -> User Management``. -If a user has no associated email address, no email will be sent. +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@pam`` user, this is the email address entered during installation. A +user's email address can be configured in ``Configuration -> Access Control -> +User Management``. If a user has no associated email address, no email will be +sent. -.. NOTE:: In standard Proxmox Backup Server installations, the ``sendmail`` binary is provided by - 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. +.. NOTE:: In standard Proxmox Backup Server installations, the ``sendmail`` + binary is provided by 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. See :ref:`notifications.cfg` for all configuration options. @@ -64,13 +64,13 @@ See :ref:`notifications.cfg` for all configuration options. SMTP ^^^^ -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. +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. +.. NOTE:: Unlike sendmail targets, SMTP targets do not have any queuing/retry + mechanism in case of a failed mail delivery. See :ref:`notifications.cfg` for all configuration options. @@ -78,10 +78,10 @@ See :ref:`notifications.cfg` for all configuration options. Gotify ^^^^^^ -`Gotify `_ is an open-source self-hosted notification server that -allows you to send push notifications to various devices and -applications. It provides a simple API and web interface, making it easy to -integrate with different platforms and services. +`Gotify `_ is an open-source self-hosted notification server +that allows you to send push notifications to various devices and applications. +It provides a simple API and web interface, making it easy to integrate with +different platforms and services. .. NOTE:: Gotify targets will respect the HTTP proxy settings from Configuration → Other → HTTP proxy @@ -95,27 +95,28 @@ Webhook notification targets perform HTTP requests to a configurable URL. The following configuration options are available: -* ``url``: The URL to which to perform the HTTP requests. - Supports templating to inject message contents, metadata and secrets. +* ``url``: The URL to which to perform the HTTP requests. Supports templating + to inject message contents, metadata and secrets. * ``method``: HTTP Method to use (POST/PUT/GET) * ``header``: Array of HTTP headers that should be set for the request. Supports templating to inject message contents, metadata and secrets. -* ``body``: HTTP body that should be sent. - Supports templating to inject message contents, metadata and secrets. -* ``secret``: Array of secret key-value pairs. These will be stored in - a protected configuration file only readable by root. Secrets can be +* ``body``: HTTP body that should be sent. Supports templating to inject + message contents, metadata and secrets. +* ``secret``: Array of secret key-value pairs. These will be stored in a + protected configuration file only readable by root. Secrets can be accessed in body/header/URL templates via the ``secrets`` namespace. * ``comment``: Comment for this target. -For configuration options that support templating, the -`Handlebars `_ syntax can be used to -access the following properties: +For configuration options that support templating, the `Handlebars +`_ syntax can be used to access the following +properties: * ``{{ title }}``: The rendered notification title * ``{{ message }}``: The rendered notification body * ``{{ severity }}``: The severity of the notification (``info``, ``notice``, ``warning``, ``error``, ``unknown``) -* ``{{ timestamp }}``: The notification's timestamp as a UNIX epoch (in seconds). +* ``{{ timestamp }}``: The notification's timestamp as a UNIX epoch (in + seconds). * ``{{ fields. }}``: Sub-namespace for any metadata fields of the notification. For instance, ``fields.type`` contains the notification type - for all available fields refer to :ref:`notification_events`. @@ -197,20 +198,19 @@ Example - Slack Notification Matchers --------------------- -Notification matchers route notifications to notification targets based -on their matching rules. These rules can match certain properties of a -notification, such as the timestamp (``match-calendar``), the severity of -the notification (``match-severity``) or metadata fields (``match-field``). -If a notification is matched by a matcher, all targets configured for the -matcher will receive the notification. +Notification matchers route notifications to notification targets based on +their matching rules. These rules can match certain properties of a +notification, such as the timestamp (``match-calendar``), the severity of the +notification (``match-severity``) or metadata fields (``match-field``). If a +notification is matched by a matcher, all targets configured for the matcher +will receive the notification. An arbitrary number of matchers can be created, each with with their own -matching rules and targets to notify. -Every target is notified at most once for every notification, even if -the target is used in multiple matchers. +matching rules and targets to notify. Every target is notified at most once for +every notification, even if the target is used in multiple matchers. -A matcher without rules matches any notification; the configured targets -will always be notified. +A matcher without rules matches any notification; the configured targets will +always be notified. See :ref:`notifications.cfg` for all configuration options. @@ -227,20 +227,24 @@ Examples: Field Matching Rules ^^^^^^^^^^^^^^^^^^^^ -Notifications have a selection of metadata fields that can be matched. -When using ``exact`` as a matching mode, a ``,`` can be used as a separator. -The matching rule then matches if the metadata field has **any** of the specified +Notifications have a selection of metadata fields that can be matched. When +using ``exact`` as a matching mode, a ``,`` can be used as a separator. The +matching rule then matches if the metadata field has **any** of the specified values. Examples: -* ``match-field exact:type=gc`` Only match notifications for garbage collection jobs -* ``match-field exact:type=prune,verify`` Match prune job and verification job notifications. -* ``match-field regex:datastore=^backup-.*$`` Match any datastore starting with ``backup``. +* ``match-field exact:type=gc`` Only match notifications for garbage collection + jobs +* ``match-field exact:type=prune,verify`` Match prune job and verification job + notifications. +* ``match-field regex:datastore=^backup-.*$`` Match any datastore starting with + ``backup``. If a notification does not have the matched field, the rule will **not** match. -For instance, a ``match-field regex:datastore=.*`` directive will match any notification that has -a ``datastore`` metadata field, but will not match if the field does not exist. +For instance, a ``match-field regex:datastore=.*`` directive will match any +notification that has a ``datastore`` metadata field, but will not match if the +field does not exist. Severity Matching Rules ^^^^^^^^^^^^^^^^^^^^^^^ @@ -259,9 +263,9 @@ The following severities are in use: Notification Events ------------------- -The following table contains a list of all notification events in Proxmox Backup server, their -type, severity and additional metadata fields. ``type`` as well as any other metadata field -may be used in ``match-field`` match rules. +The following table contains a list of all notification events in Proxmox +Backup server, their type, severity and additional metadata fields. ``type`` as +well as any other metadata field may be used in ``match-field`` match rules. ================================ ==================== ========== ============================================================== Event ``type`` Severity Metadata fields (in addition to ``type``) @@ -281,8 +285,8 @@ Verification job failure ``verification`` ``error`` ``datastore``, Verification job success ``verification`` ``info`` ``datastore``, ``hostname``, ``job-id`` ================================ ==================== ========== ============================================================== -The following table contains a description of all use metadata fields. All of these -can be used in ``match-field`` match rules. +The following table contains a description of all use metadata fields. All of +these can be used in ``match-field`` match rules. ==================== =================================== Metadata field Description @@ -299,45 +303,45 @@ 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``. +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``. -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. +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. Permissions ----------- -In order to modify/view the configuration for notification targets, -the ``Sys.Modify/Sys.Audit`` permissions are required for the +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: +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. +* ``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``. +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. +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. @@ -346,12 +350,12 @@ 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 +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. +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