From: Martin Kraemer Date: Tue, 11 Nov 1997 23:47:21 +0000 (+0000) Subject: Citing Lars: X-Git-Tag: APACHE_1_3b3~9 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=eff734582b272a5c5be7a148a19a705b7d4face9;p=apache Citing Lars: Hi, the attachment includes a reworked Apache manual with the new virtual host documentation. As Dean suggested I created a new directory named 'vhosts' and moved the updated vhosts-in-depth etc. documents into the new directory, renamed them and updated all other documents which refered to the old docs (at least I tried to find all documents...). Submitted by: Lars Eilebrecht Reviewed by: Martin Kraemer git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@79568 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/bind.html b/docs/manual/bind.html index 9253168138..2398082a14 100644 --- a/docs/manual/bind.html +++ b/docs/manual/bind.html @@ -95,8 +95,7 @@ not listening to, it cannot be accessed.

Apache Server Frequently Asked Questions

- $Revision: 1.93 $ ($Date: 1997/11/06 14:52:47 $) + $Revision: 1.94 $ ($Date: 1997/11/11 23:47:15 $)

The latest version of this FAQ is always available from the main @@ -254,7 +254,7 @@

Is Apache Year 2000 compliant?
I upgraded to Apache 1.3b2 and now my +
I upgraded to Apache 1.3b and now my virtual hosts don't work!

Apache Week

Apache-specific books

- I upgraded to Apache 1.3b2 and now my virtual hosts don't + I upgraded to Apache 1.3b and now my virtual hosts don't work!
@@ -2150,6 +2153,11 @@ contain ServerName and possibly ServerAlias directives so Apache can be sure to tell them apart correctly.
+
+ Please see the + Apache + Virtual Host documentation for further details about configuration. +

diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html index f00afe78e5..30c12d2f15 100644 --- a/docs/manual/mod/core.html +++ b/docs/manual/mod/core.html @@ -57,6 +57,7 @@ always available.
MaxRequestsPerChild
MaxSpareServers
MinSpareServers +
NameVirtualHost
Options
PidFile
Port @@ -252,7 +253,7 @@ control over which address and ports Apache listens to, use the BindAddress.
BindAddress can be used as an alternative method for -supporting virtual hosts using +supporting virtual hosts using multiple independent servers, instead of using <VirtualHost> sections. @@ -1111,6 +1112,34 @@ Setting this parameter to a large number is almost always a bad idea.
See also MaxSpareServers and StartServers.
+
NameVirtualHost directive
+ +Syntax: NameVirtualHost addr[:port]
+Context: server config
+Status: core
+Compatibility: NameVirtualHost is only available in Apache 1.3 and later
+ +The NameVirtualHost directive is a required directive if you want to configure +name-based virtual hosts.
+ +Although addr can be hostname it is recommended that you always use +an IP address, e.g. + +
NameVirtualHost 111.22.33.44
+ +With the NameVirtualHost directive the address to which your name-based +virtual host names resolve. +If you have multiple name-based hosts on multiple addresses, +repeat the directive for each address.
+ +Optionally you can specify a port number on which the name-based +virtual hosts should be used, e.g. + +
NameVirtualHost 111.22.33.44:8080
+ +See also: +Apache Virtual Host documentation +
Options directive
Syntax: Options [+|-]option [+|-]option ...
@@ -1490,9 +1519,10 @@ as users do not always mention that they are talking about the server!
The ServerAlias directive sets the alternate names for a host, for use with -Host-header based virtual hosts. -
See Also: -In-depth description of Virtual Host matching
+name-based virtual hosts. + +
See also: +Apache Virtual Host documentation
@@ -1522,9 +1552,11 @@ were monster.wibble.com.
1.1 and later.
The ServerPath directive sets the legacy URL pathname for a host, for -use with Host-header based virtual hosts. -
See Also: -In-depth description of Virtual Host matching
+use with name-based virtual hosts. + +
See also: +Apache Virtual Host documentation +

ServerRoot directive
@@ -1742,14 +1774,9 @@ either BindAddress or Listen.
See also: -Warnings about DNS and Apache
-See also: -Information on Virtual Hosts. -(multihome)
+Apache Virtual Host documentation
See also: -Non-IP address-based Virtual Hosts
-See also: -In-depth description of Virtual Host matching
+Warnings about DNS and Apache
See also: Setting which addresses and ports Apache uses
See also: How Directory, diff --git a/docs/manual/vhosts/details.html b/docs/manual/vhosts/details.html new file mode 100644 index 0000000000..0e992170c3 --- /dev/null +++ b/docs/manual/vhosts/details.html @@ -0,0 +1,367 @@ + + +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 +Port, +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 Port 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 Port directive has two functions due to legacy +compatibility with NCSA configuration files. One function is +to determine the default network port Apache will bind to. This +default is overridden by the existence of any +Listen directives. +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 Port 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. + +
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. + +
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 Port 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 Port statements for this vhost will not affect +the ports assigned in the address set. + +
During initialization a list for each IP address +is generated an 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, + 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.) + +
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 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 that appears after the +corresponding NameVirtualHost directive in the config file) +has the highest priority and catches any request to an unknown +server name or a request without a Host: header. + +
If the client provided a Host: header 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 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 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 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 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 catched if the port number + to which the client sent the request matches the port number of your + _default_ vhost which is your standard Port + by default. A wildcard port can be specified (i.e. + _default_:*) to catch requests to any available port. +
+ +
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 + 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"). +
+ +
+ + + + diff --git a/docs/manual/vhosts/details_1_2.html b/docs/manual/vhosts/details_1_2.html new file mode 100644 index 0000000000..d2339bff81 --- /dev/null +++ b/docs/manual/vhosts/details_1_2.html @@ -0,0 +1,396 @@ + + +An In-Depth Discussion of VirtualHost Matching + + + + + +
An In-Depth Discussion of VirtualHost Matching
+ +
This is a very rough document that was probably out of date the moment +it was written. It attempts to explain exactly what the code does when +deciding what virtual host to serve a hit from. It's provided on the +assumption that something is better than nothing. The server version +under discussion is Apache 1.2. + +
If you just want to "make it work" without understanding +how, there's a What Works section at the bottom. + +
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 +Port, +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 Port field for main_server +is 80. The main_server has no default ServerName, +ServerPath, or ServerAlias. + +
In the absence of any +Listen +directives, the (final if there +are multiple) Port directive in the main_server indicates +which port httpd will listen on. + +
The Port and ServerName directives for +any server main or virtual are used when generating URLs such as during +redirects. + +
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 Port 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. + +
The magic _default_ address has significance during +the matching algorithm. It essentially matches any unspecified address. + +
After parsing the VirtualHost directive, the vhost server +is given a default Port 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). Note that subsequent Port +statements for this vhost will not affect the ports assigned in the +address set. + +
+All vhosts are stored in a list which is in the reverse order that +they appeared in the config file. For example, if the config file is: + +
+ <VirtualHost A> + ... + </VirtualHost> + + <VirtualHost B> + ... + </VirtualHost> + + <VirtualHost C> + ... + </VirtualHost> +
+ +Then the list will be ordered: main_server, C, B, A. Keep this in mind. + +
+After parsing has completed, the list of servers is scanned, and various +merges and default values are set. In particular: + +
+
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.) + +
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. + +
Now a pass is made through the vhosts to fill in any missing +ServerName fields and to classify the vhost as either +an IP-based vhost or a name-based vhost. A vhost is +considered a name-based vhost if any of its address set overlaps the +main_server (the port associated with each address must match the +main_server's Port). Otherwise it is considered an IP-based +vhost. + +
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. Otherwise the vhost (which is necessarily an IP-based +vhost) is given a ServerName based on the result of a reverse +DNS lookup on the first address given in the VirtualHost +statement. + +
+ +
Vhost Matching
+ + +
Apache 1.3 differs from what is documented +here, and documentation still has to be written. + +
+The server determines which vhost to use for a request as follows: + +
find_virtual_server: When the connection is first made +by the client, the local IP address (the IP address to which the client +connected) is looked up in the server list. A vhost is matched if it +is an IP-based vhost, the IP address matches and the port matches +(taking into account wildcards). + +
If no vhosts are matched then the last occurrence, if it appears, +of a _default_ address (which if you recall the ordering of the +server list mentioned above means that this would be the first occurrence +of _default_ in the config file) is matched. + +
In any event, if nothing above has matched, then the main_server is +matched. + +
The vhost resulting from the above search is stored with data +about the connection. We'll call this the connection vhost. +The connection vhost is constant over all requests in a particular TCP/IP +session -- that is, over all requests in a KeepAlive/persistent session. + +
For each request made on the connection the following sequence of +events further determines the actual vhost that will be used to serve +the request. + +
check_fulluri: If the requestURI is an absoluteURI, that +is it includes http://hostname/, then an attempt is made to +determine if the hostname's address (and optional port) match that of +the connection vhost. If it does then the hostname portion of the URI +is saved as the request_hostname. If it does not match, then the +URI remains untouched. Note: to achieve this address +comparison, +the hostname supplied goes through a DNS lookup unless it matches the +ServerName or the local IP address of the client's socket. + +
parse_uri: If the URI begins with a protocol +(i.e., http:, ftp:) then the request is +considered a proxy request. Note that even though we may have stripped +an http://hostname/ in the previous step, this could still +be a proxy request. + +
read_request: If the request does not have a hostname +from the earlier step, then any Host: header sent by the +client is used as the request hostname. + +
check_hostalias: If the request now has a hostname, +then an attempt is made to match for this hostname. The first step +of this match is to compare any port, if one was given in the request, +against the Port field of the connection vhost. If there's +a mismatch then the vhost used for the request is the connection vhost. +(This is a bug, see observations.) + +
+If the port matches, then httpd scans the list of vhosts starting with +the next server after the connection vhost. This scan does not +stop if there are any matches, it goes through all possible vhosts, +and in the end uses the last match it found. The comparisons performed +are as follows: + +
+
Compare the request hostname:port with the vhost + ServerName and Port. + +
Compare the request hostname against any and all addresses given in + the VirtualHost directive for this vhost. + +
Compare the request hostname against the ServerAlias + given for the vhost. +
+ +
+check_serverpath: If the request has no hostname +(back up a few paragraphs) then a scan similar to the one +in check_hostalias is performed to match any +ServerPath directives given in the vhosts. Note that the +last match is used regardless (again consider the ordering of +the virtual hosts). + +
Observations
+ +
+ +
It is difficult to define an IP-based vhost for the machine's + "main IP address". You essentially have to create a bogus + ServerName for the main_server that does not match the + machine's IPs. +
+ +
During the scans in both check_hostalias and + check_serverpath no check is made that the vhost being + scanned is actually a name-based vhost. This means, for example, that + it's possible to match an IP-based vhost through another address. But + because the scan starts in the vhost list at the first vhost that + matched the local IP address of the connection, not all IP-based vhosts + can be matched. +
+ Consider the config file above with three vhosts A, B, C. Suppose + that B is a named-based vhost, and A and C are IP-based vhosts. If + a request comes in on B or C's address containing a header + "Host: A" then + it will be served from A's config. If a request comes in on A's + address then it will always be served from A's config regardless of + any Host: header. +
+ +
Unless you have a _default_ vhost, + it doesn't matter if you mix name-based vhosts in amongst IP-based + vhosts. During the find_virtual_server phase above no + named-based vhost will be matched, so the main_server will remain the + connection vhost. Then scans will cover all vhosts in the vhost list. +
+ If you do have a _default_ vhost, then you cannot place + named-based vhosts after it in the config. This is because on any + connection to the main server IPs the connection vhost will always be + the _default_ vhost since none of the name-based are + considered during find_virtual_server. +
+ +
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. +
+ +
A DNS lookup is always required for the main_server's + ServerName (or to generate that if it isn't specified + in the config). +
+ +
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 was available to disambiguate the two.) +
+ +
If a vhost that would otherwise be a name-vhost includes a + Port statement that doesn't match the main_server + Port then it will be considered an IP-based vhost. + Then find_virtual_server will match it (because + the ports associated with each address in the address set default + to the port of the main_server) as the connection vhost. Then + check_hostalias will refuse to check any other name-based + vhost because of the port mismatch. The result is that the vhost + will steal all hits going to the main_server address. +
+ +
If two IP-based vhosts have an address in common, the vhost appearing + later in the file is always matched. Such a thing might happen + inadvertently. If the config has name-based vhosts and for some reason + the main_server ServerName resolves to the wrong address + then all the name-based vhosts will be parsed as ip-based vhosts. + Then the last of them will steal all the hits. +
+ +
The last name-based vhost in the config is always matched for any hit + which doesn't match one of the other name-based vhosts. + +
+ +
What Works
+ +
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 +virtualhosts might affect all virtualhosts.) +
+ +
Arrange your VirtualHosts such +that all name-based virtual hosts come first, followed by IP-based +virtual hosts, followed by any _default_ virtual host +
+ +
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 /abcdef"). +
+ +
Do not use port-based vhosts in the same server as +name-based vhosts. A loose definition for port-based is a vhost which +is determined by the port on the server (i.e., one server with +ports 8000, 8080, and 80 - all of which have different configurations). +
+ +
+ + + + diff --git a/docs/manual/vhosts/examples.html b/docs/manual/vhosts/examples.html new file mode 100644 index 0000000000..c537f06dbb --- /dev/null +++ b/docs/manual/vhosts/examples.html @@ -0,0 +1,512 @@ + + +VirtualHost Examples + + + + + +
Virtual Host examples for common setups
+ + +
Base configuration
+ +
+
IP-based vhosts only +
Name-based vhosts only +
Mixed name-/IP-based vhosts +
Port-based vhosts +
+ +
Additional features
+ +
+
Using _default_ vhosts +
Migrating a named-based vhost to an IP-based vhost +
Using the ServerPath directive +
+ +
+ +
IP-based vhosts only
+ +
+ +
Setup 1: + The server machine has two IP addresses (111.22.33.44 + and 111.22.33.55) + which resolve to the names server.domain.tld and + www.otherdomain.tld respectively. + The hostname www.domain.tld is an alias (CNAME) + for server.domain.tld and will represent the + main server. +
+ Server configuration: + + +
+ ... + Port 80 + DocumentRoot /www/domain + ServerName www.domain.tld + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> +
+ www.otherdomain.tld can only be reached through the + address 111.22.33.55, while www.domain.tld + can only be reached through 111.22.33.44 + (which represents our main server). +
+
+ +
Setup 2: + Same as setup 1, but we don't want to have a dedicated main server. +
+ Server configuration: + +
+ ... + Port 80 + ServerName server.domain.tld + + <VirtualHost 111.22.33.44> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> +
+ The main server can never catch a request, because all IP address + of our machine are in use for IP-based virtual hosts + (only localhost requests can hit the main server). +
+
+ +
Setup 3: + The server machine has two IP addresses (111.22.33.44 + and 111.22.33.55) + which resolve to the names server.domain.tld and + www-cache.domain.tld respectively. + The hostname www.domain.tld is an alias (CNAME) + for server.domain.tld and will represent the + main server. + www-cache.domain.tld will become our proxy-cache + listening on port 8080, while the web server itself uses the default + port 80. +
+ Server configuration: + +
+ ... + Port 80 + Listen 111.22.33.44:80 + Listen 111.22.33.55:8080 + ServerName server.domain.tld + + <VirtualHost 111.22.33.44:80> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55:8080> + ServerName www-cache.domain.tld + ... + <Directory proxy:> + order deny,allow + deny from all + allow from 111.22.33 + </Directory> + </VirtualHost> +
+ The main server can never catch a request, because all IP addresss + (apart from localhost) of our machine are in use for IP-based + virtual hosts. The web server can only be reached on the first address + through port 80 and the proxy only on the second address through port 8080. +
+
+
+ +
Name-based vhosts only
+ +
+ +
Setup 1: + The server machine has one IP address (111.22.33.44) + which resolves to the name server.domain.tld. + There are two aliases (CNAMEs) www.domain.tld and + www.sub.domain.tld for the address 111.22.33.44. +
+ Server configuration: + +
+ ... + Port 80 + ServerName server.domain.tld + + NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain + ServerName www.sub.domain.tld + ... + </VirtualHost> +
+ Apart from localhost there are no unspecified + addresses/ports, therefore the main server only serves + localhost requests. Due to the fact + that www.domain.tld has the highest priority + it can be seen as the default or + primary server. +
+
+ +
Setup 2: + The server machine has two IP addresses (111.22.33.44 + and 111.22.33.55) + which resolve to the names server1.domain.tld and + server2.domain.tld respectively. + The alias www.domain.tld should be used for the + main server which should also catch any unspecified addresses. + We want to use a virtual host for the alias + www.otherdomain.tld and one virtual host should + catch any request to hostnames of the form + *.sub.domain.tld with www.sub.domain.tld + as its server name. The address 111.22.33.55 should be + used for the virtual hosts. +
+ Server configuration: + +
+ ... + Port 80 + ServerName www.domain.tld + DocumentRoot /www/domain + + NameVirtualHost 111.22.33.55 + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/subdomain + ServerName www.sub.domain.tld + ServerAlias *.sub.domain.tld + ... + </VirtualHost> +
+ Any request to an address other than 111.22.33.55 + will be served from the main server. A request to + 111.22.33.55 with an unknown or no Host: + header will be served from www.otherdomain.tld. +
+
+ +
+ +
Mixed name-/IP-based vhosts
+ +
+ +
Setup: + The server machine has three IP addresses (111.22.33.44, + 111.22.33.55 and 111.22.33.66) + which resolve to the names server.domain.tld, + www.otherdomain1.tld and www.otherdomain2.tld + respectively. + The address 111.22.33.44 should we used for a couple + of name-based vhosts and the other addresses for IP-based vhosts. +
+ Server configuration: + +
+ ... + Port 80 + ServerName server.domain.tld + + NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + DocumentRoot /www/domain + ServerName www.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain1 + ServerName www.sub1.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain2 + ServerName www.sub2.domain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/otherdomain1 + ServerName www.otherdomain1.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.66> + DocumentRoot /www/otherdomain2 + ServerName www.otherdomain2.tld + ... + </VirtualHost> +
+ +
+ +
+ +
Port-based vhosts
+ +
+ +
Setup: + The server machine has one IP address (111.22.33.44) + which resolves to the name www.domain.tld. + If we don't have the option to get another address or alias + for our server we can use port-based vhosts if we need + a virtual host with a different configuration. +
+ Server configuration: + +
+ ... + Listen 80 + Listen 8080 + ServerName www.domain.tld + DocumentRoot /www/domain + + <VirtualHost 111.22.33.44:8080> + DocumentRoot /www/domain2 + ... + </VirtualHost> +
+ A request to www.domain.tld on port 80 is served + from the main server and a request to port 8080 is served from + the virtual host. +
+
+ +
+ +
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.otherdomain.tld (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 + (111.22.33.66) to the VirtualHost directive. +
+ Server configuration: + +
+ ... + Port 80 + ServerName www.domain.tld + DocumentRoot /www/domain + + NameVirtualHost 111.22.33.55 + + <VirtualHost 111.22.33.55 111.22.33.66> + DocumentRoot /www/otherdomain + ServerName www.otherdomain.tld + ... + </VirtualHost> + + <VirtualHost 111.22.33.55> + DocumentRoot /www/subdomain + ServerName www.sub.domain.tld + ServerAlias *.sub.domain.tld + ... + </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 111.22.33.44 + + <VirtualHost 111.22.33.44> + # primary vhost + DocumentRoot /www/subdomain + RewriteEngine On + RewriteRule ^/.* /www/subdomain/index.html + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + DocumentRoot /www/subdomain/sub1 + ServerName www.sub1.domain.tld + ServerPath /sub1/ + RewriteEngine On + RewriteRule ^(/sub1/.*) /www/subdomain$1 + ... + </VirtualHost> + + <VirtualHost 111.22.33.44> + 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/fd-limits.html b/docs/manual/vhosts/fd-limits.html new file mode 100644 index 0000000000..77f4d8254d --- /dev/null +++ b/docs/manual/vhosts/fd-limits.html @@ -0,0 +1,59 @@ + + + +Apache Server Virtual Host Support + + + + + +
File Descriptor Limits
+ +
+When using a large number of Virtual Hosts, Apache may run out of available +file descriptors (sometimes called file handles if each Virtual +Host specifies different log files. +The total number of file descriptors used by Apache is one for each distinct +error log file, one for every other log file directive, plus 10-20 for +internal use. Unix operating systems limit the number of file descriptors that +may be used by a process; the limit is typically 64, and may usually be +increased up to a large hard-limit. +
+Although Apache attempts to increase the limit as required, this +may not work if: +
+
Your system does not provide the setrlimit() system call. +
The setrlimit(RLIMIT_NOFILE) call does not function on your system + (such as Solaris 2.3) +
The number of file descriptors required exceeds the hard limit. +
Your system imposes other limits on file descriptors, such as a limit +on stdio streams only using file descriptors below 256. (Solaris 2) +
+ +In the event of problems you can: +
+
Reduce the number of log files; don't specify log files in the VirtualHost +sections, but only log to the main log files. +
If you system falls into 1 or 2 (above), then increase the file descriptor +limit before starting Apache, using a script like +
+#!/bin/sh +ulimit -S -n 100 +exec httpd
+
+
+Please see the +Descriptors and Apache +document containing further details about file descriptor problems and how +they can be solved on your operating system. +
+ + + + diff --git a/docs/manual/vhosts/fd-limits.html.en b/docs/manual/vhosts/fd-limits.html.en new file mode 100644 index 0000000000..77f4d8254d --- /dev/null +++ b/docs/manual/vhosts/fd-limits.html.en @@ -0,0 +1,59 @@ + + + +Apache Server Virtual Host Support + + + + + +
File Descriptor Limits
+ +
+When using a large number of Virtual Hosts, Apache may run out of available +file descriptors (sometimes called file handles if each Virtual +Host specifies different log files. +The total number of file descriptors used by Apache is one for each distinct +error log file, one for every other log file directive, plus 10-20 for +internal use. Unix operating systems limit the number of file descriptors that +may be used by a process; the limit is typically 64, and may usually be +increased up to a large hard-limit. +
+Although Apache attempts to increase the limit as required, this +may not work if: +
+
Your system does not provide the setrlimit() system call. +
The setrlimit(RLIMIT_NOFILE) call does not function on your system + (such as Solaris 2.3) +
The number of file descriptors required exceeds the hard limit. +
Your system imposes other limits on file descriptors, such as a limit +on stdio streams only using file descriptors below 256. (Solaris 2) +
+ +In the event of problems you can: +
+
Reduce the number of log files; don't specify log files in the VirtualHost +sections, but only log to the main log files. +
If you system falls into 1 or 2 (above), then increase the file descriptor +limit before starting Apache, using a script like +
+#!/bin/sh +ulimit -S -n 100 +exec httpd
+
+
+Please see the +Descriptors and Apache +document containing further details about file descriptor problems and how +they can be solved on your operating system. +
+ + + + diff --git a/docs/manual/vhosts/footer.html b/docs/manual/vhosts/footer.html new file mode 100644 index 0000000000..c82d24e722 --- /dev/null +++ b/docs/manual/vhosts/footer.html @@ -0,0 +1,6 @@ +
+
+ Apache HTTP Server Version 1.3 +
+ + diff --git a/docs/manual/vhosts/header.html b/docs/manual/vhosts/header.html new file mode 100644 index 0000000000..c0959dc7aa --- /dev/null +++ b/docs/manual/vhosts/header.html @@ -0,0 +1,6 @@ +
+ +
+ Apache HTTP Server Version 1.3 +
+
diff --git a/docs/manual/vhosts/index.html b/docs/manual/vhosts/index.html new file mode 100644 index 0000000000..0b1a22678e --- /dev/null +++ b/docs/manual/vhosts/index.html @@ -0,0 +1,58 @@ + + + +Apache Virtual Host documentation + + + + + +
Apache Virtual Host documentation
+ +
The term Virtual Host refers to the practice of maintaining +more than one server on one machine, as differentiated by their apparent +hostname. For example, it is often desirable for companies sharing a +web server to have their own domains, with web servers accessible as +www.company1.com and www.company2.com, +without requiring the user to know any extra path information.
+ +
Apache was one of the first servers to support IP-based +virtual hosts right out of the box. Versions 1.1 and later of +Apache support both, IP-based and name-based virtual hosts (vhosts). +The latter variant of virtual hosts is sometimes also called host-based or +non-IP virtual hosts.
+ +
Below is a list of documentation pages which explain all details +of virtual host support in Apache version 1.3 and later.
+ +
+ +
Virtual Host Support
+ +
+
IP-based Virtual Hosts +
Name-based Virtual Hosts +
Virtual Host examples for common setups +
In-Depth Discussion of Virtual Host Matching +
File Descriptor Limits +
+ +
Configuration directives
+ +
+
<VirtualHost> +
NameVirtualHost +
ServerName +
ServerAlias +
ServerPath +
+ + + + diff --git a/docs/manual/vhosts/index.html.en b/docs/manual/vhosts/index.html.en new file mode 100644 index 0000000000..0b1a22678e --- /dev/null +++ b/docs/manual/vhosts/index.html.en @@ -0,0 +1,58 @@ + + + +Apache Virtual Host documentation + + + + + +
Apache Virtual Host documentation
+ +
The term Virtual Host refers to the practice of maintaining +more than one server on one machine, as differentiated by their apparent +hostname. For example, it is often desirable for companies sharing a +web server to have their own domains, with web servers accessible as +www.company1.com and www.company2.com, +without requiring the user to know any extra path information.
+ +
Apache was one of the first servers to support IP-based +virtual hosts right out of the box. Versions 1.1 and later of +Apache support both, IP-based and name-based virtual hosts (vhosts). +The latter variant of virtual hosts is sometimes also called host-based or +non-IP virtual hosts.
+ +
Below is a list of documentation pages which explain all details +of virtual host support in Apache version 1.3 and later.
+ +
+ +
Virtual Host Support
+ +
+
IP-based Virtual Hosts +
Name-based Virtual Hosts +
Virtual Host examples for common setups +
In-Depth Discussion of Virtual Host Matching +
File Descriptor Limits +
+ +
Configuration directives
+ +
+
<VirtualHost> +
NameVirtualHost +
ServerName +
ServerAlias +
ServerPath +
+ + + + diff --git a/docs/manual/vhosts/ip-based.html b/docs/manual/vhosts/ip-based.html new file mode 100644 index 0000000000..e1cc14ff05 --- /dev/null +++ b/docs/manual/vhosts/ip-based.html @@ -0,0 +1,129 @@ + + + +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). + +
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: +
+
The different virtual hosts need very different httpd configurations, such + as different values for: ServerType, + User, + Group, + TypesConfig or + ServerRoot. +
The machine does not process a very high request rate. +
+Use a single daemon when: +
+
Sharing of the httpd configuration between virtual hosts is acceptable. +
The machine services a large number of requests, and so the performance + loss in running separate daemons may be significant. +
+ +
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 page). + +
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 page). + +
+ +Almost any configuration directive can be put +in the VirtualHost directive, with the exception of +ServerType, +StartServers, +MaxSpareServers, +MinSpareServers, +MaxRequestsPerChild, +BindAddress, +Listen, +PidFile, +TypesConfig, +ServerRoot and +NameVirtualHost. +
+User and +Group maybe 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/name-based.html b/docs/manual/vhosts/name-based.html new file mode 100644 index 0000000000..f26dd5f8ed --- /dev/null +++ b/docs/manual/vhosts/name-based.html @@ -0,0 +1,141 @@ + + +Apache name-based Virtual Hosts + + + + + +
Apache name-based Virtual Host Support
+ +See Also: +IP-based Virtual Host Support + +
+ +
Name-based vs. IP-based virtual hosts
+ +
While the approach with IP-based virtual hosts works still very well, +it is not the most elegant solution, because a dedicated IP address +is needed for every virtual host and it is hard to implement on some +machines. The HTTP/1.1 protocol contains a method for the +server to identify what name it is being addressed as. Apache 1.1 and +later support this approach as well as the traditional +IP-address-per-hostname method.
+ +
The benefits of using the new name-based virtual host support is a +practically unlimited number of servers, ease of configuration and use, and +requires no additional hardware or software. +The main disadvantage is that the client must support this part of the +protocol. The latest versions of most browsers do, but there are still +old browsers in use who do not. This can cause problems, although a possible +solution is addressed below.
+ +
Using non-IP Virtual Hosts
+ +
Using the new virtual hosts is quite easy, and superficially looks +like the old method. You simply add to one of the Apache configuration +files (most likely httpd.conf or srm.conf) +code similar to the following:
+
+ NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + ServerName www.domain.tld + DocumentRoot /web/domain + </VirtualHost> +
+ +
The notable difference between IP-based and name-based virtual host +configuration is the +NameVirtualHost +directive which specifies any IP address that should be used as a target for +name-based virtual hosts. + +
Of course, any additional directives can (and should) be placed +into the <VirtualHost> section. To make this work, +all that is needed is to make sure that the name +www.domain.tld is an alias (CNAME) pointing to the IP address +111.22.33.44
+ +
Additionally, many servers may wish to be accessible by more than +one name. For example, the example server might want to be accessible +as domain.tld, or www2.domain.tld, assuming +the IP addresses pointed to the same server. In fact, one might want it +so that all addresses at domain.tld were picked up by the +server. This is possible with the +ServerAlias +directive, placed inside the <VirtualHost> section. For +example:
+ +
+ ServerAlias domain.tld *.domain.tld +
+ +
Note that you can use * and ? as wild-card +characters.
+ +
You also might need ServerAlias if you are +serving local users who do not always include the domain name. +For example, if local users are +familiar with typing "www" or "www.foobar" then you will need to add +ServerAlias www www.foobar. It isn't possible for the +server to know what domain the client uses for their name resolution +because the client doesn't provide that information in the request.
+ +
Compatibility with Older Browsers
+ +
As mentioned earlier, there are still some clients in use who +do not send the required data for the name-based virtual hosts to work +properly. These clients will always be sent the pages from the +primary name-based virtual host (the first virtual host +appearing in the configuration file for a specific IP address).
+ +
There is a possible workaround with the +ServerPath +directive, albeit a slightly cumbersome one:
+ +
Example configuration: + +
+ NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + ServerName www.domain.tld + ServerPath /domain + DocumentRoot /web/domain + </VirtualHost> +
+ +
What does this mean? It means that a request for any URI beginning +with "/domain" will be served from the virtual host +www.domain.tld This means that the pages can be accessed as +http://www.domain.tld/domain/ for all clients, although +clients sending a Host: header can also access it as +http://www.domain.tld/.
+ +
In order to make this work, put a link on your primary virtual host's page +to http://www.domain.tld/domain/ +Then, in the virtual host's pages, be sure to use either purely +relative links (e.g. "file.html" or +"../icons/image.gif" or links containing the prefacing +/domain/ +(e.g. "http://www.domain.tld/domain/misc/file.html" or +"/domain/misc/file.html").
+ +
This requires a bit of +discipline, but adherence to these guidelines will, for the most part, +ensure that your pages will work with all browsers, new and old.
+ +
See also: ServerPath configuration +example
+ + + + diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en new file mode 100644 index 0000000000..f26dd5f8ed --- /dev/null +++ b/docs/manual/vhosts/name-based.html.en @@ -0,0 +1,141 @@ + + +Apache name-based Virtual Hosts + + + + + +
Apache name-based Virtual Host Support
+ +See Also: +IP-based Virtual Host Support + +
+ +
Name-based vs. IP-based virtual hosts
+ +
While the approach with IP-based virtual hosts works still very well, +it is not the most elegant solution, because a dedicated IP address +is needed for every virtual host and it is hard to implement on some +machines. The HTTP/1.1 protocol contains a method for the +server to identify what name it is being addressed as. Apache 1.1 and +later support this approach as well as the traditional +IP-address-per-hostname method.
+ +
The benefits of using the new name-based virtual host support is a +practically unlimited number of servers, ease of configuration and use, and +requires no additional hardware or software. +The main disadvantage is that the client must support this part of the +protocol. The latest versions of most browsers do, but there are still +old browsers in use who do not. This can cause problems, although a possible +solution is addressed below.
+ +
Using non-IP Virtual Hosts
+ +
Using the new virtual hosts is quite easy, and superficially looks +like the old method. You simply add to one of the Apache configuration +files (most likely httpd.conf or srm.conf) +code similar to the following:
+
+ NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + ServerName www.domain.tld + DocumentRoot /web/domain + </VirtualHost> +
+ +
The notable difference between IP-based and name-based virtual host +configuration is the +NameVirtualHost +directive which specifies any IP address that should be used as a target for +name-based virtual hosts. + +
Of course, any additional directives can (and should) be placed +into the <VirtualHost> section. To make this work, +all that is needed is to make sure that the name +www.domain.tld is an alias (CNAME) pointing to the IP address +111.22.33.44
+ +
Additionally, many servers may wish to be accessible by more than +one name. For example, the example server might want to be accessible +as domain.tld, or www2.domain.tld, assuming +the IP addresses pointed to the same server. In fact, one might want it +so that all addresses at domain.tld were picked up by the +server. This is possible with the +ServerAlias +directive, placed inside the <VirtualHost> section. For +example:
+ +
+ ServerAlias domain.tld *.domain.tld +
+ +
Note that you can use * and ? as wild-card +characters.
+ +
You also might need ServerAlias if you are +serving local users who do not always include the domain name. +For example, if local users are +familiar with typing "www" or "www.foobar" then you will need to add +ServerAlias www www.foobar. It isn't possible for the +server to know what domain the client uses for their name resolution +because the client doesn't provide that information in the request.
+ +
Compatibility with Older Browsers
+ +
As mentioned earlier, there are still some clients in use who +do not send the required data for the name-based virtual hosts to work +properly. These clients will always be sent the pages from the +primary name-based virtual host (the first virtual host +appearing in the configuration file for a specific IP address).
+ +
There is a possible workaround with the +ServerPath +directive, albeit a slightly cumbersome one:
+ +
Example configuration: + +
+ NameVirtualHost 111.22.33.44 + + <VirtualHost 111.22.33.44> + ServerName www.domain.tld + ServerPath /domain + DocumentRoot /web/domain + </VirtualHost> +
+ +
What does this mean? It means that a request for any URI beginning +with "/domain" will be served from the virtual host +www.domain.tld This means that the pages can be accessed as +http://www.domain.tld/domain/ for all clients, although +clients sending a Host: header can also access it as +http://www.domain.tld/.
+ +
In order to make this work, put a link on your primary virtual host's page +to http://www.domain.tld/domain/ +Then, in the virtual host's pages, be sure to use either purely +relative links (e.g. "file.html" or +"../icons/image.gif" or links containing the prefacing +/domain/ +(e.g. "http://www.domain.tld/domain/misc/file.html" or +"/domain/misc/file.html").
+ +
This requires a bit of +discipline, but adherence to these guidelines will, for the most part, +ensure that your pages will work with all browsers, new and old.
+ +
See also: ServerPath configuration +example
+ + + +

See also

See also

The "main server" Address

The _default_ Address

Apache Server Frequently Asked Questions

Config File Parsing

Virtual Host Matching

Hash table lookup

IP-based vhost

Name-based vhost

Persistent connections

Absolute URI

Observations

Tips

An In-Depth Discussion of VirtualHost Matching

Config File Parsing

Vhost Matching

Observations

Virtual Host examples for common setups

Base configuration

Additional features

File Descriptor Limits

File Descriptor Limits

+ Apache HTTP Server Version 1.3 +

+ Apache HTTP Server Version 1.3 +

Apache Virtual Host documentation

Virtual Host Support

Configuration directives

Apache Virtual Host documentation

Virtual Host Support

Configuration directives

Apache IP-based Virtual Host Support

System requirements

How to set up Apache

Setting up multiple daemons

Setting up a single daemon with virtual hosts

Apache name-based Virtual Host Support

Name-based vs. IP-based virtual hosts

Using non-IP Virtual Hosts

Compatibility with Older Browsers

Apache name-based Virtual Host Support

Name-based vs. IP-based virtual hosts

Using non-IP Virtual Hosts

Compatibility with Older Browsers