]>
Commit | Line | Data |
---|---|---|
1ba1e952 LW |
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 |