diff --git a/docs/extend/index.md b/docs/extend/index.md index 4e8cae9855..bd0e9e1204 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -24,8 +24,9 @@ plugins using Docker Engine. For information about the legacy plugin system available in Docker Engine 1.12 and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md). -> **Note**: Docker Engine managed plugins are currently not supported -on Windows daemons. +> **Note** +> +> Docker Engine managed plugins are currently not supported on Windows daemons. ## Installing and using a plugin @@ -45,7 +46,12 @@ operation, such as creating a volume. In the following example, you install the `sshfs` plugin, verify that it is enabled, and use it to create a volume. -> **Note**: This example is intended for instructional purposes only. Once the volume is created, your SSH password to the remote host will be exposed as plaintext when inspecting the volume. You should delete the volume as soon as you are done with the example. +> **Note** +> +> This example is intended for instructional purposes only. Once the volume is +> created, your SSH password to the remote host will be exposed as plaintext +> when inspecting the volume. You should delete the volume as soon as you are +> done with the example. 1. Install the `sshfs` plugin. diff --git a/docs/extend/plugins_authorization.md b/docs/extend/plugins_authorization.md index d7aa66cd80..d62c795862 100644 --- a/docs/extend/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -53,8 +53,10 @@ Authorization plugins must follow the rules described in [Docker Plugin API](plu Each plugin must reside within directories described under the [Plugin discovery](plugin_api.md#plugin-discovery) section. -**Note**: the abbreviations `AuthZ` and `AuthN` mean authorization and authentication -respectively. +> **Note** +> +> The abbreviations `AuthZ` and `AuthN` mean authorization and authentication +> respectively. ## Default user authorization mechanism diff --git a/docs/extend/plugins_metrics.md b/docs/extend/plugins_metrics.md index c29aeef932..c698a5a137 100644 --- a/docs/extend/plugins_metrics.md +++ b/docs/extend/plugins_metrics.md @@ -18,9 +18,11 @@ Docker exposes internal metrics based on the prometheus format. Metrics plugins enable accessing these metrics in a consistent way by providing a Unix socket at a predefined path where the plugin can scrape the metrics. -> **Note**: that while the plugin interface for metrics is non-experimental, the naming -of the metrics and metric labels is still considered experimental and may change -in a future version. +> **Note** +> +> While the plugin interface for metrics is non-experimental, the naming of the +> metrics and metric labels is still considered experimental and may change in a +> future version. ## Creating a metrics plugin diff --git a/docs/extend/plugins_volume.md b/docs/extend/plugins_volume.md index b9a7139099..74abfd1bff 100644 --- a/docs/extend/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -90,9 +90,11 @@ provide the Docker Daemon with writeable paths on the host filesystem. The Docke daemon provides these paths to containers to consume. The Docker daemon makes the volumes available by bind-mounting the provided paths into the containers. -> **Note**: Volume plugins should *not* write data to the `/var/lib/docker/` -> directory, including `/var/lib/docker/volumes`. The `/var/lib/docker/` -> directory is reserved for Docker. +> **Note** +> +> Volume plugins should *not* write data to the `/var/lib/docker/` directory, +> including `/var/lib/docker/volumes`. The `/var/lib/docker/` directory is +> reserved for Docker. ### `/VolumeDriver.Create` diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 5f3a9578ef..80ecdf80c1 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -37,9 +37,12 @@ A context is processed recursively. So, a `PATH` includes any subdirectories and 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 - ... +```bash +$ docker build . + +Sending build context to Docker daemon 6.51 MB +... +``` The build is run by the Docker daemon, not by the CLI. The first thing a build process does is send the entire context (recursively) to the daemon. In most @@ -47,9 +50,10 @@ cases, it's best to start with an empty directory as context and keep your Dockerfile in that directory. Add only the files needed for building the Dockerfile. ->**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes ->the build to transfer the entire contents of your hard drive to the Docker ->daemon. +> **Warning** +> +> Do not use your root directory, `/`, as the `PATH` as it causes the build to +> transfer the entire contents of your hard drive to the Docker daemon. To use a file in the build context, the `Dockerfile` refers to the file specified in an instruction, for example, a `COPY` instruction. To increase the build's @@ -61,24 +65,33 @@ Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root of the context. You use the `-f` flag with `docker build` to point to a Dockerfile anywhere in your file system. - $ docker build -f /path/to/a/Dockerfile . +```bash +$ docker build -f /path/to/a/Dockerfile . +``` You can specify a repository and tag at which to save the new image if the build succeeds: - $ docker build -t shykes/myapp . +```bash +$ docker build -t shykes/myapp . +``` To tag the image into multiple repositories after the build, add multiple `-t` parameters when you run the `build` command: - $ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . +```bash +$ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest . +``` Before the Docker daemon runs the instructions in the `Dockerfile`, it performs a preliminary validation of the `Dockerfile` and returns an error if the syntax is incorrect: - $ docker build -t test/myapp . - Sending build context to Docker daemon 2.048 kB - Error response from daemon: Unknown instruction: RUNCMD +```bash +$ docker build -t test/myapp . + +Sending build context to Docker daemon 2.048 kB +Error response from daemon: Unknown instruction: RUNCMD +``` The Docker daemon runs the instructions in the `Dockerfile` one-by-one, committing the result of each instruction @@ -95,20 +108,23 @@ to accelerate the `docker build` process significantly. This is indicated by the `Using cache` message in the console output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/): - $ docker build -t svendowideit/ambassador . - Sending build context to Docker daemon 15.36 kB - Step 1/4 : FROM alpine:3.2 - ---> 31f630c65071 - Step 2/4 : MAINTAINER SvenDowideit@home.org.au - ---> Using cache - ---> 2a1c91448f5f - Step 3/4 : RUN apk update && apk add socat && rm -r /var/cache/ - ---> Using cache - ---> 21ed6e7fbb73 - Step 4/4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh - ---> Using cache - ---> 7ea8aef582cc - Successfully built 7ea8aef582cc +```bash +$ docker build -t svendowideit/ambassador . + +Sending build context to Docker daemon 15.36 kB +Step 1/4 : FROM alpine:3.2 + ---> 31f630c65071 +Step 2/4 : MAINTAINER SvenDowideit@home.org.au + ---> Using cache + ---> 2a1c91448f5f +Step 3/4 : RUN apk update && apk add socat && rm -r /var/cache/ + ---> Using cache + ---> 21ed6e7fbb73 +Step 4/4 : CMD env | grep _TCP= | (sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' && echo wait) | sh + ---> Using cache + ---> 7ea8aef582cc +Successfully built 7ea8aef582cc +``` Build cache is only used from images that have a local parent chain. This means that these images were created by previous builds or the whole chain of images @@ -128,13 +144,13 @@ builds that is provided by the [moby/buildkit](https://github.com/moby/buildkit) project. The BuildKit backend provides many benefits compared to the old implementation. For example, BuildKit can: -* Detect and skip executing unused build stages -* Parallelize building independent build stages -* Incrementally transfer only the changed files in your build context between builds -* Detect and skip transferring unused files in your build context -* Use external Dockerfile implementations with many new features -* Avoid side-effects with rest of the API (intermediate images and containers) -* Prioritize your build cache for automatic pruning +- Detect and skip executing unused build stages +- Parallelize building independent build stages +- Incrementally transfer only the changed files in your build context between builds +- Detect and skip transferring unused files in your build context +- Use external Dockerfile implementations with many new features +- Avoid side-effects with rest of the API (intermediate images and containers) +- Prioritize your build cache for automatic pruning To use the BuildKit backend, you need to set an environment variable `DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`. @@ -249,20 +265,24 @@ following lines are all treated identically: The following parser directives are supported: -* `syntax` -* `escape` +- `syntax` +- `escape` ## syntax - # syntax=[remote image reference] +```dockerfile +# syntax=[remote image reference] +``` For example: - # syntax=docker/dockerfile - # syntax=docker/dockerfile:1.0 - # syntax=docker.io/docker/dockerfile:1 - # syntax=docker/dockerfile:1.0.0-experimental - # syntax=example.com/user/repo:tag@sha256:abcdef... +```dockerfile +# syntax=docker/dockerfile +# syntax=docker/dockerfile:1.0 +# syntax=docker.io/docker/dockerfile:1 +# syntax=docker/dockerfile:1.0.0-experimental +# syntax=example.com/user/repo:tag@sha256:abcdef... +``` This feature is only enabled if the [BuildKit](#buildkit) backend is used. @@ -272,6 +292,7 @@ external implementations of builders that are distributed as Docker images and execute inside a container sandbox environment. Custom Dockerfile implementation allows you to: + - Automatically get bugfixes without updating the daemon - Make sure all users are using the same implementation to build your Dockerfile - Use the latest features without updating the daemon @@ -285,17 +306,17 @@ channels where new images are released: stable and experimental. Stable channel follows semantic versioning. For example: - - docker/dockerfile:1.0.0 - only allow immutable version 1.0.0 - - docker/dockerfile:1.0 - allow versions 1.0.* - - docker/dockerfile:1 - allow versions 1.*.* - - docker/dockerfile:latest - latest release on stable channel + - `docker/dockerfile:1.0.0` - only allow immutable version `1.0.0` + - `docker/dockerfile:1.0` - allow versions `1.0.*` + - `docker/dockerfile:1` - allow versions `1.*.*` + - `docker/dockerfile:latest` - latest release on stable channel The experimental channel uses incremental versioning with the major and minor component from the stable channel on the time of the release. For example: - - docker/dockerfile:1.0.1-experimental - only allow immutable version 1.0.1-experimental - - docker/dockerfile:1.0-experimental - latest experimental releases after 1.0 - - docker/dockerfile:experimental - latest release on experimental channel + - `docker/dockerfile:1.0.1-experimental` - only allow immutable version `1.0.1-experimental` + - `docker/dockerfile:1.0-experimental` - latest experimental releases after `1.0` + - `docker/dockerfile:experimental` - latest release on experimental channel You should choose a channel that best fits your needs. If you only want bugfixes, you should use `docker/dockerfile:1.0`. If you want to benefit from @@ -303,15 +324,20 @@ experimental features, you should use the experimental channel. If you are using the experimental channel, newer releases may not be backwards compatible, so it is recommended to use an immutable full version variant. -For master builds and nightly feature releases refer to the description in [the source repository](https://github.com/moby/buildkit/blob/master/README.md). +For master builds and nightly feature releases refer to the description in +[the source repository](https://github.com/moby/buildkit/blob/master/README.md). ## escape - # escape=\ (backslash) +```dockerfile +# escape=\ (backslash) +``` Or - # escape=` (backtick) +```dockerfile +# escape=` (backtick) +``` The `escape` directive sets the character used to escape characters in a `Dockerfile`. If not specified, the default escape character is `\`. @@ -342,13 +368,15 @@ RUN dir c:\ Results in: - PS C:\John> docker build -t cmd . - Sending build context to Docker daemon 3.072 kB - Step 1/2 : FROM microsoft/nanoserver - ---> 22738ff49c6d - Step 2/2 : COPY testfile.txt c:\RUN dir c: - GetFileAttributesEx c:RUN: The system cannot find the file specified. - PS C:\John> +```powershell +PS C:\John> docker build -t cmd . +Sending build context to Docker daemon 3.072 kB +Step 1/2 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/2 : COPY testfile.txt c:\RUN dir c: +GetFileAttributesEx c:RUN: The system cannot find the file specified. +PS C:\John> +``` One solution to the above would be to use `/` as the target of both the `COPY` instruction, and `dir`. However, this syntax is, at best, confusing as it is not @@ -358,40 +386,44 @@ natural for paths on `Windows`, and at worst, error prone as not all commands on By adding the `escape` parser directive, the following `Dockerfile` succeeds as expected with the use of natural platform semantics for file paths on `Windows`: - # escape=` +```dockerfile +# escape=` - FROM microsoft/nanoserver - COPY testfile.txt c:\ - RUN dir c:\ +FROM microsoft/nanoserver +COPY testfile.txt c:\ +RUN dir c:\ +``` Results in: - PS C:\John> docker build -t succeeds --no-cache=true . - Sending build context to Docker daemon 3.072 kB - Step 1/3 : FROM microsoft/nanoserver - ---> 22738ff49c6d - Step 2/3 : COPY testfile.txt c:\ - ---> 96655de338de - Removing intermediate container 4db9acbb1682 - Step 3/3 : RUN dir c:\ - ---> Running in a2c157f842f5 - Volume in drive C has no label. - Volume Serial Number is 7E6D-E0F7 +```powershell +PS C:\John> docker build -t succeeds --no-cache=true . +Sending build context to Docker daemon 3.072 kB +Step 1/3 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/3 : COPY testfile.txt c:\ + ---> 96655de338de +Removing intermediate container 4db9acbb1682 +Step 3/3 : RUN dir c:\ + ---> Running in a2c157f842f5 + Volume in drive C has no label. + Volume Serial Number is 7E6D-E0F7 - Directory of c:\ + Directory of c:\ - 10/05/2016 05:04 PM 1,894 License.txt - 10/05/2016 02:22 PM Program Files - 10/05/2016 02:14 PM Program Files (x86) - 10/28/2016 11:18 AM 62 testfile.txt - 10/28/2016 11:20 AM Users - 10/28/2016 11:20 AM Windows - 2 File(s) 1,956 bytes - 4 Dir(s) 21,259,096,064 bytes free - ---> 01c7f3bef04f - Removing intermediate container a2c157f842f5 - Successfully built 01c7f3bef04f - PS C:\John> +10/05/2016 05:04 PM 1,894 License.txt +10/05/2016 02:22 PM Program Files +10/05/2016 02:14 PM Program Files (x86) +10/28/2016 11:18 AM 62 testfile.txt +10/28/2016 11:20 AM Users +10/28/2016 11:20 AM Windows + 2 File(s) 1,956 bytes + 4 Dir(s) 21,259,096,064 bytes free + ---> 01c7f3bef04f +Removing intermediate container a2c157f842f5 +Successfully built 01c7f3bef04f +PS C:\John> +``` ## Environment replacement @@ -408,9 +440,9 @@ whitespace, like `${foo}_bar`. The `${variable_name}` syntax also supports a few of the standard `bash` modifiers as specified below: -* `${variable:-word}` indicates that if `variable` is set then the result +- `${variable:-word}` indicates that if `variable` is set then the result will be that value. If `variable` is not set then `word` will be the result. -* `${variable:+word}` indicates that if `variable` is set then `word` will be +- `${variable:+word}` indicates that if `variable` is set then `word` will be the result, otherwise the result is the empty string. In all cases, `word` can be any string, including additional environment @@ -421,40 +453,37 @@ for example, will translate to `$foo` and `${foo}` literals respectively. Example (parsed representation is displayed after the `#`): - FROM busybox - ENV foo /bar - WORKDIR ${foo} # WORKDIR /bar - ADD . $foo # ADD . /bar - COPY \$foo /quux # COPY $foo /quux +```dockerfile +FROM busybox +ENV foo /bar +WORKDIR ${foo} # WORKDIR /bar +ADD . $foo # ADD . /bar +COPY \$foo /quux # COPY $foo /quux +``` Environment variables are supported by the following list of instructions in the `Dockerfile`: -* `ADD` -* `COPY` -* `ENV` -* `EXPOSE` -* `FROM` -* `LABEL` -* `STOPSIGNAL` -* `USER` -* `VOLUME` -* `WORKDIR` - -as well as: - -* `ONBUILD` (when combined with one of the supported instructions above) - -> **Note**: -> prior to 1.4, `ONBUILD` instructions did **NOT** support environment -> variable, even when combined with any of the instructions listed above. +- `ADD` +- `COPY` +- `ENV` +- `EXPOSE` +- `FROM` +- `LABEL` +- `STOPSIGNAL` +- `USER` +- `VOLUME` +- `WORKDIR` +- `ONBUILD` (when combined with one of the supported instructions above) Environment variable substitution will use the same value for each variable throughout the entire instruction. In other words, in this example: - ENV abc=hello - ENV abc=bye def=$abc - ENV ghi=$abc +```dockerfile +ENV abc=hello +ENV abc=bye def=$abc +ENV ghi=$abc +``` will result in `def` having a value of `hello`, not `bye`. However, `ghi` will have a value of `bye` because it is not part of the same instruction @@ -482,7 +511,7 @@ considered as a comment and is ignored before interpreted by the CLI. Here is an example `.dockerignore` file: -``` +```gitignore # comment */temp* */*/temp* @@ -515,9 +544,9 @@ Lines starting with `!` (exclamation mark) can be used to make exceptions to exclusions. The following is an example `.dockerignore` file that uses this mechanism: -``` - *.md - !README.md +```gitignore +*.md +!README.md ``` All markdown files *except* `README.md` are excluded from the context. @@ -526,10 +555,10 @@ The placement of `!` exception rules influences the behavior: the last line of the `.dockerignore` that matches a particular file determines whether it is included or excluded. Consider the following example: -``` - *.md - !README*.md - README-secret.md +```gitignore +*.md +!README*.md +README-secret.md ``` No markdown files are included in the context except README files other than @@ -537,10 +566,10 @@ No markdown files are included in the context except README files other than Now consider this example: -``` - *.md - README-secret.md - !README*.md +```gitignore +*.md +README-secret.md +!README*.md ``` All of the README files are included. The middle line has no effect because @@ -555,19 +584,27 @@ Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve this, specify `*` as the first pattern, followed by one or more `!` exception patterns. -**Note**: For historical reasons, the pattern `.` is ignored. +> **Note** +> +> For historical reasons, the pattern `.` is ignored. ## FROM - FROM [--platform=] [AS ] +```dockerfile +FROM [--platform=] [AS ] +``` Or - FROM [--platform=] [:] [AS ] +```dockerfile +FROM [--platform=] [:] [AS ] +``` Or - FROM [--platform=] [@] [AS ] +```dockerfile +FROM [--platform=] [@] [AS ] +``` The `FROM` instruction initializes a new build stage and sets the [*Base Image*](../../glossary/#base-image) for subsequent instructions. As such, a @@ -648,43 +685,53 @@ command. In the *shell* form you can use a `\` (backslash) to continue a single RUN instruction onto the next line. For example, consider these two lines: -``` +```dockerfile RUN /bin/bash -c 'source $HOME/.bashrc; \ echo $HOME' ``` Together they are equivalent to this single line: -``` +```dockerfile RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME' ``` -> **Note**: -> To use a different shell, other than '/bin/sh', use the *exec* form -> passing in the desired shell. For example, -> `RUN ["/bin/bash", "-c", "echo hello"]` +To use a different shell, other than '/bin/sh', use the *exec* form passing in +the desired shell. For example: -> **Note**: +```dockerfile +RUN ["/bin/bash", "-c", "echo hello"] +``` + +> **Note** +> > The *exec* form is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). -> **Note**: -> Unlike the *shell* form, the *exec* form does not invoke a command shell. -> This means that normal shell processing does not happen. For example, -> `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. -> When using the exec form and executing a shell directly, as in the case for -> the shell form, it is the shell that is doing the environment variable -> expansion, not docker. +Unlike the *shell* form, the *exec* form does not invoke a command shell. +This means that normal shell processing does not happen. For example, +`RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +If you want shell processing then either use the *shell* form or execute +a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. +When using the exec form and executing a shell directly, as in the case for +the shell form, it is the shell that is doing the environment variable +expansion, not docker. + +> **Note** > -> **Note**: > In the *JSON* form, it is necessary to escape backslashes. This is > particularly relevant on Windows where the backslash is the path separator. > The following line would otherwise be treated as *shell* form due to not > being valid JSON, and fail in an unexpected way: -> `RUN ["c:\windows\system32\tasklist.exe"]` +> +> ```dockerfile +> RUN ["c:\windows\system32\tasklist.exe"] +> ``` +> > The correct syntax for this example is: -> `RUN ["c:\\windows\\system32\\tasklist.exe"]` +> +> ```dockerfile +> RUN ["c:\\windows\\system32\\tasklist.exe"] +> ``` The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like @@ -727,24 +774,23 @@ container.** These defaults can include an executable, or they can omit the executable, in which case you must specify an `ENTRYPOINT` instruction as well. -> **Note**: -> If `CMD` is used to provide default arguments for the `ENTRYPOINT` -> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified -> with the JSON array format. +If `CMD` is used to provide default arguments for the `ENTRYPOINT` instruction, +both the `CMD` and `ENTRYPOINT` instructions should be specified with the JSON +array format. -> **Note**: -> The *exec* form is parsed as a JSON array, which means that -> you must use double-quotes (") around words not single-quotes ('). +> **Note** +> +> The *exec* form is parsed as a JSON array, which means that you must use +> double-quotes (") around words not single-quotes ('). -> **Note**: -> Unlike the *shell* form, the *exec* form does not invoke a command shell. -> This means that normal shell processing does not happen. For example, -> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `CMD [ "sh", "-c", "echo $HOME" ]`. -> When using the exec form and executing a shell directly, as in the case for -> the shell form, it is the shell that is doing the environment variable -> expansion, not docker. +Unlike the *shell* form, the *exec* form does not invoke a command shell. +This means that normal shell processing does not happen. For example, +`CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +If you want shell processing then either use the *shell* form or execute +a shell directly, for example: `CMD [ "sh", "-c", "echo $HOME" ]`. +When using the exec form and executing a shell directly, as in the case for +the shell form, it is the shell that is doing the environment variable +expansion, not docker. When used in the shell or exec formats, the `CMD` instruction sets the command to be executed when running the image. @@ -752,16 +798,20 @@ to be executed when running the image. If you use the *shell* form of the `CMD`, then the `` will execute in `/bin/sh -c`: - FROM ubuntu - CMD echo "This is a test." | wc - +```dockerfile +FROM ubuntu +CMD echo "This is a test." | wc - +``` If you want to **run your** `` **without a shell** then you must express the command as a JSON array and give the full path to the executable. **This array form is the preferred format of `CMD`.** Any additional parameters must be individually expressed as strings in the array: - FROM ubuntu - CMD ["/usr/bin/wc","--help"] +```dockerfile +FROM ubuntu +CMD ["/usr/bin/wc","--help"] +``` If you would like your container to run the same executable every time, then you should consider using `ENTRYPOINT` in combination with `CMD`. See @@ -770,35 +820,40 @@ you should consider using `ENTRYPOINT` in combination with `CMD`. See If the user specifies arguments to `docker run` then they will override the default specified in `CMD`. -> **Note**: -> Don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits +> **Note** +> +> Do not confuse `RUN` with `CMD`. `RUN` actually runs a command and commits > the result; `CMD` does not execute anything at build time, but specifies > the intended command for the image. ## LABEL - LABEL = = = ... +```dockerfile +LABEL = = = ... +``` The `LABEL` instruction adds metadata to an image. A `LABEL` is a key-value pair. To include spaces within a `LABEL` value, use quotes and backslashes as you would in command-line parsing. A few usage examples: - LABEL "com.example.vendor"="ACME Incorporated" - LABEL com.example.label-with-value="foo" - LABEL version="1.0" - LABEL description="This text illustrates \ - that label-values can span multiple lines." +```dockerfile +LABEL "com.example.vendor"="ACME Incorporated" +LABEL com.example.label-with-value="foo" +LABEL version="1.0" +LABEL description="This text illustrates \ +that label-values can span multiple lines." +``` An image can have more than one label. You can specify multiple labels on a single line. Prior to Docker 1.10, this decreased the size of the final image, but this is no longer the case. You may still choose to specify multiple labels in a single instruction, in one of the following two ways: -```none +```dockerfile LABEL multi.label1="value1" multi.label2="value2" other="value3" ``` -```none +```dockerfile LABEL multi.label1="value1" \ multi.label2="value2" \ other="value3" @@ -808,21 +863,29 @@ Labels included in base or parent images (images in the `FROM` line) are inherited by your image. If a label already exists but with a different value, the most-recently-applied value overrides any previously-set value. -To view an image's labels, use the `docker inspect` command. - - "Labels": { - "com.example.vendor": "ACME Incorporated" - "com.example.label-with-value": "foo", - "version": "1.0", - "description": "This text illustrates that label-values can span multiple lines.", - "multi.label1": "value1", - "multi.label2": "value2", - "other": "value3" - }, +To view an image's labels, use the `docker image inspect` command. You can use +the `--format` option to show just the labels; + +```bash +docker image inspect --format='{{json .Config.Labels}}' myimage +``` +```json +{ + "com.example.vendor": "ACME Incorporated", + "com.example.label-with-value": "foo", + "version": "1.0", + "description": "This text illustrates that label-values can span multiple lines.", + "multi.label1": "value1", + "multi.label2": "value2", + "other": "value3" +} +``` ## MAINTAINER (deprecated) - MAINTAINER +```dockerfile +MAINTAINER +``` The `MAINTAINER` instruction sets the *Author* field of the generated images. The `LABEL` instruction is a much more flexible version of this and you should use @@ -830,13 +893,17 @@ it instead, as it enables setting any metadata you require, and can be viewed easily, for example with `docker inspect`. To set a label corresponding to the `MAINTAINER` field you could use: - LABEL maintainer="SvenDowideit@home.org.au" +```dockerfile +LABEL maintainer="SvenDowideit@home.org.au" +``` This will then be visible from `docker inspect` with the other labels. ## EXPOSE - EXPOSE [/...] +```dockerfile +EXPOSE [/...] +``` The `EXPOSE` instruction informs Docker that the container listens on the specified network ports at runtime. You can specify whether the port listens on @@ -883,8 +950,10 @@ see the ## ENV - ENV - ENV = ... +```dockerfile +ENV +ENV = ... +``` The `ENV` instruction sets the environment variable `` to the value ``. This value will be in the environment for all subsequent instructions @@ -904,14 +973,18 @@ quotes and backslashes can be used to include spaces within values. For example: - ENV myName="John Doe" myDog=Rex\ The\ Dog \ - myCat=fluffy +```dockerfile +ENV myName="John Doe" myDog=Rex\ The\ Dog \ + myCat=fluffy +``` and - ENV myName John Doe - ENV myDog Rex The Dog - ENV myCat fluffy +```dockerfile +ENV myName John Doe +ENV myDog Rex The Dog +ENV myCat fluffy +``` will yield the same net results in the final image. @@ -919,7 +992,8 @@ The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. -> **Note**: +> **Note** +> > Environment persistence can cause unexpected side effects. For example, > setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get > users on a Debian-based image. To set a value for a single command, use @@ -929,11 +1003,15 @@ change them using `docker run --env =`. ADD has two forms: -- `ADD [--chown=:] ... ` -- `ADD [--chown=:] ["",... ""]` (this form is required for paths containing -whitespace) +```dockerfile +ADD [--chown=:] ... +ADD [--chown=:] ["",... ""] +``` -> **Note**: +The latter form is required for paths containing whitespace. + +> **Note** +> > The `--chown` feature is only supported on Dockerfiles used to build Linux containers, > and will not work on Windows containers. Since user and group ownership concepts do > not translate between Linux and Windows, the use of `/etc/passwd` and `/etc/group` for @@ -950,21 +1028,41 @@ the context of the build. Each `` may contain wildcards and matching will be done using Go's [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: - ADD hom* /mydir/ # adds all files starting with "hom" - ADD hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" +To add all files starting with "hom": + +```dockerfile +ADD hom* /mydir/ +``` + +In the example below, `?` is replaced with any single character, e.g., "home.txt". + +```dockerfile +ADD hom?.txt /mydir/ +``` The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - ADD test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ - ADD test /absoluteDir/ # adds "test" to /absoluteDir/ +The example below uses a relative path, and adds "test.txt" to `/relativeDir/`: + +```dockerfile +ADD test.txt relativeDir/ +``` + +Whereas this example uses an absolute path, and adds "test.txt" to `/absoluteDir/` + +```dockerfile +ADD test.txt /absoluteDir/ +``` When adding files or directories that contain special characters (such as `[` and `]`), you need to escape those paths following the Golang rules to prevent them from being treated as a matching pattern. For example, to add a file named `arr[0].txt`, use the following; - ADD arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ +```dockerfile +ADD arr[[]0].txt /mydir/ +``` All new files and directories are created with a UID and GID of 0, unless the @@ -978,10 +1076,12 @@ username or groupname is provided, the container's root filesystem from name to integer UID or GID respectively. The following examples show valid definitions for the `--chown` flag: - ADD --chown=55:mygroup files* /somedir/ - ADD --chown=bin files* /somedir/ - ADD --chown=1 files* /somedir/ - ADD --chown=10:11 files* /somedir/ +```dockerfile +ADD --chown=55:mygroup files* /somedir/ +ADD --chown=bin files* /somedir/ +ADD --chown=1 files* /somedir/ +ADD --chown=10:11 files* /somedir/ +``` If the container root filesystem does not contain either `/etc/passwd` or `/etc/group` files and either user or group names are used in the `--chown` @@ -995,7 +1095,8 @@ to set the `mtime` on the destination file. However, like any other file processed during an `ADD`, `mtime` will not be included in the determination of whether or not the file has changed and the cache should be updated. -> **Note**: +> **Note** +> > If you build by passing a `Dockerfile` through STDIN (`docker > build - < somefile`), there is no build context, so the `Dockerfile` > can only contain a URL based `ADD` instruction. You can also pass a @@ -1003,18 +1104,18 @@ of whether or not the file has changed and the cache should be updated. > the `Dockerfile` at the root of the archive and the rest of the > archive will be used as the context of the build. -> **Note**: -> If your URL files are protected using authentication, you -> will need to use `RUN wget`, `RUN curl` or use another tool from -> within the container as the `ADD` instruction does not support -> authentication. +If your URL files are protected using authentication, you need to use `RUN wget`, +`RUN curl` or use another tool from within the container as the `ADD` instruction +does not support authentication. -> **Note**: +> **Note** +> > The first encountered `ADD` instruction will invalidate the cache for all > following instructions from the Dockerfile if the contents of `` have > changed. This includes invalidating the cache for `RUN` instructions. > See the [`Dockerfile` Best Practices -guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) for more information. +guide](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +> for more information. `ADD` obeys the following rules: @@ -1037,7 +1138,8 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. -> **Note**: +> **Note** +> > The directory itself is not copied, just its contents. - If `` is a *local* tar archive in a recognized compression format @@ -1049,7 +1151,8 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi 2. The contents of the source tree, with conflicts resolved in favor of "2." on a file-by-file basis. - > **Note**: + > **Note** + > > Whether a file is identified as a recognized compression format or not > is done solely based on the contents of the file, not the name of the file. > For example, if an empty file happens to end with `.tar.gz` this will not @@ -1076,11 +1179,15 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi COPY has two forms: -- `COPY [--chown=:] ... ` -- `COPY [--chown=:] ["",... ""]` (this form is required for paths containing -whitespace) +```dockerfile +COPY [--chown=:] ... +COPY [--chown=:] ["",... ""] +``` -> **Note**: +This latter form is required for paths containing whitespace + +> **Note** +> > The `--chown` feature is only supported on Dockerfiles used to build Linux containers, > and will not work on Windows containers. Since user and group ownership concepts do > not translate between Linux and Windows, the use of `/etc/passwd` and `/etc/group` for @@ -1097,22 +1204,41 @@ of the build. Each `` may contain wildcards and matching will be done using Go's [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: - COPY hom* /mydir/ # adds all files starting with "hom" - COPY hom?.txt /mydir/ # ? is replaced with any single character, e.g., "home.txt" +To add all files starting with "hom": + +```dockerfile +COPY hom* /mydir/ +``` + +In the example below, `?` is replaced with any single character, e.g., "home.txt". + +```dockerfile +COPY hom?.txt /mydir/ +``` The `` is an absolute path, or a path relative to `WORKDIR`, into which the source will be copied inside the destination container. - COPY test relativeDir/ # adds "test" to `WORKDIR`/relativeDir/ - COPY test /absoluteDir/ # adds "test" to /absoluteDir/ +The example below uses a relative path, and adds "test.txt" to `/relativeDir/`: +```dockerfile +COPY test.txt relativeDir/ +``` + +Whereas this example uses an absolute path, and adds "test.txt" to `/absoluteDir/` + +```dockerfile +COPY test.txt /absoluteDir/ +``` When copying files or directories that contain special characters (such as `[` and `]`), you need to escape those paths following the Golang rules to prevent -them from being treated as a matching pattern. For example, to copy a file +them from being treated as a matching pattern. For example, to add a file named `arr[0].txt`, use the following; - COPY arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ +```dockerfile +ADD arr[[]0].txt /mydir/ +``` All new files and directories are created with a UID and GID of 0, unless the optional `--chown` flag specifies a given username, groupname, or UID/GID @@ -1125,17 +1251,20 @@ username or groupname is provided, the container's root filesystem from name to integer UID or GID respectively. The following examples show valid definitions for the `--chown` flag: - COPY --chown=55:mygroup files* /somedir/ - COPY --chown=bin files* /somedir/ - COPY --chown=1 files* /somedir/ - COPY --chown=10:11 files* /somedir/ +```dockerfile +COPY --chown=55:mygroup files* /somedir/ +COPY --chown=bin files* /somedir/ +COPY --chown=1 files* /somedir/ +COPY --chown=10:11 files* /somedir/ +``` If the container root filesystem does not contain either `/etc/passwd` or `/etc/group` files and either user or group names are used in the `--chown` flag, the build will fail on the `COPY` operation. Using numeric IDs requires -no lookup and will not depend on container root filesystem content. +no lookup and does not depend on container root filesystem content. -> **Note**: +> **Note** +> > If you build using STDIN (`docker build - < somefile`), there is no > build context, so `COPY` can't be used. @@ -1156,7 +1285,8 @@ image with the same name is attempted to be used instead. - If `` is a directory, the entire contents of the directory are copied, including filesystem metadata. -> **Note**: +> **Note** +> > The directory itself is not copied, just its contents. - If `` is any other kind of file, it is copied individually along with @@ -1178,17 +1308,26 @@ image with the same name is attempted to be used instead. ENTRYPOINT has two forms: -- `ENTRYPOINT ["executable", "param1", "param2"]` - (*exec* form, preferred) -- `ENTRYPOINT command param1 param2` - (*shell* form) +The *exec* form, which is the preferred form: + +```dockerfile +ENTRYPOINT ["executable", "param1", "param2"] +``` + +The *shell* form: + +```dockerfile +ENTRYPOINT command param1 param2 +``` An `ENTRYPOINT` allows you to configure a container that will run as an executable. -For example, the following will start nginx with its default content, listening +For example, the following starts nginx with its default content, listening on port 80: - docker run -i -t --rm -p 80:80 nginx +```bash +$ docker run -i -t --rm -p 80:80 nginx +``` Command line arguments to `docker run ` will be appended after all elements in an *exec* form `ENTRYPOINT`, and will override all elements specified @@ -1213,35 +1352,43 @@ You can use the *exec* form of `ENTRYPOINT` to set fairly stable default command and arguments and then use either form of `CMD` to set additional defaults that are more likely to be changed. - FROM ubuntu - ENTRYPOINT ["top", "-b"] - CMD ["-c"] +```dockerfile +FROM ubuntu +ENTRYPOINT ["top", "-b"] +CMD ["-c"] +``` When you run the container, you can see that `top` is the only process: - $ docker run -it --rm --name test top -H - top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 - Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - %Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st - KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers - KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem +```bash +$ docker run -it --rm --name test top -H - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top +top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05 +Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie +%Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st +KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers +KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top +``` To examine the result further, you can use `docker exec`: - $ docker exec -it test ps aux - USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND - root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H - root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux +```bash +$ docker exec -it test ps aux + +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H +root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux +``` And you can gracefully request `top` to shut down using `docker stop test`. The following `Dockerfile` shows using the `ENTRYPOINT` to run Apache in the foreground (i.e., as `PID 1`): -``` +```dockerfile FROM debian:stable RUN apt-get update && apt-get install -y --force-yes apache2 EXPOSE 80 443 @@ -1275,7 +1422,7 @@ on shutdown, or are co-ordinating more than one executable, you may need to ensu that the `ENTRYPOINT` script receives the Unix signals, passes them on, and then does some more work: -``` +```bash #!/bin/sh # Note: I've written this using sh so it works in the busybox container too @@ -1302,41 +1449,48 @@ and then ask the script to stop Apache: ```bash $ docker exec -it test ps aux + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND root 1 0.1 0.0 4448 692 ? Ss+ 00:42 0:00 /bin/sh /run.sh 123 cmd cmd2 root 19 0.0 0.2 71304 4440 ? Ss 00:42 0:00 /usr/sbin/apache2 -k start www-data 20 0.2 0.2 360468 6004 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start www-data 21 0.2 0.2 360468 6000 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start root 81 0.0 0.1 15572 2140 ? R+ 00:44 0:00 ps aux + $ docker top test + PID USER COMMAND 10035 root {run.sh} /bin/sh /run.sh 123 cmd cmd2 10054 root /usr/sbin/apache2 -k start 10055 33 /usr/sbin/apache2 -k start 10056 33 /usr/sbin/apache2 -k start + $ /usr/bin/time docker stop test + test real 0m 0.27s user 0m 0.03s sys 0m 0.03s ``` -> **Note:** you can override the `ENTRYPOINT` setting using `--entrypoint`, +> **Note** +> +> You can override the `ENTRYPOINT` setting using `--entrypoint`, > but this can only set the binary to *exec* (no `sh -c` will be used). -> **Note**: +> **Note** +> > The *exec* form is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). -> **Note**: -> Unlike the *shell* form, the *exec* form does not invoke a command shell. -> This means that normal shell processing does not happen. For example, -> `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. -> If you want shell processing then either use the *shell* form or execute -> a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`. -> When using the exec form and executing a shell directly, as in the case for -> the shell form, it is the shell that is doing the environment variable -> expansion, not docker. +Unlike the *shell* form, the *exec* form does not invoke a command shell. +This means that normal shell processing does not happen. For example, +`ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +If you want shell processing then either use the *shell* form or execute +a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`. +When using the exec form and executing a shell directly, as in the case for +the shell form, it is the shell that is doing the environment variable +expansion, not docker. ### Shell form ENTRYPOINT example @@ -1346,57 +1500,75 @@ and will ignore any `CMD` or `docker run` command line arguments. To ensure that `docker stop` will signal any long running `ENTRYPOINT` executable correctly, you need to remember to start it with `exec`: - FROM ubuntu - ENTRYPOINT exec top -b +```dockerfile +FROM ubuntu +ENTRYPOINT exec top -b +``` When you run this image, you'll see the single `PID 1` process: - $ docker run -it --rm --name test top - Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached - CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq - Load average: 0.08 0.03 0.05 2/98 6 - PID PPID USER STAT VSZ %VSZ %CPU COMMAND - 1 0 root R 3164 0% 0% top -b +```bash +$ docker run -it --rm --name test top -Which will exit cleanly on `docker stop`: +Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached +CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq +Load average: 0.08 0.03 0.05 2/98 6 + PID PPID USER STAT VSZ %VSZ %CPU COMMAND + 1 0 root R 3164 0% 0% top -b +``` - $ /usr/bin/time docker stop test - test - real 0m 0.20s - user 0m 0.02s - sys 0m 0.04s +Which exits cleanly on `docker stop`: + +```bash +$ /usr/bin/time docker stop test + +test +real 0m 0.20s +user 0m 0.02s +sys 0m 0.04s +``` If you forget to add `exec` to the beginning of your `ENTRYPOINT`: - FROM ubuntu - ENTRYPOINT top -b - CMD --ignored-param1 +```dockerfile +FROM ubuntu +ENTRYPOINT top -b +CMD --ignored-param1 +``` You can then run it (giving it a name for the next step): - $ docker run -it --name test top --ignored-param2 - Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached - CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq - Load average: 0.01 0.02 0.05 2/101 7 - PID PPID USER STAT VSZ %VSZ %CPU COMMAND - 1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2 - 7 1 root R 3164 0% 0% top -b +```bash +$ docker run -it --name test top --ignored-param2 + +Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached +CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq +Load average: 0.01 0.02 0.05 2/101 7 + PID PPID USER STAT VSZ %VSZ %CPU COMMAND + 1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2 + 7 1 root R 3164 0% 0% top -b +``` You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`. If you then run `docker stop test`, the container will not exit cleanly - the `stop` command will be forced to send a `SIGKILL` after the timeout: - $ docker exec -it test ps aux - PID USER COMMAND - 1 root /bin/sh -c top -b cmd cmd2 - 7 root top -b - 8 root ps aux - $ /usr/bin/time docker stop test - test - real 0m 10.19s - user 0m 0.04s - sys 0m 0.03s +```bash +$ docker exec -it test ps aux + +PID USER COMMAND + 1 root /bin/sh -c top -b cmd cmd2 + 7 root top -b + 8 root ps aux + +$ /usr/bin/time docker stop test + +test +real 0m 10.19s +user 0m 0.04s +sys 0m 0.03s +``` ### Understand how CMD and ENTRYPOINT interact @@ -1421,13 +1593,17 @@ The table below shows what command is executed for different `ENTRYPOINT` / `CMD | **CMD ["p1_cmd", "p2_cmd"]** | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry p1_cmd p2_cmd | | **CMD exec_cmd p1_cmd** | /bin/sh -c exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd | -> **Note**: If `CMD` is defined from the base image, setting `ENTRYPOINT` will +> **Note** +> +> If `CMD` is defined from the base image, setting `ENTRYPOINT` will > reset `CMD` to an empty value. In this scenario, `CMD` must be defined in the > current image to have a value. ## VOLUME - VOLUME ["/data"] +```dockerfile +VOLUME ["/data"] +``` The `VOLUME` instruction creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other @@ -1435,17 +1611,19 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to -[*Share Directories via Volumes*](https://docs.docker.com/engine/tutorials/dockervolumes/) +[*Share Directories via Volumes*](https://docs.docker.com/storage/volumes/) documentation. The `docker run` command initializes the newly created volume with any data that exists at the specified location within the base image. For example, consider the following Dockerfile snippet: - FROM ubuntu - RUN mkdir /myvol - RUN echo "hello world" > /myvol/greeting - VOLUME /myvol +```dockerfile +FROM ubuntu +RUN mkdir /myvol +RUN echo "hello world" > /myvol/greeting +VOLUME /myvol +``` This Dockerfile results in an image that causes `docker run` to create a new mount point at `/myvol` and copy the `greeting` file @@ -1476,9 +1654,15 @@ Keep the following things in mind about volumes in the `Dockerfile`. ## USER - USER [:] +```dockerfile +USER [:] +``` + or - USER [:] + +```dockerfile +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 @@ -1487,25 +1671,28 @@ group (or GID) to use when running the image and for any `RUN`, `CMD` and > Note that when specifying a group for the user, the user will have _only_ the > specified group membership. Any other configured group memberships will be ignored. -> **Warning**: +> **Warning** +> > When the user doesn't have a primary group then the image (or the next > instructions) will be run with the `root` group. - +> > On Windows, the user must be created first if it's not a built-in account. > This can be done with the `net user` command called as part of a Dockerfile. ```dockerfile - FROM microsoft/windowsservercore - # Create Windows user in the container - RUN net user /add patrick - # Set it for subsequent commands - USER patrick +FROM microsoft/windowsservercore +# Create Windows user in the container +RUN net user /add patrick +# Set it for subsequent commands +USER patrick ``` ## WORKDIR - WORKDIR /path/to/workdir +```dockerfile +WORKDIR /path/to/workdir +``` The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`. @@ -1516,61 +1703,71 @@ 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 - WORKDIR c - RUN pwd +```dockerfile +WORKDIR /a +WORKDIR b +WORKDIR c +RUN pwd +``` -The output of the final `pwd` command in this `Dockerfile` would be -`/a/b/c`. +The output of the final `pwd` command in this `Dockerfile` would be `/a/b/c`. The `WORKDIR` instruction can resolve environment variables previously set using `ENV`. You can only use environment variables explicitly set in the `Dockerfile`. For example: - ENV DIRPATH /path - WORKDIR $DIRPATH/$DIRNAME - RUN pwd +```dockerfile +ENV DIRPATH /path +WORKDIR $DIRPATH/$DIRNAME +RUN pwd +``` The output of the final `pwd` command in this `Dockerfile` would be `/path/$DIRNAME` ## ARG - ARG [=] +```dockerfile +ARG [=] +``` The `ARG` instruction defines a variable that users can pass at build-time to the builder with the `docker build` command using the `--build-arg =` flag. If a user specifies a build argument that was not defined in the Dockerfile, the build outputs a warning. -``` +```console [Warning] One or more build-args [foo] were not consumed. ``` A Dockerfile may include one or more `ARG` instructions. For example, the following is a valid Dockerfile: -``` +```dockerfile FROM busybox ARG user1 ARG buildno -... +# ... ``` -> **Warning:** It is not recommended to use build-time variables for -> passing secrets like github keys, user credentials etc. Build-time variable -> values are visible to any user of the image with the `docker history` command. +> **Warning:** +> +> It is not recommended to use build-time variables for passing secrets like +> github keys, user credentials etc. Build-time variable values are visible to +> any user of the image with the `docker history` command. +> +> Refer to the ["build images with BuildKit"](https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information) +> section to learn about secure ways to use secrets when building images. ### Default values An `ARG` instruction can optionally include a default value: -``` +```dockerfile FROM busybox ARG user1=someuser ARG buildno=1 -... +# ... ``` If an `ARG` instruction has a default value and if there is no value passed @@ -1582,16 +1779,16 @@ An `ARG` variable definition comes into effect from the line on which it is defined in the `Dockerfile` not from the argument's use on the command-line or elsewhere. For example, consider this Dockerfile: -``` -1 FROM busybox -2 USER ${user:-some_user} -3 ARG user -4 USER $user -... +```dockerfile +FROM busybox +USER ${user:-some_user} +ARG user +USER $user +# ... ``` A user builds this file by calling: -``` +```bash $ docker build --build-arg user=what_user . ``` @@ -1604,7 +1801,7 @@ An `ARG` instruction goes out of scope at the end of the build stage where it was defined. To use an arg in multiple stages, each stage must include the `ARG` instruction. -``` +```dockerfile FROM busybox ARG SETTINGS RUN ./run/setup $SETTINGS @@ -1621,15 +1818,16 @@ available to the `RUN` instruction. Environment variables defined using the `ENV` instruction always override an `ARG` instruction of the same name. Consider this Dockerfile with an `ENV` and `ARG` instruction. +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER v1.0.0 +RUN echo $CONT_IMG_VER ``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER v1.0.0 -4 RUN echo $CONT_IMG_VER -``` + Then, assume this image is built with this command: -``` +```bash $ docker build --build-arg CONT_IMG_VER=v2.0.1 . ``` @@ -1641,17 +1839,17 @@ arguments or inherited from environment, from its point of definition. Using the example above but a different `ENV` specification you can create more useful interactions between `ARG` and `ENV` instructions: -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0} -4 RUN echo $CONT_IMG_VER +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0} +RUN echo $CONT_IMG_VER ``` Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. Consider a docker build without the `--build-arg` flag: -``` +```bash $ docker build . ``` @@ -1668,18 +1866,18 @@ Dockerfile instructions.](#environment-replacement) Docker has a set of predefined `ARG` variables that you can use without a corresponding `ARG` instruction in the Dockerfile. -* `HTTP_PROXY` -* `http_proxy` -* `HTTPS_PROXY` -* `https_proxy` -* `FTP_PROXY` -* `ftp_proxy` -* `NO_PROXY` -* `no_proxy` +- `HTTP_PROXY` +- `http_proxy` +- `HTTPS_PROXY` +- `https_proxy` +- `FTP_PROXY` +- `ftp_proxy` +- `NO_PROXY` +- `no_proxy` To use these, simply pass them on the command line using the flag: -``` +```bash --build-arg = ``` @@ -1690,7 +1888,7 @@ sensitive authentication information in an `HTTP_PROXY` variable. For example, consider building the following Dockerfile using `--build-arg HTTP_PROXY=http://user:pass@proxy.lon.example.com` -``` Dockerfile +```dockerfile FROM ubuntu RUN echo "Hello World" ``` @@ -1703,7 +1901,7 @@ build does not result in a cache miss. If you need to override this behaviour then you may do so by adding an `ARG` statement in the Dockerfile as follows: -``` Dockerfile +```dockerfile FROM ubuntu ARG HTTP_PROXY RUN echo "Hello World" @@ -1723,14 +1921,14 @@ the `--platform` flag on `docker build`. The following `ARG` variables are set automatically: -* `TARGETPLATFORM` - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`. -* `TARGETOS` - OS component of TARGETPLATFORM -* `TARGETARCH` - architecture component of TARGETPLATFORM -* `TARGETVARIANT` - variant component of TARGETPLATFORM -* `BUILDPLATFORM` - platform of the node performing the build. -* `BUILDOS` - OS component of BUILDPLATFORM -* `BUILDARCH` - architecture component of BUILDPLATFORM -* `BUILDVARIANT` - variant component of BUILDPLATFORM +- `TARGETPLATFORM` - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`. +- `TARGETOS` - OS component of TARGETPLATFORM +- `TARGETARCH` - architecture component of TARGETPLATFORM +- `TARGETVARIANT` - variant component of TARGETPLATFORM +- `BUILDPLATFORM` - platform of the node performing the build. +- `BUILDOS` - OS component of BUILDPLATFORM +- `BUILDARCH` - architecture component of BUILDPLATFORM +- `BUILDVARIANT` - variant component of BUILDPLATFORM These arguments are defined in the global scope so are not automatically available inside build stages or for your `RUN` commands. To expose one of @@ -1757,16 +1955,16 @@ matching `ARG` statement in the `Dockerfile`. For example, consider these two Dockerfile: -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 RUN echo $CONT_IMG_VER +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +RUN echo $CONT_IMG_VER ``` -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 RUN echo hello +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +RUN echo hello ``` If you specify `--build-arg CONT_IMG_VER=` on the command line, in both @@ -1777,12 +1975,13 @@ changes, we get a cache miss. Consider another example under the same command line: +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER $CONT_IMG_VER +RUN echo $CONT_IMG_VER ``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER $CONT_IMG_VER -4 RUN echo $CONT_IMG_VER -``` + In this example, the cache miss occurs on line 3. The miss happens because the variable's value in the `ENV` references the `ARG` variable and that variable is changed through the command line. In this example, the `ENV` @@ -1791,11 +1990,11 @@ command causes the image to include the value. If an `ENV` instruction overrides an `ARG` instruction of the same name, like this Dockerfile: -``` -1 FROM ubuntu -2 ARG CONT_IMG_VER -3 ENV CONT_IMG_VER hello -4 RUN echo $CONT_IMG_VER +```dockerfile +FROM ubuntu +ARG CONT_IMG_VER +ENV CONT_IMG_VER hello +RUN echo $CONT_IMG_VER ``` Line 3 does not cause a cache miss because the value of `CONT_IMG_VER` is a @@ -1804,7 +2003,9 @@ the `RUN` (line 4) doesn't change between builds. ## ONBUILD - ONBUILD [INSTRUCTION] +```dockerfile +ONBUILD +``` The `ONBUILD` instruction adds to the image a *trigger* instruction to be executed at a later time, when the image is used as the base for @@ -1851,18 +2052,24 @@ Here's how it works: For example you might add something like this: - [...] - ONBUILD ADD . /app/src - ONBUILD RUN /usr/local/bin/python-build --dir /app/src - [...] +```dockerfile +ONBUILD ADD . /app/src +ONBUILD RUN /usr/local/bin/python-build --dir /app/src +``` -> **Warning**: Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed. +> **Warning** +> +> Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed. -> **Warning**: The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. +> **Warning** +> +> The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions. ## STOPSIGNAL - STOPSIGNAL signal +```dockerfile +STOPSIGNAL signal +``` The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, @@ -1872,8 +2079,8 @@ or a signal name in the format SIGNAME, for instance SIGKILL. The `HEALTHCHECK` instruction has two forms: -* `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container) -* `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image) +- `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container) +- `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image) The `HEALTHCHECK` instruction tells Docker how to test a container to check that it is still working. This can detect cases such as a web server that is stuck in @@ -1887,10 +2094,10 @@ After a certain number of consecutive failures, it becomes `unhealthy`. The options that can appear before `CMD` are: -* `--interval=DURATION` (default: `30s`) -* `--timeout=DURATION` (default: `30s`) -* `--start-period=DURATION` (default: `0s`) -* `--retries=N` (default: `3`) +- `--interval=DURATION` (default: `30s`) +- `--timeout=DURATION` (default: `30s`) +- `--start-period=DURATION` (default: `0s`) +- `--retries=N` (default: `3`) The health check will first run **interval** seconds after the container is started, and then again **interval** seconds after each previous check completes. @@ -1923,8 +2130,10 @@ The possible values are: For example, to check every five minutes or so that a web-server is able to serve the site's main page within three seconds: - HEALTHCHECK --interval=5m --timeout=3s \ - CMD curl -f http://localhost/ || exit 1 +```dockerfile +HEALTHCHECK --interval=5m --timeout=3s \ + CMD curl -f http://localhost/ || exit 1 +``` To help debug failing probes, any output text (UTF-8 encoded) that the command writes on stdout or stderr will be stored in the health status and can be queried with @@ -1939,7 +2148,9 @@ The `HEALTHCHECK` feature was added in Docker 1.12. ## SHELL - SHELL ["executable", "parameters"] +```dockerfile +SHELL ["executable", "parameters"] +``` The `SHELL` instruction allows the default shell used for the *shell* form of commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on @@ -1953,21 +2164,23 @@ well as alternate shells available including `sh`. The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides all previous `SHELL` instructions, and affects all subsequent instructions. For example: - FROM microsoft/windowsservercore +```dockerfile +FROM microsoft/windowsservercore - # Executed as cmd /S /C echo default - RUN echo default +# Executed as cmd /S /C echo default +RUN echo default - # Executed as cmd /S /C powershell -command Write-Host default - RUN powershell -command Write-Host default +# Executed as cmd /S /C powershell -command Write-Host default +RUN powershell -command Write-Host default - # Executed as powershell -command Write-Host hello - SHELL ["powershell", "-command"] - RUN Write-Host hello +# Executed as powershell -command Write-Host hello +SHELL ["powershell", "-command"] +RUN Write-Host hello - # Executed as cmd /S /C echo hello - SHELL ["cmd", "/S", "/C"] - RUN echo hello +# Executed as cmd /S /C echo hello +SHELL ["cmd", "/S", "/C"] +RUN echo hello +``` The following instructions can be affected by the `SHELL` instruction when the *shell* form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`. @@ -1975,13 +2188,15 @@ The following instructions can be affected by the `SHELL` instruction when the The following example is a common pattern found on Windows which can be streamlined by using the `SHELL` instruction: - ... - RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" - ... +```dockerfile +RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +``` The command invoked by docker will be: - cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +```powershell +cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" +``` This is inefficient for two reasons. First, there is an un-necessary cmd.exe command processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell* @@ -1990,9 +2205,9 @@ form requires an extra `powershell -command` prefixing the command. To make this more efficient, one of two mechanisms can be employed. One is to use the JSON form of the RUN command such as: - ... - RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] - ... +```dockerfile +RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] +``` While the JSON form is unambiguous and does not use the un-necessary cmd.exe, it does require more verbosity through double-quoting and escaping. The alternate @@ -2000,48 +2215,52 @@ mechanism is to use the `SHELL` instruction and the *shell* form, making a more natural syntax for Windows users, especially when combined with the `escape` parser directive: - # escape=` +```dockerfile +# escape=` - FROM microsoft/nanoserver - SHELL ["powershell","-command"] - RUN New-Item -ItemType Directory C:\Example - ADD Execute-MyCmdlet.ps1 c:\example\ - RUN c:\example\Execute-MyCmdlet -sample 'hello world' +FROM microsoft/nanoserver +SHELL ["powershell","-command"] +RUN New-Item -ItemType Directory C:\Example +ADD Execute-MyCmdlet.ps1 c:\example\ +RUN c:\example\Execute-MyCmdlet -sample 'hello world' +``` Resulting in: - PS E:\docker\build\shell> docker build -t shell . - Sending build context to Docker daemon 4.096 kB - Step 1/5 : FROM microsoft/nanoserver - ---> 22738ff49c6d - Step 2/5 : SHELL powershell -command - ---> Running in 6fcdb6855ae2 - ---> 6331462d4300 - Removing intermediate container 6fcdb6855ae2 - Step 3/5 : RUN New-Item -ItemType Directory C:\Example - ---> Running in d0eef8386e97 +```powershell +PS E:\docker\build\shell> docker build -t shell . +Sending build context to Docker daemon 4.096 kB +Step 1/5 : FROM microsoft/nanoserver + ---> 22738ff49c6d +Step 2/5 : SHELL powershell -command + ---> Running in 6fcdb6855ae2 + ---> 6331462d4300 +Removing intermediate container 6fcdb6855ae2 +Step 3/5 : RUN New-Item -ItemType Directory C:\Example + ---> Running in d0eef8386e97 - Directory: C:\ + Directory: C:\ - Mode LastWriteTime Length Name - ---- ------------- ------ ---- - d----- 10/28/2016 11:26 AM Example +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 10/28/2016 11:26 AM Example - ---> 3f2fbf1395d9 - Removing intermediate container d0eef8386e97 - Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ - ---> a955b2621c31 - Removing intermediate container b825593d39fc - Step 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world' - ---> Running in be6d8e63fe75 - hello world - ---> 8e559e9bf424 - Removing intermediate container be6d8e63fe75 - Successfully built 8e559e9bf424 - PS E:\docker\build\shell> + ---> 3f2fbf1395d9 +Removing intermediate container d0eef8386e97 +Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ + ---> a955b2621c31 +Removing intermediate container b825593d39fc +Step 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world' + ---> Running in be6d8e63fe75 +hello world + ---> 8e559e9bf424 +Removing intermediate container be6d8e63fe75 +Successfully built 8e559e9bf424 +PS E:\docker\build\shell> +``` The `SHELL` instruction could also be used to modify the way in which a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed @@ -2064,7 +2283,7 @@ builder with a syntax directive. To learn about these features, [refer to the do Below you can see some examples of Dockerfile syntax. -``` +```dockerfile # Nginx # # VERSION 0.0.1 @@ -2074,7 +2293,7 @@ LABEL Description="This image is used to start the foobar executable" Vendor="AC RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server ``` -``` +```dockerfile # Firefox over VNC # # VERSION 0.3 @@ -2093,7 +2312,7 @@ EXPOSE 5900 CMD ["x11vnc", "-forever", "-usepw", "-create"] ``` -``` +```dockerfile # Multiple images example # # VERSION 0.1 diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md index 2cdb744cde..0167d054f0 100644 --- a/docs/reference/commandline/build.md +++ b/docs/reference/commandline/build.md @@ -78,12 +78,13 @@ that succeeds, the directory is sent to the Docker daemon as the context. Local copy gives you the ability to access private repositories using local user credentials, VPN's, and so forth. -> **Note:** +> **Note** +> > If the `URL` parameter contains a fragment the system will recursively clone > the repository and its submodules using a `git clone --recursive` command. Git URLs accept context configuration in their fragment section, separated by a -colon `:`. The first part represents the reference that Git will check out, +colon (`:`). The first part represents the reference that Git will check out, 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. @@ -396,13 +397,13 @@ the command line. When `docker build` is run with the `--cgroup-parent` option the containers used in the build will be run with the [corresponding `docker run` -flag](../run.md#specifying-custom-cgroups). +flag](../run.md#specify-custom-cgroups). ### Set ulimits in container (--ulimit) Using the `--ulimit` option with `docker build` will cause each build step's container to be started using those [`--ulimit` -flag values](./run.md#set-ulimits-in-container-ulimit). +flag values](run.md#set-ulimits-in-container---ulimit). ### Set build-time variables (--build-arg) @@ -577,7 +578,9 @@ $ ls ./out vndr ``` -> **Note**: This feature requires the BuildKit backend. You can either +> **Note** +> +> This feature requires the BuildKit backend. You can either > [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx) > plugin which provides more output type options. @@ -616,7 +619,9 @@ BuildKit automatically pulls the image from the registry if needed. $ docker build --cache-from myname/myapp . ``` -> **Note**: This feature requires the BuildKit backend. You can either +> **Note** +> +> This feature requires the BuildKit backend. You can either > [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx) > plugin. The previous builder has limited support for reusing cache from > pre-pulled images. diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md index b5aef34692..072cf48830 100644 --- a/docs/reference/commandline/cli.md +++ b/docs/reference/commandline/cli.md @@ -407,7 +407,9 @@ Sometimes, multiple options can call for a more complex value string as for $ docker run -v /host:/container example/mysql ``` -> **Note**: Do not use the `-t` and `-a stderr` options together due to +> **Note** +> +> Do not use the `-t` and `-a stderr` options together due to > limitations in the `pty` implementation. All `stderr` in `pty` mode > simply goes to `stdout`. diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md index f5c0a69dcf..839ce0022f 100644 --- a/docs/reference/commandline/cp.md +++ b/docs/reference/commandline/cp.md @@ -90,7 +90,7 @@ you must be explicit with a relative or absolute path, for example: `/path/to/file:name.txt` or `./file:name.txt` It is not possible to copy certain system files such as resources under -`/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs-tmpfs), and mounts created by +`/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by the user in the container. However, you can still copy such files by manually running `tar` in `docker exec`. Both of the following examples do the same thing in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index d227cde97e..2851d23404 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -109,10 +109,10 @@ type `dockerd`. To run the daemon with debug output, use `dockerd -D` or add `"debug": true` to the `daemon.json` file. -> **Note**: In Docker 1.13 and higher, enable experimental features by starting -> `dockerd` with the `--experimental` flag or adding `"experimental": true` to the -> `daemon.json` file. In earlier Docker versions, a different build was required -> to enable experimental features. +> **Enabling experimental features** +> +> Enable experimental features by starting `dockerd` with the `--experimental` +> flag or adding `"experimental": true` to the `daemon.json` file. ## Examples @@ -135,7 +135,9 @@ interface using its IP address: `-H tcp://192.168.59.103:2375`. It is conventional to use port `2375` for un-encrypted, and port `2376` for encrypted communication with the daemon. -> **Note**: If you're using an HTTPS encrypted socket, keep in mind that only +> **Note** +> +> If you're using an HTTPS encrypted socket, keep in mind that only > TLS1.0 and greater are supported. Protocols SSLv3 and under are not > supported anymore for security reasons. @@ -300,20 +302,24 @@ The `overlay` is a very fast union filesystem. It is now merged in the main Linux kernel as of [3.18.0](https://lkml.org/lkml/2014/10/26/137). `overlay` also supports page cache sharing, this means multiple containers accessing the same file can share a single page cache entry (or entries), it makes -`overlay` as efficient with memory as `aufs` driver. Call -`dockerd -s overlay` to use it. - -> **Note**: As promising as `overlay` is, the feature is still quite young and -> should not be used in production. Most notably, using `overlay` can cause -> excessive inode consumption (especially as the number of images grows), as -> well as being incompatible with the use of RPMs. +`overlay` as efficient with memory as `aufs` driver. Call `dockerd -s overlay` +to use it. The `overlay2` uses the same fast union filesystem but takes advantage of [additional features](https://lkml.org/lkml/2015/2/11/106) added in Linux kernel 4.0 to avoid excessive inode consumption. Call `dockerd -s overlay2` to use it. -> **Note**: Both `overlay` and `overlay2` are currently unsupported on `btrfs` +> **Note** +> +> The `overlay` storage driver can cause excessive inode consumption (especially +> as the number of images grows). We recommend using the `overlay2` storage +> driver instead. + + +> **Note** +> +> Both `overlay` and `overlay2` are currently unsupported on `btrfs` > or any Copy on Write filesystem and should only be used over `ext4` partitions. On Windows, the Docker daemon supports a single image layer storage driver @@ -460,7 +466,9 @@ $ sudo service docker start ##### `dm.loopdatasize` -> **Note**: This option configures devicemapper loopback, which should not +> **Note** +> +> This option configures devicemapper loopback, which should not > be used in production. Specifies the size to use when creating the loopback file for the @@ -476,7 +484,9 @@ $ sudo dockerd --storage-opt dm.loopdatasize=200G ##### `dm.loopmetadatasize` -> **Note**: This option configures devicemapper loopback, which should not +> **Note** +> +> This option configures devicemapper loopback, which should not > be used in production. Specifies the size to use when creating the loopback file for the @@ -623,7 +633,9 @@ $ sudo dockerd --storage-opt dm.override_udev_sync_check=true When this value is `true`, the `devicemapper` continues and simply warns you the errors are happening. -> **Note**: The ideal is to pursue a `docker` daemon and environment that does +> **Note** +> +> The ideal is to pursue a `docker` daemon and environment that does > support synchronizing with `udev`. For further discussion on this > topic, see [docker#4036](https://github.com/docker/docker/issues/4036). > Otherwise, set this flag for migrating existing Docker daemons to @@ -955,7 +967,9 @@ This is the same example via the command line: $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-runc-replacement ``` -> **Note**: Defining runtime arguments via the command line is not supported. +> **Note** +> +> Defining runtime arguments via the command line is not supported. #### Options for the runtime diff --git a/docs/reference/commandline/history.md b/docs/reference/commandline/history.md index 4fa714ef1f..c6cfdd1f7b 100644 --- a/docs/reference/commandline/history.md +++ b/docs/reference/commandline/history.md @@ -68,7 +68,8 @@ output the data exactly as the template declares or, when using the `table` directive, will include column headers as well. The following example uses a template without headers and outputs the -`ID` and `CreatedSince` entries separated by a colon for the `busybox` image: +`ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` +image: ```bash $ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox diff --git a/docs/reference/commandline/image_prune.md b/docs/reference/commandline/image_prune.md index b136d66641..daea4c7021 100644 --- a/docs/reference/commandline/image_prune.md +++ b/docs/reference/commandline/image_prune.md @@ -190,7 +190,9 @@ This example removes images which have a maintainer label not set to `john`: $ docker image prune --filter="label!=maintainer=john" ``` -> **Note**: You are prompted for confirmation before the `prune` removes +> **Note** +> +> You are prompted for confirmation before the `prune` removes > anything, but you are not shown a list of what will potentially be removed. > In addition, `docker image ls` does not support negative filtering, so it > difficult to predict what images will actually be removed. diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md index 6d3dc05747..e64fd32dc1 100644 --- a/docs/reference/commandline/images.md +++ b/docs/reference/commandline/images.md @@ -184,8 +184,7 @@ dea752e4e117 511136ea3c5a ``` -> **Note**: Docker warns you if any containers exist that are using these -> untagged images. +Docker warns you if any containers exist that are using these untagged images. #### Show images with a given label @@ -309,7 +308,7 @@ output the data exactly as the template declares or, when using the `table` directive, will include column headers as well. The following example uses a template without headers and outputs the -`ID` and `Repository` entries separated by a colon for all images: +`ID` and `Repository` entries separated by a colon (`:`) for all images: ```bash $ docker images --format "{{.ID}}: {{.Repository}}" diff --git a/docs/reference/commandline/import.md b/docs/reference/commandline/import.md index f18b72b94a..686776ccb2 100644 --- a/docs/reference/commandline/import.md +++ b/docs/reference/commandline/import.md @@ -60,7 +60,7 @@ $ docker import http://example.com/exampleimage.tgz - Import to docker from a local archive. ```bash - $ docker import /path/to/exampleimage.tgz + $ docker import /path/to/exampleimage.tgz ``` ### Import from a local directory @@ -81,9 +81,12 @@ archiving with tar. If you are not root (or the sudo command) when you tar, then the ownerships might not get preserved. ## When the daemon supports multiple operating systems + If the daemon supports multiple operating systems, and the image being imported does not match the default operating system, it may be necessary to add `--platform`. This would be necessary when importing a Linux image into a Windows daemon. - # docker import --platform=linux .\linuximage.tar +```bash +$ docker import --platform=linux .\linuximage.tar +``` diff --git a/docs/reference/commandline/kill.md b/docs/reference/commandline/kill.md index 308ad88af9..942605ec52 100644 --- a/docs/reference/commandline/kill.md +++ b/docs/reference/commandline/kill.md @@ -23,7 +23,9 @@ inside the container is sent `SIGKILL` signal (default), or the signal that is specified with the `--signal` option. You can kill a container using the container's ID, ID-prefix, or name. -> **Note**: `ENTRYPOINT` and `CMD` in the *shell* form run as a subcommand of +> **Note** +> +> `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of > `/bin/sh -c`, which does not pass signals. This means that the executable is > not the container’s PID 1 and does not receive Unix signals. diff --git a/docs/reference/commandline/logs.md b/docs/reference/commandline/logs.md index 3534140e45..76502989e1 100644 --- a/docs/reference/commandline/logs.md +++ b/docs/reference/commandline/logs.md @@ -25,8 +25,10 @@ Options: The `docker logs` command batch-retrieves logs present at the time of execution. -> **Note**: this command is only functional for containers that are started with -> the `json-file` or `journald` logging driver. +> **Note** +> +> This command is only functional for containers that are started with the +> `json-file` or `journald` logging driver. For more information about selecting and configuring logging drivers, refer to [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). @@ -73,4 +75,4 @@ $ docker logs -f --until=2s Tue 14 Nov 2017 16:40:00 CET Tue 14 Nov 2017 16:40:01 CET Tue 14 Nov 2017 16:40:02 CET -``` \ No newline at end of file +``` diff --git a/docs/reference/commandline/manifest.md b/docs/reference/commandline/manifest.md index 9c54cbd4c3..d8232a1fec 100644 --- a/docs/reference/commandline/manifest.md +++ b/docs/reference/commandline/manifest.md @@ -40,7 +40,7 @@ to two images -- one for windows on amd64, and one for darwin on amd64. ### manifest inspect -``` +```bash manifest inspect --help Usage: docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST @@ -275,9 +275,10 @@ $ docker manifest create --insecure myprivateregistry.mycompany.com/repo/image:1 $ docker manifest push --insecure myprivateregistry.mycompany.com/repo/image:tag ``` -> **Note**: the `--insecure` flag is not required to annotate a manifest list, +> **Note** +> +> The `--insecure` flag is not required to annotate a manifest list, > since annotations are to a locally-stored copy of a manifest list. You may also > skip the `--insecure` flag if you are performing a `docker manifest inspect` > on a locally-stored manifest list. Be sure to keep in mind that locally-stored > manifest lists are never used by the engine on a `docker pull`. - diff --git a/docs/reference/commandline/network.md b/docs/reference/commandline/network.md index 17d9e98545..bf5e19b701 100644 --- a/docs/reference/commandline/network.md +++ b/docs/reference/commandline/network.md @@ -35,7 +35,7 @@ prune, connect, and disconnect networks. * [network create](network_create.md) * [network inspect](network_inspect.md) -* [network list](network_list.md) +* [network list](network_ls.md) * [network rm](network_rm.md) * [network prune](network_prune.md) * [network connect](network_connect.md) diff --git a/docs/reference/commandline/network_disconnect.md b/docs/reference/commandline/network_disconnect.md index 4b6691f747..4e6f2f6d31 100644 --- a/docs/reference/commandline/network_disconnect.md +++ b/docs/reference/commandline/network_disconnect.md @@ -24,7 +24,7 @@ disconnect it from the network. ## Examples ```bash - $ docker network disconnect multi-host-network container1 +$ docker network disconnect multi-host-network container1 ``` diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md index 60a0b04f6c..d48673aaba 100644 --- a/docs/reference/commandline/network_ls.md +++ b/docs/reference/commandline/network_ls.md @@ -221,7 +221,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`ID` and `Driver` entries separated by a colon for all networks: +`ID` and `Driver` entries separated by a colon (`:`) for all networks: ```bash $ docker network ls --format "{{.ID}}: {{.Driver}}" diff --git a/docs/reference/commandline/network_prune.md b/docs/reference/commandline/network_prune.md index 37a9a6d734..64d237cac3 100644 --- a/docs/reference/commandline/network_prune.md +++ b/docs/reference/commandline/network_prune.md @@ -96,7 +96,7 @@ f949d337b1f5 none null local * [network ls](network_ls.md) * [network inspect](network_inspect.md) * [network rm](network_rm.md) -* [Understand Docker container networks](https://docs.docker.com/engine/userguide/networking/) +* [Understand Docker container networks](https://docs.docker.com/network/) * [system df](system_df.md) * [container prune](container_prune.md) * [image prune](image_prune.md) diff --git a/docs/reference/commandline/network_rm.md b/docs/reference/commandline/network_rm.md index 01195a7ac1..52a4265aa7 100644 --- a/docs/reference/commandline/network_rm.md +++ b/docs/reference/commandline/network_rm.md @@ -56,4 +56,4 @@ deletion. * [network ls](network_ls.md) * [network inspect](network_inspect.md) * [network prune](network_prune.md) -* [Understand Docker container networks](https://docs.docker.com/engine/userguide/networking/) +* [Understand Docker container networks](https://docs.docker.com/network/) diff --git a/docs/reference/commandline/node_demote.md b/docs/reference/commandline/node_demote.md index bb2d5d8103..103c57f697 100644 --- a/docs/reference/commandline/node_demote.md +++ b/docs/reference/commandline/node_demote.md @@ -20,7 +20,9 @@ Options: Demotes an existing manager so that it is no longer a manager. -> **Note**: This is a cluster management command, and must be executed on a swarm +> **Note** +> +> This is a cluster management command, and must be executed on a swarm > manager node. To learn about managers and workers, refer to the [Swarm mode > section](https://docs.docker.com/engine/swarm/) in the documentation. diff --git a/docs/reference/commandline/node_inspect.md b/docs/reference/commandline/node_inspect.md index 0679fda8ff..16ad0b98c2 100644 --- a/docs/reference/commandline/node_inspect.md +++ b/docs/reference/commandline/node_inspect.md @@ -25,9 +25,12 @@ given template for each result. Go's [text/template](http://golang.org/pkg/text/template/) package describes all the details of the format. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/node_ls.md b/docs/reference/commandline/node_ls.md index 6e2b77c259..8e4eb703ad 100644 --- a/docs/reference/commandline/node_ls.md +++ b/docs/reference/commandline/node_ls.md @@ -27,9 +27,12 @@ Lists all the nodes that the Docker Swarm manager knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -41,10 +44,11 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATU 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader ``` -> **Note**: -> In the above example output, there is a hidden column of `.Self` that indicates if the -> node is the same node as the current docker daemon. A `*` (e.g., `e216jshn25ckzbvmwlnh5jr3g *`) -> means this node is the current docker daemon. +> **Note** +> +> In the above example output, there is a hidden column of `.Self` that indicates +> if the node is the same node as the current docker daemon. A `*` (e.g., +> `e216jshn25ckzbvmwlnh5jr3g *`) means this node is the current docker daemon. ### Filtering @@ -54,11 +58,11 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b The currently supported filters are: -* [id](node_ls.md#id) -* [label](node_ls.md#label) -* [membership](node_ls.md#membership) -* [name](node_ls.md#name) -* [role](node_ls.md#role) +* [id](#id) +* [label](#label) +* [membership](#membership) +* [name](#name) +* [role](#role) #### id @@ -148,7 +152,8 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`ID`, `Hostname`, and `TLS Status` entries separated by a colon for all nodes: +`ID`, `Hostname`, and `TLS Status` entries separated by a colon (`:`) for all +nodes: ```bash $ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}" diff --git a/docs/reference/commandline/node_promote.md b/docs/reference/commandline/node_promote.md index 812d3eee39..8906e67375 100644 --- a/docs/reference/commandline/node_promote.md +++ b/docs/reference/commandline/node_promote.md @@ -19,9 +19,12 @@ Options: Promotes a node to manager. This command can only be executed on a manager node. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/node_ps.md b/docs/reference/commandline/node_ps.md index 6c8e11a692..c6dcc9f891 100644 --- a/docs/reference/commandline/node_ps.md +++ b/docs/reference/commandline/node_ps.md @@ -27,9 +27,12 @@ Lists all the tasks on a Node that Docker knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -127,7 +130,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`Name` and `Image` entries separated by a colon for all tasks: +`Name` and `Image` entries separated by a colon (`:`) for all tasks: ```bash $ docker node ps --format "{{.Name}}: {{.Image}}" diff --git a/docs/reference/commandline/node_rm.md b/docs/reference/commandline/node_rm.md index fe85383a18..d64dd80db8 100644 --- a/docs/reference/commandline/node_rm.md +++ b/docs/reference/commandline/node_rm.md @@ -23,9 +23,12 @@ Options: Removes the specified nodes from a swarm. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/node_update.md b/docs/reference/commandline/node_update.md index f3cbd2e732..f8dc40db69 100644 --- a/docs/reference/commandline/node_update.md +++ b/docs/reference/commandline/node_update.md @@ -23,9 +23,12 @@ Options: Update metadata about a node, such as its availability, labels, or roles. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -57,7 +60,7 @@ $ docker node update --label-add type=queue worker1 The labels you set for nodes using `docker node update` apply only to the node entity within the swarm. Do not confuse them with the docker daemon labels for -[dockerd](https://docs.docker.com/engine/userguide/labels-custom-metadata/#daemon-labels). +[dockerd](dockerd.md). For more information about labels, refer to [apply custom metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/). diff --git a/docs/reference/commandline/plugin_inspect.md b/docs/reference/commandline/plugin_inspect.md index a324073063..63fbde3af2 100644 --- a/docs/reference/commandline/plugin_inspect.md +++ b/docs/reference/commandline/plugin_inspect.md @@ -23,10 +23,17 @@ in a JSON array. ## Examples +### Inspect a plugin -```none +The following example example inspects the `tiborvass/sample-volume-plugin` plugin: + +```bash $ docker plugin inspect tiborvass/sample-volume-plugin:latest +``` +Output is in JSON format (output below is formatted for readability): + +```json { "Id": "8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21", "Name": "tiborvass/sample-volume-plugin:latest", @@ -134,7 +141,6 @@ $ docker plugin inspect tiborvass/sample-volume-plugin:latest } ``` -(output formatted for readability) ### Formatting the output diff --git a/docs/reference/commandline/plugin_ls.md b/docs/reference/commandline/plugin_ls.md index bbf09e9c9c..3261fec8d9 100644 --- a/docs/reference/commandline/plugin_ls.md +++ b/docs/reference/commandline/plugin_ls.md @@ -75,8 +75,8 @@ using a Go template. Valid placeholders for the Go template are listed below: -Placeholder | Description ----------------|------------------------------------------------------------------------------------------ +Placeholder | Description +-------------------|------------------------------------------------------------ `.ID` | Plugin ID `.Name` | Plugin name `.Description` | Plugin description @@ -88,7 +88,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`ID` and `Name` entries separated by a colon for all plugins: +`ID` and `Name` entries separated by a colon (`:`) for all plugins: ```bash $ docker plugin ls --format "{{.ID}}: {{.Name}}" diff --git a/docs/reference/commandline/plugin_set.md b/docs/reference/commandline/plugin_set.md index 4bfdd96f4d..33ea04567c 100644 --- a/docs/reference/commandline/plugin_set.md +++ b/docs/reference/commandline/plugin_set.md @@ -32,45 +32,43 @@ by looking at the `Settable` field. Here is an extract of a plugin manifest: -``` +```json { - "config": { - ... - "args": { - "name": "myargs", - "settable": ["value"], - "value": ["foo", "bar"] - }, - "env": [ - { - "name": "DEBUG", - "settable": ["value"], - "value": "0" - }, - { - "name": "LOGGING", - "value": "1" - } - ], - "devices": [ - { - "name": "mydevice", - "path": "/dev/foo", - "settable": ["path"] - } - ], - "mounts": [ - { - "destination": "/baz", - "name": "mymount", - "options": ["rbind"], - "settable": ["source"], - "source": "/foo", - "type": "bind" - } - ], - ... - } + "config": { + "args": { + "name": "myargs", + "settable": ["value"], + "value": ["foo", "bar"] + }, + "env": [ + { + "name": "DEBUG", + "settable": ["value"], + "value": "0" + }, + { + "name": "LOGGING", + "value": "1" + } + ], + "devices": [ + { + "name": "mydevice", + "path": "/dev/foo", + "settable": ["path"] + } + ], + "mounts": [ + { + "destination": "/baz", + "name": "mymount", + "options": ["rbind"], + "settable": ["source"], + "source": "/foo", + "type": "bind" + } + ] + } } ``` @@ -111,7 +109,9 @@ $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount. /bar ``` -> **Note**: Since only `source` is settable in `mymount`, +> **Note** +> +> Since only `source` is settable in `mymount`, > `docker plugins set mymount=/bar myplugin` would work too. ### Change a device path @@ -131,7 +131,8 @@ $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$devi /dev/bar ``` -> **Note**: Since only `path` is settable in `mydevice`, +> **Note** +> Since only `path` is settable in `mydevice`, > `docker plugins set mydevice=/dev/bar myplugin` would work too. ### Change the source of the arguments diff --git a/docs/reference/commandline/port.md b/docs/reference/commandline/port.md index b49e726129..029df710f8 100644 --- a/docs/reference/commandline/port.md +++ b/docs/reference/commandline/port.md @@ -24,15 +24,24 @@ just a specific mapping: ```bash $ docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test + $ docker port test + 7890/tcp -> 0.0.0.0:4321 9876/tcp -> 0.0.0.0:1234 + $ docker port test 7890/tcp + 0.0.0.0:4321 + $ docker port test 7890/udp + 2014/06/24 11:53:36 Error: No public port '7890/udp' published for test + $ docker port test 7890 + 0.0.0.0:4321 ``` diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index ea05ecb025..41f701d297 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -72,6 +72,7 @@ The `docker ps -s` command displays two different on-disk-sizes for each contain ```bash $ docker ps -s + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE SIZE e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB) 00c6131c5e30 telegraf:1.5 "/entrypoint.sh" 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB) @@ -310,10 +311,12 @@ a volume mounted in a specific path: ```bash $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" + CONTAINER ID MOUNTS 9c3527ed70ce remote-volume $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" + CONTAINER ID MOUNTS 9c3527ed70ce remote-volume ``` @@ -418,7 +421,7 @@ exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the `ID` and -`Command` entries separated by a colon for all running containers: +`Command` entries separated by a colon (`:`) for all running containers: ```bash $ docker ps --format "{{.ID}}: {{.Command}}" diff --git a/docs/reference/commandline/pull.md b/docs/reference/commandline/pull.md index a0a9a023ad..96bafcd147 100644 --- a/docs/reference/commandline/pull.md +++ b/docs/reference/commandline/pull.md @@ -35,7 +35,7 @@ If you are behind an HTTP proxy server, for example in corporate settings, before open a connect to registry, you may need to configure the Docker daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables. To set these environment variables on a host using -`systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/engine/admin/systemd/#http-proxy) +`systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) for variables configuration. ### Concurrent downloads @@ -101,7 +101,7 @@ same image, their layers are stored only once and do not consume extra disk space. For more information about images, layers, and the content-addressable store, -refer to [understand images, containers, and storage drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/). +refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/). ### Pull an image by digest (immutable identifier) @@ -163,7 +163,9 @@ FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5 MAINTAINER some maintainer ``` -> **Note**: Using this feature "pins" an image to a specific version in time. +> **Note** +> +> Using this feature "pins" an image to a specific version in time. > Docker will therefore not pull updated versions of an image, which may include > security updates. If you want to pull an updated image, you need to change the > digest accordingly. @@ -240,7 +242,9 @@ a3ed95caeb02: Pulling fs layer ^C ``` -> **Note**: Technically, the Engine terminates a pull operation when the -> connection between the Docker Engine daemon and the Docker Engine client -> initiating the pull is lost. If the connection with the Engine daemon is -> lost for other reasons than a manual interaction, the pull is also aborted. +> **Note** +> +> The Engine terminates a pull operation when the connection between the Docker +> Engine daemon and the Docker Engine client initiating the pull is lost. If the +> connection with the Engine daemon is lost for other reasons than a manual +> interaction, the pull is also aborted. diff --git a/docs/reference/commandline/rm.md b/docs/reference/commandline/rm.md index 337a2e3245..de04a26bee 100644 --- a/docs/reference/commandline/rm.md +++ b/docs/reference/commandline/rm.md @@ -22,8 +22,7 @@ Options: ### Remove a container -This will remove the container referenced under the link -`/redis`. +This removes the container referenced under the link `/redis`. ```bash $ docker rm /redis @@ -33,7 +32,7 @@ $ docker rm /redis ### Remove a link specified with `--link` on the default bridge network -This will remove the underlying link between `/webapp` and the `/redis` +This removes the underlying link between `/webapp` and the `/redis` containers on the default bridge network, removing all network communication between the two containers. This does not apply when `--link` is used with user-specified networks. @@ -46,7 +45,7 @@ $ docker rm --link /webapp/redis ### Force-remove a running container -This command will force-remove a running container. +This command force-removes a running container. ```bash $ docker rm --force redis @@ -63,10 +62,9 @@ The main process inside the container referenced under the link `redis` will rec $ docker rm $(docker ps -a -q) ``` -This command will delete all stopped containers. The command -`docker ps -a -q` will return all existing container IDs and pass them to -the `rm` command which will delete them. Any running containers will not be -deleted. +This command deletes all stopped containers. The command +`docker ps -a -q` above returns all existing container IDs and passes them to +the `rm` command which deletes them. Running containers are not deleted. ### Remove a container and its volumes @@ -75,7 +73,7 @@ $ docker rm -v redis redis ``` -This command will remove the container and any volumes associated with it. +This command removes the container and any volumes associated with it. Note that if a volume was specified with a name, it will not be removed. ### Remove a container and selectively remove volumes @@ -83,9 +81,10 @@ Note that if a volume was specified with a name, it will not be removed. ```bash $ docker create -v awesome:/foo -v /bar --name hello redis hello + $ docker rm -v hello ``` -In this example, the volume for `/foo` will remain intact, but the volume for -`/bar` will be removed. The same behavior holds for volumes inherited with +In this example, the volume for `/foo` remains intact, but the volume for +`/bar` is removed. The same behavior holds for volumes inherited with `--volumes-from`. diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index d1375be392..e3c74e17a2 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -155,7 +155,7 @@ of all containers. The `docker run` command can be used in combination with `docker commit` to [*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md). -For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/engine/userguide/networking/). +For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/). ## Examples @@ -282,8 +282,7 @@ $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/stat ``` By bind-mounting the docker unix socket and statically linked docker -binary (refer to [get the linux binary]( -https://docs.docker.com/engine/installation/binaries/#/get-the-linux-binary)), +binary (refer to [get the linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)), you give the container the full access to create and manipulate the host's Docker daemon. @@ -311,7 +310,7 @@ docker run -v c:\foo:c: ... docker run -v c:\foo:c:\existing-directory-with-contents ... ``` -For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/engine/tutorials/dockervolumes/) +For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/) ### Add bind mounts or volumes using the --mount flag @@ -322,7 +321,7 @@ mounts in a container. The `--mount` flag supports most options that are supported by the `-v` or the `--volume` flag, but uses a different syntax. For in-depth information on the `--mount` flag, and a comparison between `--volume` and `--mount`, refer to -the [service create command reference](service_create.md#add-bind-mounts-or-volumes). +the [service create command reference](service_create.md#add-bind-mounts-volumes-or-memory-filesystems). Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. @@ -344,7 +343,7 @@ $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host machine. You can also specify `udp` and `sctp` ports. -The [Docker User Guide](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/) +The [Docker User Guide](https://docs.docker.com/network/links/) explains in detail how to manipulate ports in Docker. Note that ports which are not bound to the host (i.e., `-p 80:80` instead of @@ -449,8 +448,8 @@ com.example.label3 You can load multiple label-files by supplying multiple `--label-file` flags. For additional information on working with labels, see [*Labels - custom -metadata in Docker*](https://docs.docker.com/engine/userguide/labels-custom-metadata/) in the Docker User -Guide. +metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in +the Docker User Guide. ### Connect a container to a network (--network) @@ -476,9 +475,11 @@ or name. For `overlay` networks or custom plugins that support multi-host connectivity, containers connected to the same multi-host network but launched from different Engines can also communicate in this way. -> **Note**: Service discovery is unavailable on the default bridge network. -> Containers can communicate via their IP addresses by default. To communicate -> by name, they must be linked. +> **Note** +> +> Service discovery is unavailable on the default bridge network. Containers can +> communicate via their IP addresses by default. To communicate by name, they +> must be linked. You can disconnect a container from a network using the `docker network disconnect` command. @@ -580,9 +581,10 @@ $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc fdisk: unable to open /dev/xvdc: Operation not permitted ``` -> **Note**: `--device` cannot be safely used with ephemeral devices. Block devices -> that may be removed should not be added to untrusted containers with -> `--device`. +> **Note** +> +> The `--device` option cannot be safely used with ephemeral devices. Block devices +> that may be removed should not be added to untrusted containers with `--device`. For Windows, the format of the string passed to the `--device` option is in the form of `--device=/`. Beginning with Windows Server 2019 @@ -602,9 +604,11 @@ ports on the host visible in the container. PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 ``` -> **Note**: the `--device` option is only supported on process-isolated -> Windows containers. This option fails if the container isolation is `hyperv` -> or when running Linux Containers on Windows (LCOW). +> **Note** +> +> The `--device` option is only supported on process-isolated Windows containers. +> This option fails if the container isolation is `hyperv` or when running Linux +> Containers on Windows (LCOW). ### Access an NVIDIA GPU @@ -705,9 +709,11 @@ $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" 1024 ``` -> **Note**: If you do not provide a `hard limit`, the `soft limit` will be used -> for both values. If no `ulimits` are set, they will be inherited from -> the default `ulimits` set on the daemon. `as` option is disabled now. +> **Note** +> +> If you do not provide a `hard limit`, the `soft limit` is used +> for both values. If no `ulimits` are set, they are inherited from +> the default `ulimits` set on the daemon. The `as` option is disabled now. > In other words, the following script is not supported: > > ```bash @@ -845,23 +851,22 @@ network namespace, run this command: $ docker run --sysctl net.ipv4.ip_forward=1 someimage ``` -> **Note**: Not all sysctls are namespaced. Docker does not support changing sysctls +> **Note** +> +> Not all sysctls are namespaced. Docker does not support changing sysctls > inside of a container that also modify the host system. As the kernel > evolves we expect to see more sysctls become namespaced. #### Currently supported sysctls -- `IPC Namespace`: +IPC Namespace: - ```none - kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced - Sysctls beginning with fs.mqueue.* - ``` +- `kernel.msgmax`, `kernel.msgmnb`, `kernel.msgmni`, `kernel.sem`, + `kernel.shmall`, `kernel.shmmax`, `kernel.shmmni`, `kernel.shm_rmid_forced`. +- Sysctls beginning with `fs.mqueue.*` +- If you use the `--ipc=host` option these sysctls are not allowed. - If you use the `--ipc=host` option these sysctls will not be allowed. +Network Namespace: -- `Network Namespace`: - - Sysctls beginning with net.* - - If you use the `--network=host` option using these sysctls will not be allowed. +- Sysctls beginning with `net.*` +- If you use the `--network=host` option using these sysctls are not allowed. diff --git a/docs/reference/commandline/search.md b/docs/reference/commandline/search.md index 531fd72a6c..76d6cf7d8a 100644 --- a/docs/reference/commandline/search.md +++ b/docs/reference/commandline/search.md @@ -26,11 +26,6 @@ Options: Search [Docker Hub](https://hub.docker.com) for images -See [*Find Public Images on Docker Hub*](https://docs.docker.com/engine/tutorials/dockerrepos/#searching-for-images) for -more details on finding shared images from the command line. - -> **Note**: Search queries return a maximum of 25 results. - ## Examples ### Search images by name @@ -93,9 +88,9 @@ than one filter, then pass multiple flags (e.g. `--filter is-automated=true --fi The currently supported filters are: -* stars (int - number of stars the image has) -* is-automated (boolean - true or false) - is the image automated or not -* is-official (boolean - true or false) - is the image official or not +- stars (int - number of stars the image has) +- is-automated (boolean - true or false) - is the image automated or not +- is-official (boolean - true or false) - is the image official or not #### stars @@ -157,10 +152,9 @@ output the data exactly as the template declares. If you use the `table` directive, column headers are included as well. The following example uses a template without headers and outputs the -`Name` and `StarCount` entries separated by a colon for all images: +`Name` and `StarCount` entries separated by a colon (`:`) for all images: ```bash -{% raw %} $ docker search --format "{{.Name}}: {{.StarCount}}" nginx nginx: 5441 @@ -173,13 +167,11 @@ bitnami/nginx: 23 evild/alpine-nginx: 14 million12/nginx: 9 maxexcloo/nginx: 7 -{% endraw %} ``` This example outputs a table format: ```bash -{% raw %} $ docker search --format "table {{.Name}}\t{{.IsAutomated}}\t{{.IsOfficial}}" nginx NAME AUTOMATED OFFICIAL @@ -189,5 +181,4 @@ richarvey/nginx-php-fpm [OK] jrcs/letsencrypt-nginx-proxy-companion [OK] million12/nginx-php [OK] webdevops/php-nginx [OK] -{% endraw %} ``` diff --git a/docs/reference/commandline/secret.md b/docs/reference/commandline/secret.md index 3f13162562..83c74ee638 100644 --- a/docs/reference/commandline/secret.md +++ b/docs/reference/commandline/secret.md @@ -32,5 +32,5 @@ Manage secrets. * [secret create](secret_create.md) * [secret inspect](secret_inspect.md) -* [secret list](secret_list.md) +* [secret list](secret_ls.md) * [secret rm](secret_rm.md) diff --git a/docs/reference/commandline/secret_create.md b/docs/reference/commandline/secret_create.md index 14e0d76bfa..f61aa0c0b5 100644 --- a/docs/reference/commandline/secret_create.md +++ b/docs/reference/commandline/secret_create.md @@ -22,9 +22,12 @@ Creates a secret using standard input or from a file for the secret content. For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/secret_inspect.md b/docs/reference/commandline/secret_inspect.md index ecce0b9f50..5645484ad8 100644 --- a/docs/reference/commandline/secret_inspect.md +++ b/docs/reference/commandline/secret_inspect.md @@ -28,9 +28,12 @@ describes all the details of the format. For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/secret_ls.md b/docs/reference/commandline/secret_ls.md index 028c156303..8e8b086b9e 100644 --- a/docs/reference/commandline/secret_ls.md +++ b/docs/reference/commandline/secret_ls.md @@ -27,9 +27,12 @@ Run this command on a manager node to list the secrets in the swarm. For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -49,9 +52,9 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b The currently supported filters are: -* [id](secret_ls.md#id) (secret's ID) -* [label](secret_ls.md#label) (`label=` or `label==`) -* [name](secret_ls.md#name) (secret's name) +- [id](#id) (secret's ID) +- [label](#label) (`label=` or `label==`) +- [name](#name) (secret's name) #### id @@ -123,7 +126,7 @@ output the data exactly as the template declares or, when using the `table` directive, will include column headers as well. The following example uses a template without headers and outputs the -`ID` and `Name` entries separated by a colon for all images: +`ID` and `Name` entries separated by a colon (`:`) for all images: ```bash $ docker secret ls --format "{{.ID}}: {{.Name}}" diff --git a/docs/reference/commandline/secret_rm.md b/docs/reference/commandline/secret_rm.md index 5fd1b71019..62630cd6c8 100644 --- a/docs/reference/commandline/secret_rm.md +++ b/docs/reference/commandline/secret_rm.md @@ -24,9 +24,12 @@ Removes the specified secrets from the swarm. For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/). -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -37,8 +40,10 @@ $ docker secret rm secret.json sapth4csdo5b6wz2p5uimh5xg ``` -> **Warning**: Unlike `docker rm`, this command does not ask for confirmation -> before removing a secret. +> **Warning** +> +> Unlike `docker rm`, this command does not ask for confirmation before removing +> a secret. ## Related commands diff --git a/docs/reference/commandline/service.md b/docs/reference/commandline/service.md index 504a7f8d05..b1cff8ae44 100644 --- a/docs/reference/commandline/service.md +++ b/docs/reference/commandline/service.md @@ -31,6 +31,9 @@ Run 'docker service COMMAND --help' for more information on a command. Manage services. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index 75a52ce66e..4ae820fcc9 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -85,9 +85,12 @@ Options: Creates a service as described by the specified parameters. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -289,7 +292,7 @@ $ docker service create \ ``` For more information about labels, refer to [apply custom -metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/). +metadata](https://docs.docker.com/config/labels-custom-metadata/). ### Add bind mounts, volumes or memory filesystems @@ -327,7 +330,7 @@ your web server containers when they start. To update the website, you just update the named volume. For more information about named volumes, see -[Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/). +[Data Volumes](https://docs.docker.com/storage/volumes/). The following table describes options which apply to both bind mounts and named volumes in a service: @@ -342,14 +345,14 @@ volumes in a service: type -

The type of mount, can be either volume, bind, tmpfs, or npipe. Defaults to volume if no type is specified. +

The type of mount, can be either volume, bind, tmpfs, or npipe. Defaults to volume if no type is specified.

  • volume: mounts a managed volume into the container.
  • bind: bind-mounts a directory or file from the host into the container.
  • tmpfs: mount a tmpfs in the container
  • npipe: mounts named pipe from the host into the container (Windows containers only).
    • -

+ @@ -389,11 +392,11 @@ volumes in a service:

The Engine mounts binds and volumes read-write unless readonly option is given when mounting the bind or volume. Note that setting readonly for a - bind-mount does not make its submounts readonly on the current Linux implementation. See also bind-nonrecursive. + bind-mount does not make its submounts readonly on the current Linux implementation. See also bind-nonrecursive.

  • true or 1 or no value: Mounts the bind or volume read-only.
  • false or 0: Mounts the bind or volume read-write.
    • -

+ @@ -417,14 +420,13 @@ The following options can only be used for bind mounts (`type=bind`): consistency -

The consistency requirements for the mount; one of -

    -
  • default: Equivalent to consistent.
    • -
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
    • -
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
    • -
  • delegated: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are visible on the host.
    • -
-

+

The consistency requirements for the mount; one of

+
    +
  • default: Equivalent to consistent.
    • +
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
    • +
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
    • +
  • delegated: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are visible on the host.
    • +
@@ -506,7 +508,7 @@ The following options can only be used for named volumes (`type=volume`): creation. For example, volume-label=mylabel=hello-world,my-other-label=hello-mars. For more information about labels, refer to - apply custom metadata. + apply custom metadata. @@ -914,7 +916,7 @@ $ docker service create \ The swarm extends my-network to each node running the service. Containers on the same network can access each other using -[service discovery](https://docs.docker.com/engine/swarm/networking/#use-swarm-mode-service-discovery). +[service discovery](https://docs.docker.com/network/overlay/#container-discovery). Long form syntax of `--network` allows to specify list of aliases and driver options: `--network name=my-network,alias=web1,driver-opt=field1=value1` @@ -924,7 +926,7 @@ Long form syntax of `--network` allows to specify list of aliases and driver opt You can publish service ports to make them available externally to the swarm using the `--publish` flag. The `--publish` flag can take two different styles of arguments. The short version is positional, and allows you to specify the -published port and target port separated by a colon. +published port and target port separated by a colon (`:`). ```bash $ docker service create --name my_web --replicas 3 --publish 8080:80 nginx @@ -1068,9 +1070,10 @@ In this example, we are going to set the template of the created containers base service's name, the node's ID and hostname where it sits. ```bash -$ docker service create --name hosttempl \ - --hostname="{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}"\ - busybox top +$ docker service create \ + --name hosttempl \ + --hostname="{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}"\ + busybox top va8ew30grofhjoychbr6iot8c @@ -1105,10 +1108,11 @@ You can narrow the kind of nodes your task can land on through the using the `--generic-resource` flag (if the nodes advertise these resources): ```bash -$ docker service create --name cuda \ - --generic-resource "NVIDIA-GPU=2" \ - --generic-resource "SSD=1" \ - nvidia/cuda +$ docker service create \ + --name cuda \ + --generic-resource "NVIDIA-GPU=2" \ + --generic-resource "SSD=1" \ + nvidia/cuda ``` ## Related commands diff --git a/docs/reference/commandline/service_inspect.md b/docs/reference/commandline/service_inspect.md index 73d56ab126..9f0d53da22 100644 --- a/docs/reference/commandline/service_inspect.md +++ b/docs/reference/commandline/service_inspect.md @@ -27,9 +27,12 @@ the given template will be executed for each result. Go's [text/template](http://golang.org/pkg/text/template/) package describes all the details of the format. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -48,47 +51,47 @@ dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` produce the same result: -```none +```bash $ docker service inspect redis [ - { - "ID": "dmu1ept4cxcfe8k8lhtux3ro3", - "Version": { - "Index": 12 + { + "ID": "dmu1ept4cxcfe8k8lhtux3ro3", + "Version": { + "Index": 12 + }, + "CreatedAt": "2016-06-17T18:44:02.558012087Z", + "UpdatedAt": "2016-06-17T18:44:02.558012087Z", + "Spec": { + "Name": "redis", + "TaskTemplate": { + "ContainerSpec": { + "Image": "redis:3.0.6" }, - "CreatedAt": "2016-06-17T18:44:02.558012087Z", - "UpdatedAt": "2016-06-17T18:44:02.558012087Z", - "Spec": { - "Name": "redis", - "TaskTemplate": { - "ContainerSpec": { - "Image": "redis:3.0.6" - }, - "Resources": { - "Limits": {}, - "Reservations": {} - }, - "RestartPolicy": { - "Condition": "any", - "MaxAttempts": 0 - }, - "Placement": {} - }, - "Mode": { - "Replicated": { - "Replicas": 1 - } - }, - "UpdateConfig": {}, - "EndpointSpec": { - "Mode": "vip" - } + "Resources": { + "Limits": {}, + "Reservations": {} }, - "Endpoint": { - "Spec": {} + "RestartPolicy": { + "Condition": "any", + "MaxAttempts": 0 + }, + "Placement": {} + }, + "Mode": { + "Replicated": { + "Replicas": 1 } + }, + "UpdateConfig": {}, + "EndpointSpec": { + "Mode": "vip" + } + }, + "Endpoint": { + "Spec": {} } + } ] ``` @@ -96,13 +99,13 @@ $ docker service inspect redis $ docker service inspect dmu1ept4cxcf [ - { - "ID": "dmu1ept4cxcfe8k8lhtux3ro3", - "Version": { - "Index": 12 - }, - ... - } + { + "ID": "dmu1ept4cxcfe8k8lhtux3ro3", + "Version": { + "Index": 12 + }, + ... + } ] ``` diff --git a/docs/reference/commandline/service_logs.md b/docs/reference/commandline/service_logs.md index b74d01d6fe..fe5dcae28c 100644 --- a/docs/reference/commandline/service_logs.md +++ b/docs/reference/commandline/service_logs.md @@ -26,20 +26,25 @@ Options: The `docker service logs` command batch-retrieves logs present at the time of execution. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. The `docker service logs` command can be used with either the name or ID of a service, or with the ID of a task. If a service is passed, it will display logs for all of the containers in that service. If a task is passed, it will only display logs from that particular task. -> **Note**: This command is only functional for services that are started with +> **Note** +> +> This command is only functional for services that are started with > the `json-file` or `journald` logging driver. For more information about selecting and configuring logging drivers, refer to -[Configure logging drivers](https://docs.docker.com/engine/admin/logging/overview/). +[Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). The `docker service logs --follow` command will continue streaming the new output from the service's `STDOUT` and `STDERR`. diff --git a/docs/reference/commandline/service_ls.md b/docs/reference/commandline/service_ls.md index bd67c00f60..acb1e2c1f8 100644 --- a/docs/reference/commandline/service_ls.md +++ b/docs/reference/commandline/service_ls.md @@ -25,9 +25,12 @@ Options: This command lists services are running in the swarm. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -138,7 +141,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`ID`, `Mode`, and `Replicas` entries separated by a colon for all services: +`ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: ```bash $ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" diff --git a/docs/reference/commandline/service_ps.md b/docs/reference/commandline/service_ps.md index 072fdd3440..66c9a52d3b 100644 --- a/docs/reference/commandline/service_ps.md +++ b/docs/reference/commandline/service_ps.md @@ -25,9 +25,12 @@ Options: Lists the tasks that are running as part of the specified services. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -168,7 +171,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`Name` and `Image` entries separated by a colon for all tasks: +`Name` and `Image` entries separated by a colon (`:`) for all tasks: ```bash $ docker service ps --format "{{.Name}}: {{.Image}}" top diff --git a/docs/reference/commandline/service_rm.md b/docs/reference/commandline/service_rm.md index 866c8f4815..ecbe0dbb32 100644 --- a/docs/reference/commandline/service_rm.md +++ b/docs/reference/commandline/service_rm.md @@ -22,9 +22,12 @@ Options: Removes the specified services from the swarm. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -40,8 +43,10 @@ $ docker service ls ID NAME MODE REPLICAS IMAGE ``` -> **Warning**: Unlike `docker rm`, this command does not ask for confirmation -> before removing a running service. +> **Warning** +> +> Unlike `docker rm`, this command does not ask for confirmation before removing +> a running service. ## Related commands diff --git a/docs/reference/commandline/service_rollback.md b/docs/reference/commandline/service_rollback.md index 6c9ff05350..bd9aaec3b2 100644 --- a/docs/reference/commandline/service_rollback.md +++ b/docs/reference/commandline/service_rollback.md @@ -21,9 +21,12 @@ Options: Roll back a specified service to its previous version from the swarm. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/service_scale.md b/docs/reference/commandline/service_scale.md index 6565f3059a..ee999dffdb 100644 --- a/docs/reference/commandline/service_scale.md +++ b/docs/reference/commandline/service_scale.md @@ -24,9 +24,12 @@ services which are global mode. The command will return immediately, but the actual scaling of the service may take some time. To stop all replicas of a service while keeping the service active in the swarm you can set the scale to 0. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md index 6022fd6d83..34559555e0 100644 --- a/docs/reference/commandline/service_update.md +++ b/docs/reference/commandline/service_update.md @@ -110,9 +110,12 @@ service requires recreating the tasks for it to take effect. For example, only c setting. However, the `--force` flag will cause the tasks to be recreated anyway. This can be used to perform a rolling restart without any changes to the service parameters. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -147,9 +150,8 @@ point, effectively removing the `test-data` volume. Each command returns the service name. - The `--mount-add` flag takes the same parameters as the `--mount` flag on - `service create`. Refer to the [volumes and - bind mounts](service_create.md#volumes-and-bind-mounts-mount) section in the - `service create` reference for details. + `service create`. Refer to the [volumes and bind mounts](service_create.md#add-bind-mounts-volumes-or-memory-filesystems) + section in the `service create` reference for details. - The `--mount-rm` flag takes the `target` path of the mount. @@ -179,7 +181,7 @@ myservice Use the `--publish-add` or `--publish-rm` flags to add or remove a published port for a service. You can use the short or long syntax discussed in the -[docker service create](service_create/#publish-service-ports-externally-to-the-swarm) +[docker service create](service_create.md#publish-service-ports-externally-to-the-swarm--p---publish) reference. The following example adds a published service port to an existing service. @@ -194,7 +196,7 @@ $ docker service update \ Use the `--network-add` or `--network-rm` flags to add or remove a network for a service. You can use the short or long syntax discussed in the -[docker service create](service_create/#attach-a-service-to-an-existing-network-network) +[docker service create](service_create.md#attach-a-service-to-an-existing-network---network) reference. The following example adds a new alias name to an existing service already connected to network my-network: @@ -288,13 +290,13 @@ $ docker service update \ ### Update services using templates Some flags of `service update` support the use of templating. -See [`service create`](./service_create.md#templating) for the reference. +See [`service create`](service_create.md#create-services-using-templates) for the reference. ### Specify isolation mode (Windows) `service update` supports the same `--isolation` flag as `service create` -See [`service create`](./service_create.md) for the reference. +See [`service create`](service_create.md) for the reference. ## Related commands diff --git a/docs/reference/commandline/stack_deploy.md b/docs/reference/commandline/stack_deploy.md index 356401a3f3..0be6dc50c0 100644 --- a/docs/reference/commandline/stack_deploy.md +++ b/docs/reference/commandline/stack_deploy.md @@ -30,10 +30,12 @@ Options: Create and update a stack from a `compose` file on the swarm. -> **Note**: This is a cluster management command. When using swarm as an orchestrator, -> this command must be executed on a swarm manager node. To learn about managers -> and workers, refer to the [Swarm mode section](https://docs.docker.com/engine/swarm/) -> in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/stack_ls.md b/docs/reference/commandline/stack_ls.md index 3ca8b8bbc1..08815f801e 100644 --- a/docs/reference/commandline/stack_ls.md +++ b/docs/reference/commandline/stack_ls.md @@ -26,10 +26,12 @@ Options: Lists the stacks. -> **Note**: This is a cluster management command. When using swarm as an orchestrator, -> this command must be executed on a swarm manager node. To learn about managers -> and workers, refer to the [Swarm mode section](https://docs.docker.com/engine/swarm/) -> in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -61,7 +63,7 @@ the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`Name` and `Services` entries separated by a colon for all stacks: +`Name` and `Services` entries separated by a colon (`:`) for all stacks: ```bash $ docker stack ls --format "{{.Name}}: {{.Services}}" diff --git a/docs/reference/commandline/stack_ps.md b/docs/reference/commandline/stack_ps.md index c484573fe7..81cadc16a0 100644 --- a/docs/reference/commandline/stack_ps.md +++ b/docs/reference/commandline/stack_ps.md @@ -27,10 +27,12 @@ Options: Lists the tasks that are running as part of the specified stack. -> **Note**: This is a cluster management command. When using swarm as an orchestrator, -> this command must be executed on a swarm manager node. To learn about managers -> and workers, refer to the [Swarm mode section](https://docs.docker.com/engine/swarm/) -> in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -138,7 +140,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`Name` and `Image` entries separated by a colon for all tasks: +`Name` and `Image` entries separated by a colon (`:`) for all tasks: ```bash $ docker stack ps --format "{{.Name}}: {{.Image}}" voting diff --git a/docs/reference/commandline/stack_rm.md b/docs/reference/commandline/stack_rm.md index ba4e32e4fc..a6fb12eb4d 100644 --- a/docs/reference/commandline/stack_rm.md +++ b/docs/reference/commandline/stack_rm.md @@ -25,10 +25,12 @@ Options: Remove the stack from the swarm. -> **Note**: This is a cluster management command. When using swarm as an orchestrator, -> this command must be executed on a swarm manager node. To learn about managers -> and workers, refer to the [Swarm mode section](https://docs.docker.com/engine/swarm/) -> in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples diff --git a/docs/reference/commandline/stack_services.md b/docs/reference/commandline/stack_services.md index 0d61e53efb..cbe6966797 100644 --- a/docs/reference/commandline/stack_services.md +++ b/docs/reference/commandline/stack_services.md @@ -25,10 +25,12 @@ Options: Lists the services that are running as part of the specified stack. -> **Note**: This is a cluster management command. When using swarm as an orchestrator, -> this command must be executed on a swarm manager node. To learn about managers -> and workers, refer to the [Swarm mode section](https://docs.docker.com/engine/swarm/) -> in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -87,7 +89,7 @@ using a Go template. Valid placeholders for the Go template are listed below: Placeholder | Description -------------|------------------------------------------------------------------------------------------ +------------|------------------------------------------------------------------- `.ID` | Service ID `.Name` | Service name `.Mode` | Service mode (replicated, global) @@ -99,7 +101,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`ID`, `Mode`, and `Replicas` entries separated by a colon for all services: +`ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: ```bash $ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}" diff --git a/docs/reference/commandline/stats.md b/docs/reference/commandline/stats.md index 993adcf200..5b5d3f6a1e 100644 --- a/docs/reference/commandline/stats.md +++ b/docs/reference/commandline/stats.md @@ -21,16 +21,33 @@ Options: ## Description -The `docker stats` command returns a live data stream for running containers. To limit data to one or more specific containers, specify a list of container names or ids separated by a space. You can specify a stopped container but stopped containers do not return any data. +The `docker stats` command returns a live data stream for running containers. To +limit data to one or more specific containers, specify a list of container names +or ids separated by a space. You can specify a stopped container but stopped +containers do not return any data. -If you want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint. +If you need more detailed information about a container's resource usage, use +the `/containers/(id)/stats` API endpoint. -> **Note**: On Linux, the Docker CLI reports memory usage by subtracting cache usage from the total memory usage. The API does not perform such a calculation but rather provides the total memory usage and the amount from the cache so that clients can use the data as needed. -The cache usage is defined as the value of `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts. -On Docker 19.03 and older, the cache usage was defined as the value of `cache` field. -On cgroup v2 hosts, the cache usage is defined as the value of `inactive_file` field. +> **Note** +> +> On Linux, the Docker CLI reports memory usage by subtracting cache usage from +> the total memory usage. The API does not perform such a calculation but rather +> provides the total memory usage and the amount from the cache so that clients +> can use the data as needed. The cache usage is defined as the value of +> `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts. +> +> On Docker 19.03 and older, the cache usage was defined as the value of `cache` +> field. On cgroup v2 hosts, the cache usage is defined as the value of +> `inactive_file` field. -> **Note**: The `PIDS` column contains the number of processes and kernel threads created by that container. Threads is the term used by Linux kernel. Other equivalent terms are "lightweight process" or "kernel task", etc. A large number in the `PIDS` column combined with a small number of processes (as reported by `ps` or `top`) may indicate that something in the container is creating many threads. +> **Note** +> +> The `PIDS` column contains the number of processes and kernel threads created +> by that container. Threads is the term used by Linux kernel. Other equivalent +> terms are "lightweight process" or "kernel task", etc. A large number in the +> `PIDS` column combined with a small number of processes (as reported by `ps` +> or `top`) may indicate that something in the container is creating many threads. ## Examples @@ -132,7 +149,7 @@ outputs the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`Container` and `CPUPerc` entries separated by a colon for all images: +`Container` and `CPUPerc` entries separated by a colon (`:`) for all images: ```bash $ docker stats --format "{{.Container}}: {{.CPUPerc}}" @@ -164,6 +181,3 @@ On Windows: "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" - -> **Note**: On Docker 17.09 and older, the `{{.Container}}` column was used, -> instead of `{{.ID}}\t{{.Name}}`. diff --git a/docs/reference/commandline/swarm_ca.md b/docs/reference/commandline/swarm_ca.md index c951d17e77..4309b62e0e 100644 --- a/docs/reference/commandline/swarm_ca.md +++ b/docs/reference/commandline/swarm_ca.md @@ -26,9 +26,12 @@ Options: View or rotate the current swarm CA certificate. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -111,7 +114,7 @@ progress of the rotation. * [swarm init](swarm_init.md) * [swarm join](swarm_join.md) -* [swarm join-token](swarm_join_token.md) +* [swarm join-token](swarm_join-token.md) * [swarm leave](swarm_leave.md) * [swarm unlock](swarm_unlock.md) -* [swarm unlock-key](swarm_unlock_key.md) +* [swarm unlock-key](swarm_unlock-key.md) diff --git a/docs/reference/commandline/swarm_init.md b/docs/reference/commandline/swarm_init.md index 39567632cc..696aaa8dde 100644 --- a/docs/reference/commandline/swarm_init.md +++ b/docs/reference/commandline/swarm_init.md @@ -55,7 +55,7 @@ a new node to the swarm, the node joins as a worker or manager node based upon t to [swarm join](swarm_join.md). After you create the swarm, you can display or rotate the token using -[swarm join-token](swarm_join_token.md). +[swarm join-token](swarm_join-token.md). ### `--autolock` @@ -189,8 +189,8 @@ by passing `--availability=drain` to `docker swarm init`. * [swarm ca](swarm_ca.md) * [swarm join](swarm_join.md) -* [swarm join-token](swarm_join_token.md) +* [swarm join-token](swarm_join-token.md) * [swarm leave](swarm_leave.md) * [swarm unlock](swarm_unlock.md) -* [swarm unlock-key](swarm_unlock_key.md) +* [swarm unlock-key](swarm_unlock-key.md) * [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_join-token.md b/docs/reference/commandline/swarm_join-token.md index 96ff623ba0..98c5a16c1d 100644 --- a/docs/reference/commandline/swarm_join-token.md +++ b/docs/reference/commandline/swarm_join-token.md @@ -25,9 +25,12 @@ role. You pass the token using the `--token` flag when you run [swarm join](swarm_join.md). Nodes use the join token only when they join the swarm. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -39,6 +42,7 @@ the swarm: ```bash $ docker swarm join-token worker + To add a worker to this swarm, run the following command: docker swarm join \ @@ -46,6 +50,7 @@ To add a worker to this swarm, run the following command: 172.17.0.2:2377 $ docker swarm join-token manager + To add a manager to this swarm, run the following command: docker swarm join \ @@ -57,6 +62,7 @@ Use the `--rotate` flag to generate a new join token for the specified role: ```bash $ docker swarm join-token --rotate worker + Successfully rotated worker join token. To add a worker to this swarm, run the following command: @@ -106,5 +112,5 @@ Only print the token. Do not print a complete command for joining. * [swarm join](swarm_join.md) * [swarm leave](swarm_leave.md) * [swarm unlock](swarm_unlock.md) -* [swarm unlock-key](swarm_unlock_key.md) +* [swarm unlock-key](swarm_unlock-key.md) * [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_join.md b/docs/reference/commandline/swarm_join.md index 1be75d4418..fd47a1076c 100644 --- a/docs/reference/commandline/swarm_join.md +++ b/docs/reference/commandline/swarm_join.md @@ -117,8 +117,8 @@ by passing `--availability=drain` to `docker swarm join`. * [swarm ca](swarm_ca.md) * [swarm init](swarm_init.md) -* [swarm join-token](swarm_join_token.md) +* [swarm join-token](swarm_join-token.md) * [swarm leave](swarm_leave.md) * [swarm unlock](swarm_unlock.md) -* [swarm unlock-key](swarm_unlock_key.md) +* [swarm unlock-key](swarm_unlock-key.md) * [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_leave.md b/docs/reference/commandline/swarm_leave.md index 66341b8cad..548f63e342 100644 --- a/docs/reference/commandline/swarm_leave.md +++ b/docs/reference/commandline/swarm_leave.md @@ -33,6 +33,7 @@ Consider the following swarm, as seen from the manager: ```bash $ docker node ls + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active @@ -43,6 +44,7 @@ To remove `worker2`, issue the following command from `worker2` itself: ```bash $ docker swarm leave + Node left the default swarm. ``` @@ -57,7 +59,7 @@ command. * [node rm](node_rm.md) * [swarm init](swarm_init.md) * [swarm join](swarm_join.md) -* [swarm join-token](swarm_join_token.md) +* [swarm join-token](swarm_join-token.md) * [swarm unlock](swarm_unlock.md) -* [swarm unlock-key](swarm_unlock_key.md) +* [swarm unlock-key](swarm_unlock-key.md) * [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_unlock-key.md b/docs/reference/commandline/swarm_unlock-key.md index 8c2786a596..79c65b4e3d 100644 --- a/docs/reference/commandline/swarm_unlock-key.md +++ b/docs/reference/commandline/swarm_unlock-key.md @@ -26,9 +26,12 @@ swarm. You can view or rotate the unlock key using `swarm unlock-key`. To view the key, run the `docker swarm unlock-key` command without any arguments: -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -49,6 +52,7 @@ key: ```bash $ docker swarm unlock-key --rotate + Successfully rotated manager unlock key. To unlock a swarm manager after it restarts, run the `docker swarm unlock` @@ -64,6 +68,7 @@ The `-q` (or `--quiet`) flag only prints the key: ```bash $ docker swarm unlock-key -q + SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 ``` @@ -81,7 +86,7 @@ Only print the unlock key, without instructions. * [swarm ca](swarm_ca.md) * [swarm init](swarm_init.md) * [swarm join](swarm_join.md) -* [swarm join-token](swarm_join_token.md) +* [swarm join-token](swarm_join-token.md) * [swarm leave](swarm_leave.md) * [swarm unlock](swarm_unlock.md) * [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_unlock.md b/docs/reference/commandline/swarm_unlock.md index 03e374dd45..ea0026fbe8 100644 --- a/docs/reference/commandline/swarm_unlock.md +++ b/docs/reference/commandline/swarm_unlock.md @@ -22,9 +22,12 @@ used to reactivate a manager after its Docker daemon restarts if the autolock setting is turned on. The unlock key is printed at the time when autolock is enabled, and is also available from the `docker swarm unlock-key` command. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -38,7 +41,7 @@ Please enter unlock key: * [swarm ca](swarm_ca.md) * [swarm init](swarm_init.md) * [swarm join](swarm_join.md) -* [swarm join-token](swarm_join_token.md) +* [swarm join-token](swarm_join-token.md) * [swarm leave](swarm_leave.md) -* [swarm unlock-key](swarm_unlock_key.md) +* [swarm unlock-key](swarm_unlock-key.md) * [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_update.md b/docs/reference/commandline/swarm_update.md index 31e43d2e60..0c190ef331 100644 --- a/docs/reference/commandline/swarm_update.md +++ b/docs/reference/commandline/swarm_update.md @@ -26,9 +26,12 @@ Options: Updates a swarm with new parameter values. -> **Note**: This is a cluster management command, and must be executed on a swarm -> manager node. To learn about managers and workers, refer to the [Swarm mode -> section](https://docs.docker.com/engine/swarm/) in the documentation. +> **Note** +> +> This is a cluster management command, and must be executed on a swarm +> manager node. To learn about managers and workers, refer to the +> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the +> documentation. ## Examples @@ -41,7 +44,7 @@ $ docker swarm update --cert-expiry 720h * [swarm ca](swarm_ca.md) * [swarm init](swarm_init.md) * [swarm join](swarm_join.md) -* [swarm join-token](swarm_join_token.md) +* [swarm join-token](swarm_join-token.md) * [swarm leave](swarm_leave.md) * [swarm unlock](swarm_unlock.md) -* [swarm unlock-key](swarm_unlock_key.md) +* [swarm unlock-key](swarm_unlock-key.md) diff --git a/docs/reference/commandline/system_df.md b/docs/reference/commandline/system_df.md index a894dcdf68..92e070bef0 100644 --- a/docs/reference/commandline/system_df.md +++ b/docs/reference/commandline/system_df.md @@ -66,8 +66,9 @@ my-named-vol 0 * `UNIQUE SIZE` is the amount of space that is only used by a given image * `SIZE` is the virtual size of the image, it is the sum of `SHARED SIZE` and `UNIQUE SIZE` -> **Note**: Network information is not shown because it doesn't consume the disk -> space. +> **Note** +> +> Network information is not shown because it does not consume disk space. ## Performance @@ -98,7 +99,7 @@ the data exactly as the template declares or, when using the `table` directive, will include column headers as well. The following example uses a template without headers and outputs the -`Type` and `TotalCount` entries separated by a colon: +`Type` and `TotalCount` entries separated by a colon (`:`): ```bash $ docker system df --format "{{.Type}}: {{.TotalCount}}" diff --git a/docs/reference/commandline/system_events.md b/docs/reference/commandline/system_events.md index 8b020dec63..1f4a04ec22 100644 --- a/docs/reference/commandline/system_events.md +++ b/docs/reference/commandline/system_events.md @@ -175,7 +175,7 @@ $ docker stop test **Shell 1: (Again .. now showing events):** -```none +```console 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) @@ -194,6 +194,7 @@ machine, using the following different time syntaxes: ```bash $ docker system events --since 1483283804 + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) @@ -204,6 +205,7 @@ $ docker system events --since 1483283804 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) $ docker system events --since '2017-01-05' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) @@ -214,6 +216,7 @@ $ docker system events --since '2017-01-05' 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) $ docker system events --since '2013-09-03T15:49:29' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) @@ -224,6 +227,7 @@ $ docker system events --since '2013-09-03T15:49:29' 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) $ docker system events --since '10m' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) @@ -325,12 +329,12 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299 #### Format as JSON -```none - $ docker system events --format '{{json .}}' +```bash +$ docker system events --format '{{json .}}' - {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. - {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. - {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. - {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. +{"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. +{"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. +{"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. +{"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. +{"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. ``` diff --git a/docs/reference/commandline/system_prune.md b/docs/reference/commandline/system_prune.md index a08894ead1..67f01b596e 100644 --- a/docs/reference/commandline/system_prune.md +++ b/docs/reference/commandline/system_prune.md @@ -97,11 +97,13 @@ deleted: sha256:3a88a5c81eb5c283e72db2dbc6d65cbfd8e80b6c89bb6e714cfaaa0eed99c548 Total reclaimed space: 13.5 MB ``` -> **Note**: The `--volumes` option was added in Docker 17.06.1. Older versions -> of Docker prune volumes by default, along with other Docker objects. On older -> versions, run `docker container prune`, `docker network prune`, and -> `docker image prune` separately to remove unused containers, networks, and -> images, without removing volumes. +> **Note** +> +> The `--volumes` option was added in Docker 17.06.1. Older versions of Docker +> prune volumes by default, along with other Docker objects. On older versions, +> run `docker container prune`, `docker network prune`, and `docker image prune` +> separately to remove unused containers, networks, and images, without removing +> volumes. ### Filtering @@ -138,7 +140,7 @@ containers, images, networks, and volumes without the specified labels. * [volume inspect](volume_inspect.md) * [volume rm](volume_rm.md) * [volume prune](volume_prune.md) -* [Understand Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) +* [Understand Data Volumes](https://docs.docker.com/storage/volumes/) * [system df](system_df.md) * [container prune](container_prune.md) * [image prune](image_prune.md) diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md index b6a0feb8c4..8eb7715bb7 100644 --- a/docs/reference/commandline/tag.md +++ b/docs/reference/commandline/tag.md @@ -31,7 +31,7 @@ digits, underscores, periods and dashes. A tag name may not start with a period or a dash and may contain a maximum of 128 characters. You can group your images together using names and tags, and then upload them -to [*Share Images via Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub). +to [*Share images on Docker Hub*](https://docs.docker.com/get-started/part3/). ## Examples diff --git a/docs/reference/commandline/trust_inspect.md b/docs/reference/commandline/trust_inspect.md index e514069e82..8c7f1ea533 100644 --- a/docs/reference/commandline/trust_inspect.md +++ b/docs/reference/commandline/trust_inspect.md @@ -149,6 +149,7 @@ display any signed tags. ```bash $ docker trust inspect unsigned-img + No signatures or cannot access unsigned-img ``` @@ -157,6 +158,7 @@ However, if other tags are signed in the same image repository, ```bash $ docker trust inspect alpine:unsigned + [ { "Name": "alpine:unsigned", @@ -165,17 +167,17 @@ $ docker trust inspect alpine:unsigned { "Name": "Repository", "Keys": [ - { - "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" - } + { + "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" + } ] }, { "Name": "Root", "Keys": [ - { - "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" - } + { + "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" + } ] } ] @@ -190,59 +192,60 @@ signed tags in the repository: ```bash $ docker trust inspect alpine + [ - { - "Name": "alpine", - "SignedTags": [ - { - "SignedTag": "3.5", - "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "3.6", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "edge", - "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "latest", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - } - ], - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Repository", - "Keys": [ - { - "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" - } - ] - }, - { - "Name": "Root", - "Keys": [ - { - "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" - } - ] - } + { + "Name": "alpine", + "SignedTags": [ + { + "SignedTag": "3.5", + "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", + "Signers": [ + "Repo Admin" ] - } + }, + { + "SignedTag": "3.6", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "edge", + "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "latest", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + } + ], + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Repository", + "Keys": [ + { + "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" + } + ] + }, + { + "Name": "Root", + "Keys": [ + { + "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" + } + ] + } + ] + } ] ``` @@ -254,104 +257,105 @@ and reports the results in an ordered list: ```bash $ docker trust inspect alpine notary + [ - { - "Name": "alpine", - "SignedTags": [ - { - "SignedTag": "3.5", - "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "3.6", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "edge", - "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "integ-test-base", - "Digest": "3952dc48dcc4136ccdde37fbef7e250346538a55a0366e3fccc683336377e372", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "latest", - "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", - "Signers": [ - "Repo Admin" - ] - } - ], - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Repository", - "Keys": [ - { - "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" - } - ] - }, - { - "Name": "Root", - "Keys": [ - { - "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" - } - ] - } + { + "Name": "alpine", + "SignedTags": [ + { + "SignedTag": "3.5", + "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c", + "Signers": [ + "Repo Admin" ] - }, - { - "Name": "notary", - "SignedTags": [ - { - "SignedTag": "server", - "Digest": "71f64ab718a3331dee103bc5afc6bc492914738ce37c2d2f127a8133714ecf5c", - "Signers": [ - "Repo Admin" - ] - }, - { - "SignedTag": "signer", - "Digest": "a6122d79b1e74f70b5dd933b18a6d1f99329a4728011079f06b245205f158fe8", - "Signers": [ - "Repo Admin" - ] - } - ], - "Signers": [], - "AdministrativeKeys": [ - { - "Name": "Root", - "Keys": [ - { - "ID": "8cdcdef5bd039f4ab5a029126951b5985eebf57cabdcdc4d21f5b3be8bb4ce92" - } - ] - }, - { - "Name": "Repository", - "Keys": [ - { - "ID": "85bfd031017722f950d480a721f845a2944db26a3dc084040a70f1b0d9bbb3df" - } - ] - } + }, + { + "SignedTag": "3.6", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" ] - } + }, + { + "SignedTag": "edge", + "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "integ-test-base", + "Digest": "3952dc48dcc4136ccdde37fbef7e250346538a55a0366e3fccc683336377e372", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "latest", + "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478", + "Signers": [ + "Repo Admin" + ] + } + ], + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Repository", + "Keys": [ + { + "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd" + } + ] + }, + { + "Name": "Root", + "Keys": [ + { + "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce" + } + ] + } + ] + }, + { + "Name": "notary", + "SignedTags": [ + { + "SignedTag": "server", + "Digest": "71f64ab718a3331dee103bc5afc6bc492914738ce37c2d2f127a8133714ecf5c", + "Signers": [ + "Repo Admin" + ] + }, + { + "SignedTag": "signer", + "Digest": "a6122d79b1e74f70b5dd933b18a6d1f99329a4728011079f06b245205f158fe8", + "Signers": [ + "Repo Admin" + ] + } + ], + "Signers": [], + "AdministrativeKeys": [ + { + "Name": "Root", + "Keys": [ + { + "ID": "8cdcdef5bd039f4ab5a029126951b5985eebf57cabdcdc4d21f5b3be8bb4ce92" + } + ] + }, + { + "Name": "Repository", + "Keys": [ + { + "ID": "85bfd031017722f950d480a721f845a2944db26a3dc084040a70f1b0d9bbb3df" + } + ] + } + ] + } ] ``` @@ -386,6 +390,7 @@ and specify their `KEYS`: ```bash $ docker trust inspect --pretty my-image:purple + SIGNED TAG DIGEST SIGNERS purple 941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557 alice, bob, carol @@ -419,6 +424,7 @@ Root Key: a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce ```bash $ docker trust inspect --pretty alpine + SIGNED TAG DIGEST SIGNERS 2.6 9ace551613070689a12857d62c30ef0daa9a376107ec0fff0e34786cedb3399b (Repo Admin) 2.7 9f08005dff552038f0ad2f46b8e65ff3d25641747d3912e3ea8da6785046561a (Repo Admin) @@ -440,6 +446,7 @@ Here's an example with signers that are set up by `docker trust` commands: ```bash $ docker trust inspect --pretty my-image + SIGNED TAG DIGEST SIGNERS red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob diff --git a/docs/reference/commandline/trust_revoke.md b/docs/reference/commandline/trust_revoke.md index 72e2d63ba9..8423c33ad8 100644 --- a/docs/reference/commandline/trust_revoke.md +++ b/docs/reference/commandline/trust_revoke.md @@ -28,7 +28,7 @@ Here's an example of a repo with two signed tags: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob @@ -55,7 +55,7 @@ Successfully deleted signature for example/trust-demo:red After revocation, the tag is removed from the list of released tags: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob @@ -75,7 +75,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When no tag is specified, `docker trust` revokes all signatures that you have a signing key for. ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo SIGNED TAG DIGEST SIGNERS red 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943 alice blue f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197 alice, bob @@ -103,7 +103,7 @@ Successfully deleted signature for example/trust-demo All tags that have `alice`'s signature on them are removed from the list of released tags: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo diff --git a/docs/reference/commandline/trust_sign.md b/docs/reference/commandline/trust_sign.md index 1e0bf50ff7..c623dac7d1 100644 --- a/docs/reference/commandline/trust_sign.md +++ b/docs/reference/commandline/trust_sign.md @@ -28,7 +28,8 @@ Options: Given an image: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41 (Repo Admin) @@ -41,6 +42,7 @@ Sign a new tag with `docker trust sign`: ```bash $ docker trust sign example/trust-demo:v2 + Signing and pushing trust metadata for example/trust-demo:v2 The push refers to a repository [docker.io/example/trust-demo] eed4e566104a: Layer already exists @@ -56,10 +58,11 @@ Enter passphrase for repository key with ID 36d4c36: Successfully signed docker.io/example/trust-demo:v2 ``` -Use `docker trust view` to list the new signature: +Use `docker trust inspect --pretty` to list the new signature: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41 (Repo Admin) v2 8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56 (Repo Admin) @@ -74,7 +77,7 @@ Root Key: 246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b Given an image: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -94,6 +97,7 @@ Sign a new tag with `docker trust sign`: ```bash $ docker trust sign example/trust-demo:v1 + Signing and pushing trust metadata for example/trust-demo:v1 The push refers to a repository [docker.io/example/trust-demo] 26b126eb8632: Layer already exists @@ -107,10 +111,11 @@ Enter passphrase for delegation key with ID 27d42a8: Successfully signed docker.io/example/trust-demo:v1 ``` -`docker trust view` lists the new signature: +`docker trust inspect --pretty` lists the new signature: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice @@ -130,12 +135,14 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When signing an image on a repo for the first time, `docker trust sign` sets up new keys before signing the image. ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + No signatures or cannot access example/trust-demo ``` ```bash $ docker trust sign example/trust-demo:v1 + Signing and pushing trust metadata for example/trust-demo:v1 Enter passphrase for root key with ID 36cac18: Enter passphrase for new repository key with ID 731396b: @@ -159,7 +166,8 @@ Successfully signed docker.io/example/trust-demo:v1 ``` ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56 alice diff --git a/docs/reference/commandline/trust_signer_add.md b/docs/reference/commandline/trust_signer_add.md index b58f056190..e3c6f928ab 100644 --- a/docs/reference/commandline/trust_signer_add.md +++ b/docs/reference/commandline/trust_signer_add.md @@ -27,7 +27,7 @@ Options: To add a new signer, `alice`, to this repository: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -51,10 +51,10 @@ $ docker trust signer add alice example/trust-demo --key alice.crt Successfully added signer: alice to example/trust-demo ``` -`docker trust view` now lists `alice` as a valid signer: +`docker trust inspect --pretty` now lists `alice` as a valid signer: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -75,24 +75,26 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 When adding a signer on a repo for the first time, `docker trust signer add` sets up a new repo if it doesn't exist. ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + No signatures or cannot access example/trust-demo ``` ```bash $ docker trust signer add alice example/trust-demo --key alice.crt - Initializing signed repository for example/trust-demo... - Enter passphrase for root key with ID 748121c: + +Initializing signed repository for example/trust-demo... +Enter passphrase for root key with ID 748121c: Enter passphrase for new repository key with ID 95b9e55: Repeat passphrase for new repository key with ID 95b9e55: Successfully initialized "example/trust-demo" Adding signer "alice" to example/trust-demo... - Successfully added signer: alice to example/trust-demo +Successfully added signer: alice to example/trust-demo ``` ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -112,7 +114,8 @@ Root Key: 748121c14bd1461f6c58cb3ef39087c8fdc7633bb11a98af844fd9a04e208103 ## Add a signer to multiple repos To add a signer, `alice`, to multiple repositories: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob @@ -126,7 +129,8 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` ```bash -$ docker trust view example/trust-demo2 +$ docker trust inspect --pretty example/trust-demo2 + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob @@ -143,6 +147,7 @@ Add `alice` to both repositories with a single `docker trust signer add` command ```bash $ docker trust signer add alice example/trust-demo example/trust-demo2 --key alice.crt + Adding signer "alice" to example/trust-demo... Enter passphrase for repository key with ID 95b9e55: Successfully added signer: alice to example/trust-demo @@ -151,11 +156,13 @@ Adding signer "alice" to example/trust-demo2... Enter passphrase for repository key with ID ece554f: Successfully added signer: alice to example/trust-demo2 ``` -`docker trust view` now lists `alice` as a valid signer of both `example/trust-demo` and `example/trust-demo2`: + +`docker trust inspect --pretty` now lists `alice` as a valid signer of both `example/trust-demo` and `example/trust-demo2`: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob @@ -169,8 +176,10 @@ Administrative keys for example/trust-demo: Repository Key: 95b9e5514c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` + ```bash -$ docker trust view example/trust-demo2 +$ docker trust inspect --pretty example/trust-demo2 + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob @@ -190,6 +199,7 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ```bash $ docker trust signer add alice example/unauthorized example/authorized --key alice.crt + Adding signer "alice" to example/unauthorized... you are not authorized to perform this operation: server returned 401. diff --git a/docs/reference/commandline/trust_signer_remove.md b/docs/reference/commandline/trust_signer_remove.md index 74dcdbf223..2e197d56d2 100644 --- a/docs/reference/commandline/trust_signer_remove.md +++ b/docs/reference/commandline/trust_signer_remove.md @@ -26,7 +26,7 @@ Options: To remove an existing signer, `alice`, from this repository: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -52,10 +52,10 @@ Enter passphrase for repository key with ID 642692c: Successfully removed alice from example/trust-demo ``` -`docker trust view` now does not list `alice` as a valid signer: +`docker trust inspect --pretty` now does not list `alice` as a valid signer: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo No signatures for example/trust-demo @@ -75,7 +75,8 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 To remove an existing signer, `alice`, from multiple repositories: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice, bob @@ -91,7 +92,8 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` ```bash -$ docker trust view example/trust-demo2 +$ docker trust inspect --pretty example/trust-demo2 + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 alice, bob @@ -120,11 +122,12 @@ Enter passphrase for repository key with ID ece554f: Successfully removed alice from example/trust-demo2 ``` -Run `docker trust view` to confirm that `alice` is no longer listed as a valid +Run `docker trust inspect --pretty` to confirm that `alice` is no longer listed as a valid signer of either `example/trust-demo` or `example/trust-demo2`: ```bash -$ docker trust view example/trust-demo +$ docker trust inspect --pretty example/trust-demo + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob @@ -139,7 +142,8 @@ Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` ```bash -$ docker trust view example/trust-demo2 +$ docker trust inspect --pretty example/trust-demo2 + SIGNED TAG DIGEST SIGNERS v1 74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 bob diff --git a/docs/reference/commandline/update.md b/docs/reference/commandline/update.md index f218f61cc2..7edeeb7fd7 100644 --- a/docs/reference/commandline/update.md +++ b/docs/reference/commandline/update.md @@ -43,8 +43,10 @@ options on a running or a stopped container. On kernel version older than 4.6, you can only update `--kernel-memory` on a stopped container or on a running container with kernel memory initialized. -> **Warning**: The `docker update` and `docker container update` commands are -> not supported for Windows containers. +> **Warning** +> +> The `docker update` and `docker container update` commands are not supported +> for Windows containers. {: .warning } ## Examples diff --git a/docs/reference/commandline/version.md b/docs/reference/commandline/version.md index 8e4997a0eb..a3abdd0738 100644 --- a/docs/reference/commandline/version.md +++ b/docs/reference/commandline/version.md @@ -33,20 +33,32 @@ describes all the details of the format. $ docker version Client: -Version: 1.8.0 -API version: 1.20 -Go version: go1.4.2 -Git commit: f5bae0a -Built: Tue Jun 23 17:56:00 UTC 2015 -OS/Arch: linux/amd64 + Version: 19.03.8 + API version: 1.40 + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:21:11 2020 + OS/Arch: darwin/amd64 + Experimental: true Server: -Version: 1.8.0 -API version: 1.20 -Go version: go1.4.2 -Git commit: f5bae0a -Built: Tue Jun 23 17:56:00 UTC 2015 -OS/Arch: linux/amd64 + Engine: + Version: 19.03.8 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:29:16 2020 + OS/Arch: linux/amd64 + Experimental: true + containerd: + Version: v1.2.13 + GitCommit: 7ad184331fa3e55e52b890ea95e65ba581ae3429 + runc: + Version: 1.0.0-rc10 + GitCommit: dc9208a3303feef5b3839f4323d9beb36df0a9dd + docker-init: + Version: 0.18.0 + GitCommit: fec3683 ``` ### Get the server version @@ -54,7 +66,7 @@ OS/Arch: linux/amd64 ```bash $ docker version --format '{{.Server.Version}}' -1.8.0 +19.03.8 ``` ### Dump raw JSON data @@ -62,5 +74,5 @@ $ docker version --format '{{.Server.Version}}' ```bash $ docker version --format '{{json .}}' -{"Client":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"},"ServerOK":true,"Server":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","KernelVersion":"3.13.2-gentoo","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"}} +{"Client":{"Platform":{"Name":"Docker Engine - Community"},"Version":"19.03.8","ApiVersion":"1.40","DefaultAPIVersion":"1.40","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"darwin","Arch":"amd64","BuildTime":"Wed Mar 11 01:21:11 2020","Experimental":true},"Server":{"Platform":{"Name":"Docker Engine - Community"},"Components":[{"Name":"Engine","Version":"19.03.8","Details":{"ApiVersion":"1.40","Arch":"amd64","BuildTime":"Wed Mar 11 01:29:16 2020","Experimental":"true","GitCommit":"afacb8b","GoVersion":"go1.12.17","KernelVersion":"4.19.76-linuxkit","MinAPIVersion":"1.12","Os":"linux"}},{"Name":"containerd","Version":"v1.2.13","Details":{"GitCommit":"7ad184331fa3e55e52b890ea95e65ba581ae3429"}},{"Name":"runc","Version":"1.0.0-rc10","Details":{"GitCommit":"dc9208a3303feef5b3839f4323d9beb36df0a9dd"}},{"Name":"docker-init","Version":"0.18.0","Details":{"GitCommit":"fec3683"}}],"Version":"19.03.8","ApiVersion":"1.40","MinAPIVersion":"1.12","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"linux","Arch":"amd64","KernelVersion":"4.19.76-linuxkit","Experimental":true,"BuildTime":"2020-03-11T01:29:16.000000000+00:00"}} ``` diff --git a/docs/reference/commandline/volume.md b/docs/reference/commandline/volume.md index f28ad491d8..96ed528569 100644 --- a/docs/reference/commandline/volume.md +++ b/docs/reference/commandline/volume.md @@ -33,7 +33,7 @@ prune volumes. * [volume create](volume_create.md) * [volume inspect](volume_inspect.md) -* [volume list](volume_list.md) +* [volume list](volume_ls.md) * [volume rm](volume_rm.md) * [volume prune](volume_prune.md) -* [Understand Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) +* [Understand Data Volumes](https://docs.docker.com/storage/volumes/) diff --git a/docs/reference/commandline/volume_create.md b/docs/reference/commandline/volume_create.md index b8057b8302..cbec1b463f 100644 --- a/docs/reference/commandline/volume_create.md +++ b/docs/reference/commandline/volume_create.md @@ -113,4 +113,4 @@ $ docker volume create --driver local \ * [volume ls](volume_ls.md) * [volume rm](volume_rm.md) * [volume prune](volume_prune.md) -* [Understand Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) +* [Understand Data Volumes](https://docs.docker.com/storage/volumes/) diff --git a/docs/reference/commandline/volume_inspect.md b/docs/reference/commandline/volume_inspect.md index 4a5b721fb1..1335dcc4f8 100644 --- a/docs/reference/commandline/volume_inspect.md +++ b/docs/reference/commandline/volume_inspect.md @@ -28,19 +28,26 @@ details of the format. ```bash $ docker volume create -85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d + +8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5 + $ docker volume inspect 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d + [ { - "Name": "85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d", - "Driver": "local", - "Mountpoint": "/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data", - "Status": null + "CreatedAt": "2020-04-19T11:00:21Z", + "Driver": "local", + "Labels": {}, + "Mountpoint": "/var/lib/docker/volumes/8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5/_data", + "Name": "8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5", + "Options": {}, + "Scope": "local" } ] -$ docker volume inspect --format '{{ .Mountpoint }}' 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d -/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data +$ docker volume inspect --format '{{ .Mountpoint }}' 8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5 + +/var/lib/docker/volumes/8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5/_data ``` ## Related commands @@ -49,4 +56,4 @@ $ docker volume inspect --format '{{ .Mountpoint }}' 85bffb0677236974f93955d8ecc * [volume ls](volume_ls.md) * [volume rm](volume_rm.md) * [volume prune](volume_prune.md) -* [Understand Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) +* [Understand Data Volumes](https://docs.docker.com/storage/volumes/) diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md index dc922365cb..c697ead133 100644 --- a/docs/reference/commandline/volume_ls.md +++ b/docs/reference/commandline/volume_ls.md @@ -57,10 +57,10 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b The currently supported filters are: -* dangling (boolean - true or false, 0 or 1) -* driver (a volume driver's name) -* label (`label=` or `label==`) -* name (a volume's name) +- dangling (boolean - true or false, 0 or 1) +- driver (a volume driver's name) +- label (`label=` or `label==`) +- name (a volume's name) #### dangling @@ -171,7 +171,7 @@ output the data exactly as the template declares or, when using the `table` directive, includes column headers as well. The following example uses a template without headers and outputs the -`Name` and `Driver` entries separated by a colon for all volumes: +`Name` and `Driver` entries separated by a colon (`:`) for all volumes: ```bash $ docker volume ls --format "{{.Name}}: {{.Driver}}" @@ -187,4 +187,4 @@ vol3: local * [volume inspect](volume_inspect.md) * [volume rm](volume_rm.md) * [volume prune](volume_prune.md) -* [Understand Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) +* [Understand Data Volumes](https://docs.docker.com/storage/volumes/) diff --git a/docs/reference/commandline/volume_prune.md b/docs/reference/commandline/volume_prune.md index f11c89002e..9906d60b12 100644 --- a/docs/reference/commandline/volume_prune.md +++ b/docs/reference/commandline/volume_prune.md @@ -56,7 +56,7 @@ volumes without the specified labels. * [volume ls](volume_ls.md) * [volume inspect](volume_inspect.md) * [volume rm](volume_rm.md) -* [Understand Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) +* [Understand Data Volumes](https://docs.docker.com/storage/volumes/) * [system df](system_df.md) * [container prune](container_prune.md) * [image prune](image_prune.md) diff --git a/docs/reference/commandline/volume_rm.md b/docs/reference/commandline/volume_rm.md index 03bfcb0385..8095c489a7 100644 --- a/docs/reference/commandline/volume_rm.md +++ b/docs/reference/commandline/volume_rm.md @@ -26,8 +26,9 @@ Remove one or more volumes. You cannot remove a volume that is in use by a conta ## Examples ```bash - $ docker volume rm hello - hello +$ docker volume rm hello + +hello ``` ## Related commands @@ -36,4 +37,4 @@ Remove one or more volumes. You cannot remove a volume that is in use by a conta * [volume inspect](volume_inspect.md) * [volume ls](volume_ls.md) * [volume prune](volume_prune.md) -* [Understand Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) +* [Understand Data Volumes](https://docs.docker.com/storage/volumes/) diff --git a/docs/reference/commandline/wait.md b/docs/reference/commandline/wait.md index 4b4e5ba139..2a903b13ed 100644 --- a/docs/reference/commandline/wait.md +++ b/docs/reference/commandline/wait.md @@ -15,8 +15,10 @@ Options: --help Print usage ``` -> **Note**: `docker wait` returns `0` when run against a container which had -> already exited before the `docker wait` command was run. +> **Note** +> +> `docker wait` returns `0` when run against a container which had already +> exited before the `docker wait` command was run. ## Examples diff --git a/docs/reference/run.md b/docs/reference/run.md index 15f07e8d93..dbdd85f76d 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -48,7 +48,9 @@ other `docker` command. To learn how to interpret the types of `[OPTIONS]`, see [*Option types*](commandline/cli.md#option-types). -> **Note**: Depending on your Docker system configuration, you may be +> **Note** +> +> Depending on your Docker system configuration, you may be > required to preface the `docker run` command with `sudo`. To avoid > having to use `sudo` with the `docker` command, your system > administrator can create a Unix group called `docker` and add users to @@ -128,19 +130,24 @@ If you do not specify `-a` then Docker will [attach to both stdout and stderr You can specify to which of the three standard streams (`STDIN`, `STDOUT`, `STDERR`) you'd like to connect instead, as in: - $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash +```bash +$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash +``` For interactive processes (like a shell), you must use `-i -t` together in order to allocate a tty for the container process. `-i -t` is often written `-it` as you'll see in later examples. Specifying `-t` is forbidden when the client is receiving its standard input from a pipe, as in: - $ echo test | docker run -i busybox cat +```bash +$ echo test | docker run -i busybox cat +``` ->**Note**: A process running as PID 1 inside a container is treated ->specially by Linux: it ignores any signal with the default action. ->So, the process will not terminate on `SIGINT` or `SIGTERM` unless it is ->coded to do so. +> **Note** +> +> A process running as PID 1 inside a container is treated specially by Linux: +> it ignores any signal with the default action. As a result, the process will +> not terminate on `SIGINT` or `SIGTERM` unless it is coded to do so. ## Container identification @@ -161,8 +168,9 @@ container. If you specify a `name`, you can use it when referencing the container within a Docker network. This works for both background and foreground Docker containers. -> **Note**: Containers on the default bridge network must be linked to -> communicate by name. +> **Note** +> +> Containers on the default bridge network must be linked to communicate by name. ### PID equivalent @@ -188,7 +196,9 @@ the digest value is predictable and referenceable. The following example runs a container from the `alpine` image with the `sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest: - $ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date +```bash +$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date +``` ## PID settings (--pid) @@ -212,7 +222,7 @@ within the container. Create this Dockerfile: -``` +```dockerfile FROM alpine:latest RUN apk add --update htop && rm -rf /var/cache/apk/* CMD ["htop"] @@ -226,7 +236,7 @@ $ docker build -t myhtop . Use the following command to run `htop` inside a container: -``` +```bash $ docker run -it --rm --pid=host myhtop ``` @@ -410,8 +420,10 @@ docker daemon. It is recommended to run containers in this mode when their networking performance is critical, for example, a production Load Balancer or a High Performance Web Server. -> **Note**: `--network="host"` gives the container full access to local system -> services such as D-bus and is therefore considered insecure. +> **Note** +> +> `--network="host"` gives the container full access to local system services +> such as D-bus and is therefore considered insecure. #### Network: container @@ -426,9 +438,11 @@ Example running a Redis container with Redis binding to `localhost` then running the `redis-cli` command and connecting to the Redis server over the `localhost` interface. - $ docker run -d --name redis example/redis --bind 127.0.0.1 - $ # use the redis container's network stack to access localhost - $ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1 +```bash +$ docker run -d --name redis example/redis --bind 127.0.0.1 +$ # use the redis container's network stack to access localhost +$ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1 +``` #### User-defined network @@ -444,7 +458,7 @@ Engines can also communicate in this way. The following example creates a network using the built-in `bridge` network driver and running a container in the created network -``` +```bash $ docker network create -d bridge my-net $ docker run --network=my-net -itd --name=container3 busybox ``` @@ -455,24 +469,29 @@ Your container will have lines in `/etc/hosts` which define the hostname of the container itself as well as `localhost` and a few other common things. The `--add-host` flag can be used to add additional lines to `/etc/hosts`. - $ docker run -it --add-host db-static:86.75.30.9 ubuntu cat /etc/hosts - 172.17.0.22 09d03f76bf2c - fe00::0 ip6-localnet - ff00::0 ip6-mcastprefix - ff02::1 ip6-allnodes - ff02::2 ip6-allrouters - 127.0.0.1 localhost - ::1 localhost ip6-localhost ip6-loopback - 86.75.30.9 db-static +```bash +$ docker run -it --add-host db-static:86.75.30.9 ubuntu cat /etc/hosts + +172.17.0.22 09d03f76bf2c +fe00::0 ip6-localnet +ff00::0 ip6-mcastprefix +ff02::1 ip6-allnodes +ff02::2 ip6-allrouters +127.0.0.1 localhost +::1 localhost ip6-localhost ip6-loopback +86.75.30.9 db-static +``` If a container is connected to the default bridge network and `linked` with other containers, then the container's `/etc/hosts` file is updated with the linked container's name. -> **Note** Since Docker may live update the container’s `/etc/hosts` file, there -may be situations when processes inside the container can end up reading an -empty or incomplete `/etc/hosts` file. In most cases, retrying the read again -should fix the problem. +> **Note** +> +> Since Docker may live update the container’s `/etc/hosts` file, there +> may be situations when processes inside the container can end up reading an +> empty or incomplete `/etc/hosts` file. In most cases, retrying the read again +> should fix the problem. ## Restart policies (--restart) @@ -548,18 +567,21 @@ will try forever to restart the container. The number of (attempted) restarts for a container can be obtained via [`docker inspect`](commandline/inspect.md). For example, to get the number of restarts for container "my-container"; - {% raw %} - $ docker inspect -f "{{ .RestartCount }}" my-container - # 2 - {% endraw %} +```bash +{% raw %} +$ docker inspect -f "{{ .RestartCount }}" my-container +# 2 +{% endraw %} +``` Or, to get the last time the container was (re)started; - {% raw %} - $ docker inspect -f "{{ .State.StartedAt }}" my-container - # 2015-03-04T23:47:07.691840179Z - {% endraw %} - +```bash +{% raw %} +$ docker inspect -f "{{ .State.StartedAt }}" my-container +# 2015-03-04T23:47:07.691840179Z +{% endraw %} +``` Combining `--restart` (restart policy) with the `--rm` (clean up) flag results in an error. On container restart, attached clients are disconnected. See the @@ -567,12 +589,16 @@ examples on using the [`--rm` (clean up)](#clean-up-rm) flag later in this page. ### Examples - $ docker run --restart=always redis +```bash +$ docker run --restart=always redis +``` This will run the `redis` container with a restart policy of **always** so that if the container exits, Docker will restart it. - $ docker run --restart=on-failure:10 redis +```bash +$ docker run --restart=on-failure:10 redis +``` This will run the `redis` container with a restart policy of **on-failure** and a maximum restart count of 10. If the `redis` container exits with a @@ -588,27 +614,39 @@ the exit codes follow the `chroot` standard, see below: **_125_** if the error is with Docker daemon **_itself_** - $ docker run --foo busybox; echo $? - # flag provided but not defined: --foo - See 'docker run --help'. - 125 +```bash +$ docker run --foo busybox; echo $? + +flag provided but not defined: --foo +See 'docker run --help'. +125 +``` **_126_** if the **_contained command_** cannot be invoked - $ docker run busybox /etc; echo $? - # docker: Error response from daemon: Container command '/etc' could not be invoked. - 126 +```bash +$ docker run busybox /etc; echo $? + +docker: Error response from daemon: Container command '/etc' could not be invoked. +126 +``` **_127_** if the **_contained command_** cannot be found - $ docker run busybox foo; echo $? - # docker: Error response from daemon: Container command 'foo' not found or does not exist. - 127 +```bash +$ docker run busybox foo; echo $? + +docker: Error response from daemon: Container command 'foo' not found or does not exist. +127 +``` **_Exit code_** of **_contained command_** otherwise - $ docker run busybox /bin/sh -c 'exit 3'; echo $? - # 3 +```bash +$ docker run busybox /bin/sh -c 'exit 3'; echo $? + +3 +``` ## Clean up (--rm) @@ -622,52 +660,74 @@ the container exits**, you can add the `--rm` flag: --rm=false: Automatically remove the container when it exits -> **Note**: When you set the `--rm` flag, Docker also removes the anonymous volumes -associated with the container when the container is removed. This is similar -to running `docker rm -v my-container`. Only volumes that are specified without a -name are removed. For example, with -`docker run --rm -v /foo -v awesome:/bar busybox top`, the volume for `/foo` will be removed, -but the volume for `/bar` will not. Volumes inherited via `--volumes-from` will be removed -with the same logic -- if the original volume was specified with a name it will **not** be removed. +> **Note** +> +> If you set the `--rm` flag, Docker also removes the anonymous volumes +> associated with the container when the container is removed. This is similar +> to running `docker rm -v my-container`. Only volumes that are specified without +> a name are removed. For example, when running: +> +> ```bash +> docker run --rm -v /foo -v awesome:/bar busybox top +> ``` +> +> the volume for `/foo` will be removed, but the volume for `/bar` will not. +> Volumes inherited via `--volumes-from` will be removed with the same logic: if +> the original volume was specified with a name it will **not** be removed. ## Security configuration - --security-opt="label=user:USER" : Set the label user for the container - --security-opt="label=role:ROLE" : Set the label role for the container - --security-opt="label=type:TYPE" : Set the label type for the container - --security-opt="label=level:LEVEL" : Set the label level for the container - --security-opt="label=disable" : Turn off label confinement for the container - --security-opt="apparmor=PROFILE" : Set the apparmor profile to be applied to the container - --security-opt="no-new-privileges:true|false" : Disable/enable container processes from gaining new privileges - --security-opt="seccomp=unconfined" : Turn off seccomp confinement for the container - --security-opt="seccomp=profile.json": White listed syscalls seccomp Json file to be used as a seccomp filter + +| Option | Description | +|:------------------------------------------|:--------------------------------------------------------------------------| +| `--security-opt="label=user:USER"` | Set the label user for the container | +| `--security-opt="label=role:ROLE"` | Set the label role for the container | +| `--security-opt="label=type:TYPE"` | Set the label type for the container | +| `--security-opt="label=level:LEVEL"` | Set the label level for the container | +| `--security-opt="label=disable"` | Turn off label confinement for the container | +| `--security-opt="apparmor=PROFILE"` | Set the apparmor profile to be applied to the container | +| `--security-opt="no-new-privileges:true"` | Disable container processes from gaining new privileges | +| `--security-opt="seccomp=unconfined"` | Turn off seccomp confinement for the container | +| `--security-opt="seccomp=profile.json"` | White-listed syscalls seccomp Json file to be used as a seccomp filter | You can override the default labeling scheme for each container by specifying the `--security-opt` flag. Specifying the level in the following command allows you to share the same content between containers. - $ docker run --security-opt label=level:s0:c100,c200 -it fedora bash +```bash +$ docker run --security-opt label=level:s0:c100,c200 -it fedora bash +``` -> **Note**: Automatic translation of MLS labels is not currently supported. +> **Note** +> +> Automatic translation of MLS labels is not currently supported. To disable the security labeling for this container versus running with the `--privileged` flag, use the following command: - $ docker run --security-opt label=disable -it fedora bash +```bash +$ docker run --security-opt label=disable -it fedora bash +``` If you want a tighter security policy on the processes within a container, you can specify an alternate type for the container. You could run a container that is only allowed to listen on Apache ports by executing the following command: - $ docker run --security-opt label=type:svirt_apache_t -it centos bash +```bash +$ docker run --security-opt label=type:svirt_apache_t -it centos bash +``` -> **Note**: You would have to write policy defining a `svirt_apache_t` type. +> **Note** +> +> You would have to write policy defining a `svirt_apache_t` type. If you want to prevent your container processes from gaining additional privileges, you can execute the following command: - $ docker run --security-opt no-new-privileges -it centos bash +```bash +$ docker run --security-opt no-new-privileges -it centos bash +``` This means that commands that raise privileges such as `su` or `sudo` will no longer work. It also causes any seccomp filters to be applied later, after privileges have been dropped @@ -774,25 +834,33 @@ We have four ways to set user memory usage: Examples: - $ docker run -it ubuntu:14.04 /bin/bash +```bash +$ docker run -it ubuntu:14.04 /bin/bash +``` We set nothing about memory, this means the processes in the container can use as much memory and swap memory as they need. - $ docker run -it -m 300M --memory-swap -1 ubuntu:14.04 /bin/bash +```bash +$ docker run -it -m 300M --memory-swap -1 ubuntu:14.04 /bin/bash +``` We set memory limit and disabled swap memory limit, this means the processes in the container can use 300M memory and as much swap memory as they need (if the host supports swap memory). - $ docker run -it -m 300M ubuntu:14.04 /bin/bash +```bash +$ docker run -it -m 300M ubuntu:14.04 /bin/bash +``` We set memory limit only, this means the processes in the container can use 300M memory and 300M swap memory, by default, the total virtual memory size (--memory-swap) will be set as double of memory, in this case, memory + swap would be 2*300M, so processes can use 300M swap memory as well. - $ docker run -it -m 300M --memory-swap 1G ubuntu:14.04 /bin/bash +```bash +$ docker run -it -m 300M --memory-swap 1G ubuntu:14.04 /bin/bash +``` We set both memory and swap memory, so the processes in the container can use 300M memory and 700M swap memory. @@ -844,11 +912,15 @@ memory. The following example limits the memory to 100M and disables the OOM killer for this container: - $ docker run -it -m 100M --oom-kill-disable ubuntu:14.04 /bin/bash +```bash +$ docker run -it -m 100M --oom-kill-disable ubuntu:14.04 /bin/bash +``` The following example, illustrates a dangerous way to use the flag: - $ docker run -it --oom-kill-disable ubuntu:14.04 /bin/bash +```bash +$ docker run -it --oom-kill-disable ubuntu:14.04 /bin/bash +``` The container has unlimited memory which can cause the host to run out memory and require killing system processes to free memory. The `--oom-score-adj` @@ -916,12 +988,16 @@ limit and "K" the kernel limit. There are three possible ways to set limits: Examples: - $ docker run -it -m 500M --kernel-memory 50M ubuntu:14.04 /bin/bash +```bash +$ docker run -it -m 500M --kernel-memory 50M ubuntu:14.04 /bin/bash +``` We set memory and kernel memory, so the processes in the container can use 500M memory in total, in this 500M memory, it can be 50M kernel memory tops. - $ docker run -it --kernel-memory 50M ubuntu:14.04 /bin/bash +```bash +$ docker run -it --kernel-memory 50M ubuntu:14.04 /bin/bash +``` We set kernel memory without **-m**, so the processes in the container can use as much memory as they want, but they can only use 50M kernel memory. @@ -936,7 +1012,9 @@ between 0 and 100. A value of 0 turns off anonymous page swapping. A value of For example, you can set: - $ docker run -it --memory-swappiness=0 ubuntu:14.04 /bin/bash +```bash +$ docker run -it --memory-swappiness=0 ubuntu:14.04 /bin/bash +``` Setting the `--memory-swappiness` option is helpful when you want to retain the container's working set and to avoid swapping performance penalties. @@ -985,7 +1063,9 @@ And usually `--cpu-period` should work with `--cpu-quota`. Examples: - $ docker run -it --cpu-period=50000 --cpu-quota=25000 ubuntu:14.04 /bin/bash +```bash +$ docker run -it --cpu-period=50000 --cpu-quota=25000 ubuntu:14.04 /bin/bash +``` If there is 1 CPU, this means the container can get 50% CPU worth of run-time every 50ms. @@ -1004,11 +1084,15 @@ We can set cpus in which to allow execution for containers. Examples: - $ docker run -it --cpuset-cpus="1,3" ubuntu:14.04 /bin/bash +```bash +$ docker run -it --cpuset-cpus="1,3" ubuntu:14.04 /bin/bash +``` This means processes in container can be executed on cpu 1 and cpu 3. - $ docker run -it --cpuset-cpus="0-2" ubuntu:14.04 /bin/bash +```bash +$ docker run -it --cpuset-cpus="0-2" ubuntu:14.04 /bin/bash +``` This means processes in container can be executed on cpu 0, cpu 1 and cpu 2. @@ -1017,12 +1101,16 @@ on NUMA systems. Examples: - $ docker run -it --cpuset-mems="1,3" ubuntu:14.04 /bin/bash +```bash +$ docker run -it --cpuset-mems="1,3" ubuntu:14.04 /bin/bash +``` This example restricts the processes in the container to only use memory from memory nodes 1 and 3. - $ docker run -it --cpuset-mems="0-2" ubuntu:14.04 /bin/bash +```bash +$ docker run -it --cpuset-mems="0-2" ubuntu:14.04 /bin/bash +``` This example restricts the processes in the container to only use memory from memory nodes 0, 1 and 2. @@ -1043,19 +1131,25 @@ By default, all containers get the same proportion of block IO bandwidth container's blkio weight relative to the weighting of all other running containers using the `--blkio-weight` flag. -> **Note:** The blkio weight setting is only available for direct IO. Buffered IO -> is not currently supported. +> **Note:** +> +> The blkio weight setting is only available for direct IO. Buffered IO is not +> currently supported. The `--blkio-weight` flag can set the weighting to a value between 10 to 1000. For example, the commands below create two containers with different blkio weight: - $ docker run -it --name c1 --blkio-weight 300 ubuntu:14.04 /bin/bash - $ docker run -it --name c2 --blkio-weight 600 ubuntu:14.04 /bin/bash +```bash +$ docker run -it --name c1 --blkio-weight 300 ubuntu:14.04 /bin/bash +$ docker run -it --name c2 --blkio-weight 600 ubuntu:14.04 /bin/bash +``` If you do block IO in the two containers at the same time, by, for example: - $ time dd if=/mnt/zerofile of=test.out bs=1M count=1024 oflag=direct +```bash +$ time dd if=/mnt/zerofile of=test.out bs=1M count=1024 oflag=direct +``` You'll find that the proportion of time is the same as the proportion of blkio weights of the two containers. @@ -1064,9 +1158,11 @@ The `--blkio-weight-device="DEVICE_NAME:WEIGHT"` flag sets a specific device wei The `DEVICE_NAME:WEIGHT` is a string containing a colon-separated device name and weight. For example, to set `/dev/sda` device weight to `200`: - $ docker run -it \ - --blkio-weight-device "/dev/sda:200" \ - ubuntu +```bash +$ docker run -it \ + --blkio-weight-device "/dev/sda:200" \ + ubuntu +``` If you specify both the `--blkio-weight` and `--blkio-weight-device`, Docker uses the `--blkio-weight` as the default weight and uses `--blkio-weight-device` @@ -1074,22 +1170,28 @@ to override this default with a new value on a specific device. The following example uses a default weight of `300` and overrides this default on `/dev/sda` setting that weight to `200`: - $ docker run -it \ - --blkio-weight 300 \ - --blkio-weight-device "/dev/sda:200" \ - ubuntu +```bash +$ docker run -it \ + --blkio-weight 300 \ + --blkio-weight-device "/dev/sda:200" \ + ubuntu +``` The `--device-read-bps` flag limits the read rate (bytes per second) from a device. For example, this command creates a container and limits the read rate to `1mb` per second from `/dev/sda`: - $ docker run -it --device-read-bps /dev/sda:1mb ubuntu +```bash +$ docker run -it --device-read-bps /dev/sda:1mb ubuntu +``` The `--device-write-bps` flag limits the write rate (bytes per second) to a device. For example, this command creates a container and limits the write rate to `1mb` per second for `/dev/sda`: - $ docker run -it --device-write-bps /dev/sda:1mb ubuntu +```bash +$ docker run -it --device-write-bps /dev/sda:1mb ubuntu +``` Both flags take limits in the `:[unit]` format. Both read and write rates must be a positive integer. You can specify the rate in `kb` @@ -1099,33 +1201,44 @@ The `--device-read-iops` flag limits read rate (IO per second) from a device. For example, this command creates a container and limits the read rate to `1000` IO per second from `/dev/sda`: - $ docker run -ti --device-read-iops /dev/sda:1000 ubuntu +```bash +$ docker run -ti --device-read-iops /dev/sda:1000 ubuntu +``` The `--device-write-iops` flag limits write rate (IO per second) to a device. For example, this command creates a container and limits the write rate to `1000` IO per second to `/dev/sda`: - $ docker run -ti --device-write-iops /dev/sda:1000 ubuntu +```bash +$ docker run -ti --device-write-iops /dev/sda:1000 ubuntu +``` Both flags take limits in the `:` format. Both read and write rates must be a positive integer. ## Additional groups - --group-add: Add additional groups to run as + +```bash +--group-add: Add additional groups to run as +``` By default, the docker container process runs with the supplementary groups looked up for the specified user. If one wants to add more to that list of groups, then one can use this flag: - $ docker run --rm --group-add audio --group-add nogroup --group-add 777 busybox id - uid=0(root) gid=0(root) groups=10(wheel),29(audio),99(nogroup),777 +```bash +$ docker run --rm --group-add audio --group-add nogroup --group-add 777 busybox id +uid=0(root) gid=0(root) groups=10(wheel),29(audio),99(nogroup),777 +``` ## Runtime privilege and Linux capabilities - --cap-add: Add Linux capabilities - --cap-drop: Drop Linux capabilities - --privileged=false: Give extended privileges to this container - --device=[]: Allows you to run devices inside the container without the --privileged flag. +| Option | Description | +|:---------------|:------------------------------------------------------------------------------| +| `--cap-add` | Add Linux capabilities | +| `--cap-drop` | Drop Linux capabilities | +| `--privileged` | Give extended privileges to this container | +| `--device=[]` | Allows you to run devices inside the container without the --privileged flag. | By default, Docker containers are "unprivileged" and cannot, for example, run a Docker daemon inside a Docker container. This is because @@ -1144,24 +1257,28 @@ If you want to limit access to a specific device or devices you can use the `--device` flag. It allows you to specify one or more devices that will be accessible within the container. - $ docker run --device=/dev/snd:/dev/snd ... +```bash +$ docker run --device=/dev/snd:/dev/snd ... +``` By default, the container will be able to `read`, `write`, and `mknod` these devices. This can be overridden using a third `:rwm` set of options to each `--device` flag: - $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc +```bash +$ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc - Command (m for help): q - $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc - You will not be able to write the partition table. +Command (m for help): q +$ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc +You will not be able to write the partition table. - Command (m for help): q +Command (m for help): q - $ docker run --device=/dev/sda:/dev/xvdc:w --rm -it ubuntu fdisk /dev/xvdc - crash.... +$ docker run --device=/dev/sda:/dev/xvdc:w --rm -it ubuntu fdisk /dev/xvdc + crash.... - $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc - fdisk: unable to open /dev/xvdc: Operation not permitted +$ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc +fdisk: unable to open /dev/xvdc: Operation not permitted +``` In addition to `--privileged`, the operator can have fine grain control over the capabilities using `--cap-add` and `--cap-drop`. By default, Docker has a default @@ -1218,37 +1335,52 @@ Further reference information is available on the [capabilities(7) - Linux man p Both flags support the value `ALL`, so if the operator wants to have all capabilities but `MKNOD` they could use: - $ docker run --cap-add=ALL --cap-drop=MKNOD ... +```bash +$ docker run --cap-add=ALL --cap-drop=MKNOD ... +``` For interacting with the network stack, instead of using `--privileged` they should use `--cap-add=NET_ADMIN` to modify the network interfaces. - $ docker run -it --rm ubuntu:14.04 ip link add dummy0 type dummy - RTNETLINK answers: Operation not permitted - $ docker run -it --rm --cap-add=NET_ADMIN ubuntu:14.04 ip link add dummy0 type dummy +```bash +$ docker run -it --rm ubuntu:14.04 ip link add dummy0 type dummy + +RTNETLINK answers: Operation not permitted + +$ docker run -it --rm --cap-add=NET_ADMIN ubuntu:14.04 ip link add dummy0 type dummy +``` To mount a FUSE based filesystem, you need to combine both `--cap-add` and `--device`: - $ docker run --rm -it --cap-add SYS_ADMIN sshfs sshfs sven@10.10.10.20:/home/sven /mnt - fuse: failed to open /dev/fuse: Operation not permitted - $ docker run --rm -it --device /dev/fuse sshfs sshfs sven@10.10.10.20:/home/sven /mnt - fusermount: mount failed: Operation not permitted - $ docker run --rm -it --cap-add SYS_ADMIN --device /dev/fuse sshfs - # sshfs sven@10.10.10.20:/home/sven /mnt - The authenticity of host '10.10.10.20 (10.10.10.20)' can't be established. - ECDSA key fingerprint is 25:34:85:75:25:b0:17:46:05:19:04:93:b5:dd:5f:c6. - Are you sure you want to continue connecting (yes/no)? yes - sven@10.10.10.20's password: - root@30aa0cfaf1b5:/# ls -la /mnt/src/docker - total 1516 - drwxrwxr-x 1 1000 1000 4096 Dec 4 06:08 . - drwxrwxr-x 1 1000 1000 4096 Dec 4 11:46 .. - -rw-rw-r-- 1 1000 1000 16 Oct 8 00:09 .dockerignore - -rwxrwxr-x 1 1000 1000 464 Oct 8 00:09 .drone.yml - drwxrwxr-x 1 1000 1000 4096 Dec 4 06:11 .git - -rw-rw-r-- 1 1000 1000 461 Dec 4 06:08 .gitignore - .... +```bash +$ docker run --rm -it --cap-add SYS_ADMIN sshfs sshfs sven@10.10.10.20:/home/sven /mnt + +fuse: failed to open /dev/fuse: Operation not permitted + +$ docker run --rm -it --device /dev/fuse sshfs sshfs sven@10.10.10.20:/home/sven /mnt + +fusermount: mount failed: Operation not permitted + +$ docker run --rm -it --cap-add SYS_ADMIN --device /dev/fuse sshfs + +# sshfs sven@10.10.10.20:/home/sven /mnt +The authenticity of host '10.10.10.20 (10.10.10.20)' can't be established. +ECDSA key fingerprint is 25:34:85:75:25:b0:17:46:05:19:04:93:b5:dd:5f:c6. +Are you sure you want to continue connecting (yes/no)? yes +sven@10.10.10.20's password: + +root@30aa0cfaf1b5:/# ls -la /mnt/src/docker + +total 1516 +drwxrwxr-x 1 1000 1000 4096 Dec 4 06:08 . +drwxrwxr-x 1 1000 1000 4096 Dec 4 11:46 .. +-rw-rw-r-- 1 1000 1000 16 Oct 8 00:09 .dockerignore +-rwxrwxr-x 1 1000 1000 464 Oct 8 00:09 .drone.yml +drwxrwxr-x 1 1000 1000 4096 Dec 4 06:11 .git +-rw-rw-r-- 1 1000 1000 461 Dec 4 06:08 .gitignore +.... +``` The default seccomp profile will adjust to the selected capabilities, in order to allow use of facilities allowed by the capabilities, so you should not have to adjust this, @@ -1304,7 +1436,9 @@ Dockerfile instruction and how the operator can override that setting. Recall the optional `COMMAND` in the Docker commandline: - $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] +```bash +$ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] +``` This command is optional because the person who created the `IMAGE` may have already provided a default `COMMAND` using the Dockerfile `CMD` @@ -1317,7 +1451,9 @@ get appended as arguments to the `ENTRYPOINT`. ### ENTRYPOINT (default command to execute at runtime) +```bash --entrypoint="": Overwrite the default entrypoint set by the image +``` The `ENTRYPOINT` of an image is similar to a `COMMAND` because it specifies what executable to run when the container starts, but it is @@ -1331,18 +1467,26 @@ runtime by using a string to specify the new `ENTRYPOINT`. Here is an example of how to run a shell in a container that has been set up to automatically run something else (like `/usr/bin/redis-server`): - $ docker run -it --entrypoint /bin/bash example/redis +```bash +$ docker run -it --entrypoint /bin/bash example/redis +``` or two examples of how to pass more parameters to that ENTRYPOINT: - $ docker run -it --entrypoint /bin/bash example/redis -c ls -l - $ docker run -it --entrypoint /usr/bin/redis-cli example/redis --help +```bash +$ docker run -it --entrypoint /bin/bash example/redis -c ls -l +$ docker run -it --entrypoint /usr/bin/redis-cli example/redis --help +``` You can reset a containers entrypoint by passing an empty string, for example: - $ docker run -it --entrypoint="" mysql bash +```bash +$ docker run -it --entrypoint="" mysql bash +``` -> **Note**: Passing `--entrypoint` will clear out any default command set on the +> **Note** +> +> Passing `--entrypoint` will clear out any default command set on the > image (i.e. any `CMD` instruction in the Dockerfile used to build it). ### EXPOSE (incoming ports) @@ -1426,6 +1570,7 @@ current value of the named variable is propagated into the container's environme ```bash $ export today=Wednesday $ docker run -e "deep=purple" -e today --rm alpine env + PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=d2219b854598 deep=purple @@ -1483,52 +1628,54 @@ Similarly the operator can set the **HOSTNAME** (Linux) or **COMPUTERNAME** (Win Example: - {% raw %} - $ docker run --name=test -d \ - --health-cmd='stat /etc/passwd || exit 1' \ - --health-interval=2s \ - busybox sleep 1d - $ sleep 2; docker inspect --format='{{.State.Health.Status}}' test - healthy - $ docker exec test rm /etc/passwd - $ sleep 2; docker inspect --format='{{json .State.Health}}' test +```bash +{% raw %} +$ docker run --name=test -d \ + --health-cmd='stat /etc/passwd || exit 1' \ + --health-interval=2s \ + busybox sleep 1d +$ sleep 2; docker inspect --format='{{.State.Health.Status}}' test +healthy +$ docker exec test rm /etc/passwd +$ sleep 2; docker inspect --format='{{json .State.Health}}' test +{ + "Status": "unhealthy", + "FailingStreak": 3, + "Log": [ { - "Status": "unhealthy", - "FailingStreak": 3, - "Log": [ - { - "Start": "2016-05-25T17:22:04.635478668Z", - "End": "2016-05-25T17:22:04.7272552Z", - "ExitCode": 0, - "Output": " File: /etc/passwd\n Size: 334 \tBlocks: 8 IO Block: 4096 regular file\nDevice: 32h/50d\tInode: 12 Links: 1\nAccess: (0664/-rw-rw-r--) Uid: ( 0/ root) Gid: ( 0/ root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..." - }, - { - "Start": "2016-05-25T17:22:06.732900633Z", - "End": "2016-05-25T17:22:06.822168935Z", - "ExitCode": 0, - "Output": " File: /etc/passwd\n Size: 334 \tBlocks: 8 IO Block: 4096 regular file\nDevice: 32h/50d\tInode: 12 Links: 1\nAccess: (0664/-rw-rw-r--) Uid: ( 0/ root) Gid: ( 0/ root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..." - }, - { - "Start": "2016-05-25T17:22:08.823956535Z", - "End": "2016-05-25T17:22:08.897359124Z", - "ExitCode": 1, - "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" - }, - { - "Start": "2016-05-25T17:22:10.898802931Z", - "End": "2016-05-25T17:22:10.969631866Z", - "ExitCode": 1, - "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" - }, - { - "Start": "2016-05-25T17:22:12.971033523Z", - "End": "2016-05-25T17:22:13.082015516Z", - "ExitCode": 1, - "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" - } - ] + "Start": "2016-05-25T17:22:04.635478668Z", + "End": "2016-05-25T17:22:04.7272552Z", + "ExitCode": 0, + "Output": " File: /etc/passwd\n Size: 334 \tBlocks: 8 IO Block: 4096 regular file\nDevice: 32h/50d\tInode: 12 Links: 1\nAccess: (0664/-rw-rw-r--) Uid: ( 0/ root) Gid: ( 0/ root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..." + }, + { + "Start": "2016-05-25T17:22:06.732900633Z", + "End": "2016-05-25T17:22:06.822168935Z", + "ExitCode": 0, + "Output": " File: /etc/passwd\n Size: 334 \tBlocks: 8 IO Block: 4096 regular file\nDevice: 32h/50d\tInode: 12 Links: 1\nAccess: (0664/-rw-rw-r--) Uid: ( 0/ root) Gid: ( 0/ root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..." + }, + { + "Start": "2016-05-25T17:22:08.823956535Z", + "End": "2016-05-25T17:22:08.897359124Z", + "ExitCode": 1, + "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" + }, + { + "Start": "2016-05-25T17:22:10.898802931Z", + "End": "2016-05-25T17:22:10.969631866Z", + "ExitCode": 1, + "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" + }, + { + "Start": "2016-05-25T17:22:12.971033523Z", + "End": "2016-05-25T17:22:13.082015516Z", + "ExitCode": 1, + "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" } - {% endraw %} + ] +} +{% endraw %} +``` The health status is also displayed in the `docker ps` output. @@ -1543,7 +1690,9 @@ The health status is also displayed in the `docker ps` output. The example below mounts an empty tmpfs into the container with the `rw`, `noexec`, `nosuid`, and `size=65536k` options. - $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image +```bash +$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image +``` ### VOLUME (shared filesystems) @@ -1562,7 +1711,8 @@ The example below mounts an empty tmpfs into the container with the `rw`, --volumes-from="": Mount all volumes from the given container(s) -> **Note**: +> **Note** +> > When using systemd to manage the Docker daemon's start and stop, in the systemd > unit file there is an option to control mount propagation for the Docker daemon > itself, called `MountFlags`. The value of this setting may cause Docker to not diff --git a/experimental/vlan-networks.md b/experimental/vlan-networks.md index f0309b1a9e..e1ef471d29 100644 --- a/experimental/vlan-networks.md +++ b/experimental/vlan-networks.md @@ -2,42 +2,67 @@ ### Getting Started -The Ipvlan driver is currently in experimental mode in order to incubate Docker users use cases and vet the implementation to ensure a hardened, production ready driver in a future release. Libnetwork now gives users total control over both IPv4 and IPv6 addressing. The VLAN driver builds on top of that in giving operators complete control of layer 2 VLAN tagging and even Ipvlan L3 routing for users interested in underlay network integration. For overlay deployments that abstract away physical constraints see the [multi-host overlay ](https://docs.docker.com/engine/userguide/networking/get-started-overlay/) driver. +The Ipvlan driver is currently in experimental mode in order to incubate Docker +users use cases and vet the implementation to ensure a hardened, production ready +driver in a future release. Libnetwork now gives users total control over both +IPv4 and IPv6 addressing. The VLAN driver builds on top of that in giving +operators complete control of layer 2 VLAN tagging and even Ipvlan L3 routing +for users interested in underlay network integration. For overlay deployments +that abstract away physical constraints see the +[multi-host overlay](https://docs.docker.com/network/network-tutorial-overlay/) +driver. -Ipvlan is a new twist on the tried and true network virtualization technique. The Linux implementations are extremely lightweight because rather than using the traditional Linux bridge for isolation, they are simply associated to a Linux Ethernet interface or sub-interface to enforce separation between networks and connectivity to the physical network. +Ipvlan is a new twist on the tried and true network virtualization technique. +The Linux implementations are extremely lightweight because rather than using +the traditional Linux bridge for isolation, they are simply associated to a Linux +Ethernet interface or sub-interface to enforce separation between networks and +connectivity to the physical network. -Ipvlan offers a number of unique features and plenty of room for further innovations with the various modes. Two high level advantages of these approaches are, the positive performance implications of bypassing the Linux bridge and the simplicity of having fewer moving parts. Removing the bridge that traditionally resides in between the Docker host NIC and container interface leaves a simple setup consisting of container interfaces, attached directly to the Docker host interface. This result is easy access for external facing services as there is no need for port mappings in these scenarios. +Ipvlan offers a number of unique features and plenty of room for further +innovations with the various modes. Two high level advantages of these approaches +are, the positive performance implications of bypassing the Linux bridge and the +simplicity of having fewer moving parts. Removing the bridge that traditionally +resides in between the Docker host NIC and container interface leaves a simple +setup consisting of container interfaces, attached directly to the Docker host +interface. This result is easy access for external facing services as there is +no need for port mappings in these scenarios. ### Pre-Requisites -- The examples on this page are all single host and setup using Docker experimental builds that can be installed with the following instructions: [Install Docker experimental](https://github.com/docker/docker/tree/master/experimental) - -- All of the examples can be performed on a single host running Docker. Any examples using a sub-interface like `eth0.10` can be replaced with `eth0` or any other valid parent interface on the Docker host. Sub-interfaces with a `.` are created on the fly. `-o parent` interfaces can also be left out of the `docker network create` all together and the driver will create a `dummy` interface that will enable local host connectivity to perform the examples. - +- The examples on this page are all single host and require using Docker + experimental features to be enabled. +- All of the examples can be performed on a single host running Docker. Any + example using a sub-interface like `eth0.10` can be replaced with `eth0` or + any other valid parent interface on the Docker host. Sub-interfaces with a `.` + are created on the fly. `-o parent` interfaces can also be left out of the + `docker network create` all together and the driver will create a `dummy` + interface that will enable local host connectivity to perform the examples. - Kernel requirements: - - - To check your current kernel version, use `uname -r` to display your kernel version - - Ipvlan Linux kernel v4.2+ (support for earlier kernels exists but is buggy) + - To check your current kernel version, use `uname -r` + - Ipvlan Linux kernel v4.2+ (support for earlier kernels exists but is buggy) ### Ipvlan L2 Mode Example Usage -An example of the ipvlan `L2` mode topology is shown in the following image. The driver is specified with `-d driver_name` option. In this case `-d ipvlan`. +An example of the ipvlan `L2` mode topology is shown in the following image. +The driver is specified with `-d driver_name` option. In this case `-d ipvlan`. ![Simple Ipvlan L2 Mode Example](images/ipvlan_l2_simple.png) -The parent interface in the next example `-o parent=eth0` is configured as followed: +The parent interface in the next example `-o parent=eth0` is configured as follows: -``` +```bash $ ip addr show eth0 3: eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 inet 192.168.1.250/24 brd 192.168.1.255 scope global eth0 ``` -Use the network from the host's interface as the `--subnet` in the `docker network create`. The container will be attached to the same network as the host interface as set via the `-o parent=` option. +Use the network from the host's interface as the `--subnet` in the +`docker network create`. The container will be attached to the same network as +the host interface as set via the `-o parent=` option. Create the ipvlan network and run a container attaching to it: -``` +```bash # Ipvlan (-o ipvlan_mode= Defaults to L2 mode if not specified) $ docker network create -d ipvlan \ --subnet=192.168.1.0/24 \ @@ -52,15 +77,22 @@ $ docker run --net=db_net -it --rm alpine /bin/sh # they are intentionally filtered by Linux for additional isolation. ``` -The default mode for Ipvlan is `l2`. If `-o ipvlan_mode=` are left unspecified, the default mode will be used. Similarly, if the `--gateway` is left empty, the first usable address on the network will be set as the gateway. For example, if the subnet provided in the network create is `--subnet=192.168.1.0/24` then the gateway the container receives is `192.168.1.1`. +The default mode for Ipvlan is `l2`. If `-o ipvlan_mode=` are left unspecified, +the default mode will be used. Similarly, if the `--gateway` is left empty, the +first usable address on the network will be set as the gateway. For example, if +the subnet provided in the network create is `--subnet=192.168.1.0/24` then the +gateway the container receives is `192.168.1.1`. -To help understand how this mode interacts with other hosts, the following figure shows the same layer 2 segment between two Docker hosts that applies to and Ipvlan L2 mode. +To help understand how this mode interacts with other hosts, the following +figure shows the same layer 2 segment between two Docker hosts that applies to +and Ipvlan L2 mode. ![Multiple Ipvlan Hosts](images/macvlan-bridge-ipvlan-l2.png) -The following will create the exact same network as the network `db_net` created prior, with the driver defaults for `--gateway=192.168.1.1` and `-o ipvlan_mode=l2`. +The following will create the exact same network as the network `db_net` created +prior, with the driver defaults for `--gateway=192.168.1.1` and `-o ipvlan_mode=l2`. -``` +```bash # Ipvlan (-o ipvlan_mode= Defaults to L2 mode if not specified) $ docker network create -d ipvlan \ --subnet=192.168.1.0/24 \ @@ -78,11 +110,19 @@ $ ping -c 4 ipv1 # they are intentionally filtered by Linux for additional isolation. ``` -The drivers also support the `--internal` flag that will completely isolate containers on a network from any communications external to that network. Since network isolation is tightly coupled to the network's parent interface the result of leaving the `-o parent=` option off of a `docker network create` is the exact same as the `--internal` option. If the parent interface is not specified or the `--internal` flag is used, a netlink type `dummy` parent interface is created for the user and used as the parent interface effectively isolating the network completely. +The drivers also support the `--internal` flag that will completely isolate +containers on a network from any communications external to that network. Since +network isolation is tightly coupled to the network's parent interface the result +of leaving the `-o parent=` option off of a `docker network create` is the exact +same as the `--internal` option. If the parent interface is not specified or the +`--internal` flag is used, a netlink type `dummy` parent interface is created +for the user and used as the parent interface effectively isolating the network +completely. -The following two `docker network create` examples result in identical networks that you can attach container to: +The following two `docker network create` examples result in identical networks +that you can attach container to: -``` +```bash # Empty '-o parent=' creates an isolated network $ docker network create -d ipvlan \ --subnet=192.168.10.0/24 isolated1 @@ -107,27 +147,59 @@ $ docker exec -it cid3 /bin/sh ### Ipvlan 802.1q Trunk L2 Mode Example Usage -Architecturally, Ipvlan L2 mode trunking is the same as Macvlan with regard to gateways and L2 path isolation. There are nuances that can be advantageous for CAM table pressure in ToR switches, one MAC per port and MAC exhaustion on a host's parent NIC to name a few. The 802.1q trunk scenario looks the same. Both modes adhere to tagging standards and have seamless integration with the physical network for underlay integration and hardware vendor plugin integrations. +Architecturally, Ipvlan L2 mode trunking is the same as Macvlan with regard to +gateways and L2 path isolation. There are nuances that can be advantageous for +CAM table pressure in ToR switches, one MAC per port and MAC exhaustion on a +host's parent NIC to name a few. The 802.1q trunk scenario looks the same. Both +modes adhere to tagging standards and have seamless integration with the physical +network for underlay integration and hardware vendor plugin integrations. -Hosts on the same VLAN are typically on the same subnet and almost always are grouped together based on their security policy. In most scenarios, a multi-tier application is tiered into different subnets because the security profile of each process requires some form of isolation. For example, hosting your credit card processing on the same virtual network as the frontend webserver would be a regulatory compliance issue, along with circumventing the long standing best practice of layered defense in depth architectures. VLANs or the equivocal VNI (Virtual Network Identifier) when using the Overlay driver, are the first step in isolating tenant traffic. +Hosts on the same VLAN are typically on the same subnet and almost always are +grouped together based on their security policy. In most scenarios, a multi-tier +application is tiered into different subnets because the security profile of each +process requires some form of isolation. For example, hosting your credit card +processing on the same virtual network as the frontend webserver would be a +regulatory compliance issue, along with circumventing the long standing best +practice of layered defense in depth architectures. VLANs or the equivocal VNI +(Virtual Network Identifier) when using the Overlay driver, are the first step +in isolating tenant traffic. ![Docker VLANs in Depth](images/vlans-deeper-look.png) -The Linux sub-interface tagged with a vlan can either already exist or will be created when you call a `docker network create`. `docker network rm` will delete the sub-interface. Parent interfaces such as `eth0` are not deleted, only sub-interfaces with a netlink parent index > 0. +The Linux sub-interface tagged with a vlan can either already exist or will be +created when you call a `docker network create`. `docker network rm` will delete +the sub-interface. Parent interfaces such as `eth0` are not deleted, only +sub-interfaces with a netlink parent index > 0. -For the driver to add/delete the vlan sub-interfaces the format needs to be `interface_name.vlan_tag`. Other sub-interface naming can be used as the specified parent, but the link will not be deleted automatically when `docker network rm` is invoked. +For the driver to add/delete the vlan sub-interfaces the format needs to be +`interface_name.vlan_tag`. Other sub-interface naming can be used as the +specified parent, but the link will not be deleted automatically when +`docker network rm` is invoked. -The option to use either existing parent vlan sub-interfaces or let Docker manage them enables the user to either completely manage the Linux interfaces and networking or let Docker create and delete the Vlan parent sub-interfaces (netlink `ip link`) with no effort from the user. +The option to use either existing parent vlan sub-interfaces or let Docker manage +them enables the user to either completely manage the Linux interfaces and +networking or let Docker create and delete the Vlan parent sub-interfaces +(netlink `ip link`) with no effort from the user. -For example: use `eth0.10` to denote a sub-interface of `eth0` tagged with the vlan id of `10`. The equivalent `ip link` command would be `ip link add link eth0 name eth0.10 type vlan id 10`. +For example: use `eth0.10` to denote a sub-interface of `eth0` tagged with the +vlan id of `10`. The equivalent `ip link` command would be +`ip link add link eth0 name eth0.10 type vlan id 10`. -The example creates the vlan tagged networks and then start two containers to test connectivity between containers. Different Vlans cannot ping one another without a router routing between the two networks. The default namespace is not reachable per ipvlan design in order to isolate container namespaces from the underlying host. +The example creates the vlan tagged networks and then start two containers to +test connectivity between containers. Different Vlans cannot ping one another +without a router routing between the two networks. The default namespace is not +reachable per ipvlan design in order to isolate container namespaces from the +underlying host. **Vlan ID 20** -In the first network tagged and isolated by the Docker host, `eth0.20` is the parent interface tagged with vlan id `20` specified with `-o parent=eth0.20`. Other naming formats can be used, but the links need to be added and deleted manually using `ip link` or Linux configuration files. As long as the `-o parent` exists anything can be used if compliant with Linux netlink. +In the first network tagged and isolated by the Docker host, `eth0.20` is the +parent interface tagged with vlan id `20` specified with `-o parent=eth0.20`. +Other naming formats can be used, but the links need to be added and deleted +manually using `ip link` or Linux configuration files. As long as the `-o parent` +exists anything can be used if compliant with Linux netlink. -``` +```bash # now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged $ docker network create -d ipvlan \ --subnet=192.168.20.0/24 \ @@ -141,9 +213,12 @@ $ docker run --net=ipvlan20 -it --name ivlan_test2 --rm alpine /bin/sh **Vlan ID 30** -In the second network, tagged and isolated by the Docker host, `eth0.30` is the parent interface tagged with vlan id `30` specified with `-o parent=eth0.30`. The `ipvlan_mode=` defaults to l2 mode `ipvlan_mode=l2`. It can also be explicitly set with the same result as shown in the next example. +In the second network, tagged and isolated by the Docker host, `eth0.30` is the +parent interface tagged with vlan id `30` specified with `-o parent=eth0.30`. The +`ipvlan_mode=` defaults to l2 mode `ipvlan_mode=l2`. It can also be explicitly +set with the same result as shown in the next example. -``` +```bash # now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged. $ docker network create -d ipvlan \ --subnet=192.168.30.0/24 \ @@ -156,19 +231,25 @@ $ docker run --net=ipvlan30 -it --name ivlan_test3 --rm alpine /bin/sh $ docker run --net=ipvlan30 -it --name ivlan_test4 --rm alpine /bin/sh ``` -The gateway is set inside of the container as the default gateway. That gateway would typically be an external router on the network. +The gateway is set inside of the container as the default gateway. That gateway +would typically be an external router on the network. -``` +```bash $$ ip route default via 192.168.30.1 dev eth0 192.168.30.0/24 dev eth0 src 192.168.30.2 ``` -Example: Multi-Subnet Ipvlan L2 Mode starting two containers on the same subnet and pinging one another. In order for the `192.168.114.0/24` to reach `192.168.116.0/24` it requires an external router in L2 mode. L3 mode can route between subnets that share a common `-o parent=`. +Example: Multi-Subnet Ipvlan L2 Mode starting two containers on the same subnet +and pinging one another. In order for the `192.168.114.0/24` to reach +`192.168.116.0/24` it requires an external router in L2 mode. L3 mode can route +between subnets that share a common `-o parent=`. -Secondary addresses on network routers are common as an address space becomes exhausted to add another secondary to an L3 vlan interface or commonly referred to as a "switched virtual interface" (SVI). +Secondary addresses on network routers are common as an address space becomes +exhausted to add another secondary to an L3 vlan interface or commonly referred +to as a "switched virtual interface" (SVI). -``` +```bash $ docker network create -d ipvlan \ --subnet=192.168.114.0/24 --subnet=192.168.116.0/24 \ --gateway=192.168.114.254 --gateway=192.168.116.254 \ @@ -179,50 +260,87 @@ $ docker run --net=ipvlan114 --ip=192.168.114.10 -it --rm alpine /bin/sh $ docker run --net=ipvlan114 --ip=192.168.114.11 -it --rm alpine /bin/sh ``` -A key takeaway is, operators have the ability to map their physical network into their virtual network for integrating containers into their environment with no operational overhauls required. NetOps simply drops an 802.1q trunk into the Docker host. That virtual link would be the `-o parent=` passed in the network creation. For untagged (non-VLAN) links, it is as simple as `-o parent=eth0` or for 802.1q trunks with VLAN IDs each network gets mapped to the corresponding VLAN/Subnet from the network. +A key takeaway is, operators have the ability to map their physical network into +their virtual network for integrating containers into their environment with no +operational overhauls required. NetOps simply drops an 802.1q trunk into the +Docker host. That virtual link would be the `-o parent=` passed in the network +creation. For untagged (non-VLAN) links, it is as simple as `-o parent=eth0` or +for 802.1q trunks with VLAN IDs each network gets mapped to the corresponding +VLAN/Subnet from the network. -An example being, NetOps provides VLAN ID and the associated subnets for VLANs being passed on the Ethernet link to the Docker host server. Those values are simply plugged into the `docker network create` commands when provisioning the Docker networks. These are persistent configurations that are applied every time the Docker engine starts which alleviates having to manage often complex configuration files. The network interfaces can also be managed manually by being pre-created and docker networking will never modify them, simply use them as parent interfaces. Example mappings from NetOps to Docker network commands are as follows: +An example being, NetOps provides VLAN ID and the associated subnets for VLANs +being passed on the Ethernet link to the Docker host server. Those values are +simply plugged into the `docker network create` commands when provisioning the +Docker networks. These are persistent configurations that are applied every time +the Docker engine starts which alleviates having to manage often complex +configuration files. The network interfaces can also be managed manually by +being pre-created and docker networking will never modify them, simply use them +as parent interfaces. Example mappings from NetOps to Docker network commands +are as follows: - VLAN: 10, Subnet: 172.16.80.0/24, Gateway: 172.16.80.1 - - `--subnet=172.16.80.0/24 --gateway=172.16.80.1 -o parent=eth0.10` - - VLAN: 20, IP subnet: 172.16.50.0/22, Gateway: 172.16.50.1 - - `--subnet=172.16.50.0/22 --gateway=172.16.50.1 -o parent=eth0.20 ` - - VLAN: 30, Subnet: 10.1.100.0/16, Gateway: 10.1.100.1 - - `--subnet=10.1.100.0/16 --gateway=10.1.100.1 -o parent=eth0.30` ### IPVlan L3 Mode Example -IPVlan will require routes to be distributed to each endpoint. The driver only builds the Ipvlan L3 mode port and attaches the container to the interface. Route distribution throughout a cluster is beyond the initial implementation of this single host scoped driver. In L3 mode, the Docker host is very similar to a router starting new networks in the container. They are on networks that the upstream network will not know about without route distribution. For those curious how Ipvlan L3 will fit into container networking see the following examples. +IPVlan will require routes to be distributed to each endpoint. The driver only +builds the Ipvlan L3 mode port and attaches the container to the interface. Route +distribution throughout a cluster is beyond the initial implementation of this +single host scoped driver. In L3 mode, the Docker host is very similar to a +router starting new networks in the container. They are on networks that the +upstream network will not know about without route distribution. For those +curious how Ipvlan L3 will fit into container networking see the following +examples. ![Docker Ipvlan L2 Mode](images/ipvlan-l3.png) -Ipvlan L3 mode drops all broadcast and multicast traffic. This reason alone makes Ipvlan L3 mode a prime candidate for those looking for massive scale and predictable network integrations. It is predictable and in turn will lead to greater uptimes because there is no bridging involved. Bridging loops have been responsible for high profile outages that can be hard to pinpoint depending on the size of the failure domain. This is due to the cascading nature of BPDUs (Bridge Port Data Units) that are flooded throughout a broadcast domain (VLAN) to find and block topology loops. Eliminating bridging domains, or at the least, keeping them isolated to a pair of ToRs (top of rack switches) will reduce hard to troubleshoot bridging instabilities. Ipvlan L2 modes is well suited for isolated VLANs only trunked into a pair of ToRs that can provide a loop-free non-blocking fabric. The next step further is to route at the edge via Ipvlan L3 mode that reduces a failure domain to a local host only. +Ipvlan L3 mode drops all broadcast and multicast traffic. This reason alone +makes Ipvlan L3 mode a prime candidate for those looking for massive scale and +predictable network integrations. It is predictable and in turn will lead to +greater uptimes because there is no bridging involved. Bridging loops have been +responsible for high profile outages that can be hard to pinpoint depending on +the size of the failure domain. This is due to the cascading nature of BPDUs +(Bridge Port Data Units) that are flooded throughout a broadcast domain (VLAN) +to find and block topology loops. Eliminating bridging domains, or at the least, +keeping them isolated to a pair of ToRs (top of rack switches) will reduce hard +to troubleshoot bridging instabilities. Ipvlan L2 modes is well suited for +isolated VLANs only trunked into a pair of ToRs that can provide a loop-free +non-blocking fabric. The next step further is to route at the edge via Ipvlan L3 +mode that reduces a failure domain to a local host only. -- L3 mode needs to be on a separate subnet as the default namespace since it requires a netlink route in the default namespace pointing to the Ipvlan parent interface. +- L3 mode needs to be on a separate subnet as the default namespace since it + requires a netlink route in the default namespace pointing to the Ipvlan parent + interface. +- The parent interface used in this example is `eth0` and it is on the subnet + `192.168.1.0/24`. Notice the `docker network` is **not** on the same subnet + as `eth0`. +- Unlike ipvlan l2 modes, different subnets/networks can ping one another as + long as they share the same parent interface `-o parent=`. -- The parent interface used in this example is `eth0` and it is on the subnet `192.168.1.0/24`. Notice the `docker network` is **not** on the same subnet as `eth0`. - -- Unlike ipvlan l2 modes, different subnets/networks can ping one another as long as they share the same parent interface `-o parent=`. - -``` +```bash $$ ip a show eth0 3: eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 link/ether 00:50:56:39:45:2e brd ff:ff:ff:ff:ff:ff inet 192.168.1.250/24 brd 192.168.1.255 scope global eth0 ``` -- A traditional gateway doesn't mean much to an L3 mode Ipvlan interface since there is no broadcast traffic allowed. Because of that, the container default gateway simply points to the containers `eth0` device. See below for CLI output of `ip route` or `ip -6 route` from inside an L3 container for details. +- A traditional gateway doesn't mean much to an L3 mode Ipvlan interface since + there is no broadcast traffic allowed. Because of that, the container default + gateway simply points to the containers `eth0` device. See below for CLI output + of `ip route` or `ip -6 route` from inside an L3 container for details. -The mode ` -o ipvlan_mode=l3` must be explicitly specified since the default ipvlan mode is `l2`. +The mode ` -o ipvlan_mode=l3` must be explicitly specified since the default +ipvlan mode is `l2`. -The following example does not specify a parent interface. The network drivers will create a dummy type link for the user rather than rejecting the network creation and isolating containers from only communicating with one another. +The following example does not specify a parent interface. The network drivers +will create a dummy type link for the user rather than rejecting the network +creation and isolating containers from only communicating with one another. -``` +```bash # Create the Ipvlan L3 network $ docker network create -d ipvlan \ --subnet=192.168.214.0/24 \ @@ -241,24 +359,36 @@ $ docker run --net=ipnet210 --ip=10.1.214.9 -it --rm alpine ping -c 2 192.168.21 ``` -Notice there is no `--gateway=` option in the network create. The field is ignored if one is specified `l3` mode. Take a look at the container routing table from inside of the container: +> **Note** +> +> Notice that there is no `--gateway=` option in the network create. The field +> is ignored if one is specified `l3` mode. Take a look at the container routing +> table from inside of the container: +> +> ```bash +> # Inside an L3 mode container +> $$ ip route +> default dev eth0 +> 192.168.214.0/24 dev eth0 src 192.168.214.10 +> ``` -``` -# Inside an L3 mode container -$$ ip route - default dev eth0 - 192.168.214.0/24 dev eth0 src 192.168.214.10 -``` - -In order to ping the containers from a remote Docker host or the container be able to ping a remote host, the remote host or the physical network in between need to have a route pointing to the host IP address of the container's Docker host eth interface. More on this as we evolve the Ipvlan `L3` story. +In order to ping the containers from a remote Docker host or the container be +able to ping a remote host, the remote host or the physical network in between +need to have a route pointing to the host IP address of the container's Docker +host eth interface. More on this as we evolve the Ipvlan `L3` story. ### Dual Stack IPv4 IPv6 Ipvlan L2 Mode -- Not only does Libnetwork give you complete control over IPv4 addressing, but it also gives you total control over IPv6 addressing as well as feature parity between the two address families. +- Not only does Libnetwork give you complete control over IPv4 addressing, but +it also gives you total control over IPv6 addressing as well as feature parity +between the two address families. -- The next example will start with IPv6 only. Start two containers on the same VLAN `139` and ping one another. Since the IPv4 subnet is not specified, the default IPAM will provision a default IPv4 subnet. That subnet is isolated unless the upstream network is explicitly routing it on VLAN `139`. +- The next example will start with IPv6 only. Start two containers on the same +VLAN `139` and ping one another. Since the IPv4 subnet is not specified, the +default IPAM will provision a default IPv4 subnet. That subnet is isolated +unless the upstream network is explicitly routing it on VLAN `139`. -``` +```bash # Create a v6 network $ docker network create -d ipvlan \ --subnet=2001:db8:abc2::/64 --gateway=2001:db8:abc2::22 \ @@ -266,12 +396,11 @@ $ docker network create -d ipvlan \ # Start a container on the network $ docker run --net=v6ipvlan139 -it --rm alpine /bin/sh - ``` View the container eth0 interface and v6 routing table: -``` +```bash # Inside the IPv6 container $$ ip a show eth0 75: eth0@if55: mtu 1500 qdisc noqueue state UNKNOWN group default @@ -291,7 +420,7 @@ default via 2001:db8:abc2::22 dev eth0 metric 1024 Start a second container and ping the first container's v6 address. -``` +```bash # Test L2 connectivity over IPv6 $ docker run --net=v6ipvlan139 -it --rm alpine /bin/sh @@ -315,11 +444,13 @@ PING 2001:db8:abc2::1 (2001:db8:abc2::1): 56 data bytes round-trip min/avg/max/stddev = 0.044/0.051/0.058/0.000 ms ``` -The next example with setup a dual stack IPv4/IPv6 network with an example VLAN ID of `140`. +The next example with setup a dual stack IPv4/IPv6 network with an example +VLAN ID of `140`. -Next create a network with two IPv4 subnets and one IPv6 subnets, all of which have explicit gateways: +Next create a network with two IPv4 subnets and one IPv6 subnets, all of which +have explicit gateways: -``` +```bash $ docker network create -d ipvlan \ --subnet=192.168.140.0/24 --subnet=192.168.142.0/24 \ --gateway=192.168.140.1 --gateway=192.168.142.1 \ @@ -330,7 +461,7 @@ $ docker network create -d ipvlan \ Start a container and view eth0 and both v4 & v6 routing tables: -``` +```bash $ docker run --net=ipvlan140 --ip6=2001:db8:abc2::51 -it --rm alpine /bin/sh $ ip a show eth0 @@ -353,23 +484,37 @@ $$ ip -6 route default via 2001:db8:abc9::22 dev eth0 metric 1024 ``` -Start a second container with a specific `--ip4` address and ping the first host using IPv4 packets: +Start a second container with a specific `--ip4` address and ping the first host +using IPv4 packets: -``` +```bash $ docker run --net=ipvlan140 --ip=192.168.140.10 -it --rm alpine /bin/sh ``` -**Note**: Different subnets on the same parent interface in Ipvlan `L2` mode cannot ping one another. That requires a router to proxy-arp the requests with a secondary subnet. However, Ipvlan `L3` will route the unicast traffic between disparate subnets as long as they share the same `-o parent` parent link. +> **Note** +> +> Different subnets on the same parent interface in Ipvlan `L2` mode cannot ping +> one another. That requires a router to proxy-arp the requests with a secondary +> subnet. However, Ipvlan `L3` will route the unicast traffic between disparate +> subnets as long as they share the same `-o parent` parent link. ### Dual Stack IPv4 IPv6 Ipvlan L3 Mode **Example:** IpVlan L3 Mode Dual Stack IPv4/IPv6, Multi-Subnet w/ 802.1q Vlan Tag:118 -As in all of the examples, a tagged VLAN interface does not have to be used. The sub-interfaces can be swapped with `eth0`, `eth1`, `bond0` or any other valid interface on the host other then the `lo` loopback. +As in all of the examples, a tagged VLAN interface does not have to be used. The +sub-interfaces can be swapped with `eth0`, `eth1`, `bond0` or any other valid +interface on the host other then the `lo` loopback. -The primary difference you will see is that L3 mode does not create a default route with a next-hop but rather sets a default route pointing to `dev eth` only since ARP/Broadcasts/Multicast are all filtered by Linux as per the design. Since the parent interface is essentially acting as a router, the parent interface IP and subnet needs to be different from the container networks. That is the opposite of bridge and L2 modes, which need to be on the same subnet (broadcast domain) in order to forward broadcast and multicast packets. +The primary difference you will see is that L3 mode does not create a default +route with a next-hop but rather sets a default route pointing to `dev eth` only +since ARP/Broadcasts/Multicast are all filtered by Linux as per the design. Since +the parent interface is essentially acting as a router, the parent interface IP +and subnet needs to be different from the container networks. That is the opposite +of bridge and L2 modes, which need to be on the same subnet (broadcast domain) +in order to forward broadcast and multicast packets. -``` +```bash # Create an IPv6+IPv4 Dual Stack Ipvlan L3 network # Gateways for both v4 and v6 are set to a dev e.g. 'default dev eth0' $ docker network create -d ipvlan \ @@ -393,7 +538,7 @@ $ docker run --net=ipnet110 --ip6=2001:db8:abc6::50 --ip=192.168.112.50 -it --rm Interface and routing table outputs are as follows: -``` +```bash $$ ip a show eth0 63: eth0@if59: mtu 1500 qdisc noqueue state UNKNOWN group default link/ether 00:50:56:2b:29:40 brd ff:ff:ff:ff:ff:ff @@ -415,9 +560,14 @@ $$ ip -6 route default dev eth0 metric 1024 ``` -*Note:* There may be a bug when specifying `--ip6=` addresses when you delete a container with a specified v6 address and then start a new container with the same v6 address it throws the following like the address isn't properly being released to the v6 pool. It will fail to unmount the container and be left dead. +> *Note* +> +> There may be a bug when specifying `--ip6=` addresses when you delete a +> container with a specified v6 address and then start a new container with the +> same v6 address it throws the following like the address isn't properly being +> released to the v6 pool. It will fail to unmount the container and be left dead. -``` +```console docker: Error response from daemon: Address already in use. ``` @@ -425,11 +575,16 @@ docker: Error response from daemon: Address already in use. **Vlan ID 40** -If a user does not want the driver to create the vlan sub-interface it simply needs to exist prior to the `docker network create`. If you have sub-interface naming that is not `interface.vlan_id` it is honored in the `-o parent=` option again as long as the interface exists and is up. +If a user does not want the driver to create the vlan sub-interface it simply +needs to exist prior to the `docker network create`. If you have sub-interface +naming that is not `interface.vlan_id` it is honored in the `-o parent=` option +again as long as the interface exists and is up. -Links, when manually created, can be named anything as long as they exist when the network is created. Manually created links do not get deleted regardless of the name when the network is deleted with `docker network rm`. +Links, when manually created, can be named anything as long as they exist when +the network is created. Manually created links do not get deleted regardless of +the name when the network is deleted with `docker network rm`. -``` +```bash # create a new sub-interface tied to dot1q vlan 40 $ ip link add link eth0 name eth0.40 type vlan id 40 @@ -449,7 +604,7 @@ $ docker run --net=ipvlan40 -it --name ivlan_test6 --rm alpine /bin/sh **Example:** Vlan sub-interface manually created with any name: -``` +```bash # create a new sub interface tied to dot1q vlan 40 $ ip link add link eth0 name foo type vlan id 40 @@ -468,8 +623,10 @@ $ docker run --net=ipvlan40 -it --name ivlan_test6 --rm alpine /bin/sh Manually created links can be cleaned up with: -``` +```bash $ ip link del foo ``` -As with all of the Libnetwork drivers, they can be mixed and matched, even as far as running 3rd party ecosystem drivers in parallel for maximum flexibility to the Docker user. +As with all of the Libnetwork drivers, they can be mixed and matched, even as +far as running 3rd party ecosystem drivers in parallel for maximum flexibility +to the Docker user.