diff --git a/content/manuals/desktop/features/networking/_index.md b/content/manuals/desktop/features/networking/_index.md index fa3d52d0f13..4f69cc9800f 100644 --- a/content/manuals/desktop/features/networking/_index.md +++ b/content/manuals/desktop/features/networking/_index.md @@ -65,13 +65,9 @@ Host firewalls can permit or deny inbound connections by filtering on `com.docke ## Using Docker Desktop with a proxy -Docker Desktop can use your system’s default proxy settings or custom settings that you configure with [Docker Desktop's proxy setting](/manuals/desktop/settings-and-maintenance/settings.md#proxies). All proxy traffic passes through `com.docker.backend.exe`. +Docker Desktop can use your system’s default proxy settings or custom settings that you configure with [Docker Desktop’s proxy setting](/manuals/desktop/settings-and-maintenance/settings.md#proxies). -When a proxy is enabled: - -- The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`. -- The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary. -- Docker Desktop then downloads the requested images or data through the proxy as usual. +Docker Desktop routes traffic through two separate proxies. The Containers proxy governs all `docker image pull` operations, as well as running container traffic when air-gapped container enforcement is enabled. The Docker Desktop proxy governs host-level traffic - the Desktop application, Docker CLI, and extensions — and is a fallback for image pulls only when the Containers proxy is not explicitly configured. Note that: diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index 7f74e9f69bc..71b9c2951f0 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -123,7 +123,7 @@ To prevent developers from accidentally changing the proxy settings, see #### Docker Desktop proxy -Used for signing in to Docker, pulling and pushing images, fetching artifacts during image builds, and reporting error diagnostics. +Used for Docker Desktop host-level traffic: signing in to Docker, the Desktop application, CLI, and extensions. Acts as a fallback for `docker image pull` only when [Containers proxy](#containers-proxy) is not configured. | Proxy mode | Description | |------------|-------------| @@ -137,7 +137,7 @@ Used for signing in to Docker, pulling and pushing images, fetching artifacts du #### Containers proxy -Used for outbound traffic from running containers. +Used for `docker image pull` (always enforced - all `docker pull` and Compose pull operations go through this proxy) and for outbound traffic from running containers when air-gapped container enforcement is configured. If a PAC file is configured here, ensure it returns an appropriate proxy server for Docker registry endpoints, or image pulls will fail. | Proxy mode | Description | |------------|-------------| diff --git a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md index 70393db82b0..36eb900d1e1 100644 --- a/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md +++ b/content/manuals/enterprise/security/hardened-desktop/air-gapped-containers.md @@ -23,16 +23,17 @@ Use air-gapped containers if: ## How air-gapped containers work -Air-gapped containers operate by intercepting container network traffic and applying proxy rules: +`containersProxy` governs two distinct traffic paths: -1. Traffic interception: Docker Desktop intercepts all outgoing network connections from containers -1. Port filtering: Only traffic on specified ports (`transparentPorts`) is subject to proxy rules -1. Rule evaluation: PAC file rules or static proxy settings determine how to handle each connection -1. Connection handling: Traffic is allowed directly, routed through a proxy, or blocked based on the rules +- Image pulls (always enforced): Docker Desktop hardwires `http.docker.internal:3128` as the daemon's proxy in `daemon.json` at VM startup, so all `docker pull` and Compose pull operations always go through `containersProxy`, including any PAC file rules. +- Running container outbound traffic (opt-in): Docker Desktop intercepts container TCP connections and applies proxy rules only for ports listed in `transparentPorts`. Without it, running container traffic bypasses `containersProxy` entirely. -Some important considerations include: +> [!IMPORTANT] +> +> If you configure a PAC file under `containersProxy`, the PAC file must return an appropriate proxy server to connect to the registries where your images are hosted. + +Other considerations: -- The existing `proxy` setting continues to apply to Docker Desktop application traffic on the host - If PAC file download fails, containers block requests to target URLs - Hostname is available for ports 80 and 443, but only IP addresses for other ports @@ -65,7 +66,7 @@ Add the container proxy to your [`admin-settings.json` file](/manuals/enterprise ### Configuration parameters -The `containersProxy` setting controls network policies applied to container traffic: +The `containersProxy` setting controls network policies applied to `docker image pull` and, when `transparentPorts` is configured, running container outbound traffic: | Parameter | Description | Value | |-----------|-------------|-------| diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md index 92d55ac7d98..06a018c865d 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md @@ -309,6 +309,11 @@ The following tables describe all available settings in the `admin-settings.json ### Proxy settings +Docker Desktop has two distinct proxy settings with different scopes: + +- `proxy` (App Proxy): Governs Docker Desktop host-level traffic — the Desktop application, Docker CLI, and extensions. It also serves as a fallback for the daemon when `containersProxy` is not explicitly configured. Once `containersProxy` is set, `proxy` plays no role in daemon or container traffic. +- [`containersProxy`](#container-proxy): Always governs `docker image pull`. All `docker image pull` and Compose pull operations go through `containersProxy`, including any PAC file rules. It also governs running container outbound traffic when `transparentPorts` is configured. + | Parameter | OS | Description | Version | | :------------------- | ------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `proxy` | | If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores any values set for `http`, `https` and `exclude`. Change `mode` to `manual` to manually configure proxy servers. If the proxy port is custom, specify it in the `http` or `https` property, for example `"https": "http://myotherproxy.com:4321"`. The `exclude` property specifies a comma-separated list of hosts and domains to bypass the proxy. | | @@ -332,7 +337,7 @@ The following tables describe all available settings in the `admin-settings.json | Parameter | OS | Description | Version | | :---------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -| `containersProxy` | | Creates air-gapped containers. For more information see [Air-Gapped Containers](../air-gapped-containers.md). | | +| `containersProxy` | | Configures the proxy for `docker image pull` (always enforced) and running container outbound traffic (enforced when `transparentPorts` is set). For more information see [Air-Gapped Containers](../air-gapped-containers.md). | | | `pac` | | Specifies a PAC file URL. For example, `"pac": "http://containerproxy/proxy.pac"`. | | | `embeddedPac` | | Specifies an embedded PAC (Proxy Auto-config) script. For example, `"embeddedPac": "function FindProxyForURL(url, host) { return \"PROXY 192.168.92.1:2003\"; }"`. This setting takes precedence over HTTP, HTTPS, Proxy bypass and PAC server URL. | | diff --git a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md index eb703caa9fd..08a741de397 100644 --- a/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md +++ b/content/manuals/enterprise/security/hardened-desktop/settings-management/settings-reference.md @@ -400,7 +400,16 @@ Defines network addresses that containers should bypass when using proxy setting ### Air-gapped container proxy -Configures an HTTP/HTTPS proxy for containers in air-gapped environments, providing controlled network access in offline or restricted network environments. +Configures an HTTP/HTTPS proxy that governs two distinct traffic paths: + +- Daemon image pulls (always enforced): Docker Desktop always injects `http.docker.internal:3128` as the daemon's proxy in `daemon.json` at VM startup. All `docker pull` and Compose pull operations are routed through `containersProxy`, including any PAC file rules. This applies regardless of whether `transparentPorts` is configured. +- Running container outbound traffic (opt-in): Container TCP traffic is only subject to `containersProxy` rules when `transparentPorts` is configured. Without it, running containers connect directly and PAC file rules do not apply to their outbound traffic. + +> [!IMPORTANT] +> +> If you configure a PAC file under `containersProxy`, the PAC file must return an appropriate proxy server to connect to the registries where your images are hosted. + +The [`proxy`](#proxy) setting governs Docker Desktop host-level traffic: the Desktop application, Docker CLI, and extensions. It serves as a fallback for the daemon only when `containersProxy` is not explicitly configured. Once `containersProxy` is set, `proxy` plays no role in daemon or container traffic. | Property | Value | |---|---|