diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index 32f91f922ed..9c00192a109 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -339,14 +339,13 @@ Notifications appear briefly in the lower-right of the Docker Desktop Dashboard, ## Advanced (Mac only) -Reconfigure CLI tool installation paths and privileged system permissions set during initial install. +Reconfigure CLI tool installation paths and privileged system permissions. | Setting | Description | Notes | | ------------------- | ----------------------------------------- | ------------------------------------- | -| CLI tools installation — **System** | Install Docker CLI tools to `/usr/local/bin`. | | -| CLI tools installation — **User** | Install Docker CLI tools to `$HOME/.docker/bin` | Add `$HOME/.docker/bin` to your PATH by appending `export PATH=$PATH:~/.docker/bin` to `~/.bashrc` or `~/.zshrc`, then restart your shell. | +| CLI tools installation — **System** | Install Docker CLI tools to `/usr/local/bin`. | Requires password | +| CLI tools installation — **User** | Install Docker CLI tools to `$HOME/.docker/bin`. This is the default. | Automatically added to your PATH | | **Allow the default Docker socket to be used** | Creates `/var/run/docker.sock` which some third party clients may use to communicate with Docker Desktop. For more information, see [permission requirements for macOS](/manuals/desktop/setup/install/mac-permission-requirements.md#installing-symlinks). | Requires password | -| **Allow privileged port mapping** | Starts the privileged helper process which binds the ports that are between 1 and 1024. For more information, see [permission requirements for macOS](/manuals/desktop/setup/install/mac-permission-requirements.md#binding-privileged-ports). | Requires password | ## Docker Offload diff --git a/content/manuals/desktop/setup/install/mac-install.md b/content/manuals/desktop/setup/install/mac-install.md index 3c065841aa1..d87ed910b3f 100644 --- a/content/manuals/desktop/setup/install/mac-install.md +++ b/content/manuals/desktop/setup/install/mac-install.md @@ -99,7 +99,7 @@ This page provides download links, system requirements, and step-by-step install 6. From the installation window, select either: - **Use recommended settings (Requires password)**. This lets Docker Desktop automatically set the necessary configuration settings. - - **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping. See [Settings](/manuals/desktop/settings-and-maintenance/settings.md#advanced), for more information and how to set the location of the Docker CLI tools. + - **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, and enable the default Docker socket. See [Settings](/manuals/desktop/settings-and-maintenance/settings.md#advanced), for more information and how to set the location of the Docker CLI tools. 7. Select **Finish**. If you have applied any of the previous configurations that require a password in step 6, enter your password to confirm your choice. ### Install from the command line diff --git a/content/manuals/desktop/setup/install/mac-permission-requirements.md b/content/manuals/desktop/setup/install/mac-permission-requirements.md index 34bc7d7e2ff..24475eab84b 100644 --- a/content/manuals/desktop/setup/install/mac-permission-requirements.md +++ b/content/manuals/desktop/setup/install/mac-permission-requirements.md @@ -19,38 +19,27 @@ Docker Desktop on Mac is designed with security in mind. Administrative rights a Docker Desktop for Mac is run as an unprivileged user. However, Docker Desktop requires certain functionalities to perform a limited set of privileged configurations such as: - [Installing symlinks](#installing-symlinks) in`/usr/local/bin`. - - [Binding privileged ports](#binding-privileged-ports) that are less than 1024. Although privileged ports (ports below 1024) are not typically used as a security boundary, operating systems still prevent unprivileged processes from binding to them which breaks commands like `docker run -p 127.0.0.1:80:80 docker/getting-started`. - [Ensuring `localhost` and `kubernetes.docker.internal` are defined](#ensuring-localhost-and-kubernetesdockerinternal-are-defined) in `/etc/hosts`. Some old macOS installs don't have `localhost` in `/etc/hosts`, which causes Docker to fail. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers. - - Securely caching the Registry Access Management policy which is read-only for the developer. -Privileged access is granted during installation. +Privileged access, when needed, is granted through the **Advanced** page in **Settings**, rather than at install time. -The first time Docker Desktop for Mac launches, it presents an installation window where you can choose to either use the default settings, which work for most developers and requires you to grant privileged access, or use advanced settings. - -If you work in an environment with elevated security requirements, for instance where local administrative access is prohibited, then you can use the advanced settings to remove the need for granting privileged access. You can configure: +From the **Advanced** page, you can enable: - The location of the Docker CLI tools either in the system or user directory - The default Docker socket -- Privileged port mapping -Depending on which advanced settings you configure, you must enter your password to confirm. +If you work in an environment with elevated security requirements, for instance where local administrative access is prohibited, then you can leave these settings at their defaults to avoid granting privileged access. -You can change these configurations at a later date from the **Advanced** page in **Settings**. +Depending on which advanced settings you configure, you must enter your password to confirm. ### Installing symlinks -The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop creates symlinks for the binaries in `/usr/local/bin`, which means they're automatically included in `PATH` on most systems. - -You can choose whether to install symlinks either in `/usr/local/bin` or `$HOME/.docker/bin` during installation of Docker Desktop. +The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. By default, Docker Desktop creates symlinks for the binaries in `$HOME/.docker/bin`, which is automatically added to your terminal's `PATH`. -If `/usr/local/bin` is chosen, and this location is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created in `/usr/local/bin`. If `$HOME/.docker/bin` is chosen, authorization is not required, but then you must [manually add `$HOME/.docker/bin`](/manuals/desktop/settings-and-maintenance/settings.md#advanced) to your PATH. +You can change the symlink location to `/usr/local/bin` from the **Advanced** page in **Settings**. If `/usr/local/bin` is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created there. -You are also given the option to enable the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various Docker clients relying on the default Docker socket path work without additional changes. +You are also given the option to enable the installation of the `/var/run/docker.sock` symlink from the **Advanced** page in **Settings**. Creating this symlink ensures various Docker clients relying on the default Docker socket path work without additional changes. -As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to the Docker socket included. To ensure the Docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users//.docker/run/docker.sock /var/run/docker.sock`. This ensures the you aren't prompted on each startup to create the symlink. If you don't enable this option at installation, the symlink and the startup task is not created and you may have to explicitly set the `DOCKER_HOST` environment variable to `/Users//.docker/run/docker.sock` in the clients it is using. The Docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup. - -### Binding privileged ports - -You can choose to enable privileged port mapping during installation, or from the **Advanced** page in **Settings** post-installation. Docker Desktop requires authorization to confirm this choice. +As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to the Docker socket included. To ensure the Docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users//.docker/run/docker.sock /var/run/docker.sock`. This ensures the you aren't prompted on each startup to create the symlink. If you don't enable this option, the symlink and the startup task is not created and you may have to explicitly set the `DOCKER_HOST` environment variable to `/Users//.docker/run/docker.sock` in the clients it is using. The Docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup. ### Ensuring `localhost` and `kubernetes.docker.internal` are defined @@ -65,41 +54,15 @@ Privileged configurations are applied during the installation with the `--user` The limitation of this approach is that Docker Desktop can only be run by one user-account per machine, namely the one specified in the `-–user` flag. -## Privileged helper - -In the limited situations when the privileged helper is needed, for example binding privileged ports or caching the Registry Access Management policy, the privileged helper is started by `launchd` and runs in the background unless it is disabled at runtime as previously described. The Docker Desktop backend communicates with the privileged helper over the UNIX domain socket `/var/run/com.docker.vmnetd.sock`. The functionalities it performs are: -- Binding privileged ports that are less than 1024. -- Securely caching the Registry Access Management policy which is read-only for the developer. -- Uninstalling the privileged helper. - -The removal of the privileged helper process is done in the same way as removing `launchd` processes. - -```console -$ ps aux | grep vmnetd -root 28739 0.0 0.0 34859128 228 ?? Ss 6:03PM 0:00.06 /Library/PrivilegedHelperTools/com.docker.vmnetd -user 32222 0.0 0.0 34122828 808 s000 R+ 12:55PM 0:00.00 grep vmnetd - -$ sudo launchctl unload -w /Library/LaunchDaemons/com.docker.vmnetd.plist -Password: - -$ ps aux | grep vmnetd -user 32242 0.0 0.0 34122828 716 s000 R+ 12:55PM 0:00.00 grep vmnetd - -$ rm /Library/LaunchDaemons/com.docker.vmnetd.plist - -$ rm /Library/PrivilegedHelperTools/com.docker.vmnetd -``` - ## Backend helper socket -Aside from the optional [privileged helper](#privileged-helper), the Docker -Desktop backend process (`com.docker.backend`) uses an internal helper socket +The Docker Desktop backend process (`com.docker.backend`) uses an internal helper socket (`~/Library/Containers/com.docker.docker/Data/forkexecd.sock`) to fork and execute helper processes as part of running Docker Desktop. -Unlike the privileged helper, this socket does not run as `root` and grants no -elevated privileges. It is owned by, and accessible only to, the same macOS user -running Docker Desktop, and is contained in Docker Desktop's application container. +This socket does not run as `root` and grants no elevated privileges. It is owned by, +and accessible only to, the same macOS user running Docker Desktop, and is contained +in Docker Desktop's application container. ## Containers running as root within the Linux VM diff --git a/content/manuals/desktop/setup/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md index c4b06f1be93..fa4fb0d2ccd 100644 --- a/content/manuals/desktop/setup/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -65,7 +65,6 @@ The privileged helper `com.docker.service` is a Windows service which runs in th The service performs the following functionalities: - Ensuring that `kubernetes.docker.internal` is defined in the Win32 hosts file. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers. - Ensuring that `host.docker.internal` and `gateway.docker.internal` are defined in the Win32 hosts file. They point to the host local IP address and allow an application to resolve the host IP using the same name from either the host itself or a container. -- Securely caching the Registry Access Management policy which is read-only for the developer. - Creating the Hyper-V VM `"DockerDesktopVM"` and managing its lifecycle - starting, stopping, and destroying it. The VM name is hard coded in the service code so the service cannot be used for creating or manipulating any other VMs. - Moving the VHDX file or folder. - Starting and stopping the Windows Docker engine and querying whether it's running.