Enabling user namespace remapping feature in Docker 1.10.

SUSE Linux Enterprise Server 12 Service Pack 1 (SLES 12 SP1)
SUSE Linux Enterprise Workstation Extension 12

User namespace remapping feature needs manual configuration in Docker 1.10.

Background :

User namespaces allow for a set of processes in a namespace to see a different UID mapping.
This practically means that you can "fool" a process into believing it has root privileges (when in fact it doesn't).

Docker's support for user namespaces is on a whole-daemon level, meaning that every container starts with the exact same user mapping. This allows for sharing of volumes between containers without major UID mapping issues (if a UID is not mapped in a container's namespace, the container cannot access a file owned by that UID at all).

Usage :

In order to use the new user namespace remapping feature of Docker 1.10, it is needed to create a few files.
Traditionally these are managed by shadow, but for the moment this is necessary setup.

When starting the daemon you can specify the '--userns-remap' option, which takes either the argument "default" or a "user:group" mapping.

This option needs to be added to the file  /etc/sysconfig/docker  as shown below  :
   
    ## Path           : System/Management
    ## Description    : Extra cli switches for docker daemon
    ## Type           : string
    ## Default        : ""
    ## ServiceRestart : docker
    #
    DOCKER_OPTS="--userns-remap (default or <user>[:<group>])"
   
The "default" mapping is essentially equivalent to the string "dockremap:dockremap".

When having the "user:group" mapping specified however, the named user and group must exist on the host system, and it is mandatory to have the corresponding entries in  /etc/subuid  and  /etc/subgid.

An important thing to note is that the actual UID and GID of the user specified doesn't affect the mapping. The user's sole purpose is to
reserve the range of UIDs and GIDs Docker will remap to. So it's perfectly acceptable to create a "system user" and use that user for defining your mappings.


When specifying the "default" mapping, Docker will create entries for "dockremap" in both  /etc/passwd and /etc/shadow  file with a UID and GID of 10000.
However, it does not add entries to /etc/subuid and /etc/subgid automatically, these must currently be added manually.

When specifying a numeric (or mixed) "user:group" mapping, the user and group names will be determined from the first entry in /etc/passwd  and /etc/groups that have the same UID or GID as the numeric one specified.

The files /etc/subuid and /etc/subgid  are not currently managed by SLE12's version of "shadow", and therefor it is necessary to generate them manually by hand. These files are essentially access controls for what user namespace mappings a particular user has the right to. Docker obeys them and will not start if the  "--userns-remap" option you have specified doesn't have an entry in both /etc/subuid  and /etc/subgid.


The format of both  /etc/subuid  and  /etc/subgid  files is as follows  :

name:start:length

- name is the name of the user or group (/etc/subuid  and  /etc/subgid, respectively) for which the rule applies to.
- start is effectively what root  in the container will be remapped to. It is the first numeric ID that the mapping begins with.
- length is the number of UIDs to map. The UIDs are all mapped sequentially, essentially becoming "userns_remap_uid = uid_in_container + start" if "uid_in_container < length".

For example, if you wanted to remap the first "65535" UID's to the same range, starting at UID "123456", it would require to add the following line to  /etc/subuid :

    dockremap:123456:65536

The same rule applies for remapping the GIDs, and it is mandatory to remap both, or Docker will fail to start.
When not specifying a group in "--userns-remap", it will use the default GID of the user (the 4th column in  /etc/passwd).

It should be noted that changing the remapping setting for you Docker daemon will require a rebuild or re-pull all of your Docker images. When changing back to a previously used remapping setting, all of the images used with that remapping setting will be available.

How to check User Namespaces are Enabled :

A quick check for this is to see what the contents of  /proc/self/uid_map  and  /proc/self/gid_map  are inside a container.

When the contents look like this :

% docker run -it <image> cat /proc/self/{uid,gid}_map
          0          0 4294967295
          0          0 4294967295

Then the container does not have remapped UIDs.

However, when to continue using the same example mentioned above, when we remap the first "65535" UIDs to the same range starting at "123456", then the contents of both   /proc/self/uid_map  and  /proc/self/gid_map  looks as this :

% docker run -it <image> cat /proc/self/{uid,gid}_map
          0     123456      65536
          0     123456      65536

Please note :
Reference to  <image>  in the examples above refers to any image available on your Docker host, which is just used for testing purposes.