internet-check: know when your connection drops

·

Also available in Spanish: leer en castellano.

I was going to be away from home for a good while. At home, a small army of home-automation devices depends on the Internet connection, and the thought of the line quietly dropping while I was far away, with no way of knowing, bothered me more than I expected. I did not want to find out when I got back. I wanted to know the moment it happened, and again the moment it returned.

So I built internet-check: an Internet-connection monitor for an Orange Pi Zero 2 (and any Debian with systemd) that watches the line around the clock and talks to you through a Telegram bot.

What it does

  • Tells you when the Internet comes back, with the time it went down and how long it lasted.
  • Tells an outage from a power cut and from a reboot, and works out your availability over the last day, week and month.
  • A bot with a button menu: status, speed test, public IP, histories, devices on your network, Wake-on-LAN and remote reboot, with administrators and read-only users.
  • Quality, not just up or down: latency, jitter, packet loss and DNS, plus the Pi’s own health (temperature, memory, disk).
  • Automatic alerts: scheduled speed tests, a change of public IP, new devices on the network, a degraded connection, a DNS failure and health alarms.
  • Daily and weekly reports, PNG charts and CSV export.
  • A terminal interface in the style of Turbo Vision, with shaded windows and drop-down menus.

It uses only the standard library of Python 3: no dependencies, no pip, and no root needed to check the connection.

The catch, and the trick

There is a catch that anyone who builds this runs into. With the Internet down, the Pi cannot message Telegram, so it can only tell you about an outage once the line is back. That is useful, but it is not an alarm.

The fix is to turn the problem around. The Pi pings an external service every minute, a heartbeat, and it is that service that sends you the alarm when the heartbeats stop arriving. It also works if the Pi loses power or hangs. With Healthchecks.io, which is free and open source, it takes a few minutes to set up. You can even test the alarm without touching a cable: a single command to the bot pauses the heartbeats for a few minutes.

Try it

Create a bot with @BotFather in Telegram, download the .deb from the releases page and install it on your Pi:

sudo apt install ./internet-check_1.7.1_all.deb
sudo nano /etc/internet-check/bot.env      # token and chat id
sudo systemctl restart internet-check

Then unplug the network cable for a minute and plug it back in. The first alert will not take long. The bot, its commands and the interface are in Spanish for now.

Private by default

The token lives in a file only root can read and never appears in the logs. The bot ignores any chat you have not authorised, and the remote reboot needs a confirmation that expires, so an old button cannot restart your machine. There is no telemetry of any kind, and the network scan stays on the Pi.

Standing on good shoulders

internet-check talks to the Telegram Bot API, borrows speed-test servers from LibreSpeed, relies on Healthchecks.io for the heartbeat alarm, and names the devices it sees with the public registry of the IEEE. Its terminal interface is a tribute to Borland’s Turbo Vision. Thank you to all of them.

The code is on GitHub under the GPL-3.0 license. For a full look at your home network from the terminal, try its sibling lanwatch, and keep the Pi’s logs in check with logguard.