Mercurial > hg > nginx-site

annotate xml/en/docs/http/server_names.xml @ 2767:c56adb7148a4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Described more details about server selection. In particular, this covers how the large_client_header_buffers (ticket #1523) and underscores_in_headers (ticket #1987) directives work in virtual servers.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 13 Jul 2021 13:44:05 +0100
parents 30e2bd353998
children 3b5594157fab
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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"
2767
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
11 rev="4"
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
12 author="Igor Sysoev"
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13 editor="Brian Mercer">
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
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <section>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
17
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 <para>
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
19 Server names are defined using the
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
20 <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
21 directive
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
22 and determine which <link doc="ngx_http_core_module.xml" id="server"/> block
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
23 is used for a given request.
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
24 See also “<link doc="request_processing.xml"/>”.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25 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
26
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
28 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29 listen 80;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
30 server_name example.org www.example.org;
0
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 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
33
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
34 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
35 listen 80;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
36 server_name *.example.org;
0
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 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
39
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
40 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
41 listen 80;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
42 server_name mail.*;
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 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
45
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
46 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 listen 80;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
48 server_name ~^(?&lt;user&gt;.+)\.example\.net$;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 ...
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 </programlisting>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
52 </para>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
54 <para>
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
55 When searching for a virtual server by name, if name matches more than one of
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
56 the specified variants, e.g. both wildcard name and regular expression match,
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
57 the first matching variant will be chosen, in the following order of precedence:
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
58 <list type="enum">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
60 <listitem>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
61 exact name
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>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
65 longest wildcard name starting with an asterisk, e.g.
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
66 “<literal>*.example.org</literal>”
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>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
70 longest wildcard name ending with an asterisk, e.g. “<literal>mail.*</literal>”
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 <listitem>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
74 first matching regular expression
622
13f64b371d2c removed dot after list item
Vladimir Homutov <vl@nginx.com>
parents: 621
diff changeset
75 (in order of appearance in a configuration file)
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
76 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
78 </list>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 </section>
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
121
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
84 <section id="wildcard_names"
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
85 name="Wildcard names">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 <para>
625
af3f38e349eb Removed terminal whitespace and fixed apostrophes used.
Ruslan Ermilov <ru@nginx.com>
parents: 623
diff changeset
88 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
89 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
90 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
91 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
92 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
93 “<literal>~^w.*\.example\.org$</literal>”.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 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
95 The name “<literal>*.example.org</literal>” matches not only
593
130fad6dc1b4 Replaced the uses of "url" element with "literal".
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
96 <literal>www.example.org</literal> but <literal>www.sub.example.org</literal> as well.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
97 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
99 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
100 A special wildcard name in the form “<literal>.example.org</literal>” can be
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
101 used to match both the exact name “<literal>example.org</literal>”
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
102 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
103 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
104
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105 </section>
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
121
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
108 <section id="regex_names"
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
109 name="Regular expressions names">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
111 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
112 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
113 by the Perl programming language (PCRE).
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
114 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
115 character:
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 <programlisting>
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
118 server_name ~^www\d+\.example\.net$;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
119 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
120
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
121 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
122 an asterisk, as a wildcard name (and most likely as an invalid one).
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
123 Do not forget to set “<literal>^</literal>” and “<literal>$</literal>” anchors.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124 They are not required syntactically, but logically.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 Also note that domain name dots should be escaped with a backslash.
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
126 A regular expression containing the characters “<literal>{</literal>”
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
127 and “<literal>}</literal>” should be quoted:
0
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 <programlisting>
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
130 server_name "~^(?&lt;name&gt;\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
131 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 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
134
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
135 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
136 directive "server_name" is not terminated by ";" in ...
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
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 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
140
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143 server_name ~^(www\.)?(<b>?&lt;domain&gt;</b>.+)$;
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 location / {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 root /sites/<b>$domain</b>;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 }
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 </programlisting>
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 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
152
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
153 <table note="yes">
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
154
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155 <tr>
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
156 <td><literal>?&lt;<value>name</value>&gt;</literal></td>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 <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
158 </tr>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160 <tr>
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
161 <td><literal>?'<value>name</value>'</literal></td>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
162 <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
163 </tr>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 <tr>
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
166 <td><literal>?P&lt;<value>name</value>&gt;</literal></td>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 <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
168 </tr>
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 </table>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
171
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
172 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
173
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
174 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
175 pcre_compile() failed: unrecognized character after (?&lt; in ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
177
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
178 this means that the PCRE library is old and the syntax
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
179 “<literal>?P&lt;<value>name</value>&gt;</literal>” should be tried instead.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 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
181
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
182 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
183 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184 server_name ~^(www\.)?(.+)$;
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 location / {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
187 root /sites/<b>$2</b>;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
190 </programlisting>
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 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
193 since the digital references can easily be overwritten.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
195
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
196
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
197 </section>
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
121
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
200 <section id="miscellaneous_names"
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
201 name="Miscellaneous names">
0
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 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
204 There are some server names that are treated specially.
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
205 </para>
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
206
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
207 <para>
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
208 If it is required to process requests without the <header>Host</header>
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
209 header field in a <link doc="ngx_http_core_module.xml" id="server"/>
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
210 block which is not the default, an empty name should be specified:
0
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 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
213 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
214 listen 80;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
215 server_name example.org www.example.org "";
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
216 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
217 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
218 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
219 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
220
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
221 <para>
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
222 If no
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
223 <link doc="ngx_http_core_module.xml" id="server_name"/>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
224 is defined in a <link doc="ngx_http_core_module.xml" id="server"/> block
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
225 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
226 <note>
623
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
227 nginx versions up to 0.8.48 used the machine’s hostname as the server name
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
228 in this case.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229 </note>
645
bb450e295ca2 Translated "Server names" into Russian and slightly changed original layout.
Vladimir Homutov <vl@nginx.com>
parents: 625
diff changeset
230 </para>
bb450e295ca2 Translated "Server names" into Russian and slightly changed original layout.
Vladimir Homutov <vl@nginx.com>
parents: 625
diff changeset
231
bb450e295ca2 Translated "Server names" into Russian and slightly changed original layout.
Vladimir Homutov <vl@nginx.com>
parents: 625
diff changeset
232 <para>
623
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
233 If a server name is defined as “<literal>$hostname</literal>” (0.9.4), the
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
234 machine’s hostname is used.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
235 </para>
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 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
238 If someone makes a request using an IP address instead of a server name,
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
239 the <header>Host</header> request header field will contain the IP address
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
240 and the request can be handled using the IP address as the server name:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
244 listen 80;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
245 server_name example.org
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
246 www.example.org
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247 ""
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
248 <b>192.168.1.1</b>
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 ...
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 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
253 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
254
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
255 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
256 In catch-all server examples the strange name “<literal>_</literal>” can
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
257 be seen:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
258
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
259 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
260 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
261 listen 80 default_server;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
262 server_name _;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
263 return 444;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
264 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
265 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
266
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
267 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
268 of invalid domain names which never intersect with any real name.
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
269 Other invalid names like “<literal>--</literal>” and “<literal>!@#</literal>”
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
270 may equally be used.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
271 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
272
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
273 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
274 nginx versions up to 0.6.25 supported the special name “<literal>*</literal>”
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
275 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
276 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
277 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
278 by the
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
279 <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
280 directive.
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
281 The special name “<literal>*</literal>” is now deprecated
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
282 and the
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
283 <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
284 directive should be used.
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
285 Note that there is no way to specify the catch-all name or
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
286 the default server using the
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
287 <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
288 directive.
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
289 This is a property of the
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
290 <link doc="ngx_http_core_module.xml" id="listen"/>
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
291 directive
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
292 and not of the
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
293 <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
294 directive.
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
295 See also “<link doc="request_processing.xml"/>”.
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
296 It is possible to define servers listening on ports *:80 and *:8080,
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
297 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
298 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
299
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
300 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
301 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
302 listen 80;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
303 listen 8080 default_server;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
304 server_name example.net;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
305 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
306 }
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 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
309 listen 80 default_server;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
310 listen 8080;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
311 server_name example.org;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
312 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
313 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
314 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
315 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
316
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
317
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
318 </section>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
319
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
320
2042
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
321 <section id="idn"
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
322 name="Internationalized names">
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
323 <para>
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
324 Internationalized domain names
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
325 (<link url="https://en.wikipedia.org/wiki/Internationalized_domain_name">IDNs</link>)
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
326 should be specified using an ASCII (Punycode) representation
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
327 in the <link doc="ngx_http_core_module.xml" id="server_name"/> directive:
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
328 <programlisting>
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
329 server {
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
330 listen 80;
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
331 server_name xn--e1afmkfd.xn--80akhbyknj4f; # пример.испытание
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
332 ...
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
333 }
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
334 </programlisting>
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
335 </para>
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
336
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
337 </section>
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
338
30e2bd353998 Added info about Punycode to "Server Names".
Yaroslav Zhuravlev <yar@nginx.com>
parents: 966
diff changeset
339
2767
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
340 <section id="virtual_server_selection"
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
341 name="Virtual server selection">
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
342
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
343 <para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
344 First, a connection is created in a default server context.
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
345 Then, the server name can be determined
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
346 in the following request processing stages,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
347 each involved in server configuration selection:
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
348
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
349 <list type="bullet">
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
350
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
351 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
352 <para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
353 during SSL handshake, in advance, according to
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
354 <link doc="configuring_https_servers.xml" id="sni">SNI</link>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
355 </para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
356 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
357
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
358 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
359 <para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
360 after processing the request line
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
361 </para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
362 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
363
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
364 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
365 <para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
366 after processing the <literal>Host</literal> header field
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
367 </para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
368 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
369
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
370 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
371 <para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
372 if the server name was not determined after processing the request line or
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
373 from the <literal>Host</literal> header field,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
374 nginx will use the empty name as the server name.
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
375 </para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
376 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
377
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
378 </list>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
379
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
380 At each of these stages, different server configurations can be applied.
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
381 As such, certain directives should be specified with caution:
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
382 <list type="bullet">
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
383
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
384 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
385 in case of the
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
386 <link doc="ngx_http_ssl_module.xml" id="ssl_protocols"/> directive,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
387 the protocol list is set by the OpenSSL library before
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
388 the server configuration could be applied according to the name
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
389 requested through SNI,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
390 thus, protocols should be specified only for a default server;
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
391 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
392
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
393 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
394 the
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
395 <link doc="ngx_http_core_module.xml" id="client_header_buffer_size"/>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
396 and
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
397 <link doc="ngx_http_core_module.xml" id="merge_slashes"/> directives
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
398 are involved before reading the request line,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
399 thus, such directives use a default server configuration or
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
400 the server configuration chosen by SNI;
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
401 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
402
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
403 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
404 in case of the
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
405 <link doc="ngx_http_core_module.xml" id="ignore_invalid_headers"/>,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
406 <link doc="ngx_http_core_module.xml" id="large_client_header_buffers"/>,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
407 and
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
408 <link doc="ngx_http_core_module.xml" id="underscores_in_headers"/> directives
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
409 involved in processing request header fields,
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
410 it additionally depends
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
411 whether the server configuration was updated
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
412 according to the request line or the <literal>Host</literal> header field;
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
413 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
414
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
415 <listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
416 an error response will be handled with
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
417 the <link doc="ngx_http_core_module.xml" id="error_page"/> directive
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
418 in the server that currently fulfills the request.
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
419 </listitem>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
420
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
421 </list>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
422 </para>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
423
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
424 </section>
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
425
c56adb7148a4 Described more details about server selection.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2042
diff changeset
426
121
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
427 <section id="optimization"
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
428 name="Optimization">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
429
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
430 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
431 Exact names, wildcard names starting with an asterisk,
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
432 and wildcard names ending with an asterisk are stored
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
433 in three hash tables bound to the listen ports.
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
434 The sizes of hash tables are optimized at the configuration phase
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
435 so that a name can be found with the fewest CPU cache misses.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 659
diff changeset
436 The details of setting up hash tables are provided in a separate
659
77a3314c74a7 Avoid the uses of second person.
Ruslan Ermilov <ru@nginx.com>
parents: 645
diff changeset
437 <link doc="../hash.xml">document</link>.
618
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
438 </para>
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
439
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
440 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
441 The exact names hash table is searched first.
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
442 If a name is not found, the hash table with wildcard names
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
443 starting with an asterisk is searched.
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
444 If the name is not found there, the hash table with wildcard names
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
445 ending with an asterisk is searched.
618
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
446 </para>
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
447
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
448 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
449 Searching wildcard names hash table is slower than searching exact names hash
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
450 table 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
451 Note that the special wildcard form “<literal>.example.org</literal>”
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
452 is stored in a wildcard names hash table and not in an exact names hash table.
618
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
453 </para>
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
454
2300e4c1a231 Improved paragraph layout in the 'Optimization' section
Vladimir Homutov <vl@nginx.com>
parents: 593
diff changeset
455 <para>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
456 Regular expressions are tested sequentially
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
457 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
458 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
459
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
460 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
461 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
462 For example, if the most frequently requested names of a server
593
130fad6dc1b4 Replaced the uses of "url" element with "literal".
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
463 are <literal>example.org</literal> and <literal>www.example.org</literal>,
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
464 it is more efficient to define them explicitly:
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
465
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
466 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
467 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
468 listen 80;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
469 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
470 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
471 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
472 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
473
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
474 than to use the simplified form:
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
475
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
476 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
477 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
478 listen 80;
490
9913f1d51c07 Replaced "nginx" domain names with example domains.
Ruslan Ermilov <ru@nginx.com>
parents: 461
diff changeset
479 server_name .example.org;
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
480 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
481 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
482 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
483 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
484
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
485 <para>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
486 If a large number of server names are defined,
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
487 or unusually long server names are defined, tuning
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
488 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
489 and <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
490 directives at the <i>http</i> level may become necessary.
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
491 The default value of the
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
492 <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>
645
bb450e295ca2 Translated "Server names" into Russian and slightly changed original layout.
Vladimir Homutov <vl@nginx.com>
parents: 625
diff changeset
493 directive may be equal to 32, or 64, or another value,
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
494 depending on CPU cache line size.
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
495 If the default value is 32 and server name is defined as
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
496 “<literal>too.long.server.name.example.org</literal>”
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
497 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
498
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
499 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
500 could not build the server_names_hash,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
501 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
502 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
503
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
504 In this case, the directive value should be increased to the next power of two:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
505
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
506 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
507 http {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
508 server_names_hash_bucket_size 64;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
509 ...
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
510 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
511
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
512 If a large number of server names are defined,
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
513 another error message will appear:
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
514
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
515 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
516 could not build the server_names_hash,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
517 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
518 or server_names_hash_bucket_size: 32
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
519 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
520
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
521 In such a case, first try to set
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
522 <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
523 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
524 Only if this does not help,
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
525 or if nginx’s start time is unacceptably long, try to increase
271
4c6d2c614d2c Cleaned up XML tag mess:
Ruslan Ermilov <ru@nginx.com>
parents: 123
diff changeset
526 <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
527 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
528
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
529 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
530 If a server is the only server for a listen port, then nginx will not test
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
531 server names at all (and will not build the hash tables for the listen port).
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
532 However, there is one exception.
645
bb450e295ca2 Translated "Server names" into Russian and slightly changed original layout.
Vladimir Homutov <vl@nginx.com>
parents: 625
diff changeset
533 If a server name is a regular expression with captures,
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
534 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
535 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
536
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
537 </section>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
538
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
539
121
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
540 <section id="compatibility"
49443032011c Unified <section> syntax for "article" and "module" documents.
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
541 name="Compatibility">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
542
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
543 <para>
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
544 <list type="bullet">
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
545
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
546 <listitem>
623
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
547 The special server name “<literal>$hostname</literal>” has been supported
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
548 since 0.9.4.
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
549 </listitem>
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
550
7158aa1ec520 Added special server name '$hostname' description.
Vladimir Homutov <vl@nginx.com>
parents: 622
diff changeset
551 <listitem>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
552 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
553 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
554
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
555 <listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
556 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
557 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
558
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
559 <listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
560 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
561 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
562
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
563 <listitem>
621
656dfb085020 Unified server names matching description with server_name directive, improved
Vladimir Homutov <vl@nginx.com>
parents: 618
diff changeset
564 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
565 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
566
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
567 <listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
568 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
569 as the first server name since 0.6.25.
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
570 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
571
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
572 <listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
573 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
574 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
575
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
576 <listitem>
593
130fad6dc1b4 Replaced the uses of "url" element with "literal".
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
577 Wildcard form <literal>example.*</literal> has been supported since 0.6.0.
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
578 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
579
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
580 <listitem>
593
130fad6dc1b4 Replaced the uses of "url" element with "literal".
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
581 The special form <literal>.example.org</literal> has been supported since 0.3.18.
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
582 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
583
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
584 <listitem>
593
130fad6dc1b4 Replaced the uses of "url" element with "literal".
Ruslan Ermilov <ru@nginx.com>
parents: 589
diff changeset
585 Wildcard form <literal>*.example.org</literal> has been supported since 0.1.13.
461
6135f3c95bf6 Unified markup for lists.
Ruslan Ermilov <ru@nginx.com>
parents: 374
diff changeset
586 </listitem>
0
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
587
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
588 </list>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
589 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
590
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
591 </section>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
592
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
593 </article>