Skip to content

Keep what a root PHP CLI writes usable by php-fpm - #658

Merged
daylioti merged 1 commit into
masterfrom
qdb-root-cli-ownership
Nov 5, 2026
Merged

daylioti merged 1 commit into
masterfrom
qdb-root-cli-ownership

Conversation

@daylioti

@daylioti daylioti commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator

Problem

php-fpm runs as the site's user (www-data). A command started with docker exec / kubectl exec runs as root unless the caller remembers su, and what PHP creates in that process comes out root:root 0755/0644. php-fpm then can't use it:

  • quanta_db takes a per-node flock on <base>/locks/<node>.lock, which it opens with create(true).write(true). If a root process is the first to create the locks dir or a lock file, php-fpm can neither create a new lock file in that dir nor open an existing one for writing. Every request that writes such a node then fails with QuantaDbException: Permission denied (os error 13). The client gets an empty 500, and nothing is written to the app log.
  • The same goes for the other files the extension creates: the metrics arena, a new node's dir and its documents, and the trashbin dirs. If the site user's workers can't map the arena, they also lose the coherence heartbeat and keep serving from the fallback path.
  • doctor itself writes the class map, caches and node documents as root.

The entrypoint's chown only covers what exists at boot. Whatever a later root exec creates stays root-owned until someone chowns it by hand.

Change

  • doctor drops root. Started as root, it switches to the owner of sites/<host> before boot.php runs (gid, then supplementary groups, then uid). It does this in the same process, so the arguments, -d options, output and exit status don't change. It keeps root when the site dir is root-owned (an image build) or when QUANTA_DOCTOR_AS_ROOT=1 is set. If the switch fails, it exits 1 with a message instead of carrying on as root.

  • The entrypoint and quanta-build-assets keep root (QUANTA_DOCTOR_AS_ROOT=1). They run doctor on dirs they have just created as root, and they fix ownership afterwards, as before.

  • The extension creates files as the owner of the target dir. In the new qdb/src/own.rs, while a root process creates an entry, its filesystem uid/gid is set to the owner of the directory the entry goes in. This uses setfsuid/setfsgid, which act per thread; the real and effective ids stay root. It applies to:

    • the lock dir and lock files;
    • the metrics arena;
    • a new node's dir (created as the father dir's owner);
    • document writes (created as the node dir's owner);
    • the trashbin dirs, including the copy made when the trashbin is on another filesystem.

    Opening, renaming and removing existing entries keep root's rights. Nothing changes unless euid is 0.

    This is deliberately not a chown afterwards. These dirs are writable by the site user, so a root chown by path could be redirected to any file on the system by swapping in a symlink between the create and the chown. A create done as the site user can only reach what that user can reach anyway.

  • Read-only fallback for lock files. If opening a lock file for writing is refused (EACCES), it is opened read-only instead. flock(2) takes the same exclusive lock through a read-only descriptor. This covers root-owned lock files left by an earlier build.

  • Docs: the image section of the README, and a new "Running PHP as root" section in qdb/docs/usage.md.

Other things that can be created as root were checked and are not affected:

  • Shared-memory segments. Only qdbd writes them, and supervisord starts it as the site user.
  • Node link symlinks. Linux ignores a symlink's own permissions, and renaming or removing one depends only on the directory's permissions.

Behaviour change

php doctor started as root now runs as the owner of the site dir. A caller that needs doctor to write somewhere only root may write must set QUANTA_DOCTOR_AS_ROOT=1 and fix ownership itself.

This includes /docker-entrypoint.d/ hooks. They run before the entrypoint's ownership pass, so a hook that runs doctor on dirs this boot created as root needs the variable too.

Not covered

  • Other PHP run as root (php -r …, scripts) still writes its own files (caches, the class map, …) as root. Only doctor drops privileges, and only the extension's own files are created as the dir owner.
  • A lock dir that is already root-owned still refuses new lock files. One left by an older build in a container that is still running clears when the container restarts, because the entrypoint chowns /tmp/quanta_db on every start.

Testing

  • New conformance test qdb/tests/php/16_root_cli.php. It needs root and runs in fallback mode only; in daemon mode the harness would start qdbd as root, which production doesn't do. Root creates, rewrites and deletes nodes in a tree owned by an unprivileged user. The trashbin is on another filesystem (/dev/shm), so the delete exercises the copy path. Then a separate process running as that user (workers/app_user_writes.php):

    • maps the metrics arena;
    • rewrites the node root created, and creates a child in it;
    • creates a new node;
    • writes behind a root-owned 0644 lock file;
    • deletes into the trashbin root created.

    Against the extension in the published sha-02919b7d image, 8 of its 12 assertions fail. With this change all 12 pass.

  • New parity test qdb/tests/quanta/10_doctor_root.php, run in all three modes. A root doctor class_map on a site owned by www-data writes the class map and the doctor recipe as www-data. Doctor's output and exit status come through, and in the extension modes so do its -d options. QUANTA_DOCTOR_AS_ROOT=1 and a root-owned site both keep root. Against master's doctor, 2 of its 10 assertions fail.

  • Full suites on the rebuilt image with sh qdb/tests/run-in-docker.sh: conformance in fallback and daemon modes, parity in noext, fallback and daemon modes, plus nginx -t and php-fpm -t. All pass. cargo test: 168 passed.

  • End to end in the image, with supervisord running and qdbd as www-data:

    • As root via docker exec, ran php doctor localhost check and php -r writes (create, rewrite, delete) through the extension. Afterwards, find /tmp/quanta_db sites/localhost static ! -user www-data returns nothing.
    • Then chowned one lock file to root:root 0644 by hand. A www-data process rewrote the node root created, created a child in it, created a new node, wrote behind the root-owned lock file and deleted into the trashbin; all succeeded.
    • GET / returns 200.

php-fpm runs as the site's user, but a docker/kubectl exec runs as root,
and what PHP created there came out root-owned: the quanta_db lock dir
and lock files, the metrics arena, new node dirs and documents, the
trashbin dirs, and everything doctor writes. php-fpm then got EACCES on
every write that needed one of them, until someone chowned them back.

doctor started as root now switches to the owner of the site dir before
it boots, in the same process. QUANTA_DOCTOR_AS_ROOT=1 keeps root; the
entrypoint and quanta-build-assets set it, as they fix ownership
themselves.

The extension creates its files with the filesystem identity of the
owner of the directory they go in (setfsuid/setfsgid), not with a chown
afterwards, which a symlink swapped in between could redirect. A lock
file that cannot be opened for writing is opened read-only: flock works
the same on it.
@daylioti
daylioti merged commit 08db98e into master Nov 5, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant