From 0901fa6221eade34a05b6f9ebd234c4e81828530 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:07:02 +0000 Subject: [PATCH] ENGDOCS-1994 (#19445) * ENGDOCS-1994 * technical review comment * editorial review * fix json * fix json * Update content/desktop/hardened-desktop/settings-management/configure.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> * Fix links --------- Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .../settings-management/_index.md | 14 ++++---- .../settings-management/configure.md | 32 ++++++++++++++++--- 2 files changed, 35 insertions(+), 11 deletions(-) diff --git a/content/desktop/hardened-desktop/settings-management/_index.md b/content/desktop/hardened-desktop/settings-management/_index.md index 7f69fcc3de..3212e12388 100644 --- a/content/desktop/hardened-desktop/settings-management/_index.md +++ b/content/desktop/hardened-desktop/settings-management/_index.md @@ -23,9 +23,9 @@ It is available with [Docker Desktop 4.13.0 and later](../../release-notes.md). ### How does it work? -Administrators can configure several Docker Desktop settings using an `admin-settings.json` file. This file is located on the Docker Desktop host and can only be accessed by users with root or admin privileges. +Administrators can configure several Docker Desktop settings using an `admin-settings.json` file. This file is located on the Docker Desktop host and can only be accessed by developers with root or admin privileges. -Values that are set to `locked: true` within the `admin-settings.json` override any previous values set by users and ensure that these cannot be modified. For more information, see [Configure Settings Management](../settings-management/configure.md#step-two-configure-the-settings-you-want-to-lock-in). +Values that are set to `locked: true` within the `admin-settings.json` override any previous values set by developers and ensure that these cannot be modified. For more information, see [Configure Settings Management](../settings-management/configure.md#step-two-configure-the-settings-you-want-to-lock-in). ### What features can I configure with Settings Management? @@ -41,23 +41,25 @@ Using the `admin-settings.json` file, admins can: - Turn off Docker Extensions - Turn off Docker Scout SBOM indexing - 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 For more details on the syntax and options admins can set, see [Configure Settings Management](configure.md). ### How do I set up and enforce Settings Management? -As an administrator, you first need to [configure a registry.json to enforce sign-in](../../../security/for-admins/configure-sign-in.md). This is because the Settings Management feature requires a Docker Business subscription and therefore your Docker Desktop users must authenticate to your organization for this configuration to take effect. +As an administrator, you first need to [configure a registry.json to enforce sign-in](../../../security/for-admins/configure-sign-in.md). This is because the Settings Management feature requires a Docker Business subscription and therefore your Docker Desktop developers must authenticate to your organization for this configuration to take effect. Next, you must either manually [create and configure the admin-settings.json file](configure.md), or use the `--admin-settings` installer flag on [macOS](../../install/mac-install.md#install-from-the-command-line) or [Windows](../../install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json` and save it in the correct location. -Once this is done, Docker Desktop users receive the changed settings when they either: +Once this is done, Docker Desktop developers receive the changed settings when they either: - Quit, re-launch, and sign in to Docker Desktop - Launch and sign in to Docker Desktop for the first time Docker doesn't automatically mandate that developers re-launch and re-authenticate once a change has been made, so as not to disrupt your developers' workflow. -### What do users see when the settings are enforced? +### What do developers see when the settings are enforced? -Any settings that are enforced, are grayed out in Docker Desktop and the user is unable to edit them, either via the Docker Desktop UI, CLI, or the `settings.json` file. In addition, if Enhanced Container Isolation is enforced, users can't use privileged containers or similar techniques to modify enforced settings within the Docker Desktop Linux VM, for example, reconfigure proxy and networking of reconfigure Docker Engine. +Any settings that are enforced, are grayed out in Docker Desktop and the user is unable to edit them, either via the Docker Desktop UI, CLI, or the `settings.json` file. In addition, if Enhanced Container Isolation is enforced, developers can't use privileged containers or similar techniques to modify enforced settings within the Docker Desktop Linux VM, for example, reconfigure proxy and networking of reconfigure Docker Engine. ![Proxy settings grayed out](/assets/images/grayed-setting.png) diff --git a/content/desktop/hardened-desktop/settings-management/configure.md b/content/desktop/hardened-desktop/settings-management/configure.md index bb7f058547..872bac90ff 100644 --- a/content/desktop/hardened-desktop/settings-management/configure.md +++ b/content/desktop/hardened-desktop/settings-management/configure.md @@ -138,22 +138,40 @@ The following `admin-settings.json` code and table provides an example of the re "blockDockerLoad": { "locked": false, "value": true + }, + "filesharingAllowedDirectories": [ + { + "path": "$HOME", + "sharedByDefault": true + }, + { + "path":"$TMP", + "sharedByDefault": false + } + ], + "useVirtualizationFrameworkVirtioFS": { + "locked": true, + "value": true + }, + "useGrpcfuse": { + "locked": true, + "value": true } -} +} ``` | Parameter | | Description | | :------------------------------- |---| :------------------------------- | | `configurationFileVersion` | |Specifies the version of the configuration file format. | -| `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.| +| `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. | +|        `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. | | `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. | |               `commandList` | | Restricts the commands that containers can issue via the bind-mounted Docker Engine socket. | | `linuxVM` | |Parameters and settings related to Linux VM options - grouped together here for convenience. | -|        `wslEngineEnabled` | Windows only | If `value` is set to true, Docker Desktop uses the WSL 2 based engine. This overrides anything that may have been set at installation using the `--backend=` flag. | +|        `wslEngineEnabled` | Windows only | If `value` is set to true, Docker Desktop uses the WSL 2 based engine. This overrides anything that may have been set at installation using the `--backend=` flag. | |       `dockerDaemonOptions`| |If `value` is set to true, it overrides the options in the Docker Engine config file. See the [Docker Engine reference](/reference/cli/dockerd/#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. | |       `vpnkitCIDR` | |Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal` | |`kubernetes`| | If `enabled` is set to true, a Kubernetes single-node cluster is started when Docker Desktop starts. If `showSystemContainers` is set to true, Kubernetes containers are displayed in the UI and when you run `docker ps`. `imagesRepository` allows you to specify which repository Docker Desktop pulls the Kubernetes images from. For example, `"imagesRepository": "registry-1.docker.io/docker"`. | @@ -165,7 +183,11 @@ The following `admin-settings.json` code and table provides an example of the re |`scout`|| Setting `useBackgroundIndexing` to `false` disables automatic indexing of images loaded to the image store. Setting `sbomIndexing` to `false` prevents the manual indexing triggered by inspecting an image in Docker Desktop.

**Note**: Users can still use the `docker scout` CLI commands to index images, even if indexing is disabled in Settings Management. | | `allowExperimentalFeatures`| | If `value` is set to `false`, experimental features are disabled.| | `allowBetaFeatures`| | If `value` is set to `false`, beta features are disabled.| -| `blockDockerLoad` | | If `value` is set to `true`, users are no longer able to run [`docker load`](../../../reference/cli/docker/image/load.md) and receive an error if they try to.| +| `blockDockerLoad` | | If `value` is set to `true`, users are no longer able to run [`docker load`](/reference/cli/docker/image/load/) and receive an error if they try to.| +| `filesharingAllowedDirectories` | | Specify which paths your developers can add file shares to. Also accepts `$HOME`, `$TMP`, or `$TEMP` as `path` variables. When a path is added, its subdirectories are allowed. If `sharedByDefault` is set to `true`, that path will be added upon factory reset or when Docker Desktop first starts. | +| `useVirtualizationFrameworkVirtioFS`| macOS only | If `value` is set to `true`, VirtioFS is set as the file sharing mechanism. Note: If both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `true`, VirtioFS takes precedence. Likewise, if both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `false`, osxfs is set as the file sharing mechanism. | +| `useGrpcfuse` | macOS only | If `value` is set to `true`, gRPC Fuse is set as the file sharing mechanism. | + ### Step three: Re-launch Docker Desktop >**Note**