mirror of
https://git.proxmox.com/git/proxmox-backup
synced 2025-10-04 17:05:37 +00:00
docs: notifications: reflow text to 80 characters
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
Thomas Lamprecht
parent
d25ec96c21
commit
6d193b9a1e
@ -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 <http://gotify.net>`_ 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 <http://gotify.net>`_ 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 <https://handlebarsjs.com>`_ syntax can be used to
|
||||
access the following properties:
|
||||
For configuration options that support templating, the `Handlebars
|
||||
<https://handlebarsjs.com>`_ 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.<name> }}``: 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user