proxmox-mirrors/proxmox-backup
1
0
Fork 1
mirror of https://git.proxmox.com/git/proxmox-backup synced 2025-10-04 20:16:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: notifications: reflow text to 80 characters

Browse Source 
Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
Link: https://lore.proxmox.com/20250409084628.125951-2-l.wagner@proxmox.com
This commit is contained in:
Lukas Wagner 2025-04-09 10:46:27 +02:00 committed by Thomas Lamprecht
parent d25ec96c21
commit 6d193b9a1e
1 changed files with 103 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
docs/notifications.rst
View File

@ -7,26 +7,25 @@ Overview
-------- --------
* Proxmox Backup Server emits :ref:`notification_events` in case of noteworthy * Proxmox Backup Server emits :ref:`notification_events` in case of noteworthy
events in the system. These events are handled by the notification system. events in the system. These events are handled by the notification system. A
A notification event has metadata, for example a timestamp, a severity level, notification event has metadata, for example a timestamp, a severity level, a
a type and other metadata fields. type and other metadata fields.
* :ref:`notification_matchers` route a notification event to one or more notification * :ref:`notification_matchers` route a notification event to one or more
targets. A matcher can have match rules to selectively route based on the metadata notification targets. A matcher can have match rules to selectively route
of a notification event. based on the metadata of a notification event.
* :ref:`notification_targets` are a destination to which 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 is routed to by a matcher. There are multiple types of target, mail-based
(Sendmail and SMTP) and Gotify. (Sendmail and SMTP) and Gotify.
Datastores and tape backup jobs have a configurable :ref:`notification_mode`. Datastores and tape backup jobs have a configurable :ref:`notification_mode`.
It allows you to choose between the notification system and a legacy mode It allows you to choose between the notification system and a legacy mode for
for sending notification emails. The legacy mode is equivalent to the sending notification emails. The legacy mode is equivalent to the way
way notifications were handled before Proxmox Backup Server 3.2. notifications were handled before Proxmox Backup Server 3.2.
The notification system can be configured in the GUI under The notification system can be configured in the GUI under *Configuration →
*Configuration → Notifications*. The configuration is stored in Notifications*. The configuration is stored in :ref:`notifications.cfg` and
:ref:`notifications.cfg` and :ref:`notifications_priv.cfg` - :ref:`notifications_priv.cfg` - the latter contains sensitive configuration
the latter contains sensitive configuration options such as options such as passwords or authentication tokens for notification targets and
passwords or authentication tokens for notification targets and
can only be read by ``root``. can only be read by ``root``.
.. _notification_targets: .. _notification_targets:
@ -41,22 +40,23 @@ Proxmox Backup Server offers multiple types of notification targets.
Sendmail Sendmail
^^^^^^^^ ^^^^^^^^
The sendmail binary is a program commonly found on Unix-like operating systems The sendmail binary is a program commonly found on Unix-like operating systems
that handles the sending of email messages. that handles the sending of email messages. It is a command-line utility that
It is a command-line utility that allows users and applications to send emails allows users and applications to send emails directly from the command line or
directly from the command line or from within scripts. from within scripts.
The sendmail notification target uses the ``sendmail`` binary to send emails to a The sendmail notification target uses the ``sendmail`` binary to send emails to
list of configured users or email addresses. If a user is selected as a recipient, a list of configured users or email addresses. If a user is selected as a
the email address configured in user's settings will be used. recipient, the email address configured in user's settings will be used. For
For the ``root@pam`` user, this is the email address entered during installation. the ``root@pam`` user, this is the email address entered during installation. A
A user's email address can be configured in ``Configuration -> Access Control -> User Management``. user's email address can be configured in ``Configuration -> Access Control ->
If a user has no associated email address, no email will be sent. 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 .. NOTE:: In standard Proxmox Backup Server installations, the ``sendmail``
Postfix. It may be necessary to configure Postfix so that it can deliver binary is provided by Postfix. It may be necessary to configure Postfix so
mails correctly - for example by setting an external mail relay (smart host). that it can deliver mails correctly - for example by setting an external
In case of failed delivery, check the system logs for messages logged by mail relay (smart host). In case of failed delivery, check the system logs
the Postfix daemon. for messages logged by the Postfix daemon.
See :ref:`notifications.cfg` for all configuration options. See :ref:`notifications.cfg` for all configuration options.
@ -64,13 +64,13 @@ See :ref:`notifications.cfg` for all configuration options.
SMTP SMTP
^^^^ ^^^^
SMTP notification targets can send emails directly to an SMTP mail relay. SMTP notification targets can send emails directly to an SMTP mail relay. This
This target does not use the system's MTA to deliver emails. target does not use the system's MTA to deliver emails. Similar to sendmail
Similar to sendmail targets, if a user is selected as a recipient, the user's configured targets, if a user is selected as a recipient, the user's configured email
email address will be used. address will be used.
.. NOTE:: Unlike sendmail targets, SMTP targets do not have any queuing/retry mechanism .. NOTE:: Unlike sendmail targets, SMTP targets do not have any queuing/retry
in case of a failed mail delivery. mechanism in case of a failed mail delivery.
See :ref:`notifications.cfg` for all configuration options. See :ref:`notifications.cfg` for all configuration options.
@ -78,10 +78,10 @@ See :ref:`notifications.cfg` for all configuration options.
Gotify Gotify
^^^^^^ ^^^^^^
`Gotify <http://gotify.net>`_ is an open-source self-hosted notification server that `Gotify <http://gotify.net>`_ is an open-source self-hosted notification server
allows you to send push notifications to various devices and that allows you to send push notifications to various devices and applications.
applications. It provides a simple API and web interface, making it easy to It provides a simple API and web interface, making it easy to integrate with
integrate with different platforms and services. different platforms and services.
.. NOTE:: Gotify targets will respect the HTTP proxy settings from .. NOTE:: Gotify targets will respect the HTTP proxy settings from
Configuration → Other → HTTP proxy Configuration → Other → HTTP proxy
@ -95,27 +95,28 @@ Webhook notification targets perform HTTP requests to a configurable URL.
The following configuration options are available: The following configuration options are available:
* ``url``: The URL to which to perform the HTTP requests. * ``url``: The URL to which to perform the HTTP requests. Supports templating
Supports templating to inject message contents, metadata and secrets. to inject message contents, metadata and secrets.
* ``method``: HTTP Method to use (POST/PUT/GET) * ``method``: HTTP Method to use (POST/PUT/GET)
* ``header``: Array of HTTP headers that should be set for the request. * ``header``: Array of HTTP headers that should be set for the request.
Supports templating to inject message contents, metadata and secrets. Supports templating to inject message contents, metadata and secrets.
* ``body``: HTTP body that should be sent. * ``body``: HTTP body that should be sent. Supports templating to inject
Supports templating to inject message contents, metadata and secrets. message contents, metadata and secrets.
* ``secret``: Array of secret key-value pairs. These will be stored in * ``secret``: Array of secret key-value pairs. These will be stored in a
a protected configuration file only readable by root. Secrets can be protected configuration file only readable by root. Secrets can be
accessed in body/header/URL templates via the ``secrets`` namespace. accessed in body/header/URL templates via the ``secrets`` namespace.
* ``comment``: Comment for this target. * ``comment``: Comment for this target.
For configuration options that support templating, the For configuration options that support templating, the `Handlebars
`Handlebars <https://handlebarsjs.com>`_ syntax can be used to <https://handlebarsjs.com>`_ syntax can be used to access the following
access the following properties: properties:
* ``{{ title }}``: The rendered notification title * ``{{ title }}``: The rendered notification title
* ``{{ message }}``: The rendered notification body * ``{{ message }}``: The rendered notification body
* ``{{ severity }}``: The severity of the notification (``info``, ``notice``, * ``{{ severity }}``: The severity of the notification (``info``, ``notice``,
``warning``, ``error``, ``unknown``) ``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.<name> }}``: Sub-namespace for any metadata fields of the * ``{{ fields.<name> }}``: Sub-namespace for any metadata fields of the
notification. For instance, ``fields.type`` contains the notification notification. For instance, ``fields.type`` contains the notification
type - for all available fields refer to :ref:`notification_events`. type - for all available fields refer to :ref:`notification_events`.
@ -197,20 +198,19 @@ Example - Slack
Notification Matchers Notification Matchers
--------------------- ---------------------
Notification matchers route notifications to notification targets based Notification matchers route notifications to notification targets based on
on their matching rules. These rules can match certain properties of a their matching rules. These rules can match certain properties of a
notification, such as the timestamp (``match-calendar``), the severity of notification, such as the timestamp (``match-calendar``), the severity of the
the notification (``match-severity``) or metadata fields (``match-field``). notification (``match-severity``) or metadata fields (``match-field``). If a
If a notification is matched by a matcher, all targets configured for the notification is matched by a matcher, all targets configured for the matcher
matcher will receive the notification. will receive the notification.
An arbitrary number of matchers can be created, each with with their own An arbitrary number of matchers can be created, each with with their own
matching rules and targets to notify. matching rules and targets to notify. Every target is notified at most once for
Every target is notified at most once for every notification, even if every notification, even if the target is used in multiple matchers.
the target is used in multiple matchers.
A matcher without rules matches any notification; the configured targets A matcher without rules matches any notification; the configured targets will
will always be notified. always be notified.
See :ref:`notifications.cfg` for all configuration options. See :ref:`notifications.cfg` for all configuration options.
@ -227,20 +227,24 @@ Examples:
Field Matching Rules Field Matching Rules
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
Notifications have a selection of metadata fields that can be matched. Notifications have a selection of metadata fields that can be matched. When
When using ``exact`` as a matching mode, a ``,`` can be used as a separator. using ``exact`` as a matching mode, a ``,`` can be used as a separator. The
The matching rule then matches if the metadata field has **any** of the specified matching rule then matches if the metadata field has **any** of the specified
values. values.
Examples: Examples:
* ``match-field exact:type=gc`` Only match notifications for garbage collection jobs * ``match-field exact:type=gc`` Only match notifications for garbage collection
* ``match-field exact:type=prune,verify`` Match prune job and verification job notifications. jobs
* ``match-field regex:datastore=^backup-.*$`` Match any datastore starting with ``backup``. * ``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. 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 For instance, a ``match-field regex:datastore=.*`` directive will match any
a ``datastore`` metadata field, but will not match if the field does not exist. notification that has a ``datastore`` metadata field, but will not match if the
field does not exist.
Severity Matching Rules Severity Matching Rules
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
@ -259,9 +263,9 @@ The following severities are in use:
Notification Events Notification Events
------------------- -------------------
The following table contains a list of all notification events in Proxmox Backup server, their The following table contains a list of all notification events in Proxmox
type, severity and additional metadata fields. ``type`` as well as any other metadata field Backup server, their type, severity and additional metadata fields. ``type`` as
may be used in ``match-field`` match rules. well as any other metadata field may be used in ``match-field`` match rules.
================================ ==================== ========== ============================================================== ================================ ==================== ========== ==============================================================
Event ``type`` Severity Metadata fields (in addition to ``type``) 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`` Verification job success ``verification`` ``info`` ``datastore``, ``hostname``, ``job-id``
================================ ==================== ========== ============================================================== ================================ ==================== ========== ==============================================================
The following table contains a description of all use metadata fields. All of these The following table contains a description of all use metadata fields. All of
can be used in ``match-field`` match rules. these can be used in ``match-field`` match rules.
==================== =================================== ==================== ===================================
Metadata field Description Metadata field Description
@ -299,45 +303,45 @@ Metadata field Description
System Mail Forwarding System Mail Forwarding
---------------------- ----------------------
Certain local system daemons, such as ``smartd``, send notification emails Certain local system daemons, such as ``smartd``, send notification emails to
to the local ``root`` user. Proxmox Backup Server will feed these mails the local ``root`` user. Proxmox Backup Server will feed these mails into the
into the notification system as a notification of type ``system-mail`` notification system as a notification of type ``system-mail`` and with severity
and with severity ``unknown``. ``unknown``.
When the email is forwarded to a sendmail target, the mail's content and headers When the email is forwarded to a sendmail target, the mail's content and
are forwarded as-is. For all other targets, headers are forwarded as-is. For all other targets, the system tries to extract
the system tries to extract both a subject line and the main text body both a subject line and the main text body from the email content. In instances
from the email content. In instances where emails solely consist of HTML where emails solely consist of HTML content, they will be transformed into
content, they will be transformed into plain text format during this process. plain text format during this process.
Permissions Permissions
----------- -----------
In order to modify/view the configuration for notification targets, In order to modify/view the configuration for notification targets, the
the ``Sys.Modify/Sys.Audit`` permissions are required for the ``Sys.Modify/Sys.Audit`` permissions are required for the
``/system/notifications`` ACL node. ``/system/notifications`` ACL node.
.. _notification_mode: .. _notification_mode:
Notification Mode Notification Mode
----------------- -----------------
Datastores and tape backup/restore job configuration have a ``notification-mode`` Datastores and tape backup/restore job configuration have a
option which can have one of two values: ``notification-mode`` option which can have one of two values:
* ``legacy-sendmail``: Send notification emails via the system's ``sendmail`` command. * ``legacy-sendmail``: Send notification emails via the system's ``sendmail``
The notification system will be bypassed and any configured targets/matchers will be ignored. command. The notification system will be bypassed and any configured
This mode is equivalent to the notification behavior for version before targets/matchers will be ignored. This mode is equivalent to the notification
Proxmox Backup Server 3.2. behavior for version before Proxmox Backup Server 3.2.
* ``notification-system``: Use the new, flexible notification system. * ``notification-system``: Use the new, flexible notification system.
If the ``notification-mode`` option is not set, Proxmox Backup Server will default If the ``notification-mode`` option is not set, Proxmox Backup Server will
to ``legacy-sendmail``. default to ``legacy-sendmail``.
Starting with Proxmox Backup Server 3.2, a datastore created in the UI will 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 automatically opt in to the new notification system. If the datastore is
via the API or the ``proxmox-backup-manager`` CLI, the ``notification-mode`` created via the API or the ``proxmox-backup-manager`` CLI, the
option has to be set explicitly to ``notification-system`` if the ``notification-mode`` option has to be set explicitly to
notification system shall be used. ``notification-system`` if the notification system shall be used.
The ``legacy-sendmail`` mode might be removed in a later release of The ``legacy-sendmail`` mode might be removed in a later release of
Proxmox Backup Server. Proxmox Backup Server.
@ -346,12 +350,12 @@ Settings for ``legacy-sendmail`` notification mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If ``notification-mode`` is set to ``legacy-sendmail``, Proxmox Backup Server If ``notification-mode`` is set to ``legacy-sendmail``, Proxmox Backup Server
will send notification emails via the system's ``sendmail`` command to the email will send notification emails via the system's ``sendmail`` command to the
address configured for the user set in the ``notify-user`` option email address configured for the user set in the ``notify-user`` option
(falling back to ``root@pam`` if not set). (falling back to ``root@pam`` if not set).
For datastores, you can also change the level of notifications received per task For datastores, you can also change the level of notifications received per
type via the ``notify`` option. task type via the ``notify`` option.
* Always: send a notification for any scheduled task, independent of the * Always: send a notification for any scheduled task, independent of the
outcome outcome