Webmonit

Install the server

On Debian and its derivatives (amd64, arm64, armhf, riscv64):

curl -fsSL https://repo.lrob.net/apt/webmonit/webmonit.gpg -o /usr/share/keyrings/webmonit.gpg
echo "deb [signed-by=/usr/share/keyrings/webmonit.gpg] https://repo.lrob.net/apt/webmonit stable main" > /etc/apt/sources.list.d/webmonit.list
apt update && apt install webmonit

beta in place of stable follows the development builds. The package creates the webmonit system user, writes a starter /etc/webmonit/webmonit.yaml, installs the unit and starts the service on 127.0.0.1:17460.

The first token, the first account

sudo -u webmonit webmonit token init        # prints the admin API token, once
sudo -u webmonit webmonit user add <login>  # an account for the interface

The token goes into ~/.config/webmonit/cli.yaml (server:, token:) or WEBMONIT_TOKEN, and drives every CLI verb and the API. The account is what you sign into the interface with.

In front: a reverse proxy

The service listens on loopback on purpose. Put nginx, Apache or Caddy with TLS in front of 127.0.0.1:17460, then tell the console the URL you serve it on, in Settings › Server (or public_url: in /etc/webmonit/webmonit.yaml) — the links in alerts, the status pages and the agent install snippet use it. The overview's Getting started panel lists this and the other first steps until each is done.

Validate any configuration change before restarting: webmonit serve -t reports every problem at once, each with its file and line.

Name resolution

The checks resolve names through the resolvers listed under resolvers: in /etc/webmonit/webmonit.yaml, in that order: the first is always asked first, the next only when the one before has stayed silent. A name that does not exist is final whoever says it. Put a local resolver first and a public one after it as the fallback: a public resolver asked on every lookup throttles, and each question it drops costs a check its whole time.

Everything about resolution is a setting, changed live in Settings › Checks, with the file's values unless set there and back to the file when emptied:

  • Resolvers, in order — host or host:port, eight at most.
  • Patience per resolver — how long one may stay silent before the next is asked, 2 s by default.
  • DNS walk, per question — the DNS checks also walk from the root to the authoritative servers; one referral that has not come in this time is skipped for the next, 2 s by default.
  • Ceiling per kind of check — the longest a check of a kind may take whatever its monitor asks: a port or a ping answers in milliseconds, a DNS check that asks every declared server needs the seconds a dead one costs.