Running as a service
This page shows how to run MiraServe as a long-lived service on Linux with systemd: which users and directories it needs, how to generate a hardened unit file, how to check and reload configuration, and how to keep TLS private keys out of the web server process.
Alpha software. The current version is 0.1.0-alpha.0. There is no tagged release yet and no packages have been published. The repository contains packaging definitions, but they have not yet been validated on real installs. Use alpha builds for evaluation, not for production traffic.
What the repository contains
The source tree (not published yet, see availability) contains packaging definitions under packaging/ and a Containerfile at the top level. None of them has produced a published artifact yet.
| Target | Where | State |
|---|---|---|
| systemd units | miraserve service generate --target systemd and --target systemd-keyd; copies in packaging/systemd/ | Generated by the binary; described on this page. |
| .deb and .rpm | packaging/nfpm/nfpm.yaml (nFPM), with sysusers.d, tmpfiles.d and install scripts | Definition only; no package has been built for release. |
| Homebrew | packaging/homebrew/miraserve.rb | Refers to a v0.1.0-alpha.0 source tarball that has not been published and carries a placeholder checksum. |
| Container image | Containerfile (distroless, runs as UID 65532) | Can be built locally; no image has been published. |
| macOS launchd | miraserve service generate --target launchd | Generated by the binary. |
| Windows | miraserve service generate --target windows (scheduled-task installer script) | The project's own documentation calls this development / non-production: stopping the task terminates the process without a graceful drain. |
Build and install the binary
Build from a checkout with a recent stable Rust toolchain, then install the binary where the generated unit expects it (/usr/bin/miraserve by default):
$ cargo build --release --locked --bin miraserve
$ sudo install -m 0755 target/release/miraserve /usr/bin/miraserve
$ miraserve --version
miraserve 0.1.0-alpha.0
Users and directories
MiraServe never needs to run as root. The packaging defines two system accounts, both with no login shell:
miraserveruns the web server (the worker).miraserve-keydruns the optional TLS signing daemon described in key isolation.
From a checkout you can create both accounts and all directories with the same sysusers.d and tmpfiles.d files the packages would install:
$ sudo install -m 0644 packaging/systemd/miraserve.sysusers /usr/lib/sysusers.d/miraserve.conf
$ sudo install -m 0644 packaging/systemd/miraserve.tmpfiles /usr/lib/tmpfiles.d/miraserve.conf
$ sudo systemd-sysusers /usr/lib/sysusers.d/miraserve.conf
$ sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/miraserve.conf
| Path | Mode and owner | Purpose |
|---|---|---|
/etc/miraserve/conf | 0750 root:miraserve | Configuration (miraserve.kdl, readable by the worker, not writable). |
/etc/miraserve/certs | 0750 root:miraserve | Certificate chains, and private keys when keys stay in-process. |
/etc/miraserve/keys | 0700 miraserve-keyd:miraserve-keyd | Private keys for split-daemon mode. The worker cannot read it. |
/var/lib/miraserve/acme | 0700 miraserve:miraserve | ACME account and issued certificates. |
/var/lib/miraserve/releases | 0750 miraserve:miraserve | Release stores for atomic publishing. |
/run/miraserve | 0750 miraserve:miraserve | PID file. |
/run/miraserve-keyd | 2750 miraserve-keyd:miraserve | Signing daemon socket. |
/var/www/miraserve | 0755 root:root | Default document root. |
The configuration lives in its own conf subdirectory rather than directly in /etc/miraserve. On Linux, MiraServe confines itself with Landlock (a kernel feature that lets a process restrict its own file access). Keeping the config in a dedicated directory lets Landlock grant access to that directory, so an editor's save-by-rename still reloads cleanly, without that grant also covering /etc/miraserve/keys.
A minimal service configuration
Put this in /etc/miraserve/conf/miraserve.kdl (owner root:miraserve, mode 0640). It serves one static site with a certificate you provide; see TLS for ACME instead.
server {
listen ":443" protocols="h3,h2,h1"
listen ":80" redirect-https=#true
tls {
key-isolation "in-process"
cert "/etc/miraserve/certs/example.com.crt"
key "/etc/miraserve/certs/example.com.key"
}
sandbox {
user "miraserve"
landlock #true
seccomp "strict"
}
}
site "example.com" {
root "/var/www/miraserve"
}
Generate the systemd unit
miraserve service generate writes a hardened unit for the binary, config and ACME paths you give it. Without --output it prints to standard output; with --output it refuses to overwrite an existing file unless you add --force.
$ sudo miraserve service generate --target systemd \
--binary /usr/bin/miraserve \
--config /etc/miraserve/conf/miraserve.kdl \
--acme-dir /var/lib/miraserve/acme \
--output /etc/systemd/system/miraserve.service
$ sudo systemctl daemon-reload
An excerpt of the generated unit with the default paths:
[Service]
Type=simple
User=miraserve
Group=miraserve
ExecStartPre="/usr/bin/miraserve" check --fs --acme-dir "/var/lib/miraserve/acme" "/etc/miraserve/conf/miraserve.kdl"
ExecStart="/usr/bin/miraserve" run "/etc/miraserve/conf/miraserve.kdl" --acme-dir "/var/lib/miraserve/acme" --pid-file /run/miraserve/miraserve.pid
ExecReload="/usr/bin/miraserve" reload --pid-file /run/miraserve/miraserve.pid --config "/etc/miraserve/conf/miraserve.kdl"
KillSignal=SIGTERM
# Derived from `server.timeouts.graceful-drain` + 15s grace (override with `--graceful-drain <secs>`).
TimeoutStopSec=45s
Restart=on-failure
# Privilege separation: bind :80/:443 without ever running as UID 0 (Threat Model T2/T5)
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
NoNewPrivileges=yes
...
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
PrivateDevices=yes
...
# Set MemoryDenyWriteExecute=yes (via --no-wasm) if Wasmtime JIT plugins are not used.
MemoryDenyWriteExecute=no
...
InaccessiblePaths=-/etc/miraserve/keys
ReadWritePaths=/var/lib/miraserve /run/miraserve
UMask=0027
Points worth knowing:
- The service runs as
miraserveand receives onlyCAP_NET_BIND_SERVICE, the capability needed to bind ports 80 and 443. ExecStartPrerunsmiraserve check --fs, so a configuration that does not validate, or that names files the service user cannot read, stops the start instead of half-starting./etc/miraserve/keysis always inaccessible to this unit, whichever key mode you use.MemoryDenyWriteExecuteisnoby default because WASM plugins are compiled to machine code at load time. If you do not use plugins, pass--no-wasmto set it toyes.
| Flag | Default | Meaning |
|---|---|---|
--target | required | systemd, systemd-keyd, launchd or windows. |
--binary | per platform (/usr/bin/miraserve for systemd) | Path to the installed binary. |
--config | /etc/miraserve/conf/miraserve.kdl for systemd | Configuration file. |
--user, --group | miraserve (miraserve-keyd for systemd-keyd) | Service account. |
--acme-dir | /var/lib/miraserve/acme for systemd | ACME state directory. |
--split-keyd | off | Order the worker after miraserve-keyd.service and add Wants= on it. |
--keyd-socket | /run/miraserve-keyd/keyd.sock | Signing daemon socket, used by systemd-keyd. |
--auth-secret-file | none | Shared secret file for loopback TCP signing-daemon mode. |
--no-wasm | off | Set MemoryDenyWriteExecute=yes. |
--graceful-drain | read from --config if it exists, else 30 | Seconds; TimeoutStopSec is this plus 15. |
-o, --output | standard output | Write to a file. |
--force | off | Overwrite an existing output file. |
Check the configuration as the service user
miraserve check validates the configuration against the schema and the project's security rules. --fs also verifies on disk that configured certificates and keys, CA bundles, site roots, WASM modules, bot-auth key files, publishing keys and release stores exist and can be used, and, with --acme-dir, the ACME state directory. --strict turns every warning into a failure.
Run it as miraserve, not as root. Root can read every file, so a check run as root can pass while the service itself would fail to start on a permission error.
$ sudo -u miraserve miraserve check --fs --strict --acme-dir /var/lib/miraserve/acme /etc/miraserve/conf/miraserve.kdl
In split-daemon mode --fs deliberately skips the readability check on private keys, because the worker is not supposed to read them. Instead it checks that the signing daemon's socket exists and that the current user can connect to it, so start miraserve-keyd first.
Start, stop and reload
$ sudo systemctl enable --now miraserve.service
$ sudo systemctl reload miraserve.service
$ sudo systemctl status miraserve.service
systemctl reload runs miraserve reload, which validates the file first, then sends SIGHUP to the PID in the PID file and waits for the server to report success or failure. If the new file does not validate, the running configuration stays in place. You can run it directly too:
$ sudo miraserve reload --pid-file /run/miraserve/miraserve.pid --config /etc/miraserve/conf/miraserve.kdl
OK: MiraServe PID 71771 reloaded successfully (generation 2)
Some settings are not applied by a reload. The server logs a warning and keeps the old value until you restart: listen addresses, sandbox, telemetry metrics-listen, metrics-path and otlp-endpoint, key-isolation and keyd-socket, any client-ca, and the acme block.
On stop, systemd sends SIGTERM and MiraServe drains open connections for up to graceful-drain (30 seconds by default).
TLS key isolation: in-process or split-daemon
MiraServe has two ways of holding TLS private keys, set with key-isolation in server { tls { } }:
"in-process"(the default): the web server process loads the keys itself. This is the only mode that works with built-in ACME."split-daemon": a separate process,miraserve keyd, holds the keys and performs only the signing step of each TLS handshake. The web server asks it for signatures over a local socket and never has the key bytes in its memory, so a bug that leaks worker memory cannot leak the keys.
Split-daemon mode cannot be combined with ACME: check rejects an acme block with error E106 unless every site has a manual certificate and key. Use certificates you obtain separately, with the chain in /etc/miraserve/certs/ and the key in /etc/miraserve/keys/ (owner miraserve-keyd, mode 0600).
server {
listen ":443" protocols="h3,h2,h1"
listen ":80" redirect-https=#true
tls {
key-isolation "split-daemon"
keyd-socket "/run/miraserve-keyd/keyd.sock"
cert "/etc/miraserve/certs/example.com.crt"
key "/etc/miraserve/keys/example.com.key"
}
sandbox {
user "miraserve"
}
}
site "example.com" {
root "/var/www/miraserve"
}
Generate both units, start the signing daemon, check the configuration as the worker user (this confirms it can reach the daemon's socket), then start the worker:
$ sudo miraserve service generate --target systemd-keyd \
--config /etc/miraserve/conf/miraserve.kdl \
--output /etc/systemd/system/miraserve-keyd.service
$ sudo miraserve service generate --target systemd --split-keyd \
--output /etc/systemd/system/miraserve.service --force
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now miraserve-keyd.service
$ sudo -u miraserve miraserve check --fs --strict /etc/miraserve/conf/miraserve.kdl
$ sudo systemctl enable --now miraserve.service
The generated signing-daemon unit runs as miraserve-keyd with no capabilities and no network access (PrivateNetwork=yes), and accepts connections only from the miraserve user. Its socket directory, /run/miraserve-keyd, is created from the tmpfiles.d file installed earlier, so that file must be in place:
[Service]
Type=simple
User=miraserve-keyd
Group=miraserve-keyd
SupplementaryGroups=miraserve
ExecStartPre=+/usr/bin/systemd-tmpfiles --create --prefix=/run/miraserve-keyd /usr/lib/tmpfiles.d/miraserve.conf
ExecStart="/usr/bin/miraserve" keyd --socket "/run/miraserve-keyd/keyd.sock" --config "/etc/miraserve/conf/miraserve.kdl" --allow-peer-user miraserve
...
CapabilityBoundingSet=
AmbientCapabilities=
NoNewPrivileges=yes
PrivateNetwork=yes
RestrictAddressFamilies=AF_UNIX
...
MemoryDenyWriteExecute=yes
ReadOnlyPaths=/etc/miraserve
ReadWritePaths=-/run/miraserve-keyd
--allow-peer-user miraserve makes the daemon check the connecting process's user ID through the kernel (SO_PEERCRED) and accept only that exact user, not every member of the miraserve group.
Where Unix sockets with peer credentials are not available, the signing daemon can listen on loopback TCP instead (for example keyd-socket "tcp://127.0.0.1:9444"; non-loopback addresses are rejected). In that mode, give both sides the same 32-byte secret file: --auth-secret-file for miraserve keyd and --keyd-auth-secret-file for miraserve run.
miraserve keyd flag | Default | Meaning |
|---|---|---|
--socket | /run/miraserve-keyd/keyd.sock | Unix socket path or tcp://127.0.0.1:<port>. |
--config | none | Load every certificate and key pair from a MiraServe config. |
--cert, --key, --hosts | none | Load one pair directly, for the listed SNI host names. |
--allow-peer-user | none | The single worker user allowed to connect. |
--auth-secret-file | none | Shared HMAC secret for loopback TCP. |
--allow-tls12 | off | Sign TLS 1.2 handshakes for all keys. Without it, only keys whose site enables TLS 1.2 may be used for TLS 1.2. |
--dev-tls | off | Generate a throwaway development certificate inside the daemon. |
Firewall
Open TCP 80 and TCP 443, plus UDP 443 if you enable HTTP/3, on both IPv4 and IPv6. A bare ":443" listener binds both address families.
Containers
The Containerfile builds a distroless image that runs as UID and GID 65532 and listens on 8443 (HTTPS) and 8080 (redirect). Its default command starts with --dev-tls, a throwaway self-signed certificate, so it is only a demonstration. For anything else, mount your own config and override the command without --dev-tls, so that missing certificates stop the server instead of being replaced.
$ docker build -f Containerfile -t miraserve:local .
$ docker run --rm -p 8443:8443/tcp -p 8443:8443/udp -p 8080:8080/tcp miraserve:local
Limits and current state
- No release has been tagged and no package, image or Homebrew bottle is published. Everything on this page assumes a source build.
- The nFPM packages, Homebrew formula and container image have not been validated on real installs.
- Landlock and seccomp (a Linux filter that blocks dangerous system calls) apply on Linux only. On macOS and Windows the server logs that they are unsupported and relies on the remaining confinement. See sandboxing.
- The Windows scheduled task stops by terminating the process, so in-flight requests are cut off.