Configure Settings Management with a JSON file

メモ

Settings Management is available to Docker Business customers only.

This page contains information on how to configure Settings Management with an admin-settings.json file. You can specify and lock configuration parameters to create a standardized Docker Desktop environment across your company or organization.

Settings Management is designed specifically for organizations who don’t give developers root access to their machines.

Prerequisites

You first need to enforce sign-in to ensure that all Docker Desktop developers authenticate with your organization. Since Settings Management requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in.

Step one: Create the admin-settings.json file and save it in the correct location

You can either use the --admin-settings installer flag on macOS or Windows to automatically create the admin-settings.json and save it in the correct location, or set it up manually.

To set it up manually:

  1. Create a new, empty JSON file and name it admin-settings.json.

  2. Save the admin-settings.json file on your developers' machines in the following locations:

    • Mac: /Library/Application\ Support/com.docker.docker/admin-settings.json
    • Windows: C:\ProgramData\DockerDesktop\admin-settings.json
    • Linux: /usr/share/docker-desktop/admin-settings.json

    By placing this file in a protected directory, developers are unable to modify it.

    重要

    It is assumed that you have the ability to push the admin-settings.json settings file to the locations specified through a device management software such as Jamf.

Step two: Configure the settings you want to lock in

メモ

Some of the configuration parameters only apply to certain platforms or to specific Docker Desktop versions. This is highlighted in the following table.

The admin-settings.json file requires a nested list of configuration parameters, each of which must contain the locked parameter. You can add or remove configuration parameters as per your requirements.

If locked: true, users aren't able to edit this setting from Docker Desktop or the CLI.

If locked: false, it's similar to setting a factory default in that:

  • For new installs, locked: false pre-populates the relevant settings in the Docker Desktop Dashboard, but users are able to modify it.

  • If Docker Desktop is already installed and being used, locked: false is ignored. This is because existing users of Docker Desktop may have already updated a setting, which in turn will have been written to the relevant config file, for example the settings-store.json (or settings.json for Docker Desktop versions 4.34 and earlier) or daemon.json. In these instances, the user's preferences are respected and the values aren't altered. These can be controlled by setting locked: true.

The following admin-settings.json code and table provides an example of the required syntax and descriptions for parameters and values:

{
  "configurationFileVersion": 2,
  "exposeDockerAPIOnTCP2375": {
    "locked": true,
    "value": false
  },
  "proxy": {
    "locked": true,
    "mode": "system",
    "http": "",
    "https": "",
    "exclude": [],
    "windowsDockerdPort": 65000,
    "enableKerberosNtlm": false
  },
  "containersProxy": {
    "locked": true,
    "mode": "manual",
    "http": "",
    "https": "",
    "exclude": [],
    "pac":"",
    "transparentPorts": ""
  },
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*"
        ]
      },
      "commandList": {
        "type": "deny",
        "commands": ["push"]
      }
    }
  },
  "linuxVM": {
    "wslEngineEnabled": {
      "locked": false,
      "value": false
    },
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    },
    "vpnkitCIDR": {
      "locked": false,
      "value":"192.168.65.0/24"
    }
  },
  "kubernetes": {
     "locked": false,
     "enabled": false,
     "showSystemContainers": false,
     "imagesRepository": ""
  },
  "windowsContainers": {
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    }
  },
  "disableUpdate": {
    "locked": false,
    "value": false
  },
  "analyticsEnabled": {
    "locked": false,
    "value": true
  },
  "extensionsEnabled": {
    "locked": true,
    "value": false
  },
  "scout": {
    "locked": false,
    "sbomIndexing": true,
    "useBackgroundIndexing": true
  },
  "allowExperimentalFeatures": {
    "locked": false,
    "value": false
  },
  "allowBetaFeatures": {
    "locked": false,
    "value": false
  },
  "blockDockerLoad": {
    "locked": false,
    "value": true
  },
  "filesharingAllowedDirectories": [
    {
      "path": "$HOME",
      "sharedByDefault": true
    },
    {
      "path":"$TMP",
      "sharedByDefault": false
    }
  ],
  "useVirtualizationFrameworkVirtioFS": {
    "locked": true,
    "value": true
  },
  "useVirtualizationFrameworkRosetta": {
    "locked": true,
    "value": true
  },
  "useGrpcfuse": {
    "locked": true,
    "value": true
  },
  "displayedOnboarding": {
    "locked": true,
    "value": true
  },
  "desktopTerminalEnabled": {
    "locked": false,
    "value": false
  }
}

General

ParameterOSDescriptionVersion
configurationFileVersionSpecifies the version of the configuration file format.
analyticsEnabledIf value is set to false, Docker Desktop doesn't send usage statistics to Docker.
disableUpdateIf value is set to true, checking for and notifications about Docker Desktop updates is disabled.
extensionsEnabledIf value is set to false, Docker extensions are disabled.
blockDockerLoadIf value is set to true, users are no longer able to run docker load and receive an error if they try to.
displayedOnboardingIf value is set to true, the onboarding survey will not be displayed to new users. Setting value to false has no effect.Docker Desktop version 4.30 and later
desktopTerminalEnabledIf value is set to false, developers cannot use the Docker terminal to interact with the host machine and execute commands directly from Docker Desktop.
exposeDockerAPIOnTCP2375Windows onlyExposes 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.

File sharing and emulation

ParameterOSDescriptionVersion
filesharingAllowedDirectoriesSpecify 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.
useVirtualizationFrameworkVirtioFSmacOS onlyIf 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.
useGrpcfusemacOS onlyIf value is set to true, gRPC Fuse is set as the file sharing mechanism.
useVirtualizationFrameworkRosettamacOS onlyIf value is set to true, Docker Desktop turns on Rosetta to accelerate x86_64/amd64 binary emulation on Apple Silicon. Note: This also automatically enables Use Virtualization framework.Docker Desktop version 4.29 and later.

Docker Scout

ParameterOSDescriptionVersion
scoutSetting useBackgroundIndexing to false disables automatic indexing of images loaded to the image store. Setting sbomIndexing to false prevents users from being able to index image by inspecting them in Docker Desktop or using docker scout CLI commands.

Proxy

ParameterOSDescriptionVersion
proxyIf 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.
       windowsDockerdPortWindows onlyExposes 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.
       enableKerberosNtlmWhen set to true, Kerberos and NTLM authentication is enabled. Default is false. For more information, see the settings documentation.Docker Desktop version 4.32 and later.

Container proxy

ParameterOSDescriptionVersion
containersProxyCreates air-gapped containers. For more information see Air-Gapped Containers.Docker Desktop version 4.29 and later.

Linux VM

ParameterOSDescriptionVersion
linuxVMParameters and settings related to Linux VM options - grouped together here for convenience.
       wslEngineEnabledWindows onlyIf 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=<backend name> flag.
       dockerDaemonOptionsIf value is set to true, it overrides the options in the Docker Engine config file. See the Docker Engine reference. Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled.
       vpnkitCIDROverrides the network range used for vpnkit DHCP/DNS for *.docker.internal

Windows containers

ParameterOSDescriptionVersion
windowsContainersParameters and settings related to windowsContainers options - grouped together here for convenience.
       dockerDaemonOptionsOverrides the options in the Linux daemon config file. See the Docker Engine reference.

メモ

This setting is not available to configure via the Docker Admin Console.

Kubernetes

ParameterOSDescriptionVersion
kubernetesIf 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 Docker Desktop Dashboard and when you run docker ps. imagesRepository lets you specify which repository Docker Desktop pulls the Kubernetes images from. For example, "imagesRepository": "registry-1.docker.io/docker".

Features in development

ParameterOSDescriptionVersion
allowExperimentalFeaturesIf value is set to false, experimental features are disabled.
allowBetaFeaturesIf value is set to false, beta features are disabled.

Enhanced Container Isolation

ParameterOSDescriptionVersion
enhancedContainerIsolationIf 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.
       dockerSocketMountBy 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 lets you relax this in a controlled way. See ECI Configuration for more info.
              imageListIndicates which container images are allowed to bind-mount the Docker Engine socket.
              commandListRestricts the commands that containers can issue via the bind-mounted Docker Engine socket.

Step three: Re-launch Docker Desktop

メモ

Test the changes made through the admin-settings.json file locally to see if the settings work as expected.

For settings to take effect:

  • On a new install, developers need to launch Docker Desktop and authenticate to their organization.
  • On an existing install, developers need to quit Docker Desktop through the Docker menu, and then re-launch Docker Desktop. If they are already signed in, they don't need to sign in again for the changes to take effect.

    重要

    Selecting Restart from the Docker menu isn't enough as it only restarts some components of Docker Desktop.

So as not to disrupt your developers' workflow, Docker doesn't automatically mandate that developers re-launch and re-authenticate once a change has been made.

In Docker Desktop, developers see the relevant settings grayed out and the message Locked by your administrator.

Proxy settings grayed out with Settings Management