nginx-site: xml/en/docs/http/server

comparison xml/en/docs/http/server_names.xml @ 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	2300e4c1a231
children	13f64b371d2c

comparison

equal deleted inserted replaced

-:32f50b2f9f0c
+:656dfb085020
 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
 <article name="Server names"
 link="/en/docs/http/server_names.html"
 lang="en"
-rev="1"
+rev="2"
 author="Igor Sysoev"
 editor="Brian Mercer">
 <section>
 <para>
 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.
+and determine which <link doc="ngx_http_core_module.xml" id="server"/> block
-See also &ldquo;<link doc="request_processing.xml"/>&rdquo;.
+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>
 server {
 listen       80;
 listen       80;
 server_name  ~^(?&lt;user&gt;.+)\.example\.net$;
 ...
 }
 </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 wildcard name starting with an asterisk, e.g.
-(longest first);
+“<literal>*.example.org</literal>”
 </listitem>
 <listitem>
-wildcard names ending with an asterisk: <literal>mail.*</literal>
+longest wildcard name ending with an asterisk, e.g. “<literal>mail.*</literal>”
-(longest first);
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+first matching regular expression
-and regular expressions in the order listed in the configuration file.
+(in order of appearance in a configuration file).
 </listitem>
 </list>
-The first match stops the search.
 </para>
 </section>
 The name “<literal>*.example.org</literal>” matches not only
 <literal>www.example.org</literal> but <literal>www.sub.example.org</literal> as well.
 </para>
 <para>
-A special wildcard in the form “<literal>.example.org</literal>” can be used
+A special wildcard name in the form “<literal>.example.org</literal>” can be
-to match both the exact name “<literal>example.org</literal>”
+used to match both the exact name “<literal>example.org</literal>”
 and the wildcard name “<literal>*.example.org</literal>”.
 </para>
 </section>
 server_name  ~^www\d+\.example\.net$;
 </programlisting>
 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 &ldquo;^&rdquo; and &ldquo;$&rdquo; 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 &ldquo;{&rdquo;
+A regular expression containing the characters “<literal>{</literal>”
-and &ldquo;}&rdquo; should be quoted:
+and “<literal>}</literal>” should be quoted:
 <programlisting>
 server_name  "~^(?&lt;name&gt;\w\d<b>{</b>1,3<b>}</b>+)\.example\.net$";
 </programlisting>
 <programlisting>
 pcre_compile() failed: unrecognized character after (?&lt; in ...
 </programlisting>
-this means that the PCRE library is old
+this means that the PCRE library is old and the syntax
-and you should try the syntax “<literal>?P&lt;<value>name</value>&gt;</literal>”.
+“<literal>?P&lt;<value>name</value>&gt;</literal>” should be tried instead.
 The captures can also be used in digital form:
 <programlisting>
 server {
 server_name   ~^(www\.)?(.+)$;
 <section id="miscellaneous_names"
 name="Miscellaneous names">
 <para>
-If you want to process requests without a &ldquo;Host&rdquo; header line
+There are some server names that are treated specially.
-in a server block which is not the default, you should specify an empty name:
+</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 {
 listen       80;
 server_name  example.org  www.example.org  "";
 </para>
 <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
 in this case.
 </note>
 </para>
 <para>
 If someone makes a request using an IP address instead of a server name,
-the request&rsquo;s &ldquo;Host&rdquo; header line will contain the IP address
+the <header>Host</header> request header field will contain the IP address
-and you can handle the request using the IP address as the server name:
+and the request can be handled using the IP address as the server name:
 <programlisting>
 server {
 listen       80;
 server_name  example.org
 }
 </programlisting>
 </para>
 <para>
-In catch-all server examples you may see the strange name &ldquo;_&rdquo;:
+In catch-all server examples the strange name “<literal>_</literal>” can
+be seen:
 <programlisting>
 server {
 listen       80  default_server;
 server_name  _;
 }
 </programlisting>
 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 &ldquo;--&rdquo;, &ldquo;!@#&rdquo;, and so on.
+Other invalid names like “<literal>--</literal>” and “<literal>!@#</literal>”
-</para>
+may equally be used.
+</para>
-<para>
-nginx versions up to 0.6.25 supported the special name &ldquo;*&rdquo;
+<para>
+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 &ldquo;*&rdquo; 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
 <link doc="ngx_http_core_module.xml" id="listen"/>
 directive
 and not of the
 <link doc="ngx_http_core_module.xml" id="server_name"/>
 directive.
-See also &ldquo;<link doc="request_processing.xml"/>&rdquo;.
+See also “<link doc="request_processing.xml"/>”.
-You can define servers listening on ports *:80 and *:8080,
+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:
 <programlisting>
 server {
 <section id="optimization"
 name="Optimization">
 <para>
-Exact names and wildcard names are stored in hashes.
+Exact names, wildcard names starting with an asterisk,
-The hashes are bound to the listen ports and every listen port
+and wildcard names ending with an asterisk are stored
-may have up to three hashes: an exact names hash, a wildcard names hash
+in three hash tables bound to the listen ports.
-starting with an asterisk, and a wildcard names hash ending with an asterisk.
+The sizes of hash tables are optimized at the configuration phase
-The sizes of the hashes are optimized at the configuration phase so that
+so that a name can be found with the fewest CPU cache misses.
-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.
+The exact names hash table is searched first.
-If a name is not found using the exact name hash, then the wildcard names hash
+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
+Searching wildcard names hash table is slower than searching exact names hash
-because names are searched by domain parts.
+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>
 Regular expressions are tested sequentially
 and therefore are the slowest method and are non-scalable.
 }
 </programlisting>
 </para>
 <para>
-If you have defined a large number of server names,
+If a large number of server names are defined,
-or defined unusually long server names, you may need to tune
+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.
+depending on CPU cache line size.
-If the default value is 32 and you define
+If the default value is 32 and server name is defined as
-&ldquo;too.long.server.name.example.org&rdquo; as a server name,
+“<literal>too.long.server.name.example.org</literal>”
 then nginx will fail to start and display the error message:
 <programlisting>
 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 {
 server_names_hash_bucket_size  64;
 ...
 </programlisting>
-If you have defined a large number of server names,
+If a large number of server names are defined,
-you will get another error message:
+another error message will appear:
 <programlisting>
 could not build the server_names_hash,
 you should increase either server_names_hash_max_size: 512
 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&rsquo;s start time is unacceptably long,
+or if nginx’s start time is unacceptably long, try to increase
-should you 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"/>
 is a regular expression with captures,
 then nginx has to execute the expression to get the captures.
 <para>
 <list type="bullet">
 <listitem>
-A default server name value is an empty name &ldquo;&rdquo; since 0.8.48.
+A default server name value is an empty name “” since 0.8.48.
 </listitem>
 <listitem>
 Named regular expression server name captures have been supported since 0.8.25.
 </listitem>
 <listitem>
 Regular expression server name captures have been supported since 0.7.40.
 </listitem>
 <listitem>
-An empty server name &ldquo;&rdquo; has been supported since 0.7.12.
+An empty server name “” has been supported since 0.7.12.
 </listitem>
 <listitem>
 A wildcard server name or regular expression has been supported for use
 as the first server name since 0.6.25.

Mercurial > hg > nginx-site

comparison xml/en/docs/http/server_names.xml @ 621:656dfb085020