Overview
--------
+[thumbnail="screenshot/gui-datacenter-notification-overview.png"]
{pve} will send notifications if case of noteworthy events in the system.
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
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`):
----
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
* `server`: The base URL of the Gotify server, e.g. `http://<ip>: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]
[[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 of certain properties of
-a notification, such as the timestamp (`match-calendar`), the severity of
-the notificaiton (`match-severity`) or metadata fiels (`match-field`).
-If a matcher matches a notification, all targets configured for the matcher
-will receive the notification.
+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.
* `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
* `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.
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 warning,error`: Match warnings and error
The following severities are in use:
-`info`, `notice`, `warning`, `error`.
+`info`, `notice`, `warning`, `error`, `unknown`.
Examples
| 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"]
| `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
-----------
-For every target, there exists a corresponding ACL path
-`/mapping/notification/targets/<name>`. Matchers use
-a seperate namespace in the ACL tree: `/mapping/notification/matchers/<name>`.
+In order to modify/view the configuration for notification targets,
+the `Mapping.Modify/Mapping.Audit` permissions are required for the
+`/mapping/notifications` ACL node.
-To test a target, a user must have the `Mapping.Use` permission on the corresponding
-node in the ACL tree.
-`Mapping.Modify` and `Mapping.Audit` are needed to read/modify the
-configuration of a target or matcher.
+Testing a target requires `Mapping.Use`, `Mapping.Audit` or `Mapping.Modify`
+permissions on `/mapping/notifications`
projects / pve-docs.git / blobdiff