0.29.7

docs/PHP_FPM.md

@@ -1,5 +1,10 @@
 # PHP-FPM / FastCGI for the Web Server
 
+**Separate pools for distinct Web Services:** Reusing the same PHP-FPM socket
+with different `PHP_ADMIN_VALUE` maps can leak `open_basedir` restrictions into
+a different virtual host. See the 0.29.7 guide
+[PHP_FPM_ISOLATION.md](PHP_FPM_ISOLATION.md) for remediation and tests.
+
 RustProxy 0.25 can execute configured PHP extensions through a long-running PHP-FPM pool while preserving the reusable Web Service architecture.
 
 ## Architecture
@@ -44,6 +49,90 @@ Configuration example:
 Unspecified PHP fields inherit the safe serde defaults. A service without
 `php_profile_id` uses its own `php` object as in earlier versions.
 
+## Where to configure each PHP setting (0.29.7)
+
+Both editors expose the **same fields and validation**:
+
+1. **Web Server → Web Service → PHP-FPM → Local configuration:** set values on one service (`web_services[].php`). Select **Local configuration** in the profile selector first.
+2. **Web Server → PHP-FPM profiles → Add/Edit profile:** set shared values on a profile (`php_fpm_profiles[].php`), then attach it in a Web Service's PHP-FPM tab (`php_profile_id`). Editing the profile changes every attached service. Per-service `php` values remain saved for later detach but do **not** override an attached profile.
+3. **Actual PHP-FPM pool config** (`php-fpm.d/*.conf` or distribution equivalent): the pool must exist and listen on the configured socket. Isolate restrictive `open_basedir`/`php_admin_value` settings in *separate pools and sockets*, not by alternating request-time `PHP_ADMIN_VALUE` on shared workers. RustProxy does not launch PHP-FPM.
+
+| UI field (JSON property) | What to enter / sample | Notes |
+| --- | --- | --- |
+| Enable PHP-FPM / FastCGI (`enabled`) | Checked for PHP apps | Off means PHP is not executed. Never serve PHP source. |
+| PHP-FPM socket (`endpoint`) | `unix:/run/php/php_wordpress.sock`, `tcp:127.0.0.1:9000`, `tcp:[::1]:9000` | Only local Unix sockets or TCP loopback **IP**, not hostnames. Socket ownership and permissions must allow RustProxy access. |
+| PHP extensions (`extensions`) | `php, phtml` | Comma-separated, no leading dots; at most 16. Only listed extensions are executable. |
+| Enable PHP PATH_INFO splitting (`path_info`) | Checked for Roundcube `/static.php/skins/...` | Splits an existing PHP script path and its trailing URL; off for ordinary WordPress unless needed. |
+| Forward Authorization (`pass_authorization`) | Checked when API / Basic / Bearer auth is used | Sends request `Authorization` to `HTTP_AUTHORIZATION` in FastCGI. |
+| Connection timeout (`connect_timeout_ms`) | `1000` = 1 second | Integer 50–60000 milliseconds. |
+| Request timeout (`request_timeout_ms`) | `30000` = 30 seconds | Integer 100–3600000 milliseconds for the full FastCGI request. |
+| Max simultaneous PHP requests (`max_concurrent_requests`) | `64` | Integer 1–4096 per Web Service; excess is rejected with HTTP 503. |
+| Request-body limit (`max_request_body_bytes`) | `67108864` = 64 MiB; `0` = no additional limit | Integer 0–8589934592 **bytes**, independent of PHP `post_max_size`. |
+| Response-header limit (`max_response_header_bytes`) | `65536` = 64 KiB | Integer 4096–1048576 bytes. |
+| PHP-FPM STDERR log limit (`stderr_log_bytes`) | `4096`; `0` = disabled | Integer 0–65536 bytes collected per request. |
+| Custom FastCGI parameters (`custom_params`) | `APP_ENV = production` | One static `NAME = value` per line. Names A-Z/0-9/underscore, beginning with a letter. No core CGI, HTTP_* or PHP control params. |
+| PHP INI overrides (`php_values` / `PHP_VALUE`) | `memory_limit = 256M` | One php.ini `directive = value` per line. PHP decides which directives can change at this scope. |
+| Administrator PHP INI overrides (`php_admin_values` / `PHP_ADMIN_VALUE`) | `open_basedir = /var/www/webmail/:/tmp/` | Trusted operator only; for security isolation prefer dedicated PHP-FPM pool configuration. Do not define the same directive in both INI maps. |
+
+**Syntax in the three multiline fields is not JSON:** use `key = value`, a separate line per entry; **do not** wrap it in `PHP_VALUE=...` or `php_admin_value[...]` inside the RustProxy editor. Those latter directives belong to the *native PHP-FPM pool configuration*, not the RustProxy FastCGI request fields. Empty values and control characters are rejected. Up to 64 entries per map, maximum 8192 bytes per value and 128 KiB combined.
+
+### Ready-to-use WordPress and Roundcube examples
+
+**WordPress — Web Service `/var/www/linuxiarz.pl/`, dedicated FPM socket:**
+
+```text
+PHP enabled: checked
+PHP PATH_INFO: unchecked
+Endpoint: unix:/run/php/php_wordpress.sock
+PHP extensions: php
+PHP_VALUE:
+  memory_limit = 256M
+  upload_max_filesize = 64M
+  post_max_size = 64M
+  max_execution_time = 60
+PHP_ADMIN_VALUE: leave empty (or set security restrictions in WordPress's own FPM pool)
+```
+
+Use `index.php` in **Index files**, plus `try_files` lines `$uri`, `$uri/`, `/index.php?$query_string` in **Routing**. The WordPress pool must be allowed to read its `wp-config.php`, `wp-includes` and `wp-content` directories.
+
+**Roundcube — Web Service `/var/www/webmail/public_html`, separate FPM socket:**
+
+```text
+PHP enabled: checked
+PHP PATH_INFO: checked
+Endpoint: unix:/run/php/php_roundcube.sock
+PHP extensions: php
+PHP_VALUE:
+  memory_limit = 256M
+  upload_max_filesize = 64M
+  post_max_size = 64M
+PHP_ADMIN_VALUE: prefer the native Roundcube PHP-FPM pool instead; e.g.:
+  open_basedir = /var/www/webmail/:/usr/lib/php/:/tmp/:/etc/enigma
+```
+
+Add additional permitted external paths only if Roundcube's actual dependencies need them. Roundcube assets such as `/static.php/skins/elastic/...` require PATH_INFO splitting. Restart/recycle workers after separating pools; using a different RustProxy profile but the **same socket** does not isolate the worker state. See [pool isolation](PHP_FPM_ISOLATION.md).
+
+### FastCGI vs php.ini examples
+
+```text
+# Custom FastCGI parameters — application-specific static environment:
+APP_ENV = production
+APP_DEBUG = 0
+
+# PHP_VALUE — regular PHP-level options:
+memory_limit = 256M
+max_execution_time = 60
+error_reporting = E_ALL
+log_errors = On
+display_errors = Off
+date.timezone = Europe/Warsaw
+
+# PHP_ADMIN_VALUE — privileged operator-level options:
+open_basedir = /var/www/webmail/:/usr/lib/php/:/tmp/
+```
+
+The `#` comments above are explanations separating fields; **do not paste them** into the corresponding form inputs. Boolean INI directives commonly accept `On`/`Off`, size directives can accept `K`/`M`/`G` and timeouts use seconds. The actual PHP/FPM version determines supported directives and permitted scopes.
+
 ## Runtime model
 
 RustProxy implements the FastCGI protocol directly. It does not spawn `php`, `php-cgi` or shell processes for individual requests.