Bind mounts — host paths in containers · Docker & Containers

A bind mount is a host directory mounted directly into the container. The container sees the host’s actual files; there is no Docker-managed storage layer.

Bind mounts are the most powerful and most dangerous storage primitive in Docker. Used well, they let the host and container share state. Used poorly, they are how an attacker breaks out of a container — and, more often, how a deployment silently starts serving nothing.

When to use bind mounts

Development. Mount your source tree into a container to iterate quickly. The container sees your edits without rebuilds.
Configuration. Mount a single config file to inject settings without rebuilding the image.
Host integration. Monitoring agents that must read real host state: /proc, /sys, a log directory.

When NOT to use bind mounts

Production data. Volumes are Docker-managed and portable; a bind mount ties the container to one host’s directory layout.
Multi-host deployments. Bind mounts are host-local. Schedule the container elsewhere and the path points at nothing — or worse, at something else.
Database data. Same reason, plus the ownership problems covered in the permissions lesson.

The failure that costs a night

A bind mount over a non-empty image directory shadows it, silently

This is the single most common bind-mount outage, and it produces no error anywhere.

The Docker documentation is explicit: “If you bind-mount a directory into a non-empty directory on the container, the directory’s existing contents are obscured by the bind mount.”

So -v /srv/app/config:/etc/nginx/conf.d does not add your config to nginx’s config directory. It replaces it. If /srv/app/config on the host is empty — because the deploy script has not run yet, because the path has a typo, because the directory is on a filesystem that failed to mount — nginx starts with an empty conf.d, falls back to the default server block, and serves the “Welcome to nginx” page to production.

The container is Up. The health check on port 80 passes, because nginx is answering. docker logs is clean. Every instinct says “the application is broken”, and the application never started.

Worse: with the -v short form, Docker creates the host directory if it does not exist. A typo in the source path does not fail; it creates an empty directory and mounts that. There is no signal at all.

The diagnosis is a one-liner, and it is worth putting in a runbook:

Read-only / Safewhat did the mount hide— Compare what the container sees at the mount point with what the image ships there.

CONTAINER=web
MOUNTPOINT=/etc/nginx/conf.d

# What the running container sees
docker exec "$CONTAINER" ls -la "$MOUNTPOINT"

# What the IMAGE has at that path, with no mounts in the way
IMAGE=$(docker inspect --format '{{.Config.Image}}' "$CONTAINER")
docker run --rm --entrypoint ls "$IMAGE" -la "$MOUNTPOINT"

If the first is empty and the second is not, the mount is the problem and the application is innocent.

Read-only / Safelist every mount— Every bind and volume attached to a container, with its host source.

CONTAINER=web
docker inspect --format '{{range .Mounts}}{{.Type}}  {{.Source}} -> {{.Destination}} (rw={{.RW}}){{"\n"}}{{end}}' "$CONTAINER"

Read-only / Safemounts output— The Source column is the host path. An empty source directory is invisible here — check it separately.

$ docker inspect --format '{{range .Mounts}}...{{end}}' web

bind  /srv/app/config -> /etc/nginx/conf.d (rw=true)
volume  /var/lib/docker/volumes/web-cache/_data -> /var/cache/nginx (rw=true)

Illustrative output

`-v` versus `--mount`

The two forms are not equivalent, and the difference is exactly the behaviour that hides the bug above.

	`-v` / `--volume`	`--mount`
Host path missing	Created as an empty directory	Error, container does not start
Syntax	Colon-separated positional	Comma-separated key=value
Ambiguity	`-v foo:/data` is a named volume; `-v ./foo:/data` is a bind	`type=bind` or `type=volume` is explicit
Creating the source deliberately	Always	Only with `bind-create-src`

# Fails loudly if /srv/app/config does not exist — which is what you want
docker run -d --name web \
  --mount type=bind,src=/srv/app/config,dst=/etc/nginx/conf.d,readonly \
  nginx:1.27

Use --mount for anything that runs unattended. The extra typing buys you a container that refuses to start rather than one that starts wrong.

There is no Docker in a bind mount

A bind mount is not a Docker feature at all. When the container starts, runc — following the mounts array in the OCI config.json — issues mount(2) with MS_BIND inside the container’s new mount namespace. The kernel makes the same inode visible at a second path.

Three consequences follow directly from that:

No translation layer. There is no copy, no metadata, no ownership mapping. The file the container writes is the host file, with the host’s inode, the host’s UID, and the host’s SELinux label. This is why UID mismatches bite here and not with a named volume that Docker created.

:ro is a mount flag, not a permission. It is MS_RDONLY on that mount, in that namespace. The host still has the path read-write, and so does any other container that mounted it without :ro.

Mount propagation is a real setting. By default the bind is rprivate: a filesystem mounted underneath the source path on the host after the container started is not visible to the container. That is why a container that bind-mounts /mnt/data sees an empty directory when /mnt/data is an NFS mount that came up late — the container is looking at the empty directory the NFS mount is covering on the host. bind-propagation=rslave propagates host-side mounts into the container and is the correct setting for monitoring agents that must see mounts appear.

SELinux labels

On SELinux-enforcing hosts (RHEL, CentOS Stream, Fedora, Rocky), a bind-mounted host path carries whatever label it already has, and the container’s container_t domain is not permitted to write it. The symptom is Permission denied on a path whose Unix permissions are obviously fine.

The :z and :Z suffixes tell Docker to relabel the source:

:z — label the content as shared between containers. Multiple containers can use the path.
:Z — label the content as private and unshared to this container. More restrictive, and it means no other container (and no host service) can use it.

docker run -v /srv/appdata:/data:z nginx:1.27

Never put :z or :Z on a system directory

The relabel is recursive and it writes to the host. :Z on a shared path is how you take a host service down: relabel /var/log with a container-private label and rsyslog can no longer write its own log directory.

The catastrophic version is :z or :Z on /, /usr, /etc or /home. Docker will walk the entire tree relabelling as it goes, the operation takes a very long time, and when it finishes the host is unbootable in enforcing mode. There is no undo other than restorecon -R over the whole filesystem, from a rescue environment.

Label directories you created for the container. Never label a directory the host also depends on. If you need shared access between a host service and a container, chcon a purpose-made subdirectory instead of relabelling the parent.

Note also that with Swarm services, :z, :Z and :ro on bind mounts are ignored — a genuine difference in behaviour between docker run and docker service create.

Security implications

Bind mounts bypass the container’s filesystem isolation. A container with / bind-mounted from the host can read any file its UID can read, modify any file its UID can write, and execute host binaries.

Without user-namespace remapping, a container running as root is UID 0 on the host. The container boundary for a bind-mounted path is the Unix permission check and nothing else.

What if a container bind-mounts `/`?

The container has the entire host filesystem at a path inside it, and if it runs as root, full write access to it. Writing /etc/shadow, /etc/sudoers, or a unit file into /etc/systemd/system are all one echo away, and none of them require --privileged or any capability beyond the default set.

--privileged is not what makes this dangerous; the bind mount is. --privileged removes the remaining device and capability restrictions and turns “full write access to the host filesystem” into “full control of the kernel”, but the filesystem was already gone.

This pattern shows up legitimately in rescue and provisioning containers, run interactively by an operator who understands it. It is never appropriate for a long-running workload. Mount the specific path the workload needs, readonly unless it must write, and audit the list with docker inspect --format '{{json .Mounts}}' in CI.

The Docker socket deserves its own mention. -v /var/run/docker.sock:/var/run/docker.sock is a bind mount, and it gives the container the ability to start another container with any mount and any privilege it likes. It is host root with extra steps. It has a dedicated lesson; treat it as a bind mount whose source happens to be an API.

Verifying a bind mount actually worked

“The container is running” is not verification. These two commands distinguish working from broken:

Read-only / Safeverify— Prove the content arrived and prove writability matches your intent.

CONTAINER=web
MOUNTPOINT=/etc/nginx/conf.d

# 1. The mount point is non-empty and holds what you expect
docker exec "$CONTAINER" find "$MOUNTPOINT" -maxdepth 1 -type f -printf '%p %s\n'

# 2. It is read-only if you asked for read-only.
#    Expect "Read-only file system" here, and treat success as the failure.
docker exec "$CONTAINER" touch "$MOUNTPOINT/.writetest" && echo 'WRITABLE - check your readonly flag' || echo 'read-only as intended'

The second check is the one that can fail usefully. A readonly flag that was silently dropped — because someone converted a --mount line back to -v and lost the :ro — leaves you with a container that can overwrite the config the host is managing.