I am in a Docker context and i am using user namespaces to map my container's user into my host's user (let's say foo). As i use portainer (As a container), i need to bind the Docker socket.

$ll /var/run/docker.sock                                                                                                                                                 
srw-rw---- 1 root docker 0 nov.  14 11:47 /var/run/docker.sock

$sudo cat /etc/docker/daemon.json
  "userns-remap": "foo"

uid=1000(foo) gid=1000(foo) groupes=1000(foo),999(docker)

$getent group docker

Even if my foo user is allowed to access the docker group's files and Docker is using my foo user to run docker processes, my portainer is not allowed to access to socket.

Now, if i add this line to /etc/subgid, my problem is solved:


My understanding of this line is: foo user is allowed to access to first group with gid starting from 999, which is 999 (999+0). My foo user is allowed to access 999 gid which is docker group.

As i can see, there is a difference between:

$getent group docker


grep 999 /etc/subgid

My question: What is the difference between these two configurations and why do i need the subgid setup to allow my container to access my Docker socket ?

Thanks !

  • looking at man subgid would be a good start
    – A.B
    Commented Jul 16, 2018 at 23:48

1 Answer 1


with user namespace mapping

/etc/subuid for User IDs
/etc/subgid for Group IDs

are used to determine the range where user IDs in a container's context are mapped to the actual host ID.

So, for a

 /etc/subuid > foo:100000:5000

for example a process belonging '0' in the container might actually belong on the host User NS to a user ID somewhere in 100000+5000.

If now in the host context some resource is limited to specific user IDs, it might be that while in the container the user ID look good in the actual host context the ID is somewhere in the upper ranges and thus cannot access the resource.

  • what does the foo mean here? will a container running as root map to 100000 and be able to edit a mounted foo-owned file? Commented Nov 20, 2023 at 16:06

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .