Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_core_module.xml @ 147:8057b7793bd9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Removed the "dq" element.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 25 Oct 2011 12:45:29 +0000
parents 370cf5ccd3ca
children 682163f2b298
comparison
equal deleted inserted replaced
146:356bcdeb008f 147:8057b7793bd9
143 location /i/ { 143 location /i/ {
144 alias /data/w3/images/; 144 alias /data/w3/images/;
145 } 145 }
146 </example> 146 </example>
147 the request of 147 the request of
148 <dq><code>/i/top.gif</code></dq> will be responded 148 “<code>/i/top.gif</code>” will be responded
149 with the file 149 with the file
150 <dq><pathname>/data/w3/images/top.gif</pathname></dq>. 150 <pathname>/data/w3/images/top.gif</pathname>.
151 </para> 151 </para>
152 152
153 <para> 153 <para>
154 The <argument>path</argument> value can contain variables 154 The <argument>path</argument> value can contain variables
155 except <var>$document_root</var> and <var>$realpath_root</var>. 155 except <var>$document_root</var> and <var>$realpath_root</var>.
1000 1000
1001 <para> 1001 <para>
1002 Sets a configuration based on a request URI. 1002 Sets a configuration based on a request URI.
1003 A location can either be defined by a prefix string, or by a regular expression. 1003 A location can either be defined by a prefix string, or by a regular expression.
1004 Regular expressions are specified by prepending them with the 1004 Regular expressions are specified by prepending them with the
1005 <dq><value>~*</value></dq> prefix (for case-insensitive matching), or with the 1005 “<value>~*</value>” prefix (for case-insensitive matching), or with the
1006 <dq><value>~</value></dq> prefix (for case-sensitive matching). 1006 “<value>~</value>” prefix (for case-sensitive matching).
1007 To find a location matching a given request, nginx first checks 1007 To find a location matching a given request, nginx first checks
1008 locations defined using the prefix strings (prefix locations). 1008 locations defined using the prefix strings (prefix locations).
1009 Among them, the most specific one is searched. 1009 Among them, the most specific one is searched.
1010 Then regular expressions are checked, in the order of their appearance 1010 Then regular expressions are checked, in the order of their appearance
1011 in a configuration file. 1011 in a configuration file.
1029 Regular expressions can contain captures (0.7.40) that can later 1029 Regular expressions can contain captures (0.7.40) that can later
1030 be used in other directives. 1030 be used in other directives.
1031 </para> 1031 </para>
1032 1032
1033 <para> 1033 <para>
1034 If the most specific prefix location has the <dq><value>^~</value></dq> prefix 1034 If the most specific prefix location has the “<value>^~</value>” prefix
1035 then regular expressions are not checked. 1035 then regular expressions are not checked.
1036 </para> 1036 </para>
1037 1037
1038 <para> 1038 <para>
1039 Also, using the <dq><value>=</value></dq> prefix it is possible to define 1039 Also, using the “<value>=</value>” prefix it is possible to define
1040 an exact match of URI and location. 1040 an exact match of URI and location.
1041 If an exact match is found, the search terminates. 1041 If an exact match is found, the search terminates.
1042 For example, if a <dq><code>/</code></dq> request happens frequently, 1042 For example, if a “<code>/</code>” request happens frequently,
1043 defining <dq><code>location = /</code></dq> will speed up the processing 1043 defining “<code>location = /</code>” will speed up the processing
1044 of these requests, as search terminates right after the first 1044 of these requests, as search terminates right after the first
1045 comparison. 1045 comparison.
1046 Such a location cannot obviously contain nested locations. 1046 Such a location cannot obviously contain nested locations.
1047 </para> 1047 </para>
1048 1048
1049 <para> 1049 <para>
1050 <note> 1050 <note>
1051 In versions from 0.7.1 to 0.8.41, if a request matched the prefix 1051 In versions from 0.7.1 to 0.8.41, if a request matched the prefix
1052 location without the <dq><value>=</value></dq> and <dq><value>^~</value></dq> 1052 location without the “<value>=</value>” and “<value>^~</value>”
1053 prefixes, the search also terminated and regular expressions were 1053 prefixes, the search also terminated and regular expressions were
1054 not checked. 1054 not checked.
1055 </note> 1055 </note>
1056 </para> 1056 </para>
1057 1057
1072 1072
1073 location ~* \.(gif|jpg|jpeg)$ { 1073 location ~* \.(gif|jpg|jpeg)$ {
1074 [ configuration D ] 1074 [ configuration D ]
1075 } 1075 }
1076 </example> 1076 </example>
1077 The <dq><code>/</code></dq> request will match configuration A, 1077 The “<code>/</code>” request will match configuration A,
1078 the <dq><code>/documents/document.html</code></dq> request will match 1078 the “<code>/documents/document.html</code>” request will match
1079 configuration B, 1079 configuration B,
1080 the <dq><code>/images/1.gif</code></dq> request will match configuration C, and 1080 the “<code>/images/1.gif</code>” request will match configuration C, and
1081 the <dq><code>/documents/1.jpg</code></dq> request will match configuration D. 1081 the “<code>/documents/1.jpg</code>” request will match configuration D.
1082 </para> 1082 </para>
1083 1083
1084 <para> 1084 <para>
1085 The <dq><value>@</value></dq> prefix defines a named location. 1085 The “<value>@</value>” prefix defines a named location.
1086 Such a location is not used for a regular request processing, but instead 1086 Such a location is not used for a regular request processing, but instead
1087 used for request redirection. 1087 used for request redirection.
1088 They cannot be nested, and cannot contain nested locations. 1088 They cannot be nested, and cannot contain nested locations.
1089 </para> 1089 </para>
1090 1090
1137 </para> 1137 </para>
1138 1138
1139 <para> 1139 <para>
1140 Note that compression is essential for the correct prefix string 1140 Note that compression is essential for the correct prefix string
1141 and regular expressions location matching. 1141 and regular expressions location matching.
1142 Without it, the <dq><code>//scripts/one.php</code></dq> request would not match 1142 Without it, the “<code>//scripts/one.php</code>” request would not match
1143 <example> 1143 <example>
1144 location /scripts/ { 1144 location /scripts/ {
1145 ... 1145 ...
1146 } 1146 }
1147 </example> 1147 </example>
1148 and might be processed as a static file, 1148 and might be processed as a static file,
1149 so it gets converted to <dq><code>/scripts/one.php</code></dq>. 1149 so it gets converted to “<code>/scripts/one.php</code>”.
1150 </para> 1150 </para>
1151 1151
1152 <para> 1152 <para>
1153 Turning the compression <value>off</value> can become necessary if a URI 1153 Turning the compression <value>off</value> can become necessary if a URI
1154 contains base64-encoded names, since base64 uses the “/” character internally. 1154 contains base64-encoded names, since base64 uses the “/” character internally.
1526 <example> 1526 <example>
1527 location /i/ { 1527 location /i/ {
1528 root /data/w3; 1528 root /data/w3;
1529 } 1529 }
1530 </example> 1530 </example>
1531 <dq><code>/i/top.gif</code></dq> will be responded 1531 “<code>/i/top.gif</code>” will be responded
1532 with the file 1532 with the file
1533 <dq><pathname>/data/w3/i/top.gif</pathname></dq>. 1533 <pathname>/data/w3/i/top.gif</pathname>.
1534 </para> 1534 </para>
1535 1535
1536 <para> 1536 <para>
1537 The <argument>path</argument> value can contain variables 1537 The <argument>path</argument> value can contain variables
1538 except <var>$document_root</var> and <var>$realpath_root</var>. 1538 except <var>$document_root</var> and <var>$realpath_root</var>.
1661 </example> 1661 </example>
1662 </para> 1662 </para>
1663 1663
1664 <para> 1664 <para>
1665 The first name becomes the primary server name. 1665 The first name becomes the primary server name.
1666 Server names can include an asterisk (<dq><code>*</code></dq>) 1666 Server names can include an asterisk (“<code>*</code>”)
1667 to replace the first or last part of a name: 1667 to replace the first or last part of a name:
1668 <example> 1668 <example>
1669 server { 1669 server {
1670 server_name example.com *.example.com www.example.*; 1670 server_name example.com *.example.com www.example.*;
1671 } 1671 }
1686 machine's hostname is substituted. 1686 machine's hostname is substituted.
1687 </para> 1687 </para>
1688 1688
1689 <para> 1689 <para>
1690 It is also possible to use regular expressions in server names, 1690 It is also possible to use regular expressions in server names,
1691 prepending the name with a tilde (<dq><code>~</code></dq>): 1691 prepending the name with a tilde (“<code>~</code>”):
1692 <example> 1692 <example>
1693 server { 1693 server {
1694 server_name www.example.com ~^www\d+\.example\.com$; 1694 server_name www.example.com ~^www\d+\.example\.com$;
1695 } 1695 }
1696 </example> 1696 </example>
1762 <listitem> 1762 <listitem>
1763 full names 1763 full names
1764 </listitem> 1764 </listitem>
1765 1765
1766 <listitem> 1766 <listitem>
1767 names with the prefix mask, e.g. <dq><code>*.example.com</code></dq> 1767 names with the prefix mask, e.g. “<code>*.example.com</code>”
1768 </listitem> 1768 </listitem>
1769 1769
1770 <listitem> 1770 <listitem>
1771 names with the suffix mask, e.g. <dq><code>mail.*</code></dq> 1771 names with the suffix mask, e.g. “<code>mail.*</code>”
1772 </listitem> 1772 </listitem>
1773 1773
1774 <listitem> 1774 <listitem>
1775 regular expressions 1775 regular expressions
1776 </listitem> 1776 </listitem>
1906 <para> 1906 <para>
1907 Checks the existence of files in the specified order, and uses 1907 Checks the existence of files in the specified order, and uses
1908 the first found file for request processing; the processing 1908 the first found file for request processing; the processing
1909 is performed in the current context. 1909 is performed in the current context.
1910 It is possible to check the directory existence by specifying 1910 It is possible to check the directory existence by specifying
1911 a slash at the end of a name, e.g. <dq><code>$uri/</code></dq>. 1911 a slash at the end of a name, e.g. “<code>$uri/</code>”.
1912 If none of the files were found, an internal redirect to the 1912 If none of the files were found, an internal redirect to the
1913 <argument>uri</argument> specified by the last argument is made. 1913 <argument>uri</argument> specified by the last argument is made.
1914 As of version 0.7.51, the last argument can also be a 1914 As of version 0.7.51, the last argument can also be a
1915 <argument>code</argument>: 1915 <argument>code</argument>:
1916 <example> 1916 <example>
2042 <pathname>conf/mime.types</pathname> file. 2042 <pathname>conf/mime.types</pathname> file.
2043 </para> 2043 </para>
2044 2044
2045 <para> 2045 <para>
2046 To make a particular location emit the 2046 To make a particular location emit the
2047 <dq><code>application/octet-stream</code></dq> 2047 “<code>application/octet-stream</code>”
2048 MIME type for all requests, try the following: 2048 MIME type for all requests, try the following:
2049 <example> 2049 <example>
2050 location /download/ { 2050 location /download/ {
2051 types { } 2051 types { }
2052 default_type application/octet-stream; 2052 default_type application/octet-stream;
2204 the <argument>name</argument> request header field 2204 the <argument>name</argument> request header field
2205 </tag-desc> 2205 </tag-desc>
2206 2206
2207 <tag-name><var>$is_args</var></tag-name> 2207 <tag-name><var>$is_args</var></tag-name>
2208 <tag-desc> 2208 <tag-desc>
2209 <dq><code>?</code></dq> if a request line has arguments, 2209 “<code>?</code>” if a request line has arguments,
2210 or an empty string otherwise 2210 or an empty string otherwise
2211 </tag-desc> 2211 </tag-desc>
2212 2212
2213 <tag-name><var>$limit_rate</var></tag-name> 2213 <tag-name><var>$limit_rate</var></tag-name>
2214 <tag-desc> 2214 <tag-desc>
2287 </para> 2287 </para>
2288 </tag-desc> 2288 </tag-desc>
2289 2289
2290 <tag-name><var>$request_completion</var></tag-name> 2290 <tag-name><var>$request_completion</var></tag-name>
2291 <tag-desc> 2291 <tag-desc>
2292 <dq><code>OK</code></dq> if a request has completed, 2292 “<code>OK</code>” if a request has completed,
2293 or an empty string otherwise 2293 or an empty string otherwise
2294 </tag-desc> 2294 </tag-desc>
2295 2295
2296 <tag-name><var>$request_filename</var></tag-name> 2296 <tag-name><var>$request_filename</var></tag-name>
2297 <tag-desc> 2297 <tag-desc>
2301 </tag-desc> 2301 </tag-desc>
2302 2302
2303 <tag-name><var>$request_method</var></tag-name> 2303 <tag-name><var>$request_method</var></tag-name>
2304 <tag-desc> 2304 <tag-desc>
2305 request method, usually 2305 request method, usually
2306 <dq><code>GET</code></dq> or <dq><code>POST</code></dq> 2306 “<code>GET</code>” or “<code>POST</code>”
2307 </tag-desc> 2307 </tag-desc>
2308 2308
2309 <tag-name><var>$request_uri</var></tag-name> 2309 <tag-name><var>$request_uri</var></tag-name>
2310 <tag-desc> 2310 <tag-desc>
2311 full original request URI (with arguments) 2311 full original request URI (with arguments)
2312 </tag-desc> 2312 </tag-desc>
2313 2313
2314 <tag-name><var>$scheme</var></tag-name> 2314 <tag-name><var>$scheme</var></tag-name>
2315 <tag-desc> 2315 <tag-desc>
2316 request scheme, <dq><code>http</code></dq> or <dq><code>https</code></dq> 2316 request scheme, “<code>http</code>” or “<code>https</code>”
2317 </tag-desc> 2317 </tag-desc>
2318 2318
2319 <tag-name><var>$sent_http_</var><argument>name</argument></tag-name> 2319 <tag-name><var>$sent_http_</var><argument>name</argument></tag-name>
2320 <tag-desc> 2320 <tag-desc>
2321 the <argument>name</argument> response header field 2321 the <argument>name</argument> response header field
2342 </tag-desc> 2342 </tag-desc>
2343 2343
2344 <tag-name><var>$server_protocol</var></tag-name> 2344 <tag-name><var>$server_protocol</var></tag-name>
2345 <tag-desc> 2345 <tag-desc>
2346 request protocol, usually 2346 request protocol, usually
2347 <dq><code>HTTP/1.0</code></dq> 2347 “<code>HTTP/1.0</code>”
2348 or 2348 or
2349 <dq><code>HTTP/1.1</code></dq> 2349 “<code>HTTP/1.1</code>”
2350 </tag-desc> 2350 </tag-desc>
2351 2351
2352 <tag-name><var>$uri</var></tag-name> 2352 <tag-name><var>$uri</var></tag-name>
2353 <tag-desc> 2353 <tag-desc>
2354 current URI in request 2354 current URI in request