Apache2/Virtual Hosts

Configuring virtual hosts and subdomains
The Gentoo maintainers of the Apache package have supplied a template configuration file for a virtual host in. This setup can be confusing for new users to set up a proper configuration.

Below is a more comprehensive example of how to host one or more websites on your local machine. Here it is assumed that the machine has only one IP address. This a common situation for new Apache users who want to host some websites on their local machine.

Prerequisites: A router capable of performing NAT/PAT (Network Address Translation/Port Address Translation) is often used to share the same internet connection among several computers. The websites to be hosted must have their DNS records pointed to the external IP address.

The default http port (80) is inbound forwarded to the local machine running a webserver. Due to Network Address Translation, the Apache configuration does not need to know the actual IP address where DNS points to for the website.

The description below deals with Apache 2.2.14 (r1). The machine that runs Apache listens to port and has IP address. In this case, the external IP address is assumed to be, and all DNS records of the websites to be hosted should point to this address. If hosting subdomains for a domain is desired, ensure there is an 'A' record for that specific subdomain, or a general wildcard entry ('*'), both of which should point to the external IP address.

The existing (template) files in provided by Apache/Gentoo maintainers can be deleted, if following the instructions below.

Apache needs details about the actual port and local IP address the webserver will be using. The best place to put it is in the main configuration file. The following lines should be added just before the virtual-host support section: # below two lines with additions, just above Virtual-host support Listen 80 NameVirtualHost *:80 # end of addition # Virtual-host support # # Gentoo has made using virtual-hosts easy. In /etc/apache2/vhosts.d/ we # include a default vhost (enabled by adding -D DEFAULT_VHOST to  # APACHE2_OPTS in /etc/conf.d/apache2). Include /etc/apache2/vhosts.d/*.conf

Notice that the virtual-host support section following the and  directives merely includes all files ending with .conf from the  directory.

In the example above it is assumed that the machine has only one IP address, hence the asterisk in the NameVirtualHost directive. Instead the actual IP address from the example machine,, could be used. But in that case, if for some reason the actual IP address changes and this is not reflected in the Apache configuration files, it may lead to unexpected results. See 'Avoiding unexpected directory listing' below. It is not advisable to explicitly qualify the NameVirtualHost directive.

For each website to be hosted, a (minimal) Virtual Host configuration should be provided in a file in. Suppose the website is, then a minimal configuration, where the use of a subdomain is illustrated, is as follows:

  ServerName asubdomain.my-url.com ServerAlias bsubdomain.my-url.com ServerAdmin webmaster@subdomain.my-url.com DocumentRoot "/var/www/com/my-url/asubdomain"  Options Indexes FollowSymLinks AllowOverride All Order allow,deny Allow from all    ServerName my-url.com ServerAlias *.my-url.com ServerAdmin webmaster@my-url.com DocumentRoot "/var/www/com/my-url/www"  Options Indexes FollowSymLinks AllowOverride All Order allow,deny Allow from all   

The Include statement in the toplevel configuration file includes every file with extension  from. This is to encourage placing all configuration for every hosted website in a different file. This is the preferred configuration.

In fact, it is not strictly necessary to have a separate file for each website (or subdomain). However, in this example we will configure a 'default' website, and you should at least put that configuration in a separate file which must be processed first. You can read more about this below ('Avoiding the default website').

The ServerAlias directives and  tell Apache to serve all requests which match the  and  clause, unless the requested subdomain is matched by any other virtual host (in our example ).

If you plan to serve a specific subdomain other than or serving the main website without the need for prepending it with, please also read the guidelines at 'Avoiding the default website'.

If you want to host subdomains, make sure that their configuration is read (and processed) before the main domain (as in this example where the subdomain is apparently configured in the same file as the main domain). If you don't keep virtual domains in the same file, take care that the filenames assure this.

The path where the files of your websites are located is arbitrary (in the example: /var/www/com/my-url/www). Make sure that the owner and group of this directory is apache:

If you want to add another website to be hosted, just copy this file, and replace all occurences of the domain name accordingly, and place its files under the correct location in the filesystem, and set the privilege rights to apache.

Avoiding the default website
Gentoo's main Apache configuration file processes each file in  in alphabetical order. Apache treats the first encountered virtual host as the default website, which will be used for all requests that are not matched by other configured virtual hosts (or subdomain). Unless you take some precautions, this can easily lead to some unexpected results, which are explained and remedied below.

General advice: only use a ServerAlias directive in the main virtual host configuration, and with care (but never with wildcard) in subdomain configurations.

Even if you are aware of the above, some unexpected results may occur.

Unexpected result #1:

Every http request that resolves to your machine will be served by Apache. If there is no matching virtual host, Apache will just serve the first virtual host it encountered during initialization.

Unexpected result #2:

In fact the same as above, but with different remedy. On a request for a website with a subdomain which has not been configured, Apache will serve the default website, unless instructed otherwise.

Remedy #1: Simply add a phoney virtual host which is guaranteed to be processed first during initialization. Treat this host as a any other normal virtual host, but make sure that the ServerName predicate does not match any valid website. In this respect, using plain 'localhost' is a good idea.

If you use separate files for each virtual host, ensure its file is processed first (e.g. prepending it with "00_" and rename other file(s) with this).

If you keep all your virtual host configurations in one file, put it as the first configured host.

Remedy #2: Put all configurations for a subdomain of a virtual hosts in front of the main domain configuration. This is straightforward when you keep all configuration in one file. Again, take care with naming and numbering of files when you choose to put the configuration in several files. modules.d/00_mod_log_config.conf

Fine-grain logging
By default all logging is done by Apache in two files in and. You can refine this for a specific virtual host by adding an access (CustomLog) and/or an error log (ErrorLog) rule in a virtual host configuration, just under the definition of the document root.

DocumentRoot "/var/www/com/my-url/www" CustomLog "/var/log/apache2/com/my-url/www/access.txt" common ErrorLog "/var/log/apache2/com/my-url/www/error.txt"

The definition 'common' in the access log refers to the definition in file. What is defined there is the most common (sic) format, but if you like you can tweak with it.

Please note: Apache will start, but not serve ANY page, if a path you have specified does not exist or is otherwise not accessible. (This is confusing, but properly logged in file ).

Virtual hosts and SSL
If you want to add encryption to a website, you must set up SSL (Secure Socket Layer). The standard SSL setup in Apache is easy but not covered here. Usage of SSL is limited, since the original SSL protocol is not suited for more than one virtual host.

New technology (SNI, Server Name Identification) removes this limitation. Using this technology your website is able to encrypt not only one but several virtual hosts. Some recent mainstream browsers are already enabled for SNI, and others are expected to follow.

For a full coverage of enabling SNI in your webserver, you are referred to an article on this wiki about SSL and Name Based Virtual Hosts.

Avoiding unexpected directory listing
Providing a default website, as configured in needs special attention. When you use NAT/PAT, and the IP address of your webserver machine has been changed, and you reflected that change in your router, but you did not change any setting in the configuration of Apache, the webserver will respond to each request with a 403 status. Although not explicitly configured, the webserver is trying to serve pages from.

A security breach problem can arise when your machine that hosts the webserver also hosts ordinary user accounts for accessing the machine. You are advised not to do so, but it is not unlikely that you provide user accounts for external users who need to maintain the content of a website hosted on your machine.

When you allow terminal access you should be aware that when you 'forgot' to reflect changes in the IP address in the Apache configuration, the current set up of Apache still allows browsing to 'localhost'. Depending on the actual rights the apache user has on your filesystem, Apache offers ftp-like access to your whole filesystem.

This only affects Apache configurations that explicitly qualify the IP address in VirtualHost and NameVirtualHost predicates (not *:80).

Testing your webserver
Configuration of Apache may seem straightforward but it is also very error-prone. You are advised to do the following tests. For each virtual host check if the main domain, any subdomains and use of erroneous subdomains yields the correct results.

When you use a terminal and have lynx or links to your disposal, you should test the example configuration from this page as follows:

and verify the results. The first three commands should point to your website, and the fourth to your subdomain. None should point to the default website.

Repeat this for all your virtual hosts.

Also test the default website:

(we assume is your external IP address).

Since we have configured a default website, all of these should give that, and not one of your virtual hosts.

From here...
When you have your webserver up and running as described here you are encouraged to make the next step.

Once you have acquired the 'feeling' about how Apache works you may find your own ways of enhancing its possibilities which go way beyond the scope of this article.

For instance, adding PHP support to it, or perhaps even JSP, enables you to build versatile websites with dynamic content.

Let's hope Gentoo and Apache have opened your horizon.