Run the Docker image as a non-root user

[gaul]

The Docker image currently runs everything as root. With #401 complete (jlink-trimmed JRE, #993), the remaining obvious hardening gap is dropping root: container scanners flag it (CIS Docker Benchmark 4.1), and the Kubernetes restricted Pod Security Standard rejects root images unless deployments override runAsUser. Non-root was deliberately deferred from the #993 review as out of scope, and it changes long-standing defaults, so filing this to collect feedback before committing to an approach.

Current behavior

• dumb-init, run-docker-container.sh, and java all run as uid 0.
• The default S3PROXY_ENDPOINT=http://0.0.0.0:80 binds a privileged port.
• The run script creates JCLOUDS_FILESYSTEM_BASEDIR (default /data) at startup, which works only because root may create directories under /.

Proposal

1. Create a dedicated s3proxy user and group with a fixed, documented uid/gid and add a numeric USER <uid>:<gid> (numeric so Kubernetes runAsNonRoot validates without an explicit runAsUser).
2. Change the default endpoint to http://0.0.0.0:8080, EXPOSE 8080, and use 8443 in the secure-endpoint examples.
3. Pre-create /data in the Dockerfile owned by that user, keeping the script's mkdir as a best-effort for custom basedirs.

Breaking changes and workarounds

1. Default port moves from 80 to 8080. Existing docker run --publish x:80 invocations, compose files, Kubernetes Services with containerPort: 80, and health checks must switch to port 8080. Workarounds:

• Update the mapping (--publish 80:8080 preserves the same host-side port), or
• Keep the old behavior with --env S3PROXY_ENDPOINT=http://0.0.0.0:80. Binding port 80 as non-root actually works on Docker ≥ 20.10 and rootless Podman because they set net.ipv4.ip_unprivileged_port_start=0 inside the container. It does not work on Kubernetes with containerd/CRI-O defaults; there you would additionally set that sysctl via securityContext.sysctls (allowed as a safe sysctl in recent Kubernetes) or fall back to --user root.

2. /data ownership. Bind mounts (--volume /host/dir:/data) whose host directory is owned by root or another uid will fail with permission errors. Named Docker volumes populated after this change inherit the image ownership and work; volumes created by older versions keep root ownership. Workarounds: chown the host directory to the documented uid, run with --user $(id -u) so the container matches the host owner, use Podman's :U volume flag or --userns=keep-id, or set fsGroup in the Kubernetes pod spec and let the kubelet fix ownership.

3. Derived images. Anything building FROM this image and running apt-get or writing to /opt/s3proxy must insert USER root before those steps (and ideally switch back afterwards). Files COPYed into derived images need to be readable by the s3proxy uid.

4. Mounted keystores and configs. A keystore for S3PROXY_SECURE_ENDPOINT (or any mounted config) must be readable by the non-root uid; previously root could read any mounted file. Workaround: chmod/chown the mounted file, or --user root.

In all cases --user root (or runAsUser: 0) restores the exact old behavior, so nothing is unfixable, but every workaround is action required from existing users, which is why this should land with a prominent release note, likely in a major version.

Alternatives considered

• Keep root as the default and only document --user. Non-breaking, but running with --user today fails anyway because /data cannot be created and port 80 cannot be bound in some runtimes, so the image changes (pre-created /data, higher default port) are needed regardless; at that point the remaining difference is just whether USER is the default.
• Publish a parallel -nonroot tag (as nginx does with nginx-unprivileged, or distroless with :nonroot). Zero breakage and lets users opt in, at the cost of a second image variant to build, test, and document. Could also serve as a transition period before flipping the default.
• setcap cap_net_bind_service on the java launcher to keep port 80. Rejected: setcap puts the binary in secure-execution mode, which disables the $ORIGIN RPATH the JVM uses to locate libjli, and file capabilities are unreliable across image copy/flatten steps.

Open questions

1. Which uid? ubuntu:24.04+ base images already reserve uid 1000 for the stock ubuntu user, so the choice is roughly: reuse ubuntu (uid 1000, convenient for bind mounts matching the common first host user), delete it and create s3proxy as 1000, use a system uid (999), or follow the distroless convention (65532).
2. Flip the default in the next major release, or start with a -nonroot tag and flip later?
3. Is 8080 the right default port, or is there a strong reason to prefer another (e.g. 9000 as MinIO users expect)?

Comments welcome, especially from anyone running the image on Kubernetes or building derived images.

[gaul]

@toindev FYI

[BASKARUNIBASKARRAJU]

Hi @gaul , I’d be interested in working on this issue as an external contributor.

I’ve gone through the current behavior and the proposed approach, particularly the non-root user, /data ownership, and the change from port 80 to 8080.

I’d be happy to investigate and implement the changes, including updating the Docker image, handling the filesystem permissions, updating the relevant tests/documentation, and verifying the resulting image behavior.

Before I start working on it, could you confirm whether you’d be open to an external contributor taking this up? Also, if you have a preferred direction for the open questions around the UID/GID and whether this should initially be a -nonroot image or become the default in the next major release, I’d be happy to follow that direction.

Thanks!

[gaul]

I am happy to merge a contributor request. However this seems to require breaking user configurations so I want to understand the tradeoffs and how we can minimize the pain. Could you investigate and explain the options beyond the issue description?

[BASKARUNIBASKARRAJU]

Thanks @gaul — here's the investigation you asked for. I've gone through the Dockerfile, the container start script, and the Kubernetes manifests to ground this in the current behavior.

Why it runs as root today

It comes down to one root cause: the default endpoint binds a privileged port, http://0.0.0.0:80. Binding a port below 1024 needs root (or NET_BIND_SERVICE), so the image has no USER directive. Two related consequences:

• The start script does mkdir "${JCLOUDS_FILESYSTEM_BASEDIR}" (/data) at runtime, which only works because root can write to / — and it runs even for cloud backends that never use the filesystem.
• The k8s manifests already work around this: they drop all capabilities except NET_BIND_SERVICE with a comment pointing at this issue, and the README notes that full Pod Security Standards restricted compliance still needs a non-root image.

Fix the port and pre-create /data, and non-root falls out.

What actually breaks, ranked by blast radius

1. Port 80 → 8080 (widest). Anything naming the port must change: docker run -p 80:80, k8s containerPort/Service port, reverse-proxy upstreams, healthchecks. Even the CI smoke test maps host 8080 → container 80.
2. /data ownership. A non-root uid can't mkdir /data or write to a bind-mount/PVC whose contents are root-owned. Existing volumes need a one-time chown or a k8s fsGroup.
3. Derived images. FROM andrewgaul/s3proxy images running apt/apk now need USER root before and USER s3proxy after.
4. Mounted keystores must be readable by the new uid.

Open questions

UID/GID: 1000 collides with host uid 1000 on bind mounts; 999 is arbitrary; 65532 (distroless nonroot) is the de-facto container convention, collision-unlikely, and pairs naturally with runAsNonRoot: true / runAsUser: 65532. I'd assign 65532 and document it as a stable contract.

Port: 9000 collides with MinIO/PHP-FPM/SonarQube. 8080 is already what the non-Docker docs use (README, SFTP), so it's the consistent pick.

Rollout — the crux of your question:

• Option A — gradual -nonroot tag. Publish :<version>-nonroot alongside the root default; flip the default at a future major.
  • Pros: zero forced breakage, opt-in, real deprecation window.
  • Cons: two images to build/scan/publish indefinitely; the default image stays insecure; the eventual flip is still a big-bang — it defers the pain rather than removing it.
• Option B — flip the default at the next major (5.0).
  • Pros: one image; secure default; a major bump is the sanctioned place for breaking changes, so it respects semver and user expectations; the workaround comments in the manifests get deleted in one clean commit.
  • Cons: every Docker/k8s user acts once when they adopt 5.0.

(The "document --user only" alternative I'd reject: it leaves the default insecure and, because of the runtime mkdir, --user alone actually breaks the current image.)

Recommendation

Option B — flip the default at 5.0, with the migration made as painless as the format allows. A major version is exactly where users expect breaking changes and read release notes, so it charges the cost once, at the cheapest moment. Option A defers the same breakage while doubling maintenance forever and leaves the default image insecure — the very thing this issue is about. The blast radius here is bounded and mechanical (a port number and a chown), which is easy to document.

Concretely I'd ship with B:

• Pre-create /data owned by 65532 in the Dockerfile and drop the runtime mkdir (this also lets cloud-backend pods keep readOnlyRootFilesystem: true without an emptyDir hack).
• Default endpoint → :8080, EXPOSE 8080 443, add USER s3proxy (65532).
• Update both k8s manifests: runAsNonRoot: true, runAsUser: 65532, fsGroup: 65532, drop NET_BIND_SERVICE, repoint ports to 8080, remove the issue-Run the Docker image as a non-root user #1121 comments.
• Update the CI smoke test to publish :8080 and assert the process runs as 65532 (guards against regressions).
• Add a "Migrating to 5.0" README section: repoint 80→8080; chown -R 65532:65532 existing /data (or set fsGroup); USER root/USER s3proxy around apt in derived images; keystores readable by 65532. Note --publish 80:8080 as an escape hatch for anyone who must keep port 80 externally.

No Java changes — the app binds whatever endpoint it's given; the port is purely a packaging default.

If you'd rather avoid any forced change even at a major, I'm happy to do Option A instead — but framed as a time-boxed deprecation (ship -nonroot now, announce the default flip at a named major), not an indefinite dual image. Let me know which direction you prefer and I'll open a PR.