Configuration reference

Every field Yarrix reads from its config folder, one row per field. For how the files fit together, secrets, layering and validation, read configuration.md first.

How to read the tables:

Field is a dotted path. [] is a list item; <key> is a name you choose (a map key); {type=webhook} selects one form of a field that has several, by the value that tells them apart.
Required means the key must be present. A field with a default may be left out.
Flags: secret takes ${env:NAME} or ${file:/path} and is redacted everywhere it is shown. exec is a field that becomes a command, or the target of one, on a host. guarded is a field that widens what the hub itself will do (where it writes or sends). exec and guarded fields can be changed through the API only from an admin browser session; see security.md.
Unknown keys are errors in every file. Durations are a number and a unit: 30s, 5m, 48h, 30d.

The JSON Schemas these tables come from are in proto/config/; point your editor at them for completion.

yarrix.yaml (server)#

Server settings: sign-in, retention, the web terminal, importers and self-monitoring. (proto/config/yarrix.schema.json)

versionliteral 1Required

Always 1.

trusted_proxiesarray of string

Reverse proxies whose X-Forwarded-For is believed. Only a request from one of these has its client address read from that header (the rightmost address that is not itself a trusted proxy); every other request is keyed on its own connection. Empty = never read the header.

Default []

networkobject

Default {}

network.portinteger

min 1024; max 65535; The port the hub listens on. Default 7790.

network.lanboolean

true: listen on all interfaces so other computers can reach this hub. false: loopback only.

Default false

authobject

Default {}

auth.providersarray of one ofguarded

How people sign in. Several may be listed. local (passwords on the hub) is the default; see auth.md.

auth.providers[]one of

auth.providers[]{type=local}.typeliteral "local"Requiredguarded

auth.providers[]{type=supabase}.typeliteral "supabase"Requiredguarded

auth.providers[]{type=supabase}.urlstringRequiredguarded

format uri; Your Supabase project URL.

auth.providers[]{type=supabase}.anon_keystringRequiredsecretguarded

min length 1

auth.providers[]{type=supabase}.jwt_secretstringsecretguarded

min length 1; Verifies HS256 tokens. Leave it out to use the project's JWKS.

auth.providers[]{type=supabase}.oauth_providerstringguarded

The Supabase OAuth provider to send people to, for example github.

auth.providers[]{type=tailscale}.typeliteral "tailscale"Requiredguarded

auth.providers[]{type=tailscale}.modeenumguarded

one of "whois", "headers"; whois asks the local tailscaled who owns the connection. headers trusts the Tailscale-User-Login header, only from trusted_proxies.

Default "whois"

auth.providers[]{type=tailscale}.trusted_proxiesarray of stringguarded

Addresses allowed to set the identity header in headers mode.

Default ["127.0.0.1/32","::1/128"]

auth.providers[]{type=tailscale}.socketstringguarded

min length 1; Path of the tailscaled LocalAPI socket for whois mode. Unset uses the platform default.

auth.providers[]{type=tailscale}.allow_remote_proxybooleanguarded

headers mode refuses to start on a non-loopback listener unless this is true.

Default false

auth.usersarray of object

Who may do what. Roles are computed from these rules on every request.

Default []

auth.users[]object

auth.users[].matchstringRequired

min length 1; Compared case-insensitively with the verified email (Supabase) or tailnet login (Tailscale).

auth.users[].roleenumRequired

one of "admin", "operator", "viewer"; viewer reads, operator acts, admin manages.

auth.users[].terminalarray of string

each min length 1; Host ids, or *, this user may open a terminal on. An admin needs no grant; a viewer never gets one.

auth.default_roleenumguarded

one of "none", "viewer"; Role for someone who signs in but matches no rule. none denies them.

Default "none"

auth.token_limitsobject

Default {}

auth.token_limits.max_mutedurationguarded

The longest a snooze, silence or pause made with a read-write API key can last. A key can never make an open-ended one.

Default "24h"

retentionobject

How long samples are kept. The hub keeps raw 1-minute points and 5-minute rollups; the retention job runs hourly and re-reads this each time, so an edit applies without a restart.

Default {}

retention.rawdurationguarded

How long 1-minute points are kept. At least 24h.

Default "48h"

retention.raw_stepduration

Fixed at 1m: the raw tier is 1-minute points.

Default "1m"

retention.rollupdurationguarded

How long 5-minute rollups are kept. At least 30d.

Default "30d"

retention.rollup_stepduration

Fixed at 5m: the rollup tier is 5-minute points.

Default "5m"

availabilityobject

Availability history: how long the record of each object's up, degraded, down and not-observed time is kept. Re-read at each daily purge.

Default {}

availability.keepdurationguarded

How long availability history is kept. At least 35d; default 400d (a year plus a month).

Default "400d"

terminalobject

Default {}

terminal.enabledbooleanguarded

The web terminal is off until this is true. See terminal.md.

Default false

terminal.recordbooleanguarded

Record sessions to the data directory.

Default true

terminal.startup_commandstringexec

max length 1024; Default command a terminal runs on connect. An empty string is the login shell. {user} and {host} are replaced. A host can override it.

Default ""

terminal.max_sessionsinteger

min 1; Most terminals open at once across the hub.

Default 4

terminal.idle_timeoutduration

Close a terminal after this long without input.

Default "30m"

agent_updatesobject

Default {}

agent_updates.modeenumguarded

one of "automatic", "one_click", "notify"

Default "one_click"

agent_updates.windowobject

Hub local time. Absent = any time. Used by automatic updates.

agent_updates.window.startstringRequired

pattern ^([01]\d|2[0-3]):[0-5]\d$

agent_updates.window.endstringRequired

pattern ^([01]\d|2[0-3]):[0-5]\d$

agent_updates.max_concurrentinteger

min 1; max 50; Updates in flight at once (automatic and Update all)

Default 2

importersarray of object

Seed app checks from a data file. An importer can only produce http, tcp and tls checks, never anything that runs a command.

Default []

importers[]object

importers[].idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

importers[].typeliteral "file"Required

importers[].pathstringRequired

min length 1

importers[].itemsstringRequired

min length 1; JSONPath to the list of services Point it at the array ($.services) or at its elements ($.services[*]); either imports each element as one service.

importers[].mapmap of string

Templates over each item

Default {}

importers[].map.<key>string

importers[].defaultsmap of any

Values applied to every item. Only the keys an importer may set are allowed.

Default {}

importers[].defaults.<key>any

status_pagesarray of objectguarded

Pages anyone you allow can read without opening the web app. Absent = no /status routes at all. Changing this needs an admin signed in to the web app.

Default []

status_pages[]object

status_pages[].idstringRequiredguarded

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

status_pages[].titlestringRequiredguarded

min length 1; max length 120

status_pages[].accessenumguarded

one of "public", "viewer"; public: anyone who can reach the hub, no sign-in. viewer: any signed-in user.

Default "viewer"

status_pages[].show_reasonsbooleanguarded

Show the hub's reason line under a problem. A reason can name hosts, addresses, paths and commands, so leave this off for a public page.

Default false

status_pages[].show_availabilitybooleanguarded

Show the 30-day availability percentage on each row.

Default true

status_pages[].itemsarray of one ofRequiredguarded

min items 1; max items 100

status_pages[].items[]one of

status_pages[].items[]{ref+label}.refstringRequiredguarded

pattern ^(host|check|backup|heartbeat):[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

status_pages[].items[]{ref+label}.labelstringRequiredguarded

min length 1; max length 80; The name a visitor sees. Nothing else about the object is shown.

status_pages[].items[]{tag+label}.tagstringRequiredguarded

min length 1; max length 64; Every app and heartbeat with this tag, shown as one row: the worst state among them.

status_pages[].items[]{tag+label}.labelstringRequiredguarded

min length 1; max length 80; The name a visitor sees for the row.

badgesarray of objectguarded

Status badges at /badge/<key>.svg and .json. Absent = no /badge routes at all. Changing this needs an admin signed in to the web app.

badges[]object

badges[].idstringRequiredguarded

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

badges[].labelstringguarded

min length 1; max length 40; The left side of the badge. Defaults to the badge id.

badges[].tagstringguarded

min length 1; max length 64; Every app and heartbeat with this tag.

badges[].itemsarray of stringguarded

min items 1; max items 100; each pattern ^(host|check|backup|heartbeat):[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$; These objects, by reference.

badges[].keystringsecretguarded

min length 1; Pin the key (16 to 64 letters and digits, from a secret reference). Without it the hub makes one and keeps it in its database.

self_monitorobject

Default {}

self_monitor.ping_urlstringsecretguarded

min length 1; A URL the hub pings so an outside service notices if the hub itself stops (a dead-man's switch).

self_monitor.db_backupobject

A scheduled copy of the hub's own database.

Default {}

self_monitor.db_backup.schedulestring

Cron expression, 5 fields.

Default "0 3 * * *"

self_monitor.db_backup.keepinteger

min 1; Copies to keep.

Default 7

self_monitor.db_backup.pathstringguarded

Absolute directory for the copies. Empty uses backups under the data directory.

Default ""

configobject

Default {}

config.gitobject

Default {}

config.git.commitbooleanguarded

When the config folder is a git repository, saving a file through the API makes one local commit (never pushed). Set false to turn that off.

defaults.yaml#

Thresholds and collection settings every host inherits. Every key is optional. (proto/config/defaults.schema.json)

thresholdsobject

[warn, fail] per metric, in percent (load is the 1-minute average, temp is degrees C). Built in: cpu 80/95, mem 80/92, gpu 80/95, disk 80/90, temp 85/95. A host can override any one.

thresholds.cpu[number, number]

thresholds.mem[number, number]

thresholds.gpu[number, number]

thresholds.disk[number, number]

thresholds.temp[number, number]

thresholds.load[number, number]

sustainduration

A metric must stay over its threshold this long before it alerts. Built in: 5m.

tlsobject

Days before a certificate expires at which a TLS check warns and goes critical.

tls.warn_daysinteger

min 1

tls.critical_daysinteger

min 1

collect_defaultsobject

Collection intervals inherited by every host that does not set its own.

collect_defaults.agentobject

collect_defaults.agent.push_intervalduration

How often an agent host sends its samples, when the host sets no collect.push_interval. Built in: 60s.

collect_defaults.sshobject

collect_defaults.ssh.intervalduration

How often the hub polls an SSH host, when the host sets no collect.interval. Built in: 60s. Minimum 15s.

check_intervalduration

How often app checks run when they set no interval. Checks never run faster than the hub's minimum interval.

alerts.yaml#

Destinations, delivery, routing rules, behavior and maintenance windows. (proto/config/alerts.schema.json)

destinationsmap of one ofRequired

keys match ^[a-z0-9][a-z0-9_-]{0,63}$; Where alerts go, by id. Exactly one must set default: true.

destinations.<key>one of

destinations.<key>{type=webhook}.typeliteral "webhook"Required

destinations.<key>{type=webhook}.namestring

destinations.<key>{type=webhook}.eventsarray of enum

each one of "incident.opened", "incident.updated", "incident.resolved", "incident.summary", "incident.grouped", "digest.daily", "report.weekly", "report.monthly", "system.action", "test"; Only send these events. Absent sends all of them.

destinations.<key>{type=webhook}.enabledboolean

Default true

destinations.<key>{type=webhook}.defaultboolean

The destination the locked last rule falls back to.

Default false

destinations.<key>{type=webhook}.urlstringRequiredsecret

min length 1; The webhook URL. It is a secret, so keep it in ${env:...}.

destinations.<key>{type=webhook}.methodenum

one of "POST", "PUT"

Default "POST"

destinations.<key>{type=webhook}.formatenum

one of "yarrix_json", "slack", "discord", "ntfy", "template"; See alert-delivery.md for each format.

Default "yarrix_json"

destinations.<key>{type=webhook}.templatestring

min length 1; max length 8192; Body for format: template. Mustache-style, for example {"text": "{{headline}}"}.

destinations.<key>{type=webhook}.content_typestring

pattern ^[a-z]+\/[a-z0-9.+-]+$; Content-Type of a template body.

Default "application/json"

destinations.<key>{type=webhook}.allow_metadata_ipsbooleanguarded

Cloud metadata addresses (169.254.169.254 and friends) are refused unless this is true.

Default false

destinations.<key>{type=webhook}.headersmap of string

Extra request headers. Values are secrets.

destinations.<key>{type=webhook}.headers.<key>stringsecret

min length 1

destinations.<key>{type=webhook}.signobject

Adds X-Yarrix-Timestamp and X-Yarrix-Signature headers so a receiver can verify the body.

destinations.<key>{type=webhook}.sign.typeliteral "hmac_sha256"Required

destinations.<key>{type=webhook}.sign.secretstringRequiredsecret

min length 1

destinations.<key>{type=webhook}.mention_on_criticalstring

Text a template can place with {{mention}}, only on critical alerts.

destinations.<key>{type=email}.typeliteral "email"Required

destinations.<key>{type=email}.namestring

destinations.<key>{type=email}.eventsarray of enum

each one of "incident.opened", "incident.updated", "incident.resolved", "incident.summary", "incident.grouped", "digest.daily", "report.weekly", "report.monthly", "system.action", "test"

destinations.<key>{type=email}.enabledboolean

Default true

destinations.<key>{type=email}.defaultboolean

Default false

destinations.<key>{type=email}.toarray of stringRequired

min items 1; each pattern ^(?:[^<>]*<[^\s<>@]+@[^\s<>@]+>|[^\s<>@]+@[^\s<>@]+)$; each min length 1; each max length 320; Recipients.

destinations.<key>{type=email}.ccarray of string

each pattern ^(?:[^<>]*<[^\s<>@]+@[^\s<>@]+>|[^\s<>@]+@[^\s<>@]+)$; each min length 1; each max length 320

destinations.<key>{type=email}.fromstring

pattern ^(?:[^<>]*<[^\s<>@]+@[^\s<>@]+>|[^\s<>@]+@[^\s<>@]+)$; min length 1; max length 320; Sender. Falls back to the shared smtp.from.

destinations.<key>{type=email}.subject_prefixstring

max length 64

destinations.<key>{type=email}.smtpobject

Overrides the shared smtp: block field by field.

destinations.<key>{type=email}.smtp.hoststring

min length 1; max length 253

destinations.<key>{type=email}.smtp.portinteger

min 1; max 65535

destinations.<key>{type=email}.smtp.securityenum

one of "starttls", "tls", "none"

destinations.<key>{type=email}.smtp.usernamestringsecret

min length 1

destinations.<key>{type=email}.smtp.passwordstringsecret

min length 1

destinations.<key>{type=email}.smtp.fromstring

pattern ^(?:[^<>]*<[^\s<>@]+@[^\s<>@]+>|[^\s<>@]+@[^\s<>@]+)$; min length 1; max length 320

destinations.<key>{type=email}.smtp.helostring

min length 1; max length 253

destinations.<key>{type=email}.smtp.timeoutduration

destinations.<key>{type=email}.smtp.tls_ca_filestring

min length 1; PEM file of a private CA to trust for this server

destinations.<key>{type=telegram}.typeliteral "telegram"Required

destinations.<key>{type=telegram}.namestring

destinations.<key>{type=telegram}.eventsarray of enum

each one of "incident.opened", "incident.updated", "incident.resolved", "incident.summary", "incident.grouped", "digest.daily", "report.weekly", "report.monthly", "system.action", "test"

destinations.<key>{type=telegram}.enabledboolean

Default true

destinations.<key>{type=telegram}.defaultboolean

Default false

destinations.<key>{type=telegram}.bot_tokenstringRequiredsecret

min length 1; The bot's token from @BotFather. A secret, so keep it in ${env:...}. Yarrix ships no bot: you bring your own.

destinations.<key>{type=telegram}.chat_idstring or integerRequired

The user, group or channel id that receives the messages (for example "-1001234567890"). Not a secret.

destinations.<key>{type=telegram}.thread_idinteger

A forum topic inside a group chat.

destinations.<key>{type=telegram}.api_urlstringsecret

min length 1; Only for a self-hosted Bot API server. Defaults to https://api.telegram.org.

destinations.<key>{type=pushover}.typeliteral "pushover"Required

destinations.<key>{type=pushover}.namestring

destinations.<key>{type=pushover}.eventsarray of enum

each one of "incident.opened", "incident.updated", "incident.resolved", "incident.summary", "incident.grouped", "digest.daily", "report.weekly", "report.monthly", "system.action", "test"

destinations.<key>{type=pushover}.enabledboolean

Default true

destinations.<key>{type=pushover}.defaultboolean

Default false

destinations.<key>{type=pushover}.app_tokenstringRequiredsecret

min length 1; Your Pushover application token. A secret, so keep it in ${env:...}. Yarrix ships no application: you bring your own.

destinations.<key>{type=pushover}.user_keystringRequiredsecret

min length 1; Your user key, or a group key. A secret, so keep it in ${env:...}.

destinations.<key>{type=pushover}.devicestring

pattern ^([A-Za-z0-9_-]+)?$; max length 25; Send to one device on the user key. Absent sends to every device.

destinations.<key>{type=pushover}.priorityobject

The Pushover priority for each severity. 2 is an emergency and needs emergency.

Default {}

destinations.<key>{type=pushover}.priority.criticalinteger

min -2; max 2

Default 1

destinations.<key>{type=pushover}.priority.warninteger

min -2; max 2

Default 0

destinations.<key>{type=pushover}.priority.infointeger

min -2; max 2

Default -1

destinations.<key>{type=pushover}.emergencyobject

Required when any priority is 2. Pushover repeats an emergency every retry until it is acknowledged in the app, and stops after expire (at most 3h). retry is at least 30s.

destinations.<key>{type=pushover}.emergency.retrydurationRequired

destinations.<key>{type=pushover}.emergency.expiredurationRequired

smtpobject

Shared mail server for every email destination. security: none is allowed only to a loopback or private address.

smtp.hoststringRequired

min length 1; max length 253

smtp.portintegerRequired

min 1; max 65535

smtp.securityenum

one of "starttls", "tls", "none"; starttls upgrades a plain connection, tls connects encrypted, none sends unencrypted.

Default "starttls"

smtp.usernamestringsecret

min length 1

smtp.passwordstringsecret

min length 1

smtp.fromstringRequired

pattern ^(?:[^<>]*<[^\s<>@]+@[^\s<>@]+>|[^\s<>@]+@[^\s<>@]+)$; min length 1; max length 320

smtp.helostring

min length 1; max length 253; Name announced to the server.

smtp.timeoutduration

Default "30s"

smtp.tls_ca_filestring

min length 1; PEM file of a private CA to trust for this server

deliveryobject

Default {}

delivery.timeoutduration

Per-request timeout.

Default "5s"

delivery.retriesinteger

min 0; Retries after the first attempt fails.

Default 6

delivery.backoffobject

Default {}

delivery.backoff.startduration

First retry delay; it doubles up to max.

Default "10s"

delivery.backoff.maxduration

Default "15m"

delivery.queueliteral "disk"

The retry queue is always on disk.

Default "disk"

rulesarray of objectRequired

min items 1; Run top to bottom, and every matching rule adds its destinations. If none match, the default destination gets the alert. The last rule must be - fallback: [<the default destination>].

rules[]object

rules[].whenobject

What the rule matches. Absent keys match anything.

rules[].when.severityenum

one of "info", "warn", "critical"

rules[].when.domainenum

one of "hosts", "apps", "backups", "heartbeats", "system"

rules[].when.hoststring

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

rules[].when.checkstring

rules[].when.tagstring

rules[].when.host_stateenum

one of "asleep", "down", "up"

rules[].sendarray of string

each pattern ^[a-z0-9][a-z0-9_-]{0,63}$; Destinations to send to.

rules[].alsoarray of string

each pattern ^[a-z0-9][a-z0-9_-]{0,63}$; Extra destinations. Works the same as send.

rules[].holdboolean

Hold matching alerts instead of sending them. Wins over every other matching rule.

rules[].ignore_quiet_hoursboolean

Send even during quiet hours.

rules[].fallbackarray of string

min items 1; each pattern ^[a-z0-9][a-z0-9_-]{0,63}$; Only on the last rule: the default destination.

behaviorobject

Default {}

behavior.after_consecutive_failuresinteger

min 1; Failed runs in a row before an app or custom check alerts. A check can set its own.

Default 2

behavior.send_recoveryboolean

Send a message when an incident resolves.

Default true

behavior.renotify_unacked_criticalduration

Repeat an unacknowledged critical alert this often.

behavior.group_waitduration

Default "90s"

behavior.suppress_when_host_downboolean

Default true

behavior.group_by_hostboolean

Default true

behavior.group_intervalduration

Default "5m"

behavior.quiet_hoursobject

A daily window in which alerts of the severities in hold wait until it ends.

behavior.quiet_hours.fromstringRequired

pattern ^([01]\d|2[0-3]):[0-5]\d$

behavior.quiet_hours.tostringRequired

pattern ^([01]\d|2[0-3]):[0-5]\d$

behavior.quiet_hours.tzstring

Default "UTC"

behavior.quiet_hours.holdarray of enum

each one of "info", "warn", "critical"

Default ["warn","info"]

behavior.digestobject

One daily summary message to the listed destinations.

behavior.digest.atstringRequired

pattern ^([01]\d|2[0-3]):[0-5]\d$

behavior.digest.tzstring

Default "UTC"

behavior.digest.sendarray of string

each pattern ^[a-z0-9][a-z0-9_-]{0,63}$

Default []

behavior.reportsarray of object

Weekly (on day) or monthly (on the 1st, covering the previous month) availability reports to the listed destinations.

behavior.reports[]object

behavior.reports[].everyenumRequired

one of "weekly", "monthly"

behavior.reports[].dayenum

one of "mon", "tue", "wed", "thu", "fri", "sat", "sun"

behavior.reports[].atstringRequired

pattern ^([01]\d|2[0-3]):[0-5]\d$

behavior.reports[].tzstring

Default "UTC"

behavior.reports[].sendarray of string

each pattern ^[a-z0-9][a-z0-9_-]{0,63}$

Default []

maintenancearray of object

Windows in which a host, check or backup does not alert.

Default []

maintenance[]object

maintenance[].targetstringRequired

pattern ^(host|check|backup):[a-z0-9][a-z0-9_-]*$; host:<id>, check:<id> or backup:<id>.

maintenance[].windowstringRequired

maintenance[].reasonstring

hosts/<id>.yaml#

One file per host: how it is collected, its checks, apps, backups and heartbeats. (proto/config/host.schema.json)

idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$; The host's id, used everywhere else. Keep it equal to the file name.

enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

rolestring

osenum

one of "auto", "linux", "macos", "windows", "unraid", "synology", "ugos", "other"; auto detects the system from what the host reports.

Default "auto"

groupstring

asleep_policyenum

one of "down", "unobserved"; What a host that went to sleep counts as: down or unobserved.

Default "down"

suppress_children_when_downboolean

alert_groupingboolean

depends_onarray of string

max items 32; each pattern ^(host|check|backup|heartbeat):[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$; Objects this one waits on: while one is down, its notifications are held and the incident records the parent.

Default []

collectobjectRequired

collect.methodenumRequired

one of "agent", "ssh", "relay"; agent (the host connects out), ssh (the hub connects in) or relay (another agent pulls it).

collect.collectorsarray of string

Limits the agent's extra collectors to these (smart, unraid, docker, services, power, vpn, gpu).

collect.relay_forarray of string

each pattern ^[a-z0-9][a-z0-9_-]{0,63}$; Host ids this agent pulls over SSH on the hub's behalf.

collect.push_intervalduration

How often the hub expects an agent push. Default 60s.

collect.intervalduration

SSH poll interval; default 60s, minimum 15s SSH poll interval. Default 60s, minimum 15s.

collect.tokenstringsecretguarded

min length 1; A fixed token for an agent host, as an alternative to enrolling. The agent presents it in place of an enrollment token.

sshobject

The connection for SSH collection, custom checks and agentless backup probes. Required when collect.method is ssh.

ssh.targetstringRequiredexec

pattern ^[A-Za-z0-9_][A-Za-z0-9._-]*@(?:[A-Za-z0-9_][A-Za-z0-9._-]*|\[[0-9A-Fa-f:.]+\])(?::\d{1,5})?$; user@host[:port].

ssh.jumparray of stringexec

each pattern ^(?:[A-Za-z0-9_][A-Za-z0-9._-]*@)?(?:[A-Za-z0-9_][A-Za-z0-9._-]*|\[[0-9A-Fa-f:.]+\])(?::\d{1,5})?$; Jump hosts, each a host id or user@host[:port].

Default []

ssh.identity_filestringexec

min length 1; max length 1024; A path read by ssh, never inline key material A path to a private key file on the hub, never the key itself.

ssh.host_keystringexec

min length 1; max length 2048; Pinned host key; absent = trust on first use A pinned host key line (ssh-ed25519 AAAA...). Absent means trust on first use; see security.md.

ssh.sudobooleanexec

Run root-only reads as sudo -n; needs a NOPASSWD rule Run root-only reads as sudo -n. Needs a NOPASSWD rule on the host.

Default false

thresholdsobject

Overrides defaults.yaml per metric.

thresholds.cpu[number, number]

thresholds.mem[number, number]

thresholds.gpu[number, number]

thresholds.disk[number, number]

thresholds.temp[number, number]

thresholds.load[number, number]

sustainduration

tlsobject

tls.warn_daysinteger

min 1

tls.critical_daysinteger

min 1

terminalobject

Lets people open a terminal on this host. The terminal is also off globally until terminal.enabled.

terminal.targetstringRequiredexec

pattern ^[A-Za-z0-9_][A-Za-z0-9._-]*@(?:[A-Za-z0-9_][A-Za-z0-9._-]*|\[[0-9A-Fa-f:.]+\])(?::\d{1,5})?$; user@host[:port] the terminal logs in as. Use a different account from the collector; see security.md.

terminal.jumparray of stringexec

each pattern ^(?:[A-Za-z0-9_][A-Za-z0-9._-]*@)?(?:[A-Za-z0-9_][A-Za-z0-9._-]*|\[[0-9A-Fa-f:.]+\])(?::\d{1,5})?$

Default []

terminal.identity_filestringexec

min length 1; max length 1024; A path read by ssh, never inline key material A path to a private key file on the hub.

terminal.login_shellbooleanexec

Send the startup command through a login shell (default true).

terminal.startup_commandstring or nullexec

Overrides the global default. Absent inherits it; an empty string is a plain login shell.

agent_updatesone of

agent_updates{form 1}.modeenum

one of "automatic", "one_click", "notify"

agent_updates{form 2}null

custom_checksarray of object

Your own checks, run over SSH. See custom-checks.md.

custom_checks[]object

custom_checks[].idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

custom_checks[].enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

custom_checks[].namestring

custom_checks[].runobjectRequiredexec

Exactly one of command (a line), script (a file under the config folder's scripts/) or agent_command (a name from the host's agent.yaml).

custom_checks[].run.commandstring

min length 1; max length 4096

custom_checks[].run.scriptstring

min length 1; max length 512

custom_checks[].run.agent_commandstring

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

custom_checks[].shellenumexec

one of "sh", "bash", "powershell", "cmd"; Default: sh, or powershell on Windows Default sh, or powershell on Windows.

custom_checks[].intervalduration

Use this or cron, not both.

custom_checks[].cronstring

pattern ^\S+(\s+\S+){4}$; Five fields, in tz.

custom_checks[].tzstring

Default "UTC"

custom_checks[].timeoutduration

Between 1ms and 10m.

Default "30s"

custom_checks[].parseone of

How the output becomes a status. Default: exit code 0 is ok.

Default {"mode":"exit_code","ok_codes":[0]}

custom_checks[].parse{mode=exit_code}.modeliteral "exit_code"Required

custom_checks[].parse{mode=exit_code}.ok_codesarray of integer

min items 1; each min 0; each max 255

Default [0]

custom_checks[].parse{mode=exit_code}.warn_codesarray of integer

each min 0; each max 255

custom_checks[].parse{mode=number}.modeliteral "number"Required

custom_checks[].parse{mode=number}.patternstring

min length 1; max length 1024; One capture group; default is the first number in stdout

custom_checks[].parse{mode=number}.warnnumber

custom_checks[].parse{mode=number}.criticalnumber

custom_checks[].parse{mode=number}.directionenum

one of "above", "below"

Default "above"

custom_checks[].parse{mode=number}.unitstring

max length 16

custom_checks[].parse{mode=json}.modeliteral "json"Required

custom_checks[].parse{mode=json}.fieldsarray of one ofRequired

min items 1

custom_checks[].parse{mode=json}.fields[]one of

custom_checks[].parse{mode=json}.fields[]{path+equals}.pathstringRequired

pattern ^\$

custom_checks[].parse{mode=json}.fields[]{path+equals}.equalsstring or number or boolean or nullRequired

custom_checks[].parse{mode=json}.fields[]{path+below}.pathstringRequired

pattern ^\$

custom_checks[].parse{mode=json}.fields[]{path+below}.belowobjectRequired

custom_checks[].parse{mode=json}.fields[]{path+below}.below.warnnumberRequired

custom_checks[].parse{mode=json}.fields[]{path+below}.below.criticalnumberRequired

custom_checks[].parse{mode=regex}.modeliteral "regex"Required

custom_checks[].parse{mode=regex}.ok_patternstring

min length 1; max length 1024

custom_checks[].parse{mode=regex}.bad_patternstring

min length 1; max length 1024

custom_checks[].parse{mode=regex}.streamenum

one of "stdout", "stderr", "both"

Default "stdout"

custom_checks[].domainenum

one of "hosts", "apps"; hosts (default) makes the check's warn and critical count toward the host's state; apps lists it with the app checks.

Default "hosts"

custom_checks[].depends_onarray of string

Default []

custom_checks[].envmap of stringexec

Passed as environment variables; the way to give a check a secret Environment variables for the check, the way to give it a secret. Names that change how programs load code (PATH, LD_*, NODE_OPTIONS, ...) are refused.

custom_checks[].env.<key>stringsecret

min length 1

custom_checks[].severityenum

one of "info", "warn", "critical"; How serious a failure is. Default warn.

Default "warn"

custom_checks[].after_consecutive_failuresinteger

min 1; Failed runs in a row before it alerts. Falls back to behavior.after_consecutive_failures.

assertsarray of object

max items 64; Rules over facts the host reports, for example { fact: power.sleep_disabled, equals: true }.

Default []

asserts[]object

asserts[].factstringRequired

pattern ^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)*$; max length 128; A dotted path into the host's facts.

asserts[].equalsboolean or number or string

asserts[].not_equalsboolean or number or string

asserts[].minnumber

asserts[].maxnumber

asserts[].matchingarray of string

min items 1; max items 32; each min length 1; each max length 128; Keep only list items whose name matches one of these globs (*, ?).

asserts[].severityenum

one of "warn", "critical"

Default "critical"

asserts[].namestring

min length 1; max length 80; Shown instead of the fact path

asserts[].enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

appsarray of one of

Checks on things running on or near this host.

apps[]one of

apps[]{kind=http}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=http}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=http}.namestring

apps[]{kind=http}.intervalduration

apps[]{kind=http}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$; hub (default) or agent:<host id> to run the check from that agent.

apps[]{kind=http}.severityenum

one of "info", "warn", "critical"

apps[]{kind=http}.tagsarray of string

apps[]{kind=http}.timeoutduration

apps[]{kind=http}.after_consecutive_failuresinteger

min 1

apps[]{kind=http}.depends_onarray of string

Default []

apps[]{kind=http}.kindliteral "http"Required

apps[]{kind=http}.urlstringRequired

format uri

apps[]{kind=http}.methodstring

Default "GET"

apps[]{kind=http}.headersmap of string

apps[]{kind=http}.headers.<key>stringsecret

min length 1

apps[]{kind=http}.expectobject

What a good response looks like.

apps[]{kind=http}.expect.statusinteger

min 100; max 599

apps[]{kind=http}.expect.body_containsstring

apps[]{kind=http}.expect.jsonmap of any

apps[]{kind=http}.expect.json.<key>any

apps[]{kind=http}.expect.max_msinteger

min 1

apps[]{kind=http}.follow_redirectsboolean

apps[]{kind=http}.tls_verifyboolean

Verify the server certificate (default true).

apps[]{kind=http}.tlsobject

apps[]{kind=http}.tls.warn_daysinteger

min 1

apps[]{kind=http}.tls.critical_daysinteger

min 1

apps[]{kind=tcp}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=tcp}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=tcp}.namestring

apps[]{kind=tcp}.intervalduration

apps[]{kind=tcp}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=tcp}.severityenum

one of "info", "warn", "critical"

apps[]{kind=tcp}.tagsarray of string

apps[]{kind=tcp}.timeoutduration

apps[]{kind=tcp}.after_consecutive_failuresinteger

min 1

apps[]{kind=tcp}.depends_onarray of string

Default []

apps[]{kind=tcp}.kindliteral "tcp"Required

apps[]{kind=tcp}.hoststringRequired

apps[]{kind=tcp}.portintegerRequired

min 1; max 65535

apps[]{kind=tcp}.sendstring

Bytes to send after connecting.

apps[]{kind=tcp}.expectstring

Text the reply must contain.

apps[]{kind=tls}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=tls}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=tls}.namestring

apps[]{kind=tls}.intervalduration

apps[]{kind=tls}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=tls}.severityenum

one of "info", "warn", "critical"

apps[]{kind=tls}.tagsarray of string

apps[]{kind=tls}.timeoutduration

apps[]{kind=tls}.after_consecutive_failuresinteger

min 1

apps[]{kind=tls}.depends_onarray of string

Default []

apps[]{kind=tls}.kindliteral "tls"Required

apps[]{kind=tls}.hoststringRequired

apps[]{kind=tls}.portinteger

min 1; max 65535

Default 443

apps[]{kind=tls}.snistring

apps[]{kind=tls}.tlsobject

apps[]{kind=tls}.tls.warn_daysinteger

min 1

apps[]{kind=tls}.tls.critical_daysinteger

min 1

apps[]{kind=ping}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=ping}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=ping}.namestring

apps[]{kind=ping}.intervalduration

apps[]{kind=ping}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=ping}.severityenum

one of "info", "warn", "critical"

apps[]{kind=ping}.tagsarray of string

apps[]{kind=ping}.timeoutduration

apps[]{kind=ping}.after_consecutive_failuresinteger

min 1

apps[]{kind=ping}.depends_onarray of string

Default []

apps[]{kind=ping}.kindliteral "ping"Required

apps[]{kind=ping}.hoststringRequired

pattern ^(?:(?!-)[A-Za-z0-9_][A-Za-z0-9_.-]{0,252}|(?=.*:.*:)[0-9A-Fa-f:]+(?:\.\d{1,3}){0,3})$; max length 253

apps[]{kind=ping}.countinteger

min 1; max 10

Default 3

apps[]{kind=ping}.max_loss_pctnumber

min 0; max 100

Default 50

apps[]{kind=ping}.max_rtt_msnumber

min 1

apps[]{kind=dns}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=dns}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=dns}.namestringRequired

pattern ^(?:(?!-)[A-Za-z0-9_][A-Za-z0-9_.-]{0,252}|(?=.*:.*:)[0-9A-Fa-f:]+(?:\.\d{1,3}){0,3})$; max length 253

apps[]{kind=dns}.intervalduration

apps[]{kind=dns}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=dns}.severityenum

one of "info", "warn", "critical"

apps[]{kind=dns}.tagsarray of string

apps[]{kind=dns}.timeoutduration

apps[]{kind=dns}.after_consecutive_failuresinteger

min 1

apps[]{kind=dns}.depends_onarray of string

Default []

apps[]{kind=dns}.kindliteral "dns"Required

apps[]{kind=dns}.typeenum

one of "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "PTR"

Default "A"

apps[]{kind=dns}.serverstring

pattern ^(?:\d{1,3}(?:\.\d{1,3}){3}(?::\d{1,5})?|(?=.*:.*:)[0-9A-Fa-f:.]+|\[[0-9A-Fa-f:.]+\]:\d{1,5})$

apps[]{kind=dns}.expectobject

apps[]{kind=dns}.expect.containsarray of string

min items 1; max items 20; each min length 1; each max length 512

apps[]{kind=dns}.expect.equalsarray of string

min items 1; max items 20; each min length 1; each max length 512

apps[]{kind=domain}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=domain}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=domain}.namestringRequired

pattern ^(?!-)(?:[A-Za-z0-9-]{1,63}\.)+[A-Za-z][A-Za-z0-9-]{1,62}$

apps[]{kind=domain}.intervalduration

apps[]{kind=domain}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=domain}.severityenum

one of "info", "warn", "critical"

apps[]{kind=domain}.tagsarray of string

apps[]{kind=domain}.timeoutduration

apps[]{kind=domain}.after_consecutive_failuresinteger

min 1

apps[]{kind=domain}.depends_onarray of string

Default []

apps[]{kind=domain}.kindliteral "domain"Required

apps[]{kind=domain}.warn_daysinteger

min 1

Default 30

apps[]{kind=domain}.critical_daysinteger

min 1

Default 7

apps[]{kind=domain}.rdap_urlstring

format uri

apps[]{kind=synthetic}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=synthetic}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=synthetic}.namestring

apps[]{kind=synthetic}.intervalduration

apps[]{kind=synthetic}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=synthetic}.severityenum

one of "info", "warn", "critical"

apps[]{kind=synthetic}.tagsarray of string

apps[]{kind=synthetic}.timeoutduration

apps[]{kind=synthetic}.after_consecutive_failuresinteger

min 1

apps[]{kind=synthetic}.depends_onarray of string

Default []

apps[]{kind=synthetic}.kindliteral "synthetic"Required

apps[]{kind=synthetic}.stepsarray of objectRequired

min items 1

apps[]{kind=synthetic}.steps[]object

apps[]{kind=synthetic}.steps[].namestringRequired

apps[]{kind=synthetic}.steps[].requestobjectRequired

apps[]{kind=synthetic}.steps[].request.methodstring

Default "GET"

apps[]{kind=synthetic}.steps[].request.urlstringRequired

apps[]{kind=synthetic}.steps[].request.headersmap of string

apps[]{kind=synthetic}.steps[].request.headers.<key>stringsecret

min length 1

apps[]{kind=synthetic}.steps[].request.bodystring

apps[]{kind=synthetic}.steps[].extractmap of string

apps[]{kind=synthetic}.steps[].extract.<key>string

apps[]{kind=synthetic}.steps[].expectobject

apps[]{kind=synthetic}.steps[].expect.statusinteger

min 100; max 599

apps[]{kind=synthetic}.steps[].expect.body_containsstring

apps[]{kind=synthetic}.steps[].expect.jsonmap of any

apps[]{kind=synthetic}.steps[].expect.json.<key>any

apps[]{kind=synthetic}.steps[].expect.max_msinteger

min 1

apps[]{kind=synthetic}.cleanuparray of object

apps[]{kind=synthetic}.cleanup[]object

apps[]{kind=synthetic}.cleanup[].namestringRequired

apps[]{kind=synthetic}.cleanup[].requestobjectRequired

apps[]{kind=synthetic}.cleanup[].request.methodstring

Default "GET"

apps[]{kind=synthetic}.cleanup[].request.urlstringRequired

apps[]{kind=synthetic}.cleanup[].request.headersmap of string

apps[]{kind=synthetic}.cleanup[].request.headers.<key>stringsecret

min length 1

apps[]{kind=synthetic}.cleanup[].request.bodystring

apps[]{kind=synthetic}.cleanup[].extractmap of string

apps[]{kind=synthetic}.cleanup[].extract.<key>string

apps[]{kind=synthetic}.cleanup[].expectobject

apps[]{kind=synthetic}.cleanup[].expect.statusinteger

min 100; max 599

apps[]{kind=synthetic}.cleanup[].expect.body_containsstring

apps[]{kind=synthetic}.cleanup[].expect.jsonmap of any

apps[]{kind=synthetic}.cleanup[].expect.json.<key>any

apps[]{kind=synthetic}.cleanup[].expect.max_msinteger

min 1

apps[]{kind=log}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=log}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=log}.namestring

apps[]{kind=log}.intervalduration

apps[]{kind=log}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=log}.severityenum

one of "info", "warn", "critical"

apps[]{kind=log}.tagsarray of string

apps[]{kind=log}.timeoutduration

apps[]{kind=log}.after_consecutive_failuresinteger

min 1

apps[]{kind=log}.depends_onarray of string

Default []

apps[]{kind=log}.kindliteral "log"Required

apps[]{kind=log}.sourceobjectRequired

Where to read the log: a path on the host, or a command that prints it.

apps[]{kind=log}.source.pathstring

apps[]{kind=log}.source.commandstringexec

apps[]{kind=log}.formatenumRequired

one of "regex", "json"

apps[]{kind=log}.line_patternstring

apps[]{kind=log}.errorobject

apps[]{kind=log}.error.level_inarray of string

apps[]{kind=log}.error_patternstring

apps[]{kind=log}.windowduration

Default "24h"

backupsarray of object

See backups.md.

backups[]object

backups[].idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

backups[].enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

backups[].namestring

backups[].typestringRequired

min length 1; Picks the log pattern pack the log check (B2) uses: rsync, restic, borg, tar, sqlite, rclone, ccc or time_machine. Any other value reads as the generic pack.

backups[].sourceobjectRequired

backups[].source.hoststringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

backups[].source.pathstringRequired

backups[].destone of

backups[].dest{host+path}.hoststringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

backups[].dest{host+path}.pathstringRequired

backups[].dest{s3}.s3objectRequired

backups[].dest{s3}.s3.bucketstringRequired

min length 1

backups[].dest{s3}.s3.prefixstring

Default ""

backups[].dest{s3}.s3.regionstring

Default "us-east-1"

backups[].dest{s3}.s3.endpointstring

format uri

backups[].dest{s3}.s3.path_styleboolean

backups[].dest{s3}.s3.access_keystringRequiredsecret

min length 1

backups[].dest{s3}.s3.secret_keystringRequiredsecret

min length 1

backups[].schedulestringRequired

min length 1; Cron expression for when the backup should run.

backups[].tzstring

Default "UTC"

backups[].graceduration

How late a run may be before it counts as missed.

Default "30m"

backups[].heartbeatstring

pattern ^[a-z0-9][a-z0-9_-]{0,63}$; Id of a heartbeat that the job pings; its pings are the run reports.

backups[].depends_onarray of string

Default []

backups[].size_band[string, string]

[low, high] sizes the result must fall inside, for example [9.2TB, 10.6TB].

backups[].max_drop_pctnumber

min 0; max 100; Fail when the size dropped by more than this share since the last run.

backups[].dest_min_freestring

pattern ^\d+(\.\d+)?\s?(B|KB|MB|GB|TB)$

backups[].dest_mountboolean or string

backups[].size_methodenum

one of "report", "artifact", "du"

backups[].integrityobject

backups[].integrity.methodenumRequired

one of "sqlite_integrity", "tar_list", "zip_test", "checksum_sample", "restic_check", "tmutil_verify", "tar_entries", "named"

backups[].integrity.globstring

pattern ^[A-Za-z0-9._*?-]{1,128}$

backups[].integrity.modeenum

one of "quick", "full"

backups[].integrity.sampleinteger

min 1; max 100

backups[].integrity.entriesarray of string

min items 1; max items 100; each pattern ^[^\x00-\x1f\x7f]+$; each min length 1; each max length 512

backups[].integrity.commandstring

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

backups[].integrity.password_filestring

pattern ^[^\x00-\x1f\x7f]+$; min length 1; max length 512

backups[].logobject

backups[].log.hoststring

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

backups[].log.pathstring

min length 1; max length 1024

backups[].log.commandstring

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

backups[].error_patternsarray of string

max items 20; each min length 1; each max length 200

backups[].retentionobject

backups[].retention.minintegerRequired

min 0

backups[].retention.maxintegerRequired

min 0

backups[].retention.globstring

pattern ^[A-Za-z0-9._*?-]{1,128}$

backups[].restore_testany

Not supported in this version Reserved. Restore tests arrive in a later release.

backups[].writable_probeany

Not supported in this version Reserved. Not supported in this version.

backups[].severityenum

one of "info", "warn", "critical"

backups[].after_failuresinteger

min 1

heartbeatsarray of object

Jobs that ping the hub. See heartbeats.md.

heartbeats[]object

heartbeats[].idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

heartbeats[].enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

heartbeats[].namestring

heartbeats[].descriptionstring

max length 2000; What this job is, in plain text (up to 2000 characters).

heartbeats[].ownerstring

max length 120; Who to ask when it fails: a person or team name (up to 120 characters).

heartbeats[].runbookstring

max length 2000; Web link (http or https) to what to do when it fails. Shown in the UI and sent in alerts.

heartbeats[].tagsarray of string

Tags a routing rule can match with when: { tag: ... }.

heartbeats[].schedulestringRequired

min length 1; How often it should succeed: a duration such as "6h" (at least every 6 hours, counted from the last success; tz is ignored) or a five-field cron expression read in tz. Cron expression for when the job should ping.

heartbeats[].keywordsobject

heartbeats[].keywords.fail_if_presentarray of string

max items 16; each min length 1; each max length 128; Any of these in the output of a success ping turns it into a failure. At most 16 strings of at most 128 characters.

heartbeats[].keywords.fail_if_absentarray of string

max items 16; each min length 1; each max length 128; All of these must appear in the output of a success ping, or it is a failure. A success ping with no body fails.

heartbeats[].keywords.case_sensitiveboolean

Match case exactly. Default false.

Default false

heartbeats[].depends_onarray of string

Default []

heartbeats[].tzstring

Default "UTC"

heartbeats[].graceduration

How late a ping may be before it alerts.

Default "10m"

heartbeats[].max_durationduration

Alert if a started run takes longer than this.

heartbeats[].ping_tokenstringsecret

min length 1; Pins the token in the ping URL (16 to 64 characters of A-Z a-z 0-9 _ -). Generated and kept stable if left out.

heartbeats[].severityenum

one of "info", "warn", "critical"

checks/*.yaml#

Apps and heartbeats that do not belong to one host. (proto/config/checks.schema.json)

appsarray of one of

Same fields as apps in a host file.

apps[]one of

apps[]{kind=http}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=http}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=http}.namestring

apps[]{kind=http}.intervalduration

apps[]{kind=http}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=http}.severityenum

one of "info", "warn", "critical"

apps[]{kind=http}.tagsarray of string

apps[]{kind=http}.timeoutduration

apps[]{kind=http}.after_consecutive_failuresinteger

min 1

apps[]{kind=http}.depends_onarray of string

Default []

apps[]{kind=http}.kindliteral "http"Required

apps[]{kind=http}.urlstringRequired

format uri

apps[]{kind=http}.methodstring

Default "GET"

apps[]{kind=http}.headersmap of string

apps[]{kind=http}.headers.<key>stringsecret

min length 1

apps[]{kind=http}.expectobject

apps[]{kind=http}.expect.statusinteger

min 100; max 599

apps[]{kind=http}.expect.body_containsstring

apps[]{kind=http}.expect.jsonmap of any

apps[]{kind=http}.expect.json.<key>any

apps[]{kind=http}.expect.max_msinteger

min 1

apps[]{kind=http}.follow_redirectsboolean

apps[]{kind=http}.tls_verifyboolean

apps[]{kind=http}.tlsobject

apps[]{kind=http}.tls.warn_daysinteger

min 1

apps[]{kind=http}.tls.critical_daysinteger

min 1

apps[]{kind=tcp}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=tcp}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=tcp}.namestring

apps[]{kind=tcp}.intervalduration

apps[]{kind=tcp}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=tcp}.severityenum

one of "info", "warn", "critical"

apps[]{kind=tcp}.tagsarray of string

apps[]{kind=tcp}.timeoutduration

apps[]{kind=tcp}.after_consecutive_failuresinteger

min 1

apps[]{kind=tcp}.depends_onarray of string

Default []

apps[]{kind=tcp}.kindliteral "tcp"Required

apps[]{kind=tcp}.hoststringRequired

apps[]{kind=tcp}.portintegerRequired

min 1; max 65535

apps[]{kind=tcp}.sendstring

apps[]{kind=tcp}.expectstring

apps[]{kind=tls}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=tls}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=tls}.namestring

apps[]{kind=tls}.intervalduration

apps[]{kind=tls}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=tls}.severityenum

one of "info", "warn", "critical"

apps[]{kind=tls}.tagsarray of string

apps[]{kind=tls}.timeoutduration

apps[]{kind=tls}.after_consecutive_failuresinteger

min 1

apps[]{kind=tls}.depends_onarray of string

Default []

apps[]{kind=tls}.kindliteral "tls"Required

apps[]{kind=tls}.hoststringRequired

apps[]{kind=tls}.portinteger

min 1; max 65535

Default 443

apps[]{kind=tls}.snistring

apps[]{kind=tls}.tlsobject

apps[]{kind=tls}.tls.warn_daysinteger

min 1

apps[]{kind=tls}.tls.critical_daysinteger

min 1

apps[]{kind=ping}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=ping}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=ping}.namestring

apps[]{kind=ping}.intervalduration

apps[]{kind=ping}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=ping}.severityenum

one of "info", "warn", "critical"

apps[]{kind=ping}.tagsarray of string

apps[]{kind=ping}.timeoutduration

apps[]{kind=ping}.after_consecutive_failuresinteger

min 1

apps[]{kind=ping}.depends_onarray of string

Default []

apps[]{kind=ping}.kindliteral "ping"Required

apps[]{kind=ping}.hoststringRequired

pattern ^(?:(?!-)[A-Za-z0-9_][A-Za-z0-9_.-]{0,252}|(?=.*:.*:)[0-9A-Fa-f:]+(?:\.\d{1,3}){0,3})$; max length 253

apps[]{kind=ping}.countinteger

min 1; max 10

Default 3

apps[]{kind=ping}.max_loss_pctnumber

min 0; max 100

Default 50

apps[]{kind=ping}.max_rtt_msnumber

min 1

apps[]{kind=dns}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=dns}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=dns}.namestringRequired

pattern ^(?:(?!-)[A-Za-z0-9_][A-Za-z0-9_.-]{0,252}|(?=.*:.*:)[0-9A-Fa-f:]+(?:\.\d{1,3}){0,3})$; max length 253

apps[]{kind=dns}.intervalduration

apps[]{kind=dns}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=dns}.severityenum

one of "info", "warn", "critical"

apps[]{kind=dns}.tagsarray of string

apps[]{kind=dns}.timeoutduration

apps[]{kind=dns}.after_consecutive_failuresinteger

min 1

apps[]{kind=dns}.depends_onarray of string

Default []

apps[]{kind=dns}.kindliteral "dns"Required

apps[]{kind=dns}.typeenum

one of "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "PTR"

Default "A"

apps[]{kind=dns}.serverstring

pattern ^(?:\d{1,3}(?:\.\d{1,3}){3}(?::\d{1,5})?|(?=.*:.*:)[0-9A-Fa-f:.]+|\[[0-9A-Fa-f:.]+\]:\d{1,5})$

apps[]{kind=dns}.expectobject

apps[]{kind=dns}.expect.containsarray of string

min items 1; max items 20; each min length 1; each max length 512

apps[]{kind=dns}.expect.equalsarray of string

min items 1; max items 20; each min length 1; each max length 512

apps[]{kind=domain}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=domain}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=domain}.namestringRequired

pattern ^(?!-)(?:[A-Za-z0-9-]{1,63}\.)+[A-Za-z][A-Za-z0-9-]{1,62}$

apps[]{kind=domain}.intervalduration

apps[]{kind=domain}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=domain}.severityenum

one of "info", "warn", "critical"

apps[]{kind=domain}.tagsarray of string

apps[]{kind=domain}.timeoutduration

apps[]{kind=domain}.after_consecutive_failuresinteger

min 1

apps[]{kind=domain}.depends_onarray of string

Default []

apps[]{kind=domain}.kindliteral "domain"Required

apps[]{kind=domain}.warn_daysinteger

min 1

Default 30

apps[]{kind=domain}.critical_daysinteger

min 1

Default 7

apps[]{kind=domain}.rdap_urlstring

format uri

apps[]{kind=synthetic}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=synthetic}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=synthetic}.namestring

apps[]{kind=synthetic}.intervalduration

apps[]{kind=synthetic}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=synthetic}.severityenum

one of "info", "warn", "critical"

apps[]{kind=synthetic}.tagsarray of string

apps[]{kind=synthetic}.timeoutduration

apps[]{kind=synthetic}.after_consecutive_failuresinteger

min 1

apps[]{kind=synthetic}.depends_onarray of string

Default []

apps[]{kind=synthetic}.kindliteral "synthetic"Required

apps[]{kind=synthetic}.stepsarray of objectRequired

min items 1

apps[]{kind=synthetic}.steps[]object

apps[]{kind=synthetic}.steps[].namestringRequired

apps[]{kind=synthetic}.steps[].requestobjectRequired

apps[]{kind=synthetic}.steps[].request.methodstring

Default "GET"

apps[]{kind=synthetic}.steps[].request.urlstringRequired

apps[]{kind=synthetic}.steps[].request.headersmap of string

apps[]{kind=synthetic}.steps[].request.headers.<key>stringsecret

min length 1

apps[]{kind=synthetic}.steps[].request.bodystring

apps[]{kind=synthetic}.steps[].extractmap of string

apps[]{kind=synthetic}.steps[].extract.<key>string

apps[]{kind=synthetic}.steps[].expectobject

apps[]{kind=synthetic}.steps[].expect.statusinteger

min 100; max 599

apps[]{kind=synthetic}.steps[].expect.body_containsstring

apps[]{kind=synthetic}.steps[].expect.jsonmap of any

apps[]{kind=synthetic}.steps[].expect.json.<key>any

apps[]{kind=synthetic}.steps[].expect.max_msinteger

min 1

apps[]{kind=synthetic}.cleanuparray of object

apps[]{kind=synthetic}.cleanup[]object

apps[]{kind=synthetic}.cleanup[].namestringRequired

apps[]{kind=synthetic}.cleanup[].requestobjectRequired

apps[]{kind=synthetic}.cleanup[].request.methodstring

Default "GET"

apps[]{kind=synthetic}.cleanup[].request.urlstringRequired

apps[]{kind=synthetic}.cleanup[].request.headersmap of string

apps[]{kind=synthetic}.cleanup[].request.headers.<key>stringsecret

min length 1

apps[]{kind=synthetic}.cleanup[].request.bodystring

apps[]{kind=synthetic}.cleanup[].extractmap of string

apps[]{kind=synthetic}.cleanup[].extract.<key>string

apps[]{kind=synthetic}.cleanup[].expectobject

apps[]{kind=synthetic}.cleanup[].expect.statusinteger

min 100; max 599

apps[]{kind=synthetic}.cleanup[].expect.body_containsstring

apps[]{kind=synthetic}.cleanup[].expect.jsonmap of any

apps[]{kind=synthetic}.cleanup[].expect.json.<key>any

apps[]{kind=synthetic}.cleanup[].expect.max_msinteger

min 1

apps[]{kind=log}.idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

apps[]{kind=log}.enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

apps[]{kind=log}.namestring

apps[]{kind=log}.intervalduration

apps[]{kind=log}.run_onstring

pattern ^(hub|agent:[a-z0-9][a-z0-9_-]*)$

apps[]{kind=log}.severityenum

one of "info", "warn", "critical"

apps[]{kind=log}.tagsarray of string

apps[]{kind=log}.timeoutduration

apps[]{kind=log}.after_consecutive_failuresinteger

min 1

apps[]{kind=log}.depends_onarray of string

Default []

apps[]{kind=log}.kindliteral "log"Required

apps[]{kind=log}.sourceobjectRequired

apps[]{kind=log}.source.pathstring

apps[]{kind=log}.source.commandstringexec

apps[]{kind=log}.formatenumRequired

one of "regex", "json"

apps[]{kind=log}.line_patternstring

apps[]{kind=log}.errorobject

apps[]{kind=log}.error.level_inarray of string

apps[]{kind=log}.error_patternstring

apps[]{kind=log}.windowduration

Default "24h"

heartbeatsarray of object

Same fields as heartbeats in a host file.

heartbeats[]object

heartbeats[].idstringRequired

pattern ^[a-z0-9][a-z0-9_-]{0,63}$

heartbeats[].enabledboolean

false switches this off: no collection, no alerts, history kept. Absent = on.

heartbeats[].namestring

heartbeats[].descriptionstring

max length 2000; What this job is, in plain text (up to 2000 characters).

heartbeats[].ownerstring

max length 120; Who to ask when it fails: a person or team name (up to 120 characters).

heartbeats[].runbookstring

max length 2000; Web link (http or https) to what to do when it fails. Shown in the UI and sent in alerts.

heartbeats[].tagsarray of string

Tags a routing rule can match with when: { tag: ... }.

heartbeats[].schedulestringRequired

min length 1; How often it should succeed: a duration such as "6h" (at least every 6 hours, counted from the last success; tz is ignored) or a five-field cron expression read in tz.

heartbeats[].keywordsobject

heartbeats[].keywords.fail_if_presentarray of string

max items 16; each min length 1; each max length 128; Any of these in the output of a success ping turns it into a failure. At most 16 strings of at most 128 characters.

heartbeats[].keywords.fail_if_absentarray of string

max items 16; each min length 1; each max length 128; All of these must appear in the output of a success ping, or it is a failure. A success ping with no body fails.

heartbeats[].keywords.case_sensitiveboolean

Match case exactly. Default false.

Default false

heartbeats[].depends_onarray of string

Default []

heartbeats[].tzstring

Default "UTC"

heartbeats[].graceduration

Default "10m"

heartbeats[].max_durationduration

heartbeats[].ping_tokenstringsecret

min length 1

heartbeats[].severityenum

one of "info", "warn", "critical"