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
 --------
 
 Overview
 --------

+[thumbnail="screenshot/gui-datacenter-notification-overview.png"]

 
 {pve} will send notifications if case of noteworthy events in the system.
 
 
 {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
 --------------------
 

+[[notification_targets_sendmail]]

 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
 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
 ----
 
         comment Send to multiple users/addresses
 ----
 

+[[notification_targets_smtp]]

 SMTP
 ~~~~
 SMTP
 ~~~~

+[thumbnail="screenshot/gui-datacenter-notification-smtp.png"]

 
 SMTP notification targets can send emails directly to an SMTP mail relay.
 
 
 SMTP notification targets can send emails directly to an SMTP mail relay.
 


@@ -126,8 +132,10 @@ smtp: example
         password somepassword
 ----
 
         password somepassword
 ----
 

+[[notification_targets_gotify]]

 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
 
 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
 ---------------------
 [[notification_matchers]]
 Notification Matchers
 ---------------------

+[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 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.
 
 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
 
 * `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
 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`
 
 * `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.
 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.
 
 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.
 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:
 * `match-severity warning,error`: Match warnings and error
 
 The following severities are in use:

-`info`, `notice`, `warning`, `error`.
+`info`, `notice`, `warning`, `error`, `unknown`.

 
 
 Examples
 
 
 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`
 | 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"]
 |===========================================================================
 
 [width="100%",options="header"]


@@ -290,14 +304,27 @@ Notification Events
 | `hostname` | Hostname, including domain (e.g. `pve1.example.com`)
 |=======================================================================
 
 | `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
 -----------
 
 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`