An In-Depth Discussion of Virtual Host Matching

Available Languages: en | + ko | + tr

+ + +

The virtual host code was completely rewritten in + Apache 1.3. This document attempts to explain + exactly what Apache does when deciding what virtual host to + serve a hit from. With the help of the new + NameVirtualHost + directive virtual host configuration should be a lot easier and + safer than with versions prior to 1.3.

+ +

If you just want to make it work without + understanding how, here are some + examples.

+ +

Config File Parsing
Virtual Host Matching
Tips

Config File Parsing

+ +

There is a main_server which consists of all the + definitions appearing outside of + <VirtualHost> sections. There are virtual + servers, called vhosts, which are defined by + <VirtualHost> + sections.

+ +

The directives + Listen, + ServerName, + ServerPath, + and ServerAlias + can appear anywhere within the definition of a server. However, + each appearance overrides the previous appearance (within that + server).

+ +

The default value of the Listen field for + main_server is 80. The main_server has no default + ServerPath, or ServerAlias. The + default ServerName is deduced from the server's IP + address.

+ +

The main_server Listen directive has two functions. One + function is to determine the default network port Apache will + bind to. The second function is to specify the port number + which is used in absolute URIs during redirects.

+ +

Unlike the main_server, vhost ports do not affect + what ports Apache listens for connections on.

+ +

Each address appearing in the VirtualHost + directive can have an optional port. If the port is unspecified + it defaults to the value of the main_server's most recent + Listen statement. The special port * + indicates a wildcard that matches any port. Collectively the + entire set of addresses (including multiple A + record results from DNS lookups) are called the vhost's + address set.

+ +

Unless a NameVirtualHost + directive is used for a specific IP address the first vhost + with that address is treated as an IP-based vhost. The IP + address can also be the wildcard *.

+ +

If name-based vhosts should be used a + NameVirtualHost directive must appear + with the IP address set to be used for the name-based vhosts. + In other words, you must specify the IP address that holds the + hostname aliases (CNAMEs) for your name-based vhosts via a + NameVirtualHost directive in your configuration + file.

+ +

Multiple NameVirtualHost directives can be used + each with a set of VirtualHost directives but only + one NameVirtualHost directive should be used for + each specific IP:port pair.

+ +

The ordering of NameVirtualHost and + VirtualHost directives is not important which + makes the following two examples identical (only the order of + the VirtualHost directives for one + address set is important, see below):

+ + + + +

+ NameVirtualHost 111.22.33.44 + <VirtualHost 111.22.33.44> + # server A + ... + </VirtualHost> + <VirtualHost 111.22.33.44> + # server B + ... + </VirtualHost> + + NameVirtualHost 111.22.33.55 + <VirtualHost 111.22.33.55> + # server C + ... + </VirtualHost> + <VirtualHost 111.22.33.55> + # server D + ... + </VirtualHost> +

+ <VirtualHost 111.22.33.44> + # server A + </VirtualHost> + <VirtualHost 111.22.33.55> + # server C + ... + </VirtualHost> + <VirtualHost 111.22.33.44> + # server B + ... + </VirtualHost> + <VirtualHost 111.22.33.55> + # server D + ... + </VirtualHost> + + NameVirtualHost 111.22.33.44 + NameVirtualHost 111.22.33.55 + +

+ + +

(To aid the readability of your configuration you should + prefer the left variant.)

+ +

After parsing the VirtualHost directive, the + vhost server is given a default Listen equal to the + port assigned to the first name in its VirtualHost + directive.

+ +

The complete list of names in the VirtualHost + directive are treated just like a ServerAlias (but + are not overridden by any ServerAlias statement) + if all names resolve to the same address set. Note that + subsequent Listen statements for this vhost will not + affect the ports assigned in the address set.

+ +

During initialization a list for each IP address is + generated and inserted into an hash table. If the IP address is + used in a NameVirtualHost directive the list + contains all name-based vhosts for the given IP address. If + there are no vhosts defined for that address the + NameVirtualHost directive is ignored and an error + is logged. For an IP-based vhost the list in the hash table is + empty.

+ +

Due to a fast hashing function the overhead of hashing an IP + address during a request is minimal and almost not existent. + Additionally the table is optimized for IP addresses which vary + in the last octet.

+ +

For every vhost various default values are set. In + particular:

+ +

If a vhost has no ServerAdmin, + Timeout, + KeepAliveTimeout, + KeepAlive, + MaxKeepAliveRequests, + ReceiveBufferSize, + or SendBufferSize + directive then the respective value is inherited from the + main_server. (That is, inherited from whatever the final + setting of that value is in the main_server.)
The "lookup defaults" that define the default directory + permissions for a vhost are merged with those of the + main_server. This includes any per-directory configuration + information for any module.
The per-server configs for each module from the + main_server are merged into the vhost server.

+ +

Essentially, the main_server is treated as "defaults" or a + "base" on which to build each vhost. But the positioning of + these main_server definitions in the config file is largely + irrelevant -- the entire config of the main_server has been + parsed when this final merging occurs. So even if a main_server + definition appears after a vhost definition it might affect the + vhost definition.

+ +

If the main_server has no ServerName at this + point, then the hostname of the machine that httpd + is running on is used instead. We will call the main_server address + set those IP addresses returned by a DNS lookup on the + ServerName of the main_server.

+ +

For any undefined ServerName fields, a + name-based vhost defaults to the address given first in the + VirtualHost statement defining the vhost.

+ +

Any vhost that includes the magic _default_ + wildcard is given the same ServerName as the + main_server.

+ +

Virtual Host Matching

+ +

The server determines which vhost to use for a request as + follows:

+ +

Hash table lookup

+ +

When the connection is first made by a client, the IP + address to which the client connected is looked up in the + internal IP hash table.

+ +

If the lookup fails (the IP address wasn't found) the + request is served from the _default_ vhost if + there is such a vhost for the port to which the client sent the + request. If there is no matching _default_ vhost + the request is served from the main_server.

+ +

If the IP address is not found in the hash table then the + match against the port number may also result in an entry + corresponding to a NameVirtualHost *, which is + subsequently handled like other name-based vhosts.

+ +

If the lookup succeeded (a corresponding list for the IP + address was found) the next step is to decide if we have to + deal with an IP-based or a name-base vhost.

+ + + +

IP-based vhost

+ +

If the entry we found has an empty name list then we have + found an IP-based vhost, no further actions are performed and + the request is served from that vhost.

+ + + +

Name-based vhost

+ +

If the entry corresponds to a name-based vhost the name list + contains one or more vhost structures. This list contains the + vhosts in the same order as the VirtualHost + directives appear in the config file.

+ +

The first vhost on this list (the first vhost in the config + file with the specified IP address) has the highest priority + and catches any request to an unknown server name or a request + without a Host: header field.

+ +

If the client provided a Host: header field the + list is searched for a matching vhost and the first hit on a + ServerName or ServerAlias is taken + and the request is served from that vhost. A Host: + header field can contain a port number, but Apache always + matches against the real port to which the client sent the + request.

+ +

If the client submitted a HTTP/1.0 request without + Host: header field we don't know to what server + the client tried to connect and any existing + ServerPath is matched against the URI from the + request. The first matching path on the list is used and the + request is served from that vhost.

+ +

If no matching vhost could be found the request is served + from the first vhost with a matching port number that is on the + list for the IP to which the client connected (as already + mentioned before).

+ + + +

Persistent connections

+ +

The IP lookup described above is only done once for a + particular TCP/IP session while the name lookup is done on + every request during a KeepAlive/persistent + connection. In other words a client may request pages from + different name-based vhosts during a single persistent + connection.

+ + + +

Absolute URI

+ +

If the URI from the request is an absolute URI, and its + hostname and port match the main server or one of the + configured virtual hosts and match the address and + port to which the client sent the request, then the + scheme/hostname/port prefix is stripped off and the remaining + relative URI is served by the corresponding main server or + virtual host. If it does not match, then the URI remains + untouched and the request is taken to be a proxy request.

+ + +

Observations

+ +

A name-based vhost can never interfere with an IP-base + vhost and vice versa. IP-based vhosts can only be reached + through an IP address of its own address set and never + through any other address. The same applies to name-based + vhosts, they can only be reached through an IP address of the + corresponding address set which must be defined with a + NameVirtualHost directive.
ServerAlias and ServerPath + checks are never performed for an IP-based vhost.
The order of name-/IP-based, the _default_ + vhost and the NameVirtualHost directive within + the config file is not important. Only the ordering of + name-based vhosts for a specific address set is significant. + The one name-based vhosts that comes first in the + configuration file has the highest priority for its + corresponding address set.
For security reasons the port number given in a + Host: header field is never used during the + matching process. Apache always uses the real port to which + the client sent the request.
If a ServerPath directive exists which is a + prefix of another ServerPath directive that + appears later in the configuration file, then the former will + always be matched and the latter will never be matched. (That + is assuming that no Host: header field was + available to disambiguate the two.)
If two IP-based vhosts have an address in common, the + vhost appearing first in the config file is always matched. + Such a thing might happen inadvertently. The server will give + a warning in the error logfile when it detects this.
A _default_ vhost catches a request only if + there is no other vhost with a matching IP address + and a matching port number for the request. The + request is only caught if the port number to which the client + sent the request matches the port number of your + _default_ vhost which is your standard + Listen by default. A wildcard port can be + specified (i.e., _default_:*) to catch + requests to any available port. This also applies to + NameVirtualHost * vhosts.
The main_server is only used to serve a request if the IP + address and port number to which the client connected is + unspecified and does not match any other vhost (including a + _default_ vhost). In other words the main_server + only catches a request for an unspecified address/port + combination (unless there is a _default_ vhost + which matches that port).
A _default_ vhost or the main_server is + never matched for a request with an unknown or + missing Host: header field if the client + connected to an address (and port) which is used for + name-based vhosts, e.g., in a + NameVirtualHost directive.
You should never specify DNS names in + VirtualHost directives because it will force + your server to rely on DNS to boot. Furthermore it poses a + security threat if you do not control the DNS for all the + domains listed. There's more + information available on this and the next two + topics.
ServerName should always be set for each + vhost. Otherwise A DNS lookup is required for each + vhost.

+ + +

Tips

+ +

In addition to the tips on the DNS Issues page, here are + some further tips:

+ +

Place all main_server definitions before any + VirtualHost definitions. (This is to aid the + readability of the configuration -- the post-config merging + process makes it non-obvious that definitions mixed in around + virtual hosts might affect all virtual hosts.)
Group corresponding NameVirtualHost and + VirtualHost definitions in your configuration to + ensure better readability.
Avoid ServerPaths which are prefixes of + other ServerPaths. If you cannot avoid this then + you have to ensure that the longer (more specific) prefix + vhost appears earlier in the configuration file than the + shorter (less specific) prefix (i.e., "ServerPath + /abc" should appear after "ServerPath /abc/def").

+ +