[[chapter_notifications]] Notifications ============= ifndef::manvolnum[] :pve-toplevel: endif::manvolnum[] Overview -------- [thumbnail="screenshot/gui-datacenter-notification-overview.png"] {pve} will send notifications if case of noteworthy events in the system. There are a number of different xref:notification_events[notification events], each with their own set of metadata fields that can be used in notification matchers. A xref:notification_matchers[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 configurable set of notification targets. A xref:notification_targets[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 Datacenter -> Notifications. The configuration is stored in `/etc/pve/notifications.cfg` and `/etc/pve/priv/notifications.cfg` - the latter contains sensitive configuration options such as passwords or authentication tokens for notification targets. [[notification_targets]] Notification Targets -------------------- [[notification_targets_sendmail]] Sendmail ~~~~~~~~ [thumbnail="screenshot/gui-datacenter-notification-sendmail.png"] 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. NOTE: In standard {pve} installations, the `sendmail` binary is provided by Postfix. For this type of target to work correctly, it might be necessary to change Postfix's configuration so that it can correctly deliver emails. For cluster setups it is necessary to have a working Postfix configuration on every single cluster node. The configuration for Sendmail target plugins has the following options: * `mailto`: E-Mail address to which the notification shall be sent to. Can be set multiple times to accomodate multiple recipients. * `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 accomodate multiple recipients. * `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 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 `root@$hostname`, where `$hostname` is the hostname of the node. * `comment`: Comment for this target The `From` header in the email will be set to `$author <$from-address>`. Example configuration (`/etc/pve/notifications.cfg`): ---- sendmail: example mailto-user root@pam mailto-user admin@pve mailto max@example.com from-address pve1@example.com comment Send to multiple users/addresses ---- [[notification_targets_smtp]] SMTP ~~~~ [thumbnail="screenshot/gui-datacenter-notification-smtp.png"] SMTP notification targets can send emails directly to an SMTP mail relay. The configuration for SMTP target plugins has the following options: * `mailto`: E-Mail address to which the notification shall be sent to. Can be set multiple times to accomodate multiple recipients. * `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 accomodate multiple recipients. * `author`: Sets the author of the E-Mail. Defaults to `Proxmox VE`. * `from-address`: Sets the From-addresss of the email. SMTP relays might require that this address is owned by the user in order to avoid spoofing. The `From` header in the email will be set to `$author <$from-address>`. * `username`: Username to use during authentication. If no username is set, no authentication will be performed. The PLAIN and LOGIN authentication methods are supported. * `password`: Password to use when authenticating. * `mode`: Sets the encryption mode (`insecure`, `starttls` or `tls`). Defaults to `tls`. * `server`: Address/IP of the SMTP relay * `port`: The port to connect to. If not set, the used port defaults to 25 (`insecure`), 465 (`tls`) or 587 (`starttls`), depending on the value of `mode`. * `comment`: Comment for this target Example configuration (`/etc/pve/notifications.cfg`): ---- smtp: example mailto-user root@pam mailto-user admin@pve mailto max@example.com from-address pve1@example.com username pve1 server mail.example.com mode starttls ---- The matching entry in `/etc/pve/priv/notifications.cfg`, containing the secret token: ---- smtp: example password somepassword ---- [[notification_targets_gotify]] Gotify ~~~~~~ [thumbnail="screenshot/gui-datacenter-notification-gotify.png"] http://gotify.net[Gotify] is an open-source self-hosted notification server that allows you to send and receive 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. The configuration for Gotify target plugins has the following options: * `server`: The base URL of the Gotify server, e.g. `http://:8888` * `token`: The authentication token. Tokens can be generated within the Gotify web interface. * `comment`: Comment for this target NOTE: The Gotify target plugin will respect the HTTP proxy settings from the xref:datacenter_configuration_file[datacenter configuration] Example configuration (`/etc/pve/notifications.cfg`): ---- gotify: example server http://gotify.example.com:8888 comment Send to multiple users/addresses ---- The matching entry in `/etc/pve/priv/notifications.cfg`, containing the secret token: ---- gotify: example token somesecrettoken ---- [[notification_matchers]] Notification Matchers --------------------- [thumbnail="screenshot/gui-datacenter-notification-matcher.png"] 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 any matching rules is always true; the configured targets will always be notified. ---- matcher: always-matches target admin comment This matcher always matches ---- Matcher Options ~~~~~~~~~~~~~~~ * `target`: Determine which target should be notified if the matcher matches. can be used multiple times to notify multiple targets. * `invert-match`: Inverts the result of the whole matcher * `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 match. If set to `any`, at least one rule must match. a matcher must be true. Defaults to `all`. * `match-calendar`: Match the notification's timestamp against a schedule * `match-field`: Match the notification's metadata fields * `match-severity`: Match the notification's severity * `comment`: Comment for this matcher [[notification_matchers_calendar]] Calendar Matching Rules ~~~~~~~~~~~~~~~~~~~~~~~ A calendar matcher matches the time when a notification is sent agaist a configurable schedule. * `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` [[notification_matchers_field]] Field Matching Rules ~~~~~~~~~~~~~~~~~~~~ Notifications have a selection of metadata fields that can be matched. * `match-field exact:type=vzdump` Only match notifications about backups. * `match-field regex:hostname=^.+\.example\.com$` Match the hostname of the node. If a matched metadata field does not exist, the notification will not be matched. For instance, a `match-field regex:hostname=.*` directive will only match notifications that have an arbitraty `hostname` metadata field, but will not match if the field does not exist. [[notification_matchers_severity]] Severity Matching Rules ~~~~~~~~~~~~~~~~~~~~~~~ A notification has a associated severity that can be matched. * `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`. Examples ~~~~~~~~ ---- matcher: workday match-calendar mon-fri 9-17 target admin comment Notify admins during working hours matcher: night-and-weekend match-calendar mon-fri 9-17 invert-match true target on-call-admins comment Separate target for non-working hours ---- ---- matcher: backup-failures match-field exact:type=vzdump match-severity error target backup-admins comment Send notifications about backup failures to one group of admins matcher: cluster-failures match-field exact:type=replication match-field exact:type=fencing mode any target cluster-admins comment Send cluster-related notifications to other group of admins ---- The last matcher could also be rewritten using a field matcher with a regular expression: ---- matcher: cluster-failures match-field regex:type=^(replication|fencing)$ target cluster-admins comment Send cluster-related notifications to other group of admins ---- [[notification_events]] Notification Events ------------------- [width="100%",options="header"] |=========================================================================== | Event | `type` | Severity | Metadata fields (in addition to `type`) | System updates available |`package-updates` | `info` | `hostname` | Cluster node fenced |`fencing` | `error` | `hostname` | Storage replication failed |`replication` | `error` | - | Backup finished |`vzdump` | `info` (`error` on failure) | `hostname` | Mail for root |`system-mail` | `unknown`| - |=========================================================================== [width="100%",options="header"] |======================================================================= | Field name | Description | `type` | Type of the notifcation | `hostname` | Hostname, including domain (e.g. `pve1.example.com`) |======================================================================= System Mail Forwarding --------------------- Certain local system daemons, such as `smartd`, generate notification emails that are initially directed to the local `root` user. {pve} will feed these mails into the notification system as a notification of type `system-mail` and with severity `unknown`. When the forwarding process involves an email-based target (like `sendmail` or `smtp`), the email is forwarded exactly as received, with all original mail headers remaining intact. 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 `Mapping.Modify/Mapping.Audit` permissions are required for the `/mapping/notifications` ACL node. Testing a target requires `Mapping.Use`, `Mapping.Audit` or `Mapping.Modify` permissions on `/mapping/notifications`