src - OpenBSD base system

diff options


context:
space:
mode:

author	Jason McIntyre <jmc@cvs.openbsd.org>	2005-07-28 19:12:40 +0000
committer	Jason McIntyre <jmc@cvs.openbsd.org>	2005-07-28 19:12:40 +0000
commit	9895c5987c272ab0aa2edc373e7656e93dd16041 (patch)
tree	3f13e87160f2bbb5b17eea7e3b937d1ca5dc2c56 /usr.sbin/httpd/htdocs/manual/vhosts
parent	628d31714800827769bef8e8a0b422444f1f5379 (diff)

from tamas tevesz:

==> some obsolete info regarding apache 1.2

Diffstat (limited to 'usr.sbin/httpd/htdocs/manual/vhosts')

-rw-r--r--

usr.sbin/httpd/htdocs/manual/vhosts/details_1_2.html

396

1 files changed, 0 insertions, 396 deletions

diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/details_1_2.html b/usr.sbin/httpd/htdocs/manual/vhosts/details_1_2.html
deleted file mode 100644
index f4717d3c5d8..00000000000
--- a/usr.sbin/httpd/htdocs/manual/vhosts/details_1_2.html
+++ /dev/null

@@ -1,396 +0,0 @@

-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

-<html xmlns="http://www.w3.org/1999/xhtml">

- <head>

- <meta name="generator" content="HTML Tidy, see www.w3.org" />

- <title>An In-Depth Discussion of VirtualHost Matching</title>

- </head>

-

- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"

- vlink="#000080" alink="#FF0000">

- <div align="CENTER">

- <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />

- <h3>Apache HTTP Server Version 1.3</h3>

- </div>

- <h1 align="CENTER">An In-Depth Discussion of VirtualHost

- Matching</h1>

- 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 <a href="#whatworks">What Works</a> section at

- the bottom.

- <h3>Config File Parsing</h3>

- There is a main_server which consists of all the definitions

- appearing outside of <code>VirtualHost</code> sections. There

- are virtual servers, called vhosts, which are defined

- by <a

- href="../mod/core.html#virtualhost"><samp>VirtualHost</samp></a>

- sections.

- The directives <a

- href="../mod/core.html#port"><samp>Port</samp></a>, <a

- href="../mod/core.html#servername"><samp>ServerName</samp></a>,

- <a

- href="../mod/core.html#serverpath"><samp>ServerPath</samp></a>,

- and <a

- href="../mod/core.html#serveralias"><samp>ServerAlias</samp></a>

- can appear anywhere within the definition of a server. However,

- each appearance overrides the previous appearance (within that

- server).

- The default value of the <code>Port</code> field for

- main_server is 80. The main_server has no default

- <code>ServerName</code>, <code>ServerPath</code>, or

- <code>ServerAlias</code>.

- In the absence of any <a

- href="../mod/core.html#listen"><samp>Listen</samp></a>

- directives, the (final if there are multiple) <code>Port</code>

- directive in the main_server indicates which port httpd will

- listen on.

- The <code>Port</code> and <code>ServerName</code> directives

- for any server main or virtual are used when generating URLs

- such as during redirects.

- Each address appearing in the <code>VirtualHost</code>

- directive can have an optional port. If the port is unspecified

- it defaults to the value of the main_server's most recent

- <code>Port</code> statement. The special port <samp>*</samp>

- indicates a wildcard that matches any port. Collectively the

- entire set of addresses (including multiple <samp>A</samp>

- record results from DNS lookups) are called the vhost's

- address set.

- The magic <code>_default_</code> address has significance

- during the matching algorithm. It essentially matches any

- unspecified address.

- After parsing the <code>VirtualHost</code> directive, the

- vhost server is given a default <code>Port</code> equal to the

- port assigned to the first name in its <code>VirtualHost</code>

- directive. The complete list of names in the

- <code>VirtualHost</code> directive are treated just like a

- <code>ServerAlias</code> (but are not overridden by any

- <code>ServerAlias</code> statement). Note that subsequent

- <code>Port</code> 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:

- <blockquote>

-<pre>

- <VirtualHost A>

- ...

- </VirtualHost>

- <VirtualHost B>

- ...

- </VirtualHost>

- <VirtualHost C>

- ...

- </VirtualHost>

-</pre>

- </blockquote>

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

- <ol>

- <li>If a vhost has no <a

- href="../mod/core.html#serveradmin"><code>ServerAdmin</code></a>,

- <a

- href="../mod/core.html#resourceconfig"><code>ResourceConfig</code></a>,

- <a

- href="../mod/core.html#accessconfig"><code>AccessConfig</code></a>,

- <a href="../mod/core.html#timeout"><code>Timeout</code></a>,

- <a

- href="../mod/core.html#keepalivetimeout"><code>KeepAliveTimeout</code></a>,

- <a

- href="../mod/core.html#keepalive"><code>KeepAlive</code></a>,

- <a

- href="../mod/core.html#maxkeepaliverequests"><code>MaxKeepAliveRequests</code></a>,

- or <a

- href="../mod/core.html#sendbuffersize"><code>SendBufferSize</code></a>

- 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.)</li>

- <li>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.</li>

- <li>The per-server configs for each module from the

- main_server are merged into the vhost server.</li>

- </ol>

- 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 <code>ServerName</code> 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

- <code>ServerName</code> of the main_server.

- Now a pass is made through the vhosts to fill in any missing

- <code>ServerName</code> 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 <code>Port</code>).

- Otherwise it is considered an IP-based vhost.

- For any undefined <code>ServerName</code> fields, a

- name-based vhost defaults to the address given first in the

- <code>VirtualHost</code> statement defining the vhost. Any

- vhost that includes the magic <samp>_default_</samp> wildcard

- is given the same <code>ServerName</code> as the main_server.

- Otherwise the vhost (which is necessarily an IP-based vhost) is

- given a <code>ServerName</code> based on the result of a

- reverse DNS lookup on the first address given in the

- <code>VirtualHost</code> statement.

- <h3>Vhost Matching</h3>

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

- <code>find_virtual_server</code>: 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 <samp>_default_</samp> address (which if you

- recall the ordering of the server list mentioned above means

- that this would be the first occurrence of

- <samp>_default_</samp> 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.

- <code>check_fulluri</code>: If the requestURI is an

- absoluteURI, that is it includes <code>http://hostname/</code>,

- 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 <code>ServerName</code> or the

- local IP address of the client's socket.

- <code>parse_uri</code>: If the URI begins with a protocol

- (i.e., <code>http:</code>, <code>ftp:</code>) then the

- request is considered a proxy request. Note that even though we

- may have stripped an <code>http://hostname/</code> in the

- previous step, this could still be a proxy request.

- <code>read_request</code>: If the request does not have a

- hostname from the earlier step, then any <code>Host:</code>

- header sent by the client is used as the request hostname.

- <code>check_hostalias</code>: 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 <code>Port</code> 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:

- <ul>

- <li>Compare the request hostname:port with the vhost

- <code>ServerName</code> and <code>Port</code>.</li>

- <li>Compare the request hostname against any and all

- addresses given in the <code>VirtualHost</code> directive for

- this vhost.</li>

- <li>Compare the request hostname against the

- <code>ServerAlias</code> given for the vhost.</li>

- </ul>

- <code>check_serverpath</code>: If the request has no

- hostname (back up a few paragraphs) then a scan similar to the

- one in <code>check_hostalias</code> is performed to match any

- <code>ServerPath</code> directives given in the vhosts. Note

- that the last match is used regardless (again

- consider the ordering of the virtual hosts).

- <h3>Observations</h3>

- <ul>

- <li>It is difficult to define an IP-based vhost for the

- machine's "main IP address". You essentially have to create a

- bogus <code>ServerName</code> for the main_server that does

- not match the machine's IPs.</li>

- <li>

- During the scans in both <code>check_hostalias</code> and

- <code>check_serverpath</code> 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 "<samp>Host: A</samp>" 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.

- </li>

- <li>

- Unless you have a <samp>_default_</samp> vhost, it doesn't

- matter if you mix name-based vhosts in amongst IP-based

- vhosts. During the <code>find_virtual_server</code> 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 <samp>_default_</samp> 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

- <samp>_default_</samp> vhost since none of the name-based

- are considered during <code>find_virtual_server</code>.

- </li>

- <li>You should never specify DNS names in

- <code>VirtualHost</code> 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. <a href="dns-caveats.html">There's more

- information available on this and the next two

- topics</a>.</li>

- <li><code>ServerName</code> should always be set for each

- vhost. Otherwise A DNS lookup is required for each

- vhost.</li>

- <li>A DNS lookup is always required for the main_server's

- <code>ServerName</code> (or to generate that if it isn't

- specified in the config).</li>

- <li>If a <code>ServerPath</code> directive exists which is a

- prefix of another <code>ServerPath</code> 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.)</li>

- <li>If a vhost that would otherwise be a name-vhost includes

- a <code>Port</code> statement that doesn't match the

- main_server <code>Port</code> then it will be considered an

- IP-based vhost. Then <code>find_virtual_server</code> 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 <code>check_hostalias</code> 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.</li>

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

- <code>ServerName</code> 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.</li>

- <li>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.</li>

- </ul>

- <h3><a id="whatworks" name="whatworks">What Works</a></h3>

- In addition to the tips on the <a

- href="../dns-caveats.html#tips">DNS Issues</a> page, here are some

- further tips:

- <ul>

- <li>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.)</li>

- <li>Arrange your VirtualHosts such that all name-based

- virtual hosts come first, followed by IP-based virtual hosts,

- followed by any <samp>_default_</samp> virtual host</li>

- <li>Avoid <code>ServerPaths</code> which are prefixes of

- other <code>ServerPaths</code>. 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").</li>

- <li>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).</li>

- </ul>

- <hr />

- <h3 align="CENTER">Apache HTTP Server Version 1.3</h3>

- <a href="./"><img src="../images/index.gif" alt="Index" /></a>

- <a href="../"><img src="../images/home.gif" alt="Home" /></a>

- </body>

-</html>