From b4e137218d2f03539bab2acd5ee1bc6759eeb999 Mon Sep 17 00:00:00 2001 From: Astrid Malo Date: Fri, 4 Oct 2002 15:04:27 +0000 Subject: [PATCH] removed due to convertion into xml git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@97100 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/vhosts/details.html | 392 ----------------- docs/manual/vhosts/examples.html | 722 ------------------------------- docs/manual/vhosts/ip-based.html | 139 ------ docs/manual/vhosts/mass.html | 442 ------------------- 4 files changed, 1695 deletions(-) delete mode 100644 docs/manual/vhosts/details.html delete mode 100644 docs/manual/vhosts/examples.html delete mode 100644 docs/manual/vhosts/ip-based.html delete mode 100644 docs/manual/vhosts/mass.html diff --git a/docs/manual/vhosts/details.html b/docs/manual/vhosts/details.html deleted file mode 100644 index a3e9c3025c..0000000000 --- a/docs/manual/vhosts/details.html +++ /dev/null @@ -1,392 +0,0 @@ - - - - - - - An In-Depth Discussion of Virtual Host Matching - - - - - - -

An In-Depth Discussion of Virtual Host - Matching

- -

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

- -

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 servers 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>
-  <VirtualHost 111.22.33.44>    | # server A
-  # server A                    | </VirtualHost>
-  ...                           | <VirtualHost 111.22.33.55>
-  </VirtualHost>                | # server C
-  <VirtualHost 111.22.33.44>    | ...
-  # server B                    | </VirtualHost>
-  ...                           | <VirtualHost 111.22.33.44>
-  </VirtualHost>                | # server B
-                                | ...
-  NameVirtualHost 111.22.33.55  | </VirtualHost>
-  <VirtualHost 111.22.33.55>    | <VirtualHost 111.22.33.55>
-  # server C                    | # server D
-  ...                           | ...
-  </VirtualHost>                | </VirtualHost>
-  <VirtualHost 111.22.33.55>    |
-  # server D                    | NameVirtualHost 111.22.33.44
-  ...                           | NameVirtualHost 111.22.33.55
-  </VirtualHost>                |
-                                |
-
- -

(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:

- -
    -
  1. If a vhost has no ServerAdmin, - ResourceConfig, - AccessConfig, - Timeout, - KeepAliveTimeout, - KeepAlive, - MaxKeepAliveRequests, - 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.)
    2. - -
  2. 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.
    3. - -
  3. The per-server configs for each module from the - main_server are merged into the vhost server.
    4. -
- 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

- - - -

Tips

- -

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

- - - - - - diff --git a/docs/manual/vhosts/examples.html b/docs/manual/vhosts/examples.html deleted file mode 100644 index df5fe970c4..0000000000 --- a/docs/manual/vhosts/examples.html +++ /dev/null @@ -1,722 +0,0 @@ - - - - - - - VirtualHost Examples - - - - - - -

Virtual Host examples for common setups

- -

This document attempts to answer the commonly-asked questions about - setting up virtual hosts. These scenarios are those involving multiple - web sites running on a single server, via name-based or IP-based virtual hosts. A document should be - coming soon about running sites on several servers behind a single - proxy server.

- -

Examples

- - - - - -

Additional features

- - -
- -

Running several name-based web - sites on a single IP address.

- - - -

Setup:

- -

Your server has a single IP address, and multiple aliases (CNAMES) - point to this machine in DNS. You want to run a web server for - www.example1.com and www.example2.org on this - machine.

- -
- - - - -
Note: Creating virtual - host configurations on your Apache server does not magically - cause DNS entries to be created for those host names. You - must have the names in DNS, resolving to your IP - address, or nobody else will be able to see your web site. You - can put entries in your hosts file for local - testing, but that will work only from the machine with those - hosts entries.
-
- -

Server configuration:

- -
- - - - -
-
-    # Ensure that Apache listens on port 80
-    Listen 80
-
-    # Listen for virtual host requests on all IP addresses
-    NameVirtualHost *
-
-    <VirtualHost *>
-        DocumentRoot /www/example1
-        ServerName www.example1.com
-
-        # Other directives here
-
-    </VirtualHost>
-    
-    <VirtualHost *>
-        DocumentRoot /www/example2
-        ServerName www.example2.org
-    
-        # Other directives here
-
-    </VirtualHost> 
-
-
-
- -

The asterisks match all addresses, so the main server serves no - requests. Due to the fact that www.example1.com is first - in the configuration file, it has the highest priority and can be seen - as the default or primary server. That means - that if a request is received that does not match one of the specified - ServerName directives, it will be served by this first - VirtualHost.

- -
- - - - -
- Note: - -

You can, if you wish, replace * with the actual - IP address of the system. In that case, the argument to - VirtualHost must match the argument to - NameVirtualHost:

- -
- - - - -
-
-    NameVirtualHost 172.20.30.40
-
-    <VirtualHost 172.20.30.40>
-        # etc ...
-
-
-
- -

However, it is additionally useful to use * - on systems where the IP address is not predictable - for - example if you have a dynamic IP address with your ISP, and - you are using some variety of dynamic DNS solution. Since - * matches any IP address, this configuration - would work without changes whenever your IP address - changes.

-
-
- -

The above configuration is what you will want to use in almost - all name-based virtual hosting situations. The only think that this - configuration will not work for, in fact, is when you are serving - different content based on differing IP addresses or ports.

- -
- -

Name-based hosts on more than one - IP address.

- -
- - - - -
Note: Any of the - techniques discussed here can be extended to any number of IP - addresses.
-
- Setup 1: - -

The server has two IP addresses. On one (172.20.30.40), we - will serve the "main" server, server.domain.com and on the - other (172.20.30.50), we will serve two or more virtual hosts.

- -

Server configuration:

- -
- - - - -
-
-    Listen 80
-
-    # This is the "main" server running on 172.20.30.40
-    ServerName server.domain.com
-    DocumentRoot /www/mainserver
-
-    # This is the other address
-    NameVirtualHost 172.20.30.50
-
-    <VirtualHost 172.20.30.50>
-        DocumentRoot /www/example1
-        ServerName www.example1.com
-    
-        # Other directives here ...
-
-    </VirtualHost>
-    
-    <VirtualHost 172.20.30.50>
-        DocumentRoot /www/example2
-        ServerName www.example2.org
-    
-        # Other directives here ...
-
-    </VirtualHost> 
-
-
-
- -

Any request to an address other than 172.20.30.50 will be - served from the main server. A request to 172.20.30.50 with an - unknown hostname, or no Host: header, will be served from - www.example1.com.

- -

Serving the same content on - different IP addresses (such as an internal and external - address).

- - Setup: - -

The server machine has two IP addresses (192.168.1.1 - and 172.20.30.40). The machine is sitting between an - internal (intranet) network and an external (internet) network. Outside - of the network, the name server.example.com resolves to - the external address (172.20.30.40), but inside the - network, that same name resolves to the internal address - (192.168.1.1).

- -

The server can be made to respond to internal and external requests - with the same content, with just one VirtualHost - section.

- -

Server configuration:

- -
- - - - -
-
-    NameVirtualHost 192.168.1.1
-    NameVirtualHost 172.20.30.40
-
-    <VirtualHost 192.168.1.1 172.20.30.40>
-        DocumentRoot /www/server1
-        ServerName server.example.com
-        ServerAlias server
-    </VirtualHost>
-
-
-
- -

Now requests from both networks will be served from the same - VirtualHost.

- -
- - - - -
- -

Note: On the internal - network, one can just use the name server rather - than the fully qualified host name - server.example.com.

- -

Note also that, in the above example, you can replace the list - of IP addresses with *, which will cause the server to - respond the same on all addresses.

- -
-
-
- -

Running different sites on different - ports.

- -

Setup:

- -

You have multiple domains going to the same IP and also want to - serve multiple ports. By defining the ports in the "NameVirtualHost" - tag, you can allow this to work. If you try using <VirtualHost - name:port> without the NameVirtualHost name:port or you try to use - the Listen directive, your configuration will not work.

- -

Server configuration:

- -
- - - - -
-
-    Listen 80
-    Listen 8080
-
-    NameVirtualHost 172.20.30.40:80
-    NameVirtualHost 172.20.30.40:8080
-
-    <VirtualHost 172.20.30.40:80>
-        ServerName www.example1.com
-        DocumentRoot /www/domain-80
-    </VirtualHost>
-
-    <VirtualHost 172.20.30.40:8080>
-        ServerName www.example1.com
-        DocumentRoot /www/domain-8080
-    </VirtualHost>
-
-    <VirtualHost 172.20.30.40:80>
-        ServerName www.example2.org
-        DocumentRoot /www/otherdomain-80
-    </VirtualHost>
-
-    <VirtualHost 172.20.30.40:8080>
-        ServerName www.example2.org
-        DocumentRoot /www/otherdomain-8080
-    </VirtualHost>
-
-
-
-
- -

IP-based virtual hosting

- -

Setup:

- -

The server has two IP addresses (172.20.30.40 and - 172.20.30.50) which resolve to the names - www.example1.com and www.example2.org - respectively.

- -

Server configuration:

- -
- - - - -
-
-    Listen 80
-
-    <VirtualHost 172.20.30.40>
-        DocumentRoot /www/example1
-        ServerName www.example1.com
-    </VirtualHost>
-   
-    <VirtualHost 172.20.30.50>
-        DocumentRoot /www/example2
-        ServerName www.example2.org
-    </VirtualHost>
-
-
-
- -

Requests for any address not specified in one of the - <VirtualHost> directives (such as - localhost, for example) will go to the main server, if - there is one.

-
- -

Mixed port-based and ip-based - virtual hosts

- -

Setup:

- -

The server machine has two IP addresses (172.20.30.40 and - 172.20.30.50) which resolve to the names - www.example1.com and www.example2.org - respectively. In each case, we want to run hosts on ports 80 and - 8080.

- -
- - - - -
-
-    Listen 172.20.30.40:80
-    Listen 172.20.30.40:8080
-    Listen 172.20.30.50:80
-    Listen 172.20.30.50:8080
-    
-    <VirtualHost 172.20.30.40:80>
-        DocumentRoot /www/example1-80
-        ServerName www.example1.com
-    </VirtualHost>
-
-    <VirtualHost 172.20.30.40:8080>
-        DocumentRoot /www/example1-8080
-        ServerName www.example1.com
-    </VirtualHost>
-    
-    <VirtualHost 172.20.30.50:80>
-        DocumentRoot /www/example2-80
-        ServerName www.example1.org
-    </VirtualHost>
-
-    <VirtualHost 172.20.30.50:8080>
-        DocumentRoot /www/example2-8080
-        ServerName www.example2.org
-    </VirtualHost>
-
-
-
-
- -

Mixed name-based and IP-based - vhosts

- -

Setup:

- -

On some of my addresses, I want to do name-based virtual hosts, and - on others, IP-based hosts.

- -

Server configuration:

- -
- - - - -
-
-    Listen 80
-
-    NameVirtualHost 172.20.30.40
-
-    <VirtualHost 172.20.30.40>
-        DocumentRoot /www/example1
-        ServerName www.example1.com
-    </VirtualHost>
-   
-    <VirtualHost 172.20.30.40>
-        DocumentRoot /www/example2
-        ServerName www.example2.org
-    </VirtualHost> 
-    
-    <VirtualHost 172.20.30.40>
-        DocumentRoot /www/example3
-        ServerName www.example3.net
-    </VirtualHost> 
-
-    # IP-based
-    <VirtualHost 172.20.30.50>
-        DocumentRoot /www/example4
-        ServerName www.example4.edu
-    </VirtualHost> 
-    
-    <VirtualHost 172.20.30.60>
-        DocumentRoot /www/example5
-        ServerName www.example5.gov
-    </VirtualHost>     
-
-
-
-
- -

Using _default_ - vhosts

- -

Setup 1:

- -

Catching every request to any unspecified IP address and - port, i.e., an address/port combination that is not used for - any other virtual host.

- -

Server configuration:

- -
- - - - -
-
-    <VirtualHost _default_:*>
-        DocumentRoot /www/default
-    </VirtualHost>
-
-
-
- -

Using such a default vhost with a wildcard port effectively prevents - any request going to the main server.

- -

A default vhost never serves a request that was sent to an - address/port that is used for name-based vhosts. If the request - contained an unknown or no Host: header it is always - served from the primary name-based vhost (the vhost for that - address/port appearing first in the configuration file).

- -

You can use AliasMatch or - RewriteRule - to rewrite any request to a single information page (or script).

- -

Setup 2:

- -

Same as setup 1, but the server listens on several ports and we want - to use a second _default_ vhost for port 80.

- -

Server configuration:

- -
- - - - -
-
-    <VirtualHost _default_:80>
-        DocumentRoot /www/default80
-        # ...
-    </VirtualHost>
-    
-    <VirtualHost _default_:*>
-        DocumentRoot /www/default
-        # ...
-    </VirtualHost>    
-
-
-
- -

The default vhost for port 80 (which must appear before any - default vhost with a wildcard port) catches all requests that were sent - to an unspecified IP address. The main server is never used to serve a - request.

- -

Setup 3:

- -

We want to have a default vhost for port 80, but no other default - vhosts.

- -

Server configuration:

- -
- - - - -
-
-    <VirtualHost _default_:80>
-    DocumentRoot /www/default
-    ...
-    </VirtualHost>
-
-
-
- -

A request to an unspecified address on port 80 is served from the - default vhost any other request to an unspecified address and port is - served from the main server.

-
- -

Migrating a name-based vhost to an - IP-based vhost

- -

Setup:

- -

The name-based vhost with the hostname - www.example2.org (from our name-based example, setup 2) should get its own IP - address. To avoid problems with name servers or proxies who cached the - old IP address for the name-based vhost we want to provide both - variants during a migration phase.
- The solution is easy, because we can simply add the new IP address - (172.20.30.50) to the VirtualHost - directive.

- -

Server configuration:

- -
- - - - -
-
-    Listen 80
-    ServerName www.example1.com
-    DocumentRoot /www/example1
-
-    NameVirtualHost 172.20.30.40
-
-    <VirtualHost 172.20.30.40 172.20.30.50>
-        DocumentRoot /www/example2
-        ServerName www.example2.org
-        # ...
-    </VirtualHost>
-   
-    <VirtualHost 172.20.30.40>
-        DocumentRoot /www/example3
-        ServerName www.example3.net
-        ServerAlias *.example3.net
-        # ...
-    </VirtualHost>
-
-
-
- -

The vhost can now be accessed through the new address (as an - IP-based vhost) and through the old address (as a name-based - vhost).

-
- -

Using the - ServerPath directive

- -

Setup:

- -

We have a server with two name-based vhosts. In order to match the - correct virtual host a client must send the correct Host: - header. Old HTTP/1.0 clients do not send such a header and Apache has - no clue what vhost the client tried to reach (and serves the request - from the primary vhost). To provide as much backward compatibility as - possible we create a primary vhost which returns a single page - containing links with an URL prefix to the name-based virtual - hosts.

- -

Server configuration:

- -
- - - - -
-
-    NameVirtualHost 172.20.30.40
-
-    <VirtualHost 172.20.30.40>
-        # primary vhost
-        DocumentRoot /www/subdomain
-        RewriteEngine On
-        RewriteRule ^/.* /www/subdomain/index.html
-        # ...
-    </VirtualHost>
-
-    <VirtualHost 172.20.30.40>
-    DocumentRoot /www/subdomain/sub1
-        ServerName www.sub1.domain.tld
-        ServerPath /sub1/
-        RewriteEngine On
-        RewriteRule ^(/sub1/.*) /www/subdomain$1 
-        # ...
-    </VirtualHost>
-
-    <VirtualHost 172.20.30.40>
-        DocumentRoot /www/subdomain/sub2
-        ServerName www.sub2.domain.tld
-        ServerPath /sub2/
-        RewriteEngine On
-        RewriteRule ^(/sub2/.*) /www/subdomain$1 
-        # ...
-    </VirtualHost>
-
-
-
- -

Due to the ServerPath - directive a request to the URL - http://www.sub1.domain.tld/sub1/ is always served - from the sub1-vhost.
- A request to the URL http://www.sub1.domain.tld/ is only - served from the sub1-vhost if the client sent a correct - Host: header. If no Host: header is sent the - client gets the information page from the primary host.
- Please note that there is one oddity: A request to - http://www.sub2.domain.tld/sub1/ is also served from the - sub1-vhost if the client sent no Host: header.
- The RewriteRule directives are used to make sure that a - client which sent a correct Host: header can use both URL - variants, i.e., with or without URL prefix.

- - - - diff --git a/docs/manual/vhosts/ip-based.html b/docs/manual/vhosts/ip-based.html deleted file mode 100644 index 7b8b908898..0000000000 --- a/docs/manual/vhosts/ip-based.html +++ /dev/null @@ -1,139 +0,0 @@ - - - - - - - Apache IP-based Virtual Host Support - - - - - - -

Apache IP-based Virtual Host Support

- See also: Name-based - Virtual Hosts Support -
- -

System requirements

- As the term IP-based indicates, the server - must have a different IP address for each IP-based - virtual host. This can be achieved by the machine - having several physical network connections, or by use of - virtual interfaces which are supported by most modern operating - systems (see system documentation for details, these are - frequently called "ip aliases", and the "ifconfig" command is - most commonly used to set them up). - -

How to set up Apache

- There are two ways of configuring apache to support multiple - hosts. Either by running a separate httpd daemon for each - hostname, or by running a single daemon which supports all the - virtual hosts. - -

Use multiple daemons when:

- - - Use a single daemon when: - - - -

Setting up multiple daemons

- Create a separate httpd installation for each virtual host. For - each installation, use the Listen directive in the - configuration file to select which IP address (or virtual host) - that daemon services. e.g. -
-    Listen www.smallco.com:80
-
- It is recommended that you use an IP address instead of a - hostname (see DNS caveats). - -

Setting up a single daemon with virtual hosts

- For this case, a single httpd will service requests for the - main server and all the virtual hosts. The VirtualHost directive - in the configuration file is used to set the values of ServerAdmin, ServerName, DocumentRoot, ErrorLog and TransferLog - or CustomLog - configuration directives to different values for each virtual - host. e.g. -
-    <VirtualHost www.smallco.com>
-    ServerAdmin webmaster@mail.smallco.com
-    DocumentRoot /groups/smallco/www
-    ServerName www.smallco.com
-    ErrorLog /groups/smallco/logs/error_log
-    TransferLog /groups/smallco/logs/access_log
-    </VirtualHost>
-
-    <VirtualHost www.baygroup.org>
-    ServerAdmin webmaster@mail.baygroup.org
-    DocumentRoot /groups/baygroup/www
-    ServerName www.baygroup.org
-    ErrorLog /groups/baygroup/logs/error_log
-    TransferLog /groups/baygroup/logs/access_log
-    </VirtualHost>
-
- It is recommended that you use an IP address instead of a - hostname (see DNS caveats). - -

Almost any configuration directive can be - put in the VirtualHost directive, with the exception of - directives that control process creation and a few other - directives. To find out if a directive can be used in the - VirtualHost directive, check the Context using the - directive index.

- -

User and Group may be used inside a - VirtualHost directive if the suEXEC - wrapper is used.

- -

SECURITY: When specifying where to write log files, - be aware of some security risks which are present if anyone - other than the user that starts Apache has write access to the - directory where they are written. See the security tips document - for details.

- - - - diff --git a/docs/manual/vhosts/mass.html b/docs/manual/vhosts/mass.html deleted file mode 100644 index 3ce888e462..0000000000 --- a/docs/manual/vhosts/mass.html +++ /dev/null @@ -1,442 +0,0 @@ - - - - - - - Dynamically configured mass virtual hosting - - - - - - -

Dynamically configured mass virtual - hosting

- -

This document describes how to efficiently serve an - arbitrary number of virtual hosts with Apache 1.3. -

- -

Contents:

- - -
- -

Motivation

- -

The techniques described here are of interest if your - httpd.conf contains many - <VirtualHost> sections that are - substantially the same, for example:

-
-NameVirtualHost 111.22.33.44
-<VirtualHost 111.22.33.44>
-    ServerName                 www.customer-1.com
-    DocumentRoot        /www/hosts/www.customer-1.com/docs
-    ScriptAlias  /cgi-bin/  /www/hosts/www.customer-1.com/cgi-bin
-</VirtualHost>
-<VirtualHost 111.22.33.44>
-    ServerName                 www.customer-2.com
-    DocumentRoot        /www/hosts/www.customer-2.com/docs
-    ScriptAlias  /cgi-bin/  /www/hosts/www.customer-2.com/cgi-bin
-</VirtualHost>
-# blah blah blah
-<VirtualHost 111.22.33.44>
-    ServerName                 www.customer-N.com
-    DocumentRoot        /www/hosts/www.customer-N.com/docs
-    ScriptAlias  /cgi-bin/  /www/hosts/www.customer-N.com/cgi-bin
-</VirtualHost>
-
-
-
- - -

The basic idea is to replace all of the static - <VirtualHost> configuration with a mechanism - that works it out dynamically. This has a number of - advantages:

- -
    -
  1. Your configuration file is smaller so Apache starts - faster and uses less memory.
    2. - -
  2. Adding virtual hosts is simply a matter of creating the - appropriate directories in the filesystem and entries in the - DNS - you don't need to reconfigure or restart Apache.
    3. -
-
-
- - -

The main disadvantage is that you cannot have a different - log file for each virtual host; however if you have very many - virtual hosts then doing this is dubious anyway because it eats - file descriptors. It is better to log to a pipe or a fifo and - arrange for the process at the other end to distribute the logs - to the customers (it can also accumulate statistics, etc.).

-
- -

Overview

- -

A virtual host is defined by two pieces of information: its - IP address, and the contents of the Host: header - in the HTTP request. The dynamic mass virtual hosting technique - is based on automatically inserting this information into the - pathname of the file that is used to satisfy the request. This - is done most easily using mod_vhost_alias, - but if you are using a version of Apache up to 1.3.6 then you - must use mod_rewrite. - Both of these modules are disabled by default; you must enable - one of them when configuring and building Apache if you want to - use this technique.

- -

A couple of things need to be `faked' to make the dynamic - virtual host look like a normal one. The most important is the - server name which is used by Apache to generate - self-referential URLs, etc. It is configured with the - ServerName directive, and it is available to CGIs - via the SERVER_NAME environment variable. The - actual value used at run time is controlled by the UseCanonicalName - setting. With UseCanonicalName Off the server name - comes from the contents of the Host: header in the - request. With UseCanonicalName DNS it comes from a - reverse DNS lookup of the virtual host's IP address. The former - setting is used for name-based dynamic virtual hosting, and the - latter is used for IP-based hosting. If Apache cannot work out - the server name because there is no Host: header - or the DNS lookup fails then the value configured with - ServerName is used instead.

- -

The other thing to `fake' is the document root (configured - with DocumentRoot and available to CGIs via the - DOCUMENT_ROOT environment variable). In a normal - configuration this setting is used by the core module when - mapping URIs to filenames, but when the server is configured to - do dynamic virtual hosting that job is taken over by another - module (either mod_vhost_alias or - mod_rewrite) which has a different way of doing - the mapping. Neither of these modules is responsible for - setting the DOCUMENT_ROOT environment variable so - if any CGIs or SSI documents make use of it they will get a - misleading value.

-
- -

Simple dynamic virtual - hosts

- -

This extract from httpd.conf implements the - virtual host arrangement outlined in the Motivation section above, but in a - generic fashion using mod_vhost_alias.

-
-# get the server name from the Host: header
-UseCanonicalName Off
-
-# this log format can be split per-virtual-host based on the first field
-LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
-CustomLog logs/access_log vcommon
-
-# include the server name in the filenames used to satisfy requests
-VirtualDocumentRoot /www/hosts/%0/docs
-VirtualScriptAlias  /www/hosts/%0/cgi-bin
-
- -

This configuration can be changed into an IP-based virtual - hosting solution by just turning UseCanonicalName - Off into UseCanonicalName DNS. The server - name that is inserted into the filename is then derived from - the IP address of the virtual host.

-
- -

A virtually hosted - homepages system

- -

This is an adjustment of the above system tailored for an - ISP's homepages server. Using a slightly more complicated - configuration we can select substrings of the server name to - use in the filename so that e.g. the documents for - www.user.isp.com are found in - /home/user/. It uses a single cgi-bin - directory instead of one per virtual host.

-
-# all the preliminary stuff is the same as above, then
-
-# include part of the server name in the filenames
-VirtualDocumentRoot /www/hosts/%2/docs
-
-# single cgi-bin directory
-ScriptAlias  /cgi-bin/  /www/std-cgi/
-
- -

There are examples of more complicated - VirtualDocumentRoot settings in the - mod_vhost_alias documentation.

-
- -

Using more than - one virtual hosting system on the same server

- -

With more complicated setups you can use Apache's normal - <VirtualHost> directives to control the - scope of the various virtual hosting configurations. For - example, you could have one IP address for homepages customers - and another for commercial customers with the following setup. - This can of course be combined with conventional - <VirtualHost> configuration sections.

-
-UseCanonicalName Off
-
-LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
-
-<Directory /www/commercial>
-    Options FollowSymLinks
-    AllowOverride All
-</Directory>
-
-<Directory /www/homepages>
-    Options FollowSymLinks
-    AllowOverride None
-</Directory>
-
-<VirtualHost 111.22.33.44>
-    ServerName www.commercial.isp.com
-
-    CustomLog logs/access_log.commercial vcommon
-
-    VirtualDocumentRoot /www/commercial/%0/docs
-    VirtualScriptAlias  /www/commercial/%0/cgi-bin
-</VirtualHost>
-
-<VirtualHost 111.22.33.45>
-    ServerName www.homepages.isp.com
-
-    CustomLog logs/access_log.homepages vcommon
-
-    VirtualDocumentRoot /www/homepages/%0/docs
-    ScriptAlias         /cgi-bin/ /www/std-cgi/
-</VirtualHost>
-
-
- -

More efficient IP-based - virtual hosting

- -

After the first example I noted that - it is easy to turn it into an IP-based virtual hosting setup. - Unfortunately that configuration is not very efficient because - it requires a DNS lookup for every request. This can be avoided - by laying out the filesystem according to the IP addresses - themselves rather than the corresponding names and changing the - logging similarly. Apache will then usually not need to work - out the server name and so incur a DNS lookup.

-
-# get the server name from the reverse DNS of the IP address
-UseCanonicalName DNS
-
-# include the IP address in the logs so they may be split
-LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon
-CustomLog logs/access_log vcommon
-
-# include the IP address in the filenames
-VirtualDocumentRootIP /www/hosts/%0/docs
-VirtualScriptAliasIP  /www/hosts/%0/cgi-bin
-
-
- -

Using older versions - of Apache

- -

The examples above rely on mod_vhost_alias - which appeared after version 1.3.6. If you are using a version - of Apache without mod_vhost_alias then you can - implement this technique with mod_rewrite as - illustrated below, but only for Host:-header-based virtual - hosts.

- -

In addition there are some things to beware of with logging. - Apache 1.3.6 is the first version to include the - %V log format directive; in versions 1.3.0 - 1.3.3 - the %v option did what %V does; - version 1.3.4 has no equivalent. In all these versions of - Apache the UseCanonicalName directive can appear - in .htaccess files which means that customers can - cause the wrong thing to be logged. Therefore the best thing to - do is use the %{Host}i directive which logs the - Host: header directly; note that this may include - :port on the end which is not the case for - %V.

-
- -

Simple dynamic - virtual hosts using mod_rewrite

- -

This extract from httpd.conf does the same - thing as the first example. The first - half is very similar to the corresponding part above but with - some changes for backward compatibility and to make the - mod_rewrite part work properly; the second half - configures mod_rewrite to do the actual work.

- -

There are a couple of especially tricky bits: By default, - mod_rewrite runs before the other URI translation - modules (mod_alias etc.) so if they are used then - mod_rewrite must be configured to accommodate - them. Also, mome magic must be performed to do a - per-dynamic-virtual-host equivalent of - ScriptAlias.

-
-# get the server name from the Host: header
-UseCanonicalName Off
-
-# splittable logs
-LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon
-CustomLog logs/access_log vcommon
-
-<Directory /www/hosts>
-    # ExecCGI is needed here because we can't force
-    # CGI execution in the way that ScriptAlias does
-    Options FollowSymLinks ExecCGI
-</Directory>
-
-# now for the hard bit
-
-RewriteEngine On
-
-# a ServerName derived from a Host: header may be any case at all
-RewriteMap  lowercase  int:tolower
-
-## deal with normal documents first:
-# allow Alias /icons/ to work - repeat for other aliases
-RewriteCond  %{REQUEST_URI}  !^/icons/
-# allow CGIs to work
-RewriteCond  %{REQUEST_URI}  !^/cgi-bin/
-# do the magic
-RewriteRule  ^/(.*)$  /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1
-
-## and now deal with CGIs - we have to force a MIME type
-RewriteCond  %{REQUEST_URI}  ^/cgi-bin/
-RewriteRule  ^/(.*)$  /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1  [T=application/x-httpd-cgi]
-
-# that's it!
-
-
- -

A - homepages system using mod_rewrite

- -

This does the same thing as the second - example.

-
-RewriteEngine on
-
-RewriteMap   lowercase  int:tolower
-
-# allow CGIs to work
-RewriteCond  %{REQUEST_URI}  !^/cgi-bin/
-
-# check the hostname is right so that the RewriteRule works
-RewriteCond  ${lowercase:%{SERVER_NAME}}  ^www\.[a-z-]+\.isp\.com$
-
-# concatenate the virtual host name onto the start of the URI
-# the [C] means do the next rewrite on the result of this one
-RewriteRule  ^(.+)  ${lowercase:%{SERVER_NAME}}$1  [C]
-
-# now create the real file name
-RewriteRule  ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2
-
-# define the global CGI directory
-ScriptAlias  /cgi-bin/  /www/std-cgi/
-
-
- -

Using a separate virtual - host configuration file

- -

This arrangement uses more advanced mod_rewrite - features to get the translation from virtual host to document - root from a separate configuration file. This provides more - flexibility but requires more complicated configuration.

- -

The vhost.map file contains something like - this:

-
-www.customer-1.com  /www/customers/1
-www.customer-2.com  /www/customers/2
-# ...
-www.customer-N.com  /www/customers/N
-
-
-
- - -

The http.conf contains this:

-
-RewriteEngine on
-
-RewriteMap   lowercase  int:tolower
-
-# define the map file
-RewriteMap   vhost      txt:/www/conf/vhost.map
-
-# deal with aliases as above
-RewriteCond  %{REQUEST_URI}               !^/icons/
-RewriteCond  %{REQUEST_URI}               !^/cgi-bin/
-RewriteCond  ${lowercase:%{SERVER_NAME}}  ^(.+)$
-# this does the file-based remap
-RewriteCond  ${vhost:%1}                  ^(/.*)$
-RewriteRule  ^/(.*)$                      %1/docs/$1
-
-RewriteCond  %{REQUEST_URI}               ^/cgi-bin/
-RewriteCond  ${lowercase:%{SERVER_NAME}}  ^(.+)$
-RewriteCond  ${vhost:%1}                  ^(/.*)$
-RewriteRule  ^/(.*)$                      %1/cgi-bin/$1
-
-
-
- - - - -- 2.40.0