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

annotate xml/en/docs/http/server_names.xml @ 587:5bb7716cae7e

Documented in more depth how server names are matched.

author	Ruslan Ermilov <ru@nginx.com>
date	Thu, 12 Jul 2012 09:58:35 +0000
parents	be54c443235a
children	764fbac1b8b4

rev	line source
580 be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	1 <!--
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	2 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	3 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	4 -->
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	5
50 9d544687d02c Fixed DOCTYPE declaration. Ruslan Ermilov <ru@nginx.com> parents: 0 diff changeset	6 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	7
123 7db449e89e92 Unified the use of the "name" attribute instead of "title". Ruslan Ermilov <ru@nginx.com> parents: 121 diff changeset	8 <article name="Server names"
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	9 link="/en/docs/http/server_names.html"
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	10 lang="en"
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	11 author="Igor Sysoev"
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	12 editor="Brian Mercer">
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	13
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	14
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	15 <section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	16
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	17 <para>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	18 Server names are defined using the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	19 <link doc="ngx_http_core_module.xml" id="server_name"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	20 directive
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	21 and determine which server block is used for a given request.
374 a413dffb0557 Replaced "a href" with "link doc" / "link url". Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	22 See also “<link doc="request_processing.xml"/>”.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	23 They may be defined using exact names, wildcard names, or regular expressions:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	24
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	25 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	26 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	27 listen 80;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	28 server_name example.org www.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	29 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	30 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	31
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	32 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	33 listen 80;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	34 server_name *.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	35 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	36 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	37
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	38 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	39 listen 80;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	40 server_name mail.*;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	43
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	44 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	45 listen 80;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	46 server_name ~^(?<user>.+)\.example\.net$;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	47 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	48 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	49 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	50
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	51 The names are tested in the following order:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	52
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	53 <list type="enum">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	54
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	55 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	56 exact names;
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	57 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	58
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	59 <listitem>
587 5bb7716cae7e Documented in more depth how server names are matched. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	60 wildcard names starting with an asterisk: <url>*.example.org</url>
5bb7716cae7e Documented in more depth how server names are matched. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	61 (longest first);
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	62 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	63
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	64 <listitem>
587 5bb7716cae7e Documented in more depth how server names are matched. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	65 wildcard names ending with an asterisk: <url>mail.*</url>
5bb7716cae7e Documented in more depth how server names are matched. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	66 (longest first);
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	67 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	68
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	69 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	70 and regular expressions in the order listed in the configuration file.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	71 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	72
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	73 </list>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	74 The first match stops the search.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	75 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	76
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	77 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	78
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	79
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	80 <section id="wildcard_names"
49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	81 name="Wildcard names">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	82
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	83 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	84 A wildcard name may contain an asterisk only on the name's start or end,
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	85 and only on a dot border. The names “<literal>www.*.example.org</literal>”
9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	86 and “<literal>w*.example.org</literal>” are invalid.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	87 However, these names can be specified using regular expressions,
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	88 for example, “<literal>~^www\..+\.example\.org$</literal>” and
9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	89 “<literal>~^w.*\.example\.org$</literal>”.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	90 An asterisk can match several name parts.
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	91 The name “<literal>*.example.org</literal>” matches not only
9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	92 <url>www.example.org</url> but <url>www.sub.example.org</url> as well.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	93 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	94
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	95 <para>
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	96 A special wildcard in the form “<literal>.example.org</literal>” can be used
9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	97 to match both the exact name “<literal>example.org</literal>”
9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	98 and the wildcard name “<literal>*.example.org</literal>”.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	99 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	100
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	101 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	102
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	103
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	104 <section id="regex_names"
49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	105 name="Regular expressions names">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	106
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	107 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	108 The regular expressions used by nginx are compatible with those used
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	109 by the Perl programming language (PCRE).
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	110 To use a regular expression, the server name must start with the tilde
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	111 character:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	112
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	113 <programlisting>
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	114 server_name ~^www\d+\.example\.net$;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	115 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	116
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	117 otherwise it will be treated as an exact name, or if the expression contains
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	118 an asterisk, as a wildcard name (and most likely as an invalid one).
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	119 Do not forget to set “^” and “$” anchors.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	120 They are not required syntactically, but logically.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	121 Also note that domain name dots should be escaped with a backslash.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	122 A regular expression containing the characters “{”
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	123 and “}” should be quoted:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	124
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	125 <programlisting>
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	126 server_name "~^(?<name>\w\d<b>{</b>1,3<b>}</b>+)\.example\.net$";
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	127 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	128
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	129 otherwise nginx will fail to start and display the error message:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	130
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	131 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	132 directive "server_name" is not terminated by ";" in ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	133 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	134
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	135 A named regular expression capture can be used later as a variable:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	136
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	137 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	138 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	139 server_name ~^(www\.)?(<b>?<domain></b>.+)$;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	140
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	141 location / {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	142 root /sites/<b>$domain</b>;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	143 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	144 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	145 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	146
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	147 The PCRE library supports named captures using the following syntax:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	148
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	149 <table note="yes">
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	150
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	151 <tr>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	152 <td><literal>?<<value>name</value>></literal></td>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	153 <td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	154 </tr>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	155
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	156 <tr>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	157 <td><literal>?'<value>name</value>'</literal></td>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	158 <td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	159 </tr>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	160
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	161 <tr>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	162 <td><literal>?P<<value>name</value>></literal></td>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	163 <td>Python compatible syntax, supported since PCRE-4.0</td>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	164 </tr>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	165
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	166 </table>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	167
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	168 If nginx fails to start and displays the error message:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	169
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	170 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	171 pcre_compile() failed: unrecognized character after (?< in ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	172 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	173
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	174 this means that the PCRE library is old
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	175 and you should try the syntax “<literal>?P<<value>name</value>></literal>”.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	176 The captures can also be used in digital form:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	177
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	178 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	179 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	180 server_name ~^(www\.)?(.+)$;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	181
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	182 location / {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	183 root /sites/<b>$2</b>;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	184 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	185 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	186 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	187
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	188 However, such usage should be limited to simple cases (like the above),
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	189 since the digital references can easily be overwritten.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	190 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	191
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	192
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	193 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	194
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	195
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	196 <section id="miscellaneous_names"
49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	197 name="Miscellaneous names">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	198
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	199 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	200 If you want to process requests without a “Host” header line
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	201 in a server block which is not the default, you should specify an empty name:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	202
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	203 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	204 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	205 listen 80;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	206 server_name example.org www.example.org "";
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	207 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	208 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	209 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	210 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	211
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	212 <para>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	213 If no
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	214 <link doc="ngx_http_core_module.xml" id="server_name"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	215 is defined in a server block,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	216 then nginx uses the empty name as the server name.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	217 <note>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	218 nginx versions up to 0.8.48 used the <i>hostname</i> as the server name
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	219 in this case.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	220 </note>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	221 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	222
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	223 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	224 If someone makes a request using an IP address instead of a server name,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	225 the request’s “Host” header line will contain the IP address
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	226 and you can handle the request using the IP address as the server name:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	227
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	228 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	229 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	230 listen 80;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	231 server_name example.org
9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	232 www.example.org
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	233 ""
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	234 <b>192.168.1.1</b>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	235 ;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	236 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	237 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	238 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	239 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	240
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	241 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	242 In catch-all server examples you may see the strange name “_”:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	243
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	244 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	245 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	246 listen 80 default_server;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	247 server_name _;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	248 return 444;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	249 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	250 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	251
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	252 There is nothing special about this name, it is just one of a myriad
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	253 of invalid domain names which never intersect with any real name.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	254 You may also use something like “--”, “!@#”, and so on.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	255 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	256
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	257 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	258 nginx versions up to 0.6.25 supported the special name “*”
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	259 which was erroneously interpreted to be a catch-all name.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	260 It never functioned as a catch-all or wildcard server name.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	261 Instead, it supplied the functionality that is now provided
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	262 by the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	263 <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	264 directive.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	265 The special name “*” is now deprecated
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	266 and the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	267 <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	268 directive should be used.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	269 Note that there is no way to specify the catch-all name or
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	270 the <i>default</i> server using the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	271 <link doc="ngx_http_core_module.xml" id="server_name"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	272 directive.
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	273 This is a property of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	274 <link doc="ngx_http_core_module.xml" id="listen"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	275 directive
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	276 and not of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	277 <link doc="ngx_http_core_module.xml" id="server_name"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	278 directive.
374 a413dffb0557 Replaced "a href" with "link doc" / "link url". Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	279 See also “<link doc="request_processing.xml"/>”.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	280 You can define servers listening on ports :80 and :8080,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	281 and direct that one will be the default server for port *:8080,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	282 while the other will be the default for port *:80:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	283
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	284 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	285 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	286 listen 80;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	287 listen 8080 default_server;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	288 server_name example.net;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	289 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	290 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	291
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	292 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	293 listen 80 default_server;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	294 listen 8080;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	295 server_name example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	296 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	297 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	298 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	299 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	300
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	301
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	302 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	303
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	304
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	305 <section id="optimization"
49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	306 name="Optimization">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	307
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	308 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	309 Exact names and wildcard names are stored in hashes.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	310 The hashes are bound to the listen ports and every listen port
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	311 may have up to three hashes: an exact names hash, a wildcard names hash
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	312 starting with an asterisk, and a wildcard names hash ending with an asterisk.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	313 The sizes of the hashes are optimized at the configuration phase so that
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	314 a name can be found with the fewest CPU cache misses.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	315 The exact names hash is searched first.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	316 If a name is not found using the exact name hash, then the wildcard names hash
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	317 starting with an asterisk is searched.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	318 If the name is not found there, the wildcard names hash
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	319 ending with an asterisk is searched.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	320 Searching wildcard names hashes is slower than searching exact name hash
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	321 because names are searched by domain parts.
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	322 Note that the special wildcard form “<literal>.example.org</literal>”
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	323 is stored in a wildcard names hash and not in an exact names hash.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	324 Regular expressions are tested sequentially
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	325 and therefore are the slowest method and are non-scalable.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	326 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	327
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	328 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	329 For these reasons, it is better to use exact names where possible.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	330 For example, if the most frequently requested names of a server
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	331 are <url>example.org</url> and <url>www.example.org</url>,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	332 it is more efficient to define them explicitly:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	333
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	334 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	335 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	336 listen 80;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	337 server_name example.org www.example.org *.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	338 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	339 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	340 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	341
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	342 than to use the simplified form:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	343
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	344 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	345 server {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	346 listen 80;
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	347 server_name .example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	348 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	349 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	350 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	351 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	352
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	353 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	354 If you have defined a large number of server names,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	355 or defined unusually long server names, you may need to tune
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	356 the <link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	357 and <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	358 directives at the <i>http</i> level.
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	359 The default value of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	360 <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	361 may be equal to 32, or 64, or another value,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	362 depending on your CPU cache line size.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	363 If the default value is 32 and you define
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	364 “too.long.server.name.example.org” as a server name,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	365 then nginx will fail to start and display the error message:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	366
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	367 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	368 could not build the server_names_hash,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	369 you should increase server_names_hash_bucket_size: 32
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	370 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	371
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	372 In this case, you should set the directive value to the next power of 2:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	373
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	374 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	375 http {
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	376 server_names_hash_bucket_size 64;
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	377 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	378 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	379
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	380 If you have defined a large number of server names,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	381 you will get another error message:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	382
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	383 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	384 could not build the server_names_hash,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	385 you should increase either server_names_hash_max_size: 512
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	386 or server_names_hash_bucket_size: 32
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	387 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	388
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	389 You should first try to set
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	390 <link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	391 to a number close to the number of server names.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	392 Only if this does not help,
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	393 or if nginx’s start time is unacceptably long,
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	394 should you try to increase
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	395 <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	396 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	397
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	398 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	399 If a server is the only server for a listen port, then nginx will not test
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	400 server names at all (and will not build the hashes for the listen port).
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	401 However, there is one exception.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	402 If a
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	403 <link doc="ngx_http_core_module.xml" id="server_name"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 123 diff changeset	404 is a regular expression with captures,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	405 then nginx has to execute the expression to get the captures.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	406 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	407
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	408 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	409
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	410
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	411 <section id="compatibility"
49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	412 name="Compatibility">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	413
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	414 <para>
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	415 <list type="bullet">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	416
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	417 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	418 A default server name value is an empty name “” since 0.8.48.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	419 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	420
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	421 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	422 Named regular expression server name captures have been supported since 0.8.25.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	423 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	424
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	425 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	426 Regular expression server name captures have been supported since 0.7.40.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	427 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	428
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	429 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	430 An empty server name “” has been supported since 0.7.12.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	431 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	432
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	433 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	434 A wildcard server name or regular expression has been supported for use
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	435 as the first server name since 0.6.25.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	436 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	437
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	438 <listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	439 Regular expression server names have been supported since 0.6.7.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	440 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	441
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	442 <listitem>
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	443 Wildcard form <url>example.*</url> has been supported since 0.6.0.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	444 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	445
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	446 <listitem>
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	447 The special form <url>.example.org</url> has been supported since 0.3.18.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	448 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	449
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	450 <listitem>
490 9913f1d51c07 Replaced "nginx" domain names with example domains. Ruslan Ermilov <ru@nginx.com> parents: 461 diff changeset	451 Wildcard form <url>*.example.org</url> has been supported since 0.1.13.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 374 diff changeset	452 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	453
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	454 </list>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	455 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	456
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	457 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	458
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	459 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/server_names.xml @ 587:5bb7716cae7e