diff --git a/docs/reference/commandline/docker.md b/docs/reference/commandline/docker.md index e339c0cdb9..23d1a6bf48 100644 --- a/docs/reference/commandline/docker.md +++ b/docs/reference/commandline/docker.md @@ -3,8 +3,7 @@ -The base command for the Docker CLI is `docker`. For information about the -available flags and subcommands, refer to the [CLI reference](https://docs.docker.com/reference/cli/docker/) +## Description Depending on your Docker system configuration, you may be required to preface each `docker` command with `sudo`. To avoid having to use `sudo` with the @@ -14,7 +13,25 @@ each `docker` command with `sudo`. To avoid having to use `sudo` with the For more information about installing Docker or `sudo` configuration, refer to the [installation](https://docs.docker.com/install/) instructions for your operating system. -## Environment variables +### Display help text + +To list the help on any command just execute the command, followed by the +`--help` option. + +```console +$ docker run --help + +Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] + +Create and run a new container from an image + +Options: + --add-host value Add a custom host-to-IP mapping (host:ip) (default []) + -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) +<...> +``` + +### Environment variables The following list of environment variables are supported by the `docker` command line: @@ -46,7 +63,60 @@ variables used by the Go runtime. In particular, you may find these useful: See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) for details on these variables. -## Configuration files +### Option types + +Single character command line options can be combined, so rather than +typing `docker run -i -t --name test busybox sh`, +you can write `docker run -it --name test busybox sh`. + +#### Boolean + +Boolean options take the form `-d=false`. The value you see in the help text is +the default value which is set if you do **not** specify that flag. If you +specify a Boolean flag without a value, this will set the flag to `true`, +irrespective of the default value. + +For example, running `docker run -d` will set the value to `true`, so your +container **will** run in "detached" mode, in the background. + +Options which default to `true` (e.g., `docker build --rm=true`) can only be +set to the non-default value by explicitly setting them to `false`: + +```console +$ docker build --rm=false . +``` + +#### Multi + +You can specify options like `-a=[]` multiple times in a single command line, +for example in these commands: + +```console +$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash + +$ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls +``` + +Sometimes, multiple options can call for a more complex value string as for +`-v`: + +```console +$ docker run -v /host:/container example/mysql +``` + +> **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`. + +#### Strings and Integers + +Options like `--name=""` expect a string, and they +can only be specified once. Options like `-c=0` +expect an integer, and they can only be specified once. + +### Configuration files By default, the Docker command line stores its configuration files in a directory called `.docker` within your `$HOME` directory. @@ -63,7 +133,7 @@ and the `--config` flag are set, the flag takes precedent over the environment variable. Command line options override environment variables and environment variables override properties you specify in a `config.json` file. -### Change the `.docker` directory +#### Change the `.docker` directory To specify a different directory, use the `DOCKER_CONFIG` environment variable or the `--config` command line option. If both are @@ -84,7 +154,7 @@ directory to be `HOME/newdir/.docker`. $ echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile ``` -## Docker CLI configuration file (`config.json`) properties +### Docker CLI configuration file (`config.json`) properties @@ -103,7 +173,7 @@ different location. > registries. Review your configuration file's content before sharing with others, > and prevent committing the file to version control. -### Customize the default output format for commands +#### Customize the default output format for commands These fields lets you customize the default output format for some commands if no `--format` flag is provided. @@ -123,14 +193,14 @@ if no `--format` flag is provided. | `tasksFormat` | Custom default format for `docker stack ps` output. See [`docker stack ps`](https://docs.docker.com/reference/cli/docker/stack/ps/#format) for a list of supported formatting directives. | | `volumesFormat` | Custom default format for `docker volume ls` output. See [`docker volume ls`](https://docs.docker.com/reference/cli/docker/volume/ls/#format) for a list of supported formatting directives. | -### Custom HTTP headers +#### Custom HTTP headers The property `HttpHeaders` specifies a set of headers to include in all messages sent from the Docker client to the daemon. Docker doesn't try to interpret or understand these headers; it simply puts them into the messages. Docker does not allow these headers to change any headers it sets for itself. -### Credential store options +#### Credential store options The property `credsStore` specifies an external binary to serve as the default credential store. When this property is set, `docker login` will attempt to @@ -146,7 +216,7 @@ credentials for specific registries. If this property is set, the binary for a specific registry. For more information, see the [**Credential helpers** section in the `docker login` documentation](https://docs.docker.com/reference/cli/docker/login/#credential-helpers) -### Automatic proxy configuration for containers +#### Automatic proxy configuration for containers The property `proxies` specifies proxy environment variables to be automatically set on containers, and set as `--build-arg` on containers used during `docker build`. @@ -176,7 +246,7 @@ sections for configuring proxy settings for the cli and daemon. > API or committed to an image when using `docker commit`. { .warning } -### Default key-sequence to detach from containers +#### Default key-sequence to detach from containers Once attached to a container, users detach from it and leave it running using the using `CTRL-p CTRL-q` key sequence. This detach key sequence is customizable @@ -196,13 +266,13 @@ Users can override your custom or the default key sequence on a per-container basis. To do this, the user specifies the `--detach-keys` flag with the `docker attach`, `docker exec`, `docker run` or `docker start` command. -### CLI plugin options +#### CLI plugin options The property `plugins` contains settings specific to CLI plugins. The key is the plugin name, while the value is a further map of options, which are specific to that plugin. -### Sample configuration file +#### Sample configuration file Following is a sample `config.json` file to illustrate the format used for various fields: @@ -252,7 +322,7 @@ various fields: } ``` -### Experimental features +#### Experimental features Experimental features provide early access to future product functionality. These features are intended for testing and feedback, and they may change @@ -261,7 +331,7 @@ between releases without warning or can be removed from a future release. Starting with Docker 20.10, experimental CLI features are enabled by default, and require no configuration to enable them. -### Notary +#### Notary If using your own notary server and a self-signed certificate or an internal Certificate Authority, you need to place the certificate at @@ -328,74 +398,3 @@ component to the end of the SSH address. ```console $ docker -H ssh://user@192.168.64.5/var/run/docker.sock ps ``` - -### Display help text - -To list the help on any command just execute the command, followed by the -`--help` option. - -```console -$ docker run --help - -Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] - -Create and run a new container from an image - -Options: - --add-host value Add a custom host-to-IP mapping (host:ip) (default []) - -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) -<...> -``` - -### Option types - -Single character command line options can be combined, so rather than -typing `docker run -i -t --name test busybox sh`, -you can write `docker run -it --name test busybox sh`. - -#### Boolean - -Boolean options take the form `-d=false`. The value you see in the help text is -the default value which is set if you do **not** specify that flag. If you -specify a Boolean flag without a value, this will set the flag to `true`, -irrespective of the default value. - -For example, running `docker run -d` will set the value to `true`, so your -container **will** run in "detached" mode, in the background. - -Options which default to `true` (e.g., `docker build --rm=true`) can only be -set to the non-default value by explicitly setting them to `false`: - -```console -$ docker build --rm=false . -``` - -#### Multi - -You can specify options like `-a=[]` multiple times in a single command line, -for example in these commands: - -```console -$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash - -$ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls -``` - -Sometimes, multiple options can call for a more complex value string as for -`-v`: - -```console -$ docker run -v /host:/container example/mysql -``` - -> **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`. - -#### Strings and Integers - -Options like `--name=""` expect a string, and they -can only be specified once. Options like `-c=0` -expect an integer, and they can only be specified once.