From: Daniel Earl Poirier Date: Thu, 19 Aug 2010 18:03:50 +0000 (+0000) Subject: Overhaul the detailed doc for virtual hosts: X-Git-Tag: 2.3.8~22 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a1489b3324b316342f993abab01e285109ab40cc;p=thirdparty%2Fapache%2Fhttpd.git Overhaul the detailed doc for virtual hosts: - remove references to implementation details - re-order information to fit the order of the page - add more links to glossary and other pages git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@987254 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/vhosts/details.xml b/docs/manual/vhosts/details.xml index b4b7691ecd1..5702131a689 100644 --- a/docs/manual/vhosts/details.xml +++ b/docs/manual/vhosts/details.xml @@ -30,71 +30,104 @@ exactly what Apache HTTP Server does when deciding what virtual host to serve a request from.

-

If you just want to make it work without - understanding how, here are some - examples.

+

Most users should read about + Name-based vs. IP-based Virtual Hosts to decide which type they + want to use, then read more about name-based + or IP-based virtualhosts, and then see + some examples.

+ +

If you want to understand all the details, then you can + come back to this page.

-
Configuration File Parsing +IP-based Virtual Host Support +Name-based Virtual Hosts Support +Virtual Host examples for common setups +Dynamically configured mass virtual hosting + -

There is a main_server which consists of all the +

Configuration File + +

There is a main server which consists of all the definitions appearing outside of - <VirtualHost> sections. There are virtual + <VirtualHost> sections.

+ +

There are virtual servers, called vhosts, which are defined by VirtualHost sections.

-

The - ServerName directive - may appear anywhere within the definition of a server. However, - each appearance overrides the previous appearance (within that - server).

- -

The main_server has no default - ServerAlias. The default ServerName, - if not specified, is deduced from the server's IP address.

- -

Port numbers specified in the VirtualHost directive do - not influence what port numbers Apache will listen on, they only discriminate between - which VirtualHost will be selected to handle a request.

+

Each VirtualHost directive includes one + or more addresses and optional ports.

+ +

Hostnames can be used in place of IP addresses in a virtual + host definition, but they are resolved at startup and if any name + resolutions fail, those virtual host definitions are ignored. + This is, therefore, not recommended.

+ +

If using IP-based vhosts, the address can be specified + as _default_, which will match a request if no + other vhost has the explicit address on which the request was + received.

+ +

If using name-based vhosts, the address can be specified as + *, which will match a request if no + other vhost has the explicit address on which the request was + received. The corresponding NameVirtualHost + directive must also use *.

+ +

The address appearing in the VirtualHost + directive can have an optional port. If the port is unspecified, + it is treated as a wildcard port, which can also be indicated + explicitly using *. + The wildcard port matches any port.

+ +

(Port numbers specified in the VirtualHost directive do + not influence what port numbers Apache will listen on, they only control + which VirtualHost will be selected to handle a request. + Use the Listen directive to + control the addresses and ports on which the server listens.) +

-

Each address appearing in the VirtualHost - directive can have an optional port. If the port is unspecified - it is treated as a wildcard port. 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 +

Collectively the + entire set of addresses (including multiple + results from DNS lookups) are called the vhost's address set.

-

Unless a NameVirtualHost - directive is used for the exact IP address and port pair in the - VirtualHost directive, Apache selects the best match - only on the basis of the IP address (or wildcard) and port number. - If there are multiple identical best matches, the first VirtualHost - appearing in the configuration file will be selected.

- -

If you want Apache to further discriminate on the basis of the - HTTP Host header supplied by the client, the - NameVirtualHost directive must appear - with the exact IP address (or wildcard) and port pair used in a correspnding - set of VirtualHost directives.

- -

The name-based virtual host selection occurs only after the a single IP-based - virtual host has been selected, and only considers the set of virtual hosts - the carry an identical IP address and port pair.

- -

Hostnames can be used in place of IP addresses in a virtual host definition, - but it is resolved at startup and is not recommended.

+

If you want Apache to discriminate on the + basis of the HTTP Host header supplied by the client, + the NameVirtualHost directive must appear + with the exact IP address (or wildcard) and port pair used in a + corresponding set of VirtualHost directives.

+

The + ServerName directive + may appear anywhere within the definition of a server. However, + each appearance overrides the previous appearance (within that + server). If no ServerName is specified, the server + attempts to deduce it from the server's IP address.

-

Multiple NameVirtualHost directives can be used - each with a set of VirtualHost directives but only +

Multiple NameVirtualHost directives can be used, + each with a set of VirtualHost directives, but only one NameVirtualHost directive should be used for each specific IP:port pair.

+

The first name-based vhost in the configuration file for a + given IP:port pair is significant because it is used for all + requests received on that address and port for which no other + vhost for that IP:port pair has a matching ServerName or + ServerAlias. It is also used for all SSL connections if the + server does not support Server Name Indication.

+ +

If there are no vhosts defined for an address in a + NameVirtualHost directive, the + NameVirtualHost directive is ignored at startup and an error is + logged.

+

The ordering of NameVirtualHost and - VirtualHost directives is not important which + VirtualHost directives is not important, which makes the following two examples identical (only the order of the VirtualHost directives for one address set is important, see below):

@@ -148,20 +181,6 @@

(To aid the readability of your configuration you should prefer the left variant.)

-

During initialization a list for each IP address is - generated and inserted into an hash table. If the IP address is - used in a NameVirtualHost directive the list - contains all name-based vhosts for the given IP address. If - there are no vhosts defined for that address the - NameVirtualHost directive is ignored and an error - is logged. For an IP-based vhost the list in the hash table is - empty.

- -

Due to a fast hashing function the overhead of hashing an IP - address during a request is minimal and almost not existent. - Additionally the table is optimized for IP addresses which vary - in the last octet.

-

For every vhost various default values are set. In particular:

@@ -176,31 +195,31 @@ ReceiveBufferSize, or SendBufferSize directive then the respective value is inherited from the - main_server. (That is, inherited from whatever the final - setting of that value is in the main_server.) + main server. (That is, inherited from whatever the final + setting of that value is in the main server.)
  • The "lookup defaults" that define the default directory permissions for a vhost are merged with those of the - main_server. This includes any per-directory configuration + main server. This includes any per-directory configuration information for any module.
  • The per-server configs for each module from the - main_server are merged into the vhost server.
    • + main server are merged into the vhost server. -

    Essentially, the main_server is treated as "defaults" or a +

    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 + these main server definitions in the config file is largely + irrelevant -- the entire config of the main server has been + parsed when this final merging occurs. So even if a main server definition appears after a vhost definition it might affect the vhost definition.

    -

    If the main_server has no ServerName at this +

    If the main server has no ServerName at this point, then the hostname of the machine that httpd - is running on is used instead. We will call the main_server address + is running on is used instead. We will call the main server address set those IP addresses returned by a DNS lookup on the - ServerName of the main_server.

    + ServerName of the main server.

    For any undefined ServerName fields, a name-based vhost defaults to the address given first in the @@ -208,7 +227,7 @@

    Any vhost that includes the magic _default_ wildcard is given the same ServerName as the - main_server.

    + main server.

    @@ -217,72 +236,74 @@

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

    -
    Hash table lookup +
    IP address lookup + +

    When the connection is first received on some address and port, + the server looks for all the VirtualHost definitions + that have the same IP address and port.

    -

    When the connection is first made by a client, the IP - address to which the client connected is looked up in the - internal IP hash table.

    +

    If there are no exact matches for the address and port, then + wildcard (*) matches are considered.

    -

    If the lookup fails (the IP address wasn't found) the - request is served from the _default_ vhost if - there is such a vhost for the port to which the client sent the - request. If there is no matching _default_ vhost - the request is served from the main_server.

    +

    If there are still no matches, then vhosts with IP + address specified as _default_ that match the + port are considered.

    -

    If the IP address is not found in the hash table then the - match against the port number may also result in an entry - corresponding to a NameVirtualHost *, which is - subsequently handled like other name-based vhosts.

    +

    If no matches are found, the request is served by the + main server.

    -

    If the lookup succeeded (a corresponding list for the IP - address was found) the next step is to decide if we have to - deal with an IP-based or a name-base vhost.

    +

    If there are VirtualHost definitions for + the IP address, the next step is to decide if we have to + deal with an IP-based or a name-based vhost.

    IP-based vhost -

    If the entry we found has an empty name list then we have - found an IP-based vhost, no further actions are performed and - the request is served from that vhost.

    +

    If there is no NameVirtualHost directive + matching the vhost, no further actions are performed and + the request is served from the first matching vhost.

    Name-based vhost -

    If the entry corresponds to a name-based vhost the name list - contains one or more vhost structures. This list contains the - vhosts in the same order as the VirtualHost - directives appear in the config file.

    - -

    The first vhost on this list (the first vhost in the config - file with the specified IP address) has the highest priority - and catches any request to an unknown server name or a request - without a Host: header field.

    - -

    If the client provided a Host: header field the - list is searched for a matching vhost and the first hit on a - ServerName or ServerAlias is taken - and the request is served from that vhost. A Host: - header field can contain a port number, but Apache always +

    If the entry corresponds to a name-based vhost, the "list" in + the remaining steps refers to the list of vhosts that matched, in + the order they were in the configuration file.

    + +

    If the connection is using SSL, the server supports Server Name Indication, and + the SSL client handshake includes the TLS extension with the + requested hostname, then that hostname is used below just like the + Host: header would be used on a non-SSL connection. + Otherwise, the first name-based vhost whose address matched is + used for SSL connections. This is significant because the + vhost determines which certificate the server will use for the + connection.

    + +

    If the request contains a Host: header field, the + list is searched for the first vhost with a matching + ServerName or ServerAlias, and the + request is served from that vhost. A Host: header + field can contain a port number, but Apache always ignores it and matches against the real port to which the client sent the request.

    -

    If the client submitted a HTTP/1.0 request without - Host: header field we don't know to what server - the client tried to connect to. In this case, the first virtual host - (that is, the one listed first in the server configuration file) for - the IP address and port to which the client connected, is - used to serve this request.

    +

    The first vhost in the config + file with the specified IP address has the highest priority + and catches any request to an unknown server name, or a request + without a Host: header field (such as a HTTP/1.0 + request).

    Persistent connections -

    The IP lookup described above is only done once for a - particular TCP/IP session while the name lookup is done on +

    The IP lookup described above is only done once for a + particular TCP/IP session while the name lookup is done on every request during a KeepAlive/persistent - connection. In other words a client may request pages from + connection. In other words, a client may request pages from different name-based vhosts during a single persistent connection.

    @@ -322,7 +343,7 @@ configuration file has the highest priority for its corresponding address set. -
  • The Host: header field is never used during the +
  • Any port in the Host: header field is never used during the matching process. Apache always uses the real port to which the client sent the request.
    • @@ -344,15 +365,15 @@ extension of the "best match" principle, as a specific and exact match is favored over a wildcard. -
  • The main_server is only used to serve a request if the IP - address and port number to which the client connected is - unspecified and does not match any other vhost (including a - _default_ vhost). In other words the main_server +
  • The main server is only used to serve a request if the IP + address and port number to which the client connected + does not match any vhost (including a + _default_ vhost). In other words, the main server only catches a request for an unspecified address/port combination (unless there is a _default_ vhost which matches that port).
    • -
  • A _default_ vhost or the main_server is +
  • A _default_ vhost or the main server is never matched for a request with an unknown or missing Host: header field if the client connected to an address (and port) which is used for @@ -382,7 +403,7 @@ some further tips:

      -
    • Place all main_server definitions before any +
    • 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 @@ -394,5 +415,5 @@
    • - +