mirror of https://github.com/docker/cli.git
Merge pull request #230 from mstanleyjones/remove-userns-details
Remove specific config info about userns-remap
This commit is contained in:
Sebastiaan van Stijn
GitHub
commit
2eac0bb7b7
|
|
@ -969,14 +969,14 @@ $ sudo dockerd \
|
|||
|
||||
The currently supported cluster store options are:
|
||||
|
||||
| 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. |
|
||||
| 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.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.certfile` | Specifies the path to a local file with a PEM encoded certificate. This certificate is used as the client cert for communication with the Key/Value store. |
|
||||
| `kv.keyfile` | Specifies the path to a local file with a PEM encoded private key. This private key is used as the client key for communication with the Key/Value store. |
|
||||
| `kv.path` | Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'. |
|
||||
| `kv.cacertfile` | Specifies the path to a local file with PEM encoded CA certificates to trust. |
|
||||
| `kv.certfile` | Specifies the path to a local file with a PEM encoded certificate. This certificate is used as the client cert for communication with the Key/Value store. |
|
||||
| `kv.keyfile` | Specifies the path to a local file with a PEM encoded private key. This private key is used as the client key for communication with the Key/Value store. |
|
||||
| `kv.path` | Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'. |
|
||||
|
||||
#### Access authorization
|
||||
|
||||
|
|
@ -1005,152 +1005,18 @@ plugin](../../extend/plugins_authorization.md) section in the Docker extend sect
|
|||
|
||||
#### 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
|
||||
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.
|
||||
The Linux kernel
|
||||
[user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html)
|
||||
provides 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.
|
||||
|
||||
When user namespace support is enabled, Docker creates a single daemon-wide mapping
|
||||
for all containers running on the same engine instance. The mappings will
|
||||
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.
|
||||
For details about how to use this feature, as well as limitations, see
|
||||
[Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/).
|
||||
|
||||
### Miscellaneous options
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue