From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 1FF3A20EC87 for ; Mon, 22 Apr 2024 09:51:40 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 5A7A59F64; Mon, 22 Apr 2024 09:51:40 +0200 (CEST) From: Lukas Wagner To: pbs-devel@lists.proxmox.com Date: Mon, 22 Apr 2024 09:50:29 +0200 Message-Id: <20240422075030.73895-42-l.wagner@proxmox.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240422075030.73895-1-l.wagner@proxmox.com> References: <20240422075030.73895-1-l.wagner@proxmox.com> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL -1.122 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_ASCII_DIVIDERS 0.8 Email that uses ascii formatting dividers and possible spam tricks KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment NUMERIC_HTTP_ADDR 1.242 Uses a numeric IP address in URL PROLO_LEO1 0.1 Meta Catches all Leo drug variations so far SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record URIBL_SBL_A 0.1 Contains URL's A record listed in the Spamhaus SBL blocklist [185.199.110.153, 185.199.111.153, 185.199.109.153, 185.199.108.153] Subject: [pbs-devel] [PATCH proxmox-backup v3 41/42] docs: add documentation for notification system X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox Backup Server development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pbs-devel-bounces@lists.proxmox.com Sender: "pbs-devel" Mostly copied from PVE and adapted where it makes sense. Signed-off-by: Lukas Wagner --- 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 ``: ``, +.. 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@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 `_ 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 _______________________________________________ pbs-devel mailing list pbs-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel