Skip to content

Commit

Permalink
Permit '=' separator and '[ipv6]' in --add-host
Browse files Browse the repository at this point in the history 
Fixes docker#4648

Make it easier to specify IPv6 addresses in the '--add-host' option by
permitting 'host=ip' in addition to 'host:ip', and allowing square
brackets around the address.

For example:

    --add-host=my-hostname:127.0.0.1
    --add-host=my-hostname:::1
    --add-host=my-hostname=::1
    --add-host=my-hostname:[::1]

To avoid compatibility problems, the CLI will replace an '=' separator
with ':', and strip brackets, before sending the request to the API.

Signed-off-by: Rob Murray <[email protected]>
  • Loading branch information
@robmry
robmry committed Nov 23, 2023
1 parent ce22ac2 commit 3068630
Show file tree
Hide file tree
Showing 13 changed files with 235 additions and 61 deletions.
2 changes: 1 addition & 1 deletion cli/command/container/opts.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
flags.SetAnnotation("cgroupns", "version", []string{"1.41"})

// Network and port publishing flag
flags.Var(&copts.extraHosts, "add-host", "Add a custom host-to-IP mapping (host:ip)")
flags.Var(&copts.extraHosts, "add-host", "Add a custom host-to-IP mapping (host=ip)")
flags.Var(&copts.dns, "dns", "Set custom DNS servers")
// We allow for both "--dns-opt" and "--dns-option", although the latter is the recommended way.
// This is to be consistent with service create/update
Expand Down
2 changes: 1 addition & 1 deletion cli/command/image/build.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
flags.StringSliceVar(&options.securityOpt, "security-opt", []string{}, "Security options")
flags.StringVar(&options.networkMode, "network", "default", "Set the networking mode for the RUN instructions during build")
flags.SetAnnotation("network", "version", []string{"1.25"})
flags.Var(&options.extraHosts, "add-host", `Add a custom host-to-IP mapping ("host:ip")`)
flags.Var(&options.extraHosts, "add-host", `Add a custom host-to-IP mapping ("host=ip")`)
flags.StringVar(&options.target, "target", "", "Set the target build stage to build.")
flags.StringVar(&options.imageIDFile, "iidfile", "", "Write the image ID to the file")

Expand Down
20 changes: 14 additions & 6 deletions docs/reference/commandline/build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Build an image from a Dockerfile

| Name | Type | Default | Description |
|:------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host=ip`) |
| [`--build-arg`](#build-arg) | `list` | | Set build-time variables |
| [`--cache-from`](#cache-from) | `stringSlice` | | Images to consider as cache sources |
| [`--cgroup-parent`](#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
Expand Down Expand Up @@ -454,20 +454,28 @@ Specifying the `--isolation` flag without a value is the same as setting `--isol

### <a name="add-host"></a> Add entries to container hosts file (--add-host)

You can add other hosts into a container's `/etc/hosts` file by using one or
more `--add-host` flags. This example adds a static address for a host named
`docker`:
You can add other hosts into a build container's `/etc/hosts` file by using one
or more `--add-host` flags. This example adds static addresses for hosts named
`my-hostname` and `my_hostname_v6`:

```console
$ docker build --add-host docker:10.180.0.1 .
$ docker build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .
```

If you need your build to connect to services running on the host, you can use
the special `host-gateway` value for `--add-host`. In the following example,
build containers resolve `host.docker.internal` to the host's gateway IP.

```console
$ docker build --add-host host.docker.internal:host-gateway .
$ docker build --add-host host.docker.internal=host-gateway .
```

You can wrap an IPv6 address in square brackets.
`=` and `:` are both valid separators.
Both formats in the following example are valid:

```console
$ docker build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .
```

### <a name="target"></a> Specifying target build stage (--target)
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/builder_build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Build an image from a Dockerfile

| Name | Type | Default | Description |
|:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host=ip`) |
| `--build-arg` | `list` | | Set build-time variables |
| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build |
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/container_create.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Create a new container

| Name | Type | Default | Description |
|:--------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--add-host` | `list` | | Add a custom host-to-IP mapping (host:ip) |
| `--add-host` | `list` | | Add a custom host-to-IP mapping (host=ip) |
| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) |
| `-a`, `--attach` | `list` | | Attach to STDIN, STDOUT or STDERR |
| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/container_run.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Create and run a new container from an image

| Name | Type | Default | Description |
|:--------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--add-host` | `list` | | Add a custom host-to-IP mapping (host:ip) |
| `--add-host` | `list` | | Add a custom host-to-IP mapping (host=ip) |
| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) |
| `-a`, `--attach` | `list` | | Attach to STDIN, STDOUT or STDERR |
| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/create.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Create a new container

| Name | Type | Default | Description |
|:--------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--add-host` | `list` | | Add a custom host-to-IP mapping (host:ip) |
| `--add-host` | `list` | | Add a custom host-to-IP mapping (host=ip) |
| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) |
| `-a`, `--attach` | `list` | | Attach to STDIN, STDOUT or STDERR |
| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/image_build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Build an image from a Dockerfile

| Name | Type | Default | Description |
|:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host=ip`) |
| `--build-arg` | `list` | | Set build-time variables |
| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build |
Expand Down
32 changes: 22 additions & 10 deletions docs/reference/commandline/run.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Create and run a new container from an image

| Name | Type | Default | Description |
|:----------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host:ip) |
| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host=ip) |
| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) |
| [`-a`](#attach), [`--attach`](#attach) | `list` | | Attach to STDIN, STDOUT or STDERR |
| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
Expand Down Expand Up @@ -746,22 +746,28 @@ section of the Docker run reference page.

You can add other hosts into a container's `/etc/hosts` file by using one or
more `--add-host` flags. This example adds a static address for a host named
`docker`:
`my-hostname`:

```console
$ docker run --add-host=docker:93.184.216.34 --rm -it alpine
$ docker run --add-host=my-hostname=8.8.8.8 --rm -it alpine

/ # ping docker
PING docker (93.184.216.34): 56 data bytes
64 bytes from 93.184.216.34: seq=0 ttl=37 time=93.052 ms
64 bytes from 93.184.216.34: seq=1 ttl=37 time=92.467 ms
64 bytes from 93.184.216.34: seq=2 ttl=37 time=92.252 ms
/ # ping my-hostname
PING my-hostname (8.8.8.8): 56 data bytes
64 bytes from 8.8.8.8: seq=0 ttl=37 time=93.052 ms
64 bytes from 8.8.8.8: seq=1 ttl=37 time=92.467 ms
64 bytes from 8.8.8.8: seq=2 ttl=37 time=92.252 ms
^C
--- docker ping statistics ---
--- my-hostname ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max = 92.209/92.495/93.052 ms
```

You can wrap an IPv6 address in square brackets:

```console
$ docker run --add-host my-hostname=[2001:db8::33] --rm -it alpine
```

The `--add-host` flag supports a special `host-gateway` value that resolves to
the internal IP address of the host. This is useful when you want containers to
connect to services running on the host machine.
Expand All @@ -779,11 +785,17 @@ $ echo "hello from host!" > ./hello
$ python3 -m http.server 8000
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
$ docker run \
--add-host host.docker.internal:host-gateway \
--add-host host.docker.internal=host-gateway \
curlimages/curl -s host.docker.internal:8000/hello
hello from host!
```

The `--add-host` flag also accepts a `:` separator, for example:

```console
$ docker run --add-host=my-hostname:8.8.8.8 --rm -it alpine
```

### <a name="ulimit"></a> Set ulimits in container (--ulimit)

Since setting `ulimit` settings in a container requires extra privileges not
Expand Down
6 changes: 3 additions & 3 deletions man/docker-build.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,10 +78,10 @@ set as the **URL**, the repository is cloned locally and then sent as the contex
layers in tact, and one for the squashed version.

**--add-host** []
Add a custom host-to-IP mapping (host:ip)
Add a custom host-to-IP mapping (host=ip, or host:ip)

Add a line to /etc/hosts. The format is hostname:ip. The **--add-host**
option can be set multiple times.
Add a line to /etc/hosts. The format is hostname=ip, or hostname:ip.
The **--add-host** option can be set multiple times.

**--build-arg** *variable*
name and value of a **buildarg**.
Expand Down
6 changes: 3 additions & 3 deletions man/docker-run.1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,10 +121,10 @@ executables expect) and pass along signals. The **-a** option can be set for
each of stdin, stdout, and stderr.

**--add-host**=[]
Add a custom host-to-IP mapping (host:ip)
Add a custom host-to-IP mapping (host=ip, or host:ip)

Add a line to /etc/hosts. The format is hostname:ip. The **--add-host**
option can be set multiple times.
Add a line to /etc/hosts. The format is hostname=ip, or hostname:ip.
The **--add-host** option can be set multiple times.

**--annotation**=[]
Add an annotation to the container (passed through to the OCI runtime).
Expand Down
Loading

0 comments on commit 3068630

Please sign in to comment.