Apache module mod_vhost_alias

### Apache HTTP Server Version 1.3

# Module mod_vhost_alias

This module provides support for dynamically configured mass virtual hosting.

Status: Extension
Source File: mod_vhost_alias.c
Module Identifier: vhost_alias_module
Compatibility: Available in Apache 1.3.7 and later.

## Summary

This module creates dynamically configured virtual hosts, by allowing the IP address and/or the `Host:` header of the HTTP request to be used as part of the pathname to determine what files to serve. This allows for easy use of a huge number of virtual hosts with similar configurations.

## Directives

- VirtualDocumentRoot
- VirtualDocumentRootIP
- VirtualScriptAlias
- VirtualScriptAliasIP

See also: UseCanonicalName.

## Directory Name Interpolation

All the directives in this module interpolate a string into a pathname. The interpolated string (henceforth called the "name") may be either the server name (see the `UseCanonicalName` directive for details on how this is determined) or the IP address of the virtual host on the server in dotted-quad format. The interpolation is controlled by specifiers inspired by `printf` which have a number of formats:

`%%`
  insert a `%`
`%p`
  insert the port number of the virtual host
`%N.M`
  insert (part of) the name

`N` and `M` are used to specify substrings of the name. `N` selects from the dot-separated components of the name, and `M` selects characters within whatever `N` has selected. `M` is optional and defaults to zero if it isn't present; the dot must be present if and only if `M` is present. The interpretation is as follows:

`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`

If `N` or `M` is greater than the number of parts available a single underscore is interpolated.

### Examples

For simple name-based virtual hosts you might use the following directives in your server configuration file:

        UseCanonicalName    Off
        VirtualDocumentRoot /usr/local/apache/vhosts/%0

A request for `http://www.example.com/directory/file.html` will be satisfied by the file `/usr/local/apache/vhosts/www.example.com/directory/file.html`.

For a very large number of virtual hosts it is a good idea to arrange the files to reduce the size of the `vhosts` directory. To do this you might use the following in your configuration file:

        UseCanonicalName    Off
        VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2

A request for `http://www.example.isp.com/directory/file.html` will be satisfied by the file `/usr/local/apache/vhosts/isp.com/e/x/a/example/directory/file.html`. A more even spread of files can be achieved by hashing from the end of the name, for example:

        VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2

The example request would come from `/usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html`. Alternatively you might use:

        VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+

The example request would come from `/usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html`.

For IP-based virtual hosting you might use the following in your configuration file:

        UseCanonicalName DNS
        VirtualDocumentRootIP   /usr/local/apache/vhosts/%1/%2/%3/%4/docs
        VirtualScriptAliasIP    /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin

A request for `http://www.example.isp.com/directory/file.html` would be satisfied by the file `/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html` if the IP address of `www.example.com` were 10.20.30.40. A request for `http://www.example.isp.com/cgi-bin/script.pl` would be satisfied by executing the program `/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl`.

If you want to include the `.` character in a `VirtualDocumentRoot` directive, but it clashes with a `%` directive, you can work around the problem in the following way:

        VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0

A request for `http://www.example.isp.com/directory/file.html` will be satisfied by the file `/usr/local/apache/vhosts/example.isp/directory/file.html`.

The LogFormat directives `%V` and `%A` are useful in conjunction with this module.

## VirtualDocumentRoot directive

Syntax: VirtualDocumentRoot interpolated-directory
Default: None
Context: server config, virtual host
Status: Extension
Module: mod_vhost_alias
Compatibility: VirtualDocumentRoot is only available in 1.3.7 and later.

The `VirtualDocumentRoot` directive allows you to determine where Apache will find your documents based on the value of the server name. The result of expanding interpolated-directory is used as the root of the document tree in a similar manner to the `DocumentRoot` directive's argument. If interpolated-directory is `none` then `VirtualDocumentRoot` is turned off. This directive cannot be used in the same context as `VirtualDocumentRootIP`.

## VirtualDocumentRootIP directive

Syntax: VirtualDocumentRootIP interpolated-directory
Default: None
Context: server config, virtual host
Status: Extension
Module: mod_vhost_alias
Compatibility: VirtualDocumentRootIP is only available in 1.3.7 and later.

The `VirtualDocumentRootIP` directive is like the `VirtualDocumentRoot` directive, except that it uses the IP address of the server end of the connection instead of the server name.

## VirtualScriptAlias directive

Syntax: VirtualScriptAlias interpolated-directory
Default: None
Context: server config, virtual host
Status: Extension
Module: mod_vhost_alias
Compatibility: VirtualScriptAlias is only available in 1.3.7 and later.

The `VirtualScriptAlias` directive allows you to determine where Apache will find CGI scripts in a similar manner to `VirtualDocumentRoot` does for other documents. It matches requests for URIs starting `/cgi-bin/`, much like `ScriptAlias /cgi-bin/` would.

## VirtualScriptAliasIP directive

Syntax: VirtualScriptAliasIP interpolated-directory
Default: None
Context: server config, virtual host
Status: Extension
Module: mod_vhost_alias
Compatibility: VirtualScriptAliasIP is only available in 1.3.7 and later.

The `VirtualScriptAliasIP` directive is like the `VirtualScriptAlias` directive, except that it uses the IP address of the server end of the connection instead of the server name.

### Apache HTTP Server Version 1.3