From 73badb5bc76d19989f6e61c7b3c668deebe27e52 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 7 Jun 2017 09:40:43 -0700 Subject: [PATCH 01/14] Clarify ability to attach multiple times Signed-off-by: Misty Stanley-Jones (cherry picked from commit b5d33c6e76e381dce664be6c40209fb467b43765) Signed-off-by: Andrew Hsu --- components/cli/docs/reference/commandline/attach.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From b0d4910c7ed69596ac90535b65893f21aa7aafe4 Mon Sep 17 00:00:00 2001 From: Slava Semushin Date: Wed, 7 Jun 2017 18:50:16 +0200 Subject: [PATCH 02/14] docs/reference/builder.md: mention that USER directive also allows to specify the user group. Signed-off-by: Slava Semushin (cherry picked from commit a84463d8d56a41c1bf9496efc35580789891c2c9) Signed-off-by: Andrew Hsu --- components/cli/docs/reference/builder.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/components/cli/docs/reference/builder.md b/components/cli/docs/reference/builder.md index f8ef9cf56b..9ab4ba4df9 100644 --- a/components/cli/docs/reference/builder.md +++ b/components/cli/docs/reference/builder.md @@ -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 From 6a52ac6c496770e056674f445ca1b0d25e26d9ae Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 15 Jun 2017 17:24:41 +0200 Subject: [PATCH 03/14] Added usage example for -e for exec Signed-off-by: Vishnu Narayanan Signed-off-by: Sebastiaan van Stijn (cherry picked from commit c848d9b22d43fd89121f8e1608b9c3126f347049) Signed-off-by: Andrew Hsu --- components/cli/docs/reference/commandline/exec.md | 11 +++++++++++ 1 file changed, 11 insertions(+) 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: From 345e74062e1811466fe04736adee5be63dbc6bfc Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 20 Jun 2017 15:15:08 -0700 Subject: [PATCH 04/14] Fix Markdown formatting of experimental "stacks" Signed-off-by: Sebastiaan van Stijn (cherry picked from commit c5301ca35dd98835bbc4bcec840526373a3a2ea2) Signed-off-by: Andrew Hsu --- components/cli/experimental/docker-stacks-and-bundles.md | 3 --- 1 file changed, 3 deletions(-) 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
From 1c485088329474de6ab833ea2c8f2e009cce2218 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 20 Jun 2017 21:23:21 -0700 Subject: [PATCH 05/14] Explain `stack deploy` with multiple Compose files The Docker Compose docs suggest using a separate override configuration file for production-specific settings, but it is not obvious how to feed this to `docker stack deploy`, which only supports a single Compose file as input. Thus, we now describe how to do this by merging the configuration files with `docker-compose config`. Signed-off-by: Denis Washington Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 36fa4af30b5d446a56fdbbc3c3280ed9743fad0b) Signed-off-by: Andrew Hsu --- .../reference/commandline/stack_deploy.md | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) 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 From 1d69626e30e94a2987781b70e5fa5ff8e8215b4d Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 21 Jun 2017 10:31:03 -0700 Subject: [PATCH 06/14] Reformat filtering options in ps ref Signed-off-by: Misty Stanley-Jones (cherry picked from commit 0888df30580a06c6062bc71f2cf064e8940643f3) Signed-off-by: Andrew Hsu --- .../cli/docs/reference/commandline/ps.md | 61 ++++++++++--------- 1 file changed, 31 insertions(+), 30 deletions(-) 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 From e3d07855d5a93c9655b73c7bbcbdad15af671884 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Wed, 21 Jun 2017 11:01:54 -0700 Subject: [PATCH 07/14] Fix small typo Signed-off-by: Misty Stanley-Jones (cherry picked from commit ede69a38c2cbe7d86a5a87f8e0c4738c37613160) Signed-off-by: Andrew Hsu --- components/cli/docs/extend/plugins_authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 84d2a56ff34cff2033eb18c552e27d2de72d6150 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Thu, 22 Jun 2017 15:09:14 -0700 Subject: [PATCH 08/14] Remove specific config info about userns-remap Signed-off-by: Misty Stanley-Jones (cherry picked from commit 8222baf2633816553b3f0198d84ed9fccfc8c842) Signed-off-by: Andrew Hsu --- .../cli/docs/reference/commandline/dockerd.md | 170 ++---------------- 1 file changed, 18 insertions(+), 152 deletions(-) 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 From ee07daead14e0f0cf149b37dd7d0960d69ae55ea Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Mon, 26 Jun 2017 12:50:34 -0700 Subject: [PATCH 09/14] Fix false Liquid errors Signed-off-by: Misty Stanley-Jones (cherry picked from commit 11c1729e006c909af5ed07d3d93e44948e72bc76) Signed-off-by: Andrew Hsu --- components/cli/docs/reference/commandline/cli.md | 2 ++ 1 file changed, 2 insertions(+) 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 From d4fe7965d23bf39d9e435f6146cc1f539a92a167 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 26 Jun 2017 18:46:45 -0700 Subject: [PATCH 10/14] Some builder docs improvements Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 29b419eed5c37853e50d2f75b99904da230bc84e) Signed-off-by: Andrew Hsu --- components/cli/docs/reference/builder.md | 16 ++++++++-------- .../cli/docs/reference/commandline/build.md | 12 ++++++------ 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/components/cli/docs/reference/builder.md b/components/cli/docs/reference/builder.md index 9ab4ba4df9..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 @@ -1328,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/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. From 7c374afda613138ac522b16520018f25cba8c473 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Mon, 3 Jul 2017 15:03:02 -0700 Subject: [PATCH 11/14] Provide examples for multiple uses of the same flag Signed-off-by: Misty Stanley-Jones (cherry picked from commit ef61582591f0b1a043dafeb035685a1779e3cfc3) Signed-off-by: Andrew Hsu --- .../reference/commandline/service_create.md | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) 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) From b237329009667a032483927eaa49d01d1030ab6d Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Mon, 3 Jul 2017 16:39:47 -0700 Subject: [PATCH 12/14] Clarify that you can use -d and --rm together now Signed-off-by: Misty Stanley-Jones (cherry picked from commit c63485b47d40dd22b68fe8f509637a7327330422) Signed-off-by: Andrew Hsu --- components/cli/docs/reference/run.md | 119 ++++++++++++++------------- 1 file changed, 60 insertions(+), 59 deletions(-) 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 From 2cf204719f270d0c1393b1e3755ca0dee130f050 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 4 Jul 2017 03:09:56 -0700 Subject: [PATCH 13/14] Add missing API documentatoin for DataPathAddr COmmit 0307fe1a0bcdc02583a24add41eb783c117bad8c added a new `DataPathAddr` property to the swarm/init and swarm/join endpoints. This property was not yet added to the documentation. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit c79c16910c0f3d6e88f2dc6ef609ecc3b02ccef9) Conflicts: components/engine/docs/api/version-history.md Signed-off-by: Andrew Hsu --- components/engine/api/swagger.yaml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) 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." From 149c1a0435bf0b549b3a21974c1e748a9ceeac6e Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 10 Jul 2017 21:15:02 -0700 Subject: [PATCH 14/14] Fix api-version history Commit c79c16910c0f3d6e88f2dc6ef609ecc3b02ccef9 inadvertently put these API changes under API 1.31, but they were added in API 1.30. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit dd5e818fabc7edf7fa4d952e62b949b224909d2a) Conflicts: components/engine/docs/api/version-history.md Signed-off-by: Andrew Hsu --- components/engine/docs/api/version-history.md | 2 ++ 1 file changed, 2 insertions(+) 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