Skip to content

Commit 8e3bb66

Browse files
aevesdockerusha-mandya
aevesdocker
and
usha-mandya
authored
Desktop: Networking how-tos (#23708)
<!--Delete sections as needed --> ## Description Follow up to #23626. Pivots the current content to more how-to type content (no new content added), removes repetitions, add more cross-links ## Related issues or tickets <!-- Related issues, pull requests, or Jira tickets --> ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Co-authored-by: Usha Mandya <[email protected]>
1 parent 2648063 commit 8e3bb66

File tree

4 files changed

+79
-201
lines changed

4 files changed

+79
-201
lines changed

‎content/manuals/desktop/features/networking/networking-how-tos.md‎

Lines changed: 73 additions & 197 deletions
Original file line numberDiff line numberDiff line change
@@ -14,62 +14,97 @@ aliases:
1414
- /desktop/networking/
1515
---
1616

17-
Docker Desktop includes built-in networking capabilities to help you connect containers with services on your host, across containers, or through proxies and VPNs.
17+
This page explains how to configure and use networking features, connect containers to host services, work behind proxies or VPNs, and troubleshoot common issues.
1818

19-
## Networking features for all platforms
19+
For details on how Docker Desktop routes network traffic and file I/O between containers, the VM, and the host, see [Network overview](/manuals/desktop/features/networking/index.md#overview).
2020

21-
### VPN Passthrough
21+
## Core networking how-tos
22+
23+
### Connect a container to a service on the host
24+
25+
The host has a changing IP address, or none if you have no network access. To connect to services running on your host, use the special DNS name:
26+
27+
| Name | Description |
28+
| ------------------------- | ------------------------------------------------ |
29+
| `host.docker.internal` | Resolves to the internal IP address of your host |
30+
| `gateway.docker.internal` | Resolves to the gateway IP of the Docker VM |
2231

23-
Docker Desktop networking can work when attached to a VPN. To do this,
24-
Docker Desktop intercepts traffic from the containers and injects it into
25-
the host as if it originated from the Docker application.
2632

27-
### Port mapping
33+
#### Example
2834

29-
When you run a container with the `-p` argument, for example:
35+
Run a simple HTTP server on port `8000`:
3036

3137
```console
32-
$ docker run -p 80:80 -d nginx
38+
$ python -m http.server 8000
3339
```
3440

35-
Docker Desktop makes whatever is running on port `80` in the container, in
36-
this case, `nginx`, available on port `80` of `localhost`. In this example, the
37-
host and container ports are the same.
41+
Then run a container, install `curl`, and try to connect to the host using the following commands:
3842

39-
To avoid conflicts with services already using port `80` on the host:
43+
```console
44+
$ docker run --rm -it alpine sh
45+
# apk add curl
46+
# curl http://host.docker.internal:8000
47+
# exit
48+
```
49+
50+
### Connect to a container from the host
51+
52+
To access containerized services from your host or local network, publish ports with the `-p` or `--publish` flag. For example:
4053

4154
```console
42-
$ docker run -p 8000:80 -d nginx
55+
$ docker run -d -p 80:80 --name webserver nginx
4356
```
4457

45-
Now connections to `localhost:8000` are sent to port `80` in the container.
58+
Docker Desktop makes whatever is running on port `80` in the container, in
59+
this case, `nginx`, available on port `80` of `localhost`.
4660

4761
> [!TIP]
4862
>
4963
> The syntax for `-p` is `HOST_PORT:CLIENT_PORT`.
5064
51-
### HTTP/HTTPS Proxy support
65+
To publish all ports, use the `-P` flag. For example, the following command
66+
starts a container (in detached mode) and the `-P` flag publishes all exposed ports of the
67+
container to random ports on the host.
68+
69+
```console
70+
$ docker run -d -P --name webserver nginx
71+
```
72+
73+
Alternatively, you can also use [host networking](/manuals/engine/network/drivers/host.md#docker-desktop)
74+
to give the container direct access to the network stack of the host.
75+
76+
See the [run command](/reference/cli/docker/container/run.md) for more details on
77+
publish options used with `docker run`.
78+
79+
All inbound connections pass through the Docker Desktop backend process (`com.docker.backend` (Mac), `com.docker.backend` (Windows), or `qemu` (Linux), which handles port forwarding into the VM.
80+
For more details, see [How exposed ports work](/manuals/desktop/features/networking/index.md#how-exposed-ports-work)
5281

53-
See [Proxies](/manuals/desktop/settings-and-maintenance/settings.md#proxies)
82+
### Working with VPNs
5483

55-
### SOCKS5 proxy support
84+
Docker Desktop networking can work when attached to a VPN.
5685

57-
{{< summary-bar feature_name="SOCKS5 proxy support" >}}
86+
To do this, Docker Desktop intercepts traffic from the containers and injects it into
87+
the host as if it originated from the Docker application.
5888

59-
SOCKS (Socket Secure) is a protocol that facilitates the routing of network packets between a client and a server through a proxy server. It provides a way to enhance privacy, security, and network performance for users and applications.
89+
For details about how this traffic appears to host firewalls and endpoint detection systems, see [Firewalls and endpoint visibility](/manuals/desktop/features/networking/index.md#firewalls-and-endpoint-visibility.md).
6090

61-
You can enable SOCKS proxy support to allow outgoing requests, such as pulling images, and access Linux container backend IPs from the host.
91+
### Working with proxies
6292

63-
To enable and set up SOCKS proxy support:
93+
Docker Desktop can use your system proxy or a manual configuration.
94+
To configure proxies:
6495

6596
1. Navigate to the **Resources** tab in **Settings**.
6697
2. From the dropdown menu select **Proxies**.
67-
3. Switch on the **Manual proxy configuration** toggle.
68-
4. In the **Secure Web Server HTTPS** box, paste your `socks5://host:port` URL.
98+
3. Switch on the **Manual proxy configuration** toggle.
99+
4. Enter your HTTP, HTTPS or SOCKS5 proxy URLS.
69100

70-
## Networking mode and DNS behaviour for Mac and Windows
101+
For more details on proxies and proxy configurations, see the [Proxy settings documentation](/manuals/desktop/settings-and-maintenance/settings.md#proxies).
71102

72-
With Docker Desktop version 4.42 and later, you can customize how Docker handles container networking and DNS resolution to better support a range of environments — from IPv4-only to dual-stack and IPv6-only systems. These settings help prevent timeouts and connectivity issues caused by incompatible or misconfigured host networks.
103+
## Network how-tos for Mac and Windows
104+
105+
With Docker Desktop version 4.42 and later, you can control how Docker handles container networking and DNS resolution to better support a range of environments — from IPv4-only to dual-stack and IPv6-only systems. These settings help prevent timeouts and connectivity issues caused by incompatible or misconfigured host networks.
106+
107+
You can set the following settings on the **Network** tab in the Docker Desktop Dashboard settings, or if you're an admin, with Settings Management via the [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#networking), or the [Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md)
73108

74109
> [!NOTE]
75110
>
@@ -79,123 +114,28 @@ With Docker Desktop version 4.42 and later, you can customize how Docker handles
79114

80115
Choose the default IP protocol used when Docker creates new networks. This allows you to align Docker with your host’s network capabilities or organizational requirements, such as enforcing IPv6-only access.
81116

82-
The options available are:
83-
84-
- **Dual IPv4/IPv6** (Default): Supports both IPv4 and IPv6. Most flexible and ideal for environments with dual-stack networking.
85-
- **IPv4 only**: Only IPv4 addresses are used. Use this if your host or network does not support IPv6.
86-
- **IPv6 only**: Only IPv6 addresses are used. Best for environments transitioning to or enforcing IPv6-only connectivity.
87-
88-
> [!NOTE]
89-
>
90-
> This setting can be overridden on a per-network basis using CLI flags or Compose file options.
117+
| Mode | Description |
118+
| ---------------------------- | ------------------------------------------- |
119+
| **Dual IPv4/IPv6 (default)** | Supports both IPv4 and IPv6. Most flexible. |
120+
| **IPv4 only** | Uses only IPv4 addressing. |
121+
| **IPv6 only** | Uses only IPv6 addressing. |
91122

92123
### DNS resolution behavior
93124

94125
Control how Docker filters DNS records returned to containers, improving reliability in environments where only IPv4 or IPv6 is supported. This setting is especially useful for preventing apps from trying to connect using IP families that aren't actually available, which can cause avoidable delays or failures.
95126

96-
Depending on your selected network mode, the options available are:
97-
98-
- **Auto (recommended)**: Docker detects your host's network stack and automatically filters out unsupported DNS record types (A for IPv4, AAAA for IPv6).
99-
- **Filter IPv4 (A records)**: Prevents containers from resolving IPv4 addresses. Only available in dual-stack mode.
100-
- **Filter IPv6 (AAAA records)**: Prevents containers from resolving IPv6 addresses. Only available in dual-stack mode.
101-
- **No filtering**: Docker returns all DNS records (A and AAAA), regardless of host support.
127+
| Option | Description |
128+
| ------------------------------ | --------------------------------------------------------------------------- |
129+
| **Auto (recommended)** | Automatically filters unsupported record types. (A for IPv4, AAAA for IPv6) |
130+
| **Filter IPv4 (A records)** | Blocks IPv4 lookups. Only available in dual-stack mode. |
131+
| **Filter IPv6 (AAAA records)** | Blocks IPv6 lookups. Only available in dual-stack mode. |
132+
| **No filtering** | Returns both A and AAAA records. |
102133

103134
> [!IMPORTANT]
104135
>
105136
> Switching the default networking mode resets the DNS filter to Auto.
106137
107-
### Using Settings Management
108-
109-
If you're an administrator, you can use [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#networking) to enforce this Docker Desktop setting across your developer's machines. Choose from the following code snippets and at it to your `admin-settings.json` file,
110-
or configure this setting using the [Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md)
111-
112-
{{< tabs >}}
113-
{{< tab name="Networking mode" >}}
114-
115-
Dual IPv4/IPv6:
116-
117-
```json
118-
{
119-
"defaultNetworkingMode": {
120-
"locked": true
121-
"value": "dual-stack"
122-
}
123-
}
124-
```
125-
126-
IPv4 only:
127-
128-
```json
129-
{
130-
"defaultNetworkingMode": {
131-
"locked": true
132-
"value": "ipv4only"
133-
}
134-
}
135-
```
136-
137-
IPv6 only:
138-
139-
```json
140-
{
141-
"defaultNetworkingMode": {
142-
"locked": true
143-
"value": "ipv6only"
144-
}
145-
}
146-
```
147-
148-
{{< /tab >}}
149-
{{< tab name="DNS resolution" >}}
150-
151-
Auto filter:
152-
153-
```json
154-
{
155-
"dnsInhibition": {
156-
"locked": true
157-
"value": "auto"
158-
}
159-
}
160-
```
161-
162-
Filter IPv4:
163-
164-
```json
165-
{
166-
"dnsInhibition": {
167-
"locked": true
168-
"value": "ipv4"
169-
}
170-
}
171-
```
172-
173-
Filter IPv6:
174-
175-
```json
176-
{
177-
"dnsInhibition": {
178-
"locked": true
179-
"value": "ipv6"
180-
}
181-
}
182-
```
183-
184-
No filter:
185-
186-
```json
187-
{
188-
"dnsInhibition": {
189-
"locked": true
190-
"value": "none"
191-
}
192-
}
193-
```
194-
195-
{{< /tab >}}
196-
{{< /tabs >}}
197-
198-
## Networking features for Mac and Linux
138+
## Network how-tos for Mac and Linux
199139

200140
### SSH agent forwarding
201141

@@ -248,67 +188,3 @@ ping the Windows containers.
248188

249189
This is because the Docker `bridge` network is not reachable from the host.
250190
However if you are a Windows user, per-container IP addressing is possible with Windows containers.
251-
252-
## Use cases and workarounds
253-
254-
### I want to connect from a container to a service on the host
255-
256-
The host has a changing IP address, or none if you have no network access.
257-
Docker recommends you connect to the special DNS name `host.docker.internal`,
258-
which resolves to the internal IP address used by the host.
259-
260-
You can also reach the gateway using `gateway.docker.internal`.
261-
262-
If you have installed Python on your machine, use the following instructions as an example to connect from a container to a service on the host:
263-
264-
1. Run the following command to start a simple HTTP server on port 8000.
265-
266-
`python -m http.server 8000`
267-
268-
If you have installed Python 2.x, run `python -m SimpleHTTPServer 8000`.
269-
270-
2. Now, run a container, install `curl`, and try to connect to the host using the following commands:
271-
272-
```console
273-
$ docker run --rm -it alpine sh
274-
# apk add curl
275-
# curl http://host.docker.internal:8000
276-
# exit
277-
```
278-
279-
### I want to connect to a container from the host
280-
281-
Port forwarding works for `localhost`. `--publish`, `-p`, or `-P` all work.
282-
Ports exposed from Linux are forwarded to the host.
283-
284-
Docker recommends you publish a port, or to connect from another
285-
container. This is what you need to do even on Linux if the container is on an
286-
overlay network, not a bridge network, as these are not routed.
287-
288-
For example, to run an `nginx` webserver:
289-
290-
```console
291-
$ docker run -d -p 80:80 --name webserver nginx
292-
```
293-
294-
To clarify the syntax, the following two commands both publish container's port `80` to host's port `8000`:
295-
296-
```console
297-
$ docker run --publish 8000:80 --name webserver nginx
298-
299-
$ docker run -p 8000:80 --name webserver nginx
300-
```
301-
302-
To publish all ports, use the `-P` flag. For example, the following command
303-
starts a container (in detached mode) and the `-P` flag publishes all exposed ports of the
304-
container to random ports on the host.
305-
306-
```console
307-
$ docker run -d -P --name webserver nginx
308-
```
309-
310-
Alternatively, you can also use [host networking](/manuals/engine/network/drivers/host.md#docker-desktop)
311-
to give the container direct access to the network stack of the host.
312-
313-
See the [run command](/reference/cli/docker/container/run.md) for more details on
314-
publish options used with `docker run`.

‎content/manuals/desktop/settings-and-maintenance/settings.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -235,16 +235,18 @@ containers. Alternatively, you can opt not to share it by selecting **Cancel**.
235235

236236
### Proxies
237237

238-
Docker Desktop supports the use of HTTP/HTTPS and [SOCKS5 proxies](/manuals/desktop/features/networking.md#socks5-proxy-support).
238+
Docker Desktop supports the use of HTTP/HTTPS and SOCKS5 proxies (Requires a business subscription).
239239

240-
HTTP/HTTPS proxies can be used when:
240+
HTTP/HTTPS and SOCKS5 proxies can be used when:
241241

242242
- Signing in to Docker
243243
- Pulling or pushing images
244244
- Fetching artifacts during image builds
245245
- Containers interact with the external network
246246
- Scanning images
247247

248+
For more details on how it works, see [Using Docker Desktop with a proxy](/manuals/desktop/features/networking/index.md#useing-docker-desktop-with-a-proxy).
249+
248250
If the host uses a HTTP/HTTPS proxy configuration (static or via Proxy Auto-Configuration (PAC)), Docker Desktop reads
249251
this configuration
250252
and automatically uses these settings for signing in to Docker, for pulling and pushing images, and for

‎content/manuals/desktop/troubleshoot-and-support/faqs/general.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ The host has a changing IP address, or none if you have no network access.
6060
It is recommend that you connect to the special DNS name `host.docker.internal`,
6161
which resolves to the internal IP address used by the host.
6262

63-
For more information and examples, see [how to connect from a container to a service on the host](/manuals/desktop/features/networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host).
63+
For more information and examples, see [how to connect from a container to a service on the host](/manuals/desktop/features/networking.md#connect-a-container-to-a-service-on-the-host).
6464

6565
### Can I pass through a USB device to a container?
6666

‎data/engine-cli/docker_container_run.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2262,7 +2262,7 @@ examples: |-
22622262
22632263
It's conventional to use `host.docker.internal` as the hostname referring to
22642264
`host-gateway`. Docker Desktop automatically resolves this hostname, see
2265-
[Explore networking features](/desktop/features/networking/networking-how-tos/#i-want-to-connect-from-a-container-to-a-service-on-the-host).
2265+
[Explore networking features](/desktop/features/networking/networking-how-tos/#connect-a-container-to-a-service-on-the-host).
22662266
22672267
The following example shows how the special `host-gateway` value works. The
22682268
example runs an HTTP server that serves a file from host to container over the

0 commit comments

Comments
 (0)