App checks

An app check answers "is the service answering?". The hub (or an agent you name) calls the service on a schedule and the result shows on the Apps tab: state, response time, and the TLS certificate's days left where there is one.

Declare one#

App checks live in config files, under apps:. Put a check in the host file of the machine that runs the service (hosts/<id>.yaml), so it shows next to that host, or in a file under checks/ when it belongs to no one host. The hub picks up a saved file within seconds; there is nothing to restart.

apps:
  - id: web
    kind: http
    url: "https://atlas.example.internal/health"
    expect: { status: 200, max_ms: 800 }   # optional: the status to expect and the slowest acceptable answer
  - id: db
    kind: tcp                              # the port accepts a connection
    host: atlas.example.internal
    port: 5432
  - id: mail-cert
    kind: tls                              # the certificate is valid and not close to expiry
    host: mail.example.org
    port: 443

Every field of every kind, with its default, is in the config reference. More examples are in examples/config/.

Devices with no agent: ping and DNS#

ping and dns checks run from the hub, so they work for a router, a printer or a resolver that can't run an agent. They run from the hub only for now: run_on: agent:<host> on either is a load error.

apps:
  - { id: edge-gw-ping, kind: ping, host: 192.168.1.1, count: 3, max_loss_pct: 34, max_rtt_ms: 200 }
  - { id: dns-internal, kind: dns, name: nas-1.example.internal, type: A, server: 192.168.1.53,
      expect: { contains: ["192.168.1.20"] } }

ping sends count echo requests (default 3) with the system ping program. host is an IP address or a plain hostname. The check fails when more than max_loss_pct of the requests go unanswered (default 50) or when none do, and warns when the average round trip is over max_rtt_ms.

Sending ICMP needs a permission the hub's user doesn't always have. When the hub can't send it, every ping check shows unknown: this hub cannot send ICMP (see docs), never red, and GET /status carries an icmp field with the reason (the hub also logs it at startup). To fix it:

• Docker: the hub image includes ping and runs as uid 65532. Docker's default net.ipv4.ping_group_range already allows it. If your host narrowed that sysctl, widen it for the container: --sysctl net.ipv4.ping_group_range="0 2147483647".
• Linux, no container: install iputils-ping and either allow your user through net.ipv4.ping_group_range or give the binary a capability: setcap cap_net_raw+ep $(command -v ping).
• macOS: ping is already set-uid; nothing to do.
• Windows hubs can't run ping checks yet.

dns asks a resolver for name and checks the answer. type is A (default), AAAA, CNAME, MX, TXT, NS, SRV or PTR (for PTR, name is an IP address). server is the resolver to ask, an IP address with an optional port (192.168.1.53, 192.168.1.53:5353); leave it out to use the hub's own resolver. expect.contains lists values that must all be among the answers and expect.equals the exact set (not both); with neither, any answer is fine. Answers compare as 10 mail.example.org for MX, 10 5 5060 sip.example.org for SRV (priority, weight, port, name) and the joined text for TXT. A missing name fails with NXDOMAIN, a broken resolver with SERVFAIL, a silent one with timeout. The response time is recorded.

Domain expiry#

apps:
  - { id: example-domain, kind: domain, name: example.org, warn_days: 30, critical_days: 7 }

A domain check reads when a domain registration ends, from the registry's RDAP service (the machine-readable successor of WHOIS), and counts the days left. It warns at warn_days (default 30) and goes critical at critical_days (default 7) or once the domain has expired. The days left are the check's value, charted like the TLS certificate's.

• name is the registered domain exactly as the registry knows it (example.org, not www.example.org); Yarrix doesn't work out the registered part of a longer name.
• It runs every 12 hours unless you set interval, and never more often than hourly, because registries rate-limit. A shorter interval is a load error.
• If the registry has no RDAP service for the domain's TLD, doesn't answer, or gives no expiration date, the check shows unknown with the reason, never red.
• rdap_url points the check at a specific RDAP server instead of the one IANA lists for the TLD. RDAP is contacted over https only: an http:// rdap_url is a load error, a TLD that IANA lists only over http shows unknown, and a redirect is followed (up to three times) only when it stays on the registry's own host; a redirect to any other host shows unknown.

A domain check is the only thing that makes the hub contact these outside hosts, and only while at least one exists: data.iana.org (the list of which registry serves which TLD, fetched at most once a week and kept in the hub's database) and the registry's RDAP server for your TLD (for example rdap.verisign.com for .com, rdap.publicinterestregistry.org for .org). With no domain check configured the hub never contacts either.

Many services at once#

If you already keep a list of your services in a file, the hub can read app checks from it instead: set up an importer under importers: in yarrix.yaml (Config → Service list shows what it found). An importer can only make http, tcp and tls checks. See importers in the reference.

Turning one off#

enabled: false on a check stops it and keeps its history. Set it in the file the check lives in (hosts/<id>.yaml or checks/*.yaml) and save; the hub reloads the file within seconds, and setting enabled: true (or removing the line) turns the check back on. The Config page has no switch for individual checks.