From: Joshua Slive Date: Mon, 22 Oct 2001 20:17:34 +0000 (+0000) Subject: Refresh of the name-vhosting docs. X-Git-Tag: 2.0.27~42 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c81897bd523e8dae2ef5ffeafa696396cc37d62b;p=thirdparty%2Fapache%2Fhttpd.git Refresh of the name-vhosting docs. Reviewed by: Allan Liska git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91640 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/vhosts/name-based.html b/docs/manual/vhosts/name-based.html index ad47c4ab14c..b6bde6cef05 100644 --- a/docs/manual/vhosts/name-based.html +++ b/docs/manual/vhosts/name-based.html @@ -3,9 +3,7 @@ - - - Apache name-based Virtual Hosts + Name-based Virtual Hosts @@ -13,116 +11,173 @@ vlink="#000080" alink="#FF0000"> -

Apache name-based Virtual Host Support

- See Also: IP-based - Virtual Host Support -
- -

Name-based vs. IP-based virtual hosts

- -

Early versions of HTTP (like many other protocols, e.g. FTP) - required a different IP address for each virtual host on the - server. On some platforms this can limit the number of virtual - hosts you can run, and because there are concerns about the - availability of IP addresses it is strongly discouraged by the - registraries (ARIN, RIPE, and APNIC).

- -

The HTTP/1.1 protocol, and a common extension - to HTTP/1.0, includes 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 old - IP-address-per-hostname method.

- -

The benefits of using the name-based virtual hosts is a - practically unlimited number of servers, ease of configuration - and use, and it requires no additional hardware or software. - The main disadvantage is that the client must support this part - of the protocol. Almost all browsers do, but there are still - tiny numbers of very old browsers in use which do not. This can - cause problems, although a possible solution is addressed - below.

- -

Using name-based virtual hosts

- -

Using name-based virtual hosts is quite easy, and - superficially looks like the old method. The notable difference - between IP-based and name-based virtual host configuration is - the NameVirtualHost - directive which specifies an IP address that should be used as - a target for name-based virtual hosts, or the wildcard - * to indicate that the server only does name-based - virtual hosting (no IP-based virtual hosting).

- -

For example, suppose that both www.domain.tld - and www.otherdomain.tld point at the IP address of - your server. Then you simply add to one of the Apache - configuration files (most likely httpd.conf or - srm.conf) code similar to the following:

+

Name-based Virtual Host Support

+ +

This document describes when and how to use name-based virtual hosts.

+ + + +

See also: Virtual Host examples for common +setups, IP-based Virtual Host Support, +An In-Depth Discussion of Virtual Host +Matching, and Dynamically configured mass +virtual hosting.

+ +
+ +

Name-based vs. IP-based Virtual Hosts

+ +

IP-based virtual hosts use the IP address of the connection to +determine the correct virtual host to serve. Therefore you need to +have a separate IP address for each host. With name-based virtual +hosting, the server relies on the client to report the hostname as +part of the HTTP headers. Using this technique, many different hosts +can share the same IP address.

+ +

Name-based virtual hosting is usually simpler, since you need +only configure your DNS server to map each hostname to the correct +IP address and then configure the Apache HTTP Server to recognize +the different hostnames. Name-based virtual hosting also eases +the demand for scarce IP addresses. Therefore you should use +name-based virtual hosting unless there is a specific reason to +choose IP-based virtual hosting. Some reasons why you might consider +using IP-based virtual hosting:

+ + + +

Using Name-based Virtual Hosts

+ + +
+Related Directives

+ +DocumentRoot
+NameVirtualHost
+ServerAlias
+ServerName
+ServerPath
+VirtualHost
+
+ +

To use name-based virtual hosting, you must designate the IP +address (and possibly port) on the server that will be accepting +requests for the hosts. This is configured using the NameVirtualHost directive. +In the normal case where any and all IP addresses on the server should +be used, you can use * as the argument to +NameVirtualHost. Note that mentioning an IP address in a +NameVirtualHost directive does not automatically make the +server listen to that IP address. See Setting +which addresses and ports Apache uses for more details. + +

The next step is to create a <VirtualHost> block for +each different host that you would like to serve. The argument to the +<VirtualHost> directive should be the same as the +argument to the NameVirtualHost directive (ie, an IP +address, or * for all addresses). Inside each +<VirtualHost> block, you will need at minimum a ServerName directive to +designate which host is served and a DocumentRoot directive to +show where in the filesystem the content for that host lives.

+ +

For example, suppose that both www.domain.tld and +www.otherdomain.tld point at the IP address +111.22.33.44. Then you simply add the following +to httpd.conf:

+ 
-    NameVirtualHost *
+    NameVirtualHost 111.22.33.44
 
-    <VirtualHost *>
+    <VirtualHost 111.22.33.44>
     ServerName www.domain.tld
     DocumentRoot /www/domain
     </VirtualHost>
 
-    <VirtualHost *>
+    <VirtualHost 111.22.33.44>
     ServerName www.otherdomain.tld
     DocumentRoot /www/otherdomain
     </VirtualHost>
-

Of course, any additional directives can (and should) be - placed into the <VirtualHost> section. To - make this work, all that is needed is to make sure that the - names www.domain.tld and - www.otherdomain.tld are pointing to the right IP - address.

- -

Note: When you specify an IP address in a - NameVirtualHost directive then requests to that IP - address will only ever be served by matching - <VirtualHost>s. The "main server" will - never be served from the specified IP address. - If you specify a wildcard then the "main server" isn't used at - all. If you start to use virtual hosts you should stop using - the "main server" as an independent server and rather use it as - a place for configuration directives that are common for all - your virtual hosts. In other words, you should add a - <VirtualHost> section for every server - (hostname) you want to maintain on your server.

- -

Additionally, many servers may wish to be accessible by more - than one name. For example, the example server might want to be - accessible as domain.tld, or - www2.domain.tld, assuming the IP addresses pointed - to the same server. In fact, one might want it so that all - addresses at domain.tld were picked up by the - server. This is possible with the ServerAlias - directive, placed inside the <VirtualHost> section. For - example:

-
-    ServerAlias domain.tld *.domain.tld
-
- -

Note that you can use * and ? as - wild-card characters.

- -

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.foobar" then you will need to add ServerAlias www - www.foobar. 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. The - ServerAlias directive is generally a way to have - different hostnames pointing to the same virtual host.

- -

Compatibility with Older Browsers

- -

As mentioned earlier, there are still some clients in use +

In the simplest case, the IP address 111.22.44.33 can be +replaced by * to match all IP addresses for your server.

+ +

Many servers want to be accessible by more than one name. This is +possible with the ServerAlias +directive, placed inside the <VirtualHost> section. For +example if you add this to the first <VirtualHost> block +above

+ +
+ServerAlias domain.tld *.domain.tld +
+ +

then requests for all hosts in the domain.tld domain +will be served by the www.domain.tld virtual host. The +wildcard characters * and ? can be used to match names. Of course, +you can't just make up names and place them in ServerName +or ServerAlias. You must first have your DNS server +properly configured to map those names to the IP address in the +NameVirtualHost directive.

+ +

Finally, you can fine-tune the configuration of the virtual hosts +by placing other directives inside the +<VirtualHost> containers. Most directives can be +placed in these containers and will then change the configuration only +of the relevant virtual host. To find out if a particular directive +is allowed, check the Context of the +directive. Configuration directives set in the main server +context (outside any <VirtualHost> container) +will be used only if they are not overriden by the virtual host +settings.

+ +

Now when a request arrives, the server will first check if it is +using an IP address that matches the NameVirtualHost. If +it is, then it will look at each <VirtualHost> +section with a matching IP address and try to find one where the +ServerName or ServerAlias matches the +requested hostname. If it finds one, then it uses the configuration +for that server. If no matching virtual host is found, then +the first listed virtual host that matches the IP +address will be used.

+ +

As a consequence, the first listed virtual host is the +default virtual host. The DocumentRoot from the +main server will never be used when an IP +address matches the NameVirtualHost directive. If you +would like to have a special configuration for requests that do not +match any particular virtual host, simply put that configuration in a +<VirtualHost> container and list it first in the +configuration file.

+ +

Compatibility with Older Browsers

+ +

As mentioned earlier, there are some clients who do not send the required data for the name-based virtual hosts to work properly. These clients will always be sent the pages from the first virtual host listed for that IP address diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en index ad47c4ab14c..b6bde6cef05 100644 --- a/docs/manual/vhosts/name-based.html.en +++ b/docs/manual/vhosts/name-based.html.en @@ -3,9 +3,7 @@ - - - Apache name-based Virtual Hosts + Name-based Virtual Hosts @@ -13,116 +11,173 @@ vlink="#000080" alink="#FF0000"> -

Apache name-based Virtual Host Support

- See Also: IP-based - Virtual Host Support -
- -

Name-based vs. IP-based virtual hosts

- -

Early versions of HTTP (like many other protocols, e.g. FTP) - required a different IP address for each virtual host on the - server. On some platforms this can limit the number of virtual - hosts you can run, and because there are concerns about the - availability of IP addresses it is strongly discouraged by the - registraries (ARIN, RIPE, and APNIC).

- -

The HTTP/1.1 protocol, and a common extension - to HTTP/1.0, includes 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 old - IP-address-per-hostname method.

- -

The benefits of using the name-based virtual hosts is a - practically unlimited number of servers, ease of configuration - and use, and it requires no additional hardware or software. - The main disadvantage is that the client must support this part - of the protocol. Almost all browsers do, but there are still - tiny numbers of very old browsers in use which do not. This can - cause problems, although a possible solution is addressed - below.

- -

Using name-based virtual hosts

- -

Using name-based virtual hosts is quite easy, and - superficially looks like the old method. The notable difference - between IP-based and name-based virtual host configuration is - the NameVirtualHost - directive which specifies an IP address that should be used as - a target for name-based virtual hosts, or the wildcard - * to indicate that the server only does name-based - virtual hosting (no IP-based virtual hosting).

- -

For example, suppose that both www.domain.tld - and www.otherdomain.tld point at the IP address of - your server. Then you simply add to one of the Apache - configuration files (most likely httpd.conf or - srm.conf) code similar to the following:

+

Name-based Virtual Host Support

+ +

This document describes when and how to use name-based virtual hosts.

+ + + +

See also: Virtual Host examples for common +setups, IP-based Virtual Host Support, +An In-Depth Discussion of Virtual Host +Matching, and Dynamically configured mass +virtual hosting.

+ +
+ +

Name-based vs. IP-based Virtual Hosts

+ +

IP-based virtual hosts use the IP address of the connection to +determine the correct virtual host to serve. Therefore you need to +have a separate IP address for each host. With name-based virtual +hosting, the server relies on the client to report the hostname as +part of the HTTP headers. Using this technique, many different hosts +can share the same IP address.

+ +

Name-based virtual hosting is usually simpler, since you need +only configure your DNS server to map each hostname to the correct +IP address and then configure the Apache HTTP Server to recognize +the different hostnames. Name-based virtual hosting also eases +the demand for scarce IP addresses. Therefore you should use +name-based virtual hosting unless there is a specific reason to +choose IP-based virtual hosting. Some reasons why you might consider +using IP-based virtual hosting:

+ + + +

Using Name-based Virtual Hosts

+ + +
+Related Directives

+ +DocumentRoot
+NameVirtualHost
+ServerAlias
+ServerName
+ServerPath
+VirtualHost
+
+ +

To use name-based virtual hosting, you must designate the IP +address (and possibly port) on the server that will be accepting +requests for the hosts. This is configured using the NameVirtualHost directive. +In the normal case where any and all IP addresses on the server should +be used, you can use * as the argument to +NameVirtualHost. Note that mentioning an IP address in a +NameVirtualHost directive does not automatically make the +server listen to that IP address. See Setting +which addresses and ports Apache uses for more details. + +

The next step is to create a <VirtualHost> block for +each different host that you would like to serve. The argument to the +<VirtualHost> directive should be the same as the +argument to the NameVirtualHost directive (ie, an IP +address, or * for all addresses). Inside each +<VirtualHost> block, you will need at minimum a ServerName directive to +designate which host is served and a DocumentRoot directive to +show where in the filesystem the content for that host lives.

+ +

For example, suppose that both www.domain.tld and +www.otherdomain.tld point at the IP address +111.22.33.44. Then you simply add the following +to httpd.conf:

+ 
-    NameVirtualHost *
+    NameVirtualHost 111.22.33.44
 
-    <VirtualHost *>
+    <VirtualHost 111.22.33.44>
     ServerName www.domain.tld
     DocumentRoot /www/domain
     </VirtualHost>
 
-    <VirtualHost *>
+    <VirtualHost 111.22.33.44>
     ServerName www.otherdomain.tld
     DocumentRoot /www/otherdomain
     </VirtualHost>
-

Of course, any additional directives can (and should) be - placed into the <VirtualHost> section. To - make this work, all that is needed is to make sure that the - names www.domain.tld and - www.otherdomain.tld are pointing to the right IP - address.

- -

Note: When you specify an IP address in a - NameVirtualHost directive then requests to that IP - address will only ever be served by matching - <VirtualHost>s. The "main server" will - never be served from the specified IP address. - If you specify a wildcard then the "main server" isn't used at - all. If you start to use virtual hosts you should stop using - the "main server" as an independent server and rather use it as - a place for configuration directives that are common for all - your virtual hosts. In other words, you should add a - <VirtualHost> section for every server - (hostname) you want to maintain on your server.

- -

Additionally, many servers may wish to be accessible by more - than one name. For example, the example server might want to be - accessible as domain.tld, or - www2.domain.tld, assuming the IP addresses pointed - to the same server. In fact, one might want it so that all - addresses at domain.tld were picked up by the - server. This is possible with the ServerAlias - directive, placed inside the <VirtualHost> section. For - example:

-
-    ServerAlias domain.tld *.domain.tld
-
- -

Note that you can use * and ? as - wild-card characters.

- -

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.foobar" then you will need to add ServerAlias www - www.foobar. 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. The - ServerAlias directive is generally a way to have - different hostnames pointing to the same virtual host.

- -

Compatibility with Older Browsers

- -

As mentioned earlier, there are still some clients in use +

In the simplest case, the IP address 111.22.44.33 can be +replaced by * to match all IP addresses for your server.

+ +

Many servers want to be accessible by more than one name. This is +possible with the ServerAlias +directive, placed inside the <VirtualHost> section. For +example if you add this to the first <VirtualHost> block +above

+ +
+ServerAlias domain.tld *.domain.tld +
+ +

then requests for all hosts in the domain.tld domain +will be served by the www.domain.tld virtual host. The +wildcard characters * and ? can be used to match names. Of course, +you can't just make up names and place them in ServerName +or ServerAlias. You must first have your DNS server +properly configured to map those names to the IP address in the +NameVirtualHost directive.

+ +

Finally, you can fine-tune the configuration of the virtual hosts +by placing other directives inside the +<VirtualHost> containers. Most directives can be +placed in these containers and will then change the configuration only +of the relevant virtual host. To find out if a particular directive +is allowed, check the Context of the +directive. Configuration directives set in the main server +context (outside any <VirtualHost> container) +will be used only if they are not overriden by the virtual host +settings.

+ +

Now when a request arrives, the server will first check if it is +using an IP address that matches the NameVirtualHost. If +it is, then it will look at each <VirtualHost> +section with a matching IP address and try to find one where the +ServerName or ServerAlias matches the +requested hostname. If it finds one, then it uses the configuration +for that server. If no matching virtual host is found, then +the first listed virtual host that matches the IP +address will be used.

+ +

As a consequence, the first listed virtual host is the +default virtual host. The DocumentRoot from the +main server will never be used when an IP +address matches the NameVirtualHost directive. If you +would like to have a special configuration for requests that do not +match any particular virtual host, simply put that configuration in a +<VirtualHost> container and list it first in the +configuration file.

+ +

Compatibility with Older Browsers

+ +

As mentioned earlier, there are some clients who do not send the required data for the name-based virtual hosts to work properly. These clients will always be sent the pages from the first virtual host listed for that IP address