Skip to content

Commit 1543344

Browse files
aevesdockeraevesdocker
authored
Desktop: new network setting (#22710)
<!--Delete sections as needed --> ## Description New IP setting for DD ## 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
1 parent 347733c commit 1543344

File tree

4 files changed

+168
-0
lines changed

4 files changed

+168
-0
lines changed

‎content/manuals/desktop/features/networking.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,133 @@ To enable and set up SOCKS proxy support:
6868
3. Switch on the **Manual proxy configuration** toggle.
6969
4. In the **Secure Web Server HTTPS** box, paste your `socks5://host:port` URL.
7070

71+
## Networking mode and DNS behaviour for Mac and Windows
72+
73+
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.
74+
75+
> [!NOTE]
76+
>
77+
> These settings can be overridden on a per-network basis using CLI flags or Compose file options.
78+
79+
### Default networking mode
80+
81+
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.
82+
83+
The options available are:
84+
85+
- **Dual IPv4/IPv6** (Default): Supports both IPv4 and IPv6. Most flexible and ideal for environments with dual-stack networking.
86+
- **IPv4 only**: Only IPv4 addresses are used. Use this if your host or network does not support IPv6.
87+
- **IPv6 only**: Only IPv6 addresses are used. Best for environments transitioning to or enforcing IPv6-only connectivity.
88+
89+
> [!NOTE]
90+
>
91+
> This setting can be overridden on a per-network basis using CLI flags or Compose file options.
92+
93+
### DNS resolution behavior
94+
95+
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.
96+
97+
Depending on your selected network mode, the options available are:
98+
99+
- **Auto (recommended)**: Docker detects your host's network stack and automatically filters out unsupported DNS record types (A for IPv4, AAAA for IPv6).
100+
- **Filter IPv4 (A records)**: Prevents containers from resolving IPv4 addresses. Only available in dual-stack mode.
101+
- **Filter IPv6 (AAAA records)**: Prevents containers from resolving IPv6 addresses. Only available in dual-stack mode.
102+
- **No filtering**: Docker returns all DNS records (A and AAAA), regardless of host support.
103+
104+
> [!IMPORTANT]
105+
>
106+
> Switching the default networking mode resets the DNS filter to Auto.
107+
108+
### Using Settings Management
109+
110+
If you're an administrator, you can use [Settings Management](/manuals/security/for-admins/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.
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+
71198
## Networking features for Mac and Linux
72199

73200
### SSH agent forwarding

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,8 @@ To enable Kerberos or NTLM proxy authentication you must pass the `--proxy-enabl
307307
308308
Docker Desktop uses a private IPv4 network for internal services such as a DNS server and an HTTP proxy. In case Docker Desktop's choice of subnet clashes with IPs in your environment, you can specify a custom subnet using the **Network** setting.
309309

310+
On Windows and Mac, you can also set the default networking mode and DNS resolution behavior. For more information, see [Networking](/manuals/desktop/features/networking.md#networking-mode-and-dns-behaviour-for-mac-and-windows).
311+
310312
On Mac, you can also select the **Use kernel networking for UDP** setting. This lets you use a more efficient kernel networking path for UDP. This may not be compatible with your VPN software.
311313

312314
### WSL Integration

‎content/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,15 @@ quit and reopened.
301301
>
302302
> These containers mount the Docker socket, so you must add the images to the ECI images list. If not, ECI will block the mount and Kubernetes won't start.
303303
304+
### Networking
305+
306+
|Parameter|OS|Description|Version|
307+
|:-------------------------------|---|:-------------------------------|---|
308+
| `defaultNetworkingMode` | Windows and Mac only | Defines the default IP protocol for new Docker networks: `dual-stack` (IPv4 + IPv6, default), `ipv4only`, or `ipv6only`. | Docker Desktop version 4.42 and later. |
309+
| `dnsInhibition` | Windows and Mac only | Controls DNS record filtering returned to containers. Options: `auto` (recommended), `ipv4`, `ipv6`, `none`| Docker Desktop version 4.42 and later. |
310+
311+
For more information, see [Networking](/manuals/desktop/features/networking.md#networking-mode-and-dns-behaviour-for-mac-and-windows).
312+
304313
### Features in development
305314

306315
|Parameter|OS|Description|Version|

‎content/manuals/security/for-admins/hardened-desktop/settings-management/settings-reference.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -513,6 +513,36 @@ settings.
513513
- **Configure this setting with:**
514514
- **Network** Resources settings in [Docker Desktop GUI](/manuals/desktop/settings-and-maintenance/settings.md)
515515

516+
### Networking mode
517+
518+
| Default value | Accepted values | Format |
519+
|---------------|-----------------|----------|
520+
| `dual-stack` | `ipv4only`, `ipv6only` | String |
521+
522+
- **Description:** Set the networking mode.
523+
- **OS:** {{< badge color=blue text="Windows and Mac" >}}
524+
- **Use case:** Choose the default IP protocol used when Docker creates new networks.
525+
- **Configure this setting with:**
526+
- **Network** Resources settings in [Docker Desktop GUI](/manuals/desktop/settings-and-maintenance/settings.md)
527+
- Settings Management: `defaultNetworkingMode` setting in the [`admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md)
528+
529+
For more information, see [Networking](/manuals/desktop/features/networking.md#networking-mode-and-dns-behaviour-for-mac-and-windows).
530+
531+
#### Inhibit DNS resolution for IPv4/IPv6
532+
533+
| Default value | Accepted values | Format |
534+
|---------------|-----------------|----------|
535+
| `auto` | `ipv4`, `ipv6`, `none` | String |
536+
537+
- **Description:** Filters unsupported DNS record types.
538+
- **OS:** {{< badge color=blue text="Windows and Mac" >}}
539+
- **Use case:** Control how Docker filters DNS records returned to containers, improving reliability in environments where only IPv4 or IPv6 is supported.
540+
- **Configure this setting with:**
541+
- **Network** Resources settings in [Docker Desktop GUI](/manuals/desktop/settings-and-maintenance/settings.md)
542+
- Settings Management: `dnsInhibition` setting in the [`admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md)
543+
544+
For more information, see [Networking](/manuals/desktop/features/networking.md#networking-mode-and-dns-behaviour-for-mac-and-windows).
545+
516546
### Enable WSL engine
517547

518548
| Default value | Accepted values | Format |

0 commit comments

Comments
 (0)