Debug Apache Web Server Virtual Host Configuration Settings

There are times when you want to know a couple of things about your virtual host configuration settings like:

  • How many virtual hosts are configured ?
  • Which files contain the different virtual host configurations ?
  • How many name-based virtual hosts are there vs ip-based ?
  • You added a new virtual host but have no idea why its not serving any requests yet ?

There’s a certain way httpd parses all the <VirtualHost> configuration blocks and uses them to match with client connections or incoming requests. If you don’t understand the request matching logic properly, you could end up making a few mistakes but worry not, there’s a quick way to debug our current virtual hosts in effect.

The apachectl program can be used to dump all the parsed vhost settings. It comes with the default Apache installation in all the major Linux distributions (Ubuntu, Debian, CentOS, Fedora), Mac OS, FreeBSD, etc. If for some reason apachectl doesn’t work for you, then use the httpd command directly.

Let’s see how we can get a list of virtual hosts defined and in use.

# apachectl -D DUMP_VHOSTS
VirtualHost configuration:
*:80                   is a NameVirtualHost
         default server catchall (/etc/apache2/sites-enabled/000-catchall.conf:1)
         port 80 namevhost catchall (/etc/apache2/sites-enabled/000-catchall.conf:1)
         port 80 namevhost codingshower.com (/etc/apache2/sites-enabled/codingshower.conf:1)

# apachectl -S
VirtualHost configuration:
*:80                   is a NameVirtualHost
         default server catchall (/etc/apache2/sites-enabled/000-catchall.conf:1)
         port 80 namevhost catchall (/etc/apache2/sites-enabled/000-catchall.conf:1)
         port 80 namevhost codingshower.com (/etc/apache2/sites-enabled/codingshower.conf:1)
ServerRoot: "/etc/apache2"
Main DocumentRoot: "/var/www/html"
Main ErrorLog: "/var/log/apache2/error.log"
Mutex watchdog-callback: using_defaults
Mutex rewrite-map: using_defaults
Mutex default: dir="/var/run/apache2/" mechanism=default
Mutex mpm-accept: using_defaults
PidFile: "/var/run/apache2/apache2.pid"
Define: DUMP_VHOSTS
Define: DUMP_RUN_CFG
User: name="www-data" id=33
Group: name="www-data" id=33

Both the commands parses all the virtual hosts defined in your configuration files, which is then shown under the VirtualHost configuration: section (in the output above). If we look at it closely:

*:80                   is a NameVirtualHost
         default server catchall (/etc/apache2/sites-enabled/000-catchall.conf:1)
         port 80 namevhost catchall (/etc/apache2/sites-enabled/000-catchall.conf:1)
         port 80 namevhost codingshower.com (/etc/apache2/sites-enabled/codingshower.conf:1)

This is the current virtual host setup for this site. It gives out a bunch of useful information:

  1. There are two virtual hosts set and enabled at – 000-catchall.conf:1 and codingshower.conf:1. What comes after : is the line number.
  2. All the <VirtualHost> definitions currently have been defined with *:80 as the expected addr:port type.
  3. All the virtual hosts are name-based virtual hosts.
  4. The two virtual hosts have a hostname of catchall and codingshower.com respectively. In this case they were defined with the ServerName directive inside the virtual host blocks.
  5. The catchall virtual host is also the default or primary server. What this means is that a request to *:80 will be served by catchall (default server) if it is not matched by any other virtual hosts which in this case is only codingshower.com.

I highly recommend that whenever you set up a new virtual host or make changes to the <VirtualHost>, ServerName or ServerAlias directives of existing ones, you must run one of the two commands shown above and go through your new list properly so that you know what’ll work for a specific connection/client/request.

I also highly recommend reading my other article that explains virtual host request matching in depth.

Leave a Reply

Your email address will not be published.