diff options
Diffstat (limited to 'health/notifications/email/README.md')
| -rw-r--r-- | health/notifications/email/README.md | 139 |
1 files changed, 90 insertions, 49 deletions
diff --git a/health/notifications/email/README.md b/health/notifications/email/README.md index 01dfd0e6..2470ac4d 100644 --- a/health/notifications/email/README.md +++ b/health/notifications/email/README.md @@ -1,53 +1,83 @@ -<!-- -title: "Email" -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: "Setup/Notification/Agent" -learn_autogeneration_metadata: "{'part_of_cloud': True, 'part_of_agent': True}" ---> +# Email Agent alert notifications -# Email +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: -email notifications look like this: +<img src="https://user-images.githubusercontent.com/1905463/133216974-a2ca0e4f-787b-4dce-b1b2-9996a8c5f718.png" alt="Email notification screenshot" width="50%"></img> - +## Prerequisites -## Configuration +You will need: -To edit `health_alarm_notify.conf` on your system run `/etc/netdata/edit-config health_alarm_notify.conf`. +- 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. -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). + > ### 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 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). +## Configure Netdata to send alerts via Email -Changes to this file do not require a Netdata restart. +> ### 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. -You can test your configuration by issuing the commands: +Edit `health_alarm_notify.conf`, changes to this file do not require restarting Netdata: -```sh -# become user netdata -sudo su -s /bin/bash netdata +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: -# send a test alarm -/usr/libexec/netdata/plugins.d/alarm-notify.sh test [ROLE] + ```conf + EMAIL_SENDER="user@domain" + EMAIL_SENDER="User Name <user@domain>" + EMAIL_SENDER="'User Name' <user@domain>" + EMAIL_SENDER="\"User Name\" <user@domain>" + ``` + +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: + +```conf +#------------------------------------------------------------------------------ +# email global notification options -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`. +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 @@ -57,26 +87,37 @@ X-Netdata-Host: winterland X-Netdata-Role: sysadmin ``` -## Simple SMTP transport configuration +### Using msmtp instead of sendmail -If you want an alternative to `sendmail` in order to have a simple MTA configuration for sending emails and auth to an existing SMTP server, you can do the following: +[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 +on most distributions in the system package repositories. -- Install `msmtp`. -- 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" -``` -- Login as netdata : -```sh -(sudo) su -s /bin/bash netdata -``` -- Configure `~/.msmtprc` as shown [in the documentation](https://marlam.de/msmtp/documentation/). -- Finally set the appropriate permissions on the `.msmtprc` file : -```sh -chmod 600 ~/.msmtprc -``` +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`. +2. Modify the `sendmail` path in `health_alarm_notify.conf` to point to the location of `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 + ``` + +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 + ``` +## 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. |