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 http://my.domain.com/my/url/path into their browser, then it is the string my.domain.com that is matched against the host component of the ServerName, or any ServerAlias directive (Remember ServerName can contain an optional schema and port). Anything that does not match a ServerName or ServerAlias 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
NameVirtualHost 192.168.0.1:80

# Any request to foo.com, or indeed anything other than bar.com that resolves
# to 192.168.0.1 will be served by this first virtual host
<VirtualHost 192.168.0.1:80>
  ServerName foo.com
  ServerAlias www.foo.com
  DocumentRoot /var/www/foo
</Virtualhost>

# Only URLs that start http:///bar.com/ or http://www.bar.com will be served
# by this virtual host
<VirtualHost 192.168.0.1:80>
  ServerName bar.com
  ServerAlias www.bar.com
  DocumentRoot /var/www/bar
</Virtualhost>

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.


TroubleshootingVhosts (last edited 2013-03-14 10:44:04 by SeanTimmins)