Inspecting docker activity with socat

Lately I've been busy working on an Eclipse plugin that will support a wide range of docker functionality. Some of that has involved looking at some docker client libraries, figuring out how it works in one implementation, and seeing how this can be ported to other implementations. While the Docker Remote API is well documented, it can still be tricky to get things right.

When I'm debugging some failed interaction, I've found socat to be very useful.

Let's say we want to inspect all traffic going through 'unix:///var/run/docker.sock' . We can't directly sniff the traffic on it as we don't really control this socket. We first create a fake unix socket, say '/tmp/fake' and relay all its traffic to '/var/run/docker.sock' . In this way, regular interactions remain undisturbed, but the redirect allows socat to inspect traffic.

$ socat -v UNIX-LISTEN:/tmp/fake,fork UNIX-CONNECT:/var/run/docker.sock

-v : writes the traffic to stderr as text in addition to relaying instructions. Some conversions are made for the sake of readability so if certain sequences aren't being interpreted properly, one could try -x (hex).
UNIX-LISTEN : listen for connections on the unix socket (In our case, /tmp/fake)
fork : create a separate subprocess for handling new connections so the main process may continue listening
UNIX-CONNECT : connect to the specified unix socket (In our case, /var/run/docker.sock)

Once that's been started, it's just a matter of ensuring your docker commands go through 'unix:///tmp/fake'.

$ export DOCKER_HOST=unix:///tmp/fake
$ docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
fedora              20                  6cece30db4f9        4 weeks ago         374.1 MB

The output should look something like this :

$ socat -v UNIX-LISTEN:/tmp/fake,fork UNIX-CONNECT:/var/run/docker.sock
> 2015/02/05 12:47:35.433028  length=85 from=0 to=84
GET /v1.16/images/json HTTP/1.1r
Host: /tmp/faker
User-Agent: Docker-Client/1.4.1r
r
< 2015/02/05 12:47:35.437616  length=369 from=0 to=368
HTTP/1.1 200 OKr
Content-Type: application/jsonr
Date: Thu, 05 Feb 2015 17:47:35 GMTr
Content-Length: 260r
r
[{"Created":1420065245,"Id":"6cece30db4f924da43969a12fdf47492ada22b372a0968d6ca8b71d25876629f","ParentId":"782cf93a8f16d3016dae352188cd5cfedb6a15c37d4dbd704399f02d1bb89dab","RepoTags":["fedora:20","fedora:heisenbug"],"Size":374074925,"VirtualSize":374074925}

We could have done this just as easily over TCP-LISTEN/TCP-CONNECT provided the docker service was bound to some local port but you can find out more about the various options in the man-page. Even some basic searches should demonstrate the incredible versatility of this tool.