docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DD 4.20: Update docs to indicate support for ECI on WSL-2 hosts. (#16684) 

* Update docs to indicate support for ECI on WSL-2 hosts.

Signed-off-by: Cesar Talledo <cesar.talledo@docker.com>

* More improvements to Hardened Desktop ECI docs.

Signed-off-by: Cesar Talledo <cesar.talledo@docker.com>

* Rename subsection in ECI FAQ to avoid breaking links to it.

Signed-off-by: Cesar Talledo <cesar.talledo@docker.com>

* Remove reference to Microsoft in ECI docs.

Signed-off-by: Cesar Talledo <cesar.talledo@docker.com>

* Add note indicating containers should be stopped/removed prior to enabling ECI.

See Jira ticket: https://docker.atlassian.net/browse/POS-1752

Signed-off-by: Cesar Talledo <cesar.talledo@docker.com>

---------

Signed-off-by: Cesar Talledo <cesar.talledo@docker.com>
This commit is contained in:
Cesar Talledo 2023-05-30 09:02:14 -07:00 committed by GitHub
parent 85404b4641
commit 93ea6677a5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 160 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
desktop/hardened-desktop/enhanced-container-isolation/faq.md
View File

@ -1,6 +1,6 @@
--- ---
title: FAQs and known issues title: FAQs and known issues
description: FAQ for Enhanced Container Isolation description: FAQ for Enhanced Container Isolation
keywords: enhanced container isolation, security, faq, sysbox, known issues, Docker Desktop keywords: enhanced container isolation, security, faq, sysbox, known issues, Docker Desktop
toc_max: 2 toc_max: 2
--- ---
@ -18,9 +18,10 @@ No, you can continue to use Docker as usual. Enhanced Container Isolation will b
#### Do all container workloads work well with Enhanced Container Isolation? #### Do all container workloads work well with Enhanced Container Isolation?
Most container workloads do, a few do not (yet). For the few workloads that The great majority of container workloads run fine with ECI, but a few do not
don't yet work with Enhanced Container Isolation, Docker will continue to improve the feature to reduce (yet). For the few workloads that don't yet work with Enhanced Container
this to a minimum. Isolation, Docker will continue to improve the feature to reduce this to a
minimum.
#### Can I run privileged containers with Enhanced Container Isolation? #### Can I run privileged containers with Enhanced Container Isolation?
@ -28,12 +29,13 @@ Yes, you can use the `--privileged` flag in containers but unlike privileged
containers without Enhanced Container Isolation, the container can only use it's elevated privileges to containers without Enhanced Container Isolation, the container can only use it's elevated privileges to
access resources assigned to the container. It can't access global kernel access resources assigned to the container. It can't access global kernel
resources in the Docker Desktop Linux VM. This allows you to run privileged resources in the Docker Desktop Linux VM. This allows you to run privileged
containers securely. For more information, see [Key features and benefits](features-benefits.md#privileged-containers-are-also-secured). containers securely (including Docker-in-Docker). For more information, see [Key features and benefits](features-benefits.md#privileged-containers-are-also-secured).
#### Will all privileged container workloads run with Enhanced Container Isolation? #### Will all privileged container workloads run with Enhanced Container Isolation?
No. Privileged container workloads, or non-namespaced workloads, that wish to access global kernel resources inside the Docker Desktop Linux VM won't No. Privileged container workloads that wish to access global kernel resources
work. For example, you can't use a privileged container to load a kernel module. inside the Docker Desktop Linux VM won't work. For example, you can't use a
privileged container to load a kernel module.
#### Why not just restrict usage of the `--privileged` flag? #### Why not just restrict usage of the `--privileged` flag?
@ -58,15 +60,22 @@ as configured via Docker Desktop's **Settings** > **Resources** > **File Sharing
It protects all containers launched by users via `docker create` and `docker run`. It does not yet protect Docker Desktop Kubernetes pods, Extension It protects all containers launched by users via `docker create` and `docker run`. It does not yet protect Docker Desktop Kubernetes pods, Extension
Containers, and Dev Environments. Containers, and Dev Environments.
#### Does Enhanced Container Isolation protect container launched prior to enabling ECI?
No. Containers created prior to enabling ECI are not protected. Therefore, we
recommend removing all containers prior to enabling ECI. In the future Docker
Desktop will likely make this a hard requirement.
#### Does Enhanced Container Isolation affect performance of containers? #### Does Enhanced Container Isolation affect performance of containers?
Enhanced Container Isolation has very little impact on the performance of containers. The exception is Enhanced Container Isolation has very little impact on the performance of
for containers that perform lots of `mount` and `umount` system calls, as these containers. The exception is for containers that perform lots of `mount` and
are trapped and vetted by the Sysbox container runtime. `umount` system calls, as these are trapped and vetted by the Sysbox container
runtime to ensure they are not being used to breach the container's filesystem.
#### With Enhanced Container Isolation, can the user still override the `--runtime` flag from the CLI ? #### With Enhanced Container Isolation, can the user still override the `--runtime` flag from the CLI ?
No. With Enhanced Container Isolation enabled, Sysbox is locked as the default (and only) runtime for No. With Enhanced Container Isolation enabled, Sysbox is set as the default (and only) runtime for
containers deployed by Docker Desktop users. If a user attempts to override the containers deployed by Docker Desktop users. If a user attempts to override the
runtime (e.g., `docker run --runtime=runc`), this request is ignored and the runtime (e.g., `docker run --runtime=runc`), this request is ignored and the
container is created through the Sysbox runtime. container is created through the Sysbox runtime.
@ -88,12 +97,56 @@ See [How does it work](how-eci-works.md#enhanced-container-isolation-vs-rootless
</div> </div>
<div id="tab4" class="tab-pane fade" markdown="1"> <div id="tab4" class="tab-pane fade" markdown="1">
#### Incompatibility with Windows Subsystem for Linux (WSL) #### ECI support for WSL
Enhanced Container Isolation (ECI) does not currently work when Docker Desktop runs on
Windows with WSL/WSL2. This is due to some limitations of the WSL/WSL2 Linux Prior to Docker Desktop 4.20, Enhanced Container Isolation (ECI) on
Kernel. As a result, to use Enhanced Container Isolation on Windows, you must Windows hosts was only supported when Docker Desktop was configured to use
configure Docker Desktop to use Hyper-V. This can be enforced using Admin Hyper-V to create the Docker Desktop Linux VM. ECI was not supported when Docker
Controls. For more information, see [Settings Management](../settings-management/index.md). Desktop was configured to use Windows Subsystem for Linux (aka WSL).
Starting with Docker Desktop 4.20, ECI is supported when Docker Desktop is
configured to use either Hyper-V or WSL version 2.
>**Note**
>
> Docker Desktop requires WSL 2 version 1.1.3.0 or later. To get the current
> version of WSL on your host, type `wsl --version`. If the command fails or if
> it returns a version number prior to 1.1.3.0, update WSL to the latest version
> by typing `wsl --update` in a Windows command or PowerShell terminal.
Note however that ECI on WSL is not as secure as on Hyper-V because:
* While ECI on WSL still hardens containers so that malicious workloads can't
easily breach Docker Desktop's Linux VM, ECI on WSL can't prevent Docker
Desktop users from breaching the Docker Desktop Linux VM. Such users can
trivially access that VM (as root) with the `wsl -d docker-desktop` command,
and use that access to modify Docker Engine settings inside the VM. This gives
Docker Desktop users control of the Docker Desktop VM and allows them to
bypass Docker Desktop configs set by admins via the
[settings-management](../settings-management/index.md) feature. In contrast,
ECI on Hyper-V does not allow Docker Desktop users to breach the Docker
Desktop Linux VM.
* With WSL 2, all WSL 2 distros on the same Windows host share the same instance
of the Linux kernel. As a result, Docker Desktop can't ensure the integrity of
the kernel in the Docker Desktop Linux VM since another WSL 2 distro could
modify shared kernel settings. In contrast, when using Hyper-V, the Docker
Desktop Linux VM has a dedicated kernel that is solely under the control of
Docker Desktop.
The table below summarizes this.
| Security Feature | ECI on WSL | ECI on Hyper-V | Comment |
| -------------------------------------------------- | ------------ | ---------------- | --------------------- |
| Strongly secure containers | Yes | Yes | Makes it harder for malicious container workloads to breach the Docker Desktop Linux VM and host. |
| Docker Desktop Linux VM protected from user access | No | Yes | On WSL, users can access Docker Engine directly or bypass Docker Desktop security settings. |
| Docker Desktop Linux VM has a dedicated kernel | No | Yes | On WSL, Docker Desktop can't guarantee the integrity of kernel level configs. |
In general, using ECI with Hyper-V is more secure than with WSL 2. But WSL 2
offers advantages for performance and resource utilization on the host machine,
and it's an excellent way for users to run their favorite Linux distro on
Windows hosts and access Docker from within (see Docker Desktop's WSL distro
integration feature, enabled via the Dashboard's **Settings** > **Resources** > **WSL Integration**).
#### Docker build and buildx has some restrictions #### Docker build and buildx has some restrictions
With ECI enabled, Docker build `--network=host` and Docker buildx entitlements With ECI enabled, Docker build `--network=host` and Docker buildx entitlements
@ -126,4 +179,4 @@ may run with ECI but not with `runc`, or vice-versa.
<hr> <hr>
</div> </div>
</div> </div>

8
desktop/hardened-desktop/enhanced-container-isolation/features-benefits.md
View File

@ -170,8 +170,12 @@ $ docker run -it --rm -v $HOME:/mnt alpine
> >
> Enhanced Container Isolation won't allow bind mounting the Docker socket > Enhanced Container Isolation won't allow bind mounting the Docker socket
> (/var/run/docker.sock) into a container, as doing so essentially grants the > (/var/run/docker.sock) into a container, as doing so essentially grants the
> container control of Docker, thus breaking container isolation. Containers > container control of Docker Engine, thus breaking container
> that rely on this will not work with Enhanced Container Isolation enabled. > isolation. Containers that rely on this will not work with Enhanced Container
> Isolation enabled. Instead, use Docker-in-Docker (i.e., run the Docker Engine
> fully inside a Docker Container). Enhanced Container Isolation is capable of
> running Docker-in-Docker securely, without giving the outer container root
> privileges in the Docker Desktop Linux VM.
### Vetting sensitive system calls ### Vetting sensitive system calls

93
desktop/hardened-desktop/enhanced-container-isolation/index.md
View File

@ -6,19 +6,21 @@ title: What is Enhanced Container Isolation?
>**Note** >**Note**
> >
>Enhanced Container Isolation is available to Docker Business customers only. >Enhanced Container Isolation is available to Docker Business customers only.
Enhanced Container Isolation provides an additional layer of security that uses a variety of advanced techniques to harden container isolation without impacting developer productivity. It is available with [Docker Desktop 4.13.0 or later](../../release-notes.md). Enhanced Container Isolation provides an additional layer of security to prevent malicious workloads running in containers from compromising Docker Desktop or the host.
It uses a variety of advanced techniques to harden container isolation, but without impacting developer productivity. It is available with [Docker Desktop 4.13.0 or later](../../release-notes.md).
These techniques include: These techniques include:
- Running all containers unprivileged through the Linux user-namespace. - Running all containers unprivileged through the Linux user-namespace, even those launched with the `--privileged` flag. This makes it harder for malicious container workloads to escape the container and infect the Docker Desktop VM and host.
- Restricting containers from modifying Docker Desktop VM settings. - Ensuring Docker Desktop VM immutability (e.g., its internal settings can't be modified by containers or users).
- Vetting some critical system calls to prevent container escapes, and partially virtualizing portions of `/proc` and `/sys` inside the container for further isolation. - Vetting some critical system calls to prevent container escapes, and partially virtualizing portions of `/proc` and `/sys` inside the container for further isolation.
- Preventing console access to the Docker Desktop VM. - Preventing user console access to the Docker Desktop VM.
This is done automatically and with minimal functional or performance impact. When Enhanced Container Isolation is enabled, these mechanisms are applied automatically and with minimal functional or performance impact to developers. Developers continue to use Docker Desktop as usual, but the containers they launch are more strongly isolated.
Enhanced Container Isolation helps ensure strong container isolation and also locks in any security configurations that have been created, for instance through [Registry Access Management policies](../registry-access-management.md) or with [Settings Management](../settings-management/index.md). Enhanced Container Isolation ensures stronger container isolation and also locks in any security configurations that have been created by IT admins, for instance through [Registry Access Management policies](../registry-access-management.md) or with [Settings Management](../settings-management/index.md).
>**Note** >**Note**
> >
@ -26,39 +28,66 @@ Enhanced Container Isolation helps ensure strong container isolation and also lo
### Who is it for? ### Who is it for?
- For organizations and developers that want to prevent container attacks and reduce vulnerabilities. - For organizations and developers that want to prevent container attacks and reduce vulnerabilities in developer environments.
- For organizations that want to ensure stronger container isolation that is easy and intuitive to implement on developers' machines. - For organizations that want to ensure stronger container isolation that is easy and intuitive to implement on developers' machines.
### What happens when Enhanced Container Isolation is enabled? ### What happens when Enhanced Container Isolation is enabled?
When Enhanced Container Isolation is turned on, the following features are enabled: When Enhanced Container Isolation is turned on, the following features are enabled:
- All user containers are automatically run in Linux User Namespaces which ensures stronger isolation. - All user containers are automatically run in Linux User Namespaces which ensures stronger isolation. Each container runs in a dedicated Linux user-namespace.
- The root user in the container maps to an unprivileged user at VM level. - The root user in the container maps to an unprivileged user inside the Docker Desktop Linux VM.
- Users can continue using containers as usual, including bind mounting host directories, volumes, networking configurations, etc.
- Privileged containers work, but they are only privileged within the container's Linux User Namespace, not in the Docker Desktop VM.
- Containers can no longer share namespaces with the Docker Desktop VM. For example, `--network=host`, `--pid=host`.
- Containers can no longer modify configuration files in the Docker Desktop VM.
- Console access to the Desktop VM is forbidden for all users.
- Containers become harder to breach. For example, sensitive system calls are vetted and portions of `/proc` and `/sys` are emulated. - Containers become harder to breach. For example, sensitive system calls are vetted and portions of `/proc` and `/sys` are emulated.
- Users can continue using containers as usual, including bind mounting host directories, volumes, etc.
- No change in the way developers run containers, and no special container images are required.
- Privileged containers (e.g., `--privileged` flag) work, but they are only privileged within the container's Linux User Namespace, not in the Docker Desktop VM. Therefore they can't be used to breach the Docker Desktop VM.
- Docker-in-Docker and even Kubernetes-in-Docker works, but run unprivileged inside the Docker Desktop Linux VM.
In addition, the following restrictions are imposed:
- Containers can no longer share namespaces with the Docker Desktop VM (e.g., `--network=host`, `--pid=host` are disallowed).
- Containers can no longer modify configuration files inside the Docker Desktop VM (e.g., mounting any VM directory into the container is disallowed).
- Containers can no longer access the Docker engine (e.g., mounting the Docker engine's socket into the container is restricted); this prevents malicious containers from gaining control of the Docker engine.
- Console access to the Docker Desktop VM is forbidden for all users.
These features and restrictions ensure that containers are better secured at runtime, with minimal impact to developer experience and productivity.
For more information on how Enhanced Container Isolation work, see [How does it work](how-eci-works.md). For more information on how Enhanced Container Isolation work, see [How does it work](how-eci-works.md).
>**Important** >**Important**
> >
>Enhanced Container Isolation is currently incompatible with WSL and does not protect Kubernetes pods. For more information on known limitations and workarounds, see [FAQs and known issues](faq.md). >Enhanced Container Isolation does not protect Kubernetes pods. For more information on known limitations and workarounds, see [FAQs and known issues](faq.md).
{: .important} {: .important}
### What host OSes / platforms is Enhanced Container Isolation supported on?
Enhanced Container Isolation (ECI) was introduced in Docker Desktop 4.13, for all platforms (Windows, Mac, and Linux).
For Windows hosts, ECI works with both the Docker Desktop Hyper-V and WSL 2 backends, as follows:
- Docker Desktop 4.19 or prior: ECI only works with Hyper-V.
- Docker Desktop 4.20 or later: ECI Works with both Hyper-V and WSL 2 (with WSL version 1.1.3.0 and above).
See [ECI Support for WSL](faq.md#eci-support-for-wsl) for further info as well as security caveats when using Enhanced Container Isolation on WSL 2.
### How do I enable Enhanced Container Isolation? ### How do I enable Enhanced Container Isolation?
#### As a developer #### As a developer
To enable Enhanced Container Isolation as a developer: To enable Enhanced Container Isolation as a developer:
1. Navigate to **Settings** > **General** in Docker Desktop. 1. Ensure your organization has a Docker Business subscription.
2. Next to **Use Enhanced Container Isolation**, select the checkbox. 2. Log in to your organization in Docker Desktop. This will ensure the ECI feature is available to you in Docker Desktop's Settings menu.
3. Select **Apply and restart** to save your settings. 3. Stop and remove all existing containers.
4. Navigate to **Settings** > **General** in Docker Desktop.
5. Next to **Use Enhanced Container Isolation**, select the checkbox.
6. Select **Apply and restart** to save your settings.
#### As an admin >**Important**
>
>Enhanced Container Isolation does not protect containers created prior to enabling ECI. For more information on known limitations and workarounds, see [FAQs and known issues](faq.md).
{: .important}
#### As an admin
To enable Enhanced Container Isolation as an admin, you first need to [configure a `registry.json` file to enforce sign-in](../../../docker-hub/configure-sign-in.md). This is because the Enhanced Container Isolation feature requires a Docker Business subscription and therefore your Docker Desktop users must authenticate to your organization for this configuration to take effect. To enable Enhanced Container Isolation as an admin, you first need to [configure a `registry.json` file to enforce sign-in](../../../docker-hub/configure-sign-in.md). This is because the Enhanced Container Isolation feature requires a Docker Business subscription and therefore your Docker Desktop users must authenticate to your organization for this configuration to take effect.
@ -74,6 +103,8 @@ Next, you must [create and configure the `admin-settings.json` file](../settings
} }
``` ```
By setting `"value": true`, the admin ensures ECI is enabled by default. By setting `"locked": true`, the admin ensures ECI can't be disabled by developers. If you wish to give developers the ability to disable the feature, set `"locked": false`.
For this to take effect: For this to take effect:
- On a new install, developers need to launch Docker Desktop and authenticate to their organization. - On a new install, developers need to launch Docker Desktop and authenticate to their organization.
@ -88,12 +119,12 @@ For this to take effect:
When Enhanced Container Isolation is enabled, users see: When Enhanced Container Isolation is enabled, users see:
- **Use Enhanced Container Isolation** toggled on in **Settings** > **General**. - **Use Enhanced Container Isolation** toggled on in **Settings** > **General**.
- Containers run within a Linux user namespace. - Containers run within a Linux user namespace.
To check, run: To check, run:
``` ```
$ docker run --rm alpine cat /proc/self/uid_map $ docker run --rm alpine cat /proc/self/uid_map
``` ```
The following output displays: The following output displays:
@ -102,17 +133,21 @@ The following output displays:
0 100000 65536 0 100000 65536
``` ```
This indicates that the container's root user (0) maps to unprivileged user (100000) in the Docker Desktop VM, and that the mapping extends for a range of 64K user-IDs. This indicates that the container's root user (0) maps to unprivileged user
(100000) in the Docker Desktop VM, and that the mapping extends for a range of
64K user-IDs. With If a container process were to escape the container, it would
find itself without privileges at the VM level. The user-ID mapping varies with
each new container, as each container gets an exclusive range of host User-IDs
for isolation. User-ID mapping is automatically managed by Docker Desktop. For
further details, see [How Enhanced Container Isolation works](how-eci-works.md).
In contrast, without Enhanced Container Isolation the Linux user namespace is not used, the following displays: In contrast, without ECI the Linux user namespace is not used for containers, the following displays:
``` ```
0 0 4294967295 0 0 4294967295
``` ```
This means that the root user in the container (0) is in fact the root user in the Docker Desktop VM (0) which reduces container isolation. The user-ID mapping varies with each new container, as each container gets an exclusive range of host User-IDs for isolation. User-ID mapping is automatically managed by Docker Desktop. This means that the root user in the container (0) is in fact the root user in the Docker Desktop VM (0) which reduces container isolation.
With Enhanced Container Isolation, if a process were to escape the container, it would find itself without privileges at the VM level. For further details, see [How Enhanced Container Isolation works](how-eci-works.md).
Since Enhanced Container Isolation [uses the Sysbox container runtime](how-eci-works.md) embedded in the Docker Desktop Linux VM, another way to determine if a container is running with Enhanced Container Isolation is by using `docker inspect`: Since Enhanced Container Isolation [uses the Sysbox container runtime](how-eci-works.md) embedded in the Docker Desktop Linux VM, another way to determine if a container is running with Enhanced Container Isolation is by using `docker inspect`:

9
desktop/hardened-desktop/index.md
View File

@ -7,19 +7,19 @@ keywords: security, hardened desktop, enhanced container isolation, registry acc
> >
>Hardened Docker Desktop is available to Docker Business customers only. >Hardened Docker Desktop is available to Docker Business customers only.
Hardened Docker Desktop is a security model for Docker Desktop. It's designed to provide admins with a simple and powerful way to improve their organization's security posture for containerized development, without impacting the developer experience that Docker Desktop offers. Hardened Docker Desktop is a group of security features for Docker Desktop, designed to improve security of developer environments without impacting developer experience or productivity.
It is for security conscious organizations who don’t give their users root or admin access on their machines, and who would like Docker Desktop to be within their organization’s centralized control. It is for security conscious organizations who don’t give their users root or admin access on their machines, and who would like Docker Desktop to be within their organization’s centralized control.
The Hardened Docker Desktop security model moves the ownership boundary for containers to the organization, meaning that any security controls admins set cannot be altered by the user of Docker Desktop. Hardened Docker Desktop moves the ownership boundary for Docker Desktop configuration to the organization, meaning that any security controls admins set cannot be altered by the user of Docker Desktop.
Hardened Docker Desktop includes: Hardened Docker Desktop includes:
- Settings Management, which helps admins to confidently manage and control the usage of Docker Desktop within their organization. - Settings Management, which helps admins to confidently manage and control the usage of Docker Desktop within their organization.
- Enhanced Container Isolation, a setting that instantly enhances security by preventing containers from running as root in Docker Desktop’s Linux VM and ensures that any configurations set using Settings Management, cannot be modified by containers. - Enhanced Container Isolation, a setting that instantly enhances security by preventing containers from running as root in Docker Desktop’s Linux VM and ensures that any configurations set using Settings Management cannot be bypassed or modified by containers.
- Registry Access Management, which allows admins to control the registries developers can access. - Registry Access Management, which allows admins to control the registries developers can access.
- Image Access Management, which gives admins control over which images developers can pull from Docker Hub. - Image Access Management, which gives admins control over which images developers can pull from Docker Hub.
The features of Hardened Docker Desktop operate independently of each other. When used together, these mechanisms defend against attacks at different functional layers of the developer workflow. The features of Hardened Docker Desktop operate independently of each other. When used together, these mechanisms defend against attacks at different functional layers of the developer workflow, providing a defense-in-depth approach to securing developer environments.
Docker plans to continue adding more security enhancements to the Hardened Docker Desktop security model. Docker plans to continue adding more security enhancements to the Hardened Docker Desktop security model.
@ -67,4 +67,3 @@ Docker plans to continue adding more security enhancements to the Hardened Docke
</div> </div>
</div> </div>
</div> </div>

16
desktop/hardened-desktop/settings-management/configure.md
View File

@ -2,11 +2,11 @@
description: settings management for desktop description: settings management for desktop
keywords: admin, controls, rootless, enhanced container isolation keywords: admin, controls, rootless, enhanced container isolation
title: Configure Settings Management title: Configure Settings Management
--- ---
>**Note** >**Note**
> >
>Settings Management is available to Docker Business customers only. >Settings Management is available to Docker Business customers only.
This page contains information for admins on how to configure Settings Management to specify and lock configuration parameters to create a standardized Docker Desktop environment across the organization. This page contains information for admins on how to configure Settings Management to specify and lock configuration parameters to create a standardized Docker Desktop environment across the organization.
@ -19,7 +19,7 @@ Settings Management is designed specifically for organizations who don’t give
### Step one: Create the `admin-settings.json` file and save it in the correct location ### 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](../../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, or set it up manually. You can either 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, or set it up manually.
To set it up manually: To set it up manually:
1. Create a new, empty JSON file and name it `admin-settings`. 1. Create a new, empty JSON file and name it `admin-settings`.
@ -107,14 +107,14 @@ The following `admin-settings.json` code and table provides an example of the re
} }
``` ```
| Parameter | | Description | | Parameter | | Description |
| :------------------------------- |---| :------------------------------- | | :------------------------------- |---| :------------------------------- |
| `configurationFileVersion` | |Specifies the version of the configuration file format. | | `configurationFileVersion` | |Specifies the version of the configuration file format. |
| `exposeDockerAPIOnTCP2375` | <span class="badge badge-info">Windows only</span>| 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` | <span class="badge badge-info">Windows only</span>| 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. | | `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. |
| `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). Note: Enhanced Container Isolation is currently [incompatible with WSL](../enhanced-container-isolation/faq.md#incompatibility-with-windows-subsystem-for-linux-wsl). | | `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).
| `linuxVM` | |Parameters and settings related to Linux VM options - grouped together here for convenience. | | `linuxVM` | |Parameters and settings related to Linux VM options - grouped together here for convenience. |
| &nbsp; &nbsp; &nbsp; &nbsp;`wslEngineEnabled` | <span class="badge badge-info">Windows only</span> | 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=<backend name>` flag. It is also incompatible with Enhanced Container Isolation. See [Known issues](../enhanced-container-isolation/faq.md) for more information.| | &nbsp; &nbsp; &nbsp; &nbsp;`wslEngineEnabled` | <span class="badge badge-info">Windows only</span> | 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=<backend name>` flag.
| &nbsp;&nbsp; &nbsp; &nbsp;`dockerDaemonOptions`| |If `value` is set to true, it overrides the options in the Docker Engine config file. See the [Docker Engine reference](/engine/reference/commandline/dockerd/#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. | | &nbsp;&nbsp; &nbsp; &nbsp;`dockerDaemonOptions`| |If `value` is set to true, it overrides the options in the Docker Engine config file. See the [Docker Engine reference](/engine/reference/commandline/dockerd/#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. |
| &nbsp;&nbsp; &nbsp; &nbsp;`vpnkitCIDR` | |Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal` | | &nbsp;&nbsp; &nbsp; &nbsp;`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"`. | |`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"`. |
@ -136,7 +136,7 @@ For settings to take effect:
>Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop. >Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop.
{: .important} {: .important}
Docker doesn't automatically mandate that developers re-launch and sign in once a change has been made so as not to disrupt your developers' workflow. Docker doesn't automatically mandate that developers re-launch and sign in once a change has been made so as not to disrupt your developers' workflow.
In Docker Desktop, developers see the relevant settings grayed out and the message **Locked by your administrator**. In Docker Desktop, developers see the relevant settings grayed out and the message **Locked by your administrator**.

14
desktop/hardened-desktop/settings-management/index.md
View File

@ -2,18 +2,18 @@
description: Settings Management for desktop description: Settings Management for desktop
keywords: Settings Management, rootless, docker desktop, hardened desktop keywords: Settings Management, rootless, docker desktop, hardened desktop
title: What is Settings Management? title: What is Settings Management?
--- ---
>**Note** >**Note**
> >
>Settings Management is available to Docker Business customers only. >Settings Management is available to Docker Business customers only.
Settings Management is a feature that helps admins to control certain Docker Desktop settings on client machines within their organization. Settings Management is a feature that helps admins to control certain Docker Desktop settings on client machines within their organization.
With a few lines of JSON, admins can configure controls for Docker Desktop settings such as proxies and network settings. For an extra layer of security, admins can also use Settings Management to enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/index.md) which ensures that any configurations set with Settings Management cannot be modified by containers. With a few lines of JSON, admins can configure controls for Docker Desktop settings such as proxies and network settings. For an extra layer of security, admins can also use Settings Management to enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/index.md) which ensures that any configurations set with Settings Management cannot be modified by containers.
It is available with [Docker Desktop 4.13.0 or later](../../release-notes.md). It is available with [Docker Desktop 4.13.0 or later](../../release-notes.md).
### Who is it for? ### Who is it for?
- For Organizations who wish to configure Docker Desktop to be within their organization's centralized control. - For Organizations who wish to configure Docker Desktop to be within their organization's centralized control.
- For Organizations who want to create a standardized Docker Desktop environment at scale. - For Organizations who want to create a standardized Docker Desktop environment at scale.
@ -21,7 +21,7 @@ It is available with [Docker Desktop 4.13.0 or later](../../release-notes.md).
### How does it work? ### 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 users 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 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).
@ -29,7 +29,7 @@ Values that are set to `locked: true` within the `admin-settings.json` override
Using the `admin-settings.json` file, admins can: Using the `admin-settings.json` file, admins can:
- Enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/index.md) (currently incompatible with WSL) - Enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/index.md)
- Configure HTTP proxies - Configure HTTP proxies
- Configure network settings - Configure network settings
- Configure Kubernetes settings - Configure Kubernetes settings
@ -49,7 +49,7 @@ Once this is done, Docker Desktop users receive the changed settings when they e
- Quit, re-launch, and sign in to Docker Desktop - Quit, re-launch, and sign in to Docker Desktop
- Launch and sign in to Docker Desktop for the first time - 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. 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 users see when the settings are enforced?