Mercurial > hg > nginx-site

annotate xml/en/docs/http/server_names.xml @ 2769:16f6fa718be2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated TLSv1.3 support notes. Previous notes described some early development snapshot of OpenSSL 1.1.1 with disabled TLSv1.3 by default. It was then enabled in the first alpha. Further, the updated text covers later major releases such as OpenSSL 3.0.
author Sergey Kandaurov <pluknet@nginx.com>
date Thu, 30 Sep 2021 16:29:20 +0300
parents c56adb7148a4
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>