Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Rootless and Security

Rootless Podman and User Namespaces

Learn how rootless Podman maps container users to host users with user namespaces, subuid and subgid ranges, uid_map, podman unshare and the keep-id option.

Rootless is the feature that most often makes people choose Podman. Running containers as a normal user means that even if a program breaks out of its container, it has only the powers of that user. Nobody needs to hand out sudo, and no privileged daemon is waiting to be attacked.

The trick behind it is a Linux kernel feature called user namespaces. This lesson explains the idea with real numbers, so that file ownership surprises stop being surprises. If you understand the mapping in this lesson, you can predict the owner of any file a container creates.

Root in the container is you outside

A namespace gives a process its own view of something. A user namespace gives it its own view of user and group IDs. Inside the namespace, a process can be user 0 (root) and have root-like powers over things the namespace owns. Outside, the kernel maps that ID to some ordinary ID that has no special rights.

flowchart LR
    subgraph IN["Inside the container"]
        A["UID 0 (root)"]
        B["UID 1"]
        C["UID 1000"]
    end
    subgraph OUT["On the host (your UID is 1000)"]
        D["UID 1000 (you)"]
        E["UID 100000"]
        F["UID 100999"]
    end
    A --> D
    B --> E
    C --> F

Container root becomes you. Every other container user becomes a high, unused ID from your subordinate range.

The numbers come from /etc/subuid and /etc/subgid. A line like this:

TEXT
alice:100000:65536

gives the user alice 65,536 extra IDs starting at 100000. These are not real accounts, only reserved numbers. Podman uses them to fill the container's ID space.

The mapping table

The kernel stores the mapping in /proc/PID/uid_map, one line per range: inside start, outside start, length. You can look at what Podman built with podman unshare, which opens a shell (or runs a command) inside Podman's rootless user namespace:

Terminal
id -u                                   # your UID, say 1000
podman unshare cat /proc/self/uid_map

For alice (UID 1000, range 100000:65536) the table looks like this:

TEXT
         0       1000          1
         1     100000      65536

Read it as: container UID 0 maps to host UID 1000 (1 ID); container UIDs 1 to 65536 map to host UIDs 100000 to 165535. So the container user with UID 1000, such as node in many images, is host UID 100999 (100000 + 1000 - 1).

Here is a stand-in that computes this mapping in both directions. It is JavaScript, and it follows the table logic above.

JS Stand-in: uid_map calculator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last two lines are the key to permissions: a host user who is not in the map, like UID 2000, appears inside the container as the overflow user nobody (65534).

What this means for files

When the container's root creates a file in a mounted folder, the file is owned by you on the host. When a container user with UID 33 (www-data in Debian images) creates a file, the host sees owner 100032, a number that is not a real account.

Terminal
mkdir -p ~/demo
podman run --rm -v ~/demo:/data:Z docker.io/library/alpine:latest sh -c 'echo x > /data/by-root; chown 33:33 /data/by-root'
ls -ln ~/demo

by-root ends up with the owner ID 100032 on the host, because container UID 33 maps to 100000 + 33 - 1. You cannot edit it as yourself unless you step into the namespace:

Terminal
podman unshare ls -ln ~/demo        # shows owner 33 through the mapping
podman unshare chown 0:0 ~/demo/by-root   # make it yours (container root = you)

podman unshare is the tool for fixing ownership of data that a rootless container created or will use. It is your user, looking at the world the way containers do.

keep-id: your UID inside the container

Sometimes you want the container user to be you, for example when a development container edits your project files, and they must stay owned by you. Use --userns=keep-id:

Terminal
podman run --rm -it --userns=keep-id -v "$PWD:/work:Z" -w /work docker.io/library/alpine:latest sh -c 'id; touch made-here; ls -ln made-here'

With keep-id, your host UID (say 1000) is mapped to the same number inside the container, and the container runs as that user. The file made-here is owned by 1000 inside and outside. The other container IDs are mapped around it. Variants:

Option Effect
--userns=keep-id your UID stays your UID in the container; the process runs as you
--userns=keep-id:uid=1001,gid=1001 map your UID to a chosen ID inside the container
--userns=host no user namespace: the container uses the host's IDs (so root would be real root, only possible for root)
--userns=auto rootful only: Podman picks a private, non-overlapping range for each container
--userns=nomap do not map your own UID into the container at all (a stronger isolation)

Here is a stand-in that shows how keep-id changes the mapping compared with the default.

JS Stand-in: default versus keep-id

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The sample prints the idea of the tables rather than the exact numbers Podman writes, which also include extra ranges for group mapping; check yours with podman unshare cat /proc/self/uid_map and /proc/self/gid_map.

Limits and good habits

  • Range size: 65,536 IDs cover normal images. Images that use IDs above that need a larger range in /etc/subuid.
  • Not mapped means nobody: files owned by an unmapped host user show as nobody, and cannot be changed by the container.
  • Change a range with care: after altering /etc/subuid, run podman system migrate, and expect that existing storage may need a reset (podman system reset deletes everything).
  • Use non-root users in images too: root inside is safe from the host's view, but non-root is still best practice, because you reduce the impact of a bug in the program.
  • Don't mix modes: files created by a rootful container will not be editable by your user, and the other way around.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In default rootless mode, which host user does container UID 0 correspond to?

    The first line of the uid_map maps container 0 to your own host UID.
  2. 2. With alice (UID 1000) and a range of 100000:65536, what host UID is container UID 33?

    Container IDs from 1 map to 100000 onward, so container UID N is 100000 + N - 1. For 33 that is 100032.
  3. 3. Which tool lets you view and fix file ownership the way containers see it?

    podman unshare enters Podman's rootless user namespace, so chown and ls use the mapped IDs.
  4. 4. What does --userns=keep-id do?

    keep-id is ideal for development containers that edit your own files.
  5. 5. Which two files hold subordinate ID ranges?

    They define which extra user and group IDs a user may use for namespaces.

Summary

  • User namespaces let a rootless container have a root user that is just you on the host.
  • /etc/subuid and /etc/subgid give you a range of extra IDs; other container users map into that range.
  • Container UID N (N at least 1) is host UID start + N - 1, which explains odd owners like 100032.
  • podman unshare shows and fixes ownership from the container's point of view.
  • --userns=keep-id keeps your UID inside the container for development work.
  • Unmapped host users appear as nobody in the container.

Next: Rootless Ports, Networking and Storage