Engdocs 2038 (#19698)

* ENGDOCS-2038

* ENGDOCS-2038

* re-write with D.Scott's info

* review edits

content/desktop/hardened-desktop/settings-management/_index.md

@@ -43,6 +43,7 @@ Using the `admin-settings.json` file, admins can:
 - Turn off beta and experimental features
 - Control the file sharing implementation for your developers on macOS
 - Specify which paths your developers can add file shares to
+- Configure air-gapped containers (Beta)
 
 For more details on the syntax and options admins can set, see [Configure Settings Management](configure.md).
 

content/desktop/hardened-desktop/settings-management/air-gapped-containers.md

@@ -0,0 +1,89 @@
+---
+description: Learn how to create air-gapped containers with Settings Management
+title: Configure air-gapped containers with Settings Management
+keywords: settings management, air gapped, security, Docker Desktop, configuration, proxy, network
+---
+
+> **Beta feature**
+>
+> This feature is in [Beta](../../../release-lifecycle.md/#beta).
+> It's available with Docker Desktop version 4.29 and later.
+{ .experimental }
+
+Air-gapped containers allows administrators to restrict containers from accessing network resources, limiting where data can be uploaded to or downloaded from.
+
+Docker Desktop can apply a custom set of proxy rules to network traffic from containers. The proxy can be configured to:
+
+- Allow network connections
+- Reject network connections
+- Tunnel through an HTTP or SOCKS proxy
+
+You can choose:
+
+- Which outgoing TCP ports the policy applies to. For example, only certain ports, `80`, `443` or all with `*`.
+- Whether to forward to a single HTTP or SOCKS proxy, or to have a policy per destination via a Proxy Auto-Configuration (PAC) file.
+
+## Configuration
+
+Assuming [enforced sign-in](../../../security/for-admins/configure-sign-in.md) and Settings Management are enabled, add the new proxy configuration to the `admin-settings.json` file. For example:
+
+```json
+{
+  "configurationFileVersion": 2,
+  "containersProxy": {
+    "locked": true,
+    "mode": "manual",
+    "http": "",
+    "https": "",
+    "exclude": "",
+    "pac": "http://192.168.1.16:62039/proxy.pac",
+    "transparentPorts": "*"
+  }
+}
+```
+
+The `containersProxy` setting describes the policy which is applied to traffic from containers. The valid fields are:
+
+- `locked`: If true, it is not possible for developers to override these settings. If false the settings are interpreted as default values which the developer can change.
+- `mode`: Same meaning as with the existing `proxy` setting. Possible values are `system` and `manual`.
+- `http`, `https`, `exclude`: Same meaning as with the `proxy` setting. Only takes effect if `mode` is set to `manual`.
+- `pac` : URL for a PAC file. Only takes effect if `mode` is `manual`, and is considered higher priority than `http`, `https`, `exclude`.
+- `transparentPorts`: A comma-separated list of ports (e.g. `"80,443,8080"`) or a wildcard (`*`) indicating which ports should be proxied.
+
+> **Important**
+>
+> Any existing `proxy` setting in the `admin-settings.json` file continues to apply to traffic from the app on the host.
+{ .important }
+
+## Example PAC file
+
+For general information about PAC files, see the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file).
+
+The following is an example PAC file:
+
+```javascript
+function FindProxyForURL(url, host) {
+	if (localHostOrDomainIs(host, 'internal.corp')) {
+		return "PROXY 10.0.0.1:3128";
+	}
+	if (isInNet(host, "192.168.0.0", "255.255.255.0")) {
+	    return "DIRECT";
+	}
+    return "PROXY reject.docker.internal:1234";
+}
+```
+
+The `url` parameter is either `http://host_or_ip:port` or `https://host_or_ip:port`.
+
+The hostname is normally available for outgoing requests on port `80` and `443`, but for other cases there is only an IP address.
+
+The `FindProxyForURL` can return the following values:
+
+- `PROXY host_or_ip:port`: Tunnels this request through the HTTP proxy `host_or_ip:port`
+- `SOCKS5 host_or_ip:port`: Tunnels this request through the SOCKS proxy `host_or_ip:port`
+- `DIRECT`: Allows this request to go direct, without a proxy
+- `PROXY reject.docker.internal:any_port`: Rejects this request
+
+In this particular example, HTTP and HTTPS requests for `internal.corp` are sent via the HTTP proxy `10.0.0.1:3128`. Requests to connect to IPs on the subnet `192.168.0.0/24` connect directly. All other requests are blocked.
+
+To restrict traffic connecting to ports on the developers local machine, [match the special hostname `host.docker.internal`](../../networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host).

content/desktop/hardened-desktop/settings-management/configure.md

@@ -68,6 +68,15 @@ The following `admin-settings.json` code and table provides an example of the re
     "exclude": [],
     "windowsDockerdPort": 65000
   },
+  "containersProxy": {
+    "locked": true,
+    "mode": "manual",
+    "http": "",
+    "https": "",
+    "exclude": [],
+    "pac":"",
+    "transparentPorts": ""
+  },
   "enhancedContainerIsolation": {
     "locked": true,
     "value": true,
@@ -166,6 +175,7 @@ The following `admin-settings.json` code and table provides an example of the re
 | `exposeDockerAPIOnTCP2375` | Windows only| Exposes the Docker API on a specified port. If `value` is set to true, the Docker API is exposed on port 2375. Note: This is unauthenticated and should only be enabled if protected by suitable firewall rules.|
 | `proxy` |   |If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores and 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. |
 |        `windowsDockerdPort`  | Windows only | Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. If it is set to 0, a random free port is chosen. If the value is greater than 0, use that exact value for the port. The default value is -1 which disables the option. Note: This is available for Windows containers only. |
+| `containersProxy` (Beta) | | Allows you to create air-gapped containers. For more information see [Configure air-gapped containers with Settings Management](air-gapped-containers.md).|
 | `enhancedContainerIsolation`  |  | If `value` is set to true, Docker Desktop runs all containers as unprivileged, via the Linux user-namespace, prevents them from modifying sensitive configurations inside the Docker Desktop VM, and uses other advanced techniques to isolate them. For more information, see [Enhanced Container Isolation](../enhanced-container-isolation/index.md).|
 |        `dockerSocketMount` |  | By default, enhanced container isolation blocks bind-mounting the Docker Engine socket into containers (e.g., `docker run -v /var/run/docker.sock:/var/run/docker.sock ...`). This allows admins to relax this in a controlled way. See [ECI Configuration](../enhanced-container-isolation/config.md) for more info. |
 |               `imageList` |  | Indicates which container images are allowed to bind-mount the Docker Engine socket. |

data/toc.yaml

@@ -1149,6 +1149,8 @@ Manuals:
             title: What is Settings Management?
           - path: /desktop/hardened-desktop/settings-management/configure/
             title: Configure Settings Management
+          - path: /desktop/hardened-desktop/settings-management/air-gapped-containers/
+            title: Air-gapped containers (Beta)
         - sectiontitle: Enhanced Container Isolation
           section:
           - path: /desktop/hardened-desktop/enhanced-container-isolation/