18. December 2018

Allow access to the Docker Engine without admin rights on Windows

If you have been working with Docker on Windows, the following message is probably familiar:

error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.40/containers/json: open //./pipe/docker_engine: The system cannot find the file specified. In the default daemon configuration on Windows, the docker client must be run elevated to connect. This error may also indicate that the docker daemon is not running.

As the message says, there are two likely reasons for this error: 1) Your Docker engine is not running and you need to start it. 2) You are not in an administrator / elevated session and therefore don’t have access to the engine. The reason for requiring an admin session is that the Docker client in the default configuration uses a named pipe to connect to the Docker engine and that named pipe can only be accessed by administrators¹. If you want to verify that, run the following in an elevated PowerShell session:

PS C:\Windows\system32> [System.IO.Directory]::GetAccessControl("\\.\pipe\docker_engine") | Format-Table

Path Owner                  Access
---- -----                  ------
     BUILTIN\Administrators NT AUTHORITY\SYSTEM Allow  FullControl...

If you are running this on a Windows 10 machine you need to use "\\.\pipe\docker_engine_windows" instead of "\\.\pipe\docker_engine", but the result should be the same. For understandable reasons some like Waldo(rf) are not happy to always use an elevated prompt for a number of security as well as practical concerns. To avoid this, you can simple allow your user FullControl access to that named pipe. That is unfortunately not as easy as changing ACLs on a directory but I have created a very small PowerShell module to help with that²: dockeraccesshelper, source code is here.

Usage is quite easy: When using it for the first time on a machine, you need to install the module with Install-Module -Name dockeraccesshelper

PS C:\Windows\system32> Install-Module -Name dockeraccesshelper

Untrusted repository
You are installing the modules from an untrusted repository. If you trust this repository, change its
InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from
'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): y

After that you can always import the module with Import-Module dockeraccesshelper and then run Add-AccountToDockerAccess <username> to give access to a user. In my case, I use the following command:

PS C:\Windows\system32> Import-Module dockeraccesshelper
PS C:\Windows\system32> Add-AccountToDockerAccess "FUM-GLOBAL\TFENSTER"

Now you can run all your docker commands without needing an admin session

This is only true when running Windows containers on Windows. With Linux containers on Window, a group “docker_users” is allowed as well. Beats me why this doesn’t work the same for Windows containers on Windows, but I’ll try to find out…
The actual coding was way quicker than understanding how to publish this on the PowerShell Gallery as I had never done that before…