Send a Telegram Alert When Your Home Server’s /home Reaches 90% Usage With a Tiny systemd Service and curl

 Posted on October 16, 2026  |  2 minutes  |  412 words  |  Robert Nilsson

Monitoring /home Usage with a Systemd Timer

A home server rarely needs a full‑blown monitoring stack.
If you just want a quick alert when /home fills up, a tiny systemd service plus curl will do the trick. The example below keeps the footprint minimal, respects security best practices, and uses the official Telegram Bot API.

1. Create a Bot and Grab Credentials

  1. Talk to BotFather on Telegram and create a bot.
  2. Note the bot token (e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).
  3. Find your chat ID by sending a message to the bot and querying https://api.telegram.org/bot<token>/getUpdates.
  4. Store both values in a read‑only file:
sudo mkdir -p /etc/telegram-alert
sudo tee /etc/telegram-alert/credentials <<EOF
TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
CHAT_ID=987654321
EOF
sudo chmod 600 /etc/telegram-alert/credentials

2. Service Unit – home-usage-alert.service

# /etc/systemd/system/home-usage-alert.service
[Unit]
Description=Send Telegram alert when /home exceeds 90%% usage
After=network.target

[Service]
Type=oneshot
EnvironmentFile=/etc/telegram-alert/credentials
ExecStart=/usr/bin/bash -c '
  USAGE=$(df --output=pcent /home | tail -1 | tr -d "%")
  if [ "$USAGE" -ge 90 ]; then
    curl -s -X POST https://api.telegram.org/bot$TOKEN/sendMessage \
      -d chat_id=$CHAT_ID \
      -d text="⚠️ /home is at ${USAGE}%% capacity. Free space needed." \
      -H "Content-Type: application/x-www-form-urlencoded"
  fi
'
PrivateTmp=yes
ProtectSystem=full
RestrictAddressFamilies=AF_INET AF_INET6
Restart=no

[Install]
WantedBy=multi-user.target

Security notes

  • EnvironmentFile is read‑only and owned by root, so the token never leaks to other users.
  • PrivateTmp isolates /tmp for the service.
  • ProtectSystem=full mounts the filesystem read‑only except for /var.
  • RestrictAddressFamilies limits network families, reducing surface area.

3. Timer Unit – home-usage-alert.timer

# /etc/systemd/system/home-usage-alert.timer
[Unit]
Description=Run home-usage-alert.service every 15 minutes

[Timer]
OnCalendar=*-*-* 00/15:00:00
Persistent=true

[Install]
WantedBy=timers.target

The timer triggers the service every 15 minutes. Adjust OnCalendar to fit your tolerance.

4. Enable and Test

sudo systemctl daemon-reload
sudo systemctl enable --now home-usage-alert.timer
sudo systemctl status home-usage-alert.timer

Force a check:

sudo systemctl start home-usage-alert.service

Verify the message in Telegram. If nothing arrives, inspect logs:

journalctl -u home-usage-alert.service -b

Common pitfalls

IssueFix
Token or chat ID wrongRe‑create the bot or re‑fetch the chat ID.
curl not foundInstall curl (sudo apt install curl).
Service fails silentlyEnsure the script exits with status 0; add set -e for safety.

5. Optional Enhancements

  • Rate limiting: add a lock file or systemd Persistent=true to avoid flooding if /home stays above 90 %.
  • Multiple thresholds: extend the script to send different messages at 80 % and 95 %.
  • Logging: pipe curl output to /var/log/home-usage-alert.log for audit.

The solution stays within the systemd ecosystem, uses only curl (already present on most distros), and keeps credentials protected. It’s a practical, low‑maintenance way to stay informed about disk usage on a home server.

linux  systemd  monitoring  telegram  security 

See also