diff options
Diffstat (limited to 'health/notifications/email/README.md')
| -rw-r--r-- | health/notifications/email/README.md | 147 |
1 files changed, 69 insertions, 78 deletions
diff --git a/health/notifications/email/README.md b/health/notifications/email/README.md index 2470ac4d..ce31d7b8 100644 --- a/health/notifications/email/README.md +++ b/health/notifications/email/README.md @@ -1,58 +1,65 @@ -# Email Agent alert notifications +<!--startmeta +custom_edit_url: "https://github.com/netdata/netdata/edit/master/health/notifications/email/README.md" +meta_yaml: "https://github.com/netdata/netdata/edit/master/health/notifications/email/metadata.yaml" +sidebar_label: "Email" +learn_status: "Published" +learn_rel_path: "Alerting/Notifications/Agent Dispatched Notifications" +message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE NOTIFICATION'S metadata.yaml FILE" +endmeta--> -Learn how to send notifications via Email using Netdata's Agent alert notification feature, which supports dozens of endpoints, user roles, and more. +# Email -> ### 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. -Email notifications look like this: +<img src="https://netdata.cloud/img/email.png" width="150"/> -<img src="https://user-images.githubusercontent.com/1905463/133216974-a2ca0e4f-787b-4dce-b1b2-9996a8c5f718.png" alt="Email notification screenshot" width="50%"></img> -## Prerequisites +Send notifications via Email using Netdata's Agent alert notification feature, which supports dozens of endpoints, user roles, and more. -You will need: -- 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. - > ### 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 +<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" /> -## Configure Netdata to send alerts via Email +## Setup -> ### 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. +### Prerequisites -Edit `health_alarm_notify.conf`, changes to this file do not require restarting 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: +- A working sendmail command is required 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. +- Access to the terminal where Netdata Agent is running - ```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: +### Configuration +#### File + +The configuration file name for this integration is `health_alarm_notify.conf`. + + +You can edit the configuration file using the `edit-config` script from the +Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory). + +```bash +cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata +sudo ./edit-config health_alarm_notify.conf +``` +#### Options + +The following options can be defined for this notification + +<details><summary>Config Options</summary> + +| Name | Description | Default | Required | +|:----|:-----------|:-------|:--------:| +| EMAIL_SENDER | You can change `EMAIL_SENDER` to the email address sending the notifications. | netdata | False | +| SEND_EMAIL | Set `SEND_EMAIL` to YES | YES | True | +| DEFAULT_RECIPIENT_EMAIL | 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`. | root | True | + +##### DEFAULT_RECIPIENT_EMAIL + +All roles will default to this variable if left unconfigured. +The `DEFAULT_RECIPIENT_CUSTOM` can be edited 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" @@ -62,62 +69,46 @@ role_recipients_email[proxyadmin]="proxy-admin@example.com" role_recipients_email[sitemgr]="sites@example.com" ``` -An example of a working configuration would be: -```conf +</details> + +#### Examples + +##### Basic Configuration + + + +```yaml #------------------------------------------------------------------------------ # email global notification options EMAIL_SENDER="example@domain.com" SEND_EMAIL="YES" DEFAULT_RECIPIENT_EMAIL="recipient@example.com" -``` - -### 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 -X-Netdata-Family: enp2s0 -X-Netdata-Classification: System -X-Netdata-Host: winterland -X-Netdata-Role: sysadmin ``` -### 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 -on most distributions in the system package repositories. +## Troubleshooting -To use msmtp with Netdata for sending email alerts: +### Test Notification -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`: +You can run the following command by hand, to test alerts configuration: - ```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" - ``` +```bash +# become user netdata +sudo su -s /bin/bash netdata -3. Login as netdata: +# enable debugging info on the console +export NETDATA_ALARM_NOTIFY_DEBUG=1 - ```sh - (sudo) su -s /bin/bash netdata - ``` +# send test alarms to sysadmin +/usr/libexec/netdata/plugins.d/alarm-notify.sh test -4. Configure `~/.msmtprc` as shown [in the documentation](https://marlam.de/msmtp/documentation/). -5. Finally set the appropriate permissions on the `.msmtprc` file : +# send test alarms to any role +/usr/libexec/netdata/plugins.d/alarm-notify.sh test "ROLE" +``` - ```sh - chmod 600 ~/.msmtprc - ``` +Note that this will test _all_ alert mechanisms for the selected role. -## 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. |