Some Virtual hosts troubleshooting information/tips based on the common questions about them in #httpd

TroubleShooting Virtual Hosts

The page will concentrate on Name Based virtual hosts mainly because it is what most people use and it is the one many people seem to have problems with. Version specifc information is marked as such.

The Basics

Virtual Hosts are much simpler than most people seem to think but in some cases are made more complicated by some unusual 'default' virtual host setups installed by some of the major distributions.

First things first, read the documentation!

Secondly, and this cannot be stressed enough, use apachectl -S or httpd -S whenever any changes are made to the configuration. It outputs various lines of information that are vital to the troubleshooting of virtual host configurations. See below for further information.

Thirdly, although there are a couple of exceptions, if an access log is defined then httpd will always log something to it when it serves a request and an entry will always be logged in the error log on a 4xx return code. An error log entry will also normally be written on a 5xx return code, however when using 3rd party modules, CGIs or launguages such as php it is possible for these to be hijacked and nothing will be in the log. If you cannot find the access/error log entry then you are either looking in the wrong log or the request didn't actually reach the web server.

Virtual Host Requirements

The First Virtual Host

With named base virtual hosts, the first one apache finds in the configuration files is special. This is the one that requests will be passed to if apache has no way to determine which specific virtual host to use. It is the default virtual host.

In general, if the user types into their browser, then it is the string that is matched against the host component of the ServerName, or any ServerAlias directive (Remember Server{{`Name can contain an optional schema and port). Anything that does not match a Server}}Name or Server`Alias in the configuration will be served by the default virtual host.

Note: It is the contents of the Host header that is actually used by httpd here rather than the host component of the URL, though these would normally be the same.

Virtual Host Example

Here is a very simple two virtual host example that we will use to highlight the output of apachectl -S.

# NameVirtualhost is needed in httpd prior to v2.3.11

# Any request to, or indeed anything other than that resolves
# to will be served by this first virtual host
  DocumentRoot /var/www/foo

# Only URLs that start http:/// or will be served
# by this virtual host
  DocumentRoot /var/www/bar

Problem Solving Tips

The ErrorLog is always the first place to look when any problems arise, but there are things that can be done to make troubleshooting virtual hosts easier.

In the ouput, if there are any duplicate server names or aliases (other than the default one and the namevhost immediately after it) then there are virtual hosts with the same name (or Alias) and only the first one in the list will work.

With httpd prior to v2.3.11, if you do not have a Name{{`Virtual}}{{Host directive you will not see the line ending in }}is a NameVirtualHost` and depending on the exact configuration you may see something similar to one of the following warnings:

 # If the virtual hosts are defined with IP:port
[Fri Jan 11 22:27:30 2013] [warn] VirtualHost overlaps with VirtualHost, the first has precedence, perhaps you need a NameVirtualHost directive

 # If the virtual hosts are defined with *:port
[Fri Jan 11 22:28:04 2013] [warn] _default_ VirtualHost overlap on port 80, the first has precedence