KDL basics
MiraServe reads one configuration file written in KDL, a small document language made of named nodes. This page explains the syntax the parser accepts, how the parser reacts to mistakes, and how to check a file before you start or reload the server.
The shape of a config file
A config file has exactly one server block and any number of site blocks. The server block holds settings for the whole process: listeners, TLS, the sandbox, timeouts, limits and telemetry. Each site block describes one website, chosen by the host name the client asks for. Nothing else is allowed at the top level.
This is a complete, valid config that serves one static site over HTTPS:
server {
listen ":443"
listen ":80" redirect-https=#true
tls {
cert "/etc/miraserve/certs/example.com.crt"
key "/etc/miraserve/certs/example.com.key"
}
}
site "example.com" "www.example.com" {
root "/var/www/example"
}
Settings you leave out keep their secure defaults: TLS 1.3 only, post-quantum hybrid key exchange, Landlock and seccomp on Linux, and strict security headers. To see every value after defaults are applied, run miraserve check --dump-normalized.
Syntax
Each line is a node, which MiraServe calls a directive. A node has a name, then optional values, then an optional child block in braces:
- Arguments are values written after the name, such as
"example.com"insite "example.com". - Properties are
name=valuepairs, such asredirect-https=#trueorweight=2. - Child blocks are nested nodes inside
{ … }.
Write strings in double quotes, including host names and paths. Write integers without quotes (keep-versions 20). Put one directive per line. A semicolon also ends a node, so listen ":443"; listen ":8443" on one line works, but one directive per line is easier to read and diff.
Booleans and KDL versions
The parser accepts both KDL version 2 and KDL version 1. It tries version 2 first and falls back to version 1. The visible difference is how you write booleans:
| KDL version | True | False |
|---|---|---|
| 2 (used on this site) | #true | #false |
| 1 | true | false |
Pick one version for the whole file. A file that mixes #true and true is valid in neither version, and check stops with error E001 and the message Expected identifier string at the first bare true. Some older examples use the version 1 form; they are still valid on their own.
Comments
// textcomments out the rest of the line./* text */comments out a span, which can cover several lines./-in front of a node comments out that node and its whole child block. It is a quick way to switch a block off while you test.
server {
listen ":443"
tls {
cert "/etc/miraserve/certs/example.com.crt"
key "/etc/miraserve/certs/example.com.key"
}
/-timeouts {
header-read "30s"
}
}
site "example.com" {
root "/var/www/example"
}
Durations and sizes
Durations and byte sizes are strings with a unit. A number without a unit is an error for durations.
| Kind | Units | Examples |
|---|---|---|
| Duration | ms, s, m, h, d; parts can be combined | "500ms", "30s", "1m30s", "1h" |
| Byte size | B, KB, MB, GB, TB (powers of 1000) and KiB, MiB, GiB, TiB (powers of 1024), any letter case; no unit means bytes | "16KiB", "10MB", "1GiB" |
How the parser treats mistakes
The parser fails closed. If anything in the file is wrong, the whole file is rejected and nothing from it is used: miraserve run refuses to start, and a reload keeps the previous config. In particular:
- An unknown directive or property is an error, not something to ignore. A typo such as
secruity-headersstops the check. - A directive that may appear once, such as
rootin a site ortlsinserver, is an error if it appears twice. - Values are checked against a fixed list. For example
seccompaccepts only"strict","standard"and"off". - Files larger than 10 MiB, and blocks or comments nested more than 32 levels deep, are refused before parsing.
When the KDL syntax itself is broken (error E001), the parser cannot read the file at all. check then also reports follow-on errors such as E006 'server' block must define at least one 'listen' directive. Fix the first E001 and run the check again; the follow-on errors usually disappear.
Checking a config
Run miraserve check before every start and every reload:
$ miraserve check /etc/miraserve/conf/miraserve.kdl
OK: '/etc/miraserve/conf/miraserve.kdl' is valid (2 listener(s), 1 site(s), 0 route(s), TLS >= 1.3, PQC: X25519MLKEM768 enabled, 0 warning(s))
Errors (codes starting with E) make the file invalid. Warnings (codes starting with W) mean the file is valid but weakens a default or is likely to misbehave. Each message points at the line and suggests a fix.
| Option | Effect |
|---|---|
--strict | Any warning fails the check (exit code 1). Use this in CI and before production reloads. |
--fs | Also checks, as the user running the check, that configured files and directories exist and are usable: certificates and keys (and that they match), CA bundles, site roots, error page files, key files, WASM modules, the key daemon socket, and the writable ACME and publishing directories. See Sandboxing. |
--acme-dir | With --fs: the ACME state directory to test, matching what you pass to miraserve run. |
--dev-tls | Says you will start the server with --dev-tls, which hides warning W015 (no certificate source configured). |
--format json | Prints a machine-readable report instead of text. |
--dump-normalized | Prints the full config with every default filled in. |
-q, --quiet | Hides the success line; errors and warnings are still shown. |
- as the file name | Reads the config from standard input. |
The exit code is 0 when the file is valid (and, with --strict, has no warnings), and 1 otherwise. On a package install, run the check as the service user so --fs tests the same permissions the server will have:
$ sudo -u miraserve miraserve check --fs --strict /etc/miraserve/conf/miraserve.kdl
Error codes
| Code | Meaning |
|---|---|
E001 | KDL syntax error, unterminated string or comment, file too large, or nesting too deep. |
E002 | Unknown directive in this block. |
E003 | Unknown or unexpected property. |
E004 | Wrong number or type of arguments, or a missing or unexpected child block. |
E005 | Duplicate directive, block or property. |
E006 | A required directive or block is missing (for example no server, no listen, or a site with nothing to serve). |
E007 | Invalid duration, size or number, or a value outside its allowed range. |
E101, E102, E103 | Invalid listen address; two listeners that overlap; invalid protocols list or HTTP/3 on a plain-HTTP redirect listener. |
E104 | Unsupported TLS version (only "1.3" and "1.2" exist). |
E105 | Certificate without key (or the reverse), or a key-isolation and keyd-socket mismatch. |
E106 | ACME problem: invalid email or directory, dns-01, or ACME combined with split-daemon key isolation. |
E107 | Invalid or duplicate site host name, or an Encrypted Client Hello setting (not supported yet). |
E108 | Invalid telemetry setting. |
E201 | Sandbox user or group is root or not a valid name. |
E202 | Unsafe path: empty, contains .., a directory path that is not absolute, or a system or overly broad directory such as /etc, /var or /tmp. |
E203 | Value not in the allowed list (preset, policy, mode, status code). |
E204 | Invalid rate limit. |
E301 | Invalid or duplicate route pattern. check --fs also uses this code for missing or unreadable files. |
E302 | A route has no handler or more than one. |
E303 | A file-serving or FastCGI route has no root on the route or the site. |
E304 | Invalid fastcgi-pass target or timeout. |
E305 | Invalid reverse proxy setting (upstream, weight, load balancing, health check). |
E401, E402 | Invalid ai-publish setting or preflight check. See Publishing. |
E403 | Invalid mcp-gateway setting. See MCP gateway. |
E404 | Invalid bot-auth setting. |
E501 | Invalid wasm-plugin setting. See WASM plugins. |
Warning codes
| Code | Meaning |
|---|---|
W001 | Post-quantum hybrid key exchange is turned off. |
W002 | TLS 1.2 is allowed, globally or for a site. |
W003 | Landlock or seccomp is turned off. |
W004 | Security headers are turned off for a site or route. |
W005 | Plain HTTP or FastCGI over TCP to a host that is not loopback. |
W006, W007 | Weak MCP gateway setting, or a tool pattern in both allow and deny lists. |
W008 | Dotfiles such as .env and .git may be served. |
W009 | ai-publish without the no-secrets preflight check. |
W010 | Bot signature verification is turned off. |
W011 | Every listener redirects to HTTPS, so nothing serves HTTPS. |
W012 | The metrics listener is not on a loopback address. |
W013 | Secret redaction in logs is turned off. |
W014 | A route can never match because an earlier, broader route catches its requests. |
W015 | No certificate, ACME block or key daemon is configured, or the file has no sites. |
W016 | min-body-rate-bps 0 turns off the minimum upload rate. |
W017 | The sandbox will refuse a configured directory because it is a system directory (reported by check). |
W018 | ai-publish on a site with several or wildcard hosts but no site-id. |
W019 | A sign-in URL uses plain http://, or mTLS publishing has no allowed-subjects. |
Pitfalls
- Mixed boolean styles. Copying a block from an old example that uses
trueinto a file that uses#truebreaks the whole file withE001. Convert the pasted block. - Bare words. KDL version 2 accepts some unquoted strings, such as
site example.com. Quote every string anyway; it avoids surprises with characters such as*and:. - Durations without a unit.
header-read "10"fails withE007 unknown unit. Write"10s". - Relative paths. Directory paths such as
rootand publishingstoragemust be absolute (E202otherwise). Relative file paths, for example for certificates, are resolved against the directory the server is started from, not the directory of the config file. Use absolute paths everywhere. - Warnings are not noise. Each warning marks a weakened default. Run
check --strictin CI so a new warning blocks the change until someone decides it is intended.