User namespace remapping in Docker - Commands & Configuration

Introduction

User namespace remapping helps improve security by making container users different from host users. This stops containers from having full control over the host system even if they break out.

When you want to run containers but limit their access to the host system users.

When multiple users share the same Docker host and you want to isolate their containers.

When you want to reduce risks of privilege escalation from containers to the host.

When running untrusted or third-party container images on your server.

When you want to comply with security policies that require user separation.

Config File - daemon.json

daemon.json

{
  "userns-remap": "default"
}

This configuration file enables user namespace remapping globally for Docker daemon.

userns-remap: "default" tells Docker to map container root user to an unprivileged user on the host, usually dockremap.

This improves security by isolating container users from host users.

Commands

Restart Docker daemon to apply the user namespace remapping configuration.

Terminal

sudo systemctl restart docker

Expected Output

No output (command runs silently)

Check if user namespace remapping is enabled by looking for the Userns field in Docker info.

Terminal

docker info | grep 'Userns'

Expected Output

Userns Mode: default

Run a test container to verify the user namespace remapping is working by entering the container shell.

Terminal

docker run --rm -it alpine sh

Expected Output

# id

uid=0(root) gid=0(root)

Check on the host if the dockremap user is used for remapping container processes.

Terminal

ps aux | grep dockremap

Expected Output

dockremap  12345  0.0  0.1  123456  2345 ?  Ss   10:00   0:00 /usr/bin/containerd-shim

Key Concept

If you remember nothing else from this pattern, remember: user namespace remapping isolates container users from host users to improve security.

Common Mistakes

Not restarting the Docker daemon after changing the daemon.json file.

The new user namespace remapping settings won't take effect until Docker restarts.

Always restart Docker with 'sudo systemctl restart docker' after editing daemon.json.

Expecting container root user to have the same privileges as host root.

User namespace remapping maps container root to an unprivileged host user, so permissions differ.

Understand container root is isolated and does not have full host root privileges.

Using user namespace remapping without configuring subuid and subgid for the dockremap user.

Without proper subuid/subgid ranges, remapping will fail or cause permission errors.

Ensure /etc/subuid and /etc/subgid have entries for dockremap user with valid ranges.

Summary

Edit daemon.json to add 'userns-remap': 'default' to enable user namespace remapping.

Restart Docker daemon to apply the changes.

Verify remapping is active using 'docker info' and running test containers.

User namespace remapping improves security by isolating container users from host users.

Practice

1.

What is the main purpose of user namespace remapping in Docker?

easy

A. To allow containers to use more CPU cores

B. To increase container startup speed

C. To enable automatic container backups

D. To improve security by isolating container user IDs from host user IDs

Solution

1. Step 1: Understand user namespace remapping concept

   User namespace remapping changes container user IDs so they do not match host user IDs.

2. Step 2: Identify the security benefit

   This isolation reduces risk if a container is compromised, protecting the host system.

3. Final Answer:

   To improve security by isolating container user IDs from host user IDs -> Option D

4. Quick Check:

   User namespace remapping = security isolation [OK]

Hint: User namespace remapping isolates users for security [OK]

Common Mistakes:

• Thinking it improves performance
• Confusing with resource limits
• Assuming it enables backups

2.

Which of the following is the correct way to enable user namespace remapping in Docker's daemon.json file?

{
  "userns-remap": "default"
}

easy

A. { "userns-remap": true }

B. { "userns-remap": "enabled" }

C. { "userns-remap": "default" }

D. { "userns-remap": 1 }

Solution

1. Step 1: Check Docker daemon configuration syntax

   The correct key is "userns-remap" and it expects a string value like "default" or a username.

2. Step 2: Validate options

   Only { "userns-remap": "default" } uses the correct key and a valid string value "default".

3. Final Answer:

   { "userns-remap": "default" } -> Option C

4. Quick Check:

   Correct key and string value = { "userns-remap": "default" } [OK]

Hint: Use string "default" for userns-remap in daemon.json [OK]

Common Mistakes:

• Using boolean true instead of string
• Using numeric values
• Using invalid strings like "enabled"

3.

Given Docker daemon configured with "userns-remap": "default", what will be the output of id -u inside a container run as root?

medium

A. 100000

B. 0

C. 65534

D. 1

Solution

1. Step 1: Understand user ID remapping

   When user namespace remapping is enabled, the container runs in its own user namespace where root is UID 0 inside the container.

2. Step 2: Identify the output of id -u inside container

   Inside the container, id -u for the root user reports 0, as it views UIDs from the container's namespace perspective. The host sees the remapped UID (e.g., 100000).

3. Final Answer:

   0 -> Option B

4. Quick Check:

   id -u inside container shows 0 for root [OK]

Hint: Inside container, root UID is 0 despite host remapping [OK]

Common Mistakes:

• Confusing container-internal UID (0) with host-remapped UID (100000)
• Thinking remapping changes UID view inside container
• Choosing 65534 which is nobody user

4.

You enabled user namespace remapping in Docker but containers fail to start with permission errors. What is the most likely cause?

medium

A. The remapped user IDs do not have permission on container files

B. Docker daemon.json syntax is incorrect

C. Containers are using too much CPU

D. Docker version does not support user namespaces

Solution

1. Step 1: Analyze permission errors after enabling userns-remap

   User namespace remapping changes container user IDs, so files owned by root on host may not be accessible by remapped IDs.

2. Step 2: Identify cause of permission failure

   If the remapped user IDs lack permissions on container files or volumes, containers fail to start with permission denied errors.

3. Final Answer:

   The remapped user IDs do not have permission on container files -> Option A

4. Quick Check:

   Permission errors = remapped UID lacks file access [OK]

Hint: Check file permissions for remapped user IDs [OK]

Common Mistakes:

• Blaming daemon.json syntax without checking logs
• Assuming CPU limits cause permission errors
• Ignoring Docker version compatibility

5.

You want to run a container with user namespace remapping but need the container's root user to have access to a host directory /data. What is the best way to configure this?

hard

A. Change ownership of /data on host to the remapped UID range

B. Disable user namespace remapping for this container

C. Run the container as a non-root user

D. Mount /data as read-only volume

Solution

1. Step 1: Understand user namespace remapping effect on file access

   With remapping, container root maps to a high UID on host, so host files must be owned or accessible by that UID.

2. Step 2: Adjust host directory ownership

   Changing /data ownership to the remapped UID range allows container root to access it safely without disabling remapping.

3. Final Answer:

   Change ownership of /data on host to the remapped UID range -> Option A

4. Quick Check:

   Host directory ownership matches remapped UID for access [OK]

Hint: Match host directory ownership to remapped UID [OK]

Common Mistakes:

• Disabling remapping loses security benefits
• Running as non-root may not solve access needs
• Mounting read-only prevents write access