diff --git a/components/cli/docs/extend/plugins_authorization.md b/components/cli/docs/extend/plugins_authorization.md index ac1837f754..5b49d657ef 100644 --- a/components/cli/docs/extend/plugins_authorization.md +++ b/components/cli/docs/extend/plugins_authorization.md @@ -27,7 +27,7 @@ same is true for callers using Docker's Engine API to contact the daemon. If you require greater access control, you can create authorization plugins and add them to your Docker daemon configuration. Using an authorization plugin, a Docker administrator can configure granular access policies for managing access -to Docker daemon. +to the Docker daemon. Anyone with the appropriate skills can develop an authorization plugin. These skills, at their most basic, are knowledge of Docker, understanding of REST, and diff --git a/components/cli/docs/reference/builder.md b/components/cli/docs/reference/builder.md index f8ef9cf56b..d6274407e6 100644 --- a/components/cli/docs/reference/builder.md +++ b/components/cli/docs/reference/builder.md @@ -30,13 +30,13 @@ Practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-pr ## Usage The [`docker build`](commandline/build.md) command builds an image from -a `Dockerfile` and a *context*. The build's context is the files at a specified -location `PATH` or `URL`. The `PATH` is a directory on your local filesystem. -The `URL` is a Git repository location. +a `Dockerfile` and a *context*. The build's context is the set of files at a +specified location `PATH` or `URL`. The `PATH` is a directory on your local +filesystem. The `URL` is a Git repository location. A context is processed recursively. So, a `PATH` includes any subdirectories and -the `URL` includes the repository and its submodules. A simple build command -that uses the current directory as context: +the `URL` includes the repository and its submodules. This example shows a +build command that uses the current directory as context: $ docker build . Sending build context to Docker daemon 6.51 MB @@ -1306,11 +1306,18 @@ Keep the following things in mind about volumes in the `Dockerfile`. ## USER - USER daemon + USER [:] +or + USER [:] + +The `USER` instruction sets the user name (or UID) and optionally the user +group (or GID) to use when running the image and for any `RUN`, `CMD` and +`ENTRYPOINT` instructions that follow it in the `Dockerfile`. + +> **Warning**: +> When the user does doesn't have a primary group then the image (or the next +> instructions) will be run with the `root` group. -The `USER` instruction sets the user name or UID to use when running the image -and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the -`Dockerfile`. ## WORKDIR @@ -1321,9 +1328,9 @@ The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, If the `WORKDIR` doesn't exist, it will be created even if it's not used in any subsequent `Dockerfile` instruction. -It can be used multiple times in the one `Dockerfile`. If a relative path -is provided, it will be relative to the path of the previous `WORKDIR` -instruction. For example: +The `WORKDIR` instruction can be used multiple times in a `Dockerfile`. If a +relative path is provided, it will be relative to the path of the previous +`WORKDIR` instruction. For example: WORKDIR /a WORKDIR b diff --git a/components/cli/docs/reference/commandline/attach.md b/components/cli/docs/reference/commandline/attach.md index 4153331bad..7e654d7350 100644 --- a/components/cli/docs/reference/commandline/attach.md +++ b/components/cli/docs/reference/commandline/attach.md @@ -40,7 +40,7 @@ interactively, as though the commands were running directly in your terminal. > not be interacting with the terminal at that time. You can attach to the same contained process multiple times simultaneously, -even as a different user with the appropriate permissions. +from different sessions on the Docker host. To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to diff --git a/components/cli/docs/reference/commandline/build.md b/components/cli/docs/reference/commandline/build.md index 9f587372c6..443ea015b2 100644 --- a/components/cli/docs/reference/commandline/build.md +++ b/components/cli/docs/reference/commandline/build.md @@ -63,11 +63,11 @@ Options: ## Description -Builds Docker images from a Dockerfile and a "context". A build's context is -the files located in the specified `PATH` or `URL`. The build process can refer -to any of the files in the context. For example, your build can use an -[*ADD*](../builder.md#add) instruction to reference a file in the -context. +The `docker build` command builds Docker images from a Dockerfile and a +"context". A build's context is the set of files located in the specified +`PATH` or `URL`. The build process can refer to any of the files in the +context. For example, your build can use a [*COPY*](../builder.md#copy) +instruction to reference a file in the context. The `URL` parameter can refer to three kinds of resources: Git repositories, pre-packaged tarball contexts and plain text files. @@ -88,7 +88,7 @@ user credentials, VPN's, and so forth. Git URLs accept context configuration in their fragment section, separated by a colon `:`. The first part represents the reference that Git will check out, -this can be either a branch, a tag, or a remote reference. The second part +and can be either a branch, a tag, or a remote reference. The second part represents a subdirectory inside the repository that will be used as a build context. diff --git a/components/cli/docs/reference/commandline/cli.md b/components/cli/docs/reference/commandline/cli.md index 4d1cd2a638..c2c5f34cdc 100644 --- a/components/cli/docs/reference/commandline/cli.md +++ b/components/cli/docs/reference/commandline/cli.md @@ -216,6 +216,7 @@ attach`, `docker exec`, `docker run` or `docker start` command. Following is a sample `config.json` file: ```json +{% raw %} { "HttpHeaders": { "MyHeader": "MyValue" @@ -236,6 +237,7 @@ Following is a sample `config.json` file: "unicorn.example.com": "vcbait" } } +{% endraw %} ``` ### Notary diff --git a/components/cli/docs/reference/commandline/dockerd.md b/components/cli/docs/reference/commandline/dockerd.md index ef6bcd3831..95a953f1c4 100644 --- a/components/cli/docs/reference/commandline/dockerd.md +++ b/components/cli/docs/reference/commandline/dockerd.md @@ -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 diff --git a/components/cli/docs/reference/commandline/exec.md b/components/cli/docs/reference/commandline/exec.md index e2e5d607b9..2bfa74483c 100644 --- a/components/cli/docs/reference/commandline/exec.md +++ b/components/cli/docs/reference/commandline/exec.md @@ -76,6 +76,17 @@ $ docker exec -it ubuntu_bash bash This will create a new Bash session in the container `ubuntu_bash`. +Next, set an environment variable in the current bash session. + +```bash +$ docker exec -it -e VAR=1 ubuntu_bash bash +``` + +This will create a new Bash session in the container `ubuntu_bash` with environment +variable `$VAR` set to "1". Note that this environment variable will only be valid +on the current Bash session. + + ### Try to run `docker exec` on a paused container If the container is paused, then the `docker exec` command will fail with an error: diff --git a/components/cli/docs/reference/commandline/ps.md b/components/cli/docs/reference/commandline/ps.md index 51bab4834d..167e5d73be 100644 --- a/components/cli/docs/reference/commandline/ps.md +++ b/components/cli/docs/reference/commandline/ps.md @@ -82,20 +82,21 @@ than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bi The currently supported filters are: -* id (container's id) -* label (`label=` or `label==`) -* name (container's name) -* exited (int - the code of exited containers. Only useful with `--all`) -* status (`created|restarting|running|removing|paused|exited|dead`) -* ancestor (`[:]`, `` or ``) - filters containers that were created from the given image or a descendant. -* before (container's id or name) - filters containers created before given id or name -* since (container's id or name) - filters containers created since given id or name -* isolation (`default|process|hyperv`) (Windows daemon only) -* volume (volume name or mount point) - filters containers that mount volumes. -* network (network id or name) - filters containers connected to the provided network -* health (starting|healthy|unhealthy|none) - filters containers based on healthcheck status -* publish=(container's published port) - filters published ports by containers -* expose=(container's exposed port) - filters exposed ports by containers +| Filter | Description | +|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------| +| `id` | container's ID | +| `name` | container's name | +| `label` | An arbitrary string representing either a key or a key-value pair | +| `exited` | An integer representing the container's exit code. Only useful with `--all`. | +| `status` | One of `created|restarting|running|removing|paused|exited|dead` | +| `ancestor` | Filters containers which share a given image as an ancestor. Expressed as `[:]`, ``, or `` | +| `before` or `since` | Filters containers created before or after a given container ID or name | +| `volume` | Filters running containers which have mounted a given volume or bind mount. | +| `network` | Filters running containers connected to a given network. | +| `publish` or `expose` | Filters containers which publish or expose a given port. | +| `health` | One of `starting|healthy|unhealthy|none`. Filters containers based on their healthcheck status. | +| `isolation` | Windows daemon only. One of `default|process|hyperv`. | + #### label @@ -387,21 +388,21 @@ template. Valid placeholders for the Go template are listed below: -Placeholder | Description ---------------|---------------------------------------------------------------------------------------------------- -`.ID` | Container ID -`.Image` | Image ID -`.Command` | Quoted command -`.CreatedAt` | Time when the container was created. -`.RunningFor` | Elapsed time since the container was started. -`.Ports` | Exposed ports. -`.Status` | Container status. -`.Size` | Container disk size. -`.Names` | Container names. -`.Labels` | All labels assigned to the container. -`.Label` | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'` -`.Mounts` | Names of the volumes mounted in this container. -`.Networks` | Names of the networks attached to this container. +| Placeholder | Description | +|:--------------|:------------------------------------------------------------------------------------------------| +| `.ID` | Container ID | +| `.Image` | Image ID | +| `.Command` | Quoted command | +| `.CreatedAt` | Time when the container was created. | +| `.RunningFor` | Elapsed time since the container was started. | +| `.Ports` | Exposed ports. | +| `.Status` | Container status. | +| `.Size` | Container disk size. | +| `.Names` | Container names. | +| `.Labels` | All labels assigned to the container. | +| `.Label` | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'` | +| `.Mounts` | Names of the volumes mounted in this container. | +| `.Networks` | Names of the networks attached to this container. | When using the `--format` option, the `ps` command will either output the data exactly as the template declares or, when using the `table` directive, includes @@ -429,4 +430,4 @@ a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd 01946d9d34d8 c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd -``` +``` \ No newline at end of file diff --git a/components/cli/docs/reference/commandline/service_create.md b/components/cli/docs/reference/commandline/service_create.md index 78faa98bf7..a1b6d18f9d 100644 --- a/components/cli/docs/reference/commandline/service_create.md +++ b/components/cli/docs/reference/commandline/service_create.md @@ -167,6 +167,8 @@ $ docker service create --name redis \ 4cdgfyky7ozwh3htjfw0d12qv ``` +To grant a service access to multiple secrets, use multiple `--secret` flags. + Secrets are located in `/run/secrets` in the container. If no target is specified, the name of the secret will be used as the in memory file in the container. If a target is specified, that will be the filename. In the @@ -191,10 +193,26 @@ tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/). ### Set environment variables (-e, --env) -This sets environmental variables for all tasks in a service. For example: +This sets an environmental variable for all tasks in a service. For example: ```bash -$ docker service create --name redis_2 --replicas 5 --env MYVAR=foo redis:3.0.6 +$ docker service create \ + --name redis_2 \ + --replicas 5 \ + --env MYVAR=foo \ + redis:3.0.6 +``` + +To specify multiple environment variables, specify multiple `--env` flags, each +with a separate key-value pair. + +```bash +$ docker service create \ + --name redis_2 \ + --replicas 5 \ + --env MYVAR=foo \ + --env MYVAR2=bar \ + redis:3.0.6 ``` ### Create a service with specific hostname (--hostname) diff --git a/components/cli/docs/reference/commandline/stack_deploy.md b/components/cli/docs/reference/commandline/stack_deploy.md index d57ef0f76c..7f3f7f4c5b 100644 --- a/components/cli/docs/reference/commandline/stack_deploy.md +++ b/components/cli/docs/reference/commandline/stack_deploy.md @@ -40,7 +40,7 @@ has to be run targeting a manager node. ### Compose file -The `deploy` command supports compose file version `3.0` and above." +The `deploy` command supports compose file version `3.0` and above. ```bash $ docker stack deploy --compose-file docker-compose.yml vossibility @@ -57,7 +57,28 @@ Creating service vossibility_ghollector Creating service vossibility_lookupd ``` -You can verify that the services were correctly created +Only a single Compose file is accepted. If your configuration is split between +multiple Compose files, e.g. a base configuration and environment-specific overrides, +you can combine these by passing them to `docker-compose config` with the `-f` option +and redirecting the merged output into a new file. + +```bash +$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml config > docker-stack.yml +$ docker stack deploy --compose-file docker-stack.yml vossibility + +Ignoring unsupported options: links + +Creating network vossibility_vossibility +Creating network vossibility_default +Creating service vossibility_nsqd +Creating service vossibility_logstash +Creating service vossibility_elasticsearch +Creating service vossibility_kibana +Creating service vossibility_ghollector +Creating service vossibility_lookupd +``` + +You can verify that the services were correctly created: ```bash $ docker service ls diff --git a/components/cli/docs/reference/run.md b/components/cli/docs/reference/run.md index 817c20c969..4932a530cf 100644 --- a/components/cli/docs/reference/run.md +++ b/components/cli/docs/reference/run.md @@ -87,8 +87,9 @@ default foreground mode: To start a container in detached mode, you use `-d=true` or just `-d` option. By design, containers started in detached mode exit when the root process used to -run the container exits. A container in detached mode cannot be automatically -removed when it stops, this means you cannot use the `--rm` option with `-d` option. +run the container exits, unless you also specify the `--rm` option. If you use +`-d` with `--rm`, the container is removed when it exits **or** when the daemon +exits, whichever happens first. Do not pass a `service x start` command to a detached container. For example, this command attempts to start the `nginx` service. @@ -149,7 +150,7 @@ is receiving its standard input from a pipe, as in: The operator can identify a container in three ways: | Identifier type | Example value | -| --------------------- | ------------------------------------------------------------------ | +|:----------------------|:-------------------------------------------------------------------| | UUID long identifier | "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" | | UUID short identifier | "f78375b1c487" | | Name | "evil_ptolemy" | @@ -686,29 +687,29 @@ parent group. The operator can also adjust the performance parameters of the container: -| Option | Description | -| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `-m`, `--memory=""` | Memory limit (format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. | -| `--memory-swap=""` | Total memory limit (memory + swap, format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. | -| `--memory-reservation=""` | Memory soft limit (format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. | -| `--kernel-memory=""` | Kernel memory limit (format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. | -| `-c`, `--cpu-shares=0` | CPU shares (relative weight) | -| `--cpus=0.000` | Number of CPUs. Number is a fractional number. 0.000 means no limit. | -| `--cpu-period=0` | Limit the CPU CFS (Completely Fair Scheduler) period | -| `--cpuset-cpus=""` | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems=""` | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. | -| `--cpu-quota=0` | Limit the CPU CFS (Completely Fair Scheduler) quota | -| `--cpu-rt-period=0` | Limit the CPU real-time period. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. | -| `--cpu-rt-runtime=0` | Limit the CPU real-time runtime. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. | -| `--blkio-weight=0` | Block IO weight (relative weight) accepts a weight value between 10 and 1000. | -| `--blkio-weight-device=""` | Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`) | -| `--device-read-bps=""` | Limit read rate from a device (format: `:[]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. | -| `--device-write-bps=""` | Limit write rate to a device (format: `:[]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. | -| `--device-read-iops="" ` | Limit read rate (IO per second) from a device (format: `:`). Number is a positive integer. | -| `--device-write-iops="" ` | Limit write rate (IO per second) to a device (format: `:`). Number is a positive integer. | -| `--oom-kill-disable=false` | Whether to disable OOM Killer for the container or not. | -| `--oom-score-adj=0` | Tune container's OOM preferences (-1000 to 1000) | -| `--memory-swappiness=""` | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. | +| Option | Description | +|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-m`, `--memory=""` | Memory limit (format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. | +| `--memory-swap=""` | Total memory limit (memory + swap, format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. | +| `--memory-reservation=""` | Memory soft limit (format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. | +| `--kernel-memory=""` | Kernel memory limit (format: `[]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. | +| `-c`, `--cpu-shares=0` | CPU shares (relative weight) | +| `--cpus=0.000` | Number of CPUs. Number is a fractional number. 0.000 means no limit. | +| `--cpu-period=0` | Limit the CPU CFS (Completely Fair Scheduler) period | +| `--cpuset-cpus=""` | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems=""` | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. | +| `--cpu-quota=0` | Limit the CPU CFS (Completely Fair Scheduler) quota | +| `--cpu-rt-period=0` | Limit the CPU real-time period. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. | +| `--cpu-rt-runtime=0` | Limit the CPU real-time runtime. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. | +| `--blkio-weight=0` | Block IO weight (relative weight) accepts a weight value between 10 and 1000. | +| `--blkio-weight-device=""` | Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`) | +| `--device-read-bps=""` | Limit read rate from a device (format: `:[]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. | +| `--device-write-bps=""` | Limit write rate to a device (format: `:[]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. | +| `--device-read-iops="" ` | Limit read rate (IO per second) from a device (format: `:`). Number is a positive integer. | +| `--device-write-iops="" ` | Limit write rate (IO per second) to a device (format: `:`). Number is a positive integer. | +| `--oom-kill-disable=false` | Whether to disable OOM Killer for the container or not. | +| `--oom-score-adj=0` | Tune container's OOM preferences (-1000 to 1000) | +| `--memory-swappiness=""` | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. | | `--shm-size=""` | Size of `/dev/shm`. The format is ``. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. | ### User memory constraints @@ -1158,7 +1159,7 @@ list of capabilities that are kept. The following table lists the Linux capabili options which are allowed by default and can be dropped. | Capability Key | Capability Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | +|:-----------------|:------------------------------------------------------------------------------------------------------------------------------| | SETPCAP | Modify process capabilities. | | MKNOD | Create special files using mknod(2). | | AUDIT_WRITE | Write records to kernel auditing log. | @@ -1176,31 +1177,31 @@ options which are allowed by default and can be dropped. The next table shows the capabilities which are not granted by default and may be added. -| Capability Key | Capability Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| SYS_MODULE | Load and unload kernel modules. | -| SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). | -| SYS_PACCT | Use acct(2), switch process accounting on or off. | -| SYS_ADMIN | Perform a range of system administration operations. | -| SYS_NICE | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes. | -| SYS_RESOURCE | Override resource Limits. | -| SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. | -| SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. | -| AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. | -| MAC_OVERRIDE | Allow MAC configuration or state changes. Implemented for the Smack LSM. | -| MAC_ADMIN | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). | -| NET_ADMIN | Perform various network-related operations. | -| SYSLOG | Perform privileged syslog(2) operations. | -| DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. | -| LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. | -| NET_BROADCAST | Make socket broadcasts, and listen to multicasts. | -| IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). | -| IPC_OWNER | Bypass permission checks for operations on System V IPC objects. | -| SYS_PTRACE | Trace arbitrary processes using ptrace(2). | -| SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. | -| LEASE | Establish leases on arbitrary files (see fcntl(2)). | -| WAKE_ALARM | Trigger something that will wake up the system. | -| BLOCK_SUSPEND | Employ features that can block system suspend. | +| Capability Key | Capability Description | +|:----------------|:----------------------------------------------------------------------------------------------------------------| +| SYS_MODULE | Load and unload kernel modules. | +| SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). | +| SYS_PACCT | Use acct(2), switch process accounting on or off. | +| SYS_ADMIN | Perform a range of system administration operations. | +| SYS_NICE | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes. | +| SYS_RESOURCE | Override resource Limits. | +| SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. | +| SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. | +| AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. | +| MAC_OVERRIDE | Allow MAC configuration or state changes. Implemented for the Smack LSM. | +| MAC_ADMIN | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). | +| NET_ADMIN | Perform various network-related operations. | +| SYSLOG | Perform privileged syslog(2) operations. | +| DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. | +| LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. | +| NET_BROADCAST | Make socket broadcasts, and listen to multicasts. | +| IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). | +| IPC_OWNER | Bypass permission checks for operations on System V IPC objects. | +| SYS_PTRACE | Trace arbitrary processes using ptrace(2). | +| SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. | +| LEASE | Establish leases on arbitrary files (see fcntl(2)). | +| WAKE_ALARM | Trigger something that will wake up the system. | +| BLOCK_SUSPEND | Employ features that can block system suspend. | Further reference information is available on the [capabilities(7) - Linux man page](http://man7.org/linux/man-pages/man7/capabilities.7.html) @@ -1252,7 +1253,7 @@ the `--log-driver=VALUE` with the `docker run` command to configure the container's logging driver. The following options are supported: | Driver | Description | -| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | +|:------------|:------------------------------------------------------------------------------------------------------------------------------| | `none` | Disables any logging for the container. `docker logs` won't be available with this driver. | | `json-file` | Default logging driver for Docker. Writes JSON messages to file. No logging options are supported for this driver. | | `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. | @@ -1398,12 +1399,12 @@ container. The following environment variables are set for Linux containers: -| Variable | Value | -| -------- | ----- | -| `HOME` | Set based on the value of `USER` | -| `HOSTNAME` | The hostname associated with the container | -| `PATH` | Includes popular directories, such as `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` | -| `TERM` | `xterm` if the container is allocated a pseudo-TTY | +| Variable | Value | +|:-----------|:-----------------------------------------------------------------------------------------------------| +| `HOME` | Set based on the value of `USER` | +| `HOSTNAME` | The hostname associated with the container | +| `PATH` | Includes popular directories, such as `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` | +| `TERM` | `xterm` if the container is allocated a pseudo-TTY | Additionally, the operator can **set any environment variable** in the diff --git a/components/cli/experimental/docker-stacks-and-bundles.md b/components/cli/experimental/docker-stacks-and-bundles.md index 8abfd76359..1271af67e0 100644 --- a/components/cli/experimental/docker-stacks-and-bundles.md +++ b/components/cli/experimental/docker-stacks-and-bundles.md @@ -161,21 +161,18 @@ A service has the following fields: only specify the container port to be exposed. These ports can be mapped on runtime hosts at the operator's discretion. -
WorkingDir string
Working directory inside the service containers.
-
User string
Username or UID (format: <name|uid>[:<group|gid>]).
-
Networks []string
diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 1ba9c5874c..5df349e390 100644 --- a/components/engine/api/swagger.yaml +++ b/components/engine/api/swagger.yaml @@ -7352,6 +7352,16 @@ paths: AdvertiseAddr: description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." type: "string" + DataPathAddr: + description: | + Address or interface to use for data path traffic (format: ``), for example, `192.168.1.1`, + or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` + is used. + + The `DataPathAddr` specifies the address that global scope network drivers will publish towards other + nodes in order to reach the containers running on this node. Using this parameter it is possible to + separate the container data traffic from the management traffic of the cluster. + type: "string" ForceNewCluster: description: "Force creation of a new swarm." type: "boolean" @@ -7400,6 +7410,17 @@ paths: type: "string" AdvertiseAddr: description: "Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible." + type: "string" + DataPathAddr: + description: | + Address or interface to use for data path traffic (format: ``), for example, `192.168.1.1`, + or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` + is used. + + The `DataPathAddr` specifies the address that global scope network drivers will publish towards other + nodes in order to reach the containers running on this node. Using this parameter it is possible to + separate the container data traffic from the management traffic of the cluster. + type: "string" RemoteAddrs: description: "Addresses of manager nodes already participating in the swarm." diff --git a/components/engine/docs/api/version-history.md b/components/engine/docs/api/version-history.md index 3891d35c04..8cb95b2948 100644 --- a/components/engine/docs/api/version-history.md +++ b/components/engine/docs/api/version-history.md @@ -29,6 +29,8 @@ keywords: "API, Docker, rcli, REST, documentation" generate and rotate to a new CA certificate/key pair. * `POST /service/create` and `POST /services/(id or name)/update` now take the field `Platforms` as part of the service `Placement`, allowing to specify platforms supported by the service. * `POST /containers/(name)/wait` now accepts a `condition` query parameter to indicate which state change condition to wait for. Also, response headers are now returned immediately to acknowledge that the server has registered a wait callback for the client. +* `POST /swarm/init` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic +* `POST /swarm/join` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic ## v1.29 API changes