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:

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 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 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 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.