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

dd.4.18 adminless install for mac (#16852) 

* dd.4.18 adminless install for mac

* edit

* updates

* updates

* fix build

* add info on updating PATH

* add info on updating PATH

* update code block

* edits from review

* edits from review and page-layout tweak

* further review edits

* fix build

* edits post review
This commit is contained in:
Allie Sadler 2023-04-05 16:53:01 +01:00 committed by GitHub
parent a989828588
commit 5a2416947c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 139 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
desktop/install/mac-install.md
View File

@ -78,11 +78,15 @@ Your Mac must meet the following requirements to install Docker Desktop successf
{% include desktop-license-update.md %}
4. Select **Accept** to continue. Docker Desktop starts after you accept the terms.
4. Select **Accept** to continue.
Note that Docker Desktop will not run if you do not agree to the terms. You can choose to accept the terms at a later date by opening Docker Desktop.
For more information, see [Docker Desktop Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement){: target="_blank" rel="noopener" class="_" }. We recommend that you also read the [FAQs](https://www.docker.com/pricing/faq){: target="_blank" rel="noopener" class="_"}.
5. From the installation window, select either:
- **Use recommended settings (Requires password)**. This let's 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](../settings/mac.md#advanced), for more information and how to set the location of the Docker CLI tools.
6. Select **Finish**. If you have applied any of the above configurations that require a password in step 5, you are asked to enter your password to confirm.
### Install from the command line
@ -105,13 +109,6 @@ The `install` command accepts the following flags:
- 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.

136
desktop/mac/permission-requirements.md
View File

@ -13,39 +13,108 @@ It also provides clarity on running containers as `root` as opposed to having `r
## Permission requirements
Docker Desktop for Mac is run as an unprivileged user. However, certain functionalities may be required for Docker Desktop to perform a limited set of privileged configurations such as:
- [Installing symlinks](#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](#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](#ensuring-localhost-and-kubernetesdockerinternal-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.
Docker Desktop for Mac is run as an unprivileged user. However, certain functionalities are required for Docker Desktop 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. The so-called "privileged ports" are not generally 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](#ensuring-localhost-and-kubernetesdockerinternal-are-defined) in `/etc/hosts`. Some old macOS installs do not 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.
Versions prior to 4.15 of Docker Desktop for Mac 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. Following the principle of least privilege, this approach allows `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.
Depending on which version of Docker Desktop for Mac is used, privileged access is granted either during installation, first run, or only when it is needed.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab1">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab2">Version 4.15 - 4.17 </a></li>
<li><a data-toggle="tab" data-target="#tab3">Versions prior to 4.15</a></li>
</ul>
<div class="tab-content">
<div id="tab1" class="tab-pane fade in active" markdown="1">
From version 4.18 and above, Docker Desktop for Mac provides greater control over functionality that's enabled during installation.
The first time Docker Desktop for Mac is launched, you are presented with an installation window where you can choose to either use the default settings, which work for most developers and require privileged access to be granted, 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:
- 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.
You can change these configurations at a later date from the **Advanced** page in **Settings**.
<hr>
</div>
<div id="tab2" class="tab-pane fade" markdown="1">
Versions 4.15 to 4.17 of Docker Desktop for Mac doesn't require the privileged process to run permanently. Whenever elevated privileges are needed for a configuration, Docker Desktop prompts you with information on the task it needs to perform. Most configurations are applied once, subsequent runs don't 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.
<hr>
</div>
<div id="tab3" class="tab-pane fade" markdown="1">
Versions prior to 4.15 of Docker Desktop for Mac require `root` access to be granted on the first run. The first time that Docker Desktop is launched you receive an admin prompt to grant permission for the installation of the `com.docker.vmnetd` privileged helper service. For subsequent runs, `root` privileges aren't required. Following the principle of least privilege, this approach allows `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`.
For security reasons, version 4.15 of Docker Desktop for Mac doesn't 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 don't 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.
<hr>
</div>
</div>
### 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 in the user's PATH by default, and so Docker Desktop creates symlinks for all docker binaries in it.
The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop ensures the Docker CLI is on your PATH without having to reconfigure shells, log out then log back in for example. As on most systems `/usr/local/bin` is on the PATH by default, and so 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:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab4">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab5">Version 4.17 and earlier </a></li>
</ul>
<div class="tab-content">
<div id="tab4" class="tab-pane fade in active" markdown="1">
With version 4.18 or later, you can choose whether to install symlinks either in `/usr/local/bin` or `$HOME/.docker/bin` during installation of Docker Desktop.
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 the you must [manually add `$HOME/.docker/bin`](../settings/mac.md#advanced) to their PATH.
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 to 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/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures the user is not prompted on each startup to create the symlink. If the user does not enable this option at installation, the symlink and the startup task is not created and the user may have to explicitly set the `DOCKER_HOST` environment variable 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.
<hr>
</div>
<div id="tab5" class="tab-pane fade" markdown="1">
For versions prior to 4.18, 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 the user authorizes this, 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 creates the symlinks in `~/.docker/bin` and edits the user's shell profile to ensure this location is in the 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.
- Triggers an admin prompt for the user to authorize the creation of symlinks in `/usr/local/bin`. If you authorizes this, symlinks to Docker binaries are created in `/usr/local/bin`. If you reject the prompt, are not willing to run configurations requiring elevated privileges, or don't have admin rights on your machine, Docker Desktop creates the symlinks in `~/.docker/bin` and edits your shell profile to ensure this location is in your PATH. This requires all open shells to be reloaded.
The rejection is recorded for future runs to avoid prompting you again.
For any failure to ensure binaries are on your PATH, you 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 on each startup to create the symlink. If the user rejects the prompt, the symlink and the startup task is 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.
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 that you are not prompted on each startup to create the symlink. If you reject the prompt, the symlink and the startup task is not created and you 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.
<hr>
</div>
</div>
### Binding privileged ports
When running a container that requires binding privileged ports, Docker Desktop first attempts to bind it directly as an unprivileged process. If the OS prevents this and it fails, Docker Desktop checks if the `com.docker.vmnetd` privileged helper process is running to bind the privileged port through it.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab6">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab7">Version 4.17 and earlier </a></li>
</ul>
<div class="tab-content">
<div id="tab6" class="tab-pane fade in active" markdown="1">
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).
With version 4.18 and later 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.
<hr>
</div>
<div id="tab7" class="tab-pane fade" markdown="1">
For versions below 4.18 , if you run a container that requires binding privileged ports, Docker Desktop first attempts to bind it directly as an unprivileged process. If the OS prevents this and it fails, 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 you 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 now only supports port binding and caching the Registry Access Management policy.
If the user declines the launch of the privileged helper process, binding the privileged port cannot be done and the docker CLI returns an error:
If you decline the launch of the privileged helper process, binding the privileged port cannot be done and the Docker CLI returns an error:
```console
$ docker run -p 127.0.0.1:80:80 docker/getting-started
@ -58,20 +127,41 @@ ERRO[0003] error waiting for container: context canceled
> **Note**
>
> The command may fail with the same error if the user takes too long to authorize the prompt to start the helper process, as it may timeout.
> The command may fail with the same error if you take too long to authorize the prompt to start the helper process, as it may timeout.
<hr>
</div>
</div>
### 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.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab8">Version 4.18 and later</a></li>
<li><a data-toggle="tab" data-target="#tab9">Version 4.17 and earlier </a></li>
</ul>
<div class="tab-content">
<div id="tab8" class="tab-pane fade in active" markdown="1">
With version 4.18 it is your responsibility to ensure that localhost is resolved to `127.0.0.1` and if Kubernetes is used, that `kubernetes.docker.internal` is resolved to `127.0.0.1`.
<hr>
</div>
<div id="tab9" class="tab-pane fade" markdown="1">
On first run, Docker Desktop checks if `localhost` is resolved to `127.0.0.1`. In case the resolution fails, it prompts you 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 you to do so.
<hr>
</div>
</div>
## 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:
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, you are 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
- Sets up symlinks
- Ensures that `localhost` is resolved to `127.0.0.1`
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.
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

21
desktop/settings/mac.md
View File

@ -50,6 +50,27 @@ On the **General** tab, you can configure when to start Docker and specify other
- **Use Docker Compose V2**. Select to enable the `docker-compose` command to
use Docker Compose V2. For more information, see [Docker Compose V2](../../compose/compose-v2/index.md).
## Advanced
On the **Advanced** tab, you can reconfigure your initial installation settings:
- **Choose how to configure the installation of Docker's CLI tools**.
- **System**: Docker CLI tools are installed in the system directory under `/usr/local/bin`
- **User**: Docker CLI tools are installed in the user directory under `$HOME/.docker/bin`. You must then add `$HOME/.docker/bin` to your PATH. To add `$HOME/.docker/bin` to your path:
1. Open your shell configuration file. This is `~/.bashrc` if you're using a bash shell, or `~/.zshrc` if you're using a zsh shell.
2. Run the following command:
```console
$ export PATH=$PATH:~/.docker/bin
```
3. Save and the close the file. Restart your shell to apply the changes to the PATH variable.
- **Enable default Docker socket (Requires password)**. 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](../mac/permission-requirements.md#installing-symlinks).
- **Enable privileged port mapping (Requires password)**. Starts the privileged helper process which binds the ports that are between 1 and 1024. For more information, see [permission requirements for macOS](../mac/permission-requirements.md#binding-privileged-ports).
For more information on each configuration
and use case, see [Permission requirements](../mac/permission-requirements.md).
## Resources
The **Resources** tab allows you to configure CPU, memory, disk, proxies,