Skip to main content
  1. Posts/

ntfy - Push Notification Service

·3 mins· loading ·
Self-hosting Application
Business Applications Architect, Network Engineer, Self-hosting Hobbyist.
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.


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"

    image: binwiederhier/ntfy
    container_name: ntfy
      - serve
      - TZ=Europe/Berlin    # optional: set desired timezone
      - NTFY_BEHIND_PROXY=true
      - NTFY_CACHE_FILE=/var/cache/ntfy/cache.db
#    user: 1000:1000 # optional: replace with your own user/group or uid/gid
      - /path/to/ntfy/cache:/var/cache/ntfy
      - /path/to/ntfy:/etc/ntfy
      - <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.

New Topic
Adding a new topic.

Set the name of your topic.

New Topic
Configuring new 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.


Notification on low disk space

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

THRESHOLD=85 # In percent, change if needed

df -H | grep /dev/loop* | awk '{ print $5 " " $1 }' | while read -r output;
  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%)" \
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 /path/to/ to the end of the file.

Replace /path/to/ with the actual path to your script.

Then create the bash script

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}" \
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

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.