Opened 8 years ago

Last modified 5 years ago

#971 new enhancement

Clarify $host and $hostname in embedded variables documentation

Reported by: Neil Craig Owned by:
Priority: minor Milestone:
Component: documentation Version: 1.9.x
Keywords: $host $hostname Cc:
uname -a: Linux ip-10-13-149-100.eu-west-1.compute.internal 3.10.0-327.10.1.el7.x86_64 #1 SMP Tue Feb 16 17:03:50 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux
nginx -V: nginx version: nginx/1.10.0 (BBC GTM)
built with OpenSSL 1.1.0-pre4 (beta) 16 Mar 2016
TLS SNI support enabled
configure arguments: --build='BBC GTM' --prefix=/usr/local/nginx --sbin-path=/usr/sbin/nginx --conf-path=/etc/nginx/current/nginx.conf --pid-path=/var/run/nginx.pid --error-log-path=/var/log/nginx/default-error.log --http-log-path=/var/log/nginx/default-access.log --lock-path=/var/run/nginx.lock --http-client-body-temp-path=/var/cache/nginx/client_temp --http-proxy-temp-path=/var/cache/nginx/proxy_temp --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp --http-scgi-temp-path=/var/cache/nginx/scgi_temp --user=gtmdaemon --group=gtmdaemon --with-http_realip_module --with-http_v2_module --with-http_ssl_module --with-http_geoip_module --with-pcre-jit --with-ipv6 --with-file-aio --with-cc-opt='-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4 -grecord-gcc-switches -m64 -mtune=generic' --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/headers-more-nginx-module --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/naxsi/naxsi_src --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/nginx-module-vts --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/nginx-upstream-dynamic-servers --with-openssl=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/openssl-1.1.0-pre4

Description

Hi

I've just been documenting some of my project which is based on NGINX and did some tests to clarify the values of $host and $hostname which I feel could be improved in docs: http://nginx.org/en/docs/http/ngx_http_core_module.html#variables

I'd suggest adding to $host a line to state that the value is normalised, e.g.:
"in this order of precedence: host name from the request line, or host name from the “Host” request header field, or the server name matching a request. The value of $host is normalised into lower case."

This is important if, for example, you're using $host in a cache key.

I'd also like to expand on the docs for $hostname, e.g. make it something like:
"The FQDN of the host computer, e.g. the value of 'hostname -f' on *nix systems"

Hope that all makes sense.

Change History (3)

comment:1 by Neil Craig, 8 years ago

Actually, i'd like to add an extra detail:

"in this order of precedence: host name from the request line, or host name from the “Host” request header field, or the server name matching a request. The value of $host is normalised to lower case and to remove the inbound port number i.e. a request to WWW.EXAMPLE.COM:8080 will yield a $host value of www.example.com"

comment:2 by bes.internal@…, 5 years ago

"The FQDN of the host computer, e.g. the value of 'hostname -f' on *nix systems"

But nginx's $hostname variable is not hostname -f. It just hostname as system call gethostname() which returns short name first.

in reply to:  2 comment:3 by Maxim Dounin, 5 years ago

It just hostname as system call gethostname() which returns short name first.

Not exactly correct. While it is indeed gethostname(), it is not expected to "return short name first". Instead, gethostname() returns whatever is set as the host name. Usually it's up to administrator to use either short or full name (though it is expected to be FQDN on systems participating in the DNS).

Note: See TracTickets for help on using tickets.