Intended behavior for Host header in Proxy scenario

Maxim Dounin mdounin at
Fri Nov 23 17:18:02 UTC 2018


On Fri, Nov 23, 2018 at 04:33:33PM +0100, Jack Henschel wrote:

> On 11/23/18 3:11 PM, Maxim Dounin wrote:
> > Hello!
> > 
> > On Fri, Nov 23, 2018 at 09:23:01AM +0100, Jack Henschel wrote:
> > 
> >> Hi Maxim,
> >>
> >> thanks for the quick confirmation!
> >>
> >>> The Host header is set to what you wrote in the "proxy_pass" 
> >>> by  default.  That is, it will be "backend" with the above 
> >>> configuration.
> >>
> >> Wouldn't it make more sense to use the hostname from the 
> >> particular upstream server?
> >> I see two scenarios where this is required:
> >>
> >> 1. TLS secured upstream servers. TLS verification requires the 
> >> correct Host header to be set (i.e. "" instead of 
> >> "backend"). Though I know there is the possibility of doing this 
> >> (additionally) with TLS client certificates.
> >>
> >> 2. Upstream vhosts. Consider the scenario where multiple domains 
> >> point to the same IP address, where the requests are split apart 
> >> based on the Host header (I.e. virtual hosts)
> >>
> >> What do you think?
> > 
> > All servers listed in an upstream block are expected to be equal, 
> > and expected to be able to process identical requests.  You can 
> > think of it as multiple A records in DNS, with slightly more 
> > control on nginx side.
> > 
> Alright, makes sense.
> > Moreover, nginx doesn't even know which particular server it will 
> > use when it creates a request.  And the same request can be sent 
> > to multiple servers, as per proxy_next_upstream.
> > 
> > This does not preclude you from neither using TLS, nor vhosts on 
> > upstream servers.  But you shouldn't expect that names as written 
> > within server directives in upstream blocks means anything and 
> > will be used for anything but resolving these names to IP addresses.
> Thanks for the clarification!
> Would you mind adding this implicit (reasonable) behavior of Nginx to
> the documentation?
> In particular clarify that when using an upstream block for the
> proxy_pass argument, the $proxy_host variable will contain the name of
> the host specified on the proxy_pass line and NOT the hostnames of the
> servers specified in the upstream block.
> The behavior may be totally obvious to you, but it surely wasn't for me. :-)

I don't think I've seen anyone else who assumed that $proxy_host 
should contain anything not written in the "proxy_pass" directive.

I've, however, seen people who tried to implement/asked for 
something working on a per-peer basis, such as sending a request 
with different Host headers to different servers in a single 
upstream block.  While it may worth explaining that this is not 
something possible, I don't think I know a good place in 
the documentation to do this.

May be adding the DNS analogy to the upstream directive 
documentation may help, not sure.

> BTW: Is there a "public" method for contributing to the docs? (Git, etc.)

Much like with nginx itself, sending patches into nginx-devel@ 
mailing list is the best method, see here:

Repository with docs is here:

Maxim Dounin

More information about the nginx mailing list