Sandboxing
MiraServe limits what its own process can do, so that a bug in request handling cannot be turned into reading arbitrary files or starting programs. This page explains the layers of confinement, which directories the worker may read and write, what is and is not confined on each operating system, and how to check file access before you start.
Layers of confinement
| Layer | Platforms | What it does |
|---|---|---|
cap-std root confinement | All | Static files are opened relative to the site root through a directory handle. .. and symbolic links cannot leave the root. |
| Landlock | Linux | A kernel feature that limits which files and directories a process may open. MiraServe allows only the paths its config needs; everything else is denied. |
| seccomp | Linux (x86_64, aarch64, riscv64) | A kernel filter on system calls. Dangerous calls, such as starting programs or loading kernel modules, fail with "operation not permitted". |
| Unprivileged user | All (checked on Linux and macOS) | The process must not run as root when sandbox.user or sandbox.group is set. |
On Linux, Landlock and seccomp are applied at startup to the main thread and every worker thread, before the first request is accepted. They cannot be loosened afterwards, not even by a config reload.
Configuration
Landlock and strict seccomp are on by default, so the only line most configs need is the user:
server {
listen ":443"
tls {
cert "/etc/miraserve/certs/example.com.crt"
key "/etc/miraserve/certs/example.com.key"
}
sandbox {
user "miraserve"
group "miraserve"
landlock #true
seccomp "strict"
}
}
site "example.com" {
root "/var/www/example"
}
This passes check --strict.
Directive (in server.sandbox) | Default | Meaning |
|---|---|---|
user | none | Unprivileged user name or numeric ID the server must run as. "root" or 0 is rejected (E201). |
group | none | Unprivileged group name or ID. Same rules as user. |
landlock | #true | Linux file access confinement. #false gives W003. |
seccomp | "strict" | "strict", "standard" or "off". "off" gives W003. |
Running as an unprivileged user
MiraServe does not switch users itself, because doing so would need unsafe system calls that its code forbids. Start it as the target user instead, for example with User=miraserve and AmbientCapabilities=CAP_NET_BIND_SERVICE in systemd so it can bind ports 80 and 443. When user or group is set, MiraServe looks the name up (in /etc/passwd and /etc/group, then through the system's user database) and refuses to start if the process runs as root or as a different user or group than configured. If a name cannot be resolved, use the numeric ID. The Linux packages and miraserve service generate set this up for you; see Deployment.
seccomp profiles
"standard"blocksptrace,mount,umount2,pivot_root,chroot,kexec_load,init_module,finit_module,delete_module,rebootandbpf."strict"blocks all of those, plusexecveandexecveat(the worker cannot start any program),kexec_file_load,swapon,swapoff,perf_event_open,userfaultfd,unshare,setns,process_vm_readv,process_vm_writev,add_key,request_key,keyctl, theio_uringcalls, and the new mount API calls (open_tree,move_mount,fsopen,fsconfig,fsmount,fspick).
On other CPU architectures seccomp cannot be applied and startup fails unless you set seccomp "off".
What the worker may read and write on Linux
Landlock rules are built from the config when the server starts. Read-only access never includes the right to execute files.
| Access | Paths |
|---|---|
| Read only | Public CA certificates and resolver files that exist: /etc/ssl/certs, /etc/ssl/cert.pem, /etc/ssl/openssl.cnf, /etc/ca-certificates, /etc/ca-certificates.conf, /etc/pki/tls/certs, /etc/pki/tls/cert.pem, /etc/pki/ca-trust, /etc/resolv.conf, /etc/hosts. |
| Read only | Every site root and route root, exactly as configured, with everything below it. |
| Read only | The directory of the config file and of every configured file: TLS certificates, TLS keys (only with key-isolation "in-process"), client-ca bundles, upstream TLS files, WASM modules, bot and publishing public keys, and absolute error page files. |
| Read and write | The ACME state directory (--acme-dir, or .miraserve-acme in the start directory) and every ai-publish storage directory. MiraServe creates them at startup if they are missing. |
| Connect only | FastCGI Unix sockets and the key daemon socket. |
| Denied | Everything else, including writing into site roots. |
Outgoing network connections (to upstreams, PHP-FPM over TCP, the ACME authority) are not restricted by Landlock.
Explicitly configured roots are allowed
A directory you name yourself as a site or route root, ACME directory or publishing store is granted as given, including common locations such as /var/www/example, /srv/site, /opt/app/public or /var/lib/miraserve/releases. MiraServe refuses only directories that are unsafe even when asked for explicitly:
- relative paths (the one exception is the default ACME directory
.miraserve-acme),/, and any path containing..; - anything under
/etc,/root,/proc,/sys,/devor/boot; - broad shared directories as a whole:
/bin,/sbin,/lib,/lib64,/usr,/usr/local,/usr/share,/usr/lib,/usr/bin,/usr/sbin,/var,/var/lib,/var/log,/var/run,/var/tmp,/var/cache,/tmp,/run,/home,/Usersand/private(with/private/etc,/private/varand/private/tmp); - a user's whole home directory, such as
/home/alice(a directory inside it, such as/home/alice/site, is allowed); - a symbolic link whose real target is one of the above.
miraserve check rejects most of these as error E202. Cases it can only see on disk, such as a symbolic link to a refused directory, are reported as warning W017 and logged at startup, and the site cannot read its files. Move the content into a dedicated directory.
Certificates and other files that change
For files that are replaced while the server runs, such as certificates, MiraServe grants the containing directory, so that tools which write a new file and rename it into place keep working. It never widens access to shared directories such as /var/lib, /etc/ssl, /etc/letsencrypt/live or any parent of /etc/miraserve/keys. In that case it grants only the exact file and logs a note; replacing that file by renaming then requires a restart. Keep certificates in a dedicated directory such as /etc/miraserve/certs. For symbolic links, such as Certbot's live links, the directory of the link target is granted as well.
The rules are fixed at startup. If a reload adds a root or file outside them, MiraServe logs a warning and the new path stays inaccessible until you restart. A read-only path or socket that does not exist at startup is left out with a warning; create it and restart.
macOS and Windows
Landlock and seccomp exist only on Linux. On macOS and Windows:
- The startup log reports both as unsupported on this platform. The settings are accepted, so one config can serve all platforms.
- Confinement of static files to the site root through
cap-stdstill applies. - There is no system-wide file or system call restriction. The process can read and write whatever its operating system account can. Run it under a dedicated account: a launchd daemon user on macOS, or
NT AUTHORITY\LOCAL SERVICEas set up by the Windows installer script. - On macOS the
userandgroupcheck also runs. On Windows it is not checked; the service account is the boundary.
Treat Linux as the platform for exposed production servers.
Checking file access with --fs
miraserve check --fs validates the config and then tests every configured file and directory:
- TLS certificates and keys are readable, not empty, parse as PEM, and each key matches its certificate. With
split-daemononly the certificate is read, and the key daemon socket must exist and accept a connection. client-cabundles are readable and contain valid certificates.- Site and route roots are readable directories, and custom error page files are readable.
- The ACME state directory and every publishing
storagedirectory are writable. Pass--acme-dirto test the same directory you givemiraserve run. - Bot-auth key files, publishing and MCP public keys, WASM modules and upstream TLS files are readable.
Problems are reported as errors, and the exit code is 1:
$ miraserve check --fs site.kdl
error[E301]: server.tls.cert '/etc/miraserve/certs/site.crt' is missing or unreadable: No such file or directory (os error 2)
error[E301]: server.tls.key '/etc/miraserve/certs/site.key' is missing or unreadable: No such file or directory (os error 2)
error[E301]: server.tls certificate/key pair ('/etc/miraserve/certs/site.crt', '/etc/miraserve/certs/site.key') is invalid or mismatched: TLS I/O error at '/etc/miraserve/certs/site.crt': No such file or directory (os error 2)
error[E301]: site 'example.com' root directory '/var/www/example' is missing or unreadable: No such file or directory (os error 2)
FAILED: 'site.kdl' failed --fs check with 4 filesystem error(s) and 0 warning(s)
The check runs with the permissions of whoever starts it. Run it as the service user, so it sees what the server will see:
$ sudo -u miraserve miraserve check --fs --strict /etc/miraserve/conf/miraserve.kdl
--fs does not test FastCGI sockets, and it does not simulate Landlock. A path can pass --fs and still be refused at startup if it resolves to one of the directories listed above; watch for W017.
Turning confinement off
miraserve run --no-sandbox skips Landlock and seccomp for one run. Use it only to find out whether a problem is caused by the sandbox, never in production. If the kernel has no Landlock support, startup fails with a message saying so; on such hosts you can set landlock #false (warning W003). On older kernels with partial Landlock support, the log notes that the rules are partially enforced.
Pitfalls
- Site root in a refused directory.
root "/var",root "/home/alice"or a symbolic link pointing into/etccannot be served. Use a dedicated subdirectory. - Starting as root with
userset. MiraServe does not drop privileges; it refuses to start. Let the service manager start it as the user. - PHP-FPM started after MiraServe. A FastCGI socket that does not exist at startup is not granted. Order the services so PHP-FPM starts first.
- New paths on reload. Adding a site with a new root needs a restart on Linux, not only a reload.
- ACME directory. Without
--acme-dir, ACME state goes to.miraserve-acmein the start directory, which must be writable. A relative--acme-diris refused by the sandbox; give an absolute path. - Assuming the same protection everywhere. On macOS and Windows only root confinement and the account's own permissions protect the system.