Docker User Namespaces - Enabling userns-remap on Docker Toolbox

This post shortly shows how to enable Docker user namespaces on Docker Toolbox.

What are user namespaces?

User Namespaces provide additional security by enabling a process, and therefore a container, to have a unique range of user and group IDs which are outside the traditional user and group range utilized by the host system. Potentially the most important security improvement is that, by default, container processes running as the root user will have expected administrative privilege (with some restrictions) inside the container but will effectively be mapped to an unprivileged uid on the host. source

How to enable it?

The --userns-remap is an option to the docker daemon dockerd. The upstart job can be found here:

cat /etc/init.d/docker or
cat /usr/local/etc/init.d/docker

This job can be passed additional arguments ... connect to your default vm on Virtualbox:
docker-machine ssh default
Then switch to root user:
sudo -i

Now in the boot2docker profile (which is be loaded at startup) add --userns-remap=default to the EXTRA_ARGS initialization statement:
vi /var/lib/boot2docker/profile

EXTRA_ARGS=' --label provider=virtualbox --userns-remap=default '

For later comparison optionally list the current contents of the docker directory:
ls /var/lib/docker/ -al
This is still unchanged as a restart is necessary. So exit from the vm and restart it via docker-machine:
docker-machine restart default

After the default vm has restarted reenter it by:
docker-machine ssh default
sudo -i
Now again list the contents of the docker directory:
ls /var/lib/docker/ -al

drwx------ 11 165536 165536 ... 165536.165536

The UID, GID and directory name should correspond to the output of:
cat /etc/subuid and cat /etc/subgid:


This is the default mapping provided by Docker. You can as well create your own (see the links below).

What are the consequences?

Now the 165536.165536 directory will be the main directory for the docker engine. Everything in the original /var/lib/docker/ directory will no longer be visible (e.g. images, containers) in the running docker engine. In order to use these again the docker daemon needs to be started without user namespaces enabled.

With user namespaces enabled the root user inside the the container is no longer the root user on the host as his UID and GID have been remapped. On the host this user is unprivileged.

This is the effect wanted. Yet as a "side" effect, access to shared resources (e.g. named volumes or host binds) can now be affected as well (for volume permissions e.g. see the links below).

Nevertheless user namespaces is a mayor security (isolation) benefit which accompanies well the kernel namespaces which are one of the basic foundations of container technology.

Further information

General information provided by Docker:

Further How-Tos (including individual mappings and further tests):

Volume Permissions:

Explanation on passing extra arguments to docker startup:

Disabling userns in docker-compose: