In many situations Apache httpd must construct a self-referential URL -- that is, a URL that refers back to the same server. With UseCanonicalName On Apache httpd will use the hostname and port specified in the ServerName directive to construct the canonical name for the server. This name is used in all self-referential URLs, and for the values of SERVER_NAME and SERVER_PORT in CGIs.

With UseCanonicalName Off Apache httpd will form self-referential URLs using the hostname and port supplied by the client if any are supplied (otherwise it will use the canonical name, as defined above). These values are the same that are used to implement name-based virtual hosts and are available with the same clients. The CGI variables SERVER_NAME and SERVER_PORT will be constructed from the client supplied values as well.

An example where this may be useful is on an intranet server where you have users connecting to the machine using short names such as www . You'll notice that if the users type a shortname and a URL which is a directory, such as http://www/splat , without the trailing slash, then Apache httpd will redirect them to http://www.example.com/splat/ . If you have authentication enabled, this will cause the user to have to authenticate twice (once for www and once again for www.example.com -- see the FAQ on this subject for more information). But if UseCanonicalName is set Off , then Apache httpd will redirect to http://www/splat/ .

There is a third option, UseCanonicalName DNS , which is intended for use with mass IP-based virtual hosting to support ancient clients that do not provide a Host: header. With this option, Apache httpd does a reverse DNS lookup on the server IP address that the client connected to in order to work out self-referential URLs.

See also

• UseCanonicalPhysicalPort
• ServerName
• Listen