Skip to content

Commit 03752a6

Browse files
thaJeztahthaJeztah
authored
Merge pull request #4260 from dvdksn/docs/host-flag
docs: add description and examples for docker -H
2 parents 8a8b600 + 759fa58 commit 03752a6

2 files changed

Lines changed: 63 additions & 13 deletions

File tree

‎cli/flags/options.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ func (o *ClientOptions) InstallFlags(flags *pflag.FlagSet) {
8383

8484
// opts.ValidateHost is not used here, so as to allow connection helpers
8585
hostOpt := opts.NewNamedListOptsRef("hosts", &o.Hosts, nil)
86-
flags.VarP(hostOpt, "host", "H", "Daemon socket(s) to connect to")
86+
flags.VarP(hostOpt, "host", "H", "Daemon socket to connect to")
8787
flags.StringVarP(&o.Context, "context", "c", "",
8888
`Name of the context to use to connect to the daemon (overrides `+client.EnvOverrideHost+` env var and default context set with "docker context use")`)
8989
}

‎docs/reference/commandline/cli.md‎

Lines changed: 62 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -92,18 +92,18 @@ The base command for the Docker CLI.
9292

9393
### Options
9494

95-
| Name | Type | Default | Description |
96-
|:--------------------|:---------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|
97-
| `--config` | `string` | `/root/.docker` | Location of client config files |
98-
| `-c`, `--context` | `string` | | Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with `docker context use`) |
99-
| `-D`, `--debug` | | | Enable debug mode |
100-
| `-H`, `--host` | `list` | | Daemon socket(s) to connect to |
101-
| `-l`, `--log-level` | `string` | `info` | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) |
102-
| `--tls` | | | Use TLS; implied by --tlsverify |
103-
| `--tlscacert` | `string` | `/root/.docker/ca.pem` | Trust certs signed only by this CA |
104-
| `--tlscert` | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file |
105-
| `--tlskey` | `string` | `/root/.docker/key.pem` | Path to TLS key file |
106-
| `--tlsverify` | | | Use TLS and verify the remote |
95+
| Name | Type | Default | Description |
96+
|:---------------------------------|:---------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|
97+
| `--config` | `string` | `/root/.docker` | Location of client config files |
98+
| `-c`, `--context` | `string` | | Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with `docker context use`) |
99+
| `-D`, `--debug` | | | Enable debug mode |
100+
| [`-H`](#host), [`--host`](#host) | `list` | | Daemon socket to connect to |
101+
| `-l`, `--log-level` | `string` | `info` | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) |
102+
| `--tls` | | | Use TLS; implied by --tlsverify |
103+
| `--tlscacert` | `string` | `/root/.docker/ca.pem` | Trust certs signed only by this CA |
104+
| `--tlscert` | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file |
105+
| `--tlskey` | `string` | `/root/.docker/key.pem` | Path to TLS key file |
106+
| `--tlsverify` | | | Use TLS and verify the remote |
107107

108108

109109
<!---MARKER_GEN_END-->
@@ -378,6 +378,56 @@ list of root Certificate Authorities.
378378

379379
## Examples
380380

381+
### <a name="host"></a> Specify daemon host (-H, --host)
382+
383+
You can use the `-H`, `--host` flag to specify a socket to use when you invoke
384+
a `docker` command. You can use the following protocols:
385+
386+
| Scheme | Description | Example |
387+
|----------------------------------------|---------------------------|----------------------------------|
388+
| `unix://[<path>]` | Unix socket (Linux only) | `unix:///var/run/docker.sock` |
389+
| `tcp://[<IP or host>[:port]]` | TCP connection | `tcp://174.17.0.1:2376` |
390+
| `ssh://[username@]<IP or host>[:port]` | SSH connection | `ssh://user@192.168.64.5` |
391+
| `npipe://[<name>]` | Named pipe (Windows only) | `npipe:////./pipe/docker_engine` |
392+
393+
If you don't specify the `-H` flag, and you're not using a custom
394+
[context](https://docs.docker.com/engine/context/working-with-contexts),
395+
commands use the following default sockets:
396+
397+
- `unix:///var/run/docker.sock` on macOS and Linux
398+
- `npipe:////./pipe/docker_engine` on Windows
399+
400+
To achieve a similar effect without having to specify the `-H` flag for every
401+
command, you could also [create a context](context_create.md),
402+
or alternatively, use the
403+
[`DOCKER_HOST` environment variable](#environment-variables).
404+
405+
For more information about the `-H` flag, see
406+
[Daemon socket option](dockerd.md#daemon-socket-option).
407+
408+
#### Using TCP sockets
409+
410+
The following example shows how to invoke `docker ps` over TCP, to a remote
411+
daemon with IP address `174.17.0.1`, listening on port `2376`:
412+
413+
```console
414+
$ docker -H tcp://174.17.0.1:2376 ps
415+
```
416+
417+
> **Note**
418+
>
419+
> By convention, the Docker daemon uses port `2376` for secure TLS connections,
420+
> and port `2375` for insecure, non-TLS connections.
421+
422+
#### Using SSH sockets
423+
424+
When you use SSH invoke a command on a remote daemon, the request gets forwarded
425+
to the `/var/run/docker.sock` Unix socket on the SSH host.
426+
427+
```console
428+
$ docker -H ssh://user@192.168.64.5 ps
429+
```
430+
381431
### Display help text
382432

383433
To list the help on any command just execute the command, followed by the

0 commit comments

Comments
 (0)