Skip to content
Blog

Safe Filesystem Sharing with Docker Bind Mounts: Flags, Permissions, and Security

Guide to sharing host files and directories with containers using bind mounts (-v vs --mount), enforcing read-only access (:ro), handling UID/GID permissions, and mitigating security risks.

Published on • November 17, 2026

AI Assistant

Sharing files between the host operating system and running Docker containers is a fundamental requirement for local development, configuration loading, and log collection. In Docker, Bind Mounts provide direct mapping of a file or directory from the host filesystem into a container’s target mount path.

However, improper use of bind mounts presents major security risks—including host file corruption, privilege escalation, and container escape vulnerabilities. This guide explains how bind mounts function, compares -v vs --mount, demonstrates read-only protection (:ro), and solves UID/GID permission sync issues.


What Is a Bind Mount?

A bind mount maps an exact host directory or file directly into the container’s mount namespace.

Host Filesystem                               Container Mount Namespace
┌──────────────────────────────┐              ┌──────────────────────────────┐
│ /home/user/project/src       │              │ /app/src                     │
│  ├─ index.js                 │ ───────────► │  ├─ index.js                 │
│  └─ package.json             │ (Bind Mount) │  └─ package.json             │
└──────────────────────────────┘              └──────────────────────────────┘

Key Characteristics of Bind Mounts

  • Performance: Direct access to host storage with zero virtualization overhead.
  • Immediate Synchronization: Modifications made on the host appear inside the container instantly, and vice-versa.
  • Host Path Reliance: Bind mounts rely on specific absolute directory paths on the host system.

-v (--volume) vs. --mount: Syntax and Differences

Docker offers two CLI flags for creating bind mounts: the legacy -v (--volume) flag and the modern --mount flag.

Option 1: Legacy -v / --volume Syntax

docker run -d --name web-dev \
  -v /home/user/project/src:/app/src \
  node:20-alpine
docker run -d --name web-dev \
  --mount type=bind,source=/home/user/project/src,target=/app/src \
  node:20-alpine

Comparison Matrix

Feature-v / --volume--mount
Syntax StyleConcise string (host_path:container_path:options).Explicit key-value pairs (type=bind,source=...,target=...).
Non-Existent Host Path BehaviorAutomatically creates a directory on host if path does not exist.Throws an explicit error if host path is missing.
ReadabilityObscure when combining multiple options.Highly readable and clear in documentation/scripts.
Bind PropagationLimited propagation configuration.Explicit bind propagation (rslave, private, shared).

⚠️ Caution with -v: If you misspell a host file path with -v (e.g. -v /etc/myconfig.conf:/app/config.conf), Docker creates /etc/myconfig.conf as a directory on your host, leading to silent bugs. --mount fails immediately with an error, making it safer for production scripts.


Enforcing Read-Only Protection (:ro / readonly)

By default, bind mounts grant containers read-write (rw) access to host files. If a container process is compromised, an attacker can modify, overwrite, or delete sensitive files on the host filesystem.

To protect host files, mount directories as read-only:

Using -v with :ro

docker run -d --name secure-web \
  -v /etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
  nginx:alpine

Using --mount with readonly

docker run -d --name secure-web \
  --mount type=bind,source=/etc/nginx/nginx.conf,target=/etc/nginx/nginx.conf,readonly \
  nginx:alpine

If a process inside the container attempts to modify /etc/nginx/nginx.conf, the Linux kernel rejects the operation with Read-only file system.


UID/GID File Permission Sync and Conflicts

A frequent issue with bind mounts is file ownership mismatch between the host user and the container user.

Understanding the Permission Conflict

Linux permissions rely on integer User IDs (UID) and Group IDs (GID), not username strings.

Host System User:   username="developer" (UID 1000, GID 1000)
Container User:     username="node"      (UID 1000, GID 1000) ──► MATCH (Read/Write OK)

Host System User:   username="developer" (UID 1000, GID 1000)
Container User:     username="root"      (UID 0, GID 0)       ──► Creates host files owned by ROOT

If a container running as root (UID 0) creates a file inside a bind-mounted directory, that file is owned by root on the host. The host user (UID 1000) cannot edit or delete the file without sudo.

Solutions for Permission Synchronization

Solution 1: Match Container UID/GID to Host User

Pass the host user’s UID and GID at container startup using --user:

docker run -d --name app-dev \
  --user $(id -u):$(id -g) \
  -v $(pwd):/app \
  node:20-alpine

Solution 2: Configure Dockerfile USER and Build Args

Pass build arguments matching the developer’s host user ID:

FROM node:20-alpine

ARG USER_ID=1000
ARG GROUP_ID=1000

# Update node user UID/GID to match host
RUN apk add --no-cache shadow \
    && usermod -u ${USER_ID} node \
    && groupmod -g ${GROUP_ID} node

USER node
WORKDIR /app

High-Risk Bind Mount Traps to Avoid

Never mount critical system directories into unprivileged containers:

  1. Never mount Docker Socket (/var/run/docker.sock) unless essential: Mounting the Docker control socket gives a container root-equivalent access to the entire host machine.
  2. Never bind mount / or /etc with read-write access: Mounting host root allows processes inside containers to rewrite system binaries or install host backdoors.
  3. Be careful with symlinks: Bind mounts follow host symlinks. Mounting paths containing unresolved symlinks can inadvertently expose unintended host directories.

Docker Compose Example: Safe Bind Mounts

services:
  web:
    image: nginx:alpine
    user: "1000:1000"
    ports:
      - "8080:80"
    volumes:
      # Application static assets (read-only mount)
      - type: bind
        source: ./html
        target: /usr/share/nginx/html
        read_only: true
      # NGINX configuration file (read-only mount)
      - type: bind
        source: ./nginx.conf
        target: /etc/nginx/nginx.conf
        read_only: true

Takeaway:

Bind mounts allow seamless filesystem sharing between host systems and containers. Prefer the explicit --mount type=bind syntax over -v to prevent accidental auto-creation of missing directories. Always append readonly (:ro) when mounting configuration files or code assets, and align container UIDs/GIDs (--user $(id -u):$(id -g)) to avoid host file ownership conflicts.


Sources