Skip to content

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
  1. 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.

  1. Turn it on and restart. fix can write the read_only: true line. It does not write the tmpfs: 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.

  1. 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.

  1. 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. netdata writes to /etc/netdata/.container-hostname and /var/lib/netdata/registry).
  • Entrypoints that chown a directory on first boot. On a read-only rootfs chown fails unless the target path is on a writable mount (and the CHOWN capability is retained). An image that declares the directory as a VOLUME gets a writable anonymous volume there and is unaffected: redis:7-alpine (VOLUME /data) starts under read_only: true with no extra mount.
  • Applications that rewrite their own config at startup (some exporters, some TLS-fetching sidecars).

Writable-path discovery

  1. Run the service without read_only and let it reach a steady state — exercise its real functionality, not just startup.
  2. 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

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 under read_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.