The comment claimed the extension was "built against THIS image's own lsphp so
the API/ABI always match". It was not, and could not be: `lsphp<NN>-dev` is
absent from the LiteSpeed apt repo at the version every prebuilt OLS base image
ships, because that repo carries only the current release. Measured on
OLS 1.8.4 (2026-08-05), base image vs repo candidate:
lsphp81 8.1.33-5+noble -> 8.1.34-1+noble
lsphp83 8.3.28-1+noble -> 8.3.32-1+noble
lsphp85 8.5.0-3+noble -> 8.5.8-1+noble
and the literal fix — `apt-get install lsphp<NN>-dev="$(dpkg-query lsphp<NN>)"` —
fails on all three with `E: Version '<base>' for 'lsphp<NN>-dev' was not found`
(apt exit 100). So installing -dev necessarily upgrades lsphp in the build stage;
the only satisfiable direction is to move the runtime to meet it.
The skew the reviewer measured (a .so built on 8.3.32 shipped beside an 8.3.30
runtime, lsphp83-common at 8.3.31) was not vendor randomness: BOTH stages resolve
"repo latest" independently and Docker caches them independently. `COPY ./ext`
sits at the top of the ext-build stage, so editing the extension invalidated that
stage's apt layer while stage 2's stayed cached — i.e. every extension edit
rebuilt the .so against fresh headers and shipped it next to a stale runtime.
Fixed by making them one system:
- the toolchain layer moves ABOVE the source COPY, so editing the extension no
longer re-resolves the PHP version;
- it records the resolved version to /build-out/lsphp.version and asserts
lsphp<NN> == lsphp<NN>-dev in that stage;
- stage 2 COPYs that file in BEFORE its apt layer (so the version is part of
that layer's cache key) and pins lsphp/-common/-ldap to it, then asserts the
installed versions match. Unsatisfiable pin => loud apt failure with the
remediation, never a silent fallback.
Verified: builds clean on PHP 8.1/8.3/8.5; the shipped php83 image now reports a
uniform lsphp83 family at 8.3.32 (the previous image shipped lsphp83 8.3.30 /
-common 8.3.31 / -ldap 8.3.30). Mutation-tested by recording a version the repo
no longer has: build fails at stage 2 rather than shipping the skew.
The `lsphp -i | grep` build assertion is kept but its comment now says what it
does and does not prove: it catches a .so that will not LOAD, never silent
struct-layout drift.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
My previous commit used sed with | as both delimiter and literal, which
corrupted the comment line rather than changing -m to -i. The assertion
command itself was never touched and is correct.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The comment describing the assertion still said 'lsphp -m | grep' while the
code correctly uses -i. That is the exact trap documented three lines below --
lsphp is the LSAPI SAPI and answers -m by printing usage and exiting 0, so an
-m based check never matches and never fails. Leaving the comment wrong would
invite someone to 'restore' it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A site moved from cac-fpm to cac-lsphp must see byte-identical
$_SERVER['DOCUMENT_ROOT'] and ['SCRIPT_FILENAME'] (/home/<user>/...).
The auto_prepend_file normaliser that did this was PHP_INI_PERDIR, so
any site with its own .user.ini auto_prepend_file silently displaced it
— the state 7 live shared_ols sites (Wordfence, cPanel imports) are
actually in. Hardening the hook was not an option either: making our
prepend win would have disabled those Wordfence WAFs.
Replace it with cac_path_parity, a small PHP extension that rewrites the
filesystem-path $_SERVER keys from RINIT. RINIT cannot be displaced by
.user.ini, and it occupies no userland hook, so the customer's own
auto_prepend_file stays the only prepend in play and keeps working. The
mapping lives in two PHP_INI_SYSTEM settings, which .user.ini (PERDIR /
USER only) and ini_set() cannot reach.
Mechanism is a path-component-bounded string prefix swap, not realpath():
byte-identical to cac-fpm by construction (realpath would resolve a
customer's own symlinked public_html to some third path), no syscall, and
no failure path. Every guard fails open and leaves $_SERVER untouched;
nothing here can warn, throw or 500 a site. Unconfigured it is fully
inert, so cac-fpm and cac-litespeed are unaffected.
Built in a separate Dockerfile stage keyed off the existing ARG PHPVER —
gcc/phpize/headers never reach the shipped image (verified absent; the
image grows ~155kB), and a base-image PHP bump recompiles with no human
step. A `lsphp -i | grep` assertion fails the build if the .so does not
load, so an image can never ship having silently lost parity.
The entrypoint selects the extension when present and removes any stale
prepend ini left by an older image; if the extension is somehow not
loadable it falls back to the old normaliser and logs a WARNING rather
than losing normalisation entirely. It also now logs the active parity
mode, and warns when lsphp reports no ini scan dir (previously silent).
Probe lsphp with `-i` only: it is the LSAPI SAPI, not the CLI, and
answers `-m`/`-r` by printing usage and exiting 0 — a `lsphp -m | grep`
check never matches and never errors, which is the exact class of silent
always-false assertion this change exists to remove.
Verified: 6 .phpt tests; tests/fpm-parity-check.sh proves under the FPM
SAPI that with a customer .user.ini auto_prepend_file present both keys
are still corrected AND the customer's prepend still runs, and that the
old mechanism does not; and in a real built cac-lsphp:php83 container
that SCRIPT_FILENAME is rewritten, the customer prepend still fires, and
another tenant's path is left untouched.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
php-lsapi compiles .user.ini support in but leaves it DISABLED by default.
sapi/litespeed/lsapi_main.c has `static int parse_user_ini = 0;` and only
sets it when the process environment contains LSPHP_ENABLE_USER_INI=on.
WHP never set it, so lsphp never entered the user-ini chain at all.
The failure was silent: phpinfo() still reports user_ini.filename=.user.ini
and user_ini.cache_ttl=300, because those are core INI defaults that are
simply inert under this SAPI. Every other WHP PHP tier (cac, cac-fpm,
cac-litespeed) honors .user.ini, so shared_ols was quietly inconsistent.
Impact found in production (whp01/whp02/sdbees/TrueSelfCA, 29 sites):
- Per-site memory_limit / max_input_vars overrides were ignored. A Divi
site's max_input_vars stayed at the 2000 default while its .user.ini
asked for 20000.
- Wordfence's auto_prepend_file WAF never loaded on ANY shared_ols site.
11 sites had the plugin installed and reporting "Extended Protection"
enabled while the prepend was never executed.
Verified on a live sidecar (shadowdao.com, whp01) before this commit by
injecting the env var via whp.container_types.startup_env and recreating:
before: auto_prepend_file=/scripts/cac-lsphp-normalize.php (WAF absent)
after: auto_prepend_file=/home/shadowdao/public_html/wordfence-waf.php
wordfence-waf.php present in get_included_files()
class_exists('wfWAF') === true
The platform normalize prepend still chains in behind Wordfence's bootstrap,
so DOCUMENT_ROOT canonicalisation is not lost.
Set in two places on purpose: the Dockerfile ENV makes the value visible in
`docker inspect` and survives an entrypoint override, and the entrypoint
re-exports it with the same default because the runuser fallback exec path
resets the environment. Still overridable per-container
(LSPHP_ENABLE_USER_INI=off) as an escape hatch for a site whose legacy
cPanel-generated .user.ini has not been remediated yet.
NOTE: enabling this activates every previously-inert .user.ini at once.
Audit the fleet for stale cPanel directives before rolling this image —
session.save_path values under /var/cpanel/ that do not exist in the
container, memory_limit above the cgroup cap, and upload_max_filesize
values below the platform default were all found and remediated first.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The symlink makes __FILE__/__DIR__/realpath/getcwd report /home/<user>/public_html
(WordPress/frameworks), but $_SERVER['DOCUMENT_ROOT']/['SCRIPT_FILENAME'] are raw
env vars OLS sets to its /mnt/users view — apps that build/compare paths from
them would see /mnt/users. Added a tiny auto_prepend (cac-lsphp-normalize.php,
wired via a scan-dir ini) that realpath-canonicalises those two back to /home.
Customer sites have no auto_prepend by default, so no conflict.
Verified clean-room (committed image, fresh boot): DOCUMENT_ROOT and
SCRIPT_FILENAME both report /home/<user>/public_html through the shared OLS.
Now byte-for-byte 1:1 with cac-fpm/cac-litespeed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New slim per-site PHP backend that runs 'lsphp -b 0.0.0.0:9000' (detached
LSAPI) and nothing else — the LiteSpeed analogue of cac-fpm, sitting behind
a shared OpenLiteSpeed container. Built on the same litespeedtech prebuilt
base as cac-litespeed so the lsphp runtime/extensions are identical.
- Dockerfile.lsphp: base + lsphpNN-ldap parity, reuses shared lsphp-overrides.ini,
exposes only :9000, no webserver started (guaranteed by entrypoint, not by
stripping OLS binaries).
- entrypoint-lsphp.sh: same uid/user contract + /home/$user/logs layout +
ini drop-in mechanism as entrypoint-litespeed.sh; sizes PHP_LSAPI_CHILDREN
from container memory (detect-memory-lsphp.sh) with panel override precedence;
execs lsphp -b as the per-site user via setpriv (PID 1).
- detect-memory-lsphp.sh: LSAPI_CHILDREN sizing, no OLS daemon reserve.
- healthcheck-lsphp.sh: TCP :9000 + lsphp-alive (LSAPI isn't FastCGI).
- CI: Build-LSPHP-Images job, php81-85 matrix, OLS 1.8.4, cac-lsphp:phpNN.
Verified locally: builds php83+php85; sidecar runs lsphp as the per-site
user (uid 61045) as PID 1, healthcheck green, and a real shared OLS in front
serves PHP over LSAPI (HTTP 200, SAPI=litespeed) with identical docroot path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
shadowdaoandClaude Opus 5