qm: add overrule-shutdown to CLI usage examples

[pve-docs.git] / notifications.adoc

diff --git a/notifications.adoc b/notifications.adoc
index e8ed51b7e462b636cac736b0ec45d794e685f5e3..46aff6a482dfc7ec1a4d12c2e81a7cd605c69fbf 100644 (file)
--- a/notifications.adoc
+++ b/notifications.adoc
@@ -7,6 +7,7 @@ endif::manvolnum[]
 
 Overview
 --------
+[thumbnail="screenshot/gui-datacenter-notification-overview.png"]
 
 {pve} will send notifications if case of noteworthy events in the system.
 
@@ -39,8 +40,11 @@ passwords or authentication tokens for 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
@@ -80,8 +84,10 @@ sendmail: example
         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.
 
@@ -126,8 +132,10 @@ 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
@@ -161,12 +169,14 @@ gotify: example
 [[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.
@@ -196,6 +206,7 @@ a matcher must be true. Defaults to `all`.
 * `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
@@ -206,6 +217,7 @@ configurable schedule.
 * `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.
@@ -220,6 +232,7 @@ 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.
@@ -228,7 +241,7 @@ 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
@@ -281,6 +294,7 @@ Notification Events
 | 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"]
@@ -290,14 +304,27 @@ Notification Events
 | `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`