martin 97/11/12 05:37:55
Added: htdocs/manual/vhosts host.html vhosts-in-depth.html
virtual-host.html
Log:
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 <sfx@unix-ag.org>
Reviewed by: Martin Kraemer
Revision Changes Path
1.1 apachen/htdocs/manual/vhosts/host.html
Index: host.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>Apache non-IP Virtual Hosts</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<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>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
1.1 apachen/htdocs/manual/vhosts/vhosts-in-depth.html
Index: vhosts-in-depth.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>An In-Depth Discussion of VirtualHost Matching</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<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><strong>Apache 1.3 differs from what is documented
here, and documentation still has to be written.</strong>
<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.
<P>
<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.
</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 <EM>port-based</EM> 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>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
1.1 apachen/htdocs/manual/vhosts/virtual-host.html
Index: virtual-host.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Apache Server Virtual Host Support</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<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.
<!--#include virtual="footer.html" -->
</body></html>
Added: htdocs/manual/vhosts host.html vhosts-in-depth.html
virtual-host.html
Log:
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 <sfx@unix-ag.org>
Reviewed by: Martin Kraemer
Revision Changes Path
1.1 apachen/htdocs/manual/vhosts/host.html
Index: host.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>Apache non-IP Virtual Hosts</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<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>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
1.1 apachen/htdocs/manual/vhosts/vhosts-in-depth.html
Index: vhosts-in-depth.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>An In-Depth Discussion of VirtualHost Matching</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<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><strong>Apache 1.3 differs from what is documented
here, and documentation still has to be written.</strong>
<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.
<P>
<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.
</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 <EM>port-based</EM> 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>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
1.1 apachen/htdocs/manual/vhosts/virtual-host.html
Index: virtual-host.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Apache Server Virtual Host Support</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<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.
<!--#include virtual="footer.html" -->
</body></html>