kogut.toml

kogut.toml defines services, checks, heartbeats, host alert thresholds, and notification channels. File-managed objects are read-only in the panel.

File handling

The default path is $KOGUT_DATA/kogut.toml; KOGUT_CONFIG overrides it. A missing or empty file means the defaults. All top-level tables are optional. Unknown keys are errors.

kogut checks the file every 2 seconds and applies a valid file atomically. An invalid file stops startup. An invalid reload keeps the previous configuration and reports the error in the panel and log. listen needs a restart. There is no reload signal.

Removing an object from the file removes it from kogut, and deleting the file counts as an empty file. kogut never writes the file. The MCP propose_ tools return tables to add to it, judged as a reload would judge them.

Checks and heartbeats share one namespace with panel-created checks and heartbeats, and channels share another. Panel channel names cannot use the file’s naming scheme, such as ntfy or slack-2. When the file names a check, heartbeat, or channel created in the panel:

• With the same definition, the file takes it over. It becomes file-managed and keeps its id, results, incidents, ping URL, silences, and deliveries. A channel’s secrets are removed from the database. The same definition means, for a check, the same service, type, target, from, every, timeout, method, and expect; for a heartbeat, the same service, schedule, and grace; for a channel, the same type and keys, secrets included.
• With another definition, the file is rejected. The error names the first key that differs, such as check[2].every: a check named "api" was created in the panel with another definition. Make the two equal, or rename one.
• A name used by another kind of object, such as a panel check for a file heartbeat, rejects the file.

A takeover is one-way: from then on only the file changes the object, and removing it from the file deletes it. A command check never rejects the file: the file’s check takes the name, and the host page names the command check that was left out.

Move panel objects into the file

kogut export prints the checks, heartbeats, and channels created in the panel, and the kogut edge and heartbeat URL set there, as kogut.toml that the next reload takes over. Settings → Move to kogut.toml in the panel copies the same text:

kogut export >> /var/lib/kogut/kogut.toml

Secrets are written as ${NAME} placeholders, listed at the top of the output. Set those variables before kogut reloads the file; until then the reload is rejected and the panel objects stay as they are.

A service or host already in the database becomes file-managed when the file names it, in [[service]] hosts or in [[host]]. A [[host]] never clashes with a panel host: the file takes it over. If the file later drops it, it stays panel-managed while panel checks use it. Sites, users, tokens, ping URLs, silences, maintenance windows, and the status page exist only in the database.

Check the file

kogut config check checks a file without starting the server. In GitHub Actions, run it from the image; --allow-unset checks the file without its secrets:

- name: Check kogut.toml
  run: docker run --rm -v "$PWD:/repo:ro" ghcr.io/piotrkowski/kogut:0.1 config check --allow-unset /repo/kogut.toml

Errors read <file>:<line>:<column>: <key>: <message>. Lines and columns start at 1, columns count characters, and array indexes start at 0:

/var/lib/kogut/kogut.toml:14:3: check[2].every: 5s is too often; checks run at most every 10s

A failed validation points at its key, a missing key at its table, such as the [[check]] line, and a syntax or type error at the exact character. A name clash with the panel gives the key path without a position. Errors about addresses omit the value, which may contain a secret. The startup error, the reload log, and the panel show the same text.

Secrets

String values support ${NAME} substitution from the environment:

secret = "${GITHUB_WEBHOOK_SECRET}"

Names contain letters, digits, and _, and cannot start with a digit. $NAME stays literal. There is no default syntax or recursive expansion. Keys, numbers, and booleans are not expanded. Durations are strings, so every = "${EVERY}" works.

If the variable is unset, kogut reads $CREDENTIALS_DIRECTORY/NAME, without one trailing newline. If neither exists, the file is invalid. Substitutions are read again on reload. File secrets, including channel tokens and check headers, never enter the database.

Durations

A whole number and a unit: ms, s, m, h, or d, such as "500ms", "30s", "5m", "1h", or "7d". Units cannot be combined: write "90m", not "1h30m".

Example

[server]
url = "https://kogut.acme.com"

[[service]]
name = "api"
hosts = ["vps-1"]
depends_on = ["postgres"]

[[service]]
name = "postgres"
hosts = ["vps-1"]

[[check]]
name = "API"
service = "api"
url = "https://api.acme.com/health"
expect = [{ json = "$.db", equals = "ok" }]

[[host]]
name = "vps-1"
disk = 95

[[alert]]
type = "ntfy"
url = "https://ntfy.sh/acme-ops"

[server]

Environment variables override listen and url.

[brand]

Branding for the status page, not the panel. Without [brand], the page and browser tab read “Status”.

[[service]]

A service named by a check or heartbeat but not declared is created with defaults.

[[host]]

Alert thresholds of one agent host. A key you leave out keeps its default. A host named here is created in kogut and becomes file-managed, and its thresholds are read-only in the panel. Removing the table restores the defaults.

[[host]]
name = "nas"
disk = 95
swap = false
temperature = 80
ignore_mounts = ["/mnt/backup"]

Percentages are whole numbers from 1 to 100. false turns that alert off; true is an error. A changed limit applies from the host’s next sample; after a raised limit, the 5 min start again from the first sample above it. Turning off an open alert closes it. The 5 min are fixed.

For hosts added in the panel, set the same values under Alerts → Edit alerts on the host page.

[[check]]

Each check has exactly one target, url, tcp, dns, ping, or domain, which sets its kind. See Checks.

headers

Request headers for an HTTP check, as an inline table of names and string values. Values can use ${NAME}.

• Names are HTTP header names. The same name twice in different case is an error.
• Values allow printable ASCII and tabs, up to 8 KiB, without line breaks. At most 50 headers.
• Connection, Content-Length, Keep-Alive, Proxy-Connection, TE, Trailer, Transfer-Encoding, and Upgrade are set by kogut and are errors here. Host and User-Agent replace kogut’s own.
• The headers go only to the origin of url. A redirect to another scheme, host, or port is followed without them.
• Header values are never logged, shown in the panel, or written to the database. Error messages about a value name the header, not the value.

expect

Each item is one assertion. All must pass for the check to be up.

• Without a status assertion, the response must be 2xx.
• A 429 or 503 that fails the status assertion makes the check degraded, not down, and the body assertions are skipped.
• GET and HEAD checks follow up to 5 redirects. Other methods follow none. kogut reads at most 1 MiB of the body.

When an assertion fails, the alert shows what kogut saw:

status 503, expected 2xx
$.db is "degraded", expected "ok"

[[heartbeat]]

A heartbeat alerts when a scheduled task misses a ping, starting from its first ping. Ping URLs are created in the panel or through the API. To keep a token your jobs already send, set ping_token; see Keep an existing push URL.

[[alert]]

A notification channel. type selects its keys. See Notification channels and How alerts work.

Without allow_private, kogut delivers only to public addresses. Slack, Discord, and Telegram always need one. For other services, such as Microsoft Teams or Pushover, use a webhook to an Apprise API server.

name (optional) names the channel: lowercase letters, digits, and hyphens, such as ops-phone, unique among [[alert]] tables. Without it, the channel is named after its type in file order: ntfy, then ntfy-2, and so on, counting named channels too. A name, or a panel channel’s name, cannot have that form. A named channel with the same name and settings as a panel channel takes it over (see File handling).

[auth]

Sign-in to the panel: passwords, OpenID Connect, and forward auth. Several can be on at once.

[[auth.oidc]]

One table per provider, each a button on the sign-in page. Needs the public URL (KOGUT_URL or [server] url). See OpenID Connect.

[auth.proxy]

A reverse proxy passes the person’s email in a header. See Forward auth.

[github]

Deploys from a GitHub webhook. Without this table, /hooks/github answers 404.

Each [[github.repo]] takes these keys:

Pushes to the default branch, published releases, and successful production deployment statuses become deploy markers. branch is not a supported key.

[edge]

kogut sends the kogut edge watchdog a heartbeat every 30 seconds. This table overrides the panel setting and locks it. Failures retry after 5, 10, 20, and 40 seconds, then every minute.

[retention]

How long data is kept. Each value is between "1h" and "3650d". Older data is deleted in small batches in the background.