diff options
Diffstat (limited to 'health/notifications/email/README.md')
-rw-r--r-- | health/notifications/email/README.md | 129 |
1 files changed, 82 insertions, 47 deletions
diff --git a/health/notifications/email/README.md b/health/notifications/email/README.md index e59e268a51..2470ac4d77 100644 --- a/health/notifications/email/README.md +++ b/health/notifications/email/README.md @@ -1,56 +1,83 @@ -<!-- -title: "Email agent alert notifications" -sidebar_label: "Email" -custom_edit_url: "https://github.com/netdata/netdata/edit/master/health/notifications/email/README.md" -learn_status: "Published" -learn_topic_type: "Tasks" -learn_rel_path: "Integrations/Notify/Agent alert notifications" -learn_autogeneration_metadata: "{'part_of_cloud': True, 'part_of_agent': True}" ---> +# Email Agent alert notifications -# Email agent alert notifications +Learn how to send notifications via Email using Netdata's Agent alert notification feature, which supports dozens of endpoints, user roles, and more. -You need a working `sendmail` command for email alerts to work. Almost all MTAs provide a `sendmail` interface. +> ### Note +> +> This file assumes you have read the [Introduction to Agent alert notifications](https://github.com/netdata/netdata/blob/master/health/notifications/README.md), detailing how the Netdata Agent's alert notification method works. -Netdata sends all emails as user `netdata`, so make sure your `sendmail` works for local users. +Email notifications look like this: -If you are using our Docker images, or are running Netdata on a system that does not have a working `sendmail` -command, see [the section below about using msmtp in place of sendmail](#using-msmtp-instead-of-sendmail). +<img src="https://user-images.githubusercontent.com/1905463/133216974-a2ca0e4f-787b-4dce-b1b2-9996a8c5f718.png" alt="Email notification screenshot" width="50%"></img> -email notifications look like this: +## Prerequisites -![image](https://user-images.githubusercontent.com/1905463/133216974-a2ca0e4f-787b-4dce-b1b2-9996a8c5f718.png) +You will need: -## Configuration +- A working `sendmail` command for email alerts to work. Almost all MTAs provide a `sendmail` interface. + Netdata sends all emails as user `netdata`, so make sure your `sendmail` works for local users. -To edit `health_alarm_notify.conf` on your system run `/etc/netdata/edit-config health_alarm_notify.conf`. + > ### Note + > + > If you are using our Docker images, or are running Netdata on a system that does not have a working `sendmail` command, see [the section below about using msmtp in place of sendmail](#using-msmtp-instead-of-sendmail). +- terminal access to the Agent you wish to configure -You can configure recipients in [`/etc/netdata/health_alarm_notify.conf`](https://github.com/netdata/netdata/blob/99d44b7d0c4e006b11318a28ba4a7e7d3f9b3bae/conf.d/health_alarm_notify.conf#L101). +## Configure Netdata to send alerts via Email -You can also configure per role recipients [in the same file, a few lines below](https://github.com/netdata/netdata/blob/99d44b7d0c4e006b11318a28ba4a7e7d3f9b3bae/conf.d/health_alarm_notify.conf#L313). +> ### Info +> +> This file mentions editing configuration files. +> +> - To edit configuration files in a safe way, we provide the [`edit config` script](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files) located in your [Netdata config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) (typically is `/etc/netdata`) that creates the proper file and opens it in an editor automatically. +> Note that to run the script you need to be inside your Netdata config directory. +> +> It is recommended to use this way for configuring Netdata. -Changes to this file do not require a Netdata restart. +Edit `health_alarm_notify.conf`, changes to this file do not require restarting Netdata: -You can test your configuration by issuing the commands: +1. You can change `EMAIL_SENDER` to the email address sending the notifications, the default is the system user Netdata runs as, usually being `netdata`. + Supported formats are: -```sh -# become user netdata -sudo su -s /bin/bash netdata + ```conf + EMAIL_SENDER="user@domain" + EMAIL_SENDER="User Name <user@domain>" + EMAIL_SENDER="'User Name' <user@domain>" + EMAIL_SENDER="\"User Name\" <user@domain>" + ``` -# send a test alarm -/usr/libexec/netdata/plugins.d/alarm-notify.sh test [ROLE] +2. Set `SEND_EMAIL` to `YES`. +3. Set `DEFAULT_RECIPIENT_EMAIL` to the email address you want the email to be sent by default. + You can define multiple email addresses like this: `alarms@example.com systems@example.com`. + All roles will default to this variable if left unconfigured. +4. There are also other optional configuration entries that can be found in the same section of the file. + +You can then have different email addresses per **role**, by editing `DEFAULT_RECIPIENT_EMAIL` with the email address you want, in the following entries at the bottom of the same file: + +```conf +role_recipients_email[sysadmin]="systems@example.com" +role_recipients_email[domainadmin]="domains@example.com" +role_recipients_email[dba]="databases@example.com systems@example.com" +role_recipients_email[webmaster]="marketing@example.com development@example.com" +role_recipients_email[proxyadmin]="proxy-admin@example.com" +role_recipients_email[sitemgr]="sites@example.com" ``` -Where `[ROLE]` is the role you want to test. The default (if you don't give a `[ROLE]`) is `sysadmin`. +An example of a working configuration would be: -Note that in versions before 1.16, the plugins.d directory may be installed in a different location in certain OSs (e.g. under `/usr/lib/netdata`). -You can always find the location of the alarm-notify.sh script in `netdata.conf`. +```conf +#------------------------------------------------------------------------------ +# email global notification options + +EMAIL_SENDER="example@domain.com" +SEND_EMAIL="YES" +DEFAULT_RECIPIENT_EMAIL="recipient@example.com" +``` -## Filtering +### Filtering Every notification email (both the plain text and the rich html versions) from the Netdata agent, contain a set of custom email headers that can be used for filtering using an email client. Example: -``` +```conf X-Netdata-Severity: warning X-Netdata-Alert-Name: inbound_packets_dropped_ratio X-Netdata-Chart: net_packets.enp2s0 @@ -60,7 +87,7 @@ X-Netdata-Host: winterland X-Netdata-Role: sysadmin ``` -## Using msmtp instead of sendmail +### Using msmtp instead of sendmail [msmtp](https://marlam.de/msmtp/) provides a simple alternative to a full-blown local mail server and `sendmail` that will still allow you to send email notifications. It comes pre-installed in our Docker images, and is available @@ -68,21 +95,29 @@ on most distributions in the system package repositories. To use msmtp with Netdata for sending email alerts: -1. If it’s not already installed, install msmtp. Most distributions have it in their package repositories with the - package name `msmtp`. +1. If it’s not already installed, install msmtp. Most distributions have it in their package repositories with the package name `msmtp`. 2. Modify the `sendmail` path in `health_alarm_notify.conf` to point to the location of `msmtp`: -``` -# The full path to the sendmail command. -# If empty, the system $PATH will be searched for it. -# If not found, email notifications will be disabled (silently). -sendmail="/usr/bin/msmtp" -``` + + ```conf + # The full path to the sendmail command. + # If empty, the system $PATH will be searched for it. + # If not found, email notifications will be disabled (silently). + sendmail="/usr/bin/msmtp" + ``` + 3. Login as netdata: -```sh -(sudo) su -s /bin/bash netdata -``` + + ```sh + (sudo) su -s /bin/bash netdata + ``` + 4. Configure `~/.msmtprc` as shown [in the documentation](https://marlam.de/msmtp/documentation/). 5. Finally set the appropriate permissions on the `.msmtprc` file : -```sh -chmod 600 ~/.msmtprc -``` + + ```sh + chmod 600 ~/.msmtprc + ``` + +## Test the notification method + +To test this alert notification method refer to the ["Testing Alert Notifications"](https://github.com/netdata/netdata/blob/master/health/notifications/README.md#testing-alert-notifications) section of the Agent alert notifications page. |