PHP and WordPress
MiraServe does not run PHP itself. It passes PHP requests to PHP-FPM, a separate PHP process manager, over the FastCGI protocol, and serves everything else as static files. This page shows how to connect the two safely, gives a complete WordPress config, and lists exactly what the wordpress-hardened preset blocks.
Always pair a PHP application's root with a route "*.php" that uses fastcgi-pass. MiraServe refuses to serve .php files as downloads only when a FastCGI route on the same site covers that extension, or when the site uses preset "wordpress-hardened". A site with only root "/var/www/wordpress" hands out wp-config.php, including the database password, to anyone who asks. Never point a root at PHP code without that route.
A generic PHP application
site "app.example.com" {
root "/var/www/app/public"
route "*.php" {
fastcgi-pass "unix:/run/php/php8.3-fpm.sock"
}
route "/*" {
try-files "{path}" "{path}/" "/index.php?{query}"
}
}
The order matters: route "*.php" must come before route "/*", or the catch-all takes every request and the checker warns with W014.
- A request for a
.phpfile goes to PHP-FPM, but only if that file exists inside the root. A missing script, or a path ending in/such as/uploads/photo.jpg/x.php/, is answered with404without contacting PHP-FPM. - Any other request is served as a static file if it exists, then as a directory with an index file, and otherwise rewritten internally to
/index.phpwith the original query string, which is how front-controller applications and WordPress pretty permalinks work. ForPOSTand other write methods to a directory, MiraServe runs that directory'sindex.php.
fastcgi-pass accepts a Unix socket ("unix:/run/php/php8.3-fpm.sock") or a TCP address ("127.0.0.1:9000" or "tcp://127.0.0.1:9000"). Prefer the Unix socket. FastCGI over TCP is not encrypted, so a target that is not loopback produces warning W005. Unix sockets are not available on Windows.
A complete WordPress site
This config passes check --strict. It assumes WordPress is installed in /var/www/wordpress, PHP-FPM listens on the socket shown, and MiraServe runs as the user miraserve:
server {
listen ":443"
listen ":80" redirect-https=#true
tls {
acme {
email "[email protected]"
}
}
sandbox {
user "miraserve"
}
limits {
max-body-bytes "64MiB"
}
}
site "blog.example.com" {
preset "wordpress-hardened"
root "/var/www/wordpress"
rate-limit requests=300 per="1m" burst=60
route "*.php" {
fastcgi-pass "unix:/run/php/php8.3-fpm.sock" timeout="60s"
}
route "/*" {
try-files "{path}" "{path}/" "/index.php?{query}"
}
}
max-body-bytes is raised from the default 10 MiB so media uploads work; keep it in line with PHP's upload_max_filesize and post_max_size. Set up PHP-FPM so that:
- the pool runs as its own user (for example
www-data), not asmiraserve; - the socket has mode
0660and a group thatmiraservebelongs to, and no wider access; - the pool user can write to
wp-content/uploads, whilemiraserveonly needs to read the WordPress files.
What wordpress-hardened blocks
The preset checks every request before routing, and checks again after a try-files rewrite. Paths are compared without regard to letter case, after percent-decoding, with backslashes treated as slashes. The rule names appear in the log when a request is blocked.
| Rule | Blocks | Answer |
|---|---|---|
WP_PATH_TRAVERSAL | Paths with . or .. segments or NUL bytes. | 400 |
WP_DENY_DOTFILES | Any path segment starting with a dot, such as .env, .git/ or .htaccess, except a top-level /.well-known/. | 404 |
WP_BLOCK_XMLRPC | xmlrpc.php anywhere in the path. | 403 |
WP_BLOCK_SENSITIVE_FILES | wp-config.php and any name starting with it (such as wp-config.php.bak), wp-config-sample.php, readme.html, license.txt, debug.log, and backup files ending in ~, .bak, .old, .orig, .swp or .sql, anywhere in the path. | 404 |
WP_BLOCK_UPLOADS_PHP | Files ending in .php, .phtml, .phar, .php5, .php7 or .php8 under wp-content/uploads/ or wp-includes/. | 403 |
WP_LOGIN_RATE_LIMIT | Requests for wp-login.php above 10 per minute per client IP, with a burst of 5. | 429 |
In addition, the preset makes the static file handlers refuse .php, .phtml, .phar and .phps files on that site, even without a FastCGI route.
What MiraServe sends to PHP-FPM
MiraServe sets the standard CGI variables: SCRIPT_FILENAME (the root plus the script path), SCRIPT_NAME, DOCUMENT_ROOT, REQUEST_METHOD, REQUEST_URI, QUERY_STRING, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, REMOTE_ADDR, CONTENT_TYPE, CONTENT_LENGTH, REQUEST_SCHEME, REDIRECT_STATUS, and HTTPS=on for HTTPS requests. Request headers are passed as HTTP_* variables, with these exceptions:
- HTTPoxy protection. The
Proxyrequest header is never passed, so PHP never sees anHTTP_PROXYvariable set by a client. Many HTTP libraries readHTTP_PROXYas their outgoing proxy, which would let an attacker route the application's own requests through a server they control (CVE-2016-5385). - Header names containing an underscore are dropped. Otherwise
X_Api_KeyandX-Api-Keywould both becomeHTTP_X_API_KEY, and a client could overwrite a header set by a trusted proxy. CONTENT_TYPEandCONTENT_LENGTHare set from the actual request, not copied from client headers.
PATH_INFO is not set. Applications that need URLs such as /index.php/some/path should use rewrite-style URLs through try-files instead.
The request body is read completely before it is sent to PHP-FPM, within max-body-bytes. The response is also collected completely before it is sent to the client, up to 32 MiB; a larger PHP response fails with 502. A script that runs longer than the route's timeout gets 504.
Reference
| Directive | Default | Meaning |
|---|---|---|
fastcgi-pass "<target>" | required | "unix:/path.sock", "host:port" or "tcp://host:port". |
timeout= (property of fastcgi-pass) | "30s" | Longest a script may run. Between 1 ms and "300s". |
root (route or site) | required | Directory containing the scripts. Without it the route is rejected (E303). |
preset "wordpress-hardened" (site) | none | The rules in the table above. |
max-body-bytes (server.limits) | "10MiB" | Largest request body for any request, including uploads to PHP. Up to "1GiB". |
Pitfalls
- Root without a PHP route. Serves PHP source code, including secrets. See the warning at the top.
- Route order.
route "/*"beforeroute "*.php"means PHP never runs. - XML-RPC users. The preset blocks
xmlrpc.php. Plugins and apps that still depend on XML-RPC stop working on that site. - PHP under wp-includes. The preset blocks direct requests to any PHP file under
wp-includes/. If a plugin or older editor code loads such a file directly, it gets403; the log shows ruleWP_BLOCK_UPLOADS_PHP. - Upload size. With the default
max-body-bytes, uploads over 10 MiB fail with413before they reach PHP. - Socket created after start. On Linux, the sandbox only grants access to sockets that exist when MiraServe starts. Start PHP-FPM first, or restart MiraServe after it; see Sandboxing.
- Login rate limit behind a proxy. The
wp-login.phplimit counts by client IP. Behind a CDN, all visitors share the CDN's addresses and may hit the limit together.