docker / docker/docs

Networking - `userland-proxy` could better clarify impact

Open
#17,312 6 comments 10 reactions 1 assignee View on GitHub

@dvdksn is already working on this.

Since Sep 26, 2023.

agent/skip agent/triaged area/networking kind/enhancement lifecycle/frozen
Dominant language
Markdown
Stars
4.7k
Forks
8.5k
Avg merge
2d 18h
Merged PRs (30d)
108

Description

Problem description

The daemon setting userland-proxy no longer appears to be documented? Disabling it still applies configuration, behavioural difference is not clearly explained.

Prior documentation since removed

The option was originally introduced in May 2015 with docs at docs/sources/articles/networking.md

There is not much history on those changes to derive information on if this was intentional. Considering the size and intent of the two changes, it was likely accidental and difficult for any review to catch without investing significant time to be thorough.

All that seems to exist now is this: https://docs.docker.com/engine/reference/commandline/dockerd/

Use userland proxy for loopback traffic (default true)

That does not communicate much to the user, or the actual differences in network behaviour when the setting is enabled / disabled.

Problem location

I couldn't find the information I wanted. I expected to find it near the following URL https://docs.docker.com/network/ or https://docs.docker.com/config/daemon/

Either section may be relevant. The previous docs location was regarding information on network port binding, and provided the information as a note admonition. Perhaps config (container networking) and network (iptables) are good candidates.

Project version(s) affected

Docs since Feb 2018.

Suggestions for a fix

I think it is planned to eventually drop the userland-proxy feature once it has been disabled by default and reaches a level of compatibility that makes enabling redundant.

Most users may not need this information documented, thus this issue alone may be a sufficient resource. Below is relevant information for users to be aware of regarding the feature toggles.


Previous docs content
Click to expand
  • The first part of the referenced docs (that the original review said would not be needed), was not dropped for the ~3 years it was present in the docs for.
  • The remaining seemed relevant technical information to explain better what disabling the setting did:

    The --userland-proxy parameter, true by default, provides a userland implementation for inter-container and outside-to-container communication.
    When disabled, Docker uses both an additional MASQUERADE iptable rule and the net.ipv4.route_localnet kernel parameter which allow the host machine to connect to a local container exposed port through the commonly used loopback address: this alternative is preferred for performance reasons.

Resolved

EDIT: This feedback was actually addressed, my bad 😅

An earlier PR attempt for the --userland-proxy feature has a relevant comment about the documented loopback reference:

In regards to where it says the option allows routing "through the loopback interface". It's not technically accurate as the option allows routing localnet traffic (127.0.0.0/8).
If another address is on the loopback interface, or if the 127.0.0.1 is on an interface other than loopback, it makes no difference.

This is relevant information AFAIK. Along with the route_localnet kernel change. You can query 127.0.0.1, but not the IPv6 equivalent [::1] (which has no equivalent route_localnet). As the default binding 0.0.0.0 also includes IPv6 interfaces, this behaviour from userland-proxy: false is not obvious to track down. Works fine with userland-proxy: true.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.