Up-checks

This page gets Ferrule watching anything with an address, even gear it can't read: a printer, a camera on another NVR, a web app on a VM, a router from another vendor.

What Ferrule checks: whether the thing answers, and how quickly. Three kinds of check:

Kind	Up when	Example
ping	it answers a ping	ping 192.168.1.20
http	the web page answers with any 2xx or 3xx status	http https://nas.lab:5001
tcp	the port accepts a connection	tcp 10.0.0.5:22

What it can't: it reads nothing else from the device: no temperatures, no disks, no ports. It's free in every edition.

Add your checks

Up-checks are one variable, CHECKS, with one entry per thing you want watched, separated by ;:

CHECKS=ping 192.168.1.20 name=printer; http https://nas.lab:5001 name=nas; tcp 10.0.0.5:22 name=build-ssh

1. Open Settings → Stack environment and find CHECKS, in the Up-checks group.
2. Type your entries, as above.
3. Copy the line it writes, put it in the stack and redeploy. See Settings → Stack environment.

Each entry is the kind, then the address, then any of these settings:

Setting	What it does	Default
name=	What the check is called on the dashboard and in alerts. Each check needs its own name.	the address
every=	How often to check. The shortest is 10s.	30s
timeout=	How long to wait for an answer.	5s
expect=	http only: the one status that counts as up, such as 200.	any 2xx or 3xx
tls=verify	http only: also check the certificate is trusted.	off

More examples:

CHECKS=http https://192.168.1.30/login name=camera-nvr expect=200; tcp 192.168.1.40:445 name=file-share every=1m; ping core-sw.lab timeout=1s

Use name=

A name like printer reads better in a notification than 192.168.1.20. The name is also what Ferrule keeps the check's history under, so changing it later starts a new history.

Why certificates aren't checked by default

Many devices use a self-signed certificate that no browser trusts. Ferrule still wants to know they answer, so http checks skip the certificate unless you add tls=verify. Add it for sites with a real certificate: then an expired one shows as down.

Why ping can say unavailable

Ferrule pings without any special rights, using a setting (net.ipv4.ping_group_range) that Ferrule's compose file turns on. If your Docker host removed it, ping checks say unavailable instead of up or down. http and tcp checks still work. Use a tcp check of a port the device listens on instead.

When something is down

A check is down after three failures in a row, and up again after one answer. So one lost ping or slow page doesn't alert you; three in a row does. With the default every=30s, that's about a minute.

When a check goes down:

• Needs attention shows the check by its name, with when it stopped answering and why, such as connection refused or answered 503. It's a critical alert on the LAN tab. In notification rules it's Up-check not answering (check_down).
• Notifications go out like any other alert. Quiet hours and maintenance mode apply. See Alerts and notifications.
• The outage timeline on the WAN tab gets a lane for the check, showing how long it was down.

Down when Ferrule starts

A check that's already failing when Ferrule starts is shown, but not sent as a notification: Ferrule doesn't know when it went down. If it comes back and goes down again, that's sent.

If the device hangs off a UniFi switch that's offline, the alert says so: the switch is the problem, not the device.

Where it shows up

The LAN tab gets an Up-checks panel, with a row for each check: its name, kind, address, whether it's up, down or waiting for a first answer, how quickly it last answered, and since when. Down checks are listed first.

Settings → Sources lists every entry too, with left out and the reason for any it couldn't read.

Watching only up-checks, without UniFi

Up-checks work without any UniFi console. Set UNIFI_ENABLED=false with CHECKS, and the LAN tab shows only the Up-checks panel. See Watching without UniFi.

For Prometheus or Grafana

Each check has two metrics, labelled by check, kind and target: infra_check_up is 1 when up and 0 when down, and infra_check_response_seconds is how long its last answer took.

If something's wrong

What you see	What to do
The check isn't on the LAN tab	Check Settings → Sources for left out and the reason. The log also says, starting configuration: CHECKS:.
unknown kind	The entry must start with ping, http or tcp.
http takes a full URL	Start the address with http:// or https://.
tcp takes a host and port	Add the port: tcp 10.0.0.5:22.
the name ... is already used	Two checks have the same name. Give one a different name=.
connection refused	The device answered, but nothing listens on that port. Check the port.
timed out	Nothing answered in time. Check the address, and that the device is on. A firewall may be dropping it.
answered 404 or another status	The page is wrong, or the app is broken. Check the URL, or use expect= if that status is normal.
the certificate is not trusted	Remove tls=verify, or give the device a trusted certificate.
ping cannot run here	See Why ping can say unavailable above.
192.168.100.1 is never checked	Ferrule never checks this address: it's used by both cable modems and Starlink dishes, so what answers depends on your network.

See Troubleshooting for more.