Configuration Reference

Quick start

aloha is configured via a single KDL file, read from aloha.kdl in the current working directory by default. Pass -c /path/to/file.kdl to use a different path.

A production web server serving static files over HTTPS needs three things: a plain HTTP listener on port 80 to answer ACME challenges, a TLS listener on port 443 that obtains its certificate automatically, and a vhost that maps your domain to a directory on disk.

// /etc/aloha.kdl

server {
    // Directory for ACME account keys, certificates, and JWT keys.
    // Must exist and be writable by the aloha user.
    state-dir "/var/lib/aloha"

    // Drop privileges after binding ports 80 and 443.
    user aloha
}

// Port 80: required so Let's Encrypt can reach the HTTP-01 challenge
// endpoint at /.well-known/acme-challenge/.  aloha intercepts those
// requests automatically -- no special location rule needed.
listener {
    bind "tcp://[::]:80"
}

// Port 443: aloha fetches and renews the certificate automatically.
// The domain must resolve to this server before the first startup.
listener {
    bind     "tcp://[::]:443"
    tls-acme {
        domain example.com www.example.com
        email  [email protected]   // for expiry notices from Let's Encrypt
    }
}

vhost example.com {
    alias www.example.com
    location "/" {
        static { root "/var/www/example.com" }
    }
}

On first startup aloha binds both ports (as root if needed), drops to the aloha user, then completes the ACME order before accepting HTTPS connections. Renewal happens automatically in the background before the certificate expires.

To redirect plain HTTP traffic to HTTPS rather than serving it directly, replace the port 80 vhost content with a redirect:

vhost example.com {
    alias www.example.com

    // Redirect HTTP to HTTPS.  ACME challenges on port 80 are
    // handled before routing and are never caught by this redirect.
    location "/" {
        redirect { to "https://{host}{path_and_query}"; code 301 }
    }
}

// Serve static files only on the TLS listener (443).
// You can use the same vhost name on multiple listeners.

KDL v2 primer

aloha uses KDL version 2. KDL nodes have the form:

node-name arg1 arg2 key=value {
    child-node "value"
}

Arguments are positional values placed after the node name. Properties are named key=value pairs. Children live inside { }, one per line (or separated by ;).

Strings

KDL v2 has three string forms:

Keyword literals

KDL v2 uses a # prefix for built-in literals, distinguishing them from bare-identifier strings:

Numbers

Integers and floats are written without quotes. Underscores may be used as digit separators: 1_000_000. Hexadecimal (0xff), octal (0o77), and binary (0b1010) are supported for integers.

Comments

• // — line comment to end of line.
• /* … */ — block comment, may span lines.
• /- — slashdash; comments out the next argument, property, or entire node (including its children).

Multiple nodes per line

A semicolon terminates a node, allowing siblings on one line:

server { user aloha; group aloha }
allow { authenticated } deny code=401

server

Global settings that apply to the entire process. The server block is optional; omit it to accept all defaults.

server {
    state-dir "/var/lib/aloha"
    user      aloha
    tls {
        min-version "1.2"
    }
}

access-log — Access log format and sink

One access-log block at server scope selects the format and destination for per-request access records. Without the block, lines pass through the global tracing subscriber exactly as before.

Example: JSON to a file rotated externally by logrotate:

server {
    access-log {
        format "json"
        path   "/var/log/aloha/access.log"
    }
}

auth — Authentication back-ends

aloha supports several authentication back-ends: HTTP Basic credentials validated against PAM or LDAP, an external HTTP endpoint (subrequest), and ES256 JWT session cookies. Configure one back-end in the server block; it applies to every location that challenges users.

Once a back-end is configured, add a basic-auth block inside a location to issue a WWW-Authenticate: Basic challenge, and a policy block to enforce who is allowed (see Policy blocks).

JWT

Issues and validates ES256 (ECDSA P-256) JWT session cookies so that browsers need to send credentials only once per session. After a successful login, aloha sets a Set-Cookie header; subsequent requests carry the cookie instead of re-sending credentials. Externally-issued JWTs (e.g. from an OAuth provider) can also be validated without aloha issuing tokens (standalone mode).

A P-256 private key is generated on first startup and stored at {state-dir}/jwt/ec-key.pem (mode 0600). The corresponding public key is automatically served at /.well-known/jwks.json on every virtual host.

Session mode — wraps an existing credential back-end:

server {
    state-dir "/var/lib/aloha"
    auth jwt {
        wrap pam service=login   // or ldap, subrequest
        cookie-name aloha_session  // optional
        validity    300              // seconds; optional
    }
}

Standalone mode — validates incoming JWTs only, never issues:

server {
    state-dir "/var/lib/aloha"
    auth jwt {
        cookie-name aloha_session
    }
}

In both modes, a JWT is accepted from either the named cookie or an Authorization: Bearer <token> header. Tokens are checked for a valid ES256 signature, the correct kid field, and a non-expired exp claim. The payload carries sub (username) and groups (array of group names). Cookies are issued with HttpOnly; SameSite=Strict; Path=/; Max-Age=N; the Secure flag is added automatically on TLS listeners.

LDAP

server {
    auth ldap {
        url      "ldap://localhost:389"
        bind-dn  "uid={user},ou=people,dc=example,dc=com"
        base-dn  "ou=groups,dc=example,dc=com"

        // Optional:
        group-filter "(memberUid={user})"
        group-attr   "cn"
        starttls     #false
        timeout      5
    }
}

Authentication is performed as an LDAP simple bind. The {user} placeholder in bind-dn (and in group-filter) is replaced with the RFC 4514-escaped username at request time. After a successful bind, a subtree search under base-dn finds the user’s group memberships.

Unix socket connections are supported via the ldapi:// scheme:

auth ldap {
    url     "ldapi:///var/run/slapd/ldapi"
    bind-dn "uid={user},ou=people,dc=example,dc=com"
    base-dn "ou=groups,dc=example,dc=com"
}

OIDC

server {
    state-dir "/var/lib/aloha"
    auth jwt {
        validity 3600
        wrap oidc {
            issuer             "https://accounts.example.com"
            client-id          "aloha"
            client-secret-file "/etc/aloha/oidc-secret"
            redirect-uri       "https://app.example/.aloha/oidc/callback"

            // Optional:
            scope          "openid" "profile" "email"
            groups-claim   "groups"
            username-claim "sub"
        }
    }
}

Browser-driven single sign-on against any standards-compliant OIDC identity provider (Google, Keycloak, Authelia, Okta, Entra, …). Uses the authorization-code flow with PKCE. OIDC must be wrapped inside auth jwt so the post-login identity can be persisted as an aloha session cookie; subsequent requests carry authentication via that cookie and never round-trip to the IdP.

Two server-wide endpoints are reserved automatically (paths configurable):

• GET /.aloha/oidc/login — generates the PKCE challenge and CSRF state, then 302-redirects to the IdP’s authorisation endpoint.
• GET /.aloha/oidc/callback — validates the state cookie, exchanges the code for an ID token, issues the JWT session cookie, and 302-redirects to the originally requested URL.

When OIDC is configured, anonymous browser clients that hit a protected location are automatically redirected to the login endpoint instead of receiving the basic-auth challenge. API clients (no Accept: text/html or carrying an Authorization header) keep the 401 response.

When refresh is enabled, the callback response sets a second cookie alongside the session JWT: an opaque session id that maps to an in-memory entry holding the IdP refresh token. On any request where the session JWT has expired but the refresh cookie is still present, aloha calls the IdP’s token endpoint, issues a fresh JWT, and serves the request without bouncing the browser through the login redirect. Refresh state is in-memory only; a server restart forces users to re-log in.

GET <logout-path> tears the session down: aloha drops the server-side refresh entry, emits past-dated Set-Cookie headers that clear the JWT, refresh, and login-state cookies, then issues a 302. With idp-logout enabled and an end_session_endpoint in the IdP’s discovery document, the redirect carries id_token_hint, post_logout_redirect_uri, and client_id through the IdP so its session is terminated too; otherwise the browser goes straight to post-logout-uri. Hitting the logout endpoint without an active session is a safe no-op redirect.

Back-channel logout. With backchannel-logout enabled (the default), aloha also exposes a POST-only endpoint that accepts signed logout_token JWTs pushed by the IdP. Each token is validated (signature against the cached JWKS, iss/aud, iat within backchannel-max-iat-skew, the back-channel-logout events claim, presence of sub or sid, absence of nonce, and jti uniqueness within backchannel-jti-ttl). On success aloha removes every refresh entry whose stored sid matches (or every entry for the user when only sub was sent). This only tears down server-side state — the user’s in-flight JWT session cookie remains valid until its own expiry, so operators who need fast revocation should keep validity short.

Login-flow query passthrough. The login endpoint forwards the standard OIDC hints login_hint, prompt, max_age, acr_values, and ui_locales to the IdP’s authorisation URL when they appear on the inbound query string (alongside return). Values are length-capped at 256 bytes and restricted to printable ASCII. Useful for SPAs that need prompt=none silent re-auth, password- manager deep links via login_hint, MFA enforcement via acr_values, and localised login pages via ui_locales. See OIDC Core 1.0 §3.1.2.1 for the canonical definitions.

Bearer-token resource-server mode. With bearer enabled, aloha accepts Authorization: Bearer <jwt> from API callers in addition to the browser session cookie. Tokens are validated against the IdP’s cached JWKS (signature, iss, exp, nbf) and rejected unless the aud claim contains at least one configured bearer-audience. Successful validations are cached by SHA-256(token) under the configured bearer-cache-size, so repeated requests with the same token skip the crypto until the token’s own exp. The resolved Identity uses the same username-claim / groups-claim configuration as the SSO flow, so access policies see one consistent Identity shape regardless of which auth path produced it. Supports JWT-format tokens only; opaque (introspection-required) tokens are not yet handled.

OAuth standards-track polish. Three small defensive measures sit alongside the main flow: revoke-on-logout (RFC 7009) tells the IdP to invalidate the refresh token at logout in addition to the existing end-session redirect; require-iss + the (always-on) iss match on the callback (RFC 9207) protects against mix-up attacks where a malicious site tricks a logged-in user into completing an authorization flow against the wrong IdP; resource (RFC 8707) lets the relying party narrow the access token’s aud to one or more specific protected resources, which pairs naturally with bearer-token resource-server mode above.

PAM

server {
    auth pam {
        service login   // PAM service name; defaults to login
    }
}

Credentials are validated by calling into libpam using the named service (/etc/pam.d/<service>). After a successful authentication, the user’s Unix group memberships are resolved via getgrouplist(3) and become available for group conditions in policy blocks. PAM is dispatched on a dedicated blocking thread so the async runtime is not stalled.

File (htpasswd)

server {
    auth file {
        path  "/etc/aloha/htpasswd"
        cache 60   // seconds between mtime checks
    }
}

Validates HTTP Basic credentials against an htpasswd-style file. Each line is user:hash[:group1,group2,...]; blank lines and lines beginning with # are ignored. Supported hash schemes are bcrypt ($2y$, $2b$, $2a$), SHA-512 crypt ($6$), and Argon2id ($argon2id$). Weaker schemes (DES, MD5-crypt, plain) are dropped at parse time so a misconfigured file never silently authenticates against a weak hash.

Generate entries with the standard tools: htpasswd -B -C 10 for bcrypt, mkpasswd -m sha-512 for SHA-512 crypt, or argon2 from the libargon2 package. Group memberships in the optional third column become available for group conditions in policy blocks.

The parsed table is cached in memory; aloha re-stats the file once cache seconds have elapsed and reparses only if the mtime has changed. This makes operator edits visible within ~cache seconds without paying the parse cost on every request.

Subrequest

Delegates authentication to an external HTTP endpoint — the same pattern as nginx’s auth_request module. For every request that needs authentication, aloha makes an outgoing HTTP GET to the configured URL, forwarding selected request headers. An HTTP 200 response means authenticated; any other status or a network error means anonymous.

server {
    auth subrequest {
        url            "http://auth.internal:8080/validate"
        forward-header Authorization   // repeatable
        forward-header Cookie
        user-header    X-Auth-User     // identity from response
        groups-header  X-Auth-Groups
        timeout        5
    }
}

When the auth endpoint returns 200, aloha reads identity from the response headers named by user-header and groups-header. If neither header is configured, a 200 still counts as authenticated (suitable for pure allow/deny decisions).

The typical deployment pairs the subrequest back-end on the protected server with an auth-request handler on the auth server. See that section for the complete two-server example.

error-page

Override the default minimal response body for any HTTP error status code. Define error pages in the server block; they apply to all error responses generated by access policy denials.

server {
    error-page 403 path="/var/www/errors/403.html"
    error-page 401 html="<h1>Authentication Required</h1>"
    error-page 404 path="/var/www/errors/404.html"
}

The Content-Type is always text/html; charset=utf-8. The error page replaces only the body; the status code and headers (e.g. WWW-Authenticate for 401 responses) are set normally. If the file is missing or unreadable, aloha falls back to the default minimal body.

geoip

Restricts access by the client’s country of origin using a MaxMind MMDB database. Configure the path once in the server block; then use country predicates in any policy block.

server {
    geoip {
        db "/etc/aloha/GeoLite2-Country.mmdb"
    }
}

The database is loaded into memory at startup; the file must be readable by the aloha process after privilege drop. Country codes are ISO 3166-1 alpha-2 (two uppercase letters). Private and reserved IP ranges (127.0.0.0/8, 10.0.0.0/8, etc.) are not in the database and will not match a country predicate. Combine with address to allow private ranges explicitly.

// Allow only US, Canada, and UK; plus the internal network
policy {
    allow address "10.0.0.0/8"
    allow country US CA GB
    deny  code=403
}

user and group

When aloha is started as root (necessary to bind ports 80 and 443), set user to drop privileges immediately after all sockets are bound and before any connections are accepted. The syscall sequence is setgroups → setgid → setuid.

In container deployments that use podman run --group-add keep-groups, set inherit-supplementary-groups #true to preserve the supplementary groups passed by podman rather than replacing them with a setgroups() call.

server { user www-data }
server { user aloha; group aloha }
// container: preserve groups from --group-add keep-groups
server { user aloha; inherit-supplementary-groups #true }

health

aloha responds to GET and HEAD requests on /healthz, /livez, and /readyz with a 200 OK JSON body {"status":"ok","check":"healthz"} (and so on). These endpoints are intercepted before vhost routing, so they work without a Host header and cannot be shadowed by user-defined locations. They are enabled by default; set health #false to disable them.

server {
    health #false             // disable all health endpoints
}

// Block form (equivalent):
server {
    health { enabled #false }
}

tls — Global TLS defaults

These settings can appear in a tls block inside server (global defaults) or inside a listener (per-listener override). Per-listener values take precedence.

server {
    tls {
        min-version "1.2"
        cipher TLS13_AES_256_GCM_SHA384
        cipher TLS13_CHACHA20_POLY1305_SHA256
    }
}

listener

Opens a socket and begins accepting connections. At least one is required. Use separate listeners for plain HTTP and HTTPS.

// Plain HTTP
listener {
    bind "tcp://[::]:80"
}

// HTTPS with an explicit default vhost
listener {
    bind          "tcp://[::]:443"
    default-vhost example.com
    tls-file cert="/etc/aloha/cert.pem" key="/etc/aloha/key.pem"
}

// null disables the fallback -- unrecognised hosts get a 404
listener {
    bind          "tcp://[::]:80"
    default-vhost #null
}

// Unix domain socket (useful behind a front-end proxy)
listener {
    bind "unix-stream:/run/aloha.sock"
}

Unix socket connections have no IP address; they are treated as coming from 127.0.0.1 for access-control and GeoIP purposes. Access logs show [unix] as the peer.

The bind address may also be written as the listener’s positional argument: listener "tcp://[::]:80" { … }.

quic-transport — QUIC transport tuning

Per-listener overrides for the QUIC transport. Only valid on udp: listeners; absent knobs fall back to the quinn defaults.

listener {
    bind "udp://[::]:443"
    tls-acme { domain "example.com" }
    quic-transport {
        max-concurrent-bidi-streams 100
        max-idle-timeout            30   // seconds
        keep-alive-interval         15
        zero-rtt                    #false
        retry-tokens                #true
        retry-token-lifetime        15
    }
}

proxy — Stream (TCP) proxy

Adding a proxy block to a listener activates stream mode: raw TCP bytes are forwarded to the upstream. HTTP routing does not apply.

Combine with a tls-* block on the listener to terminate TLS from clients before forwarding — aloha decrypts the incoming connection and forwards the plaintext stream. Add a tls block inside the proxy block to re-encrypt the upstream connection (re-TLS).

// Plain TCP tunnel to a PostgreSQL backend
listener "tcp://[::]:5432" {
    proxy "db.internal:5432" {
        proxy-protocol v2
    }
}

// Unix domain socket upstream
listener "tcp://[::]:5432" {
    proxy "unix-stream:/run/postgresql/.s.PGSQL.5432"
}

// TLS termination: clients connect over TLS, backend gets plaintext
listener "tcp://[::]:5433" {
    tls-self-signed
    proxy "db.internal:5432" {
        proxy-protocol v2
    }
}

// Full re-TLS: terminate client TLS, re-encrypt to upstream
listener "tcp://[::]:5433" {
    tls-file cert="cert.pem" key="key.pem"
    proxy "db.internal:5432" {
        tls             // verify with bundled WebPKI roots
    }
}

// Restrict a database port to an internal CIDR block
listener "tcp://[::]:5432" {
    proxy "db.internal:5432"
    policy {
        allow address "10.0.0.0/8"
        deny  code=403
    }
}

Arguments

Children

A policy block placed at the listener level (sibling to proxy) may only use address and country predicates. Identity predicates are rejected at startup. Denied connections are closed silently; redirect rules are treated as deny.

A config consisting entirely of stream listeners is valid with no vhost defined at all.

timeouts

Optional connection and request timeout settings. All values are in whole seconds. request-header defaults to 30 s even when the timeouts block is absent; set it to 0 to disable. All other values default to unlimited.

listener {
    bind "tcp://[::]:8080"
    timeouts {
        request-header 30
        handler        60
        keepalive      75
    }
}

tls-* — Certificate mode

Add one of three sibling blocks to a listener to enable TLS. Each accepts its settings either inline (one-line form) or as children in a block.

// Self-signed -- ephemeral, generated at startup (development only)
tls-self-signed

// PEM files from disk
tls-file cert="/etc/aloha/cert.pem" key="/etc/aloha/key.pem"

// ACME / Let's Encrypt
tls-acme {
    domain example.com www.example.com
    email  [email protected]
}

tls-acme — ACME / Let’s Encrypt

With tls-acme, aloha obtains and automatically renews a certificate via the ACME HTTP-01 challenge. A plain HTTP listener must be running to answer challenge requests. Requires state-dir in the server block.

listener {
    bind "tcp://[::]:443"
    tls-acme {
        domain example.com www.example.com
        email  [email protected]
    }
}

// Wildcard cert via Cloudflare DNS-01:
tls-acme {
    domain *.example.com
    email  "[email protected]"
    challenge "dns-01"
    dns-provider "cloudflare" {
        zone-id   "abc123..."
        api-token "cf-token..."
    }
}

// Or with an operator-supplied shell hook:
tls-acme {
    domain vpn.example.com
    challenge "dns-01"
    dns-provider "exec" {
        program "/usr/local/libexec/aloha-dns.sh"
    }
}

// TLS-ALPN-01: needs no extra port.
tls-acme {
    domain internal.example.com
    challenge "tls-alpn-01"
}

mtls — Mutual TLS (client‑cert auth)

Inside any tls-file, tls-self-signed, or tls-acme block, an mtls { } child installs a rustls WebPkiClientVerifier so the listener requires (or accepts) a client certificate chained to one of the listed CAs. A verified leaf certificate becomes an authenticated Principal: its Common Name is exposed as the request username, and the full subject DN and SAN list are available as the {client_cert_subject} and {client_cert_sans} template variables for request-headers / response-headers rules.

listener {
    bind "tcp://[::]:443"
    tls-file cert="/etc/...crt" key="/etc/...key" {
        mtls {
            ca "/etc/aloha/clients-ca.pem"
            mode "required"
            revocation "/etc/aloha/crl.pem"
            refresh 300
        }
    }
}

ocsp — OCSP stapling

Inside any tls-file or tls-acme block, aloha runs a background OCSP‑stapling task by default: on startup it reads the certificate's Authority Information Access (AIA) extension to find the issuer's OCSP responder URL, POSTs a request, and attaches the resulting response to every TLS handshake via the certificate_status_request extension. The staple is refreshed in the background before the responder’s nextUpdate field expires and is persisted to disk under state-dir/ocsp/ so restarts don’t replay a fresh fetch.

listener {
    bind "tcp://[::]:443"
    tls-file cert="/etc/...crt" key="/etc/...key" {
        ocsp #false            // disable for this listener
        ocsp-timeout 10          // fetch timeout (s)
        ocsp-min-refresh 3600   // floor for refresh cadence (s)
        ocsp-failure-backoff 300 // retry delay after a failure (s)
    }
}

certificate

Defines a named certificate at the top level of the config so that any number of listeners can share it via tls cert="name". For ACME sources this collapses what would otherwise be N independent renewal loops — one per listener — into a single background task that hot-swaps one shared acceptor.

The body contains exactly one source child: acme, files, or self-signed. Each accepts the same properties and children as the corresponding inline form (tls-acme, tls-file, tls-self-signed).

// One ACME cert shared by two listeners
certificate "main" {
    acme {
        domain example.com www.example.com
        email  [email protected]
    }
}
listener {
    bind "tcp://[::]:443"
    tls cert="main"
}
listener {
    bind "tcp://[::]:8443"
    tls cert="main"
}

// File-based shared cert
certificate "internal" {
    files cert="/etc/aloha/internal.crt" key="/etc/aloha/internal.key"
}

vhost

Maps one or more hostnames to a set of URL routing rules. Requests are matched against the Host header (port suffix stripped). At least one vhost is required for HTTP mode; stream-proxy-only configs may omit them.

Name matching

The first argument is the primary name; alias adds extra names. Both support two matching modes:

• Exact literal — the default. The full hostname must match exactly.
• Regex — add regex=#true as a property. The string is compiled as a regular expression anchored at both ends (^...$). Invalid patterns are caught at startup.

For each request, matching proceeds in this order:

1. Exact literal match across all vhosts — O(1) lookup.
2. Regex patterns — in config declaration order; first match wins.
3. Listener default-vhost fallback.

// Exact match for the bare domain plus an alias
vhost example.com {
    alias www.example.com
    location "/" {
        static { root "/var/www/example" }
    }
}

// Regex -- matches any subdomain of example.com
vhost ".+\.example\.com" regex=#true {
    location "/" {
        static { root "/var/www/wildcard" }
    }
}

location

Maps a URL path prefix to a handler. The location with the longest matching prefix wins — declaration order does not matter. Each location contains exactly one handler node.

In addition to a handler, a location may carry:

• A policy block — access control rules. See Policy blocks.
• A basic-auth block — HTTP Basic auth realm. See basic-auth.
• request-headers and/or response-headers blocks — inject or modify headers. See Header injection.
• One or more rate-limit blocks — token-bucket throttle keyed on client IP, authenticated user, or a named header. See Rate limiting.
• A max-request-body override — tighter cap for one location than the listener-wide ceiling. See Body-size override.
• An optional match block — narrow which requests this location accepts. Failing matches fall through to the next candidate location. See Request matchers.
• An optional rewrite directive — substitute the request URI via a regex and re-route from the top. See URL rewrite.

Rate limiting and body-size limits

Each location may declare one or more rate-limit blocks and an optional per-location max-request-body override. Rate-limit blocks evaluate in declaration order after authentication and access control; the first denial short-circuits with 429 Too Many Requests and a Retry-After header.

location "/login" {
    // Tight body cap for a login form on an otherwise
    // permissive listener.
    max-request-body 4096

    // Token-bucket per peer IP.  5 tokens per minute,
    // bucket holds 5 (= rate when burst is omitted).
    rate-limit {
        rate 5 per="minute"
        key  client-ip
    }
    proxy { upstream "http://login/" }
}

location "/api/" {
    // Stacked limits: a strict per-IP rate plus a softer
    // per-user rate.  Both must Allow.
    rate-limit {
        rate 100 per="second"
        burst 200
        key client-ip
    }
    rate-limit {
        rate 1000 per="minute"
        key user
    }
    proxy { upstream "http://api/" }
}

location "/keyed/" {
    // Per-API-key tier: the request header value is the
    // bucket key.  Missing headers share the empty "" bucket.
    rate-limit {
        rate 500 per="hour"
        burst 100
        key header "X-API-Key"
    }
    proxy { upstream "http://api/" }
}

Request matchers

A location may carry an optional match { } block. When present, the router only dispatches the location for requests that satisfy every predicate inside the block (AND across predicates). Within a single predicate, the listed alternatives combine with OR. When a matcher rejects a request the router falls through to the next candidate location (next-shortest matching prefix; declaration order on ties). Two locations may share the same prefix and be disambiguated by their matchers alone.

location "/api/" {
    match {
        method "POST" "PUT"
        header "X-API-Version" "~^v[23]$"
        query  "format" "json"
    }
    proxy { upstream "http://api/" }
}

// Anonymous requests to /app go to the login flow; everyone
// else proceeds to the app.
location "/app" {
    match { header-absent "Authorization" }
    redirect "/login"
}
location "/app" {
    proxy { upstream "http://app/" }
}

// Static image extensions get aggressive caching; everything
// else falls through to the default location.
location "/" {
    match { path "[.](jpg|png|gif|webp)$" }
    response-headers {
        set "Cache-Control" "public, max-age=31536000"
    }
    static { root "/var/www" }
}

// Sibling fallback at the same prefix: every other request
// to /api/ lands here.
location "/api/" {
    static { root "/var/www/api" }
}

URL rewrite

A location may carry an optional rewrite directive that substitutes the request URI before any handler runs. The from regex is matched against the URI path (not the query string); when it matches, the path is replaced by the to template — which may reference capture groups via $1, $2, or $name — and the router re-evaluates the request from the top, potentially landing on a different location. When the regex does not match, the rewrite is a no-op and the location's own handler runs on the original URI.

The replacement template may include a query string after a literal ?; whatever follows replaces the request's query. When the template omits a query, the rewritten URI has no query — the original is not carried over. A rewrite chain that fails to settle on a non-rewriting location within ten hops is treated as a misconfiguration and yields 404; a tracing::warn! records the offending URI.

location "/legacy/" {
    // /legacy/users/42 -> /api/users/42, served by the next
    // location below.
    rewrite from="^/legacy/(.*)$" to="/api/$1"
    static { root "/var/www" }   // only used when
                                  // regex doesn't match
}
location "/api/" {
    proxy { upstream "http://api/" }
}

Handler: auth-request

The server-side counterpart to the subrequest authentication back-end. A location using this handler acts as an auth endpoint: it applies its own policy block and basic-auth realm to decide whether the caller is authenticated, then returns 200 OK on success with X-Auth-User and X-Auth-Groups response headers populated from the resolved identity.

The access policy machinery issues the 401 or 403 before the handler itself is reached, so the handler has no configuration.

location "/auth/validate" {
    auth-request
    basic-auth realm="My Service"
    policy {
        allow { authenticated }
        deny
    }
}

Complete two-server example

Auth server — validates HTTP Basic credentials via PAM and returns the identity:

// auth-server.kdl
server {
    auth pam { service login }
}
listener { bind "tcp://127.0.0.1:9000" }
vhost "127.0.0.1" {
    location "/validate" {
        auth-request
        basic-auth realm=Protected
        policy { allow { authenticated }; deny }
    }
}

App server — delegates auth to the auth server and restricts a location to group members:

// app-server.kdl
server {
    auth subrequest {
        url            "http://127.0.0.1:9000/validate"
        forward-header Authorization
        user-header    X-Auth-User
        groups-header  X-Auth-Groups
    }
}
listener { bind "tcp://[::]:80" }
vhost app.example.com {
    location "/admin/" {
        basic-auth realm="Admin Area"
        policy {
            allow { group admins }
            deny
        }
        static { root "/var/www/admin" }
    }
}

basic-auth

Configures the WWW-Authenticate realm sent in 401 responses. It does not by itself restrict access; pair it with a policy block containing a deny code=401 rule (or an authenticated predicate, which issues a 401 challenge automatically for anonymous users).

location "/members/" {
    basic-auth realm="Members Area"
    policy {
        allow { authenticated }
        deny  code=401
    }
    static { root "/var/www/members" }
}

A server-level auth back-end must be configured for credentials to be validated. Without one, all requests are treated as anonymous and deny code=401 will always challenge without ever accepting credentials.

Handlers: cgi / fastcgi / scgi

These three handlers all speak CGI-adjacent protocols and share several characteristics. They all set REMOTE_ADDR to 0.0.0.0; use a request-headers block with {client_ip} to inject the real address (see Header injection). A new connection is opened per request (no connection pooling).

cgi Unix only

Executes a CGI script as a child process. One process is forked per request.

location "/cgi-bin/" {
    request-headers { set X-Real-IP "{client_ip}" }
    cgi {
        root "/usr/lib/cgi-bin"
    }
}

fastcgi

Forwards requests to a FastCGI application server such as PHP-FPM using the binary FastCGI record protocol.

location "/" {
    request-headers { set X-Real-IP "{client_ip}" }
    fastcgi {
        socket "unix-stream:/run/php/fpm.sock"
        root   "/var/www/html"
        index  index.php
    }
}

scgi

Forwards requests to an SCGI application server (Gunicorn, uWSGI, etc.) using the netstring-framed SCGI protocol.

location "/" {
    request-headers { set X-Real-IP "{client_ip}" }
    scgi {
        socket "unix-stream:/run/myapp.sock"
        root   "/var/www/html"
        index  index.py
    }
}

Handler: proxy

Reverse-proxies HTTP requests to an upstream server. Connections to the upstream are pooled and reused across requests unless proxy-protocol is set.

location "/api/" {
    proxy {
        upstream     "http://127.0.0.1:3000"
        strip-prefix #true
    }
}

// With HAProxy PROXY protocol so backend sees the real client IP
location "/api/" {
    proxy "http://127.0.0.1:3000" {
        proxy-protocol v2
    }
}

upstream may also be written as the handler’s positional argument: proxy "http://…". strip-prefix may be written as a property: proxy strip-prefix=#true.

The proxy unconditionally appends to X-Forwarded-For, sets X-Real-IP, and overrides Host with the upstream authority. Hop-by-hop headers are stripped from both the forwarded request and the backend response.

HAProxy PROXY protocol over QUIC is not supported. The wire format is an IETF draft and only HAProxy 2.9+ ships an implementation today — other major proxies (nginx, Caddy, Envoy, Traefik) don’t. For setups that need source-IP preservation on HTTP/3 traffic, terminate QUIC at HAProxy and forward decrypted HTTP/1.1 or HTTP/2 to aloha with PROXY protocol v2 over TCP.

Multi-upstream load balancing

upstream may appear multiple times to declare a pool of backends. The proxy picks one per request via the configured lb-policy and can eject failing upstreams (passively on request errors, actively via a background probe) and retry against the next.

location "/api/" {
    proxy {
        upstream "http://a:8080"
        upstream "http://b:8080" weight=2
        upstream "http://c:8080"

        lb-policy "least-conn"

        active-health {
            path          "/healthz"
            interval      10
            expect-status 200
        }
        passive-health { eject-after 3; eject-for 30 }
        retry { max 2; on-status 502 503 504 }
    }
}

// Header-hashed affinity: the request header to hash sits on the
// same node as the policy.
location "/api/" {
    proxy {
        upstream "http://a:8080"
        upstream "http://b:8080"
        lb-policy "header-hash" header="X-Session-Id"
    }
}

Retry is enabled by setting retry max=N with N>0. Because aloha must be able to replay the request body across attempts, enabling retry causes the body to be collected into memory before the first attempt. For requests with no body (GET / HEAD / empty POST) this is effectively free; for large request bodies it is a real cost and operators should leave retry max=0 (the default).

Handler: redirect

Returns an HTTP redirect response.

// Simple permanent redirect
location "/old/" {
    redirect {
        to   "/new/"
        code 301
    }
}

// Redirect all HTTP traffic to HTTPS using template variables.
// ACME challenges (/.well-known/acme-challenge/) are intercepted
// before routing and are never affected by a redirect handler.
location "/" {
    redirect {
        to   "https://{host}{path_and_query}"
        code 301
    }
}

to may also be written as the handler’s positional argument: redirect "/new/". code may be written as a property: redirect "/new/" code=301.

Header injection

The request-headers and response-headers blocks inside a location add, replace, or remove HTTP headers before the request reaches the backend and before the response reaches the client. This works for all handler types.

location "/api/" {
    request-headers {
        set    X-Client-IP       "{client_ip}"
        set    X-Auth-User       "{username}"
        set    X-Auth-Groups     "{groups}"
        set    X-Forwarded-Proto "{scheme}"
        remove Authorization
    }
    response-headers {
        set    X-Frame-Options        DENY
        set    X-Content-Type-Options nosniff
        add    Vary                   Accept-Encoding
        remove Server
    }
    proxy { upstream "http://backend:8080" }
}

Operations (applied in declaration order):

Value strings may contain {variable} placeholders expanded at request time. Unrecognised placeholders pass through unchanged. A fallback is written {variable|default}: if the variable resolves to an empty string, the default text is used instead.

set X-Auth-User   "{username|anonymous}"
set X-Auth-Groups "{groups|none}"

FastCGI, SCGI, and CGI handlers set REMOTE_ADDR = 0.0.0.0; use a request-headers rule with {client_ip} to pass the real address as HTTP_X_REAL_IP in the CGI environment. The proxy handler unconditionally appends to X-Forwarded-For and sets X-Real-IP after request-headers rules run, so a remove rule for those headers will be overwritten.

Handler: static

Serves files from a local directory. Supports Range requests, ETag conditional GET, and directory index files. Files are streamed in 64 KB chunks without buffering the entire file in memory.

location "/assets/" {
    static {
        root         "/var/www/assets"
        strip-prefix #true
        index-file   index.html
        index-file   index.htm
    }
}

// Public file share with a browsable listing.
location "/files/" {
    static {
        root "/srv/share"
        directory-listing #true
    }
}

// Per-user homepages: /~alice/foo.html serves ~alice/public_html/foo.html.
location "/" {
    static {
        userdir "public_html"
        userdir-allowlist "alice" "bob"
    }
}

root may also be written as the handler’s positional argument: static "/var/www/assets". strip-prefix may be written as a property: static "/var/www/assets" strip-prefix=#true.

Handler: status

Serves a live server status page. The HTML page auto-refreshes every 10 seconds. No children are required.

location "/status" {
    status
}

Protect with a policy block to restrict visibility. The handler responds to any HTTP method; Accept: application/json returns a JSON object with all the same data.

HTML output shows:

• Uptime and total / active request counts
• Request rate: last 5 s, 1/5/15-minute rolling averages
• Status code distribution (2xx / 3xx / 4xx / 5xx)
• Latency histogram (6 buckets from <1 ms to ≥1 s)
• Resident memory in MiB (Linux only)
• Server version and process ID
• Listener table: address, protocol, ACME domain list
• Virtual host table: names, aliases, locations with handler types

// JSON response (Accept: application/json)
{
    "version":         "0.2.0",
    "pid":             12345,
    "uptime_secs":     3661,
    "requests_total":  98765,
    "requests_active": 3,
    "status":          { "2xx": 95000, "3xx": 1200, "4xx": 500, "5xx": 65 },
    "rates":           { "current_per_sec": 12.5, "avg_1min": 10.2 },
    "auth":            "pam:login"
}

Overview

A policy block is a sequence of statements evaluated top to bottom. The first statement whose predicate matches fires its action and evaluation stops. If no statement matches, the request is denied with 403.

Statements are of the form action [predicate [values…]]. A statement with no predicate is a catch-all that always matches, so placing a bare allow or deny last acts as the default outcome.

policy {
    allow address "10.0.0.0/8"   // allow internal
    allow authenticated            // allow any logged-in user
    deny  code=403                 // catch-all deny
}

Where policy blocks appear

Statements

Every statement begins with an action keyword. All actions are terminal: when a statement fires, no further statements in the block are evaluated.

Predicates

A predicate is an optional condition that guards a statement. Without a predicate the statement is a catch-all that always fires. There are two syntactic forms:

• Inline — the predicate is written as arguments directly on the statement node. Multiple values within one predicate are OR-combined: allow country US CA GB fires when the client is in any of those three countries.
• Block — the predicate is a child block { } containing multiple predicate nodes separated by ; or newlines. All nodes inside the block must match (AND, evaluated left-to-right with short-circuit): allow { address "10.0.0.0/8"; authenticated } fires only when the client is on the internal network and is authenticated.

// Inline OR: any of these countries
allow country US CA GB

// Block AND: internal network AND authenticated
allow { address "10.0.0.0/8"; authenticated }

// not: negates a predicate (suppresses 401 challenge for auth predicates)
deny code=403 not country US CA

Named policies

Any number of reusable policy blocks can be defined in the server block by giving each a name as its first argument. Named policies are not evaluated at definition time; they are inlined wherever apply "name" appears in a concrete policy block.

// Definition (server block)
server {
    policy geo-filter {
        deny code=403 not country US CA GB
    }
    policy require-auth {
        deny code=401 not authenticated
    }
    policy admin-only {
        allow group admin
        deny  code=403
    }
}

// Usage -- the three apply statements expand to six rules:
//   deny code=403 not country US CA GB
//   deny code=401 not authenticated
//   allow group admin
//   deny code=403
location "/admin/" {
    basic-auth realm=Admin
    policy {
        apply geo-filter
        apply require-auth
        apply admin-only
    }
    static { root "/var/www/admin" }
}

Because apply splices rules in place, the effective rule list is exactly what you would get by writing all the rules out by hand. Named policies compose without any special scoping: if none of a named policy’s rules fire, evaluation falls through to the next statement after the apply.

More examples

// Block CN/RU; require auth for everyone else
policy {
    deny  code=403 country CN RU
    deny  code=401 not authenticated
    allow
}

// Allow internal IPs unconditionally; require auth for external
policy {
    allow address "10.0.0.0/8"
    allow authenticated            // issues 401 for anonymous
}

// AND: only authenticated users FROM the internal network
policy {
    allow { address "10.0.0.0/8"; authenticated }
    deny  code=403
}

// Redirect unauthenticated users to a login page instead of 401
policy {
    allow authenticated
    redirect to="/login/"
}

// Stream proxy: restrict by IP (listener level, no auth predicates)
listener "tcp://[::]:5432" {
    proxy "db.internal:5432"
    policy {
        allow address "10.0.0.0/8"
        deny  code=403
    }
}

Response compression

aloha automatically compresses responses when the client sends an Accept-Encoding header that includes zstd, br (brotli), or gzip. Preference is zstd › br › gzip when more than one is offered, which gives the best ratio at comparable CPU cost for text payloads. There is no per-location configuration; compression is always active for eligible responses.

Compression is applied to text-based content types:

• text/*
• application/json
• application/javascript, application/ecmascript
• application/xml, application/xhtml+xml
• application/wasm, application/manifest+json
• image/svg+xml

Responses smaller than 1 KB, responses that already carry a Content-Encoding header, and binary formats (images, video, audio, archives) are passed through unmodified.

When compression is applied, aloha removes Content-Length and adds:

Content-Encoding: zstd    (or br, or gzip)
Vary: Accept-Encoding

Full example

// aloha.kdl

server {
    state-dir "/var/lib/aloha"
    user      aloha

    // Validate credentials via PAM (uses /etc/pam.d/login)
    auth pam { service login }

    // Reusable policy blocks
    policy internal-only {
        deny code=403 not address "10.0.0.0/8"
    }
    policy require-auth {
        deny code=401 not authenticated
    }
    policy require-admin {
        allow group admin
        deny  code=403
    }

    // Custom error pages
    error-page 403 path="/var/www/errors/403.html"
    error-page 401 html="<h1>Authentication Required</h1>"
}

// Plain HTTP -- required for ACME HTTP-01 challenges
listener {
    bind          "tcp://[::]:80"
    default-vhost example.com
}

// HTTPS with a Let's Encrypt certificate
listener {
    bind          "tcp://[::]:443"
    default-vhost example.com
    tls-acme {
        domain example.com www.example.com
        email  [email protected]
    }
}

// Encrypted tunnel to an internal database (stream mode)
listener {
    bind     "tcp://[::]:5433"
    tls-file cert="/etc/aloha/db-cert.pem" key="/etc/aloha/db-key.pem"
    proxy "db.internal:5432" {
        proxy-protocol v2
    }
    policy {
        allow address "10.0.0.0/8"
        deny  code=403
    }
}

vhost example.com {
    alias www.example.com

    // Status page -- internal network only
    location "/status" {
        policy { apply internal-only; allow }
        status
    }

    // Admin area -- internal AND authenticated admin group
    location "/admin/" {
        basic-auth realm=Admin
        policy {
            apply internal-only   // 403 if external
            apply require-auth    // 401 if unauthenticated
            apply require-admin   // 403 if not in admin group
        }
        request-headers {
            set X-Auth-User   "{username}"
            set X-Auth-Groups "{groups}"
        }
        proxy "http://127.0.0.1:3000"
    }

    // API -- inject client info, enforce security headers
    location "/api/" {
        request-headers {
            set    X-Client-IP       "{client_ip}"
            set    X-Forwarded-Proto "{scheme}"
            remove Authorization
        }
        response-headers {
            set    X-Frame-Options        DENY
            set    X-Content-Type-Options nosniff
            remove Server
        }
        proxy {
            upstream     "http://127.0.0.1:4000"
            strip-prefix #true
        }
    }

    // PHP application via FastCGI
    location "/app/" {
        request-headers { set X-Real-IP "{client_ip}" }
        fastcgi {
            socket "unix-stream:/run/php/fpm.sock"
            root   "/var/www/html"
            index  index.php
        }
    }

    // Old URL redirect
    location "/old/" {
        redirect { to "/new/"; code 301 }
    }

    // Static files
    location "/" {
        static {
            root       "/var/www/example.com"
            index-file index.html
        }
    }
}

// Wildcard subdomain -- regex match
vhost ".+\.example\.com" regex=#true {
    location "/" {
        static { root "/var/www/wildcard" }
    }
}