CL-0007: read_only — fixing “Read-only file system” errors¶
Severity: LOW (how it is derived)
The service's root filesystem is writable, so an attacker with code execution
can change its binaries and configuration or add tools. Set read_only: true
and give the paths the application writes a tmpfs (scratch) or a named volume
(data that must survive).
Fix¶
services:
web:
image: nginx:1.27-alpine
read_only: true
tmpfs:
- /run
- /var/cache/nginx
- /tmp # docker diff shows no write here; harmless to keep
- Find what the service writes. Run it as it is, exercise what it does, and list what changed in its writable layer:
docker compose up -d web
docker diff $(docker compose ps -q web)
# C /etc/nginx/conf.d/default.conf
# A /run/nginx.pid
# A /var/cache/nginx/client_temp
# ... (C = changed, A = added; output trimmed)
Each directory there needs a tmpfs: entry (scratch data) or a named
volume (data that must survive a restart). Skip paths that are mount
targets, such as /run/secrets for a Compose secret: the runtime created
them, and they stay writable or read-only as mounted.
Writable-path discovery and
Reading the failure cover the choice.
- Turn it on and restart.
fixcan write theread_only: trueline. It does not write thetmpfs:list from step 1, so add that first; it warns, because the key alone breaks an image that writes to its root filesystem:
compose-lint fix --only CL-0007 compose.yaml # show the diff
compose-lint fix --only CL-0007 --apply compose.yaml # write it
⚠ behavior-changing · CL-0007: read_only: true breaks the container if it writes to its root filesystem; declare writable paths via tmpfs/volumes first.
docker compose up -d web
docker compose logs web | grep -i 'read-only'
For nginx this prints one harmless line: the entrypoint cannot add the
IPv6 listener to default.conf
(can not modify /etc/nginx/conf.d/default.conf (read-only file system?),
captured on Docker 29.7.2, not CI-asserted), so nginx listens on IPv4 only. Bake the config into the image if you need
IPv6. Anything else there is a path still missing from the list.
- Check the root filesystem refuses writes:
docker compose exec web touch /probe
# touch: /probe: Read-only file system
Then exercise the service, not only its startup: applications often catch a write failure and carry on with a feature quietly off.
- Check the finding is gone:
compose-lint -q compose.yaml | grep CL-0007 # prints nothing once fixed
Verified against Docker 29.7.2: nginx:1.27-alpine with this list, and
nginxinc/nginx-unprivileged:1.27 with the list under
Hardened non-root images, both serve requests and
survive a restart.
Common writable paths applications may need:
- /tmp — temporary files
- /run — PID files and sockets
- /var/log — application logs (prefer stdout/stderr instead)
- Application-specific cache directories
Tested on: Docker 29.7.2 with Compose 5.5.0, on a host without AppArmor (Yama ptrace_scope 1); the Fix steps above were re-run there in October 2026. Not tested: an AppArmor or SELinux host; the valkey image.
Compatibility¶
read_only: true is an advanced hardening step. Most images write to paths beyond /tmp and /run at startup, and the minimal tmpfs list above is rarely sufficient on its own.
Observed failure modes:
- Images that write state or registry files under image-specific paths (e.g.
netdatawrites to/etc/netdata/.container-hostnameand/var/lib/netdata/registry). - Entrypoints that
chowna directory on first boot. On a read-only rootfschownfails unless the target path is on a writable mount (and theCHOWNcapability is retained). An image that declares the directory as aVOLUMEgets a writable anonymous volume there and is unaffected:redis:7-alpine(VOLUME /data) starts underread_only: truewith no extra mount. - Applications that rewrite their own config at startup (some exporters, some TLS-fetching sidecars).
Writable-path discovery¶
- Run the service without
read_onlyand let it reach a steady state — exercise its real functionality, not just startup. - Inspect what was written:
docker diff <container>
read_only blocks exactly the writable-layer writes docker diff records, so the diff is a near-complete preview of what will break. (Volume paths don't appear in it — they stay writable under read_only anyway.)
3. Add each written path as a tmpfs entry (ephemeral data) or a named volume (persistent data) using the table below.
4. Enable read_only: true, restart, and re-verify function, not just startup: applications routinely catch a write failure and continue with the feature silently disabled (caching off, uploads rejected, temp exports failing), so read the logs and exercise the service before calling it done.
If the entrypoint runs chown, either pre-own the mount as the target UID:GID in the image build, or drop that specific service from the rule scope.
Reading the failure¶
A blocked write surfaces as Read-only file system (EROFS) in the container logs, naming the path — the remedy follows from what kind of path it is. The busybox wordings below are re-proven against a live container on every CI run (scripts/validate_rule_premises.py: the write must fail under read_only: true with this message and succeed with the mapped remedy); coreutils variants were captured live from a Debian container but are not CI-asserted.
| Symptom in logs (verbatim) | Path type | Remedy |
|---|---|---|
touch: /tmp/scratch: Read-only file system (busybox) · touch: cannot touch '/run/app.pid': Read-only file system (coreutils) |
ephemeral runtime state: PID files, sockets, scratch space | tmpfs: entry for the directory |
mkdir: can't create directory '/var/cache/': Read-only file system (busybox) · mkdir: cannot create directory '/var/cache/app': Read-only file system (coreutils) |
caches | tmpfs:, or a named volume if a warm cache across restarts matters |
can't create /etc/…: Read-only file system from the entrypoint shell (busybox; 1.38 prefixes sh: line 0:) |
config rewritten at startup | named volume for that path, pre-render the config in the image build, or accept that read_only doesn't fit this image and suppress with a documented reason |
| any EROFS under a data directory (database files, uploads) | persistent application data | named volume — never tmpfs. Named volumes stay writable under read_only (CI-proven). A tmpfs here runs green until the first restart, then silently erases the data |
nginx: [emerg] open() "/run/nginx.pid" failed (30: Read-only file system) · nginx: [emerg] mkdir() "/var/cache/nginx/client_temp" failed (30: Read-only file system) (nginx; captured on Docker 29.7.2, not CI-asserted). Other programs print their own wording; (30: …) is errno 30, EROFS |
the program's runtime or cache path | tmpfs: entry for the named directory |
No such file or directory on a path the app would normally create at startup |
directory absent from the image and rootfs unwritable — the EROFS is masked by the failed mkdir |
a tmpfs: entry both creates the mount point and makes it writable |
The last two rows are the traps: the naive fix — "add whatever path the error names as tmpfs" — is exactly wrong for persistent data, and its failure mode is invisible until a restart; and a missing-directory error under read_only is usually this rule's breakage wearing a different message.
Hardened non-root images¶
An image built to run as a non-root user is not automatically read-only-ready — it typically still writes to paths its uid owns (caches, PID files, runtime state). The two hardening steps are independent: non-root limits who the process is, read_only limits where it can write, and the second still needs the writable paths declared. The same recipe applies — ephemeral writes to tmpfs, persistent writes to a named volume, docker diff to discover the paths:
services:
web:
image: nginxinc/nginx-unprivileged:1.27 # runs as uid 101
read_only: true
tmpfs:
- /tmp # every write this image makes is under /tmp
What it detects¶
Any service that does not set read_only: true, including services that omit the key entirely or set read_only: false.
The fixer refuses one shape it could otherwise edit: a service that sets
use_api_socket: true. Compose copies that key's registry-credentials file
into the root filesystem rather than mounting it, and refuses to create it in
a read-only service (cannot create config "" in read-only service, measured
on Compose v5.0.0), so the inserted line would lint clean and fail up. Such
a service cannot take this hardening until the key is gone, which is
CL-0031's finding; the refusal says so on stderr.
Why it matters¶
A writable root filesystem allows an attacker who gains code execution inside a container to:
- Modify application binaries to inject backdoors
- Install additional attack tools (curl, wget, netcat)
- Modify configuration files to weaken security settings
A read-only filesystem forces the application to use only explicitly declared writable paths, limiting what an attacker can modify.
What it does not cover: persistence through a volume. Named volumes and bind mounts stay writable under read_only: true — that is the whole point of declaring them — so anything an attacker writes there survives a restart regardless of this setting. _t7_volume_writable asserts exactly that on every CI run. An earlier revision of this page listed "persist malware that survives container restarts (if using bind mounts or named volumes)" as something read_only prevents; it named the two cases the setting specifically does not reach. read_only narrows persistence to the paths you chose to make writable; it does not eliminate it.
ATT&CK coverage¶
No adversary technique maps to this rule. That is a finding about the rule, not an omission: a read-only root filesystem is defence in depth that denies an attacker somewhere to stage tools, which is indirect enough that naming a technique would overstate the link.
See also¶
- Hardening guide, step 6 — where this rule fits when hardening a whole file
- Docker best practices: read-only containers (ploetzli)
- netdata read-only filesystem discussion
Severity derivation¶
Derivation (see severity model):
- Baseline: A — the attacker already has code execution in this container, as the workload uid
- Precondition: Removes a mitigation — a writable rootfs grants no new privilege. It removes a constraint on what an attacker who already has code execution can leave behind
- Impact: Single container — writes land in this container's own writable layer
- Qualifier/modifier: none
- Derived: Removes a mitigation × Single container = LOW
- Shipped: LOW
- Evidence:
_cl0007(the rootfs is writable by default) and_t7_volume_writable(a named volume stays writable underread_only, which is why persistence through a volume is out of this rule's reach)
References: - OWASP Docker Security Rule #8 - CIS Docker Benchmark 5.13 — Ensure that the container's root filesystem is mounted as read only
A reference means the rule relates to that source. It does not mean a file with no finding complies with it. The CIS, OWASP and ATT&CK mapping for every rule, and the tags SARIF output carries for it, are on Standards mapping.