[pbs-devel] [PATCH proxmox-backup v2 1/3] docs: notifications: add section about how to use custom templates

[pbs-devel] [PATCH proxmox-backup v2 1/3] docs: notifications: add section about how to use custom templates

[Lukas Wagner]

This section is meant to give a basic overview on how to use
custom templates for notifications. It will be expanded in the
future, providing a more detailed view on how templates are resolved,
existing fallback mechanisms, available templates, template
variables and helpers.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
Reviewed-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 docs/notifications.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/notifications.rst b/docs/notifications.rst
index 34fc0128..2781dc1e 100644
--- a/docs/notifications.rst
+++ b/docs/notifications.rst
@@ -362,3 +362,23 @@ type via the ``notify`` option.
 
 The ``notify-user`` and ``notify`` options are ignored if ``notification-mode``
 is set to ``notification-system``.
+
+Overriding Notification Templates
+---------------------------------
+
+Proxmox Backup Server uses Handlebars templates to render notifications. The
+original templates provided by Proxmox Backup Server are stored in
+``/usr/share/proxmox-backup/templates/default/``.
+
+Notification templates can be overridden by providing a custom template file in
+the override directory at
+``/etc/proxmox-backup/notification-templates/default/``. When rendering a
+notification of a given type, Proxmox Backup Server will first attempt to load
+a template from the override directory. If this one does not exist or fails to
+render, the original template will be used.
+
+The template files follow the naming convention of
+``<type>-<body|subject>.txt.hbs``. For instance, the file
+``gc-err-body.txt.hbs`` contains the template for rendering notifications for
+garbage collection errors, while ``package-updates-subject.txt.hbs`` is used to
+render the subject line of notifications for available package updates.
-- 
2.39.5



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

[pbs-devel] [PATCH proxmox-backup v2 2/3] docs: notifications: reflow text to 80 characters

[Lukas Wagner]

Signed-off-by: Lukas Wagner <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 <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
-- 
2.39.5



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

[pbs-devel] [PATCH proxmox-backup v2 3/3] docs: notification: use unicode arrow instead of ->

[Lukas Wagner]

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 docs/notifications.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/notifications.rst b/docs/notifications.rst
index ae3f4ad6..5669dab0 100644
--- a/docs/notifications.rst
+++ b/docs/notifications.rst
@@ -48,7 +48,7 @@ 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'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.
 
-- 
2.39.5



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

Re: [pbs-devel] [PATCH proxmox-backup v2 1/3] docs: notifications: add section about how to use custom templates

[Lukas Wagner]

On  2025-04-09 10:46, Lukas Wagner wrote:
> This section is meant to give a basic overview on how to use
> custom templates for notifications. It will be expanded in the
> future, providing a more detailed view on how templates are resolved,
> existing fallback mechanisms, available templates, template
> variables and helpers.
> 
> Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
> Reviewed-by: Alexander Zeidler <a.zeidler@proxmox.com>

Forgot to pass the --notes flag when formatting the patch.
The only difference between this and v1 is that I reflowed the
text. No changes to the actual content.

-- 
- Lukas



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

[pbs-devel] applied: [PATCH proxmox-backup v2 1/3] docs: notifications: add section about how to use custom templates

[Thomas Lamprecht]

On Wed, 09 Apr 2025 10:46:26 +0200, Lukas Wagner wrote:
> This section is meant to give a basic overview on how to use
> custom templates for notifications. It will be expanded in the
> future, providing a more detailed view on how templates are resolved,
> existing fallback mechanisms, available templates, template
> variables and helpers.
> 
> 
> [...]

Applied, thanks!

[1/3] docs: notifications: add section about how to use custom templates
      commit: d25ec96c21abb2ec219d854e683953f9a4eb3909
[2/3] docs: notifications: reflow text to 80 characters
      commit: 6d193b9a1e7075b5773b44dc43a30ea669c9e1b9
[3/3] docs: notification: use unicode arrow instead of ->
      commit: f117dabcf037f6804e7a51b19c53d3081c2c8ffd


_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel