Repository navigation
The image runs without root. Migration for a derived image or a deployment is
the numbered list below; the floating trixie-php* and latest tags point at
the non-root image from this release on.
Removed
- (2) The
APPLICATION_USER/UID/GROUP/GID/DIR/CHOWNvariables: they are
ignored, the entrypoint creates no user and changes no ownership at start.
Bake the ownership of writable paths into the image (named volumes copy the
mount point owner) or own the host dir by the process uid. - (3) The library functions
setup_userandexec_as_user, and
UNIT_LIB_NO_PROVISION: a hook that calls them fails at start with "command
not found". A hook runs as the container user already; it justexecs. - The immutable tag without a version:
trixie-1.37.2-2-php*stays the
root-based 0.3.0 image. - (12) bash in the entrypoint:
docker-entrypoint.sh, the library and the
healthcheck are portable POSIX sh (/bin/sh, dash in the image). A hook in
/docker-entrypoint-hook.dis sourced by it, so a bash hook (local,
[[ ]], arrays,declare -F) stops working: rewrite it in POSIX sh,
prefix its variables with<cmd>_(nolocal) and keep onlyhandle_<cmd>
functions,<cmd>of[A-Za-z0-9_]. The handler is looked up with
command -v.
Changed
- (1) The image starts as
nonroot(uid:gid65532:65532, home
/home/nonroot): tini, the entrypoint, the Unit master and the PHP workers
run as that user and need no capability (--cap-drop=ALL, nocap_add). A
derivedDockerfileneedsUSER 0:0beforeRUN apt-getand
USER 65532:65532at the end. Any other non-root uid:gid works when its
mounts are writable for it. - (4) Do not set
applications.*.user/groupin the Unit config: an
unprivileged Unit runs its workers as its own user (it logs a warning that it
cannot use arbitrary user and group). - (5) The Unit state dir is
/run/freeunit(was the compiled
/var/lib/freeunit); with a tmpfs at/runthe configuration from
/docker-entrypoint.dis applied on every container start. An explicit
freeunitd .../freeunitd-debug ...command gets the missing--no-daemon,
--control,--pid,--statedirand--tmpdirflags; one of the last four
with another value (e.g.--statedir /var/lib/freeunit) stops the start with
an error.--version/--help/-hrun as given, without initial
configuration. - (6) Unit buffers request bodies in
/tmp(--tmpdir /tmp), where PHP keeps
its uploads and temp files by default;session.save_pathis/tmpforcli
andembed(was the root-owned/var/lib/php/sessions)./tmpmust be
writable for the process uid; underread_onlymount a host dir there
(recommended) or a tmpfs with asize. - (7) Every writable path is a mount the process uid can write:
/run(tmpfs),
/tmp, and the application's own bind mounts. The entrypoint checks
/var/run, the state dir and/tmpbefore anything else and stops with a hint
naming the missing mount.HOME(/home/nonroot, empty, 0755) may stay
read-only; an application that writes there mounts it. - (8) A listener below port 1024 needs
net.ipv4.ip_unprivileged_port_start=0
(the Docker default since Engine 20.10). - (9) Started as root (
--user 0:0): the entrypoint hands stdio to 65532 and
re-execs itself as65532:65532with no supplementary groups and
no_new_privs, logging a warning; tini (PID 1) stays root in that mode.
It needs the default capabilities or at least
CAP_SETUID/CAP_SETGID/CAP_CHOWN/CAP_KILL; without them the start stops
with an error, as does a non-root uid with group 0. The healthcheck, run as
root then, probes as the owner of the control socket. - (10) The control socket, the state dir and the generated dir belong to the
same uid as the PHP workers: code execution in PHP can reconfigure Unit until
the container restarts. The unix socket rules out SSRF, not RCE. - (11) The immutable tags carry the image version:
trixie-<freeunit-release>-php<X.Y>-v<version>(e.g.
trixie-1.37.2-2-php8.4-v0.4.0),<version>-php<X.Y>and<version>. The
release workflow refuses to run when one of them exists and creates them
last, from the attested digest, after the floating tags. - The hook files in
/docker-entrypoint-hook.dare sourced as the container
user; they must still be root-owned and not group/world-writable. - Examples: no
user/groupin the Unit configs, nocap_add;devcreates
/dataowned by 65532 in itsDockerfileinstead ofAPPLICATION_CHOWN;
cron-hookexecs supercronic without a privilege drop;web-apprenders its
TLS bundle into$ENTRYPOINT_GENERATED_DIR.
Added
ENTRYPOINT_GENERATED_DIR(/run/docker-entrypoint.d, exported to the
/docker-entrypoint.d/*.shscripts): the*.pemand*.jsona script renders
there are applied after those of/docker-entrypoint.d(certificates of both
dirs before any config, the generated config last);*.shthere are not
executed.- Library functions
drop_root_or_die,prepare_runtime_dirs,
build_unit_launch_argsand the literalsUNIT_TMP_DIR,
UNIT_NONROOT_UID/GID/HOME. test/smoke.shruns every launch mode: hardened (--read-only --cap-drop=ALL), plain, root drop (also under-t) and its refusals, an
arbitrary uid, an explicitfreeunitdcommand.