mirror of https://github.com/docker/docs.git
mac: update permission requirements for DD v.4.15 (#16247)
* update permission requirements for Mac Signed-off-by: Anca Iordache <anca.iordache@docker.com> * Update desktop/mac/permission-requirements.md Co-authored-by: Mihaela Stoica <mihaela.stoica@docker.com> * Update desktop/mac/permission-requirements.md Co-authored-by: Mihaela Stoica <mihaela.stoica@docker.com> * Update desktop/mac/permission-requirements.md Co-authored-by: Mihaela Stoica <mihaela.stoica@docker.com> * Update desktop/mac/permission-requirements.md Co-authored-by: Mihaela Stoica <mihaela.stoica@docker.com> Signed-off-by: Anca Iordache <anca.iordache@docker.com> Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Co-authored-by: Mihaela Stoica <mihaela.stoica@docker.com>
This commit is contained in:
Anca Iordache
GitHub
parent
0cfb44db60
commit
ef228bbf7a
|
|
@ -102,12 +102,19 @@ As macOS typically performs security checks the first time an application is use
|
|||
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.
|
||||
- `--user=<username>`: Performs the privileged configurations once during installation. 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}}'`
|
||||
|
||||
### Runtime permission requirements
|
||||
|
||||
For some functions, Docker Desktop may require elevated privileges. The user is informed and prompted for authorization whenever such
|
||||
configuration must be performed. [Docker Desktop permission requirements](../mac/permission-requirements.md) provides details on each configuration
|
||||
and use case.
|
||||
|
||||
|
||||
## Where to go next
|
||||
|
||||
- [Docker Desktop for Apple silicon](../install/mac-install.md) for detailed information about Docker Desktop for Apple silicon.
|
||||
|
|
|
|||
|
|
@ -7,34 +7,94 @@ redirect_from:
|
|||
- /desktop/mac/privileged-helper/
|
||||
---
|
||||
|
||||
This page contains information about the permission requirements for running and installing Docker Desktop on Mac, the functionality of the privileged helper process `com.docker.vmnetd` and the reasoning behind this approach.
|
||||
This page contains information about the permission requirements for running and installing Docker Desktop on Mac.
|
||||
|
||||
It also provides clarity on running containers as `root` as opposed to having `root` access on the host.
|
||||
|
||||
## Permission requirements
|
||||
|
||||
In the default set up flow, Docker Desktop for Mac doesn't require root privileges for installation but does require `root` access to be granted on the first run. The first time that Docker Desktop is launched the user receives an admin prompt to grant permissions for a privileged helper service to be installed. For subsequent runs, no `root` privileges are required.
|
||||
Docker Desktop for Mac is run as an unprivileged user. However, certain functionalities may require for Docker Desktop to perform a limited set of privileged configurations such as:
|
||||
- Installing symlinks in `/usr/local/bin`. This ensures the `docker` CLI is on the user’s PATH without having to reconfigure shells, log out then log back in, for example.
|
||||
- Binding privileged ports that are less than 1024. The so-called "privileged ports" have not generally been used as a security boundary, however OSes still prevent unprivileged processes from binding 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 in `/etc/hosts`. Some old macOS installs did not have `localhost` in `/etc/hosts`, which caused Docker to fail. Defining the DNS name `kubernetes.docker.internal` allows us to share Kubernetes contexts with containers.
|
||||
- Securely caching the Registry Access Management policy which is read-only for the developer.
|
||||
|
||||
The reason for this is that Docker Desktop needs to perform a limited set of privileged operations using the privileged helper process `com.docker.vmnetd`. This approach allows, following the principle of least privilege, `root` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.
|
||||
Versions prior to Docker Desktop 4.15, require `root` access to be granted on the first run. The first time that Docker Desktop is launched the user receives an admin prompt to grant permissions for a privileged helper service `com.docker.vmnetd` to be installed. For subsequent runs, no `root` privileges are required. This approach allowed, following the principle of least privilege, `root` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.
|
||||
All privileged operations are run using the privileged helper process `com.docker.vmnetd`.
|
||||
|
||||
In version 4.11 and later of Docker Desktop for Mac you can avoid running the privileged helper service in the background by using the `--user` flag on the [install command](../install/mac-install.md#install-from-the-command-line). This results in `com.docker.vmnetd` being used for set up during installation and then disabled at runtime. In this case, the user is not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag:
|
||||
For security reasons, starting with the version 4.15, Docker Desktop for Mac does not require the user to run a permanent privileged process. Whenever elevated privileges are needed for a configuration,
|
||||
Docker Desktop prompts the user with information on the task it needs to perform. Most configurations are applied once, subsequent runs do not prompt for privileged access anymore.
|
||||
The only time Docker Desktop may start the privileged process is for binding privileged ports that are not allowed by default on the host OS.
|
||||
|
||||
### Installing symlinks
|
||||
|
||||
The docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop ensures the `docker` CLI is on the user’s PATH without having to reconfigure shells, log out then log back in for example. As on most systems, `/usr/local/bin` is by default in user's PATH, Docker Desktop creates symlinks for all docker binaries in it.
|
||||
|
||||
Installing symlinks in `/usr/local/bin` is a privileged configuration Docker Desktop performs on the first startup. Docker Desktop checks if symlinks exists and takes the following actions:
|
||||
- Creates the symlinks without the admin prompt if `/usr/local/bin` is writable by unprivileged users
|
||||
- Triggers an admin prompt for the user to authorize the creation of symlinks in `/usr/local/bin`. If user authorizes, symlinks to docker binaries are created in `/usr/local/bin`.
|
||||
If the user rejects the prompt, is not willing to run configurations requiring elevated privileges, or does not have admin rights on their machine, Docker Desktop falls back to create the symlinks in `~/.docker/bin` and edits the user's shell profile to ensure this location is in user's PATH. This requires all open shells to be reloaded.
|
||||
The rejection is recorded for future runs to avoid prompting the user again.
|
||||
For any failure to ensure binaries are on the user's PATH, the user may need to manually add to their PATH the `/Applications/Docker.app/Contents/Resources/bin` or use the full path to docker binaries.
|
||||
|
||||
A particular case is the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various docker clients relying on the default docker socket path to work without additional changes. As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to 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/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures, the user is not prompted all the time on startup to create the symlink. If the user rejects the prompt, the symlink and the startup task are not created and the user may have to explicitly set the DOCKER_HOST to `/Users/<user>/.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
|
||||
|
||||
When running a container that requires privileged ports binding, Docker Desktop first attempts to bind it directly as an unprivileged process. In case of failure due to the OS preventing it, Docker Desktop checks if the `com.docker.vmnetd` privileged helper process is running to bind the privileged port through it. If the privileged helper process is not running, Docker Desktop prompts the user for authorization to run it under [launchd](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html).
|
||||
This configures the privileged helper to run as in the versions of Docker Desktop prior to 4.15. However, the functionality provided by this privileged helper has been stripped down. It now only supports port binding and caching the Registry Access Management policy.
|
||||
If the user declines the launch of the privileged helper process, the privileged port binding cannot be done and the docker CLI returns an error:
|
||||
```console
|
||||
$ docker run -p 127.0.0.1:80:80 docker/getting-started
|
||||
|
||||
docker: Error response from daemon: Ports are not available: exposing port
|
||||
TCP 127.0.0.1:80 -> 0.0.0.0:0: failed to connect to /var/run/com.docker.vmnetd.sock:
|
||||
is vmnetd running?: dial unix /var/run/com.docker.vmnetd.sock: connect: connection
|
||||
refused.
|
||||
ERRO[0003] error waiting for container: context canceled
|
||||
```
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The command may fail with the same error if user takes too long to authorize the prompt to start the helper process as it may timeout.
|
||||
|
||||
The removal of the privileged helper process can be done in the typical way of 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
|
||||
```
|
||||
|
||||
### Ensuring `localhost` and `kubernetes.docker.internal` are defined
|
||||
|
||||
On first run, Docker Desktop checks if `localhost` is resolved to `127.0.0.1`. In case the resolution fails, it prompts the user to allow adding the mapping to `/etc/hosts`. Similarly, when the Kubernetes cluster is installed, it checks that `kubernetes.docker.internal` is resolved to `127.0.0.1` and prompts the user to do so.
|
||||
|
||||
## Installing from the commandline
|
||||
|
||||
In version 4.11 and later of Docker Desktop for Mac, privileged configurations are applied during the installation with the `--user` flag on the [install command](../install/mac-install.md#install-from-the-command-line). In this case, the user is not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag:
|
||||
- Uninstalls the previous `com.docker.vmnetd` if present
|
||||
- Sets up symlinks for the user
|
||||
- Ensures that `localhost` and `kubernetes.docker.internal` are present in `/etc/hosts`
|
||||
- Ensures that `localhost` is resolved to `127.0.0.1`
|
||||
|
||||
This approach has the following limitations:
|
||||
- Docker Desktop can only be run by one user account per machine, namely the one specified in the `-–user` flag.
|
||||
- Binding privileged ports (<1024) on `127.0.0.1` will not work. For example, `docker run -p 127.0.0.1:80:80 docker/getting-started` will fail, `docker run -p 80:80 docker/getting-started` however will succeed as binding privileged ports on `0.0.0.0` is no longer a privileged operation on recent versions of MacOS.
|
||||
- Spindump diagnostics for fine grained CPU utilization are not gathered.
|
||||
This approach has the limitation that Docker Desktop can only be run by one user account per machine, namely the one specified in the `-–user` flag.
|
||||
|
||||
## Privileged Helper
|
||||
|
||||
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 it over the UNIX domain socket `/var/run/com.docker.vmnetd.sock`. The functionalities it performs are:
|
||||
- Installing and uninstalling symlinks in `/usr/local/bin`. This ensures the `docker` CLI is on the user’s PATH without having to reconfigure shells, log out then log back in for example.
|
||||
- Binding privileged ports that are less than 1024. The so-called "privileged ports" have not generally been used as a security boundary, however OSes still prevent unprivileged processes from binding them which breaks commands like `docker run -p 80:80 nginx`
|
||||
- Ensuring `localhost` and `kubernetes.docker.internal` are defined in `/etc/hosts`. Some old macOS installs did not have `localhost` in `/etc/hosts`, which caused Docker to fail. Defining the DNS name `kubernetes.docker.internal` allows us to share Kubernetes contexts with containers.
|
||||
In the limited situations when the privileged helper is needed (i.e. 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 it 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.
|
||||
- Performing some diagnostic actions, in particular gathering a performance trace of Docker itself.
|
||||
- Uninstalling the privileged helper.
|
||||
|
||||
## Containers running as root within the Linux VM
|
||||
|
|
|
|||
Loading…
Reference in New Issue