User namespace remapping in Docker - Step-by-Step Execution

Process Flow - User namespace remapping

Docker daemon starts

↓

Check userns-remap config

↓

If enabled

→Map container user IDs to host user IDs

↓

Create subuid and subgid ranges

↓

Run container with remapped IDs

↓

Container user ID != Host user ID

↓

Improved host security

↓

End

Docker daemon checks if user namespace remapping is enabled, then maps container user IDs to different host user IDs to improve security.

Execution Sample

Docker

dockerd --userns-remap=default

docker run -it alpine id

Starts Docker daemon with user namespace remapping enabled, then runs a container to show user ID mapping.

Process Table

Step	Action	User ID in Container	Mapped Host User ID	Result
1	Docker daemon starts with --userns-remap=default	-	-	User namespace remapping enabled
2	Docker creates subuid and subgid ranges for remapping	-	-	Ranges assigned to dockremap user
3	Run container with 'id' command	0 (root inside container)	100000 (mapped host user)	Container root mapped to non-root host user
4	Container process runs as remapped user	1000 (normal user inside container)	101000 (mapped host user)	Normal user remapped accordingly
5	Container exits	-	-	User namespace remapping ends with container lifecycle

💡 Container stops; user namespace remapping applies only during container runtime

Status Tracker

Variable	Start	After Step 3	After Step 4	Final
Container User ID	-	0	1000	-
Mapped Host User ID	-	100000	101000	-
Docker Daemon State	No remap	Remap enabled	Remap enabled	Remap enabled

Key Moments - 3 Insights

Why does the container root user (ID 0) map to a high host user ID like 100000?

Because user namespace remapping shifts container user IDs to a safe range on the host to avoid running as real root, as shown in execution_table step 3.

Does the container user ID inside the container change when remapping is enabled?

No, inside the container the user IDs remain the same (e.g., 0 for root), but they map to different host IDs, as seen in execution_table steps 3 and 4.

What happens if user namespace remapping is not enabled?

Container user IDs map directly to the same host user IDs, meaning root in container is root on host, which is less secure. This is implied by the initial daemon state in variable_tracker.

Visual Quiz - 3 Questions

Look at the execution table at step 3: what is the mapped host user ID for container root user?

A 101000

B 0

C 100000

D 500

💡 Hint

Check the 'Mapped Host User ID' column at step 3 in the execution_table.

At which step does the container process run as a remapped normal user (ID 1000 inside container)?

A Step 3

B Step 4

C Step 2

D Step 5

💡 Hint

Look for '1000 (normal user inside container)' in the 'User ID in Container' column in execution_table.

If user namespace remapping was disabled, what would happen to the container root user ID mapping?

A It would remain as 0 on the host

B It would map to a high host user ID like 100000

C It would map to 101000

D It would map to 500

💡 Hint

Refer to key_moments about what happens without remapping and variable_tracker Docker Daemon State.

Concept Snapshot

User namespace remapping shifts container user IDs to different host IDs.
Enables running containers as root inside but non-root on host.
Configured via dockerd --userns-remap.
Improves host security by isolating container users.
Container user IDs stay same inside container.
Host sees remapped user IDs in a safe range.

Full Transcript

User namespace remapping in Docker lets the container run users like root inside, but maps those user IDs to different, non-root user IDs on the host. When Docker daemon starts with --userns-remap, it creates subuid and subgid ranges for remapping. For example, container root user ID 0 maps to host user ID 100000. This prevents containers from having real root privileges on the host, improving security. Inside the container, user IDs remain unchanged, but on the host they are shifted. This remapping applies only during container runtime and ends when the container stops.

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