Getting started / Running as a service

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.

TargetWhereState
systemd unitsmiraserve service generate --target systemd and --target systemd-keyd; copies in packaging/systemd/Generated by the binary; described on this page.
.deb and .rpmpackaging/nfpm/nfpm.yaml (nFPM), with sysusers.d, tmpfiles.d and install scriptsDefinition only; no package has been built for release.
Homebrewpackaging/homebrew/miraserve.rbRefers to a v0.1.0-alpha.0 source tarball that has not been published and carries a placeholder checksum.
Container imageContainerfile (distroless, runs as UID 65532)Can be built locally; no image has been published.
macOS launchdmiraserve service generate --target launchdGenerated by the binary.
Windowsmiraserve 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:

  • miraserve runs the web server (the worker).
  • miraserve-keyd runs 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
PathMode and ownerPurpose
/etc/miraserve/conf0750 root:miraserveConfiguration (miraserve.kdl, readable by the worker, not writable).
/etc/miraserve/certs0750 root:miraserveCertificate chains, and private keys when keys stay in-process.
/etc/miraserve/keys0700 miraserve-keyd:miraserve-keydPrivate keys for split-daemon mode. The worker cannot read it.
/var/lib/miraserve/acme0700 miraserve:miraserveACME account and issued certificates.
/var/lib/miraserve/releases0750 miraserve:miraserveRelease stores for atomic publishing.
/run/miraserve0750 miraserve:miraservePID file.
/run/miraserve-keyd2750 miraserve-keyd:miraserveSigning daemon socket.
/var/www/miraserve0755 root:rootDefault 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 miraserve and receives only CAP_NET_BIND_SERVICE, the capability needed to bind ports 80 and 443.
  • ExecStartPre runs miraserve 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/keys is always inaccessible to this unit, whichever key mode you use.
  • MemoryDenyWriteExecute is no by default because WASM plugins are compiled to machine code at load time. If you do not use plugins, pass --no-wasm to set it to yes.
FlagDefaultMeaning
--targetrequiredsystemd, systemd-keyd, launchd or windows.
--binaryper platform (/usr/bin/miraserve for systemd)Path to the installed binary.
--config/etc/miraserve/conf/miraserve.kdl for systemdConfiguration file.
--user, --groupmiraserve (miraserve-keyd for systemd-keyd)Service account.
--acme-dir/var/lib/miraserve/acme for systemdACME state directory.
--split-keydoffOrder the worker after miraserve-keyd.service and add Wants= on it.
--keyd-socket/run/miraserve-keyd/keyd.sockSigning daemon socket, used by systemd-keyd.
--auth-secret-filenoneShared secret file for loopback TCP signing-daemon mode.
--no-wasmoffSet MemoryDenyWriteExecute=yes.
--graceful-drainread from --config if it exists, else 30Seconds; TimeoutStopSec is this plus 15.
-o, --outputstandard outputWrite to a file.
--forceoffOverwrite 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 flagDefaultMeaning
--socket/run/miraserve-keyd/keyd.sockUnix socket path or tcp://127.0.0.1:<port>.
--confignoneLoad every certificate and key pair from a MiraServe config.
--cert, --key, --hostsnoneLoad one pair directly, for the listed SNI host names.
--allow-peer-usernoneThe single worker user allowed to connect.
--auth-secret-filenoneShared HMAC secret for loopback TCP.
--allow-tls12offSign 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-tlsoffGenerate 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.