api #

The job's file name under /etc/periodic/daily (e.g. 'certbot-renew').

The script body — a #!/bin/sh executable (e.g. alpine_certbot_renew_cron()).

The installed PostgreSQL major version — matches apk add postgresql<version> and the /var/lib/postgresql/<version>/data cluster path. Pin it to the major your other hosts run, for replication and restore compatibility.

Check command — exit 0 means the script is already applied (skip).

The command the planner emits when the check fails.

The URL zap fetches the GPG signing key from, on the operator's machine: https://, or http:// to a loopback host; any other scheme is rejected by the structural gate. It may carry a reference. The key is pinned by the blake3 of its bytes, and only bytes that hash to the pin are installed.

The key's vendored pin: the blake3 of its bytes, 64 lowercase hex. Absent, the pin is tracked in zap.lock (zap lock / zap update mint and advance it).

Where the GPG key is stored; default /usr/share/keyrings/{id}.asc. It takes no reference (rejected when the config is read): it is written into the source line, inside double quotes.

The deb source line (signed-by is auto-injected from key_path). It is expanded by the target shell inside double quotes, so $VERSION_CODENAME resolves there; it takes no reference (rejected when the config is read).

The .list file path; default /etc/apt/sources.list.d/{id}.list. It takes no reference (rejected when the config is read): detection reads it as declared.

Where the source comes from + how its integrity is verified.

The build command (e.g. zig build -p $HOME/.local -Doptimize=ReleaseFast).

Path that exists iff the build is installed — the detection probe.

Working directory for run: absolute, or relative to the extracted source dir, which is the default. Takes no reference: zap rejects one here.

Build environment. Keys are POSIX names ([A-Za-z_][A-Za-z0-9_]*), validated at config-eval; a name beginning with __zap_ is rejected by the structural gate (zap's own wrapper variables). A value's references resolve before it is quoted, so it can hold any text but a NUL and the reference delimiters U+FDD0 and U+FDD1.

A fetched source archive — fetched, verified, and content-addressed.

Fetch location: an https:// URL with no user:password@ (http:// only for a loopback host), or the structural gate rejects it. It may carry a reference, resolved when zap fetches (the lock addresses a secret reference by its token, any other by its value).

How the fetched source is unpacked before run.

Optional fetch credential for a private byte-host (never hashed).

Optional upstream-signature verification, run when a fetch fills the content cache, before the bytes are pinned or built. A cache hit is not re-verified: it is re-hashed against the pin.

Vendored source pin. A declared pin self-pins; absent, the lock pins it. Mirrors ContentHash — exactly 64 lowercase hex on the wire.

the command the hook runs, as shell words by design (the hook is a shell script); the caller's own literal, never a value from elsewhere

the hook's file name: letters, digits, _ and - only, so run-parts-style runners don't skip it and it can't leave the directory

the service manager's stop command, as shell words by design; the caller's own literal, never a value from elsewhere

the certificate's names, its registration email, and the addresses the names must resolve to

The IP addresses every name the certificate covers must resolve to, on the target. Before the script changes anything, the target resolves each name with getent ahosts and getent hosts — through its own resolver, so /etc/hosts first — and refuses when a name doesn't resolve, when no address can be read, or when any A/AAAA address either prints is outside this set: Let's Encrypt validates whichever address it picks, so an undeclared AAAA would fail the validation. The two lookups together see every A and AAAA but in one case: on a musl host (Alpine) with IPv6 disabled, ahosts drops the AAAA records and hosts prints only the first, so a name with several AAAA, the first of them declared, passes unseen.

The guard reads the target's resolver, not the CA's. An /etc/hosts line, a split-horizon answer, or a cached one can pass while public DNS doesn't point at the host yet, or refuse while it does. A name /etc/hosts maps to a loopback address refuses, the safe direction. That includes the 127.0.1.1 <name> line a Debian install writes for the host's own name, when that name is the domain: remove the line, or give the host a name that isn't the domain (a tool that manages /etc/hosts may write the line back).

Each value is an IP literal, or a reference resolving to one at apply time; the target checks it and refuses anything else (a host name, say), asking for this option. An IPv6 address is compared as text, lowercased, so write it as getent prints it (the compressed form). Defaults to a reference to DEPLOY_HOST, the target's host; declare the addresses when the host is reached by name or the names also carry an AAAA.

The hook's file name under CERTBOT_DEPLOY_HOOKS_DIR. Defaults to RELOAD_NGINX_HOOK_NAME ('reload-nginx').

Check command — exit 0 means the script is already applied (skip).

The command the planner emits when the check fails.

The certificate domain. Defaults to a reference to DEPLOY_DOMAIN.

Further names the certificate covers beside domain, one -d each — e.g. the www. name a site's redirect_domains 301s to domain. The cert stays named for domain. Defaults to none.

The registration email. Defaults to a reference to DEPLOY_CERTBOT_EMAIL.

The certificate domain. Defaults to a reference to DEPLOY_DOMAIN.

Further names the certificate covers beside domain (see CertbotStandaloneIssueOptions.extra_domains). When set, the check also requires each name in the live cert's subjectAltName, so adding a name to a host whose cert predates it re-issues the cert to cover it. Defaults to none.

The registration email. Defaults to a reference to DEPLOY_CERTBOT_EMAIL.

The ACME challenge webroot. Defaults to /var/www/certbot.

The deploy hook the run executes after certonly succeeds — the file a *_certbot_reload_nginx_hook returns, or any with its path — so the server loads the re-issued certificate: certbot before 5.3.0 runs deploy hooks for renew only. On a later certbot the hook runs twice, which a reload tolerates. The switch's script must depend on the hook's file.

The command to run.

A substring that must appear in stdout.

Auth method (default scram-sha-256).

Allowed client addresses, each an IP address with its prefix length (127.0.0.1/32); a keyword (all, samehost, samenet) or a host name is refused. At least one: an auth that names none is refused, since it would write no rule.

Database engine (only postgresql).

Database name to create. Taken literally (never shell-expanded); a reference resolves on the operator's machine.

Role/user to create and own the database. Taken literally (never shell-expanded); zap.env('USER') declares "the operator's OS user".

pg_hba.conf auth config. Absent, zap writes no rule, and the role is reached over the Unix socket by the OS account of the same name. A rule zap adds is put in force with pg_reload_conf(); the server isn't restarted, and the target needs no service_manager for it.

Pinned Deno version, e.g. '2.8.2' (no leading v).

Absolute path the deno executable is installed to — e.g. '/usr/local/bin/deno' (system) or '/home/svc/.deno/bin/deno' (user-home). Parent dirs are created (install -D). Passed single-quoted, so it is taken literally: no ~ or $HOME expansion. Refused at eval unless it begins /.

Install as this user via sudo -u <user>, so bin_path (under their home) lands owned by them even when the apply runs as root. The check and the closing --version run the binary as this user too, never as the connecting user: the account owns the file, and could replace it. A user name written out: not empty, not #<uid>, and not a reference. Omit for a same-user or privileged system install. Mutually exclusive with privileged.

sudo the install into a root-owned system dir (e.g. /usr/local/bin). Defaults to false. Mutually exclusive with user.

Release-asset target triple. Defaults to 'x86_64-unknown-linux-gnu' (glibc). On an Alpine/musl host pass 'x86_64-unknown-linux-musl' — a glibc Deno binary won't run under musl without gcompat (this recipe is neutral, so the distro is the caller's to declare).

Check command — exit 0 means the script is already applied (skip).

The command the planner emits when the check fails.

Host polled over HTTPS (e.g. app.example.com, or a zap.env('DEPLOY_DOMAIN') reference resolved at execution).

Request path polled over HTTPS against domain, beginning with / (e.g. /health). Takes no reference: zap rejects one here.

How many times to poll before failing the deploy, at least 1 (default 15).

Delay between poll attempts, in milliseconds (default 2000).

Build command run locally before packaging (e.g. gro build).

Files/directories (relative to the operator cwd) to package into the tarball. An entry can't begin with - (write ./-name) or with @; either is rejected by the structural gate.

Remote application root — holds releases/, shared/, and the current symlink. An absolute path, written out: no reference (rejected when the config is read) and no ~ (rejected by the structural gate).

Number of releases to retain on the target, the live one included (default 5). Below 2 is rejected by the structural gate: the release just deployed and the one it replaced, which a failed deploy rolls back to, are always kept.

Service to restart after the symlink swap. Requires target.service_manager. Takes no reference (rejected when the config is read).

Files under the remote shared/ directory to symlink into each release root. Each is a relative name of a file: no .. component, no control character, not ending in / or in a . component (anything else is rejected by the structural gate).

Post-extract commands run on the target, in the new release directory, before swap, each in a shell of its own (sh -ec): an exit in one ends that command, not the deploy, and one that fails stops the deploy before the swap. The release is still under its hidden staging name then, so a command shouldn't record its absolute path.

Optional post-restart HTTP health check.

Directory path, absolute or under ~ (may carry a reference).

Desired octal mode (e.g. "755"). Mirrors Mode — octal, 7777 at most.

Desired owner. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

Desired group. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

the variable's name: a letter or _, then letters, digits, or _

[DEFAULT] bantime — how long a banned host stays banned. Defaults to '1h'.

[DEFAULT] findtime — the window failures are counted within. Defaults to '10m'.

[DEFAULT] maxretry — failures within find_time before a ban. Defaults to 5.

[sshd] maxretry — sshd-specific failure threshold. Defaults to 3.

[sshd] bantime — sshd-specific ban duration. Defaults to '24h'.

[DEFAULT] banaction — the fail2ban action that blocks a banned address, which has to drive the firewall the host has. Defaults to 'iptables-multiport', for a ufw host (ufw depends on iptables, not on the nft command Debian's own nftables default needs). Pass 'nftables' on an nftables host such as the one alpine_web_firewall sets up, which has no iptables. Without the command the action names, fail2ban counts and lists a ban but blocks nothing.

The file fail2ban watches for sshd auth failures. Unset, the jail reads the systemd journal (backend = systemd), where sshd logs on Debian and Ubuntu with or without rsyslog. On Alpine there is no journal: BusyBox syslog writes everything to '/var/log/messages', so pass that (and ensure the syslog service is enabled); the jail then reads the file with the sshd filter set to read BusyBox's lines. fail2ban refuses to start a jail whose logpath doesn't exist ("Have not found any log file").

Target path (may carry a reference / ~).

Content source.

Desired octal mode (e.g. "600"). Mirrors Mode — octal, 7777 at most.

Desired owner. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

Desired group. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

Ids of service resources notified when this file changes.

Command that must exit 0 after a write (e.g. NGINX_VALIDATE), or the write is rolled back — the previous bytes, owner, group, and mode restored, less any set-id or sticky bit the declared mode lacks (or a new file removed) — and the change fails. Runs against the file in place, so it suits a file some larger config includes. Text content only — rejected on remote.

Firewall backend (ufw or nftables).

Default policy for incoming traffic (default deny).

Default policy for outgoing traffic (default allow).

Allow rules (named profiles or port/proto pairs).

The service user that owns config_dir and writes the token file. run runs as them (sudo -u <user>), so the connecting user's sudo rule must allow running as them, even when it is the same user. A user name written out: not empty, not #<uid>, and not a reference.

Database name probed by the bootstrap_lock fallback check (the psql_args default is -d <service>).

Absolute directory holding secret_bootstrap_token, e.g. /home/<user>/.myapp. The token path is <config_dir>/secret_bootstrap_token. Must already exist and be writable by user (declare the config-dir directory resource, owned by user, as a depends_on).

psql connection args for the bootstrap_lock fallback probe. Defaults to -d <service>: the Unix socket, as the connecting user, whom the stock peer rule admits when the user is the role (the deploy user running the service, as fuz_app_env_base's DATABASE_URL assumes). These are shell words, spliced into the check as written: quote a value in them yourself. Every other option is passed as one single-quoted word.

Check command — exit 0 means the script is already applied (skip).

The command the planner emits when the check fails.

The DB role in DATABASE_URL. The server connects over the Unix socket, where the stock peer rule admits only the OS account of the same name, so this is the account the service runs as. Letters, digits, _, ., and -, written out (no reference): it is a name in DATABASE_URL, refused at eval otherwise.

The database name in DATABASE_URL. Letters, digits, _, ., and -, written out (no reference), refused at eval otherwise.

Directory holding secret_bootstrap_token, e.g. /home/<user>/.myapp. The emitted FUZ_BOOTSTRAP_TOKEN_PATH is <config_dir>/secret_bootstrap_token.

The port the server listens on, {{port}}'s value (PORT). Held to port.

The cookie-signing keys, {{cookie_keys}}'s value (SECRET_FUZ_COOKIE_KEYS) — a reference, zap.env('SECRET_FUZ_COOKIE_KEYS'). Held to env_value: it sits inside single quotes.

The caller's own lines, appended after the base, with their variables.

The lines, quoted by the format recipe_alpine_openrc.ts documents.

The values of the placeholders the lines add.

The kinds of the variables vars adds.

The service infix in FUZ_<infix>_TRUSTED_PROXIES, e.g. 'FORGE'.

The trusted proxy address(es). Defaults to '127.0.0.1' (the loopback nginx hop).

Absolute paths bind-mounted read-write inside the otherwise read-only root — everything the service writes at runtime (its app/data directory, a database socket directory, …). The working_directory should fall under one of these. /tmp is always a private tmpfs and need not be listed.

Each entry must be an absolute path of [A-Za-z0-9_./-] only — no whitespace or shell metacharacters — validated at eval. They're embedded unquoted into the bwrap command line, so an unsafe path would word-split and silently break the sandbox.

The bwrap binary path. Defaults to /usr/bin/bwrap.

The init-script name (/etc/init.d/<name>); also the default log basename.

Human-readable description= (e.g. the domain).

Absolute path to the executable (command=).

Arguments string passed as command_args=: shell words, which OpenRC splits and whose quotes it reads (see the module doc). Omitted when unset.

The service account (command_user=<user>), by name: a numeric uid and root are refused. Also the default for group.

The service group (command_user=<user>:<group>), by name, not root. Defaults to user.

directory= — the process working directory (typically the current release symlink). Omitted when unset.

Read as data into the daemon's environment — OpenRC's stand-in for systemd EnvironmentFile=. start_pre() has the service user check it, and the daemon's process, as command_user, exports it before it execs the command, so it must be readable by the service user. It must be an absolute path outside the log directory (which is chowned to the service user), or it is refused at eval. Omitted means no environment file. The format, and where it differs from systemd's, is in the module doc.

The capabilities= value, in libcap's IAB text, which supervise-daemon applies: ^cap_x raises cap_x as an ambient capability, !cap_x drops it from the bounding set. Defaults to '^', no ambient capability (a daemon listening on a high port behind nginx needs none); pass '^cap_net_bind_service' for one that binds below 1024. Whatever it names, the recipe appends !cap_… for every other capability (CAPABILITY_NAMES by name, then every higher number up to 63, so one a newer kernel adds is dropped too; the names need a libcap that knows cap_checkpoint_restore), so the bounding set holds only the capabilities the value names without !: a '^' alone leaves it empty. libcap's IAB text has no word for "all", so each is named. Under isolation the command holds none.

umask=, which supervise-daemon sets for the daemon (--umask): four octal digits. Defaults to '0077', as the systemd unit does, so what the service creates is its own; pass '0022' (or '0027' for a group) when another account reads what it writes, such as nginx serving a store through X-Accel-Redirect.

rc_ulimit="-n <n>" open-file cap. Omitted when unset.

respawn_delay seconds between supervise-daemon restarts. Defaults to 5.

depend() need entries. Defaults to ['net'].

depend() use entries (soft deps). Defaults to none; add 'postgresql' for an app on a local database.

Combined stdout+stderr log path (output_log/error_log). Defaults to /var/log/<name>/<name>.log. supervise-daemon opens this as command_user (after the privilege drop), so for a non-root service the path's directory must be writable by that user. The recipe handles this: it creates and chowns log_file's parent directory to the service user in a start_pre() checkpath hook (which runs as root, before the privilege drop), so the default works for a non-root service out of the box with no external directory resource. Because the parent is chowned to the service user, it must be the service's own: at or under a directory that sits directly under /var/log, /var/lib, /srv, /opt or /run and is named name or user, alone or followed by one of _, -, . (/var/log/<name>/server.log, /srv/<user>/logs/server.log), and env_file must not sit inside it, nor may command or, under isolation, the bwrap binary, which the service user could otherwise replace. Any other path is refused at eval.

At start, the hook also refuses (eerror, start_pre fails) a log directory that already exists unless it is a directory, not a symlink, owned by the service user: an absent one is created, and anything else (root's, another daemon's — a name nginx meeting /var/log/nginx) is someone else's, which the hook never re-owns. A root-owned directory is refused too, since the hook didn't make it; chown it to the service user, or remove it, to adopt it. The residual: only the log directory itself is checked, and checkpath follows a symlink in the path's intermediate components, creating through it and chowning where it points; a symlink as the last component it refuses, failing the start. So below an owner-named directory the service user already owns, a symlink it plants at an intermediate component (/srv/<user>/a/logs, replacing a) could redirect the root-run create and chown, while one swapped in for the log directory itself between the check and checkpath is refused. Where that matters, make the log directory the owner-named directory itself (/var/log/<user>).

Tier-B filesystem isolation via bubblewrap. When set, the service command runs inside a bwrap sandbox — a read-only root, a private /tmp (tmpfs), and the declared read_write_paths bound read-write — the OpenRC stand-in for systemd's ProtectSystem=strict + PrivateTmp + ReadWritePaths. It layers over the Tier-A privilege hardening (the sandboxed process still drops to command_user, holds no capabilities, whatever capabilities names (bwrap empties the bounding set), and sets no_new_privs). Requires bubblewrap on the target (declare it as a zap.pkg) and a kernel permitting unprivileged user namespaces (Alpine's default). Omit for Tier-A only.

Description= — human-readable unit description (e.g. the domain).

ExecStart= — the full command line, already absolute and quoted as needed. It begins with the absolute path of the program, optionally after systemd's @ (the next word is argv[0]) or : (no $VAR expansion) prefix. Every other prefix is refused: +, ! and !! run the command outside User= or the sandbox, and - reads a failing exit as success, so Restart=on-failure never restarts it.

User= — the service account, by name. Also the default for group. Not root: the unit is for an unprivileged account.

Group= — the service group, by name, not root. Defaults to user.

WorkingDirectory= — the process working directory (typically the current release symlink).

ReadWritePaths= — the read-write holes punched through ProtectSystem=strict + ProtectHome=read-only. Space-joined into a single directive; every path must already exist or systemd namespace setup fails with status 226.

EnvironmentFile= — emitted only when set. Leave unset when exec_start injects env itself (e.g. Deno's --env=); see the module doc.

After= units. Defaults to ['network.target']; add 'postgresql.service' for an app on a local database.

Wants= units, the line emitted only when non-empty. Defaults to none.

Restart= policy. Defaults to 'on-failure'.

RestartSec= seconds. Defaults to 5.

RestrictAddressFamilies= — space-joined. Defaults to ['AF_UNIX', 'AF_INET', 'AF_INET6'], which covers a TCP listener, the Postgres socket, and loopback callbacks.

WantedBy= install target. Defaults to 'multi-user.target'.

The capabilities the service holds, as systemd names them (CAP_NET_BIND_SERVICE), written both as the CapabilityBoundingSet= and as AmbientCapabilities=. Defaults to none: an empty CapabilityBoundingSet= and no AmbientCapabilities= line.

SystemCallFilter= — the syscall sets or names the service may call (an allow-list), written with SystemCallErrorNumber=EPERM. Defaults to ['@system-service']; widen it for a workload that needs a set outside it, such as @privileged, @mount, @debug or @pkey (`systemd-analyze syscall-filter

UMask= — four octal digits. Defaults to '0077'; pass '0022' (or '0027' for a group) when another account reads what the service writes.

Host-specific sandboxing-rationale comment, inserted verbatim after PrivateTmp=true and before PrivateDevices=true. Pass the full comment lines (each already prefixed with # , newline-separated, no trailing newline); omitted means no comment. A line that doesn't begin with # would be a directive, and one ending in \ would continue onto the next directive, so both are refused. This is where a deploy documents why its address-family / syscall-filter choices are safe for its workload — genuinely per-host prose (a git-backend service explains its subprocesses; a pure-API service notes it has none), so it can't be a shared constant.

The install script's https:// URL, piped into shell; any other scheme is rejected by the structural gate.

Path checked for existence to confirm installation (may carry ~).

Command the fetched install script is piped into (default sh), run as written. The script is fetched whole first; a failed fetch, or an empty script, fails the step.

the certificate's name, its first -d domain

the certificate chain or its private key

Symlink path (may carry a reference / ~). A real directory at the path fails the step.

The target the symlink should point to (resolved the same way).

The pinned minisign public key: the 56 base64 characters beginning RW (the key line of a .pub file, without its comment). Mirrors the Rust MinisignKey; any other shape is rejected at config eval.

Explicit signature URL, held to the rule url is; it may carry a reference. Defaults to the source URL with .minisig appended to its path, before any query or fragment.

The stock-default removal, for a zap.script.

The catch-all server, for a zap.file ordered after the removal.

Whether the site serves HTTP/2: pass the site recipe's http2. The catch-all's listen 443 sockets carry the same http2 parameter as the site's, so the two servers on one address and port agree on it. Defaults to true, the site's default.

How the site wires its SSL parameters: pass the site recipe's ssl. Defaults to 'snippet', the site's default. The catch-all includes the same parameters, because as the default_server it is the server whose SSL settings nginx starts every handshake with — its protocols, ciphers and session cache apply to the site's handshakes too, and without them a distro's own defaults would (Debian's allow TLS 1.2 ciphers without forward secrecy). That file must be on disk before the catch-all is written, or its nginx -t fails: order the catch-all after the ssl_params file ('snippet') or the certificate issuance ('certbot').

Check command — exit 0 means the script is already applied (skip).

The command the planner emits when the check fails.

The on-disk path the ssl: 'snippet' include points at — the one bit of the site config the distro wrappers supply, SSL_PARAMS_PATH on both. Unused when ssl === 'certbot'.

The site's host name, {{domain}}'s value — typically a reference, zap.env('DEPLOY_DOMAIN'). Held to hostname once it resolves.

The backend's loopback port, {{port}}'s value. Held to port.

Document root for the static frontend, e.g. `` ${CURRENT_LINK}/build ``.

The Content-Security-Policy header value (interpolated, not a placeholder). One holding a ", a \, a $, or a line break is refused: inside the quoted header value the first three end it or read as an escape or an nginx variable.

How SSL is wired into the HTTPS server.

• 'snippet' (default) — include <ssl_snippet_path>; (paired with the ssl_params recipe written to that path; zap owns the full config).
• 'certbot' — include /etc/letsencrypt/options-ssl-nginx.conf; + ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; (certbot-managed params).

Serve HTTP/2 in the HTTPS server. Defaults to true.

On by default because the alternative is a worse baseline for every site: without it a browser is capped at six connections per origin and repeats every request and response header uncompressed, which dominates the wire cost of any page serving many small assets. HPACK plus multiplexing removes both, and ALPN falls back to HTTP/1.1 for clients that can't negotiate h2, so there is no client-compatibility cost.

Emitted as the listen ... http2 parameter rather than the http2 on; directive. The directive is the modern spelling, but it only exists from nginx 1.25.1; on anything older it is an unknown directive that fails nginx -t outright, and Ubuntu 24.04 LTS ships nginx 1.24. The parameter form works on both sides of 1.25.1 (deprecated above it, still honored, one warning logged at start), so it is the spelling that delivers h2 on every supported host.

One thing to know before turning it off — and the reason this is an option at all rather than unconditional:

• limit_req burst= absorbs arrival pattern, and h2 changes it. The /api burst was sized against requests trickling in six at a time; over one multiplexed connection a page's whole RPC fan-out can arrive at once. The zone rate is unaffected (limit_req counts requests, not connections), but a site with a heavy fan-out on load may need a larger api_burst than it did on HTTP/1.1.

Server-level client_max_body_size cap. Emitted as its own line (with the surrounding blank lines) only when set; omit for nginx's default.

App-specific comment line rendered directly above client_max_body_size (without the leading # , which is added here). Ignored unless client_max_body_size is set; omit for no comment.

/api limit_req burst=. Defaults to 50.

The location / try_files arguments (the SPA fallback chain). Defaults to '$uri $uri/index.html /200.html'.

error_page 404 <target>; in the HTTPS server, e.g. '/404.html'. Emitted only when set.

App-specific location blocks injected into the HTTPS server verbatim (already indented to the server-block level, no leading/trailing blank lines), placed just before the /_app static block. A block with no add_header inherits the server's security headers and CSP; one with its own inherits none, so it renders site_security_header_directives(csp) beside them, or a Content-Security-Policy of its own. A block (a location, or an if in one) that sets add_header with no Content-Security-Policy is refused.

ACME HTTP-01 challenge webroot for the redirect server. Defaults to /var/www/certbot.

Further host names that 301 to https://{{domain}} — e.g. ['www.{{domain}}'] to send www. to the apex. Each joins the HTTP server's server_name (so the ACME challenge is served for it too) and gets a lean HTTPS server that only redirects, on the site's certificate, so the cert must cover them: pass the same names to the certbot recipes' extra_domains. Defaults to none.

A literal name may use the {{domain}} placeholder, substituted with the rest of the template. A name that carries a reference (zap.env('MIRROR_DOMAIN'), whole or interpolated) becomes its own variable, redirect_domain_<i> for the entry at index i, held to hostname once it resolves; it takes no placeholder, since a variable's value is never read for one.

Package-manager → package-name mapping (e.g. {apt: "curl"}). A name takes no reference (rejected when the config is read): it is put into the manager's command unquoted, and detection asks the manager about it (under apt by the name alone, for name=version at exactly that version, and for name:arch by that architecture). So a name is one word in the manager's syntax — a letter or digit, then letters, digits, and `+ . _ - = ~ : /

Optional custom check (a path, or a command); defaults to the PM query. A check beginning /, ~, or $HOME is a path and its references resolve; anything else is a command, run as written.

The absolute path to check, as written: no reference; a ~ or relative path is rejected. A link is followed: type, mode and owner are its target's.

Required type; absent accepts either.

Required octal mode (e.g. "600"). Mirrors Mode — octal, 7777 at most. 0644 and 644 compare the same.

Required owner. Mirrors AccountName — a portable Unix user/group name ([a-z_][a-z0-9_-]*, optional trailing $; a numeric uid/gid or any other character is rejected at parse).

Whether the path's size must be above zero (test -s). A directory's size depends on its filesystem, so this doesn't reliably check that a directory has entries.

Environment variables shared across all steps. Rejected by the structural gate — the sequential executor doesn't apply it; inline the vars into each step's run.

The pipeline steps.

Max steps to run concurrently, at least 1. Any value above 1 is rejected by the structural gate: steps run sequentially.

Identifier for this step, unique within the pipeline: a repeated id is rejected by the structural gate.

Human-readable name for the step, printed under its id in a plan.

The command this step runs.

Working directory for this step. Rejected by the structural gate — the sequential executor doesn't apply it; inline a cd into run.

Environment variables for this step. Rejected by the structural gate — the sequential executor doesn't apply it; inline the vars into run.

Step ids this depends on (within the pipeline). Rejected by the structural gate: steps run sequentially in declaration order.

The URL zap fetches the GPG signing key from, on the operator's machine: https://, or http:// to a loopback host; any other scheme is rejected by the structural gate. It may carry a reference. The key is pinned by the blake3 of its bytes, and only bytes that hash to the pin are installed.

The key's vendored pin: the blake3 of its bytes, 64 lowercase hex. Absent, the pin is tracked in zap.lock (zap lock / zap update mint and advance it).

The deb source line (signed-by is auto-injected from key_path). It is expanded by the target shell inside double quotes, so $VERSION_CODENAME resolves there; it takes no reference (rejected when the config is read).

Where the GPG key is stored; default /usr/share/keyrings/{id}.asc. It takes no reference (rejected when the config is read): it is written into the source line, inside double quotes.

The .list file path; default /etc/apt/sources.list.d/{id}.list. It takes no reference (rejected when the config is read): detection reads it as declared.

Where the GPG signing key is stored. Defaults to /usr/share/keyrings/postgresql-pgdg.asc.

The .list file path. Defaults to /etc/apt/sources.list.d/pgdg.list.

Shared-memory zone size. Defaults to '10m'.

rate= cap. Defaults to '10r/s'.

Authorization: Bearer <token>.

The bearer token; typically a reference, never a literal.

Fetch location: an https:// URL with no user:password@ (http:// only for a loopback host), or the structural gate rejects it. It may carry a reference, resolved when zap fetches (the lock addresses a secret reference by its token, any other by its value).

Vendored content pin. A declared pin self-pins (skips the lock); absent, the lock pins the resolved hash. Mirrors ContentHash — exactly 64 lowercase hex on the wire.

How the fetched bytes are materialized on the target.

Optional fetch credential for a private byte-host (never hashed).

Fetch location: an https:// URL with no user:password@ (http:// only for a loopback host), or the structural gate rejects it. It may carry a reference, resolved when zap fetches (the lock addresses a secret reference by its token, any other by its value).

How the fetched source is unpacked before run.

Optional fetch credential for a private byte-host (never hashed).

Optional upstream-signature verification, run when a fetch fills the content cache, before the bytes are pinned or built. A cache hit is not re-verified: it is re-hashed against the pin.

Vendored source pin. A declared pin self-pins; absent, the lock pins it. Mirrors ContentHash — exactly 64 lowercase hex on the wire.

Stable identity within the config. Mirrors ResourceId (a plain string on the wire). A name: a letter, a digit, or _, then any of those and . + : @ -; anything else is rejected by the structural gate.

A label for whoever reads the config. A plan prints it under the change's header; everything else (apply's progress, events, triggers) names a resource by its id. It is carried in a change, so changing it changes the plan_hash of a plan that changes this resource, but never the lock entry's config_hash.

Resource ids this depends on (the resource-graph edges).

Check command — exit 0 means the script is already applied (skip).

The command the planner emits when the check fails.

Working directory for the check and for run. An absolute path, taken verbatim: no reference (rejected when the config is read) and no ~ (rejected by the structural gate). A check that can't enter it reads as not applied; a run that can't enter it fails without running.

Extra environment, exported to the check and to run (every command of a compound sees it). Keys are POSIX names ([A-Za-z_][A-Za-z0-9_]*), validated at config-eval; a name beginning with __zap_ is rejected by the structural gate (zap's own wrapper variables). A value's references resolve before it is quoted, so it can hold any text but a NUL and the reference delimiters U+FDD0 and U+FDD1 (a value with a ' goes here, not in the command text).

Service name (interpreted by the target's service manager). Takes no reference (rejected when the config is read): it is put into the manager's command unquoted, and detection reads it as declared. So a name is one word — a letter or digit, then letters, digits, and _ . @ : - — and anything else is rejected when the config is read.

Whether the service should be enabled at boot (default true).

Whether the service should be running now; absent = don't manage runtime.

Resource ids whose change triggers a restart of this service, if it is running (try-restart on systemd, rc-service --ifstarted on OpenRC). A trigger on a service with running: false is a config error.

Resource ids whose change triggers a reload of this service, if it is running: try-reload-or-restart on systemd, rc-service --ifstarted <svc> reload on OpenRC (a service that can't reload fails the step).

the text, literal or holding references

the site's Content-Security-Policy value, the csp the site recipe is given

minisign -V against public_key.

The pinned minisign public key: the 56 base64 characters beginning RW (the key line of a .pub file, without its comment). Mirrors the Rust MinisignKey; any other shape is rejected at config eval.

Explicit signature URL, held to the rule url is; it may carry a reference. Defaults to the source URL with .minisig appended to its path, before any query or fragment.

The connect-src WebSocket endpoint, appended after 'self'. Defaults to the zap template placeholder wss://{{domain}} (substituted at apply time).

Extra connect-src sources appended after 'self' and websocket.

Extra img-src sources appended after the 'self' data: baseline (e.g. ['blob:']).

worker-src sources beyond the implicit 'self'. Emits a worker-src directive (placed after connect-src) only when set (e.g. ['blob:']).

the options given ssh_hardening

the service manager's name for sshd

the ids that reload sshd (reload_on)

AllowUsers — the sole account permitted to SSH in (the deploy user). One name, so no whitespace (sshd would read each word as another user) and no , (the verify names the user in sshd -C's comma-separated connection spec).

MaxAuthTries — auth attempts before the connection is dropped. Defaults to 3.

LoginGraceTime — seconds to complete authentication. Defaults to 20.