Proxmox/pve-docs
5
0
Fork 0
mirror of git://git.proxmox.com/git/pve-docs.git synced 2025-05-29 17:05:40 +03:00
Code Releases Activity

notifications: reflow to 80 cc text-width and indent points in lists

Browse Source 
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
This commit is contained in:
Thomas Lamprecht 2025-04-09 10:09:21 +02:00
parent 56f3d84b75
commit fbb84a2b4c
1 changed files with 86 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
notifications.adoc
View File

@ -11,30 +11,28 @@ Overview
[thumbnail="screenshot/gui-datacenter-notification-overview.png"] [thumbnail="screenshot/gui-datacenter-notification-overview.png"]
* {pve} emits xref:notification_events[Notification Events] in case of * {pve} emits xref:notification_events[Notification Events] in case of
storage replication failures, node fencing, finished/failed backups storage replication failures, node fencing, finished/failed backups and other
and other events. events.
These events are handled by the notification system. A notification These events are handled by the notification system. A notification event has
event has metadata, for example a timestamp, a severity level, metadata, for example a timestamp, a severity level, a type, and other
a type, and other optional metadata fields. optional metadata fields.
* xref:notification_matchers[Notification Matchers] route a notification * xref:notification_matchers[Notification Matchers] route a notification
event to one or more notification targets. A matcher can have match event to one or more notification targets. A matcher can have match rules to
rules to selectively route based on the metadata of a notification event. selectively route based on the metadata of a notification event.
* xref:notification_targets[Notification Targets] are a destination to * xref:notification_targets[Notification Targets] are a destination to
which a notification event is routed to by a matcher. which a notification event is routed to by a matcher. There are multiple
There are multiple types of target, mail-based (Sendmail and SMTP) types of target, mail-based (Sendmail and SMTP) and Gotify.
and Gotify.
Backup jobs have a configurable xref:notification_mode[Notification Mode]. Backup jobs have a configurable xref:notification_mode[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 {pve} 8.1. notifications were handled before {pve} 8.1.
The notification system can be configured in the GUI under The notification system can be configured in the GUI under Datacenter →
Datacenter → Notifications. The configuration is stored in Notifications. The configuration is stored in `/etc/pve/notifications.cfg` and
`/etc/pve/notifications.cfg` and `/etc/pve/priv/notifications.cfg` - `/etc/pve/priv/notifications.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 can only be read by `root`.
only be read by `root`.
[[notification_targets]] [[notification_targets]]
Notification Targets Notification Targets
@ -54,33 +52,32 @@ It is a command-line utility that allows users and applications to send emails
directly from the command line or from within scripts. directly from the command line or 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 a
list of configured users or email addresses. If a user is selected as a recipient, 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 the `root@pam` user, this is the email address entered during installation. For the `root@pam` user, this is the email address entered during installation.
A user's email address can be configured in A user's email address can be configured in `Datacenter → Permissions → Users`.
`Datacenter → Permissions → Users`.
If a user has no associated email address, no email will be sent. If a user has no associated email address, no email will be sent.
NOTE: In standard {pve} installations, the `sendmail` binary is provided by NOTE: In standard {pve} installations, the `sendmail` binary is provided by
Postfix. It may be necessary to configure Postfix so that it can deliver Postfix. It may be necessary to configure Postfix so that it can deliver mails
mails correctly - for example by setting an external mail relay (smart host). correctly - for example by setting an external mail relay (smart host). In case
In case of failed delivery, check the system logs for messages logged by of failed delivery, check the system logs for messages logged by the Postfix
the Postfix daemon. daemon.
The configuration for Sendmail target plugins has the following options: The configuration for Sendmail target plugins has the following options:
* `mailto`: E-Mail address to which the notification shall be sent to. Can be * `mailto`: E-Mail address to which the notification shall be sent to. Can be
set multiple times to accommodate multiple recipients. set multiple times to accommodate multiple recipients.
* `mailto-user`: Users to which emails shall be sent to. The user's email * `mailto-user`: Users to which emails shall be sent to. The user's email
address will be looked up in `users.cfg`. Can be set multiple times to address will be looked up in `users.cfg`. Can be set multiple times to
accommodate multiple recipients. accommodate multiple recipients.
* `author`: Sets the author of the E-Mail. Defaults to `Proxmox VE`. * `author`: Sets the author of the E-Mail. Defaults to `Proxmox VE`.
* `from-address`: Sets the from address of the E-Mail. If the parameter is not * `from-address`: Sets the from address of the E-Mail. If the parameter is not
set, the plugin will fall back to the `email_from` setting from set, the plugin will fall back to the `email_from` setting from
`datacenter.cfg`. If that is also not set, the plugin will default to `datacenter.cfg`. If that is also not set, the plugin will default to
`root@$hostname`, where `$hostname` is the hostname of the node. `root@$hostname`, where `$hostname` is the hostname of the node.
The `From` header in the email will be set to `$author <$from-address>`.
* `comment`: Comment for this target * `comment`: Comment for this target
The `From` header in the email will be set to `$author <$from-address>`.
Example configuration (`/etc/pve/notifications.cfg`): Example configuration (`/etc/pve/notifications.cfg`):
---- ----
@ -100,33 +97,33 @@ 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 target does not use the system's MTA to deliver emails. 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 Similar to sendmail targets, if a user is selected as a recipient, the user's
email address will be used. configured email 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.
The configuration for SMTP target plugins has the following options: The configuration for SMTP target plugins has the following options:
* `mailto`: E-Mail address to which the notification shall be sent to. Can be * `mailto`: E-Mail address to which the notification shall be sent to. Can be
set multiple times to accommodate multiple recipients. set multiple times to accommodate multiple recipients.
* `mailto-user`: Users to which emails shall be sent to. The user's email * `mailto-user`: Users to which emails shall be sent to. The user's email
address will be looked up in `users.cfg`. Can be set multiple times to address will be looked up in `users.cfg`. Can be set multiple times to
accommodate multiple recipients. accommodate multiple recipients.
* `author`: Sets the author of the E-Mail. Defaults to `Proxmox VE`. * `author`: Sets the author of the E-Mail. Defaults to `Proxmox VE`.
* `from-address`: Sets the From-address of the email. SMTP relays might require * `from-address`: Sets the From-address of the email. SMTP relays might require
that this address is owned by the user in order to avoid spoofing. that this address is owned by the user in order to avoid spoofing. The `From`
The `From` header in the email will be set to `$author <$from-address>`. header in the email will be set to `$author <$from-address>`.
* `username`: Username to use during authentication. If no username is set, * `username`: Username to use during authentication. If no username is set,
no authentication will be performed. The PLAIN and LOGIN authentication methods no authentication will be performed. The PLAIN and LOGIN authentication
are supported. methods are supported.
* `password`: Password to use when authenticating. * `password`: Password to use when authenticating.
* `mode`: Sets the encryption mode (`insecure`, `starttls` or `tls`). Defaults * `mode`: Sets the encryption mode (`insecure`, `starttls` or `tls`). Defaults
to `tls`. to `tls`.
* `server`: Address/IP of the SMTP relay * `server`: Address/IP of the SMTP relay.
* `port`: The port to connect to. If not set, the used port * `port`: The port to connect to. If not set, the used port .
defaults to 25 (`insecure`), 465 (`tls`) or 587 (`starttls`), depending on the Defaults to 25 (`insecure`), 465 (`tls`) or 587 (`starttls`), depending on
value of `mode`. the value of `mode`.
* `comment`: Comment for this target * `comment`: Comment for this target
Example configuration (`/etc/pve/notifications.cfg`): Example configuration (`/etc/pve/notifications.cfg`):
@ -164,11 +161,11 @@ The configuration for Gotify target plugins has the following options:
* `server`: The base URL of the Gotify server, e.g. `http://<ip>:8888` * `server`: The base URL of the Gotify server, e.g. `http://<ip>:8888`
* `token`: The authentication token. Tokens can be generated within the Gotify * `token`: The authentication token. Tokens can be generated within the Gotify
web interface. web interface.
* `comment`: Comment for this target * `comment`: Comment for this target
NOTE: The Gotify target plugin will respect the HTTP proxy settings from the NOTE: The Gotify target plugin will respect the HTTP proxy settings from the
xref:datacenter_configuration_file[datacenter configuration] xref:datacenter_configuration_file[datacenter configuration]
Example configuration (`/etc/pve/notifications.cfg`): Example configuration (`/etc/pve/notifications.cfg`):
---- ----
@ -280,22 +277,23 @@ For convenience, the following helpers are available:
[[notification_matchers]] [[notification_matchers]]
Notification Matchers Notification Matchers
--------------------- ---------------------
[thumbnail="screenshot/gui-datacenter-notification-matcher.png"] [thumbnail="screenshot/gui-datacenter-notification-matcher.png"]
Notification matchers route notifications to notification targets based Notification matchers route notifications to notification targets based on their
on their matching rules. These rules can match certain properties of a matching rules. These rules can match certain properties of a notification, such
notification, such as the timestamp (`match-calendar`), the severity of as the timestamp (`match-calendar`), the severity of the notification
the notification (`match-severity`) or metadata fields (`match-field`). (`match-severity`) or metadata fields (`match-field`).
If a notification is matched by a matcher, all targets configured for the If a notification is matched by a matcher, all targets configured for the
matcher will receive the notification. matcher 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 notification, even if Every target is notified at most once for every notification, even if the target
the target is used in multiple matchers. is used in multiple matchers.
A matcher without any matching rules is always true; the configured targets A matcher without any matching rules is always true; the configured targets will
will always be notified. always be notified.
---- ----
matcher: always-matches matcher: always-matches
target admin target admin
@ -306,20 +304,22 @@ Matcher Options
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
* `target`: Determine which target should be notified if the matcher matches. * `target`: Determine which target should be notified if the matcher matches.
can be used multiple times to notify multiple targets. can be used multiple times to notify multiple targets.
* `invert-match`: Inverts the result of the whole matcher * `invert-match`: Inverts the result of the whole matcher
* `mode`: Determines how the individual match rules are evaluated to compute * `mode`: Determines how the individual match rules are evaluated to compute
the result for the whole matcher. If set to `all`, all matching rules must the result for the whole matcher.
match. If set to `any`, at least one rule must match. If set to `all`, all matching rules must match.
a matcher must be true. Defaults to `all`. If set to `any`, at least one rule must match.
* `match-calendar`: Match the notification's timestamp against a schedule Defaults to `all`.
* `match-field`: Match the notification's metadata fields * `match-calendar`: Match the notification's timestamp against a schedule.
* `match-severity`: Match the notification's severity * `match-field`: Match the notification's metadata fields.
* `comment`: Comment for this matcher * `match-severity`: Match the notification's severity.
* `comment`: Comment for this matcher.
[[notification_matchers_calendar]] [[notification_matchers_calendar]]
Calendar Matching Rules Calendar Matching Rules
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
A calendar matcher matches the time when a notification is sent against a A calendar matcher matches the time when a notification is sent against a
configurable schedule. configurable schedule.
@ -331,9 +331,10 @@ configurable schedule.
[[notification_matchers_field]] [[notification_matchers_field]]
Field Matching Rules 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. Notifications have a selection of metadata fields that can be matched. When
The matching rule then matches if the metadata field has *any* of the specified 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. values.
* `match-field exact:type=vzdump` Only match notifications about backups. * `match-field exact:type=vzdump` Only match notifications about backups.
@ -466,24 +467,23 @@ The `legacy-sendmail` mode might be removed in a later release of
Overriding Notification Templates Overriding Notification Templates
--------------------------------- ---------------------------------
{pve} uses Handlebars templates to render notifications. The {pve} uses Handlebars templates to render notifications. The original templates
original templates provided by {pve} are stored in provided by {pve} are stored in `/usr/share/pve-manager/templates/default/`.
`/usr/share/pve-manager/templates/default/`.
Notification templates can be overridden by providing a custom template Notification templates can be overridden by providing a custom template file in
file in the override directory at `/etc/pve/notification-templates/default/`. the override directory at `/etc/pve/notification-templates/default/`. When
When rendering a notification of a given type, {pve} will first attempt rendering a notification of a given type, {pve} will first attempt to load a
to load a template from the override directory. If this one does not template from the override directory. If this one does not exist or fails to
exist or fails to render, the original template will be used. render, the original template will be used.
The template files follow the naming convention of The template files follow the naming convention of
`<type>-<body|subject>.<html|txt>.hbs`. For instance, the file `<type>-<body|subject>.<html|txt>.hbs`. For instance, the file
`vzdump-body.html.hbs` contains the template for rendering the HTML version `vzdump-body.html.hbs` contains the template for rendering the HTML version for
for backup notifications, while `package-updates-subject.txt.hbs` is used to backup notifications, while `package-updates-subject.txt.hbs` is used to render
render the subject line of notifications for available package updates. the subject line of notifications for available package updates.
Email-based notification targets, such as `sendmail` and `smtp`, always send Email-based notification targets, such as `sendmail` and `smtp`, always send
multi-part messages with an HTML and a plain text part. As a result, both multi-part messages with an HTML and a plain text part. As a result, both the
the `<type>-body.html.hbs` as well as the `<type>-body.txt.hbs` template `<type>-body.html.hbs` as well as the `<type>-body.txt.hbs` template will be
will be used when rendering the email message. All other notification used when rendering the email message. All other notification target types only
target types only use the `<type>-body.txt.hbs` template. use the `<type>-body.txt.hbs` template.