[pbs-devel] [PATCH proxmox-backup v3 41/42] docs: add documentation for notification system
Lukas Wagner
l.wagner at proxmox.com
Mon Apr 22 09:50:29 CEST 2024
Mostly copied from PVE and adapted where it makes sense.
Signed-off-by: Lukas Wagner <l.wagner at proxmox.com>
---
debian/proxmox-backup-server.install | 2 +
docs/Makefile | 6 +-
docs/conf.py | 2 +
docs/config/notifications-priv/format.rst | 1 +
docs/config/notifications-priv/man5.rst | 24 +++
docs/config/notifications/format.rst | 28 +++
docs/config/notifications/man5.rst | 24 +++
docs/configuration-files.rst | 30 +++
docs/index.rst | 1 +
docs/notifications.rst | 213 ++++++++++++++++++++++
www/OnlineHelpInfo.js | 24 +++
11 files changed, 354 insertions(+), 1 deletion(-)
create mode 100644 docs/config/notifications-priv/format.rst
create mode 100644 docs/config/notifications-priv/man5.rst
create mode 100644 docs/config/notifications/format.rst
create mode 100644 docs/config/notifications/man5.rst
create mode 100644 docs/notifications.rst
diff --git a/debian/proxmox-backup-server.install b/debian/proxmox-backup-server.install
index df7d68ee..ef1e9ba1 100644
--- a/debian/proxmox-backup-server.install
+++ b/debian/proxmox-backup-server.install
@@ -30,6 +30,8 @@ usr/share/man/man5/acl.cfg.5
usr/share/man/man5/datastore.cfg.5
usr/share/man/man5/domains.cfg.5
usr/share/man/man5/media-pool.cfg.5
+usr/share/man/man5/notifications.cfg.5
+usr/share/man/man5/notifications-priv.cfg.5
usr/share/man/man5/remote.cfg.5
usr/share/man/man5/sync.cfg.5
usr/share/man/man5/tape-job.cfg.5
diff --git a/docs/Makefile b/docs/Makefile
index 0d0963f3..a617fc91 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -11,6 +11,8 @@ GENERATED_SYNOPSIS := \
pmtx/synopsis.rst \
pmt/synopsis.rst \
config/media-pool/config.rst \
+ config/notifications/config.rst \
+ config/notifications-priv/config.rst \
config/tape/config.rst \
config/tape-job/config.rst \
config/user/config.rst \
@@ -43,7 +45,9 @@ MAN5_PAGES := \
sync.cfg.5 \
verification.cfg.5 \
datastore.cfg.5 \
- domains.cfg.5
+ domains.cfg.5 \
+ notifications.cfg.5 \
+ notifications-priv.cfg.5 \
PRUNE_SIMULATOR_FILES := \
prune-simulator/index.html \
diff --git a/docs/conf.py b/docs/conf.py
index f85cd187..fec234b9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -114,6 +114,8 @@ man_pages = [
('config/tape/man5', 'tape.cfg', 'Tape Drive and Changer Configuration', [author], 5),
('config/user/man5', 'user.cfg', 'User Configuration', [author], 5),
('config/verification/man5', 'verification.cfg', 'Verification Job Configuration', [author], 5),
+ ('config/notifications/man5', 'notifications.cfg', 'Notification target/matcher configuration', [author], 5),
+ ('config/notifications-priv/man5', 'notifications-priv.cfg', 'Notification target secrets', [author], 5),
]
diff --git a/docs/config/notifications-priv/format.rst b/docs/config/notifications-priv/format.rst
new file mode 100644
index 00000000..7d92c979
--- /dev/null
+++ b/docs/config/notifications-priv/format.rst
@@ -0,0 +1 @@
+This file contains protected credentials for notification targets.
diff --git a/docs/config/notifications-priv/man5.rst b/docs/config/notifications-priv/man5.rst
new file mode 100644
index 00000000..827c8ac7
--- /dev/null
+++ b/docs/config/notifications-priv/man5.rst
@@ -0,0 +1,24 @@
+:orphan:
+
+======================
+notifications-priv.cfg
+======================
+
+Description
+===========
+
+The file /etc/proxmox-backup/notifications-priv.cfg is a configuration file
+for Proxmox Backup Server. It contains the configration for the
+notification system configuration.
+
+File Format
+===========
+
+.. include:: format.rst
+
+Options
+=======
+
+.. include:: config.rst
+
+.. include:: ../../pbs-copyright.rst
diff --git a/docs/config/notifications/format.rst b/docs/config/notifications/format.rst
new file mode 100644
index 00000000..e29facb5
--- /dev/null
+++ b/docs/config/notifications/format.rst
@@ -0,0 +1,28 @@
+This file contains configuration for notification targets and notification
+matchers.
+
+.. Each user configuration section starts with the header ``<realm-type>: <name>``,
+.. followed by the realm's configuration options.
+..
+.. For LDAP realms, the LDAP bind password is stored in ``ldap_passwords.json``.
+..
+.. ::
+..
+.. openid: master
+.. client-id pbs
+.. comment
+.. issuer-url http://192.168.0.10:8080/realms/master
+.. username-claim username
+..
+.. ldap: ldap-server
+.. base-dn OU=People,DC=ldap-server,DC=example,DC=com
+.. mode ldaps
+.. server1 192.168.0.10
+.. sync-attributes email=mail
+.. sync-defaults-options enable-new=0,remove-vanished=acl;entry
+.. user-attr uid
+.. user-classes inetorgperson,posixaccount,person,user
+..
+..
+.. You can use the ``proxmox-backup-manager openid`` and ``proxmox-backup-manager ldap`` commands to manipulate
+.. this file.
diff --git a/docs/config/notifications/man5.rst b/docs/config/notifications/man5.rst
new file mode 100644
index 00000000..96844162
--- /dev/null
+++ b/docs/config/notifications/man5.rst
@@ -0,0 +1,24 @@
+:orphan:
+
+==================
+notifications.cfg
+==================
+
+Description
+===========
+
+The file /etc/proxmox-backup/notifications.cfg is a configuration file
+for Proxmox Backup Server. It contains the configration for the
+notification system configuration.
+
+File Format
+===========
+
+.. include:: format.rst
+
+Options
+=======
+
+.. include:: config.rst
+
+.. include:: ../../pbs-copyright.rst
diff --git a/docs/configuration-files.rst b/docs/configuration-files.rst
index ba54a7b0..ee8367e5 100644
--- a/docs/configuration-files.rst
+++ b/docs/configuration-files.rst
@@ -67,6 +67,36 @@ Options
.. include:: config/media-pool/config.rst
+.. _notifications.cfg:
+
+``notifications.cfg``
+~~~~~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/notifications/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/notifications/config.rst
+
+``notifications-priv.cfg``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/notifications-priv/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/notifications-priv/config.rst
+
``tape.cfg``
~~~~~~~~~~~~
diff --git a/docs/index.rst b/docs/index.rst
index 8e13c24f..86add2d7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,6 +34,7 @@ in the section entitled "GNU Free Documentation License".
maintenance.rst
sysadmin.rst
network-management.rst
+ notifications.rst
technical-overview.rst
faq.rst
diff --git a/docs/notifications.rst b/docs/notifications.rst
new file mode 100644
index 00000000..4f9b01b7
--- /dev/null
+++ b/docs/notifications.rst
@@ -0,0 +1,213 @@
+Notifications
+=============
+
+Overview
+--------
+
+Proxmox Backup Server will send notifications if case of noteworthy
+events.
+
+There are a number of different :ref:`Notification Events`,
+each with their own set of metadata fields that can be used in
+notification matchers.
+
+A 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 configured set of notification targets.
+
+A 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.
+
+The notification system can be configured in the GUI under
+``Configuration -> Notifications``. The configuration is stored in
+``/etc/proxmox-backup/notifications.cfg`` and
+``/etc/proxmox-backup/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
+--------------------
+
+Proxmox Backup Server offers multiple types of notification targets.
+
+.. _notification_targets_sendmail:
+
+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.
+
+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 ``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.
+
+See :ref:`notifications.cfg` for all configuration options.
+
+.. _notification_targets_smtp:
+
+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.
+
+.. 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.
+
+.. _notification_targets_gotify:
+
+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.
+
+See :ref:`notifications.cfg` for all configuration options.
+
+.. _notification_matchers:
+
+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.
+
+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.
+
+A matcher without rules matches any notification; the configured targets
+will always be notified.
+
+See :ref:`notifications.cfg` for all configuration options.
+
+Calendar Matching Rules
+^^^^^^^^^^^^^^^^^^^^^^^
+A calendar matcher matches a notification's timestamp.
+
+Examples:
+
+* ``match-calendar 8-12``
+* ``match-calendar 8:00-15:30``
+* ``match-calendar mon-fri 9:00-17:00``
+* ``match-calendar sun,tue-wed,fri 9-17``
+
+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
+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``.
+
+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.
+
+Severity Matching Rules
+^^^^^^^^^^^^^^^^^^^^^^^
+A notification has a associated severity that can be matched.
+
+Examples:
+
+* ``match-severity error``: Only match errors
+* ``match-severity warning,error``: Match warnings and error
+
+The following severities are in use:
+``info``, ``notice``, ``warning``, ``error``, ``unknown``.
+
+.. _Notification Events:
+
+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.
+
+================================ ==================== ========== ==============================================================
+Event ``type`` Severity Metadata fields (in addition to ``type``)
+================================ ==================== ========== ==============================================================
+ACME certificate renewal failed ``acme`` ``error`` ``hostname``
+Garbage collection failure ``gc`` ``error`` ``datastore``, ``hostname``
+Garbage collection success ``gc`` ``info`` ``datastore``, ``hostname``
+Package updates available ``package-updates`` ``info`` ``hostname``
+Prune job failure ``prune`` ``error`` ``datastore``, ``hostname``, ``job-id``
+Prune job success ``prune`` ``info`` ``datastore``, ``hostname``, ``job-id``
+Remote sync failure ``sync`` ``error`` ``datastore``, ``hostname``, ``job-id``
+Remote sync success ``sync`` ``info`` ``datastore``, ``hostname``, ``job-id``
+Tape backup job failure ``tape-backup`` ``error`` ``datastore``, ``hostname``, ``media-pool``, ``job-id``
+Tape backup job success ``tape-backup`` ``info`` ``datastore``, ``hostname``, ``media-pool``, ``job-id``
+Tape loading request ``tape-load`` ``notice`` ``hostname``
+Verification job failure ``verification`` ``error`` ``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
+can be used in ``match-field`` match rules.
+
+==================== ===================================
+Metadata field Description
+==================== ===================================
+``datastore`` The name of the datastore
+``hostname`` The hostname of the backup server
+``job-id`` Job ID
+``media-pool`` The name of the tape media pool
+``type`` Notification event type
+==================== ===================================
+
+.. NOTE:: The daily task checking for any available system updates only sends
+ notifications if the node has an active subscription.
+
+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``.
+
+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
+``/system/notifications`` ACL node.
diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js
index 2402c11d..639408b1 100644
--- a/www/OnlineHelpInfo.js
+++ b/www/OnlineHelpInfo.js
@@ -35,6 +35,10 @@ const proxmoxOnlineHelpInfo = {
"link": "/docs/configuration-files.html#domains-cfg",
"title": "``domains.cfg``"
},
+ "notifications-cfg": {
+ "link": "/docs/configuration-files.html#notifications-cfg",
+ "title": "``notifications.cfg``"
+ },
"faq-support-table": {
"link": "/docs/faq.html#faq-support-table",
"title": "How long will my Proxmox Backup Server version be supported?"
@@ -139,6 +143,26 @@ const proxmoxOnlineHelpInfo = {
"link": "/docs/network-management.html#sysadmin-traffic-control",
"title": "Traffic Control"
},
+ "notification-targets-sendmail": {
+ "link": "/docs/notifications.html#notification-targets-sendmail",
+ "title": "Sendmail"
+ },
+ "notification-targets-smtp": {
+ "link": "/docs/notifications.html#notification-targets-smtp",
+ "title": "SMTP"
+ },
+ "notification-targets-gotify": {
+ "link": "/docs/notifications.html#notification-targets-gotify",
+ "title": "Gotify"
+ },
+ "notification-matchers": {
+ "link": "/docs/notifications.html#notification-matchers",
+ "title": "Notification Matchers"
+ },
+ "notification-events": {
+ "link": "/docs/notifications.html#notification-events",
+ "title": "Notification Events"
+ },
"pve-integration": {
"link": "/docs/pve-integration.html#pve-integration",
"title": "`Proxmox VE`_ Integration"
--
2.39.2
More information about the pbs-devel
mailing list