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

annotate xml/en/docs/http/server_names.xml @ 580:be54c443235a

Added copyright markers to documentation sources.

author	Ruslan Ermilov <ru@nginx.com>
date	Tue, 10 Jul 2012 12:59:42 +0000
parents	9913f1d51c07
children	5bb7716cae7e

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

Mercurial > hg > nginx-site

annotate xml/en/docs/http/server_names.xml @ 580:be54c443235a