User namespace remapping in Docker - Deep Dive

Overview - User namespace remapping

What is it?

User namespace remapping is a Docker security feature that changes the user IDs inside containers to different user IDs on the host system. This means the container's root user does not have root privileges on the host, reducing security risks. It helps isolate containers better by mapping container users to less privileged host users.

Why it matters

Without user namespace remapping, a container's root user has full root access on the host, which can lead to serious security problems if the container is compromised. This feature limits the damage a container can do, making Docker safer to run on shared or sensitive systems. It protects the host from accidental or malicious container actions.

Where it fits

Before learning user namespace remapping, you should understand basic Docker concepts like containers, images, and Linux user IDs. After this, you can explore advanced Docker security features like seccomp, AppArmor, and SELinux for layered protection.

Mental Model

Core Idea

User namespace remapping changes container user IDs to different host user IDs to isolate container privileges from the host system.

Think of it like...

It's like giving a guest a fake ID card that looks like a VIP pass inside a party but is actually a visitor badge outside, so they can't access restricted areas in the building.

Host System
┌─────────────────────────────┐
│ User IDs: 0 (root), 1000, 1001 │
│                             │
│  Container User IDs mapped  │
│  ┌───────────────┐          │
│  │ Container UID 0│──maps to │──> Host UID 100000 (non-root)
│  │ Container UID 1│──maps to │──> Host UID 100001
│  └───────────────┘          │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Linux User IDs

Concept: Learn what user IDs (UIDs) are and how Linux uses them to control permissions.

Every user on a Linux system has a unique number called a UID. The root user has UID 0 and has full control. Other users have higher UIDs with limited permissions. Processes run with these UIDs to determine what they can access.

Result

You know that UID 0 means root and that permissions depend on these numbers.

Understanding UIDs is key because user namespace remapping changes these IDs to control access.

2

Foundation

Docker Containers and User Isolation

Concept: Containers run processes with user IDs inside their own environment, but by default, these IDs match the host's IDs.

When you run a container, the root user inside it is UID 0, which is also root on the host. This means the container can potentially affect the host system if it escapes isolation.

Result

You see that container root is host root by default, which is risky.

Knowing this risk explains why we need user namespace remapping to separate container users from host users.

3

Intermediate

How User Namespace Remapping Works

🤔Before reading on: do you think remapping changes container UIDs or host UIDs? Commit to your answer.

Concept: User namespace remapping maps container UIDs to different host UIDs, so container root is not host root.

Docker creates a range of UIDs on the host that correspond to container UIDs. For example, container UID 0 maps to host UID 100000. This means inside the container, processes think they are root, but on the host, they run as a less privileged user.

Result

Container root cannot perform root actions on the host, improving security.

Understanding this mapping clarifies how containers stay isolated even if they run as root inside.

4

Intermediate

Configuring User Namespace Remapping

🤔Before reading on: do you think remapping is enabled by default or requires manual setup? Commit to your answer.

Concept: User namespace remapping must be enabled and configured in Docker's daemon settings.

You edit /etc/docker/daemon.json to add "userns-remap": "default" or specify a user. Then restart Docker. This sets up the UID mapping automatically. You can also customize the UID ranges in /etc/subuid and /etc/subgid files.

Result

Docker runs containers with remapped UIDs after restart.

Knowing how to enable remapping is essential to apply this security feature in practice.

5

Intermediate

Checking Remapping Status and Effects

Concept: Learn how to verify if remapping is active and see its impact on container processes.

Run 'docker info' and look for 'Userns' field. Run a container and check process UIDs on the host with 'ps' or 'ls -l' on container files. You will see host UIDs in the remapped range instead of 0.

Result

You confirm remapping is working and see how container root maps to a non-root host UID.

Being able to verify remapping helps troubleshoot and ensure security is applied.

6

Advanced

Limitations and Compatibility Issues

🤔Before reading on: do you think remapping affects all Docker features seamlessly? Commit to your answer.

Concept: User namespace remapping can cause issues with volume mounts, file permissions, and some Docker features.

Because container UIDs differ from host UIDs, files created by containers may have unexpected ownership on the host. Some volumes may not work properly. Certain Docker features like swarm mode do not support remapping well. You must plan and test carefully.

Result

You understand remapping is not a silver bullet and requires careful use.

Knowing these limits prevents surprises and helps design secure, functional container setups.

7

Expert

Advanced Security with Namespace Stacking

🤔Before reading on: do you think user namespace remapping alone fully isolates containers? Commit to your answer.

Concept: User namespace remapping can be combined with other namespaces and security features for stronger isolation.

Docker uses multiple namespaces: PID, network, mount, and user. Stacking user namespaces with others like seccomp and AppArmor creates layered defense. Experts tune these layers to balance security and usability. Understanding kernel internals helps optimize this setup.

Result

You see how remapping fits into a bigger security strategy.

Recognizing remapping as one layer among many helps build robust container security in production.

Under the Hood

Linux namespaces isolate system resources. The user namespace remaps UIDs and GIDs inside the container to a different range on the host. The kernel translates these IDs when processes access files or resources, so container root (UID 0) appears as a non-root UID on the host. This prevents container processes from gaining host root privileges.

Why designed this way?

Originally, containers shared host UIDs, risking host security if containers were compromised. User namespaces were introduced in Linux to allow containers to have their own user ID space, improving isolation without heavy virtualization. Docker adopted this to enhance container security while keeping performance.

┌─────────────────────────────┐
│        Host Kernel          │
│ ┌───────────────┐           │
│ │ User Namespace│           │
│ │  Mapping      │           │
│ │ Container UID0│──maps to──┼──> Host UID 100000 (non-root)
│ │ Container UID1│──maps to──┼──> Host UID 100001
│ └───────────────┘           │
│                             │
│ Processes see container UIDs│
│ Kernel translates to host UIDs│
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does user namespace remapping make container root the same as host root? Commit yes or no.

Common Belief: User namespace remapping means container root is still host root.

Reality: Container root is mapped to a non-root user on the host, so it does not have host root privileges.

Why it matters: Believing otherwise leads to ignoring remapping's security benefits and risking host compromise.

Quick: Is user namespace remapping enabled by default in Docker? Commit yes or no.

Common Belief: User namespace remapping is enabled by default in Docker installations.

Reality: It is disabled by default and must be manually enabled and configured.

Why it matters: Assuming it's enabled can cause false security confidence and unexpected permission issues.

Quick: Does user namespace remapping solve all container security problems? Commit yes or no.

Common Belief: User namespace remapping fully isolates containers and solves all security risks.

Reality: It improves security but does not replace other measures like seccomp, AppArmor, or SELinux.

Why it matters: Relying solely on remapping can leave containers vulnerable to other attack vectors.

Quick: Can user namespace remapping cause volume permission problems? Commit yes or no.

Common Belief: Remapping does not affect volume mounts or file permissions.

Reality: Remapping changes file ownership on volumes, which can cause permission errors if not handled.

Why it matters: Ignoring this leads to broken applications and confusing permission errors.

Expert Zone

1

User namespace remapping requires careful UID/GID range planning to avoid conflicts with host users and other containers.

2

Combining remapping with rootless Docker setups enhances security but adds complexity in networking and storage.

3

Some kernel versions have bugs or limitations in user namespace support that affect remapping reliability.

When NOT to use

Avoid user namespace remapping when using Docker Swarm or Kubernetes features that do not support it well. For simple isolated environments, rootless Docker or VM-based containers may be better alternatives.

Production Patterns

In production, remapping is often combined with read-only root filesystems, seccomp profiles, and AppArmor policies. Enterprises use custom UID ranges per project to prevent cross-container conflicts and audit mappings for compliance.

Connections

Linux Namespaces

User namespace remapping is a specific type of Linux namespace focused on user ID isolation.

Understanding Linux namespaces helps grasp how Docker isolates containers at multiple levels, not just users.

Rootless Docker

Rootless Docker builds on user namespace remapping to run Docker daemons without root privileges on the host.

Knowing remapping clarifies how rootless Docker achieves safer container management.

Access Control in Operating Systems

User namespace remapping is a form of access control that changes identity mapping to limit permissions.

This connects to broader security principles of least privilege and identity management in OS design.

Common Pitfalls

#1 Enabling user namespace remapping without adjusting volume permissions causes access errors.

Wrong approach:

Editing /etc/docker/daemon.json with {"userns-remap": "default"} but mounting host volumes without changing ownership.

Correct approach:

After enabling remapping, adjust volume ownership with chown to match remapped UIDs or use named volumes managed by Docker.

Root cause:

Misunderstanding that remapped UIDs change file ownership expectations on the host.

#2 Assuming user namespace remapping is active without checking Docker info.

Wrong approach:

Running containers expecting remapping security but not verifying with 'docker info' or inspecting process UIDs.

Correct approach:

Always verify remapping status with 'docker info' and test UID mappings on running containers.

Root cause:

Overlooking the need to confirm configuration changes take effect.

#3 Using user namespace remapping with Docker Swarm mode.

Wrong approach:

Enabling remapping and then deploying services with swarm, expecting full compatibility.

Correct approach:

Avoid remapping in swarm mode or use alternative isolation methods like rootless containers.

Root cause:

Not knowing swarm mode does not support user namespace remapping well.

Key Takeaways

User namespace remapping improves Docker security by mapping container root to a non-root host user.

It must be explicitly enabled and configured; it is not on by default.

Remapping changes file ownership and permissions, requiring careful volume management.

It is one layer of container security and should be combined with other protections.

Not all Docker features support remapping, so know its limits before using in production.