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