httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rodent of Unusual Size <c...@hyperreal.com>
Subject cvs commit: apache/htdocs/manual vhosts-in-depth.html
Date Mon, 28 Apr 1997 19:50:58 GMT
coar        97/04/28 12:50:57

  Modified:    htdocs/manual  vhosts-in-depth.html
  Log:
  	Fixed some misspelt directives, added hyperlinks to directive
  	descriptions, and some spelling corrections.  Doubtless more to
  	be done..
  
  Revision  Changes    Path
  1.4       +114 -73   apache/htdocs/manual/vhosts-in-depth.html
  
  Index: vhosts-in-depth.html
  ===================================================================
  RCS file: /export/home/cvs/apache/htdocs/manual/vhosts-in-depth.html,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -C3 -r1.3 -r1.4
  *** vhosts-in-depth.html	1997/03/24 18:40:16	1.3
  --- vhosts-in-depth.html	1997/04/28 19:50:56	1.4
  ***************
  *** 12,39 ****
    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 <i>vhosts</i>, which are defined by <code>VirtualHost</code>
sections.
    
    <p>The directives
  ! <code>Port</code>,
  ! <code>ServerName</code>,
  ! <code>ServerPath</code>, and
  ! <code>ServerAlias</code> 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 ServerAlias</code>.
    
  ! <p>In the absence of any <code>Listen</code> directives, the (final
if there
    are multiple) <code>Port</code> directive in the main_server indicates
    which port httpd will listen on.
    
  --- 12,57 ----
    assumption that something is better than nothing.  The server version
    under discussion is Apache 1.2.
    
  ! <p>If you just want to &quot;make it work&quot; 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.
    
  ***************
  *** 44,52 ****
    <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 * indicates a wildcard that matches any port.
  ! Collectively the entire set of addresses (including multiple A record
  ! results from DNS lookups) are called the vhost's <i>address set</i>.
    
    <p> The magic <code>_default_</code> address has significance during
    the matching algorithm.  It essentially matches any unspecified address.
  --- 62,71 ----
    <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.
  ***************
  *** 84,136 ****
    After parsing has completed, the list of servers is scanned, and various
    merges and default values are set.  In particular:
    
  ! <ul>
    <li>If a vhost has no
  !     <code>ServerAdmin</code>,
  !     <code>ResourceConf</code>,
  !     <code>AccessConf</code>,
  !     <code>Timeout</code>,
  !     <code>KeepAliveTimeout</code>,
  !     <code>KeepAlive</code>,
  !     <code>KeepAliveMax</code>, or
  !     <code>SendBufferSize</code> 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.
  ! </ul>
    
  ! 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 irrellevent -- 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 <i>main_server address set</i> 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 <i>ip-based</i> vhost or a <i>name-based</i> 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
  ! _default_ 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.
  --- 103,175 ----
    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 &quot;lookup defaults&quot; 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 &quot;defaults&quot; or a
  ! &quot;base&quot; on
    which to build each vhost.  But the positioning of these main_server
  ! definitions in the config file is largely irrelevent -- 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.
  ***************
  *** 143,163 ****
    The process by which vhost a request is for is 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 occurance, if it appears,
  ! of a _default_ address (which if you recall the ordering of the
    server list mentioned above means that this would be the first occurance
  ! of _default_ 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 <i>connection vhost</i>.
    The connection vhost is constant over all requests in a particular TCP/IP
    session -- that is, over all requests in a KeepAlive/persistent session.
    
  --- 182,202 ----
    The process by which vhost a request is for is 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 occurance, 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 occurance
  ! 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.
    
  ***************
  *** 168,181 ****
    <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 <i>request_hostname</i>.  If it does not match, then the
  ! uri remains untouched.  <b>Note</b>: 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
  ! (i.e. <code>http:</code>, <code>ftp:</code>) then the request
is
    considered a proxy request.  Note that even though we may have stripped
    an <code>http://hostname/</code> in the previous step, this could still
    be a proxy request.
  --- 207,221 ----
    <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.
  ***************
  *** 193,211 ****
    
    <p>
    If the port matches, then httpd scans the list of vhosts starting with
  ! the next server <b>after</b> 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>
    
  --- 233,251 ----
    
    <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>
    
  ***************
  *** 214,262 ****
    (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
  ! <b>last match</b> 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 "Host: A" then
        it will be served from A's config.  If a request comes in on A's
        address then it will always be served from A's config regardless of
        any Host: header.
        </p>
    
  ! <li> Unless you have a _default_ 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 _default_ vhost, then you cannot place
        named-based vhosts after it in the config.  This is because on any
        connection to the main server ips the connection vhost will always be
  !     the _default_ vhost since none of the name-based are considered
        during <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.
  --- 254,303 ----
    (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
  !     &quot;main IP address&quot;.  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
  !     &quot;<SAMP>Host: A<SAMP>&quot; 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.
  ***************
  *** 265,288 ****
        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
  --- 306,329 ----
        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
  ***************
  *** 290,303 ****
        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
        inadvertantly.  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>
  --- 331,344 ----
        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
        inadvertantly.  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>
  ***************
  *** 315,332 ****
    virtualhosts might affect all virtualhosts.)
    
    <li>Arrange your VirtualHosts such
  ! that all name-based virtual hosts come first, followed by ip-based
  ! virtual hosts, followed by any _default_ virtual host
    
    <li>Avoid <code>ServerPaths</code> which are prefixes of other
    <code>ServerPaths</code>.  If you cannot avoid this then you have to
    ensure that the longer (more specific) prefix vhost appears earlier in
  ! the configuration file than the shorter (less specific) prefix.  (i.e.
  ! "ServerPath /abc" should appear after "ServerPath /abcdef").
    
    </ul>
    
    <!--#include virtual="footer.html" -->
    </BODY>
    </HTML>
  - 
  --- 356,373 ----
    virtualhosts might affect all virtualhosts.)
    
    <li>Arrange your VirtualHosts such
  ! that all name-based virtual hosts come first, followed by IP-based
  ! virtual hosts, followed by any <SAMP>_default_</SAMP> virtual host
    
    <li>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>, &quot;ServerPath /abc&quot; should appear after
  ! &quot;ServerPath /abcdef&quot;). 
    
    </ul>
    
    <!--#include virtual="footer.html" -->
    </BODY>
    </HTML>
  
  
  

Mime
View raw message