Mercurial > hg > nginx-site
comparison xml/en/docs/http/server_names.xml @ 271:4c6d2c614d2c
Cleaned up XML tag mess:
- all of <parameter> and <code>, and some of <dirname>, <value>,
and <command> were replaced by <literal>;
- the rest of <dirname> were replaced by links;
- <argument> were replaced by <value>;
- <value> is now rendered in HTML in italic;
- <literal> and <path> can now contain <value>.
Cleaned up terminology mess:
- directives take "parameters".
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Fri, 23 Dec 2011 17:29:59 +0000 |
parents | 7db449e89e92 |
children | a413dffb0557 |
comparison
equal
deleted
inserted
replaced
270:945d7299c26c | 271:4c6d2c614d2c |
---|---|
8 | 8 |
9 | 9 |
10 <section> | 10 <section> |
11 | 11 |
12 <para> | 12 <para> |
13 Server names are defined using the <dirname>server_name</dirname> directive | 13 Server names are defined using the |
14 <link doc="ngx_http_core_module.xml" id="server_name"/> | |
15 directive | |
14 and determine which server block is used for a given request. | 16 and determine which server block is used for a given request. |
15 See also “<a href="/en/docs/http/request_processing.xml" />”. | 17 See also “<a href="/en/docs/http/request_processing.xml" />”. |
16 They may be defined using exact names, wildcard names, or regular expressions: | 18 They may be defined using exact names, wildcard names, or regular expressions: |
17 | 19 |
18 <programlisting> | 20 <programlisting> |
71 <section id="wildcard_names" | 73 <section id="wildcard_names" |
72 name="Wildcard names"> | 74 name="Wildcard names"> |
73 | 75 |
74 <para> | 76 <para> |
75 A wildcard name may contain an asterisk only on the name's start or end, | 77 A wildcard name may contain an asterisk only on the name's start or end, |
76 and only on a dot border. The names <dirname>www.*.nginx.org</dirname> | 78 and only on a dot border. The names “<literal>www.*.nginx.org</literal>” |
77 and <dirname>w*.nginx.org</dirname> are invalid. | 79 and “<literal>w*.nginx.org</literal>” are invalid. |
78 However, these names can be specified using regular expressions, | 80 However, these names can be specified using regular expressions, |
79 for example, <dirname>~^www\..+\.nginx\.org$</dirname> and | 81 for example, “<literal>~^www\..+\.nginx\.org$</literal>” and |
80 <dirname>~^w.*\.nginx\.org$</dirname>. | 82 “<literal>~^w.*\.nginx\.org$</literal>”. |
81 An asterisk can match several name parts. | 83 An asterisk can match several name parts. |
82 The name <dirname>*.nginx.org</dirname> matches not only | 84 The name “<literal>*.nginx.org</literal>” matches not only |
83 <url>www.nginx.org</url> but <url>www.sub.nginx.org</url> as well. | 85 <url>www.nginx.org</url> but <url>www.sub.nginx.org</url> as well. |
84 </para> | 86 </para> |
85 | 87 |
86 <para> | 88 <para> |
87 A special wildcard in the form <dirname>.nginx.org</dirname> can be used | 89 A special wildcard in the form “<literal>.nginx.org</literal>” can be used |
88 to match both the exact name <dirname>nginx.org</dirname> | 90 to match both the exact name “<literal>nginx.org</literal>” |
89 and the wildcard name <dirname>*.nginx.org</dirname>. | 91 and the wildcard name “<literal>*.nginx.org</literal>”. |
90 </para> | 92 </para> |
91 | 93 |
92 </section> | 94 </section> |
93 | 95 |
94 | 96 |
138 The PCRE library supports named captures using the following syntax: | 140 The PCRE library supports named captures using the following syntax: |
139 | 141 |
140 <table note="yes"> | 142 <table note="yes"> |
141 | 143 |
142 <tr> | 144 <tr> |
143 <td><code>?<<i>name</i>></code></td> | 145 <td><literal>?<<value>name</value>></literal></td> |
144 <td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td> | 146 <td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td> |
145 </tr> | 147 </tr> |
146 | 148 |
147 <tr> | 149 <tr> |
148 <td><code>?'<i>name</i>'</code></td> | 150 <td><literal>?'<value>name</value>'</literal></td> |
149 <td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td> | 151 <td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td> |
150 </tr> | 152 </tr> |
151 | 153 |
152 <tr> | 154 <tr> |
153 <td><code>?P<<i>name</i>></code></td> | 155 <td><literal>?P<<value>name</value>></literal></td> |
154 <td>Python compatible syntax, supported since PCRE-4.0</td> | 156 <td>Python compatible syntax, supported since PCRE-4.0</td> |
155 </tr> | 157 </tr> |
156 | 158 |
157 </table> | 159 </table> |
158 | 160 |
161 <programlisting> | 163 <programlisting> |
162 pcre_compile() failed: unrecognized character after (?< in ... | 164 pcre_compile() failed: unrecognized character after (?< in ... |
163 </programlisting> | 165 </programlisting> |
164 | 166 |
165 this means that the PCRE library is old | 167 this means that the PCRE library is old |
166 and you should try the syntax <dirname>?P<<i>name</i>></dirname>. | 168 and you should try the syntax “<literal>?P<<value>name</value>></literal>”. |
167 The captures can also be used in digital form: | 169 The captures can also be used in digital form: |
168 | 170 |
169 <programlisting> | 171 <programlisting> |
170 server { | 172 server { |
171 server_name ~^(www\.)?(.+)$; | 173 server_name ~^(www\.)?(.+)$; |
199 } | 201 } |
200 </programlisting> | 202 </programlisting> |
201 </para> | 203 </para> |
202 | 204 |
203 <para> | 205 <para> |
204 If no <dirname>server_name</dirname> is defined in a server block, | 206 If no |
207 <link doc="ngx_http_core_module.xml" id="server_name"/> | |
208 is defined in a server block, | |
205 then nginx uses the empty name as the server name. | 209 then nginx uses the empty name as the server name. |
206 <note> | 210 <note> |
207 nginx versions up to 0.8.48 used the <i>hostname</i> as the server name | 211 nginx versions up to 0.8.48 used the <i>hostname</i> as the server name |
208 in this case. | 212 in this case. |
209 </note> | 213 </note> |
246 <para> | 250 <para> |
247 nginx versions up to 0.6.25 supported the special name “*” | 251 nginx versions up to 0.6.25 supported the special name “*” |
248 which was erroneously interpreted to be a catch-all name. | 252 which was erroneously interpreted to be a catch-all name. |
249 It never functioned as a catch-all or wildcard server name. | 253 It never functioned as a catch-all or wildcard server name. |
250 Instead, it supplied the functionality that is now provided | 254 Instead, it supplied the functionality that is now provided |
251 by the <dirname>server_name_in_redirect</dirname> directive. | 255 by the |
256 <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> | |
257 directive. | |
252 The special name “*” is now deprecated | 258 The special name “*” is now deprecated |
253 and the <dirname>server_name_in_redirect</dirname> directive should be used. | 259 and the |
260 <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> | |
261 directive should be used. | |
254 Note that there is no way to specify the catch-all name or | 262 Note that there is no way to specify the catch-all name or |
255 the <i>default</i> server using the <dirname>server_name</dirname> directive. | 263 the <i>default</i> server using the |
256 This is a property of the <dirname>listen</dirname> directive | 264 <link doc="ngx_http_core_module.xml" id="server_name"/> |
257 and not of the <dirname>server_name</dirname> directive. | 265 directive. |
266 This is a property of the | |
267 <link doc="ngx_http_core_module.xml" id="listen"/> | |
268 directive | |
269 and not of the | |
270 <link doc="ngx_http_core_module.xml" id="server_name"/> | |
271 directive. | |
258 See also “<a href="/en/docs/http/request_processing.xml" />”. | 272 See also “<a href="/en/docs/http/request_processing.xml" />”. |
259 You can define servers listening on ports *:80 and *:8080, | 273 You can define servers listening on ports *:80 and *:8080, |
260 and direct that one will be the default server for port *:8080, | 274 and direct that one will be the default server for port *:8080, |
261 while the other will be the default for port *:80: | 275 while the other will be the default for port *:80: |
262 | 276 |
296 starting with an asterisk is searched. | 310 starting with an asterisk is searched. |
297 If the name is not found there, the wildcard names hash | 311 If the name is not found there, the wildcard names hash |
298 ending with an asterisk is searched. | 312 ending with an asterisk is searched. |
299 Searching wildcard names hashes is slower than searching exact name hash | 313 Searching wildcard names hashes is slower than searching exact name hash |
300 because names are searched by domain parts. | 314 because names are searched by domain parts. |
301 Note that the special wildcard form <dirname>.nginx.org</dirname> | 315 Note that the special wildcard form “<literal>.nginx.org</literal>” |
302 is stored in a wildcard names hash and not in an exact names hash. | 316 is stored in a wildcard names hash and not in an exact names hash. |
303 Regular expressions are tested sequentially | 317 Regular expressions are tested sequentially |
304 and therefore are the slowest method and are non-scalable. | 318 and therefore are the slowest method and are non-scalable. |
305 </para> | 319 </para> |
306 | 320 |
330 </para> | 344 </para> |
331 | 345 |
332 <para> | 346 <para> |
333 If you have defined a large number of server names, | 347 If you have defined a large number of server names, |
334 or defined unusually long server names, you may need to tune | 348 or defined unusually long server names, you may need to tune |
335 the <dirname>server_names_hash_max_size</dirname> | 349 the <link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/> |
336 and <dirname>server_names_hash_bucket_size</dirname> directives | 350 and <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/> |
337 at the <i>http</i> level. | 351 directives at the <i>http</i> level. |
338 The default value of the <dirname>server_names_hash_bucket_size</dirname> | 352 The default value of the |
353 <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/> | |
339 may be equal to 32, or 64, or another value, | 354 may be equal to 32, or 64, or another value, |
340 depending on your CPU cache line size. | 355 depending on your CPU cache line size. |
341 If the default value is 32 and you define | 356 If the default value is 32 and you define |
342 “too.long.server.name.nginx.org” as a server name, | 357 “too.long.server.name.nginx.org” as a server name, |
343 then nginx will fail to start and display the error message: | 358 then nginx will fail to start and display the error message: |
362 could not build the server_names_hash, | 377 could not build the server_names_hash, |
363 you should increase either server_names_hash_max_size: 512 | 378 you should increase either server_names_hash_max_size: 512 |
364 or server_names_hash_bucket_size: 32 | 379 or server_names_hash_bucket_size: 32 |
365 </programlisting> | 380 </programlisting> |
366 | 381 |
367 You should first try to set <dirname>server_names_hash_max_size</dirname> | 382 You should first try to set |
383 <link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/> | |
368 to a number close to the number of server names. | 384 to a number close to the number of server names. |
369 Only if this does not help, | 385 Only if this does not help, |
370 or if nginx’s start time is unacceptably long, | 386 or if nginx’s start time is unacceptably long, |
371 should you try to increase <dirname>server_names_hash_bucket_size</dirname>. | 387 should you try to increase |
388 <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>. | |
372 </para> | 389 </para> |
373 | 390 |
374 <para> | 391 <para> |
375 If a server is the only server for a listen port, then nginx will not test | 392 If a server is the only server for a listen port, then nginx will not test |
376 server names at all (and will not build the hashes for the listen port). | 393 server names at all (and will not build the hashes for the listen port). |
377 However, there is one exception. | 394 However, there is one exception. |
378 If a <dirname>server_name</dirname> is a regular expression with captures, | 395 If a |
396 <link doc="ngx_http_core_module.xml" id="server_name"/> | |
397 is a regular expression with captures, | |
379 then nginx has to execute the expression to get the captures. | 398 then nginx has to execute the expression to get the captures. |
380 </para> | 399 </para> |
381 | 400 |
382 </section> | 401 </section> |
383 | 402 |