The value passed to the
UseCanonicalName configuration directive in Apache HTTPD Web server determines how Apache will internally create a “self-referential” URL for itself. A self-referential URL or the canonical server name is one that
httpd uses to refer to itself in different cases. What cases ?
- For instance the
SERVER_PORTenvironment variables that it passes to CGI scripts, holds the URL (canonical server name) value. If you’re running a PHP script then you can get these with
- Core configuration directives or those of other modules may require this URL (canonical server name) to identify the incoming request, which in a way refers to the server only. For instance
Let’s see how the different values passed to
UseCanonicalName specified either in the main server config or inside a virtual host block, affects the construction and resolution of the canonical server name (or self-referential URLs).
Off is the default value if nothing is specified. This will make Apache use the hostname and port (
Host header) supplied by the client to create the self-referential URL. If the client does not specify the hostname and port (does not send the
Host header for instance), then
UseCanonicalName On will take effect.
So now if you try to access
$_ENV['SERVER_NAME'] in your PHP script, you’ll either get the URL which will be created by the
Host header supplied by the client or via what happens when
UseCanonicalName On is set (next section). If you specified
LogFormat then the logs will start showing up the URL as well for incoming requests.
In most cases, this is what we need.
The hostname and port specified in the
ServerName directive is used to create and resolve the canonical server name. Even if a
Host header is supplied by the client, it is not considered.
ServerName is specified in the entire configuration (main and virtual servers) then the system hostname is used as the default server name. If the system hostname look up fails then a reverse lookup is performed on the first system IP address to find a suitable hostname.
The final value
DNS is interesting. In this case Apache
httpd will do a reverse DNS lookup on the server’s IP address that the client connected to. If the reverse DNS lookup resolves to a hostname then that’ll be used as the canonical server name. If the lookup fails, then the IP itself will be used.