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.