Wording of HTTPS_PROXY

[marksteward]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

This is misleading:

If you are behind an HTTPS proxy server, set the HTTPS_PROXY environment variable:

[Service]
Environment="HTTPS_PROXY=https://proxy.example.com:3129"

"HTTPS proxy server" is ambiguous, and in this paragraph both senses are conflated.

HTTPS_PROXY must be set for an HTTPS request to be proxied, and "HTTPS proxy server" in that case means "a proxy server that supports CONNECT". However, any meaningful proxy server like Squid will already support CONNECT, so this is redundant.

With the change to https:// and port 3129, the condition actually suggests that "HTTPS proxy server" means "a proxy server that must be connected to over HTTPS". However, this is not a reason to set HTTPS_PROXY, but a reason to change the URL.

Most users will actually need to set both HTTP_PROXY and HTTPS_PROXY to the same URL, and not care about what kind of proxy server they're behind. If a user gets this wrong, they'll get the following error that can be found all over the web:

Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io on 127.0.0.53:53: server misbehaving

This also exacerbates docker/cli#4501, although that ticket seems to already work on the assumption that HTTP_PROXY and HTTPS_PROXY will be set together.

Location

https://docs.docker.com/engine/daemon/proxy/

Suggestion

I suggest changing this to something like:

If you need to connect to HTTPS registries, set the HTTPS_PROXY environment variable as well:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:3128"
Environment="HTTPS_PROXY=http://proxy.example.com:3128"

If you have a proxy that uses an https:// URL, this is also supported:

[Service]
Environment="HTTP_PROXY=https://proxy.example.com:3129"
Environment="HTTPS_PROXY=https://proxy.example.com:3129"

Alternatively, remove the suggestion that someone will want to only proxy HTTP.

https://docs.docker.com/engine/cli/proxy/#configure-proxy-settings-per-daemon should also ideally be changed to remove the suggestion that HTTP/HTTPS_PROXY correspond to http://, https://, :3128 and :3129.

[marksteward]

I also suspect this could never have worked in practice:

$ docker run --rm alpine sh -c 'env | grep -i  _PROXY'
https_proxy=http://proxy.example.com:3129
HTTPS_PROXY=http://proxy.example.com:3129

That's an http:// URL for a Squid proxy listening on port 3129, which is typically https://. Note that this doesn't match the .json it references.

[marksteward]

https://docs.docker.com/reference/cli/dockerd/, which links to the page above, is quite clear about the use of HTTP/HTTPS_PROXY and gets it right, i.e.:

Proxy URL for HTTPS requests unless overridden by NoProxy. See the Go specification for details.

However, that page also has (in reference to the CLI):

HTTPS_PROXY takes precedence over HTTP_PROXY.

Which is no longer true, and might be the source of all this confusion.

[marksteward]

Would there be more chance of getting this fixed if I provide a PR?