Configuration / PHP and WordPress

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 .php file 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 with 404 without 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.php with the original query string, which is how front-controller applications and WordPress pretty permalinks work. For POST and other write methods to a directory, MiraServe runs that directory's index.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 as miraserve;
  • the socket has mode 0660 and a group that miraserve belongs to, and no wider access;
  • the pool user can write to wp-content/uploads, while miraserve only 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.

RuleBlocksAnswer
WP_PATH_TRAVERSALPaths with . or .. segments or NUL bytes.400
WP_DENY_DOTFILESAny path segment starting with a dot, such as .env, .git/ or .htaccess, except a top-level /.well-known/.404
WP_BLOCK_XMLRPCxmlrpc.php anywhere in the path.403
WP_BLOCK_SENSITIVE_FILESwp-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_PHPFiles ending in .php, .phtml, .phar, .php5, .php7 or .php8 under wp-content/uploads/ or wp-includes/.403
WP_LOGIN_RATE_LIMITRequests 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 Proxy request header is never passed, so PHP never sees an HTTP_PROXY variable set by a client. Many HTTP libraries read HTTP_PROXY as 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_Key and X-Api-Key would both become HTTP_X_API_KEY, and a client could overwrite a header set by a trusted proxy.
  • CONTENT_TYPE and CONTENT_LENGTH are 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

DirectiveDefaultMeaning
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)requiredDirectory containing the scripts. Without it the route is rejected (E303).
preset "wordpress-hardened" (site)noneThe 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 "/*" before route "*.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 gets 403; the log shows rule WP_BLOCK_UPLOADS_PHP.
  • Upload size. With the default max-body-bytes, uploads over 10 MiB fail with 413 before 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.php limit counts by client IP. Behind a CDN, all visitors share the CDN's addresses and may hit the limit together.