Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #230 from mstanleyjones/remove-userns-details 

Remove specific config info about userns-remap
This commit is contained in:
Sebastiaan van Stijn 2017-06-26 21:11:53 -07:00 committed by GitHub
parent 8fc3179111 8222baf263
commit 2eac0bb7b7
1 changed files with 18 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
docs/reference/commandline/dockerd.md
View File

@ -970,7 +970,7 @@ $ sudo dockerd \
The currently supported cluster store options are: The currently supported cluster store options are:
| Option | Description | | Option | Description |
|-----------------------|-------------| |:----------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `discovery.heartbeat` | Specifies the heartbeat timer in seconds which is used by the daemon as a `keepalive` mechanism to make sure discovery module treats the node as alive in the cluster. If not configured, the default value is 20 seconds. | | `discovery.heartbeat` | Specifies the heartbeat timer in seconds which is used by the daemon as a `keepalive` mechanism to make sure discovery module treats the node as alive in the cluster. If not configured, the default value is 20 seconds. |
| `discovery.ttl` | Specifies the TTL (time-to-live) in seconds which is used by the discovery module to timeout a node if a valid heartbeat is not received within the configured ttl value. If not configured, the default value is 60 seconds. | | `discovery.ttl` | Specifies the TTL (time-to-live) in seconds which is used by the discovery module to timeout a node if a valid heartbeat is not received within the configured ttl value. If not configured, the default value is 60 seconds. |
| `kv.cacertfile` | Specifies the path to a local file with PEM encoded CA certificates to trust. | | `kv.cacertfile` | Specifies the path to a local file with PEM encoded CA certificates to trust. |
@ -1005,152 +1005,18 @@ plugin](../../extend/plugins_authorization.md) section in the Docker extend sect
#### Daemon user namespace options #### Daemon user namespace options
The Linux kernel [user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) provides additional security by enabling The Linux kernel
a process, and therefore a container, to have a unique range of user and [user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html)
group IDs which are outside the traditional user and group range utilized by provides additional security by enabling a process, and therefore a container,
the host system. Potentially the most important security improvement is that, to have a unique range of user and group IDs which are outside the traditional
by default, container processes running as the `root` user will have expected user and group range utilized by the host system. Potentially the most important
administrative privilege (with some restrictions) inside the container but will security improvement is that, by default, container processes running as the
effectively be mapped to an unprivileged `uid` on the host. `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.
When user namespace support is enabled, Docker creates a single daemon-wide mapping For details about how to use this feature, as well as limitations, see
for all containers running on the same engine instance. The mappings will [Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/).
utilize the existing subordinate user and group ID feature available on all modern
Linux distributions.
The [`/etc/subuid`](http://man7.org/linux/man-pages/man5/subuid.5.html) and
[`/etc/subgid`](http://man7.org/linux/man-pages/man5/subgid.5.html) files will be
read for the user, and optional group, specified to the `--userns-remap`
parameter. If you do not wish to specify your own user and/or group, you can
provide `default` as the value to this flag, and a user will be created on your behalf
and provided subordinate uid and gid ranges. This default user will be named
`dockremap`, and entries will be created for it in `/etc/passwd` and
`/etc/group` using your distro's standard user and group creation tools.
> **Note**: The single mapping per-daemon restriction is in place for now
> because Docker shares image layers from its local cache across all
> containers running on the engine instance. Since file ownership must be
> the same for all containers sharing the same layer content, the decision
> was made to map the file ownership on `docker pull` to the daemon's user and
> group mappings so that there is no delay for running containers once the
> content is downloaded. This design preserves the same performance for `docker
> pull`, `docker push`, and container startup as users expect with
> user namespaces disabled.
##### Start the daemon with user namespaces enabled
To enable user namespace support, start the daemon with the
`--userns-remap` flag, which accepts values in the following formats:
- uid
- uid:gid
- username
- username:groupname
If numeric IDs are provided, translation back to valid user or group names
will occur so that the subordinate uid and gid information can be read, given
these resources are name-based, not id-based. If the numeric ID information
provided does not exist as entries in `/etc/passwd` or `/etc/group`, daemon
startup will fail with an error message.
**Example: starting with default Docker user management:**
```bash
$ sudo dockerd --userns-remap=default
```
When `default` is provided, Docker will create - or find the existing - user and group
named `dockremap`. If the user is created, and the Linux distribution has
appropriate support, the `/etc/subuid` and `/etc/subgid` files will be populated
with a contiguous 65536 length range of subordinate user and group IDs, starting
at an offset based on prior entries in those files. For example, Ubuntu will
create the following range, based on an existing user named `user1` already owning
the first 65536 range:
```bash
$ cat /etc/subuid
user1:100000:65536
dockremap:165536:65536
```
If you have a preferred/self-managed user with subordinate ID mappings already
configured, you can provide that username or uid to the `--userns-remap` flag.
If you have a group that doesn't match the username, you may provide the `gid`
or group name as well; otherwise the username will be used as the group name
when querying the system for the subordinate group ID range.
The output of `docker info` can be used to determine if the daemon is running
with user namespaces enabled or not. If the daemon is configured with user
namespaces, the Security Options entry in the response will list "userns" as
one of the enabled security features.
##### Behavior differences when user namespaces are enabled
When you start the Docker daemon with `--userns-remap`, Docker segregates the graph directory
where the images are stored by adding an extra directory with a name corresponding to the
remapped UID and GID. For example, if the remapped UID and GID begin with `165536`, all
images and containers running with that remap setting are located in `/var/lib/docker/165536.165536`
instead of `/var/lib/docker/`.
In addition, the files and directories within the new directory, which correspond to
images and container layers, are also owned by the new UID and GID. To set the ownership
correctly, you need to re-pull the images and restart the containers after starting the
daemon with `--userns-remap`.
##### Detailed information on `subuid`/`subgid` ranges
Given potential advanced use of the subordinate ID ranges by power users, the
following paragraphs define how the Docker daemon currently uses the range entries
found within the subordinate range files.
The simplest case is that only one contiguous range is defined for the
provided user or group. In this case, Docker will use that entire contiguous
range for the mapping of host uids and gids to the container process. This
means that the first ID in the range will be the remapped root user, and the
IDs above that initial ID will map host ID 1 through the end of the range.
From the example `/etc/subuid` content shown above, the remapped root
user would be uid 165536.
If the system administrator has set up multiple ranges for a single user or
group, the Docker daemon will read all the available ranges and use the
following algorithm to create the mapping ranges:
1. The range segments found for the particular user will be sorted by *start ID* ascending.
2. Map segments will be created from each range in increasing value with a length matching the length of each segment. Therefore the range segment with the lowest numeric starting value will be equal to the remapped root, and continue up through host uid/gid equal to the range segment length. As an example, if the lowest segment starts at ID 1000 and has a length of 100, then a map of 1000 -> 0 (the remapped root) up through 1100 -> 100 will be created from this segment. If the next segment starts at ID 10000, then the next map will start with mapping 10000 -> 101 up to the length of this second segment. This will continue until no more segments are found in the subordinate files for this user.
3. If more than five range segments exist for a single user, only the first five will be utilized, matching the kernel's limitation of only five entries in `/proc/self/uid_map` and `proc/self/gid_map`.
##### Disable user namespace for a container
If you enable user namespaces on the daemon, all containers are started
with user namespaces enabled. In some situations you might want to disable
this feature for a container, for example, to start a privileged container (see
[user namespace known restrictions](#user-namespace-known-restrictions)).
To enable those advanced features for a specific container use `--userns=host`
in the `run/exec/create` command.
This option will completely disable user namespace mapping for the container's user.
##### User namespace known restrictions
The following standard Docker features are currently incompatible when
running a Docker daemon with user namespaces enabled:
- sharing PID or NET namespaces with the host (`--pid=host` or `--net=host`)
- Using `--privileged` mode flag on `docker run` (unless also specifying `--userns=host`)
In general, user namespaces are an advanced feature and will require
coordination with other capabilities. For example, if volumes are mounted from
the host, file ownership will have to be pre-arranged if the user or
administrator wishes the containers to have expected access to the volume
contents. Note that when using external volume or graph driver plugins, those
external software programs must be made aware of user and group mapping ranges
if they are to work seamlessly with user namespace support.
Finally, while the `root` user inside a user namespaced container process has
many of the expected admin privileges that go along with being the superuser, the
Linux kernel has restrictions based on internal knowledge that this is a user namespaced
process. The most notable restriction that we are aware of at this time is the
inability to use `mknod`. Permission will be denied for device creation even as
container `root` inside a user namespace.
### Miscellaneous options ### Miscellaneous options