Mercurial > hg > nginx-site
changeset 621:656dfb085020
Unified server names matching description with server_name directive, improved
wording and various typesetting-related changes
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Thu, 09 Aug 2012 10:36:48 +0000 |
parents | 32f50b2f9f0c |
children | 13f64b371d2c |
files | xml/en/docs/http/server_names.xml |
diffstat | 1 files changed, 67 insertions(+), 58 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/server_names.xml +++ b/xml/en/docs/http/server_names.xml @@ -8,7 +8,7 @@ <article name="Server names" link="/en/docs/http/server_names.html" lang="en" - rev="1" + rev="2" author="Igor Sysoev" editor="Brian Mercer"> @@ -19,8 +19,9 @@ Server names are defined using the <link doc="ngx_http_core_module.xml" id="server_name"/> directive -and determine which server block is used for a given request. -See also “<link doc="request_processing.xml"/>”. +and determine which <link doc="ngx_http_core_module.xml" id="server"/> block +is used for a given request. +See also “<link doc="request_processing.xml"/>”. They may be defined using exact names, wildcard names, or regular expressions: <programlisting> @@ -48,31 +49,33 @@ server { ... } </programlisting> +</para> -The names are tested in the following order: - +<para> +When searching for a virtual server by name, if name matches more than one of +the specified variants, e.g. both wildcard name and regular expression match, +the first matching variant will be chosen, in the following order of precedence: <list type="enum"> <listitem> -exact names; +exact name </listitem> <listitem> -wildcard names starting with an asterisk: <literal>*.example.org</literal> -(longest first); +longest wildcard name starting with an asterisk, e.g. +“<literal>*.example.org</literal>” </listitem> <listitem> -wildcard names ending with an asterisk: <literal>mail.*</literal> -(longest first); +longest wildcard name ending with an asterisk, e.g. “<literal>mail.*</literal>” </listitem> <listitem> -and regular expressions in the order listed in the configuration file. +first matching regular expression +(in order of appearance in a configuration file). </listitem> </list> -The first match stops the search. </para> </section> @@ -94,8 +97,8 @@ The name “<literal>*.example.org</literal>” matches not only </para> <para> -A special wildcard in the form “<literal>.example.org</literal>” can be used -to match both the exact name “<literal>example.org</literal>” +A special wildcard name in the form “<literal>.example.org</literal>” can be +used to match both the exact name “<literal>example.org</literal>” and the wildcard name “<literal>*.example.org</literal>”. </para> @@ -117,11 +120,11 @@ server_name ~^www\d+\.example\.net$; otherwise it will be treated as an exact name, or if the expression contains an asterisk, as a wildcard name (and most likely as an invalid one). -Do not forget to set “^” and “$” anchors. +Do not forget to set “<literal>^</literal>” and “<literal>$</literal>” anchors. They are not required syntactically, but logically. Also note that domain name dots should be escaped with a backslash. -A regular expression containing the characters “{” -and “}” should be quoted: +A regular expression containing the characters “<literal>{</literal>” +and “<literal>}</literal>” should be quoted: <programlisting> server_name "~^(?<name>\w\d<b>{</b>1,3<b>}</b>+)\.example\.net$"; @@ -172,8 +175,8 @@ If nginx fails to start and displays the pcre_compile() failed: unrecognized character after (?< in ... </programlisting> -this means that the PCRE library is old -and you should try the syntax “<literal>?P<<value>name</value>></literal>”. +this means that the PCRE library is old and the syntax +“<literal>?P<<value>name</value>></literal>” should be tried instead. The captures can also be used in digital form: <programlisting> @@ -198,8 +201,13 @@ since the digital references can easily name="Miscellaneous names"> <para> -If you want to process requests without a “Host” header line -in a server block which is not the default, you should specify an empty name: +There are some server names that are treated specially. +</para> + +<para> +If it is required to process requests without the <header>Host</header> +header field in a <link doc="ngx_http_core_module.xml" id="server"/> +block which is not the default, an empty name should be specified: <programlisting> server { @@ -213,7 +221,7 @@ server { <para> If no <link doc="ngx_http_core_module.xml" id="server_name"/> -is defined in a server block, +is defined in a <link doc="ngx_http_core_module.xml" id="server"/> block then nginx uses the empty name as the server name. <note> nginx versions up to 0.8.48 used the <i>hostname</i> as the server name @@ -223,8 +231,8 @@ in this case. <para> If someone makes a request using an IP address instead of a server name, -the request’s “Host” header line will contain the IP address -and you can handle the request using the IP address as the server name: +the <header>Host</header> request header field will contain the IP address +and the request can be handled using the IP address as the server name: <programlisting> server { @@ -240,7 +248,8 @@ server { </para> <para> -In catch-all server examples you may see the strange name “_”: +In catch-all server examples the strange name “<literal>_</literal>” can +be seen: <programlisting> server { @@ -252,23 +261,24 @@ server { There is nothing special about this name, it is just one of a myriad of invalid domain names which never intersect with any real name. -You may also use something like “--”, “!@#”, and so on. +Other invalid names like “<literal>--</literal>” and “<literal>!@#</literal>” +may equally be used. </para> <para> -nginx versions up to 0.6.25 supported the special name “*” +nginx versions up to 0.6.25 supported the special name “<literal>*</literal>” which was erroneously interpreted to be a catch-all name. It never functioned as a catch-all or wildcard server name. Instead, it supplied the functionality that is now provided by the <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> directive. -The special name “*” is now deprecated +The special name “<literal>*</literal>” is now deprecated and the <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> directive should be used. Note that there is no way to specify the catch-all name or -the <i>default</i> server using the +the default server using the <link doc="ngx_http_core_module.xml" id="server_name"/> directive. This is a property of the @@ -277,8 +287,8 @@ directive and not of the <link doc="ngx_http_core_module.xml" id="server_name"/> directive. -See also “<link doc="request_processing.xml"/>”. -You can define servers listening on ports *:80 and *:8080, +See also “<link doc="request_processing.xml"/>”. +It is possible to define servers listening on ports *:80 and *:8080, and direct that one will be the default server for port *:8080, while the other will be the default for port *:80: @@ -307,27 +317,27 @@ server { name="Optimization"> <para> -Exact names and wildcard names are stored in hashes. -The hashes are bound to the listen ports and every listen port -may have up to three hashes: an exact names hash, a wildcard names hash -starting with an asterisk, and a wildcard names hash ending with an asterisk. -The sizes of the hashes are optimized at the configuration phase so that -a name can be found with the fewest CPU cache misses. +Exact names, wildcard names starting with an asterisk, +and wildcard names ending with an asterisk are stored +in three hash tables bound to the listen ports. +The sizes of hash tables are optimized at the configuration phase +so that a name can be found with the fewest CPU cache misses. +See also “<link doc="../hash.xml"/>”. </para> <para> -The exact names hash is searched first. -If a name is not found using the exact name hash, then the wildcard names hash +The exact names hash table is searched first. +If a name is not found, the hash table with wildcard names starting with an asterisk is searched. -If the name is not found there, the wildcard names hash +If the name is not found there, the hash table with wildcard names ending with an asterisk is searched. </para> <para> -Searching wildcard names hashes is slower than searching exact name hash -because names are searched by domain parts. +Searching wildcard names hash table is slower than searching exact names hash +table because names are searched by domain parts. Note that the special wildcard form “<literal>.example.org</literal>” -is stored in a wildcard names hash and not in an exact names hash. +is stored in a wildcard names hash table and not in an exact names hash table. </para> <para> @@ -361,17 +371,17 @@ server { </para> <para> -If you have defined a large number of server names, -or defined unusually long server names, you may need to tune +If a large number of server names are defined, +or unusually long server names are defined, tuning the <link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/> and <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/> -directives at the <i>http</i> level. +directives at the <i>http</i> level may become necessary. The default value of the <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/> may be equal to 32, or 64, or another value, -depending on your CPU cache line size. -If the default value is 32 and you define -“too.long.server.name.example.org” as a server name, +depending on CPU cache line size. +If the default value is 32 and server name is defined as +“<literal>too.long.server.name.example.org</literal>” then nginx will fail to start and display the error message: <programlisting> @@ -379,7 +389,7 @@ could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32 </programlisting> -In this case, you should set the directive value to the next power of 2: +In this case, the directive value should be increased to the next power of two: <programlisting> http { @@ -387,8 +397,8 @@ http { ... </programlisting> -If you have defined a large number of server names, -you will get another error message: +If a large number of server names are defined, +another error message will appear: <programlisting> could not build the server_names_hash, @@ -396,18 +406,17 @@ you should increase either server_names_ or server_names_hash_bucket_size: 32 </programlisting> -You should first try to set +In such a case, first try to set <link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/> to a number close to the number of server names. Only if this does not help, -or if nginx’s start time is unacceptably long, -should you try to increase +or if nginx’s start time is unacceptably long, try to increase <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>. </para> <para> If a server is the only server for a listen port, then nginx will not test -server names at all (and will not build the hashes for the listen port). +server names at all (and will not build the hash tables for the listen port). However, there is one exception. If a <link doc="ngx_http_core_module.xml" id="server_name"/> @@ -425,7 +434,7 @@ then nginx has to execute the expression <list type="bullet"> <listitem> -A default server name value is an empty name “” since 0.8.48. +A default server name value is an empty name “” since 0.8.48. </listitem> <listitem> @@ -437,7 +446,7 @@ Regular expression server name captures </listitem> <listitem> -An empty server name “” has been supported since 0.7.12. +An empty server name “” has been supported since 0.7.12. </listitem> <listitem>