Search code examples
dockerdocker-cli

What are the possible formats of the DOCKER_HOST URLs?

Remote docker servers can be reached by the docker cli by settings the DOCKER_HOST environment variable.

Mostly, tcp://<hostname-or-ip>:<port> or sometimes ssh://<hostname-or-ip>:<port> is used.

Unfortunately, the docker documentation talks about everything, except the possible URL formats of this variable. What are they, how do they work?

Solution

  • The parsing of the DOCKER_HOST variable happens in the parseDockerDaemonHost function in the opts/hosts.go source fragment of the docker-cli.

    The possible values are the following:

    • tcp://1.2.3.4:2375 - it connects to the docker server at the TCP port 2375 of the remote system. Beside the IP, also the hostname can be used. Leaving out the port field, it defaults to 2375 in normal mode, or to 2376 if we use TLS encryption (docker client should be called with the --tls flag for that).
    • unix:///path/to/socket - it connects to a docker server listening on the local unix socket /path/to/socket. Unix sockets exist only on Linux (& co) systems. The path does not need to be an absolute one. The default value is /var/run/docker.sock (is connected if DOCKER_HOST=unix://).
    • npipe:///./pipe/docker_engine - named pipes are similar to the Unix sockets, but in the Windows world. It probably connects a local docker server running on a Windows. Note, docker on Windows runs on a Linux VM, over the HyperV virtualization engine of the Microsoft. And it is reached probably over the virtual network provided by the HyperV. Native Windows docker is not very widely used.
    • fd://1.2.3.4:5678 - Contrary its name, it has probably nothing to do to file descriptors. It behaves similarly to the tcp://, except that the port number does not default to 2375. The exact working would probably need further digging in the docker-cli source.
    • ssh://1.2.3.4:22 - it calls the ssh command to remotely login the remote server. The docker command should be available there in the default PATH. There it executes a docker command, passing exactly the same arguments to it, with them we called it locally. Probably it can connect the docker server only on its default address (/var/run/docker.sock) on the remote side.

    Protocol-less URLs (//host:port) default to tcp://. Any other URL formats are rejected with the Invalid bind address format error message.

    The communication protocol is http(s), although I had some issues with it in proxied configurations.