notifications.adoc

   1 [[chapter_notifications]]
   2 Notifications
   3 =============
   4 ifndef::manvolnum[]
   5 :pve-toplevel:
   6 endif::manvolnum[]
   7
   8 [[notification_events]]
   9 Notification Events
  10 -------------------
  11
  12 {pve} will attempt to notify system administrators in case of certain events,
  13 such as:
  14
  15 [width="100%",options="header"]
  16 |===========================================================================
  17 | Event name        | Description                             | Severity
  18 | `package-updates` | System updates are available            | `info`
  19 | `fencing`         | The {pve} HA manager has fenced a node  | `error`
  20 | `replication`     | A storage replication job has failed    | `error`
  21 | `vzdump`          | vzdump backup finished                  | `info` (`error` on failure)
  22 |===========================================================================
  23
  24 In the 'Notification' panel of the datacenter view, the system's behavior can be
  25 configured for all events except backup jobs. For backup jobs,
  26 the settings can be found in the respective backup job configuration.
  27 For every notification event there is an option to configure the notification
  28 behavior (*when* to send a notification) and the notification target (*where* to
  29 send the notification).
  30
  31
  32 See also:
  33
  34 * xref:datacenter_configuration_file[Datacenter Configuration]
  35 * xref:datacenter_configuration_file[vzdump]
  36
  37 [[notification_targets]]
  38 Notification Targets
  39 --------------------
  40
  41 Notification targets can be configured in the 'Notification Targets' panel.
  42
  43 NOTE: The `mail-to-root` target is always available and cannot be modified or
  44 removed. It sends a mail the `root@pam` user by using the `sendmail` command and
  45 serves as a fallback target if no other target is configured for an event.
  46
  47 Sendmail
  48 ~~~~~~~~
  49 The sendmail binary is a program commonly found on Unix-like operating systems
  50 that handles the sending of email messages.
  51 It is a command-line utility that allows users and applications to send emails
  52 directly from the command line or from within scripts.
  53
  54 The sendmail notification target uses the `sendmail` binary to send emails.
  55
  56
  57 NOTE: In standard {pve} installations, the `sendmail` binary is provided by
  58 Postfix. For this type of target to work correctly, it might be necessary to
  59 change Postfix's configuration so that it can correctly deliver emails.
  60 For cluster setups it is necessary to have a working Postfix configuration on
  61 every single cluster node.
  62
  63 The configuration for Sendmail target plugins has the following options:
  64
  65 * `mailto`: E-Mail address to which the notification shall be sent to. Can be
  66 set multiple times to accomodate multiple recipients.
  67 * `mailto-user`: Users to which emails shall be sent to. The user's email
  68 address will be looked up in `users.cfg`. Can be set multiple times to
  69 accomodate multiple recipients.
  70 * `author`: Sets the author of the E-Mail. Defaults to `Proxmox VE`.
  71 * `from-address`: Sets the from address of the E-Mail. If the parameter is not
  72 set, the plugin will fall back to the `email_from` setting from
  73 `datacenter.cfg`. If that is also not set, the plugin will default to
  74 `root@$hostname`, where `$hostname` is the hostname of the node.
  75
  76 * `filter`: The name of the filter to use for this target.
  77
  78 Gotify
  79 ~~~~~~
  80
  81 http://gotify.net[Gotify] is an open-source self-hosted notification server that
  82 allows you to send and receive push notifications to various devices and
  83 applications. It provides a simple API and web interface, making it easy to
  84 integrate with different platforms and services.
  85
  86 The configuration for Gotify target plugins has the following options:
  87
  88 * `server`: The base URL of the Gotify server, e.g. `http://<ip>:8888`
  89 * `token`: The authentication token. Tokens can be generated within the Gotify
  90 web interface.
  91 * `filter`: The name of the filter to use for this target.
  92
  93 NOTE: The Gotify target plugin will respect the HTTP proxy settings from the
  94  xref:datacenter_configuration_file[datacenter configuration]
  95
  96 Group
  97 ~~~~~
  98
  99 One can only select a single target for notification events.
 100 To notify via multiple targets at the same time, a group can be created.
 101 A group can reference multiple targets. If a group is used as a target,
 102 the notification will be sent to all referenced targets. Groups can reference
 103 all targets except other groups.
 104
 105
 106 Notification Filters
 107 --------------------
 108 A notification target can be configured to use a *notification filter*.
 109 If a notification is sent to a target with a filter, the
 110 filter will determine if the notification will be actually sent or not.
 111
 112 The following matchers are available:
 113
 114 * `min-severity`: Matches notifications with equal or higher severity
 115
 116 It is also possible to configure the evaluation of the individual matchers:
 117
 118 * `invert-match`: Inverts the result of the whole filter
 119 * `mode`: Sets the logical operator used to connect the individual matchers to
 120 `and` or `or`. Defaults to `and`.
 121
 122 The `mode` option also influences the evaluation of filters without any
 123 matchers. If set to `or`, an empty filter evaluates to `false` (do not notify).
 124 If set to `and`, the result is `true` (send a notification).
 125 ----
 126 filter: always-matches
 127     mode and
 128
 129 filter: never-matches
 130     mode or
 131 ----
 132
 133 Permissions
 134 -----------
 135
 136 For every target or filter, there exists a corresponding ACL path
 137 `/mapping/notification/<name>`.
 138 If an operation can be triggered by a user (e.g. via the GUI or API) and if
 139 that operation is configured to notify via a given target, then
 140 the user must have the `Mapping.Use` permission on the corresponding
 141 node in the ACL tree.
 142 `Mapping.Modify` and `Mapping.Audit` are needed for
 143 writing/reading the configuration of a target or filter.
 144
 145 NOTE: For backwards-compatibility, the special `mail-to-root` target
 146 does not require `Mapping.Use`.
 147
 148 NOTE: When sending notifications via a group target,
 149 the user must have the `Mapping.Use` permission for every single endpoint
 150 included in the group. If a group/endpoint is configured to
 151 use a filter, the user must have the `Mapping.Use` permission for the filter
 152 as well.
 153
 154
 155
 156
 157
 158
 159