src - OpenBSD base system

diff options


context:
space:
mode:

author	Jason McIntyre <jmc@cvs.openbsd.org>	2005-07-28 19:18:10 +0000
committer	Jason McIntyre <jmc@cvs.openbsd.org>	2005-07-28 19:18:10 +0000
commit	5f9f09bbbe24108b1e8d876bde48c582eb7a0cda (patch)
tree	f13b28b953ce1d5d8dfe4de1610fff459e23cf57 /usr.sbin
parent	9895c5987c272ab0aa2edc373e7656e93dd16041 (diff)

from tamas tevesz:

==> duplicate of the files of the same name in manual/vhosts/, save formatting and one extra remark in manual/vhosts/vhosts-in-depth.html. no references to either.

Diffstat (limited to 'usr.sbin')

-rw-r--r--

usr.sbin/httpd/htdocs/manual/host.html

185

-rw-r--r--

usr.sbin/httpd/htdocs/manual/vhosts-in-depth.html

398

-rw-r--r--

usr.sbin/httpd/htdocs/manual/virtual-host.html

216

3 files changed, 0 insertions, 799 deletions

diff --git a/usr.sbin/httpd/htdocs/manual/host.html b/usr.sbin/httpd/htdocs/manual/host.html
deleted file mode 100644
index 74639a5b5fb..00000000000
--- a/usr.sbin/httpd/htdocs/manual/host.html
+++ /dev/null

@@ -1,185 +0,0 @@

-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

-<html><head>

-<title>Apache non-IP Virtual Hosts</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.2

- </H3>

-</DIV>

-<h1 ALIGN="CENTER">Apache non-IP Virtual Hosts</h1>

-<strong>See Also:</strong>

-<a href="virtual-host.html">Virtual Host Support</a>

-<hr>

-<h2>What is a Virtual Host</h2>

-<p>The "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

-<code>www.company1.com</code> and <code>www.company2.com</code>,

-without requiring the user to know any extra path information.</p>

-<p>Apache was one of the first servers to support virtual hosts right

-out of the box, but since the base <code>HTTP</code> (HyperText

-Transport Protocol) standard does not allow any method for the server

-to determine the hostname it is being addressed as, Apache's virtual

-host support has required a separate IP address for each

-server. Documentation on using this approach (which still works very

-well) <a href="virtual-host.html">is available</a>.

-<p>While the approach described above works, with the available IP

-address space growing smaller, and the number of domains increasing,

-it is not the most elegant solution, and is hard to implement on some

-machines. The <code>HTTP/1.1</code> 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.</p>

-<p>The benefits of using the new 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 user's browser must support this part of the protocol. The

-latest versions of many browsers (including Netscape Navigator 2.0 and

-later) do, but many browsers, especially older ones, do not. This can

-cause problems, although a possible solution is addressed below.</p>

-<h2>Using non-IP Virtual Hosts</h2>

-<p>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 <code>httpd.conf</code> or <code>srm.conf</code>)

-code similar to the following:</p>

-<pre>

- <VirtualHost www.apache.org>

- ServerName www.apache.org

- DocumentRoot /usr/web/apache

- </VirtualHost>

-</pre>

-<p>Of course, any additional directives can (and should) be placed

-into the <code><VirtualHost></code> section. To make this work,

-all that is needed is to make sure that the <code>www.apache.org</code>

-DNS entry points to the same IP address as the main

-server. Optionally, you could simply use that IP address in the

-<VirtualHost> entry.</p>

-<p>Additionally, many servers may wish to be accessible by more than

-one name. For example, the Apache server might want to be accessible

-as <code>apache.org</code>, or <code>ftp.apache.org</code>, assuming

-the IP addresses pointed to the same server. In fact, one might want it

-so that all addresses at <code>apache.org</code> were picked up by the

-server. This is possible with the <code>ServerAlias</code>

-directive, placed inside the <VirtualHost> section. For

-example:</p>

-<pre>

- ServerAlias apache.org *.apache.org

-</pre>

-<p>Note that you can use <code>*</code> and <code>?</code> as wild-card

-characters.</p>

-<p>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.physics" then you will need to add

-<code>ServerAlias www www.physics</code>. 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.</p>

-<h2>Security Considerations</h2>

-Apache allows all virtual hosts to be made accessible via the

-<code>Host:</code> header through all IP interfaces, even those which

-are configured to use different IP interfaces. For example, if the

-configuration for <code>www.foo.com</code> contained a virtual host

-section for <code>www.bar.com</code>, and <code>www.bar.com</code> was

-a separate IP interface, such that

-non-<code>Host:</code>-header-supporting browsers can use it, as

-before with Apache 1.0. If a request is made to

-<code>www.foo.com</code> and the request includes the header

-<code>Host: www.bar.com</code>, a page from <code>www.bar.com</code>

-will be sent.

-<P>

-This is a security concern if you are controlling access to a

-particular server based on IP-layer controls, such as from within a

-firewall or router. Let's say <code>www.bar.com</code> in the above

-example was instead an intra-net server called

-<code>private.foo.com</code>, and the router used by foo.com only let

-internal users access <code>private.foo.com</code>. Obviously,

-<code>Host:</code> header functionality now allows someone who has

-access to <code>www.foo.com</code> to get

-<code>private.foo.com</code>, if they send a <code>Host:

-private.foo.com</code> header. It is important to note that this

-condition exists only if you only implement this policy at the IP

-layer - all security controls used by Apache (i.e., <A

-HREF="mod/mod_access.html">allow, deny from,</A> etc.) are consistently

-respected.

-<h2>Compatibility with Older Browsers</h2>

-<p>As mentioned earlier, a majority of browsers do not send the

-required data for the new virtual hosts to work properly. These

-browsers will always be sent to the main server's pages. There is a

-workaround, albeit a slightly cumbersome one:</p>

-<p>To continue the <code>www.apache.org</code> example (Note: Apache's

-web server does not actually function in this manner), we might use the

-new <code>ServerPath</code> directive in the <code>www.apache.org</code> virtual host,

-for example:

-<pre>

- ServerPath /apache

-</pre>

-<p>What does this mean? It means that a request for any file beginning

-with "<code>/apache</code>" will be looked for in the Apache

-docs. This means that the pages can be accessed as

-<code>http://www.apache.org/apache/</code> for all browsers, although

-new browsers can also access it as

-<code>http://www.apache.org/</code>.</p>

-<p>In order to make this work, put a link on your main server's page

-to <code>http://www.apache.org/apache/</code> (Note: Do not use

-<code>http://www.apache.org/</code> - this would create an endless

-loop). Then, in the virtual host's pages, be sure to use either purely

-relative links (e.g. "<code>file.html</code>" or

-"<code>../icons/image.gif</code>" or links containing the prefacing

-<code>/apache/</code>

-(e.g. "<code>http://www.apache.org/apache/file.html</code>" or

-"<code>/apache/docs/1.1/index.html</code>").</p>

-<p>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. When

-a new browser contacts <code>http://www.apache.org/</code>, they will

-be directly taken to the Apache pages. Older browsers will be able to

-click on the link from the main server, go to

-<code>http://www.apache.org/apache/</code>, and then access the

-pages.</p>

-<HR>

-<H3 ALIGN="CENTER">

- Apache HTTP Server Version 1.2

-</H3>

-<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A>

-</BODY>

-</HTML>

diff --git a/usr.sbin/httpd/htdocs/manual/vhosts-in-depth.html b/usr.sbin/httpd/htdocs/manual/vhosts-in-depth.html
deleted file mode 100644
index 0f87f775ed6..00000000000
--- a/usr.sbin/httpd/htdocs/manual/vhosts-in-depth.html
+++ /dev/null

@@ -1,398 +0,0 @@

-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

-<html><head>

-<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.2

- </H3>

-</DIV>

-<h1 ALIGN="CENTER">An In-Depth Discussion of VirtualHost Matching</h1>

-<p>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.

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

-<p>There is a main_server which consists of all the definitions appearing

-outside of <CODE>VirtualHost</CODE> sections. There are virtual servers,

-called <EM>vhosts</EM>, which are defined by

-<A

- HREF="mod/core.html#virtualhost"

-><SAMP>VirtualHost</SAMP></A>

-sections.

-<p>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).

-<p>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>.

-<p>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.

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

-any server main or virtual are used when generating URLs such as during

-redirects.

-<p> 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 <EM>address set</EM>.

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

-the matching algorithm. It essentially matches any unspecified address.

-<p> 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.

-<p>

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

-<p>

-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>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>The per-server configs for each module from the main_server are

- merged into the vhost server.

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

-<p> 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 <EM>main_server address set</EM> those IP

-addresses returned by a DNS lookup on the <code>ServerName</code> of

-the main_server.

-<p> 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 <EM>IP-based</EM> vhost or a <EM>name-based</EM> 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.

-<p> 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.

-<p>

-<h3>Vhost Matching</h3>

-<p>

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

-<p> <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).

-<p> 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.

-<p> In any event, if nothing above has matched, then the main_server is

-matched.

-<p> The vhost resulting from the above search is stored with data

-about the connection. We'll call this the <EM>connection vhost</EM>.

-The connection vhost is constant over all requests in a particular TCP/IP

-session -- that is, over all requests in a KeepAlive/persistent session.

-<p> 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.

-<p> <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 <EM>request_hostname</EM>. If it does not match, then the

-URI remains untouched. <STRONG>Note</STRONG>: 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.

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

-(<EM>i.e.</EM>, <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.

-<p> <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.

-<p> <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.)

-<p>

-If the port matches, then httpd scans the list of vhosts starting with

-the next server <STRONG>after</STRONG> 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>Compare the request hostname against any and all addresses given in

- the <code>VirtualHost</code> directive for this vhost.

-<li>Compare the request hostname against the <code>ServerAlias</code>

- given for the vhost.

-</ul>

-<p>

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

-<STRONG>last match</STRONG> 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>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.

- <p>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.

- </p>

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

- <p>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>.

- </p>

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

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

- A DNS lookup is required for each vhost.</p>

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

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

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

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

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

-</ul>

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

-<p>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.)

-<p>

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

-<p>

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

-(<EM>i.e.</EM>, "ServerPath /abc" should appear after

-"ServerPath /abcdef").

-<p>

-<li>Do not use <i>port-based</i> 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 (<em>i.e.</em> one server with

-ports 8000, 8080, and 80 all of which have different configurations).

-<p>

-</ul>

-<HR>

-<H3 ALIGN="CENTER">

- Apache HTTP Server Version 1.2

-</H3>

-<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A>

-</BODY>

-</HTML>

diff --git a/usr.sbin/httpd/htdocs/manual/virtual-host.html b/usr.sbin/httpd/htdocs/manual/virtual-host.html
deleted file mode 100644
index d21ac708fd8..00000000000
--- a/usr.sbin/httpd/htdocs/manual/virtual-host.html
+++ /dev/null

@@ -1,216 +0,0 @@

-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

-<html>

-<head>

-<title>Apache Server Virtual Host Support</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.2

- </H3>

-</DIV>

-<h1 ALIGN="CENTER">Virtual Host Support</h1>

-<strong>See Also:</strong>

-<a href="host.html">Non-IP based virtual hosts</a>

-<h2>What are virtual hosts?</h2>

-This is the ability of a single machine to be a web server for multiple

-domains. For example, an Internet service provider might have a machine

-called <code>www.serve.com</code> which provides Web space for several

-organizations including, say, <em>smallco</em> and <em>baygroup</em>.

-Ordinarily, these groups would be given parts of the Web tree on www.serve.com.

-So smallco's home page would have the URL

-<blockquote>

-http://www.serve.com/smallco/

-</blockquote>

-and baygroup's home page would have the URL

-<blockquote>

-http://www.serve.com/baygroup/

-</blockquote>

-<p>

-For esthetic reasons, however, both organizations would rather their home

-pages appeared under their own names rather than that of the service

-provider's; but they do not want to set up their own Internet links and

-servers.

-<p>

-Virtual hosts are the solution to this problem. smallco and baygroup would

-have their own Internet name registrations, <code>www.smallco.com</code> and

-<code>www.baygroup.org</code> respectively. These hostnames would both

-correspond to the service provider's machine (www.serve.com). Thus

-smallco's home page would now have the URL

-<blockquote>

-http://www.smallco.com/

-</blockquote>

-and baygroup's home page would would have the URL

-<blockquote>

-http://www.baygroup.org/

-</blockquote>

-<h2>System requirements</h2>

-Due to limitations in the HTTP/1.0 protocol, the web server <strong>must have a

-different IP address for each virtual host</strong>. This can be achieved

-by the machine having several physical network connections, or by use

-of a <a href="misc/vif-info.html">virtual interface</a> on some operating systems.

-<h2>How to set up Apache</h2>

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

-<p>

-Use multiple daemons when:

-<ul>

-<li>The different virtual hosts need very different httpd configurations, such

- as different values for: <A HREF="mod/core.html#servertype">ServerType</A>,

- <A HREF="mod/core.html#user">User</A>,

- <A HREF="mod/core.html#group">Group</A>,

- <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A> or

- <A HREF="mod/core.html#serverroot">ServerRoot</A>.

-<li>The machine does not process a very high request rate.

-</ul>

-Use a single daemon when:

-<ul>

-<li>Sharing of the httpd configuration between virtual hosts is acceptable.

-<li>The machine services a large number of requests, and so the performance

- loss in running separate daemons may be significant.

-</ul>

-<h2>Setting up multiple daemons</h2>

-Create a separate httpd installation for each virtual host.

-For each installation, use the

-<A HREF="mod/core.html#bindaddress">BindAddress</A> directive in the configuration

-file to select which IP address (or virtual host) that daemon services.

-e.g.

-<blockquote><code>BindAddress www.smallco.com</code></blockquote>

-This hostname can also be given as an IP address.

-<h2>Setting up a single daemon</h2>

-For this case, a single httpd will service requests for all the virtual hosts.

-The <A HREF="mod/core.html#virtualhost">VirtualHost</A> directive in the

- configuration file is used to set the values of

-<A HREF="mod/core.html#serveradmin">ServerAdmin</A>,

-<A HREF="mod/core.html#servername">ServerName</A>,

-<A HREF="mod/core.html#documentroot">DocumentRoot</A>,

-<A HREF="mod/core.html#errorlog">ErrorLog</A> and

-<A HREF="mod/mod_log_common.html#transferlog">TransferLog</A> configuration

-directives to different values for each virtual host.

-e.g.

-<blockquote><code>

-<VirtualHost www.smallco.com><br>

-ServerAdmin webmaster@mail.smallco.com<br>

-DocumentRoot /groups/smallco/www<br>

-ServerName www.smallco.com<br>

-ErrorLog /groups/smallco/logs/error_log<br>

-TransferLog /groups/smallco/logs/access_log<br>

-</VirtualHost><br>

-<br>

-<VirtualHost www.baygroup.org><br>

-ServerAdmin webmaster@mail.baygroup.org<br>

-DocumentRoot /groups/baygroup/www<br>

-ServerName www.baygroup.org<br>

-ErrorLog /groups/baygroup/logs/error_log<br>

-TransferLog /groups/baygroup/logs/access_log<br>

-</VirtualHost><br>

-</code></blockquote>

-This VirtualHost hostnames can also be given as IP addresses.

-<P>

-Almost <strong>ANY</strong> configuration directive can be put

-in the VirtualHost directive, with the exception of

-<A HREF="mod/core.html#servertype">ServerType</A>,

-<A HREF="mod/core.html#user">User</A>,

-<A HREF="mod/core.html#group">Group</A>,

-<A HREF="mod/core.html#startservers">StartServers</A>,

-<A HREF="mod/core.html#maxspareservers">MaxSpareServers</A>,

-<A HREF="mod/core.html#minspareservers">MinSpareServers</A>,

-<A HREF="mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A>,

-<A HREF="mod/core.html#bindaddress">BindAddress</A>,

-<A HREF="mod/core.html#pidfile">PidFile</A>,

-<A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A>, and

-<A HREF="mod/core.html#serverroot">ServerRoot</A>.

-<P>

-<EM>SECURITY:</EM> 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 <A HREF="misc/security_tips.html">security

-tips</A> document for details.

-<P>

-<H2>File Handle/Resource Limits:</H2>

-When using a large number of Virtual Hosts, Apache may run out of available

-file descriptors 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.

-<p>

-Although Apache attempts to increase the limit as required, this

-may not work if:

-<ol>

-<li>Your system does not provide the setrlimit() system call.

-<li>The setrlimit(RLIMIT_NOFILE) call does not function on your system

- (such as Solaris 2.3)

-<li>The number of file descriptors required exceeds the hard limit.

-<li>Your system imposes other limits on file descriptors, such as a limit

-on stdio streams only using file descriptors below 256. (Solaris 2)

-</ol>

-In the event of problems you can:

-<ul>

-<li>Reduce the number of log files; don't specify log files in the VirtualHost

-sections, but only log to the main log files.

-<li>If you system falls into 1 or 2 (above), then increase the file descriptor

-limit before starting Apache, using a script like

-<blockquote><code>

-#!/bin/sh <br>

-ulimit -S -n 100 <br>

-exec httpd</code></blockquote>

-</ul>

-The have been reports that Apache may start running out of resources allocated

-for the root process. This will exhibit itself as errors in the error log like

-"unable to fork". There are two ways you can bump this up:

-<OL>

-<LI>Have a <code>csh</code> script wrapper around httpd which sets the

-"rlimit" to some large number, like 512.

-<LI>Edit http_main.c to add calls to setrlimit() from main(), along the lines of

-<PRE>

- struct rlimit rlp;

- rlp.rlim_cur = rlp.rlim_max = 512;

- if (setrlimit(RLIMIT_NPROC, &rlp)) {

- fprintf(stderr, "setrlimit(RLIMIT_NPROC) failed.\n");

- exit(1);

- }

-</PRE>

-(thanks to "Aaron Gifford <agifford@InfoWest.COM>" for the patch)

-</OL>

-The latter will probably manifest itself in a later version of Apache.

-<HR>

-<H3 ALIGN="CENTER">

- Apache HTTP Server Version 1.2

-</H3>

-<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A>

-</body></html>