Configuration / KDL basics

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" in site "example.com".
  • Properties are name=value pairs, such as redirect-https=#true or weight=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 versionTrueFalse
2 (used on this site)#true#false
1truefalse

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

  • // text comments 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.

KindUnitsExamples
Durationms, s, m, h, d; parts can be combined"500ms", "30s", "1m30s", "1h"
Byte sizeB, 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-headers stops the check.
  • A directive that may appear once, such as root in a site or tls in server, is an error if it appears twice.
  • Values are checked against a fixed list. For example seccomp accepts 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.

OptionEffect
--strictAny warning fails the check (exit code 1). Use this in CI and before production reloads.
--fsAlso 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-dirWith --fs: the ACME state directory to test, matching what you pass to miraserve run.
--dev-tlsSays you will start the server with --dev-tls, which hides warning W015 (no certificate source configured).
--format jsonPrints a machine-readable report instead of text.
--dump-normalizedPrints the full config with every default filled in.
-q, --quietHides the success line; errors and warnings are still shown.
- as the file nameReads 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

CodeMeaning
E001KDL syntax error, unterminated string or comment, file too large, or nesting too deep.
E002Unknown directive in this block.
E003Unknown or unexpected property.
E004Wrong number or type of arguments, or a missing or unexpected child block.
E005Duplicate directive, block or property.
E006A required directive or block is missing (for example no server, no listen, or a site with nothing to serve).
E007Invalid duration, size or number, or a value outside its allowed range.
E101, E102, E103Invalid listen address; two listeners that overlap; invalid protocols list or HTTP/3 on a plain-HTTP redirect listener.
E104Unsupported TLS version (only "1.3" and "1.2" exist).
E105Certificate without key (or the reverse), or a key-isolation and keyd-socket mismatch.
E106ACME problem: invalid email or directory, dns-01, or ACME combined with split-daemon key isolation.
E107Invalid or duplicate site host name, or an Encrypted Client Hello setting (not supported yet).
E108Invalid telemetry setting.
E201Sandbox user or group is root or not a valid name.
E202Unsafe path: empty, contains .., a directory path that is not absolute, or a system or overly broad directory such as /etc, /var or /tmp.
E203Value not in the allowed list (preset, policy, mode, status code).
E204Invalid rate limit.
E301Invalid or duplicate route pattern. check --fs also uses this code for missing or unreadable files.
E302A route has no handler or more than one.
E303A file-serving or FastCGI route has no root on the route or the site.
E304Invalid fastcgi-pass target or timeout.
E305Invalid reverse proxy setting (upstream, weight, load balancing, health check).
E401, E402Invalid ai-publish setting or preflight check. See Publishing.
E403Invalid mcp-gateway setting. See MCP gateway.
E404Invalid bot-auth setting.
E501Invalid wasm-plugin setting. See WASM plugins.

Warning codes

CodeMeaning
W001Post-quantum hybrid key exchange is turned off.
W002TLS 1.2 is allowed, globally or for a site.
W003Landlock or seccomp is turned off.
W004Security headers are turned off for a site or route.
W005Plain HTTP or FastCGI over TCP to a host that is not loopback.
W006, W007Weak MCP gateway setting, or a tool pattern in both allow and deny lists.
W008Dotfiles such as .env and .git may be served.
W009ai-publish without the no-secrets preflight check.
W010Bot signature verification is turned off.
W011Every listener redirects to HTTPS, so nothing serves HTTPS.
W012The metrics listener is not on a loopback address.
W013Secret redaction in logs is turned off.
W014A route can never match because an earlier, broader route catches its requests.
W015No certificate, ACME block or key daemon is configured, or the file has no sites.
W016min-body-rate-bps 0 turns off the minimum upload rate.
W017The sandbox will refuse a configured directory because it is a system directory (reported by check).
W018ai-publish on a site with several or wildcard hosts but no site-id.
W019A 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 true into a file that uses #true breaks the whole file with E001. 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 with E007 unknown unit. Write "10s".
  • Relative paths. Directory paths such as root and publishing storage must be absolute (E202 otherwise). 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 --strict in CI so a new warning blocks the change until someone decides it is intended.