docker

Description

Depending on your Docker system configuration, you may be required to prefaceeachdocker command withsudo. To avoid having to usesudo with thedocker command, your system administrator can create a Unix group calleddocker and add users to it.

For more information about installing Docker orsudo configuration, refer totheinstallation instructions for your operating system.

Display help text

To list the help on any command just execute the command, followed by the--help option.

$ docker run --helpUsage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]Create and run a new container from an imageOptions:      --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 thedocker commandline:

Because Docker is developed using Go, you can also use any environmentvariables used by the Go runtime. In particular, you may find these useful:

See theGo specificationfor details on these variables.

Option types

Single character command line options can be combined, so rather thantypingdocker run -i -t --name test busybox sh,you can writedocker run -it --name test busybox sh.

Boolean

Boolean options take the form-d=false. The value you see in the help text isthe default value which is set if you donot specify that flag. If youspecify a Boolean flag without a value, this will set the flag totrue,irrespective of the default value.

For example, runningdocker run -d will set the value totrue, so yourcontainerwill run in "detached" mode, in the background.

Options which default totrue (e.g.,docker build --rm=true) can only beset to the non-default value by explicitly setting them tofalse:

$ docker build --rm=false .

Multi

You can specify options like-a=[] multiple times in a single command line,for example in these commands:

$ 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:

$ docker run -v /host:/container example/mysql

Note

Do not use the-t and-a stderr options together due tolimitations in thepty implementation. Allstderr inpty modesimply goes tostdout.

Strings and Integers

Options like--name="" expect a string, and theycan only be specified once. Options like-c=0expect an integer, and they can only be specified once.

Configuration files

By default, the Docker command line stores its configuration files in adirectory called.docker within your$HOME directory.

Docker manages most of the files in the configuration directoryand you shouldn't modify them. However, you can modify theconfig.json file to control certain aspects of how thedockercommand behaves.

You can modify thedocker command behavior using environmentvariables or command-line options. You can also use options withinconfig.json to modify some of the same behavior. If an environment variableand the--config flag are set, the flag takes precedent over the environmentvariable. Command line options override environment variables and environmentvariables override properties you specify in aconfig.json file.

Change the.docker directory

To specify a different directory, use theDOCKER_CONFIGenvironment variable or the--config command line option. If both arespecified, then the--config option overrides theDOCKER_CONFIG environmentvariable. The example below overrides thedocker ps command using aconfig.json file located in the~/testconfigs/ directory.

$ docker --config ~/testconfigs/ ps

This flag only applies to whatever command is being ran. For persistentconfiguration, you can set theDOCKER_CONFIG environment variable in yourshell (e.g.~/.profile or~/.bashrc). The example below sets the newdirectory to beHOME/newdir/.docker.

$echoexportDOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile

Docker CLI configuration file (config.json) properties

Use the Docker CLI configuration to customize settings for thedocker CLI. Theconfiguration file uses JSON formatting, and properties:

By default, configuration file is stored in~/.docker/config.json. Refer to thechange the.docker directory section to use adifferent location.

Warning

The configuration file and other files inside the~/.docker configurationdirectory may contain sensitive information, such as authentication informationfor proxies or, depending on your credential store, credentials for your imageregistries. 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

These fields lets you customize the default output format for some commandsif no--format flag is provided.

Custom HTTP headers

The propertyHttpHeaders specifies a set of headers to include in all messagessent from the Docker client to the daemon. Docker doesn't try to interpret orunderstand these headers; it simply puts them into the messages. Docker doesnot allow these headers to change any headers it sets for itself.

Alternatively, use theDOCKER_CUSTOM_HEADERSenvironment variable,which is available in v27.1 and higher. This environment-variable is experimental,and its exact behavior may change.

Credential store options

The propertycredsStore specifies an external binary to serve as the defaultcredential store. When this property is set,docker login will attempt tostore credentials in the binary specified bydocker-credential-<value> whichis visible on$PATH. If this property isn't set, credentials are storedin theauths property of the CLI configuration file. For more information,see theCredential stores section in thedocker login documentation

The propertycredHelpers specifies a set of credential helpers to usepreferentially overcredsStore orauths when storing and retrievingcredentials for specific registries. If this property is set, the binarydocker-credential-<value> will be used when storing or retrieving credentialsfor a specific registry. For more information, see theCredential helpers section in thedocker login documentation

Automatic proxy configuration for containers

The propertyproxies specifies proxy environment variables to be automaticallyset on containers, and set as--build-arg on containers used duringdocker build.A"default" set of proxies can be configured, and will be used for any Dockerdaemon that the client connects to, or a configuration per host (Docker daemon),for example,https://docker-daemon1.example.com. The following properties canbe set for each environment:

These settings are used to configure proxy settings for containers only, and notused as proxy settings for thedocker CLI or thedockerd daemon. Refer to theenvironment variables andHTTP/HTTPS proxysections for configuring proxy settings for the CLI and daemon.

Warning

Proxy settings may contain sensitive information (for example, if the proxyrequires authentication). Environment variables are stored as plain text inthe container's configuration, and as such can be inspected through the remoteAPI or committed to an image when usingdocker commit.

Default key-sequence to detach from containers

Once attached to a container, users detach from it and leave it running usingthe usingCTRL-p CTRL-q key sequence. This detach key sequence is customizableusing thedetachKeys property. Specify a<sequence> value for theproperty. The format of the<sequence> is a comma-separated list of eithera letter [a-Z], or thectrl- combined with any of the following:

• a-z (a single lowercase alpha character )
• @ (at sign)
• [ (left bracket)
• \\ (two backward slashes)
• _ (underscore)
• ^ (caret)

Your customization applies to all containers started in with your Docker client.Users can override your custom or the default key sequence on a per-containerbasis. To do this, the user specifies the--detach-keys flag with thedocker attach,docker exec,docker run ordocker start command.

CLI plugin options

The propertyplugins contains settings specific to CLI plugins. Thekey is the plugin name, while the value is a further map of options,which are specific to that plugin.

Sample configuration file

Following is a sampleconfig.json file to illustrate the format used forvarious fields:

{"HttpHeaders":{"MyHeader":"MyValue"},"psFormat":"table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}","imagesFormat":"table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}","pluginsFormat":"table {{.ID}}\t{{.Name}}\t{{.Enabled}}","statsFormat":"table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}","servicesFormat":"table {{.ID}}\t{{.Name}}\t{{.Mode}}","secretFormat":"table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}","configFormat":"table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}","serviceInspectFormat":"pretty","nodesFormat":"table {{.ID}}\t{{.Hostname}}\t{{.Availability}}","detachKeys":"ctrl-e,e","credsStore":"secretservice","credHelpers":{"awesomereg.example.org":"hip-star","unicorn.example.com":"vcbait"},"plugins":{"plugin1":{"option":"value"},"plugin2":{"anotheroption":"anothervalue","athirdoption":"athirdvalue"}},"proxies":{"default":{"httpProxy":"http://user:pass@example.com:3128","httpsProxy":"https://my-proxy.example.com:3129","noProxy":"intra.mycorp.example.com","ftpProxy":"http://user:pass@example.com:3128","allProxy":"socks://example.com:1234"},"https://manager1.mycorp.example.com:2377":{"httpProxy":"http://user:pass@example.com:3128","httpsProxy":"https://my-proxy.example.com:3129"}}}

Experimental features

Experimental features provide early access to future product functionality.These features are intended for testing and feedback, and they may changebetween 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

If using your own notary server and a self-signed certificate or an internalCertificate Authority, you need to place the certificate attls/<registry_url>/ca.crt in your Docker config directory.

Alternatively you can trust the certificate globally by adding it to your system'slist of root Certificate Authorities.

Options

Examples

Specify daemon host (-H, --host)

You can use the-H,--host flag to specify a socket to use when you invokeadocker command. You can use the following protocols:

If you don't specify the-H flag, and you're not using a customcontext,commands use the following default sockets:

• unix:///var/run/docker.sock on macOS and Linux
• npipe:////./pipe/docker_engine on Windows

To achieve a similar effect without having to specify the-H flag for everycommand, you could alsocreate a context,or alternatively, use theDOCKER_HOST environment variable.

For more information about the-H flag, seeDaemon socket option.

Using TCP sockets

The following example shows how to invokedocker ps over TCP, to a remotedaemon with IP address174.17.0.1, listening on port2376:

$ docker -H tcp://174.17.0.1:2376 ps

Note

By convention, the Docker daemon uses port2376 for secure TLS connections,and port2375 for insecure, non-TLS connections.

Using SSH sockets

When you use SSH invoke a command on a remote daemon, the request gets forwardedto the/var/run/docker.sock Unix socket on the SSH host.

$ docker -H ssh://user@192.168.64.5 ps

You can optionally specify the location of the socket by appending a pathcomponent to the end of the SSH address.

$ docker -H ssh://user@192.168.64.5/var/run/docker.sock ps

Subcommands