ntfy - Push Notification Service

Table of Contents

As your home lab grows and the user base of your services increase it gets more and more important to know what’s happening on your machines.
Doesn’t being notified when your backups fail or one of your services go down sound nice? You can achieve exactly that with the use of a push notification service like ntfy.

What is ntfy?
#

ntfy is an open source HTTP-based push notification service, letting you send notifications to your devices via scripts. It can either be used as Web App or as Mobile App for Android and iOS.

Installation
#

First create the database for persistent message caching.

sudo touch /path/to/ntfy/cache/cache.db

Change /path/to/ntfy/cache according to your setup.

Use the provided docker-compose.yml to install ntfy with message cache included.

version: "2.1"

services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    command:
      - serve
    environment:
      - TZ=Europe/Berlin    # optional: set desired timezone
      - NTFY_BEHIND_PROXY=true
      - NTFY_CACHE_FILE=/var/cache/ntfy/cache.db
      - NTFY_CACHE_DURATION=168h
#    user: 1000:1000 # optional: replace with your own user/group or uid/gid
    volumes:
      - /path/to/ntfy/cache:/var/cache/ntfy
      - /path/to/ntfy:/etc/ntfy
    ports:
      - <PORT>:80
    restart: unless-stopped

Change TZ, /path/to/ntfy/cache, /path/to/ntfy and <PORT> according to your setup.

Spin the container up with

docker-compose up -d

How does it work?
#

With ntfy you can send push notifications via simple HTTP PUT/POST statements to any of your devices. Download the app to start receiving notifications on your phone.

First you need to configure the mobile app to use it with your own ntfy installation.

Default Server — Set the URL/IP Address of your ntfy installation.

Create a new topic for your notifications.

Set the name of your topic.

You are now able to send and receive notifications of the newly created topic, see the next chapter for some script examples.

The topic has to be added to the web app too if you want to receive the notifications there.

Examples
#

Notification on low disk space
#

Get notified when the disk space of your machine runs low.

#!/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
THRESHOLD=85 # In percent, change if needed

df -H | grep /dev/loop* | awk '{ print $5 " " $1 }' | while read -r output;
do
  usep=$(echo "$output" | awk '{ print $1}' | cut -d'%' -f1 )
  if [ "$usep" -ge $THRESHOLD ]; then
          curl \
  -H "Title: $(hostname) running out of space" \
  -H "Priority: high" \
  -H "Tags: warning" \
  -d "$(hostname) is almost out of disk space ($usep%)" \
  https://ntfy.domain.tld/topic
  fi
done

Edit THRESHOLD and https://ntfy.domain.tld according to your setup.

Notification on unauthorized SSH login
#

Receive notifications on unauthorized SSH logins on your machine.
First edit /etc/pam.d/sshd and add session optional pam_exec.so /path/to/ntfy-ssh-login.sh to the end of the file.

Replace /path/to/ntfy-ssh-login.sh with the actual path to your script.

Then create the bash script ntfy-ssh-login.sh

#!/bin/bash
if [[ "${PAM_TYPE}" = "open_session" && "${PAM_RHOST}" != "<EXCLUDE_IP_1>" && "${PAM_RHOST}" != "<EXCLUDE_IP_2>" ]]; then
  curl \
    -H prio:high \
    -H tags:warning,skull \
    -d "SSH login on $(hostname): ${PAM_USER} from ${PAM_RHOST}" \
    https://ntfy.domain.tld/topic
fi

Change <EXCLUDE_IP_*> to exclude the IP Address of your local machine(s) and https://ntfy.domain.tld to the actual URL/IP Address of your ntfy installation. Don’t forget to make the script executable with sudo chmod +x ntfy-ssh-login.sh.

For more examples on using ntfy within scripts, cronjobs or third party applications check out the project page.

Final thoughts
#

ntfy is a lightweight, simple and reliable solution to stay on top of what’s happening in your home lab.
It has quickly become one of my most used services, so I encourage you to give it a try and at least check out the free public version.

Don’t forget to leave a ⭐ in the ntfy GitHub Repo to appreciate the great work.

What is ntfy? #

Installation #

How does it work? #

Examples #

Notification on low disk space #

Notification on unauthorized SSH login #

Final thoughts #