Nginx: when to use proxy_set_header Host $host vs $proxy_host

Question

I've been reading up on reverse proxying and am wondering when proxy_set_header Host $host is appropriate over proxy_set_header Host $proxy_host. I did some research and in this article it says that in most cases we set Host to $host. Then why does nginx default to $proxy_host? To help me understand more concretely, will the reverse proxy configuration here (bottom of article) still work if we use $proxy_host instead?

Thanks

Answer 1

In general there is no need to explicitly do proxy_set_header Host $proxy_host because it's the default. If you need to call a server by something other than what is in the proxy_pass directive, then you will need to override via proxy_set_header something.

If you want to proxy the same host as was in your server_name directive, then you would have occasion to use proxy_set_header $host. This would commonly be the case if perhaps the actual application is hosted on another port or on some internal server.

server {
    listen 80;
    server_name site.example.com;
    
    location / {
       proxy_set_header Host $host;
       proxy_pass http://localhost:8080;
    }
}

If the name you are calling the upstream is not its actual DNS name, then you might have something like:

# 192.168.2.1 responds to site.example.com, but
# site.example.com doesn't actually resolve to 192.168.2.1
proxy_pass http://192.168.2.1;
proxy_set_header Host site.example.com;

Another case might be for "name-based" virtual hosting where there is a useful DNS name for the upstream, but you would like to call it by another name.

proxy_pass http://origin.example.com;
proxy_set_header Host site.example.com

Answer 2

$proxy_host is a tag about upstreams servers, so nginx do this one by default.

If you want to add other tag(header) about the host, use $host.