Host Monitoring over SSH
A host monitor logs in to a Linux or macOS server over SSH and reads the machine itself: load, disks, inodes, memory, swap and the system file-descriptor table. One login, one fixed command. Windows is refused before any of that runs.
This is not a check that port 22 is open. A TCP monitor answers that. This one answers whether the server still has room to work.
What it reads
- Load. The 5-minute load average divided by the number of CPUs. Warning at 1.0 per CPU, critical at 2.0.
- Disks. Local filesystems from
df. The percentage isdf’s Use%: space a normal process can still write. Blocks reserved for root are not counted as free. Warning at 80% used, critical at 95%. - Inodes. Linux only, with the same 80/95 defaults. macOS has no useful inode reading, so it is skipped.
- Memory. Available memory, not the free-page counter. Linux uses MemAvailable. Warning when 15% or less is left, critical at 5%.
- Swap. Used percent. Warning at 50%, critical at 80%. A server with no swap is not a failure.
- File descriptors. The system table (
file-nron Linux,kern.num_fileson macOS), not a processulimit. Warning at 80%, critical at 95%. - Connection tracking. The same percentages, and only when the kernel exposes the counters. A missing file is not an error.
- Read-only mounts. A filesystem that remounted read-only is a breach. On macOS the sealed system volume at
/is not.
Virtual filesystems (tmpfs, devtmpfs, and the usual /dev, /proc, /sys, /run mounts) are skipped. ignore_mounts drops a path you name. ["/"] drops only the root mount. ["/mnt"] drops /mnt and everything under it.
What it is not
| You want to know | Use instead |
|---|---|
| Is port 22 open, without logging in? | TCP monitor |
| Does the host answer at all, with nothing installed on it? | Ping monitor |
| Is a website or API on that server actually serving? | HTTP / HTTPS monitor |
| A Windows server, or a per-process file-descriptor limit | Not this monitor. Windows is refused immediately. The file-descriptor reading is the system table. |
Status
A threshold breach, including a full disk and a read-only mount, is Degraded. That check still counts as uptime and does not open an incident. A rule that only pages on outages does not fire for it.
The monitor is Down when the login is refused, the host key changed, the address is one this checker may not touch, or the operating system is not Linux or macOS. A connection that never answers is a timeout.
The first successful login pins the server’s SHA256 host key. A later key is a Down check and does not replace the pin. A refused login pauses the monitor for one hour, so a bad key does not keep hitting sshd.
Login and limits
- The address is a host or
host:port. The default port is 22.ssh://andhost://are accepted. A username in the address (user@host) is rejected: the username is a setting. host_settings.username, and aprivate_keyor apassword(or both). The key must be an unencrypted OpenSSH or PEM key. A passphrase-protected key is refused before the login.- The API and MCP never return the key or the password. A saved login comes back as
private_key_setandpassword_set. - The shortest interval is 60 seconds and the shortest timeout is 15 seconds. Retries are forced off: a retry would be a second password in front of sshd.
- A public checker will not connect to a private or link-local address. Check a machine on a local network from a private checker on that network.
Create one
The monitor form does not offer this type yet. Create it through the API or MCP.
curl -X POST https://pingzen.dev/api/v1/monitors \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "App server",
"url": "app.example.com:22",
"protocol": "host",
"interval_seconds": 300,
"timeout_seconds": 20,
"workspace_id": 1,
"host_settings": {
"username": "pingzen",
"private_key": "<unencrypted OpenSSH or PEM private key>"
}
}'MCP uses create_monitor with protocol set to host and the same host_settings. A later update_monitor merges settings: a key you send replaces that key, null removes it, and a key you omit stays. Changing the address clears the pinned host key and lifts the login pause.
The thresholds you can set are load_warn, load_critical, disk_warn_percent, disk_critical_percent, inode_warn_percent, inode_critical_percent, fd_warn_percent, fd_critical_percent, mem_avail_warn_percent, mem_avail_critical_percent, swap_warn_percent, swap_critical_percent, and ignore_mounts.