> Section: [4. Configuration](https://jaque.sh/docs/config/cue-in-practice.md)
> Next: notifications/contacts-and-policies
> Index: https://jaque.sh/llms.txt


This is a systematic reference, one section per top-level CUE definition in
`config/schema.cue`: every field, its type, its default and the
constraint the schema enforces on it. For a guided, example-driven
walkthrough of building a config against this schema, see [CUE in
practice](../config/cue-in-practice.md) instead.

## 1. `#Schema`

The root object a config file unifies against. Closed: an unknown
top-level regular field is a schema error.

| Field | Type | Default | Constraint |
|---|---|---|---|
| `hosts` | `{[Name=string]: #Host}` | - | required (may be empty) |
| `resources` | `#Resources` | `{}` | see `#Resources` |
| `commands` | `{[Name=string]: #Command}` | `{}` | see `#Command` |
| `contacts` | `{[Name=string]: #Contact}` | `{}` | see `#Contact` |
| `notifications` | `{[Name=string]: #NotificationPolicy}` | `{}` | see `#NotificationPolicy` |
| `views` | `{[Name=string]: #View}` | `{}` | see `#View` |
| `sinks` | `{[=~"^[a-z][a-z0-9_-]*$"]: #Sink}` | - | optional, see `#Sink` |

## 2. `#Host`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `address` | `string` | - | required, non-empty |
| `parents` | `[...string]` | `[]` | - |
| `vars` | `#Vars` | `{}` | see `#Vars` |
| `check` | `#Check` | - | required |
| `services` | `{[Name=string]: #Service}` | `{}` | - |
| `notification` | `string` | `""` | empty means the host never notifies |
| `zone` | `string` | `"default"` | non-empty |
| `labels` | `#Labels` | `{}` | see `#Labels` |

## 3. `#Service`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `vars` | `#Vars` | `{}` | see `#Vars` |
| `check` | `#Check` | - | required |
| `notification` | `string` | `""` | empty means the service never notifies |
| `zone` | `string` | `""` | empty inherits the host's `zone` |
| `labels` | `#Labels` | `{}` | see `#Labels` |

## 4. `#Command`

A command template: instantiated by `#CommandCheck` (a check) and by the
`command` contact type, both via a name that is a key into the top-level
`commands` map.

| Field | Type | Default | Constraint |
|---|---|---|---|
| `line` | `string` | - | required, non-empty |
| `shell` | `bool` | `false` | `false` tokenizes `line`; `true` hands it whole to `/bin/sh -c` after macro expansion |

## 5. `#Schedule`

Embedded by every branch of `#Checks`.

| Field | Type | Default | Constraint |
|---|---|---|---|
| `check_interval` | `time.Duration` | `"60s"` | - |
| `retry_interval` | `time.Duration` | `"15s"` | - |
| `timeout` | `time.Duration` | `"10s"` | - |
| `max_attempts` | `int` | `3` | `>=1` |
| `flap` | `#Flap` | - | required, see `#Flap` |

## 6. `#Flap`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `enabled` | `bool` | `true` | - |
| `alpha` | `number` | `0.1` | `>0 & <=1` |
| `high_threshold` | `number` | `0.3` | `>=0 & <=1` |
| `low_threshold` | `number` | `0.15` | `>=0 & <=high_threshold` |
| `notify_on_flap_stop` | `bool` | `false` | `true` sends the problem notification right after `FlappingStop` on the same result, instead of waiting for the next result to re-notify |

## 7. The `#Checks` branches

Every branch unifies `#Schedule` with its own type-specific fields;
`type` is the discriminator and matches the branch's key in `#Checks`.

### 7.1 `tcp` (`#TCPCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"tcp"` |
| `address` | `string` | - | required, non-empty (`"host:port"`) |

### 7.2 `http` (`#HTTPCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"http"` |
| `url` | `string` | - | required, non-empty |

### 7.3 `dns` (`#DNSCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"dns"` |
| `server` | `string` | - | required, non-empty (`"host:port"`) |
| `name` | `string` | - | required, non-empty (record to resolve) |

### 7.4 `icmp` (`#ICMPCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"icmp"` |
| `host` | `string` | - | required, non-empty |

### 7.5 `tls` (`#TLSCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"tls"` |
| `address` | `string` | - | required, non-empty |
| `warn_within` | `time.Duration` | `"336h"` | - |
| `crit_within` | `time.Duration` | `"72h"` | - |

### 7.6 `snmp` (`#SNMPCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"snmp"` |
| `address` | `string` | - | required, non-empty |
| `oid` | `string` | - | required, non-empty |
| `community` | `string` | - | v2c; required, non-empty when set |
| `user` | `string` | - | v3 USM; required, non-empty when set |
| `auth_proto` | `string` | `""` | `""`, `"MD5"`, `"SHA"`, `"SHA224"`, `"SHA256"`, `"SHA384"`, `"SHA512"` |
| `auth_pass` | `string` | `""` | - |
| `priv_proto` | `string` | `""` | `""`, `"DES"`, `"AES"`, `"AES192"`, `"AES256"`, `"AES192C"`, `"AES256C"` |
| `priv_pass` | `string` | `""` | - |
| `warn` | `string` | `""` | Nagios threshold range; mutually exclusive with `expect` |
| `crit` | `string` | `""` | Nagios threshold range; mutually exclusive with `expect` |
| `expect` | `string` | `""` | exact-match string; mutually exclusive with `warn`/`crit` |
| `label` | `string` | `""` | perfdata point name; the OID when empty |
| `uom` | `string` | `""` | raw Nagios UOM for gauge values; ignored for counters, which are always `c` |

Exactly one of `community` or `user` must be set -- the schema enforces
this as a disjunction. `auth_proto`/`auth_pass`/`priv_proto`/`priv_pass`
are only meaningful alongside `user`.

### 7.7 `legacy` (`#LegacyCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"legacy"` |
| `path` | `string` | - | required, non-empty |
| `args` | `[...string]` | `[]` | - |

### 7.8 `wasm` (`#WASMCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"wasm"` |
| `module` | `string` | - | required, non-empty (path to a `.wasm` file) |
| `args` | `[...string]` | `[]` | - |

### 7.9 `command` (`#CommandCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"command"` |
| `command` | `string` | - | required, non-empty; key into the top-level `commands` map |
| `args` | `[...string]` | `[]` | - |

### 7.10 `passive` (`#PassiveCheck`)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"passive"` |
| `freshness_threshold` | `time.Duration` | - | required, no default |
| `stale_status` | `string` | `"UNKNOWN"` | `"UNKNOWN"`, `"WARNING"`, `"CRITICAL"` |

`timeout` (from `#Schedule`) has no meaning for `passive`.

## 8. `#Window`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `weekday` | `string` | - | `"sunday"`, `"monday"`, `"tuesday"`, `"wednesday"`, `"thursday"`, `"friday"`, `"saturday"` |
| `start` | `string` | - | `=~"^([01][0-9]\|2[0-3]):[0-5][0-9]$"` |
| `end` | `string` | - | `=~"^([01][0-9]\|2[0-3]\|24):[0-5][0-9]$"` |

A window does not wrap past midnight; an overnight period is two windows.
`end` may be `"24:00"`; `start` may not.

## 9. `#View`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `selector` | `string` | - | required; parsed into a selector at decode time |
| `description` | `string` | `""` | free text, not parsed |

The map key under `views:` is the display name and is deliberately
unconstrained -- no pattern, unlike `#Labels`' keys -- because it is never
parsed.

## 10. `#Labels`

| Position | Pattern |
|---|---|
| key | `=~"^[a-z][a-z0-9_.-]*$"` |
| value | `=~"^[a-zA-Z0-9][a-zA-Z0-9_.:/-]*$"` |

These patterns are copied from the single definition the runtime enforces
internally; a test pins the two copies together so drift fails the build.

## 11. `#Vars`

| Position | Pattern |
|---|---|
| key | `=~"^[A-Z][A-Z0-9_]*$"` |
| value | `string` |

A key `PASSWORD` on a host is referenced as `$_HOSTPASSWORD$`; on a
service, as `$_SERVICEPASSWORD$`. See [Security considerations](#17-security-considerations).

## 12. `#Resources`

| Position | Pattern |
|---|---|
| key | `=~"^USER[0-9]+$"` |
| value | `string` |

A key that is not `USER<digits>` is a config error, not a silently
unreachable value.

## 13. `#Contact` and the contact types

Four discriminated variants of `#Contact`, each also carrying `labels`
(`#Labels`, default `{}`).

### `email`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"email"` |
| `address` | `string` | - | required, non-empty |

### `webhook`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"webhook"` |
| `url` | `string` | - | required, non-empty |

### `command`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"command"` |
| `command` | `string` | - | required, non-empty; key into the top-level `commands` map |
| `args` | `[...string]` | `[]` | - |
| `address` | `string` | `""` | what `$CONTACTEMAIL$` expands to for this contact |

### `telegram`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `type` | `string` | - | fixed `"telegram"` |
| `chat_id` | `string` | - | required, non-empty |

## 14. `#NotificationPolicy`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `period` | `[...#Window]` | `[]` | empty means "always notify" |
| `levels` | `[...#EscalationLevel]` | - | required, non-empty |

## 15. `#EscalationLevel`

| Field | Type | Default | Constraint |
|---|---|---|---|
| `contacts` | `[...string]` | - | required, non-empty |
| `threshold` | `int` | `0` | `>=0`; `0` means never escalate past this level |
| `renotify_interval` | `time.Duration` | `"1h"` | - |
| `disabled_kinds` | `[...string]` | `[]` | each one of `"PROBLEM"`, `"RECOVERY"`, `"STATUS_CHANGE"`, `"FLAPPING_START"`, `"FLAPPING_STOP"` |

## 16. `#Sinks`

Every sink shares `#SinkCommon`, then adds its own type-specific fields.
The map key under `sinks:` matches `=~"^[a-z][a-z0-9_-]*$"`.

### `#SinkCommon` (shared by every sink type)

| Field | Type | Default | Constraint |
|---|---|---|---|
| `input` | `string` | `"metrics"` | `"metrics"` or `"events"` |
| `selector` | `string` | `""` | a labels selector expression |
| `batch_size` | `int` | `1000` | `>0` |
| `flush_interval` | `time.Duration` | `"5s"` | - |

### Per-type fields

| Type | Field | Type | Default | Constraint |
|---|---|---|---|---|
| `clickhouse` | `url` | `string` | - | required, non-empty |
| `clickhouse` | `table` | `string` | `"perfdata"` | `=~"^[A-Za-z_][A-Za-z0-9_]*$"` |
| `remote_write` | `url` | `string` | - | required, non-empty |
| `remote_write` | `cursor` | `string` | `""` | - |
| `archive` | `url` | `string` | - | required, non-empty |
| `archive` | `segment_bytes` | `int` | `67108864` | `>0` |
| `archive` | `input` | `string` | - | fixed `"events"` |
| `http` | `url` | `string` | - | required, non-empty |
| `http` | `headers` | `{[string]: string}` | `{}` | - |
| `http` | `cursor` | `string` | `""` | - |
| `exec` | `command` | `[string, ...string]` | - | required, non-empty |
| `exec` | `cursor` | `string` | `""` | - |
| `file` | `path` | `string` | - | required, non-empty |
| `file` | `rotate_bytes` | `int` | `67108864` | `>0` |
| `file` | `cursor` | `string` | `""` | - |
| `otlp` | `url` | `string` | - | required, non-empty |
| `otlp` | `headers` | `{[string]: string}` | `{}` | - |
| `otlp` | `cursor` | `string` | `""` | - |

## 17. Security considerations

The config file is plaintext CUE on disk, not a secrets store. `#Vars`
values are free-form strings and commonly carry material like SNMP
community strings or plugin passwords, expanded into check and
notification command lines via `$_HOSTxxx$`/`$_SERVICExxx$` macros -- file
permissions on the config path are the only protection. `#SNMPCheck`'s
`auth_pass`/`priv_pass` are the same: plaintext in the file, plaintext in
the resulting SNMP request per the v3 USM protocol. Sink and contact URLs
(`clickhouse`, `remote_write`, `http`, `otlp`, `webhook`) can embed
credentials in their query string or headers; `QueryService.ListSinks` and
`ListContacts` deliberately omit these fields from their response so the
API surface never echoes them back (see [Command and query
service](../api/command-and-query-service.md)). Long-lived secrets that
apply process-wide -- the SMTP password, the Telegram bot token -- are kept
out of CUE entirely and passed as CLI flags or env vars instead; see
[CLI flags](https://jaque.sh/docs/reference/cli-flags.md), section 9.