mirror of https://github.com/docker/docs.git
Hardened Desktop and Admin Controls (#15775)
* initial structure of ECI-DM draft layout * PR-FAQ additions * further PR-FAQ additions * edits, edits, edits * edits and fix broken link * added more known issues * incorporate review feedback * tweaks from feedback * review comments for hardened desktop landing page * review comments for the Admin Controls landing page * review comments for the ECI FAQ page * review comments for the AC Configure page * screenshot add * review round 2 changes * more tweaks * info from @ebriney * minor tweaks * consistency fixes and tweaks * remove trailing comma and add more WSL notes * customer zero feedback * review suggestions from Rodny and Cesar, and proxy section fix * review edits from Rodny and Docs team * bug bash 1 fixes * bug bash 1 fixes * changes from bug bash 2 * Further comments from Cesar * proxy change * tweaks and installer flag addition * typo fix * typo fix * Cesar's additions * fix broken links * final checks
This commit is contained in:
Allie Sadler
GitHub
parent
b7f86813ee
commit
173c903a9a
|
|
@ -1269,6 +1269,28 @@ manuals:
|
|||
title: Run Docker Desktop for Windows in a VM or VDI environment
|
||||
- path: /desktop/uninstall/
|
||||
title: Uninstall Docker Desktop
|
||||
- sectiontitle: Hardened Desktop
|
||||
section:
|
||||
- path: /desktop/hardened-desktop/
|
||||
title: Overview
|
||||
- sectiontitle: Settings Management
|
||||
section:
|
||||
- path: /desktop/hardened-desktop/settings-management/
|
||||
title: What is Settings Management?
|
||||
- path: /desktop/hardened-desktop/settings-management/configure/
|
||||
title: Configure Settings Management
|
||||
- sectiontitle: Enhanced Container Isolation
|
||||
section:
|
||||
- path: /desktop/hardened-desktop/enhanced-container-isolation/
|
||||
title: What is Enhanced Container Isolation?
|
||||
- path: /desktop/hardened-desktop/enhanced-container-isolation/how-eci-works/
|
||||
title: How does it work?
|
||||
- path: /desktop/hardened-desktop/enhanced-container-isolation/features-benefits/
|
||||
title: Key features and benefits
|
||||
- path: /desktop/hardened-desktop/enhanced-container-isolation/faq/
|
||||
title: FAQs and known issues
|
||||
- path: /desktop/hardened-desktop/registry-access-management/
|
||||
title: Registry Access Management
|
||||
- sectiontitle: Dev Environments (Beta)
|
||||
section:
|
||||
- path: /desktop/dev-environments/
|
||||
|
|
@ -1680,8 +1702,7 @@ manuals:
|
|||
title: System for Cross-domain Identity Management
|
||||
- path: /docker-hub/image-access-management/
|
||||
title: Image Access Management
|
||||
- path: /docker-hub/registry-access-management/
|
||||
title: Registry Access Management
|
||||
|
||||
|
||||
- sectiontitle: Security
|
||||
section:
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
|
|
@ -0,0 +1 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#677285"><g fill="none"><path d="M0 0h24v24H0V0z"/><path d="M0 0h24v24H0V0z" opacity=".87"/></g><path d="M18 8h-1V6c0-2.76-2.24-5-5-5S7 3.24 7 6v2H6c-1.1 0-2 .9-2 2v10c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V10c0-1.1-.9-2-2-2zm-6 9c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2zM9 8V6c0-1.66 1.34-3 3-3s3 1.34 3 3v2H9z"/></svg>
|
||||
|
After Width: | Height: | Size: 409 B |
|
|
@ -0,0 +1 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#677285"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M19 3H5c-1.1 0-2 .9-2 2v7c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm0 6h-3.14c-.47 0-.84.33-.97.78C14.53 11.04 13.35 12 12 12s-2.53-.96-2.89-2.22c-.13-.45-.5-.78-.97-.78H5V6c0-.55.45-1 1-1h12c.55 0 1 .45 1 1v3zm-3.13 7H20c.55 0 1 .45 1 1v2c0 1.1-.9 2-2 2H5c-1.1 0-2-.9-2-2v-2c0-.55.45-1 1-1h4.13c.47 0 .85.34.98.8.35 1.27 1.51 2.2 2.89 2.2s2.54-.93 2.89-2.2c.13-.46.51-.8.98-.8z"/></svg>
|
||||
|
After Width: | Height: | Size: 545 B |
|
|
@ -0,0 +1 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#677285"><path d="M11.19 1.36l-7 3.11C3.47 4.79 3 5.51 3 6.3V11c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V6.3c0-.79-.47-1.51-1.19-1.83l-7-3.11c-.51-.23-1.11-.23-1.62 0zM12 11.99h7c-.53 4.12-3.28 7.79-7 8.94V12H5V6.3l7-3.11v8.8z"/></svg>
|
||||
|
After Width: | Height: | Size: 332 B |
|
|
@ -0,0 +1,129 @@
|
|||
---
|
||||
title: FAQs and known issues
|
||||
description: FAQ for Enhanced Container Isolation
|
||||
keywords: enhanced container isolation, security, faq, sysbox
|
||||
toc_max: 2
|
||||
---
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#tab3">FAQs</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab4">Limitations and Known Issues</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="tab3" class="tab-pane fade in active" markdown="1">
|
||||
|
||||
#### Do I need to change the way I use Docker when Enhanced Container Isolation is enabled?
|
||||
|
||||
No, you can continue to use Docker as usual. Enhanced Container Isolation will be mostly transparent to you.
|
||||
|
||||
#### Do all container workloads work well with Enhanced Container Isolation?
|
||||
|
||||
Most container workloads do, a few do not (yet). For the few workloads that
|
||||
don't yet work with Enhanced Container Isolation, Docker will continue to improve the feature to reduce
|
||||
this to a minimum.
|
||||
|
||||
#### Can I run privileged containers with Enhanced Container Isolation?
|
||||
|
||||
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
|
||||
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
|
||||
containers securely. 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?
|
||||
|
||||
No. Privileged container workloads that wish to access global kernel resources, for example non-namespaced, 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?
|
||||
|
||||
Privileged containers are typically used to run advanced workloads in
|
||||
containers, for example Docker-in-Docker or Kubernetes-in-Docker, to
|
||||
perform kernel operations such as loading modules, or to access hardware
|
||||
devices.
|
||||
|
||||
Enhanced Container Isolation allows running advanced workloads, but denies the ability to perform
|
||||
kernel operations or access hardware devices.
|
||||
|
||||
#### Does Enhanced Container Isolation restrict bind mounts inside the container?
|
||||
|
||||
Yes, it restricts bind mounts of directories located in the Docker Desktop Linux
|
||||
VM into the container.
|
||||
|
||||
It does not restrict bind mounts of your host machine files into the container,
|
||||
as configured via Docker Desktop's **Settings** > **Resources** > **File Sharing**.
|
||||
|
||||
#### Does Enhanced Container Isolation protect all containers launched with Docker Desktop?
|
||||
|
||||
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.
|
||||
|
||||
#### Does Enhanced Container Isolation affect performance of containers?
|
||||
|
||||
Enhanced Container Isolation has very little impact on the performance of containers. The exception is
|
||||
for containers that perform lots of `mount` and `umount` system calls, as these
|
||||
are trapped and vetted by the Sysbox container runtime.
|
||||
|
||||
#### 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
|
||||
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
|
||||
container is created through the Sysbox runtime.
|
||||
|
||||
The reason `runc` is disallowed with Enhanced Container Isolation because it
|
||||
allows users to run as "true root" on the Docker Desktop Linux VM, thereby
|
||||
providing them with implicit control of the VM and the ability to modify the
|
||||
administrative configurations for Docker Desktop, for example.
|
||||
|
||||
#### How is ECI different from Docker Engine's userns-remap mode?
|
||||
|
||||
See [How does it work](how-eci-works.md#enhanced-container-isolation-vs-docker-userns-remap-mode).
|
||||
|
||||
#### How is ECI different from Rootless Docker?
|
||||
|
||||
See [How does it work](how-eci-works.md#enhanced-container-isolation-vs-rootless-docker)
|
||||
|
||||
<hr>
|
||||
</div>
|
||||
<div id="tab4" class="tab-pane fade" markdown="1">
|
||||
|
||||
#### Incompatibility with Windows Subsystem for Linux (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
|
||||
Kernel. As a result, to use Enhanced Container Isolation on Windows, you must
|
||||
configure Docker Desktop to use Hyper-V. This can be enforced using Admin
|
||||
Controls. For more information, see [Settings Management](../settings-management/index.md).
|
||||
|
||||
#### Docker build and buildx has some restrictions
|
||||
With ECI enabled, Docker build `--network=host` and Docker buildx entitlements
|
||||
(`network.host`, `security.insecure`) are not allowed. Builds that require
|
||||
these will not work properly.
|
||||
|
||||
#### Kubernetes pods are not yet protected
|
||||
Kubernetes pods are not yet protected by ECI. A malicious or privileged pod can
|
||||
compromise the Docker Desktop Linux VM and bypass security controls. We expect
|
||||
to improve on this in future versions of Docker Desktop.
|
||||
|
||||
#### Extension Containers are not yet protected
|
||||
Extension containers are also not yet protected by ECI. Ensure you extension
|
||||
containers come from trusted entities to avoid issues. We expect to improve on
|
||||
this in future versions of Docker Desktop.
|
||||
|
||||
#### Docker Desktop dev environments are not yet protected
|
||||
Containers launched by the Docker Desktop Dev Environments feature are not yet
|
||||
protected either. We expect to improve on this in future versions of Docker
|
||||
Desktop.
|
||||
|
||||
#### Use in production
|
||||
In general users should not experience differences between running a container
|
||||
in Docker Desktop with ECI enabled, which uses the Sysbox runtime, and running
|
||||
that same container in production, through the standard OCI `runc` runtime.
|
||||
|
||||
However in some cases, typically when running advanced or privileged workloads in
|
||||
containers, users may experience some differences. In particular, the container
|
||||
may run with ECI but not with `runc`, or vice-versa.
|
||||
|
||||
<hr>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -0,0 +1,289 @@
|
|||
---
|
||||
description: Instructions on how to set up enhanced container isolation
|
||||
title: Key features and benefits
|
||||
keywords: set up, enhanced container isolation, rootless, security
|
||||
---
|
||||
|
||||
### Linux User Namespace on all Containers
|
||||
|
||||
With Enhanced Container Isolation, all user containers leverage the [Linux user-namespace](https://man7.org/linux/man-pages/man7/user_namespaces.7.html)
|
||||
for extra isolation. This means that the root user in the container maps to an unprivileged
|
||||
user in the Docker Desktop Linux VM.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
$ docker run -it --rm --name=first alpine
|
||||
/ # cat /proc/self/uid_map
|
||||
0 100000 65536
|
||||
```
|
||||
|
||||
The output `0 100000 65536` is the signature of the Linux user-namespace. It
|
||||
means that the root user (0) in the container is mapped to unprivileged user
|
||||
100000 in the Docker Desktop Linux VM, and the mapping extends for a continuous
|
||||
range of 64K user IDs. The same applies to group IDs.
|
||||
|
||||
Each container gets an exclusive range of mappings, managed by Sysbox. For
|
||||
example, if a second container is launched the mapping range is different:
|
||||
|
||||
```
|
||||
$ docker run -it --rm --name=second alpine
|
||||
/ # cat /proc/self/uid_map
|
||||
0 165536 65536
|
||||
```
|
||||
|
||||
In contrast, without Enhanced Container Isolation, the container's root user is
|
||||
in fact root on the host (aka "true root") and this applies to all containers:
|
||||
|
||||
```
|
||||
$ docker run -it --rm alpine
|
||||
/ # cat /proc/self/uid_map
|
||||
0 0 4294967295
|
||||
```
|
||||
|
||||
By virtue of using the Linux user-namespace, Enhanced Container Isolation
|
||||
ensures the container processes never run as user ID 0 (true root) in the Linux
|
||||
VM. In fact they never run with any valid user-ID in the Linux VM. Thus, their
|
||||
Linux capabilities are constrained to resources within the container only,
|
||||
increasing isolation significantly compared to regular containers, both
|
||||
container-to-host and cross-container isolation.
|
||||
|
||||
### Privileged Containers Are Also Secured
|
||||
|
||||
Privileged containers `docker run --privileged ...` are insecure because they
|
||||
give the container full access to the Linux kernel. That is, the container runs
|
||||
as true root with all capabilities enabled, seccomp and AppArmor restrictions
|
||||
are disabled, all hardware devices are exposed, for example.
|
||||
|
||||
For organizations that wish to secure Docker Desktop on their developer's
|
||||
machines, privileged containers are problematic as they allow container
|
||||
workloads whether benign or malicious to gain control of the Linux kernel
|
||||
inside the Docker Desktop VM and thus modify security related settings, for example registry
|
||||
access management, and network proxies.
|
||||
|
||||
With Enhanced Container Isolation, privileged containers can no longer do this. The combination of the Linux user-namespace and other security techniques used
|
||||
by Sysbox ensures that processes inside a privileged container can only access
|
||||
resources assigned to the container.
|
||||
|
||||
> Note
|
||||
>
|
||||
> Enhanced Container Isolation does not prevent users from launching privileged
|
||||
> containers, but rather runs them securely by ensuring that they can only
|
||||
> modify resources associated with the container. Privileged workloads that
|
||||
> modify global kernel settings, for example loading a kernel module or changing BPF
|
||||
> settings will not work properly as they will receive "permission
|
||||
> denied" error when attempting such operations.
|
||||
|
||||
For example, Enhanced Container Isolation ensures privileged containers can't
|
||||
access Docker Desktop network settings in the Linux VM configured via Berkeley
|
||||
Packet Filters (BPF):
|
||||
|
||||
```
|
||||
$ docker run --privileged djs55/bpftool map show
|
||||
Error: can't get next map: Operation not permitted
|
||||
```
|
||||
|
||||
In contrast, without Enhanced Container Isolation, privileged containers
|
||||
can easily do this:
|
||||
|
||||
```
|
||||
$ docker run --privileged djs55/bpftool map show
|
||||
17: ringbuf name blocked_packets flags 0x0
|
||||
key 0B value 0B max_entries 16777216 memlock 0B
|
||||
18: hash name allowed_map flags 0x0
|
||||
key 4B value 4B max_entries 10000 memlock 81920B
|
||||
20: lpm_trie name allowed_trie flags 0x1
|
||||
key 8B value 8B max_entries 1024 memlock 16384B
|
||||
```
|
||||
|
||||
Note that some advanced container workloads require privileged containers, for
|
||||
example Docker-in-Docker, Kubernetes-in-Docker, etc. With Enhanced Container
|
||||
Isolation you can still run such workloads but do so much more securely than
|
||||
before.
|
||||
|
||||
### Containers can't share namespaces with the Linux VM
|
||||
|
||||
When Enhanced Container Isolation is enabled, containers can't share Linux
|
||||
namespaces with the host (e.g., pid, network, uts, etc.) as that essentially
|
||||
breaks isolation.
|
||||
|
||||
For example, sharing the pid namespace fails:
|
||||
|
||||
```
|
||||
$ docker run -it --rm --pid=host alpine
|
||||
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share namespaces [pid] with the host (because they use the linux user-namespace for isolation): unknown.
|
||||
```
|
||||
|
||||
Similarly sharing the network namespace fails:
|
||||
|
||||
```
|
||||
docker run -it --rm --network=host alpine
|
||||
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share a network namespace with the host (because they use the linux user-namespace for isolation): unknown.
|
||||
```
|
||||
|
||||
In addition, the `--userns=host` flag, used to disable the user-namespace on the
|
||||
container, is ignored:
|
||||
|
||||
```
|
||||
$ docker run -it --rm --userns=host alpine
|
||||
/ # cat /proc/self/uid_map
|
||||
0 100000 65536
|
||||
```
|
||||
|
||||
Finally, Docker build `--network=host` and Docker buildx entitlements
|
||||
(`network.host`, `security.insecure`) are not allowed. Builds that require these
|
||||
won't work properly.
|
||||
|
||||
### Bind mount restrictions
|
||||
|
||||
When Enhanced Container Isolation is enabled, Docker Desktop users can continue
|
||||
to bind mount host directories into containers as configured via **Settings** >
|
||||
**Resources** > **File sharing**, but they are no longer allowed to bind mount
|
||||
arbitrary Linux VM directories into containers.
|
||||
|
||||
This prevents containers from modifying sensitive files inside the Docker
|
||||
Desktop Linux VM, files that can hold configurations for registry access
|
||||
management, proxies, docker engine configurations, and more.
|
||||
|
||||
For example, the following bind mount of the Docker Engine's configuration file
|
||||
(`/etc/docker/daemon.json` inside the Linux VM) into a container is restricted
|
||||
and therefore fails:
|
||||
|
||||
```
|
||||
$ docker run -it --rm -v /etc/docker/daemon.json:/mnt/daemon.json alpine
|
||||
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: can't mount /etc/docker/daemon.json because it's configured as a restricted host mount: unknown
|
||||
```
|
||||
|
||||
In contrast, without Enhanced Container Isolation this mount works and gives the
|
||||
container full read and write access to the Docker Engine's configuration.
|
||||
|
||||
Of course, bind mounts of host files continue to work as usual. For example,
|
||||
assuming a user configures Docker Desktop to file share her $HOME directory,
|
||||
she can bind mount it into the container:
|
||||
|
||||
```
|
||||
$ docker run -it --rm -v $HOME:/mnt alpine
|
||||
/ #
|
||||
```
|
||||
|
||||
> Note
|
||||
>
|
||||
> Enhanced Container Isolation won't allow bind mounting the Docker socket
|
||||
> (/var/run/docker.sock) into a container, as doing so essentially grants the
|
||||
> container control of Docker, thus breaking container isolation. Containers
|
||||
> that rely on this will not work with Enhanced Container Isolation enabled.
|
||||
|
||||
### Vetting sensitive system calls
|
||||
|
||||
Another feature of Enhanced Container Isolation is that it intercepts and vets a
|
||||
few highly sensitive system calls inside containers, such as `mount` and
|
||||
`umount`. This ensures that processes that have capabilities to execute these
|
||||
system calls can't use them to breach the container.
|
||||
|
||||
For example, a container that has `CAP_SYS_ADMIN` (required to execute the
|
||||
`mount` system call) can't use that capability to change a read-only bind mount
|
||||
into a read-write mount:
|
||||
|
||||
```
|
||||
$ docker run -it --rm --cap-add SYS_ADMIN -v $HOME:/mnt:ro alpine
|
||||
/ # mount -o remount,rw /mnt /mnt
|
||||
mount: permission denied (are you root?)
|
||||
```
|
||||
|
||||
Since the `$HOME` directory was mounted into the container's `/mnt` directory as
|
||||
read-only, it can't be changed from within the container to read-write. This
|
||||
ensures container processes use `mount`, or `umount`, to breach the container's
|
||||
root filesystem.
|
||||
|
||||
Note however that in the example above the container can still create mounts
|
||||
within the container, and mount them read-only or read-write as needed. Those
|
||||
mounts are allowed since they occur within the container, and therefore don't
|
||||
breach it's root filesystem:
|
||||
|
||||
```
|
||||
/ # mkdir /root/tmpfs
|
||||
/ # mount -t tmpfs tmpfs /root/tmpfs
|
||||
/ # mount -o remount,ro /root/tmpfs /root/tmpfs
|
||||
|
||||
/ # findmnt | grep tmpfs
|
||||
├─/root/tmpfs tmpfs tmpfs ro,relatime,uid=100000,gid=100000
|
||||
|
||||
/ # mount -o remount,rw /root/tmpfs /root/tmpfs
|
||||
/ # findmnt | grep tmpfs
|
||||
├─/root/tmpfs tmpfs tmpfs rw,relatime,uid=100000,gid=100000
|
||||
```
|
||||
|
||||
This feature, together with the user-namespace, ensures that even if a container
|
||||
process has all Linux capabilities they can't be used to breach the container.
|
||||
|
||||
Finally, Enhanced Container Isolation does system call vetting in such a way
|
||||
that it does not affect the performance of containers in the great majority of
|
||||
cases. It intercepts control-path system calls that are rarely used in most
|
||||
container workloads but data-path system calls are not intercepted.
|
||||
|
||||
### Filesystem user-ID mappings
|
||||
|
||||
As mentioned above, Enhanced Container Isolation enables the Linux
|
||||
user-namespace on all containers and this ensures that the container's user-ID
|
||||
range (0->64K) maps to an unprivileged range of "real" user-IDs in the Docker
|
||||
Desktop Linux VM (e.g., 100000->165535).
|
||||
|
||||
Moreover, each container gets an exclusive range of real user-IDs in the Linux
|
||||
VM (e.g., container 0 could get mapped to 100000->165535, container 2 to
|
||||
165536->231071, container 3 to 231072->296607, and so on). Same applies to
|
||||
group-IDs. In addition, if a container is stopped and restarted, there is no
|
||||
guarantee it will receive the same mapping as before. This by design and further
|
||||
improves security.
|
||||
|
||||
However the above presents a problem when mounting Docker volumes into
|
||||
containers, as the files written to such volumes will have the real
|
||||
user/group-IDs and will therefore won't be accessible across a container's
|
||||
start/stop/restart, or between containers due to the different real
|
||||
user-ID/group-ID of each container.
|
||||
|
||||
To solve this problem, Sysbox uses "filesystem user-ID remapping" via the Linux
|
||||
Kernel's ID-mapped mounts feature (added in 2021) or an alternative module
|
||||
called shiftfs. These technologies map filesystem accesses from the container's
|
||||
real user-ID (e.g., range 100000->165535) to the range (0->65535) inside Docker
|
||||
Desktop's Linux VM. This way, volumes can now be mounted or shared across
|
||||
containers, even if each container uses an exclusive range of user-IDs. Users
|
||||
need not worry about the container's real user-IDs.
|
||||
|
||||
Note that although filesystem user-ID remapping may cause containers to access
|
||||
Linux VM files mounted into the container with real user-ID 0 (i.e., root), the
|
||||
[restricted mounts feature](#bind-mount-restrictions) described above ensures
|
||||
that no Linux VM sensitive files can be mounted into the container.
|
||||
|
||||
### Procfs & Sysfs Emulation
|
||||
|
||||
Another feature of Enhanced Container Isolation is that inside each container,
|
||||
the procfs ("/proc") and sysfs ("/sys") filesystems are partially emulated. This
|
||||
serves several purposes, such as hiding sensitive host information inside the
|
||||
container and namespacing host kernel resources that are not yet namespaced by
|
||||
the Linux kernel itself.
|
||||
|
||||
As a simple example, when Enhanced Container Isolation is enabled the
|
||||
`/proc/uptime` file shows the uptime of the container itself, not that of the
|
||||
Docker Desktop Linux VM:
|
||||
|
||||
```
|
||||
$ docker run -it --rm alpine
|
||||
/ # cat /proc/uptime
|
||||
5.86 5.86
|
||||
```
|
||||
|
||||
In contrast, without Enhanced Container Isolation you see the uptime of
|
||||
the Docker Desktop Linux VM. Though this is a trivial example, it shows how
|
||||
Enhanced Container Isolation aims to prevent the Linux VM's configuration and
|
||||
information from leaking into the container so as to make it more difficult to
|
||||
breach the VM.
|
||||
|
||||
In addition several other resources under `/proc/sys` that are not namespaced by
|
||||
the Linux Kernel are also emulated inside the container. Each container
|
||||
sees a separate view of each such resource and Sysbox reconciles the values
|
||||
across the containers when programming the corresponding Linux kernel setting.
|
||||
|
||||
This has the advantage of enabling container workloads that would otherwise
|
||||
require truly privileged containers to access such non-namespaced kernel
|
||||
resources to run with Enhanced Container Isolation enabled, thereby improving
|
||||
security.
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
---
|
||||
description: Instructions on how to set up enhanced container isolation
|
||||
title: How does it work?
|
||||
keywords: set up, enhanced container isolation, rootless, security
|
||||
---
|
||||
|
||||
>**Note**
|
||||
>
|
||||
>Enhance Container Isolation is available to Docker Business customers only.
|
||||
|
||||
Enhanced Container Isolation hardens container isolation using the [Sysbox
|
||||
container runtime](https://github.com/nestybox/sysbox). Sysbox is a fork of the
|
||||
standard OCI runc runtime that was modified to enhance container isolation and
|
||||
workloads. For more details see [Under the covers](#under-the-hood).
|
||||
|
||||
Starting with version 4.13, Docker Desktop includes a customized version of
|
||||
Sysbox.
|
||||
|
||||
When [Enhanced Container Isolation is enabled](index.md#how-do-i-enable-enhanced-container-isolation), containers
|
||||
created by users through `docker run` or `docker create` are automatically
|
||||
launched using Sysbox instead of the standard OCI runc runtime. Users need not
|
||||
do anything else and can continue to use containers as usual. For exceptions,
|
||||
see [FAQs and known issues](faq.md).
|
||||
|
||||
Even containers that use the insecure `--privileged` flag can now be run
|
||||
securely with Enhanced Container Isolation, such that they can no longer be used
|
||||
to breach the Docker Desktop Virtual Machine (VM) or other containers.
|
||||
|
||||
>Note
|
||||
>
|
||||
> When Enhanced Container Isolation is enabled in Docker Desktop, the Docker CLI
|
||||
> "--runtime" flag is ignored. Docker's default runtime continues to be "runc",
|
||||
> but all user containers are implicitly launched with Sysbox.
|
||||
|
||||
Enhanced Container Isolation is not the same as Docker Engine's userns-remap
|
||||
mode or Rootless Docker. This is explained further below.
|
||||
|
||||
### Under the hood
|
||||
|
||||
Sysbox enhances container isolation by using techniques such as:
|
||||
|
||||
* Enabling the Linux user-namespace on all containers (root user in the container maps to an unprivileged user in the Linux VM).
|
||||
* Restricting the container from mounting sensitive VM directories.
|
||||
* Vetting sensitive system-calls between the container and the Linux kernel.
|
||||
* Mapping filesystem user/group IDs between the container's user-namespace and the Linux VM.
|
||||
* Emulating portions of the procfs and sysfs filesystems inside the container.
|
||||
|
||||
Some of these are made possible by recent advances in the Linux kernel which
|
||||
Docker Desktop now incorporates. Sysbox applies these techniques with minimal
|
||||
functional or performance impact to containers.
|
||||
|
||||
These techniques complement Docker's traditional container security mechanisms
|
||||
such as using other Linux namespaces, cgroups, restricted Linux capabilities,
|
||||
seccomp, and AppArmor. They add a strong layer of isolation between the
|
||||
container and the Linux kernel inside the Docker Desktop VM.
|
||||
|
||||
For more information, see [Key features and benefits](features-benefits.md).
|
||||
|
||||
### Enhanced Container Isolation vs Docker Userns-Remap Mode
|
||||
|
||||
The Docker Engine includes a feature called [userns-remap mode](/engine/security/userns-remap/)
|
||||
that enables the user-namespace in all containers. However it suffers from a few
|
||||
[limitations](/engine/security/userns-remap/) and it's
|
||||
not supported within Docker Desktop.
|
||||
|
||||
Userns-remap mode is similar to Enhanced Container Isolation in that both improve
|
||||
container isolation by leveraging the Linux user-namespace.
|
||||
|
||||
However, Enhanced Container Isolation is much more advanced since it assigns
|
||||
exclusive user-namespace mappings per container automatically and add several
|
||||
other [container isolation features](#under-the-hood) meant to secure Docker
|
||||
Desktop in organizations with stringent security requirements.
|
||||
|
||||
### Enhanced Container Isolation vs Rootless Docker
|
||||
|
||||
[Rootless Docker](/engine/security/rootless/) allows the Docker Engine, and by
|
||||
extension the containers, to run without root privileges natively a Linux host. This
|
||||
allows non-root users install and run Docker natively on Linux.
|
||||
|
||||
Rootless Docker is not supported within Docker Desktop. While it's a valuable
|
||||
feature when running Docker natively on Linux, its value within Docker Desktop
|
||||
is reduced since Docker Desktop runs the Docker Engine within a Linux VM. That
|
||||
is, Docker Desktop already allows non-root host users to run Docker and
|
||||
isolates the Docker Engine from the host using a virtual machine.
|
||||
|
||||
Unlike Rootless Docker, Enhanced Container Isolation does not run Docker Engine
|
||||
within a Linux user-namespace. Rather it runs the containers generated by that
|
||||
engine within a user-namespace. This has the advantage of bypassing [the
|
||||
limitations](/engine/security/rootless/#known-limitations) of Rootless Docker
|
||||
and creates a stronger boundary between the containers and the Docker Engine.
|
||||
|
||||
Enhanced Container Isolation is meant to ensure containers launched with Docker
|
||||
Desktop can't easily breach the Docker Desktop Linux VM and therefore modify
|
||||
security settings within it.
|
||||
|
|
@ -0,0 +1,118 @@
|
|||
---
|
||||
description: Enhanced Container Isolation - benefits, why use it, how it differs to Docker rootless, who it is for
|
||||
keywords: containers, rootless, security, sysbox, runtime
|
||||
title: What is Enhanced Container Isolation?
|
||||
---
|
||||
|
||||
>**Note**
|
||||
>
|
||||
>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).
|
||||
|
||||
These techniques include:
|
||||
- Running all containers unprivileged through the Linux user-namespace.
|
||||
- Restricting containers from modifying Docker Desktop VM settings.
|
||||
- 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.
|
||||
|
||||
This is done automatically and with minimal functional or performance impact.
|
||||
|
||||
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).
|
||||
|
||||
>**Note**
|
||||
>
|
||||
> Enhanced Container Isolation is in addition to other container security techniques used by Docker. For example, reduced Linux Capabilities, Seccomp, AppArmor.
|
||||
|
||||
### Who is it for?
|
||||
|
||||
- For organizations that want to prevent container attacks and reduce vulnerabilities.
|
||||
- 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?
|
||||
|
||||
When Enhanced Container Isolation is enabled using [Settings Management](../settings-management/index.md), the following features are enabled:
|
||||
|
||||
- All user containers are automatically run in Linux User Namespaces which ensures stronger isolation.
|
||||
- The root user in the container maps to an unprivileged user at VM level.
|
||||
- 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.
|
||||
|
||||
For more information on how Enhanced Container Isolation work, see [How does it work](how-eci-works.md).
|
||||
|
||||
>**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).
|
||||
{: .important}
|
||||
|
||||
### How do I 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.
|
||||
|
||||
Next, you must [create and configure the `admin-settings.json` file](../settings-management/configure.md) and specify:
|
||||
|
||||
```JSON
|
||||
{
|
||||
"configurationFileVersion": 2,
|
||||
"enhancedContainerIsolation": {
|
||||
"value": true,
|
||||
"locked": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For this 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 relaunch Docker Desktop. If they are already signed in, they don’t need to sign in again for the changes to take effect.
|
||||
|
||||
>Important
|
||||
>
|
||||
>Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop.
|
||||
{: .important}
|
||||
|
||||
### What do users see when this setting is enforced?
|
||||
|
||||
When Enhanced Container Isolation is enabled, users see that containers run within a Linux user namespace.
|
||||
|
||||
To check, run:
|
||||
|
||||
```
|
||||
$ docker run -it --rm alpine / # cat /proc/self/uid_map
|
||||
```
|
||||
|
||||
The following output displays:
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
In contrast, without Enhanced Container Isolation the Linux user namespace is not used, the following displays:
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
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`:
|
||||
|
||||
```
|
||||
docker inspect --format='{{.HostConfig.Runtime}}' my_container
|
||||
```
|
||||
|
||||
It outputs:
|
||||
|
||||
```
|
||||
sysbox-runc
|
||||
```
|
||||
|
||||
Without Enhanced Container Isolation, `docker inspect` outputs `runc`, which is the standard OCI runtime.
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
title: Hardened Desktop
|
||||
description: Overview of what Hardened Desktop is
|
||||
keywords: security, hardened desktop, enhanced container isolation, registry access management, admin controls, root access, admins, docker desktop
|
||||
---
|
||||
>Note
|
||||
>
|
||||
>Hardened Desktop is available to Docker Business customers only.
|
||||
|
||||
Hardened 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.
|
||||
|
||||
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 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 Desktop includes:
|
||||
- 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.
|
||||
- Registry Access Management, which allows admins to control the registries developers can access.
|
||||
|
||||
Docker plans to continue adding more security enhancements to the Hardened Desktop security model.
|
||||
|
||||
<div class="component-container">
|
||||
<!--start row-->
|
||||
<div class="row">
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<a href="/desktop/hardened-desktop/settings-management/"><img src="/assets/images/lock.svg" alt="Hardened Desktop" width="70" height="70"></a>
|
||||
</div>
|
||||
<h2 id="hardened-desktop"><a href="/desktop/hardened-desktop/settings-management/">Settings Management </a></h2>
|
||||
<p>Learn how Settings Management can secure your developers' workflows.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<a href="/desktop/hardened-desktop/enhanced-container-isolation"><img src="/assets/images/secure.svg" alt="Release notes" width="70" height="70"></a>
|
||||
</div>
|
||||
<h2 id="hardened-desktop"><a href="/desktop/hardened-desktop/enhanced-container-isolation">Enhanced Container Isolation</a></h2>
|
||||
<p>Understand how Enhanced Container Isolation can prevent container attacks. </p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<a href="/desktop/hardened-desktop/registry-access-management/"><img src="/assets/images/registry.svg" alt="Hardened Desktop" width="70" height="70"></a>
|
||||
</div>
|
||||
<h2 id="hardened-desktop"><a href="/desktop/hardened-desktop/registry-access-management/">Registry Access Management</a></h2>
|
||||
<p>Control the registries developers can access while using Docker Desktop.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
description: Registry Access Management
|
||||
keywords: registry, access, managment
|
||||
title: Registry Access Management
|
||||
redirect_from:
|
||||
- /docker-hub/registry-access-management/
|
||||
---
|
||||
|
||||
>Note
|
||||
>
|
||||
>Registry Access Management is available to Docker Business customers only.
|
||||
|
||||
With Registry Access Management, administrators can ensure that their developers using Docker Desktop only access registries that are allowed. This is done through the Registry Access Management dashboard on Docker Hub.
|
||||
|
||||
Below are some example registries administrators can allow:
|
||||
- Docker Hub. This is enabled by default.
|
||||
- Amazon ECR
|
||||
- GitHub Container Registry
|
||||
- Google Container Registry
|
||||
|
||||
Administrators can ensure registries are locked in and cannot be edited by developers, if Enhanced Container Isolation is switched on. To learn more, see [Enhanced Container Isolation](enhanced-container-isolation/index.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You need to [configure a registry.json to enforce sign-in](../../docker-hub/configure-sign-in.md). For Registry Access Management to take effect, Docker Desktop users must authenticate to your organization.
|
||||
|
||||
## Configure Registry Access Management permissions
|
||||
|
||||
To configure Registry Access Management permissions:
|
||||
|
||||
1. Sign in to your [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"} account as an organization owner.
|
||||
2. Select an organization and then navigate to the **Settings** tab on the **Organizations** page and select **Registry Access**.
|
||||
3. Toggle on Registry Access Management to set the permissions for your registry.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> When enabled, the Docker Hub registry is set by default, however you can also restrict this registry for your developers.
|
||||
|
||||
4. To add registries to your list, select **Add** and enter your registry details in the applicable fields, then select **Create**.
|
||||
5. Verify that the registry appears in your list and select **Save & Apply**. You can verify that your changes are saved in the **Activity** tab. There is no limit on the number of registries you can add.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Once you add a registry, it takes up to 24 hours for the changes to be enforced on your developers’ machines. If you want to apply the changes sooner, you must force a Docker logout on your developers’ machine and have the developers re-authenticate for Docker Desktop.
|
||||
|
||||
{:width="700px"}
|
||||
|
||||
## Verify the restrictions
|
||||
|
||||
The new Registry Access Management policy takes effect after the developer successfully authenticates to Docker Desktop using their organization credentials. If a developer attempts to pull an image from a disallowed registry via the Docker CLI, they receive an error message that the organization has disallowed this registry.
|
||||
|
||||
## Known issues
|
||||
|
||||
There are certain limitations when using Registry Access Management:
|
||||
|
||||
- Windows image pulls, and image builds are not restricted
|
||||
- Builds such as `docker buildx` using a Kubernetes driver are not restricted
|
||||
- Builds such as `docker buildx` using a custom docker-container driver are not restricted
|
||||
- Blocking is DNS-based; you must use a registry's access control mechanisms to distinguish between “push” and “pull”
|
||||
- WSL 2 requires at least a 5.4 series Linux kernel (this does not apply to earlier Linux kernel series)
|
||||
- Under the WSL 2 network, traffic from all Linux distributions is restricted (this will be resolved in the updated 5.15 series Linux kernel)
|
||||
|
||||
Also, Registry Access Management operates on the level of hosts, not IP addresses. Developers can bypass this restriction within their domain resolution, for example by running Docker against a local proxy or modifying their operating system's `sts` file. Docker Desktop does not support blocking these forms of manipulation.
|
||||
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
description: settings management for desktop
|
||||
keywords: admin, controls, rootless, enhanced container isolation
|
||||
title: Configure Settings Management
|
||||
---
|
||||
|
||||
>**Note**
|
||||
>
|
||||
>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.
|
||||
|
||||
Settings Management is designed specifically for organizations who don’t give developers root access to their machines.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Download and install Docker Desktop 4.13.0 or later](../../release-notes.md).
|
||||
- As an admin, you need to [configure a registry.json to enforce sign-in](../../../docker-hub/configure-sign-in.md). This is because this feature requires a Docker Business subscription and therefore your Docker Desktop users must authenticate to your organization for this configuration to take effect.
|
||||
|
||||
### 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.
|
||||
|
||||
To set it up manually:
|
||||
1. Create a new, empty JSON file and name it `admin-settings`.
|
||||
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 the above protected directories, end users are unable to modify it.
|
||||
|
||||
>**Note**
|
||||
>
|
||||
> It is assumed that you have the ability to push the `admin-settings.json` settings file to the locations specified above through a device management software such as [Jamf](https://www.jamf.com/lp/en-gb/apple-mobile-device-management-mdm-jamf-shared/?attr=google_ads-brand-search-shared&gclid=CjwKCAjw1ICZBhAzEiwAFfvFhEXjayUAi8FHHv1JJitFPb47C_q_RCySTmF86twF1qJc_6GST-YDmhoCuJsQAvD_BwE).
|
||||
|
||||
### Step two: Configure the settings you want to lock in
|
||||
|
||||
>**Note**
|
||||
>
|
||||
>Some of the configuration parameters only apply to Windows. This is highlighted in the table below.
|
||||
|
||||
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 UI, 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.json` or `daemon.json`. In these instances, the user's preferences are respected and we don't alter these values. These can be controlled by the admin 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"configurationFileVersion": 2,
|
||||
"exposeDockerAPIOnTCP2375": {
|
||||
"locked": true,
|
||||
"value": false
|
||||
},
|
||||
"proxy": {
|
||||
"locked": true,
|
||||
"mode": "system",
|
||||
"http": "",
|
||||
"https": "",
|
||||
"exclude": []
|
||||
},
|
||||
"enhancedContainerIsolation": {
|
||||
"locked": true,
|
||||
"value": true
|
||||
},
|
||||
"linuxVM": {
|
||||
"wslEngineEnabled": {
|
||||
"locked": false,
|
||||
"value": false
|
||||
},
|
||||
"dockerDaemonOptions": {
|
||||
"locked": false,
|
||||
"value":"{\"debug\": false}"
|
||||
},
|
||||
"vpnkitCIDR": {
|
||||
"locked": false,
|
||||
"value":"192.168.65.0/24"
|
||||
}
|
||||
},
|
||||
"windowsContainers": {
|
||||
"dockerDaemonOptions": {
|
||||
"locked": false,
|
||||
"value":"{\"debug\": false}"
|
||||
}
|
||||
},
|
||||
"disableUpdate": {
|
||||
"locked": false,
|
||||
"value": false
|
||||
},
|
||||
"analyticsEnabled": {
|
||||
"locked": false,
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Parameter | | Description |
|
||||
| :------------------------------- |---| :------------------------------- |
|
||||
| `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.|
|
||||
| `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). |
|
||||
| `linuxVM` | |Parameters and settings related to Linux VM options - grouped together here for convenience. |
|
||||
| `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.|
|
||||
| `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. |
|
||||
| `vpnkitCIDR` | |Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal` |
|
||||
| `windowsContainers` | | Parameters and settings related to `windowsContainers` options - grouped together here for convenience. |
|
||||
| `dockerDaemonOptions` | | Overrides the options in the linux daemon config file. See the [Docker Engine reference](/engine/reference/commandline/dockerd/#daemon-configuration-file).| |
|
||||
|`disableUpdate`| |If `value` is set to true, checking for and notifications about Docker Desktop updates is disabled.|
|
||||
|`analyticsEnabled`| |If `value` is set to false, Docker Desktop doesn't send usage statistics to Docker. |
|
||||
|
||||
### Step three: Re-launch Docker Desktop
|
||||
>**Note**
|
||||
>
|
||||
>Administrators should 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 relaunch Docker Desktop. If they are already signed in, they don't need to sign in again for the changes to take effect.
|
||||
>**Important**
|
||||
>
|
||||
>Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop.
|
||||
{: .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.
|
||||
|
||||
|
||||
In Docker Desktop, developers see the relevant settings grayed out and the message **Locked by your administrator**.
|
||||
|
||||
{:width="750px"}
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
description: Settings Management for desktop
|
||||
keywords: Settings Management, rootless, docker desktop, hardened desktop
|
||||
title: What is Settings Management?
|
||||
---
|
||||
>**Note**
|
||||
>
|
||||
>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.
|
||||
|
||||
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 [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).
|
||||
|
||||
### Who is it for?
|
||||
|
||||
- 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 Docker Business customers who want to confidently manage their use of Docker Desktop within tightly regulated environments.
|
||||
|
||||
### 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.
|
||||
|
||||
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).
|
||||
|
||||
### What features can I configure with Settings Management?
|
||||
|
||||
Using the `admin-settings.json` file, admins can:
|
||||
|
||||
- Enable [Enhanced Container Isolation](../enhanced-container-isolation/index.md) (currently incompatible with WSL)
|
||||
- Configure HTTP proxies
|
||||
- Configure network settings
|
||||
- Enforce the use of WSL2 based engine or Hyper-V
|
||||
- Configure Docker Engine
|
||||
- Turn off Docker Desktop's ability to checks for updates
|
||||
- Turn off Docker Desktop's ability to send usage statistics
|
||||
|
||||
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](../../../docker-hub/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.
|
||||
|
||||
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:
|
||||
- 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?
|
||||
|
||||
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.
|
||||
|
||||
{:width="750px"}
|
||||
|
|
@ -100,6 +100,10 @@ The `install` command accepts the following flags:
|
|||
- `--accept-license`: accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement){: target="_blank" rel="noopener" class="_"} now, rather than requiring it to be accepted when the application is first run
|
||||
- `--allowed-org=<org name>`: requires the user to sign in and be part of the specified Docker Hub organization when running the application
|
||||
- `--user=<username>`: Runs the privileged helper service once during installation, then disables it at runtime. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](../mac/permission-requirements.md#permission-requirements){: target="_blank" rel="noopener" class="_"}. To find the username, enter `ls /Users` in the CLI.
|
||||
- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](../hardened-desktop/settings-management/index.md).
|
||||
- It must be used together with the `--allowed-org=<org name>` flag.
|
||||
- For example:
|
||||
`--allowed-org=<org name> --admin-settings='{"configurationFileVersion": 2, "enhancedContainerIsolation": {"value": true, "locked": false}}'`
|
||||
|
||||
## Where to go next
|
||||
|
||||
|
|
|
|||
|
|
@ -158,6 +158,10 @@ The install command accepts the following flags:
|
|||
- `--no-windows-containers`: disables Windows containers integration
|
||||
- `--allowed-org=<org name>`: requires the user to sign in and be part of the specified Docker Hub organization when running the application
|
||||
- `--backend=<backend name>`: selects the default backend to use for Docker Desktop, `hyper-v`, `windows` or `wsl-2` (default)
|
||||
- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](../hardened-desktop/settings-management/index.md).
|
||||
- It must be used together with the `--allowed-org=<org name>` flag.
|
||||
- For example:
|
||||
`--allowed-org=<org name> --admin-settings='{"configurationFileVersion": 2, "enhancedContainerIsolation": {"value": true, "locked": false}}'`
|
||||
|
||||
If your admin account is different to your user account, you must add the user to the **docker-users** group:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue