Applies to: Uptime Kuma 2.5.9 (TCP Port, Ping, DNS, SMTP and Push monitors)

Uptime Kuma can watch more than websites. Use a TCP Port monitor to check that SSH, MySQL or mail ports answer, a Ping monitor to check that a server is reachable at all, a DNS monitor to check that a record still resolves to the right value, and a Push monitor for cron jobs and backups, which call Uptime Kuma when they finish.

Run the monitor outside the servers it watches, so it sees them the way the internet does and still alerts when they are down. All the monitors below are added with Add New Monitor and use the notifications described in website uptime alerts with Uptime Kuma.

1. TCP Port monitor (SSH, MySQL, SMTP and others)

  1. Monitor Type: TCP Port.
  2. Hostname: the server's IP address or host name.
  3. Port: for example 22 (SSH), 25, 465 or 587 (mail), 3306 (MySQL), 8000 (a radio stream).
  4. Set Heartbeat Interval and Retries, tick a notification and press Save.

The monitor only checks that a TCP connection opens. Lab results: 1.1.1.1 port 443 was Up with "12 ms", a lab SMTP service on port 2525 was Up with "1 ms", and a port with nothing listening went Down with:

Connection failed

Ports that must stay closed. A database port such as 3306 should normally not be reachable from the internet. Add a TCP Port monitor for it and tick Upside Down Mode ("If the service is reachable, it is DOWN."). In our lab that monitor showed Up for the closed port, so you get an alert only if a firewall change opens it. To test a port by hand first, see checking a remote port with nc.

For mail servers there is also an SMTP monitor type with an SMTP Security choice (SMTPS, Ignore STARTTLS, Use STARTTLS). Against our lab mail service it reported "SMTP connection verifies successfully", which tells you more than an open port.

2. Ping monitor

  1. Monitor Type: Ping, and enter the Hostname.
  2. The defaults are fine for most servers: Max Packets 3, Packet Size 56, Per-Ping Timeout 2 seconds and Global Timeout 10 seconds.

In our lab, 1.1.1.1 was Up with the round-trip time on the chart. Some servers and firewalls drop ping on purpose, so a TCP Port monitor on a port you know is open is often the better "is it up" check. For what ping can tell you, see the Linux ping command.

If every Ping monitor fails with spawn EPERM, the container is not allowed to send raw packets. We saw exactly this in a lab container started without the NET_RAW capability; after adding it, ping worked. Docker includes NET_RAW in its default capabilities, so a normal Docker install is not affected, but a hardened or rootless setup may be.

3. DNS record monitor

  1. Monitor Type: DNS, and enter the Hostname to look up, for example www.example.com.
  2. Resolver Server(s): 1.1.1.1 by default. You can enter several, separated by commas, or your own name server to check it directly. Port is 53.
  3. Resource Record Type: A, AAAA, CAA, CNAME, MX, NS, PTR, SOA, SRV or TXT.
  4. Optional: under Conditions, press Add Condition and set record, an operator (equals, contains, starts with and their "not" forms) and a value, for example your server's IP address.

Lab results for one.one.one.one, type A:

Records: 1.1.1.1 | 1.0.0.1

With the condition record equals 1.1.1.1 the monitor stayed Up; changing the value to 9.9.9.9 turned it Down. That is how you get an alert when someone changes your A or MX record by mistake. For checking records by hand, Linux network commands covers dig.

4. Push monitor for cron jobs and backups

A backup script has no port to check. With a Push monitor, the job calls Uptime Kuma when it finishes, and Uptime Kuma alerts you if the call does not arrive in time.

  1. Monitor Type: Push. Uptime Kuma shows a Push URL with a unique token, for example https://status.example.com/api/push/YOUR_TOKEN?status=up&msg=OK&ping=, with the note "Optional parameters: status, msg, ping".
  2. Set Heartbeat Interval a little longer than the job's schedule. For a daily job, 90000 seconds (shown as "1 day, 1 hour") gives an hour of slack.
  3. Tick a notification and press Save.

The Push URL uses the address you opened Uptime Kuma on. If you set it up through an SSH tunnel, set Settings, General, Primary Base URL to your public HTTPS address, or edit the host in the URL before you use it.

A backup script that reports success or failure:

#!/bin/sh
PUSH="https://status.example.com/api/push/YOUR_TOKEN"

if tar -czf /backup/site-$(date +%F).tar.gz /var/www; then
  curl -fsS -m 10 --retry 5 -o /dev/null "$PUSH?status=up&msg=OK&ping="
else
  curl -fsS -m 10 --retry 5 -o /dev/null "$PUSH?status=down&msg=backup%20failed&ping="
fi

Run it from cron, for example every night at 02:00 (see scheduling tasks with cron):

0 2 * * * /usr/local/bin/backup-with-push.sh

What we saw in the lab:

  • A call with the right token answered {"ok":true} and the monitor showed Up with the message "OK".
  • A call with status=down&msg=backup%20failed turned the monitor Down with the message "backup failed".
  • When no call arrived within the interval, the monitor went Down with "No heartbeat in the time window".
  • A wrong token answered {"ok":false,"msg":"Monitor not found or not active."}.

The script itself needs outbound HTTPS to your Uptime Kuma address, nothing more.

Where to run it

All of these checks run from wherever Uptime Kuma runs. Managed Uptime Kuma hosting checks addresses that are open to the internet. To also watch private IP addresses or internal services, for example over a WireGuard VPN, use an Uptime Kuma VPS with root access. To compare Uptime Kuma with agent-based tools that also watch CPU, memory and disk, see server monitoring software for Linux compared.

Official documentation: Uptime Kuma wiki.

Related services

KVM VPS hosting

NVMe SSD and full root access, with Free Basic Managed Support.

Unmanaged dedicated servers

full root access and free IPMI KVM, with Free Basic Managed Support.

Managed dedicated servers

our engineers look after the server for you, from $135 a month.

Was this answer helpful?

Still stuck? Open a ticket