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_NAME and SERVER_PORT environment 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 $_ENV or getenv().
• 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 %V in LogFormat or %0 in mod_vhost_alias (VirtualDocumentRoot).

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).

UseCanonicalName Off

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 %V in LogFormat then the logs will start showing up the URL as well for incoming requests.

In most cases, this is what we need.

UseCanonicalName On

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.

If no 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.

UseCanonicalName DNS

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.