Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4260 from dvdksn/docs/host-flag 

docs: add description and examples for docker -H
This commit is contained in:
Sebastiaan van Stijn 2023-05-08 14:06:35 +02:00 committed by GitHub
parent 8a8b600eed 759fa585cf
commit 03752a6ba6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 63 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
cli/flags/options.go
View File

@ -83,7 +83,7 @@ func (o *ClientOptions) InstallFlags(flags *pflag.FlagSet) {
// opts.ValidateHost is not used here, so as to allow connection helpers // opts.ValidateHost is not used here, so as to allow connection helpers
hostOpt := opts.NewNamedListOptsRef("hosts", &o.Hosts, nil) hostOpt := opts.NewNamedListOptsRef("hosts", &o.Hosts, nil)
flags.VarP(hostOpt, "host", "H", "Daemon socket(s) to connect to") flags.VarP(hostOpt, "host", "H", "Daemon socket to connect to")
flags.StringVarP(&o.Context, "context", "c", "", flags.StringVarP(&o.Context, "context", "c", "",
`Name of the context to use to connect to the daemon (overrides `+client.EnvOverrideHost+` env var and default context set with "docker context use")`) `Name of the context to use to connect to the daemon (overrides `+client.EnvOverrideHost+` env var and default context set with "docker context use")`)
} }

74
docs/reference/commandline/cli.md
View File

@ -92,18 +92,18 @@ The base command for the Docker CLI.
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:--------------------|:---------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| |:---------------------------------|:---------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|
| `--config` | `string` | `/root/.docker` | Location of client config files | | `--config` | `string` | `/root/.docker` | Location of client config files |
| `-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`) | | `-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`) |
| `-D`, `--debug` | | | Enable debug mode | | `-D`, `--debug` | | | Enable debug mode |
| `-H`, `--host` | `list` | | Daemon socket(s) to connect to | | [`-H`](#host), [`--host`](#host) | `list` | | Daemon socket to connect to |
| `-l`, `--log-level` | `string` | `info` | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) | | `-l`, `--log-level` | `string` | `info` | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) |
| `--tls` | | | Use TLS; implied by --tlsverify | | `--tls` | | | Use TLS; implied by --tlsverify |
| `--tlscacert` | `string` | `/root/.docker/ca.pem` | Trust certs signed only by this CA | | `--tlscacert` | `string` | `/root/.docker/ca.pem` | Trust certs signed only by this CA |
| `--tlscert` | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file | | `--tlscert` | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file |
| `--tlskey` | `string` | `/root/.docker/key.pem` | Path to TLS key file | | `--tlskey` | `string` | `/root/.docker/key.pem` | Path to TLS key file |
| `--tlsverify` | | | Use TLS and verify the remote | | `--tlsverify` | | | Use TLS and verify the remote |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
@ -378,6 +378,56 @@ list of root Certificate Authorities.
## Examples ## Examples
### <a name="host"></a> Specify daemon host (-H, --host)
You can use the `-H`, `--host` flag to specify a socket to use when you invoke
a `docker` command. You can use the following protocols:
| Scheme | Description | Example |
|----------------------------------------|---------------------------|----------------------------------|
| `unix://[<path>]` | Unix socket (Linux only) | `unix:///var/run/docker.sock` |
| `tcp://[<IP or host>[:port]]` | TCP connection | `tcp://174.17.0.1:2376` |
| `ssh://[username@]<IP or host>[:port]` | SSH connection | `ssh://user@192.168.64.5` |
| `npipe://[<name>]` | Named pipe (Windows only) | `npipe:////./pipe/docker_engine` |
If you don't specify the `-H` flag, and you're not using a custom
[context](https://docs.docker.com/engine/context/working-with-contexts),
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 every
command, you could also [create a context](context_create.md),
or alternatively, use the
[`DOCKER_HOST` environment variable](#environment-variables).
For more information about the `-H` flag, see
[Daemon socket option](dockerd.md#daemon-socket-option).
#### Using TCP sockets
The following example shows how to invoke `docker ps` over TCP, to a remote
daemon with IP address `174.17.0.1`, listening on port `2376`:
```console
$ docker -H tcp://174.17.0.1:2376 ps
```
> **Note**
>
> By convention, the Docker daemon uses port `2376` for secure TLS connections,
> and port `2375` for insecure, non-TLS connections.
#### Using SSH sockets
When you use SSH invoke a command on a remote daemon, the request gets forwarded
to the `/var/run/docker.sock` Unix socket on the SSH host.
```console
$ docker -H ssh://user@192.168.64.5 ps
```
### Display help text ### Display help text
To list the help on any command just execute the command, followed by the To list the help on any command just execute the command, followed by the