Dynamic virtual hosts using Apache mod_vhost_alias

Posted by Pixafy Team

Apache has the ability to serve multiple web sites of different domains on the same physical server using the same installation of Apache.  It does this by using virtual hosts either by using the host header or IP address to select the path of the files to server.  In this article, I will highlight an Apache Module called mod_vhost_alias, which allows for dynamically configured virtual hosting.

Just as mod_alias and mod_userdir are used to translate URIs to filenames, mod_vhost_alias uses the server name to dynamically select with path to use. Here is an example:

The path to a file on my web server is


using this apache directive and mod_vhost_alias

UseCanonicalName Off
VirtualDocumentRoot /usr/local/www/%1

I can access this file in my browser using the following url

Basically what this is doing is taking the first part of the host name and interpolating it into the path of the document root.  The ‘1’ in the ‘%1’ specifies the first dot component of the host name.  You could also use %0 to use the entire host name; changing the actual path to


The UseCanonicalName Off essentially tells Apache to set the hostname to what is supplied by the client and not what is in the ServerName directive.

It is possible to select any part of the hostname using the interpretation specifiers:

0 the whole name
1 the first part
2 the second part
-1 the last part
-2 the penultimate part
2+ the second and all subsequent parts
-2+ the penultimate and all preceding parts
1+ and -1+ the same as 0

The above is an example of name-based vhosting; you could also use IP-based, but while it is very similar, it is not beneficial for serving multiple web servers using one IP address. You may reference the Apache documentation for mod_vhost_alias more information on IP based vhosting.

Let’s discuss a real world example using mod_vhost_alias.  I use this apache functionality on my local development machine.  This allows me to create a nice friendly name for all my projects and all I have to configure is an entry in my local hosts file.

This is how it works…

Lets say I have client and personal development sites on my local host.

my document root is:


underneath I have


In order to access these projects sites, all I want to follow this URI scheme:




I can make this possible by using this directive:

VirtualDocumentRoot /home/tariq/www/%3s/%1.1/%2

This is effectively telling Apache to use the third dot component of the hostname to create the first dynamic segment of the path.  Then Apache will use the first letter of the first part of the hostname and finally the second part as the final segment of the path.

So if I wanted to get to supakillerapp I would point my browser to:


Since I told Apache to only look at the first character of %1 then I could use any string that starts with ‘c’ as the part of my host name to access a resource under this document root.  For example, I could use http://poultryandcows.supakillerapp.project/ would get me to the same place.

Using vhost aliasing a great when you need to manage a bunch of websites on the same server.  All I would need to do to start up a new site is copy files into a path that can be interpeted by the VirtualDocumentRoot directive,  /home/tariq/projects/c/newsitename is an example, and add an entry to my hosts file.

UPDATE: In response to a question in the comments, we’ve posted an example of the vhost and httpd.conf settings to make this work.

Leave us a comment below or tweet us @Pixafy