Why listen on 127.0.0.1 by default?

[NotaInutilis]

I'm setting up the socket proxy and one of the defaults is puzzling me (because it was the cause of an hour of debugging).

In the readme, it's stated that "Socket-proxy listens per default only on 127.0.0.1. Depending on what you need, you may want to set another listener address with the -listenip parameter. In almost every use case, -listenip=0.0.0.0 will be the correct configuration when using socket-proxy in a docker image."
https://github.com/wollomatic/socket-proxy#setting-up-the-tcp-listener

Since the whole documentation and use is geared towards docker (it's a docker socket proxy so that makes sense) and is strongly recommending using 0.0.0.0, why is 127.0.0.1 the default listening parameter?

I'm learning networking and the importance of default values as I set stuff up so it's a mix of genuine curiosity and a little bit of frustration.

[aleetreny]

The short version is that 127.0.0.1 is the safe default for the binary, while 0.0.0.0 is usually necessary for the common multi-container topology.

Loopback is scoped to a network namespace:

• When the binary runs directly on a host, 127.0.0.1 means only processes on that host can reach it.
• When it runs in a container, 127.0.0.1 means only processes inside that same container can reach it. A sibling Traefik or Dozzle container connects through the proxy container bridge interface, not its loopback interface, so the connection fails.
• 0.0.0.0 inside the container binds the bridge interface as well and makes sibling-container access possible.

The important distinction is that binding 0.0.0.0 does not by itself publish the port to the host or Internet. Docker network membership and any ports: mapping decide reachability outside that container namespace. The separate -allowfrom setting then decides which reachable clients the proxy accepts.

Why not default to 0.0.0.0? Because this proxy fronts a Docker socket, which is an extremely privileged control surface. A user can run the same binary outside Docker, attach the container to an overly broad network, or publish port 2375. Binding every interface by default would turn a configuration mistake into exposure. With 127.0.0.1, an incomplete configuration fails closed and requires an explicit opt-in.

For the usual Compose setup, I would use all of these together:

• -listenip=0.0.0.0 inside the proxy container
• a dedicated private or internal: true Docker network shared only with the client
• no host ports: publication unless it is genuinely needed
• -allowfrom=<client-service-name> or a narrow CIDR
• the smallest possible per-method path allowlists

If host access is required, the host-side mapping can still be restricted, for example 127.0.0.1:2375:2375, while the process binds 0.0.0.0 inside its own container.

So the default is deliberately about minimizing the consequence of a mistake. The documented Docker setting is about crossing container network namespaces. Both make sense, but the README could make that namespace distinction more explicit.

[NotaInutilis]

I actually broadly understand the technical stuff now, thanks for taking the time to explain it!

However I still have big opinions and thoughts to share about those defaults from a usability standpoint. I have not studied computer sciences but the weird monkeys called "people" that use it.

Re-reading the docs about "Allowing access" after your answer, I now get that the stated goal is a "secure-by-default design" centering on explicitly allowing access (bolded for foreshadowing reasons). That is a good thing.
https://github.com/wollomatic/socket-proxy#allowing-access

However² the choice is, in its current form, not explicit: it's an unnecessary test of technical knowledge that is not useful when actually using the container. It does not ask for permission to allow access, it's an open-book test of in-container networking, using an IP address to answer a yes/no question about security methodology.

From a user standpoint (mine): I want to install a security feature but it's broken by design when other socket proxies work out of the box. My approach to security is that I don't want to copypaste that -listenip=0.0.0.0 without understanding what it's doing. Still, out of frustration, I copypasted it. And it worked: I was rewarded for recklessly reading and blindly following the documentation! It's not that bad but still, it's not explicit consent: it's troubleshooting.

I feel like a better way of having an explicit acknowledgement from the user would be to use a mandatory variable like accessType=TCP or accessType=endpoint. This would use human language instead of IP addresses which are meaningless to somebody who does not know how to read them.

Another additional way of securing would be to not EXPOSE 2375 by default in the Dockerfile but to ask of the user to explicitly expose: 2375 in their compose file. This is once again a self-centered example: I'm using docker, I "speak" compose, I can understand it. However using these containers does not ask me to properly understand networking. I don't "speak" IP, 0.0.0.0 or 127.0.0.1 have no meaningful difference to me. I know a bit about it because I'm curious, but it's not necessary to host a few services on docker.

I'm also adding an additional argument/rant because you're also speaking of ports: publication and binding 127.0.0.1:2375:2375: there's no documentation about expose:! Anywhere! It took me a while to figure out the difference between exposing a port with expose: and publishing it with port:. This part of the Docker Compose specification feels like arcane knowledge that can sometimes be found in old forums when search is not polluted by SEO.

So putting the user in front of a problem to which one of the answer is publishing 127.0.0.1:2375:2375 if they know how to use ports: but not internal container networking feels like tempting fate. I'd personally rather teach to use expose: (Maybe expose: 127.0.0.1:2375:2375 works too but as I said earlier: lack of documentation on the topic).

I like this proxy! It's clever, simple (actually yes!) and powerful but it's frustrating because it lacks in the documentation and accessibility departments. The way it is presented is overwhelming and demands prior knowledge which I do not have (and arguably do not need, docker compose is that easy and, while impressive at first glance, the socket API documentation is actually very clear and helpful). I would have been tempted to qualify that as "gatekeeping" but I can't do that in good faith: asking a technical question got me a very cool detailed answer in less than 2 hours. That's great! Thanks for reading my ranted talk, I will definitely ask more questions later.

[wollomatic]

Hi @NotaInutilis,

thanks for your important input. As I'm not home until the end if August, just a short prelimitary reply.

I have no intention of "gatekeeping". Initially I wrote the too for my own usage and designed it just to fit my needs. After a few years I learned a lot of how other people use it. With this knowledge maybe I would have designed some thins a little different. I will look after your suggestions as soon as I'll be home again. But I would aim to have no breaking changes. Maybe it would be a good idea if we started a new discussion thread to find out if there's a need for a redesigned version 2 with breaking changes. I would approach the subject very cautiously.

Secondly, English is not my first language and documenting the own code for other users is not the easiest thing. Any help in. improving the documentation is highly appreciated :-)

And a big thanks to @aleetreny for the great answer!

Best reagards,
Wolfgang

[NotaInutilis]

I've actually begun writing some documentation that I'd find useful for my own use and will definitely share it later! English is not my native language either, so I understand the struggle.

Enjoy your time off!

[wollomatic]

I wanted ListenIP to be set explicitly to avoid any nasty surprises. Access to the Docker socket can have very serious consequences if permissions are configured incorrectly. For that reason, I believe security-sensitive software like this should rather not work at all than work insecurely.