Skip to content

ENGDOCS-2305 #21397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 13, 2024
Merged

ENGDOCS-2305 #21397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9d67727
ENGDOCS-2305
aevesdocker Nov 11, 2024
4d30c7a
formatting
aevesdocker Nov 12, 2024
ca99eb2
formatting
aevesdocker Nov 12, 2024
2381c7b
final formatting
aevesdocker Nov 12, 2024
130bfdb
Apply suggestions from code review
aevesdocker Nov 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions _vale/Docker/Acronyms.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ exceptions:
- DPI
- DSOS
- DVP
- ECI
- ELK
- FAQ
- FUSE
Expand Down Expand Up @@ -67,6 +68,7 @@ exceptions:
- NTLM
- NVDA
- OCI
- OS
- OSS
- PATH
- PDF
Expand Down
44 changes: 18 additions & 26 deletions content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,31 +9,29 @@
weight: 10
---

>**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 helps you control key Docker Desktop settings, like proxies and network configurations, on your developers' machines within your 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.
For an extra layer of security, you can also use Settings Management to enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/_index.md), which prevents containers from modifying any Settings Management configurations.

It is available with [Docker Desktop 4.13.0 and later](/manuals/desktop/release-notes.md).

### Who is it for?
## Who is it for?

- For organizations that want to configure Docker Desktop to be within their organization's centralized control.
- For organizations that 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?
## 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 developers with root or admin privileges.
You can configure several Docker Desktop settings using an `admin-settings.json` file. This file is located on the Docker Desktop host and can only be accessed by developers with root or administrator privileges.

Values that are set to `locked: true` within the `admin-settings.json` override any previous values set by developers and ensure that these cannot be modified. For more information, see [Configure Settings Management](configure.md#step-two-configure-the-settings-you-want-to-lock-in).

### What features can I configure with Settings Management?
## What features can I configure with Settings Management?

Using the `admin-settings.json` file, admins can:
Using the `admin-settings.json` file, you can:

- Turn on and lock in [Enhanced Container Isolation](../enhanced-container-isolation/_index.md)
- Configure HTTP proxies
Expand All @@ -50,33 +48,27 @@
- Control whether developers can use the Docker terminal
- Control the file sharing implementation for your developers on macOS
- Specify which paths your developers can add file shares to
- Configure Air-Gapped Containers

For more details on the syntax and options admins can set, see [Configure Settings Management](configure.md).
- Configure Air-gapped containers

### How do I set up and enforce Settings Management?
For more details on the syntax and options, see [Configure Settings Management](configure.md).

As an administrator, you first need to [enforce
sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). This is
because the Settings Management feature requires a Docker Business subscription
and therefore your Docker Desktop developers must authenticate to your
organization. Enforcing sign-in ensures that your Docker Desktop developers
always authenticate to your organization, even though they can authenticate
without it and the feature will take effect. Enforcing sign-in guarantees the
feature always takes effect.
## How do I set up and enforce Settings Management?

Check warning on line 55 in content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.HeadingLength] Try to keep headings short (< 8 words).

Raw Output:
{"message": "[Docker.HeadingLength] Try to keep headings short (\u003c 8 words).", "location": {"path": "content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md", "range": {"start": {"line": 55, "column": 4}}}, "severity": "INFO"}

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

Next, you must either manually [create and configure the admin-settings.json file](configure.md), or use the `--admin-settings` installer flag on [macOS](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/setup/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 developers receive the changed settings when they either:
- Quit, re-launch, and sign in to Docker Desktop
- Launch and sign in to Docker Desktop for the first time

Docker doesn't automatically mandate that developers re-launch and re-authenticate once a change has been made, so as not to disrupt your developers' workflow.
To avoid disrupting your developers' workflows, Docker doesn't automatically require that developers re-launch and re-authenticate once a change has been made.

## What do developers see when the settings are enforced?

Check warning on line 67 in content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.HeadingLength] Try to keep headings short (< 8 words).

Raw Output:
{"message": "[Docker.HeadingLength] Try to keep headings short (\u003c 8 words).", "location": {"path": "content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md", "range": {"start": {"line": 67, "column": 4}}}, "severity": "INFO"}

### What do developers see when the settings are enforced?
Enforced settings appear grayed out in Docker Desktop. They can't be edited via the Docker Desktop Dashboard, CLI, or `settings-store.json` (or `settings.json` for Docker Desktop 4.34 and earlier).

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-store.json` file (or `settings.json` for Docker Desktop versions 4.34 and earlier). In addition, if Enhanced Container Isolation is enforced, developers can't use privileged containers or similar techniques to modify enforced settings within the Docker Desktop Linux VM, for example, reconfigure proxy and networking of reconfigure Docker Engine.
In addition, if Enhanced Container Isolation is enforced, developers can't use privileged containers or similar techniques to modify enforced settings within the Docker Desktop Linux VM. For example, they can't reconfigure proxy and networking, or Docker Engine.

![Proxy settings grayed out](/assets/images/grayed-setting.png)

Expand Down
Loading