netdata/health/notifications/ntfy

ntfy

ntfy (pronounce: notify) is a simple HTTP-based pub-sub notification service. It allows you to send notifications to your phone or desktop via scripts from any computer, entirely without signup, cost or setup. It's also open source if you want to run your own server. You can send alerts to an ntfy server using Netdata's Agent alert notification feature, which supports dozens of endpoints, user roles, and more.

Setup

Prerequisites

• (Optional) A self-hosted ntfy server, in case you don't want to use https://ntfy.sh
• A new topic for the notifications to be published to
• Access to the terminal where Netdata Agent is running

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.

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

Config Options

| Name | Description | Default | Required | |:----|:-----------|:-------|:--------:| | SEND_NTFY | Set `SEND_NTFY` to YES | YES | yes | | DEFAULT_RECIPIENT_NTFY | URL formed by the server-topic combination you want the alert notifications to be sent to. Unless hosting your own server, the server should always be set to https://ntfy.sh. | | yes | | NTFY_USERNAME | The username for netdata to use to authenticate with an ntfy server. | | no | | NTFY_PASSWORD | The password for netdata to use to authenticate with an ntfy server. | | no | | NTFY_ACCESS_TOKEN | The access token for netdata to use to authenticate with an ntfy server. | | no | ##### DEFAULT_RECIPIENT_NTFY You can define multiple recipient URLs like this: `https://SERVER1/TOPIC1` `https://SERVER2/TOPIC2` All roles will default to this variable if left unconfigured. You can then have different servers and/or topics per role, by editing DEFAULT_RECIPIENT_NTFY with the server-topic combination you want, in the following entries at the bottom of the same file: ```conf role_recipients_ntfy[sysadmin]="https://SERVER1/TOPIC1" role_recipients_ntfy[domainadmin]="https://SERVER2/TOPIC2" role_recipients_ntfy[dba]="https://SERVER3/TOPIC3" role_recipients_ntfy[webmaster]="https://SERVER4/TOPIC4" role_recipients_ntfy[proxyadmin]="https://SERVER5/TOPIC5" role_recipients_ntfy[sitemgr]="https://SERVER6/TOPIC6" ``` ##### NTFY_USERNAME Only useful on self-hosted ntfy instances. See [users and roles](https://docs.ntfy.sh/config/#users-and-roles) for details. Ensure that your user has proper read/write access to the provided topic in `DEFAULT_RECIPIENT_NTFY` ##### NTFY_PASSWORD Only useful on self-hosted ntfy instances. See [users and roles](https://docs.ntfy.sh/config/#users-and-roles) for details. Ensure that your user has proper read/write access to the provided topic in `DEFAULT_RECIPIENT_NTFY` ##### NTFY_ACCESS_TOKEN This can be used in place of `NTFY_USERNAME` and `NTFY_PASSWORD` to authenticate with a self-hosted ntfy instance. See [access tokens](https://docs.ntfy.sh/config/?h=access+to#access-tokens) for details. Ensure that the token user has proper read/write access to the provided topic in `DEFAULT_RECIPIENT_NTFY`

Examples

Basic Configuration

SEND_NTFY="YES"
DEFAULT_RECIPIENT_NTFY="https://ntfy.sh/netdata-X7seHg7d3Tw9zGOk https://ntfy.sh/netdata-oIPm4IK1IlUtlA30"

Troubleshooting

Test Notification

You can run the following command by hand, to test alerts configuration:

# become user netdata
sudo su -s /bin/bash netdata

# enable debugging info on the console
export NETDATA_ALARM_NOTIFY_DEBUG=1

# send test alarms to sysadmin
/usr/libexec/netdata/plugins.d/alarm-notify.sh test

# send test alarms to any role
/usr/libexec/netdata/plugins.d/alarm-notify.sh test "ROLE"

Note that this will test all alert mechanisms for the selected role.