From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 58B90EEFB for ; Thu, 20 Jul 2023 16:33:34 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id A5F3014D20 for ; Thu, 20 Jul 2023 16:33:20 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS for ; Thu, 20 Jul 2023 16:33:17 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 004CD41F0D for ; Thu, 20 Jul 2023 16:33:16 +0200 (CEST) From: Lukas Wagner To: pve-devel@lists.proxmox.com Date: Thu, 20 Jul 2023 16:32:36 +0200 Message-Id: <20230720143236.652292-70-l.wagner@proxmox.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230720143236.652292-1-l.wagner@proxmox.com> References: <20230720143236.652292-1-l.wagner@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -1.077 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_ASCII_DIVIDERS 0.8 Email that uses ascii formatting dividers and possible spam tricks KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment KAM_LINEPADDING 1.2 Spam that tries to get past blank line filters SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_SCC_BODY_TEXT_LINE -0.01 - Subject: [pve-devel] [PATCH v4 pve-docs 69/69] add documentation for the new notification system X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 20 Jul 2023 14:33:34 -0000 Signed-off-by: Lukas Wagner --- notifications.adoc | 159 +++++++++++++++++++++++++++++++++++++++++++ pve-admin-guide.adoc | 2 + pve-gui.adoc | 2 + vzdump.adoc | 5 ++ 4 files changed, 168 insertions(+) create mode 100644 notifications.adoc diff --git a/notifications.adoc b/notifications.adoc new file mode 100644 index 0000000..c4d2931 --- /dev/null +++ b/notifications.adoc @@ -0,0 +1,159 @@ +[[chapter_notifications]] +Notifications +============= +ifndef::manvolnum[] +:pve-toplevel: +endif::manvolnum[] + +[[notification_events]] +Notification Events +------------------- + +{pve} will attempt to notify system administrators in case of certain events, +such as: + +[width="100%",options="header"] +|=========================================================================== +| Event name | Description | Severity +| `package-updates` | System updates are available | `info` +| `fencing` | The {pve} HA manager has fenced a node | `error` +| `replication` | A storage replication job has failed | `error` +| `vzdump` | vzdump backup finished | `info` (`error` on failure) +|=========================================================================== + +In the 'Notification' panel of the datacenter view, the system's behavior can be +configured for all events except backup jobs. For backup jobs, +the settings can be found in the respective backup job configuration. +For every notification event there is an option to configure the notification +behavior (*when* to send a notification) and the notification target (*where* to +send the notification). + + +See also: + +* xref:datacenter_configuration_file[Datacenter Configuration] +* xref:datacenter_configuration_file[vzdump] + +[[notification_targets]] +Notification Targets +-------------------- + +Notification targets can be configured in the 'Notification Targets' panel. + +NOTE: The `mail-to-root` target is always available and cannot be modified or +removed. It sends a mail the `root@pam` user by using the `sendmail` command and +serves as a fallback target if no other target is configured for an event. + +Sendmail +~~~~~~~~ +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. + +* `filter`: The name of the filter to use for this target. + +Gotify +~~~~~~ + +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. +* `filter`: The name of the filter to use for this target. + +NOTE: The Gotify target plugin will respect the HTTP proxy settings from the + xref:datacenter_configuration_file[datacenter configuration] + +Group +~~~~~ + +One can only select a single target for notification events. +To notify via multiple targets at the same time, a group can be created. +A group can reference multiple targets. If a group is used as a target, +the notification will be sent to all referenced targets. Groups can reference +all targets except other groups. + + +Notification Filters +-------------------- +A notification target can be configured to use a *notification filter*. +If a notification is sent to a target with a filter, the +filter will determine if the notification will be actually sent or not. + +The following matchers are available: + +* `min-severity`: Matches notifications with equal or higher severity + +It is also possible to configure the evaluation of the individual matchers: + +* `invert-match`: Inverts the result of the whole filter +* `mode`: Sets the logical operator used to connect the individual matchers to +`and` or `or`. Defaults to `and`. + +The `mode` option also influences the evaluation of filters without any +matchers. If set to `or`, an empty filter evaluates to `false` (do not notify). +If set to `and`, the result is `true` (send a notification). +---- +filter: always-matches + mode and + +filter: never-matches + mode or +---- + +Permissions +----------- + +For every target or filter, there exists a corresponding ACL path +`/mapping/notification/`. +If an operation can be triggered by a user (e.g. via the GUI or API) and if +that operation is configured to notify via a given target, then +the user must have the `Mapping.Use` permission on the corresponding +node in the ACL tree. +`Mapping.Modify` and `Mapping.Audit` are needed for +writing/reading the configuration of a target or filter. + +NOTE: For backwards-compatibility, the special `mail-to-root` target +does not require `Mapping.Use`. + +NOTE: When sending notifications via a group target, +the user must have the `Mapping.Use` permission for every single endpoint +included in the group. If a group/endpoint is configured to +use a filter, the user must have the `Mapping.Use` permission for the filter +as well. + + + + + + + diff --git a/pve-admin-guide.adoc b/pve-admin-guide.adoc index 5bac3d6..ce21d8f 100644 --- a/pve-admin-guide.adoc +++ b/pve-admin-guide.adoc @@ -51,6 +51,8 @@ include::ha-manager.adoc[] include::vzdump.adoc[] +include::notifications.adoc[] + // Return to normal title levels. :leveloffset: 0 diff --git a/pve-gui.adoc b/pve-gui.adoc index e0fc873..9f63a7e 100644 --- a/pve-gui.adoc +++ b/pve-gui.adoc @@ -246,6 +246,8 @@ On the datacenter level, you can access cluster-wide settings and information. * *Metric Server:* define external metric servers for {pve}. +* *Notifications:* configurate notification behavior and targets for {pve}. + * *Support:* display information about your support subscription. diff --git a/vzdump.adoc b/vzdump.adoc index f3eadcd..a7c3d1e 100644 --- a/vzdump.adoc +++ b/vzdump.adoc @@ -552,6 +552,11 @@ Backup all guest systems and send notification mails to root and admin. # vzdump --all --mode suspend --mailto root --mailto admin +Backup guest 777 and notify via the `notify-admins` notification target on +failure. + + # vzdump 777 --notification-target notify-admins --notification-policy failure + Use snapshot mode (no downtime) and non-default dump directory. # vzdump 777 --dumpdir /mnt/backup --mode snapshot -- 2.39.2