RustProxy/docs/PHP_FPM.md

PHP-FPM with Web Services

RustProxy's Web Server supports FastCGI forwarding to an existing PHP-FPM pool for configured script extensions. RustProxy does not include a PHP interpreter or run the PHP application itself.

Before enabling PHP

Install and start PHP-FPM independently, configure the application files and create a dedicated pool/socket for each application or security domain. Set the correct Unix user/group, socket permissions, PHP version and pool-level configuration. Restrict a TCP FPM endpoint to a trusted private interface; never expose FastCGI directly to the Internet.

In Web Server → PHP-FPM profiles create a reusable profile, or set PHP options in one Web Service. Select a socket such as unix:/run/php/app.sock or a reachable TCP endpoint (use the syntax accepted by the editor); enable PHP, choose extensions (default .php) and set request/connect timeouts and concurrency. Attach the profile to a Web Service and publish that service using a Vhost.

Important settings

Setting	Effect
Endpoint	Unix socket or private TCP address of a real PHP-FPM service.
Extensions	Which files are eligible for PHP execution. Confirm front-controller routes and direct PHP paths.
try_files / PATH_INFO	Resolve PHP front-controller or script.php/... paths, where supported, without accidentally executing an unintended file.
Connect/request timeouts	Bound waiting for FPM connection and application execution. Defaults in source include 1 s connect and 30 s request.
Concurrent requests	Local RustProxy FastCGI request limit (default 64), not the number of FPM worker processes.
Authorization forwarding	Optional preservation of eligible Authorization information (default enabled). Review application expectations.
Custom FastCGI parameters	Static application-specific settings. Reserved transport/identity parameters cannot be overridden arbitrarily.
PHP values	PHP_VALUE and PHP_ADMIN_VALUE options for the external FPM workers.
Body/header limits	Bound upload size, response headers and stderr exposed in logs.

Pool isolation is mandatory for mixed applications

PHP-FPM workers can retain PHP_VALUE / PHP_ADMIN_VALUE behavior across requests. Two applications with different INI/admin settings must not share one FPM worker pool, even when they have different RustProxy Vhosts. RustProxy may warn about conflicting shared endpoints but cannot isolate PHP workers inside FPM.

Example separation:

Web Service: blog           -> unix:/run/php/php_blog.sock
Web Service: webmail        -> unix:/run/php/php_webmail.sock

Give each pool access only to its own application's files; configure open_basedir and other hardening at FPM pool level where possible. Restart the affected FPM pools after policy changes to retire existing workers.

WordPress and Roundcube

For WordPress, point the document root to the website directory, enable PHP for .php, use the appropriate front-controller (index.php) and verify that wp-config.php exists and is readable only where needed. A redirect to setup-config.php can indicate filesystem/FPM/open_basedir misconfiguration rather than proxy cache.

For Roundcube, use its published web root and a separate FPM pool with the application's expected file access. Some Roundcube static script URLs use PATH_INFO; enable/test handling that resolves static.php/... without turning arbitrary strings into executable script names.

These are routing examples; presets do not install either application or choose a safe OS-specific pool automatically.

Diagnostics

• 502/503/504: check FPM health, Unix socket group permissions, endpoint path, capacity and configured timeouts.
• PHP errors/blank page: check FPM stderr, application logs and effective INI values.
• Incorrect site appears to inherit another site's open_basedir: use distinct FPM pools and restart them.
• Compressed PHP content truncated: verify current application response/framing and try the same request without compression; review FastCGI and response logs.
• Cache behavior differs from static files: PHP may ignore validators or send private / Set-Cookie, preventing shared cache storage.

Inspect Web Server → Live metrics, Logs and the application's own FPM logs. The proxy's PHP request semaphore is not a replacement for monitoring external FPM worker capacity.