Feature: Using Virtual Hosts

One of the most important facilities in Apache is its ability to run 'Virtual Hosts'. This is now the essential way to run multiple web services - each with different host names and URLs - which appear to be completely separate sites. This is widely used by ISPs, hosting sites and content providers who need to manage multiple sites but do not want to buy a new machine for each one. In this issues we explain how to go about setting up a virtual host on your machine, what you need to do to get the hostname working, and how to configure Apache.

There are two types of virtual hosts: IP-based and non-IP-based. The former is where each virtual host has its own IP address. You will need a new IP address for each virtual host you want to set up, either from your existing allocation or by obtaining more from your service provider. Once you have extra IP addresses, you tell your machine to handle them. On some operating systems, you can give a single ethernet interface multiple addresses (typically with an ifconfig alias command). On other systems you will have to have a different physical interface for each IP address (typically by buying extra ethernet cards).

IP addresses are a resource that costs money and are increasingly difficult to get hold of, so modern browsers can now also use 'non-IP' virtual hosts. This lets you use the same IP address for multiple host names. When the server receives an incoming Web connection it does not know the hostname what was used in the URL, however the new HTTP/1.1 specification adds a facility where the browser must tell the server the hostname it is using, on the Host: header. If an older browser connects to a non-IP virtual host, it will not send the Host: header, so the server will have to respond with a list of possible virtual hosts. Apache provides some help for configuring a site for both old and new browsers.

Having selected an IP address, the next stage is to update the DNS so that browsers can convert the hostname into the right address. The DNS is the system that every machine connected to the Internet uses to find the IP address of host names. If your hostname is not in the DNS, no-one will be able to connect to your server (except by the unfriendly IP address).

If the virtual host name you are going to use is under your existing domain, you can just add the record into your own DNS server. If the virtual host name is in someone else's domain, you will need to get them to add it to their DNS server files. In some cases, you will want to use a domain not yet used on the internet, in which case you will have to apply for the domain name from the InterNIC and set up the primary and secondary DNS servers for it, before adding the entry for your virtual host.

In any of these cases, the entry you need to add to the DNS is an address record (an A record) pointing at the appropriate IP address. For example, say you want the domain www.my-dom.com to access your host with IP address 10.1.2.3: you will need to add the following line to the DNS zone file for my-dom.com:

  www         A     10.1.2.3

Now users can enter http://www.my-dom.com/ as a URL in their browsers and get to your web server. However it will return the same information as if the machine's original hostname had been used. So the final stage is to tell Apache how to respond differently to the different addresses.

Configuring Apache for virtual hosts is a two stage process. Firstly, it needs to be told which IP addresses (and ports) to listen to for incoming web connections. By default Apache listens to port 80 on all IP addresses of the local machine, and this is often sufficient. If you have a more complex requirement, such as listening on various port numbers, or only to specific IP addresses, the BindAddress or Listen directives can be used.

Secondly, having accepted an incoming web connection, the server needs to be configured to handle the request differently depending on what virtual host it was addressed to. This usually involves configuring Apache to use a different DocumentRoot.

If you are happy for Apache to listen to all local IP addresses on the port specified by the Port directive, you can skip this section. However there are some cases where you will want to use the directives explained here:

• If you have many IP addresses on the machine but only want to run a web server on some of them
• If one or more of your virtual hosts is on a different port
• If you want to run multiple copies of the Apache server serving different virtual hosts

There are two ways of telling Apache what addresses and ports to listen two: either you use the BindAddress directive to specify a single address or port, or you use the Listen directive to any number of specific addresses or ports.

For example, if you run your main server on IP address 10.1.2.3 port 80, and a virtual host on IP 10.1.2.4 port 8000, you would use:

  Listen 10.1.2.3:80
  Listen 10.1.2.4:8000

Listen and BindAddress are documented on the Apache site.

Having got Apache to listen to the appropriate IP addresses and ports, the final stage is to configure the server to behave differently for requests on each of the different addresses. This is done using <VirtualHost> sections in the configuration files, normally in httpd.conf.

A typical (but minimal) virtual host configuration looks like this:

  <VirtualHost 10.1.2.3>
  DocumentRoot /www/vhost1
  ServerName  www.my-dom.com
  </VirtualHost>

This should be placed in the httpd.conf file. You would replace the text '10.1.2.3' with one of your virtual host IP addresses. If you want to specify a port as well, follow the IP address with a colon and the port number (eg '10.1.2.4:8000'). If omitted, the port defaults to 80.

If no <VirtualHost> sections are given in the configuration files, Apache will treat requests from the different addresses and ports identically. In terms of setting up virtual hosts, we call the default behaviour the 'main server' configuration. Unless overridden by <VirtualHost> sections, the main server behaviour will be inherited by all the virtual hosts. When configuring virtual hosts, you need to decide what changes need to be made in each of the virtual host configurations.

Any directives inside a <VirtualHost> section apply to just that virtual host. The directives either override the configuration give in the main server, or supplement it, depending on the directive. For example, the DocumentRoot directive in a <VirtualHost> section overrides the main server's DocumentRoot, while AddType supplements the main server's mime types.

Now, when a request arrives, Apache uses the IP address and port it arrived on to find a matching virtual host configuration. If no virtual host matches the address and port, it is handled by the main server configuration. If it does match a virtual host address, Apache will use the configuration of that virtual server to handle the request.

For the example above, the server configuration used will be the same as the main server, except that the DocumentRoot will be /www/vhost1, and the ServerName will by www.my-dom.com. Directives commonly set in <VirtualHost> sections are DocumentRoot, ServerName, ErrorLog and TransferLog. Directives that deal with handling requests and resources are valid inside <VirtualHost> sections. However some directives are not valid inside <VirtualHost> sections, including BindAddress, StartSevers, Listen, Group and User.

You can have as many <VirtualHost> sections as you want. You can choose to leave one or more of your virtual hosts being handled by the main server, or have a <VirtualHost> for every available address and port, and leave the main server with no requests to handle.

Non-IP virtual hosts are configured in a very similar way. The IP address that the requests will arrive on is given in the <VirtualHost> directive, and the host name is put in the ServerName directive. The difference is that there will (usually) be more than one <VirtualHost> section handling the same IP address. In order for Apache to know whether a request arriving on a particular IP address is supposed to be a name-based requests, the NameVirtualHost directive is used to tell Apache the IP addresses for name-based requests. A virtual host can handle more than one non-IP hostname by using the ServerAlias directive, in addition to the ServerName.