Skip to main content

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

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
NameDescriptionDefaultRequired
SEND_NTFYSet SEND_NTFY to YESYESyes
DEFAULT_RECIPIENT_NTFYURL 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_USERNAMEThe username for netdata to use to authenticate with an ntfy server.no
NTFY_PASSWORDThe password for netdata to use to authenticate with an ntfy server.no
NTFY_ACCESS_TOKENThe 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.


Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.