Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_core_module.xml @ 57:12f1de4539b4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial English translation of ngx_http_core_module.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 03 Oct 2011 16:23:44 +0000
parents
children f122a777a6de
comparison
equal deleted inserted replaced
56:b706454b2ab8 57:12f1de4539b4
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="HTTP core module"
6 link="/en/docs/http/ngx_http_core_module.html"
7 lang="en">
8
9 <section id="directives" name="Directives">
10
11 <directive name="aio" appeared-in="0.8.11">
12 <syntax>aio
13 <value>on</value> |
14 <value>off</value> |
15 <value>sendfile</value>
16 </syntax>
17 <default>aio off</default>
18 <context>http</context>
19 <context>server</context>
20 <context>location</context>
21
22 <para>
23 Enables or disables the use of asynchronous file I/O (AIO)
24 on FreeBSD and Linux.
25 </para>
26
27 <para>
28 On FreeBSD, AIO is usable starting from FreeBSD&nbsp;4.3.
29 AIO can either be linked statically into a kernel:
30 <example>
31 options VFS_AIO
32 </example>
33 or loaded dynamically as a kernel loadable module:
34 <example>
35 kldload aio
36 </example>
37 </para>
38
39 <para>
40 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically
41 when booting the kernel, will cause the entire networking subsystem
42 to use the Giant lock that can impact overall performance negatively.
43 This limitation has been removed in FreeBSD&nbsp;6.4-STABLE in 2009, and in
44 FreeBSD&nbsp;7.
45 However, starting from FreeBSD&nbsp;5.3 it is possible to enable AIO
46 without the penalty of running the networking subsystem under a
47 Giant lock&mdash;for this to work, the AIO module needs to be loaded
48 after the kernel has booted.
49 In this case, the following message will appear in
50 <pathname>/var/log/messages</pathname>
51 <example>
52 WARNING: Network stack Giant-free, but aio requires Giant.
53 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
54 </example>
55 and can safely be ignored.
56 <note>
57 The requirement to use the Giant lock with AIO is related to the
58 fact that FreeBSD supports asynchronous calls
59 <c-func>aio_read</c-func>
60 and
61 <c-func>aio_write</c-func>
62 when working with sockets.
63 However, since nginx only uses AIO for disk I/O, no problems should arise.
64 </note>
65 </para>
66
67 <para>
68 For AIO to work,
69 <link id="sendfile">sendfile</link>
70 needs to be disabled:
71 <example>
72 location /video/ {
73 sendfile off;
74 aio on;
75 output_buffers 1 64k;
76 }
77 </example>
78 </para>
79
80 <para>
81 In addition, starting from FreeBSD&nbsp;5.2.1 and nginx&nbsp;0.8.12, AIO can
82 also be used to pre-load data for <c-func>sendfile</c-func>:
83 <example>
84 location /video/ {
85 sendfile on;
86 tcp_nopush on;
87 aio sendfile;
88 }
89 </example>
90 In this configuration, <c-func>sendfile</c-func> is called with
91 the <c-def>SF_NODISKIO</c-def> flag which causes it not to
92 block on disk I/O and instead report back when the data are not in
93 memory; nginx then initiates an asynchronous data load by reading
94 one byte. The FreeBSD kernel then loads the first 128K bytes
95 of a file into memory, however next reads will only load data
96 in 16K chunks. This can be tuned using the
97 <link id="read_ahead">read_ahead</link>
98 directive.
99 </para>
100
101 <para>
102 On Linux, AIO is usable starting from kernel version 2.6.22;
103 plus, it is also necessary to enable
104 <link id="directio">directio</link>,
105 otherwise reading will be blocking:
106 <example>
107 location /video/ {
108 aio on;
109 directio 512;
110 output_buffers 1 128k;
111 }
112 </example>
113 </para>
114
115 <para>
116 On Linux,
117 <link id="directio">directio</link>
118 can only be used for reading blocks that are aligned on 512-byte
119 boundaries (or 4K for XFS).
120 Reading of unaligned file's end is still made in blocking mode.
121 The same holds true for byte range requests, and for FLV requests
122 not from the beginning of a file: reading of unaligned data at the
123 beginning and end of a file will be blocking.
124 There is no need to turn off
125 <link id="sendfile">sendfile</link>
126 explicitly as it is turned off automatically when
127 <link id="directio">directio</link>
128 is used.
129 </para>
130
131 </directive>
132
133
134 <directive name="alias">
135 <syntax>alias <argument>path</argument></syntax>
136 <default/>
137 <context>location</context>
138
139 <para>
140 Defines a replacement for the specified location.
141 For example, with the following configuration
142 <example>
143 location /i/ {
144 alias /data/w3/images/;
145 }
146 </example>
147 the request of
148 <dq><code>/i/top.gif</code></dq> will be responded
149 with the file
150 <dq><pathname>/data/w3/images/top.gif</pathname></dq>.
151 </para>
152
153 <para>
154 The <argument>path</argument> value can contain variables.
155 </para>
156
157 <para>
158 If <code>alias</code> is used inside a location defined
159 with a regular expression then such regular expression should
160 contain captures and <code>alias</code> should refer to
161 these captures (0.7.40), for example:
162 <example>
163 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
164 alias /data/w3/images/$1;
165 }
166 </example>
167 </para>
168
169 <para>
170 When location matches the last part of the directive's value:
171 <example>
172 location /images/ {
173 alias /data/w3/images/;
174 }
175 </example>
176 it is better to use the
177 <link id="root">root</link>
178 directive instead:
179 <example>
180 location /images/ {
181 root /data/w3;
182 }
183 </example>
184 </para>
185
186 </directive>
187
188
189 <directive name="client_body_in_file_only">
190 <syntax>client_body_in_file_only
191 <value>on</value> |
192 <value>clean</value> |
193 <value>off</value>
194 </syntax>
195 <default>client_body_in_file_only off</default>
196 <context>http</context>
197 <context>server</context>
198 <context>location</context>
199
200 <para>
201 Determines whether nginx should save the entire client request body
202 into a file.
203 This directive can be used during debugging, or when using the
204 <var>$request_body_file</var>
205 variable, or the
206 <link doc="ngx_http_perl_module.xml" id="methods">$r->request_body_file</link>
207 method of the module
208 <link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>.
209 </para>
210
211 <para>
212 When set to the value <value>on</value>, temporary files are not
213 removed after request processing.
214 </para>
215
216 <para>
217 The value <value>clean</value> will cause the temporary files
218 left after request processing to be removed.
219 </para>
220
221 </directive>
222
223
224 <directive name="client_body_in_single_buffer">
225 <syntax>client_body_in_single_buffer <value>on</value> | <value>off</value>
226 </syntax>
227 <default>client_body_in_single_buffer off</default>
228 <context>http</context>
229 <context>server</context>
230 <context>location</context>
231
232 <para>
233 Determines whether nginx should save the entire client request body
234 in a single buffer.
235 The directive is recommended when using the
236 <var>$request_body</var>
237 variable, to save the number of copy operations involved.
238 </para>
239
240 </directive>
241
242
243 <directive name="client_body_buffer_size">
244
245 <syntax>client_body_buffer_size <argument>size</argument></syntax>
246 <default>client_body_buffer_size 8k/16k</default>
247 <context>http</context>
248 <context>server</context>
249 <context>location</context>
250
251 <para>
252 Sets buffer size for reading client request body.
253 In case request body is larger than the buffer,
254 the whole body or only its part is written to a temporary file.
255 <!-- ссылку на соотв. директивы про временные файлы? -->
256 By default, buffer size is equal to two memory pages.
257 This is 8K on x86, other 32-bit platforms, and x86-64.
258 It is usually 16K on other 64-bit platforms.
259 </para>
260
261 </directive>
262
263
264 <directive name="client_body_temp_path">
265 <syntax>client_body_temp_path
266 <argument>path</argument>
267 [<argument>level1</argument>
268 [<argument>level2</argument>
269 [<argument>level3</argument>]]]
270 </syntax>
271 <default>client_body_temp_path client_body_temp</default>
272 <context>http</context>
273 <context>server</context>
274 <context>location</context>
275
276 <para>
277 Defines a directory for storing temporary files holding client request bodies.
278 Up to three-level subdirectory hierarchy can be used underneath the specified
279 directory.
280 For example, in the following configuration
281 <example>
282 client_body_temp_path /spool/nginx/client_temp 1 2;
283 </example>
284 a temporary file might look like this:
285 <example>
286 /spool/nginx/client_temp/7/45/00000123457
287 </example>
288 </para>
289
290 </directive>
291
292
293 <directive name="client_body_timeout">
294 <syntax>client_body_timeout <argument>time</argument></syntax>
295 <default>client_body_timeout 60</default>
296 <context>http</context>
297 <context>server</context>
298 <context>location</context>
299
300 <para>
301 Defines a timeout for reading client request body.
302 A timeout is only set between two successive read operations,
303 not for the transmission of the whole request body.
304 If a client does not transmit anything within this time,
305 the client error
306 <http-status code="408" text="Request Time-out"/>
307 is returned.
308 </para>
309
310 </directive>
311
312
313 <directive name="client_header_buffer_size">
314 <syntax>client_header_buffer_size <argument>size</argument></syntax>
315 <default>client_header_buffer_size 1k</default>
316 <context>http</context>
317 <context>server</context>
318
319 <para>
320 Sets buffer size for reading client request header.
321 For most requests, a buffer of 1K bytes is enough.
322 However, if a request includes long cookies, or comes from a WAP client,
323 it may not fit into 1K.
324 If a request line, or a request header field do not fit entirely into
325 this buffer then larger buffers are allocated, configured by the
326 <link id="large_client_header_buffers">large_client_header_buffers</link>
327 directive.
328 </para>
329
330 </directive>
331
332
333 <directive name="client_header_timeout">
334 <syntax>client_header_timeout <argument>time</argument></syntax>
335 <default>client_header_timeout 60</default>
336 <context>http</context>
337 <context>server</context>
338
339 <para>
340 Defines a timeout for reading client request header.
341 If a client does not transmit the entire header within this time,
342 the client error
343 <http-status code="408" text="Request Time-out"/>
344 is returned.
345 </para>
346
347 </directive>
348
349
350 <directive name="client_max_body_size">
351 <syntax>client_max_body_size <argument>size</argument></syntax>
352 <default>client_max_body_size 1m</default>
353 <context>http</context>
354 <context>server</context>
355 <context>location</context>
356
357 <para>
358 Sets the maximum allowed size of the client request body,
359 specified in the
360 <header>Content-Length</header>
361 request header field.
362 If it exceeds the configured value, the client error
363 <http-status code="413" text="Request Entity Too Large"/>
364 is returned.
365 Please be aware that
366 <link doc="/web/upload.xml">browsers cannot correctly display
367 this error</link>.
368 </para>
369
370 </directive>
371
372
373 <directive name="default_type">
374 <syntax>default_type <argument>mime-type</argument></syntax>
375 <default>default_type text/plain</default>
376 <context>http</context>
377 <context>server</context>
378 <context>location</context>
379
380 <para>
381 Defines a default MIME-type of a response.
382 </para>
383
384 </directive>
385
386
387 <directive name="directio" appeared-in="0.7.7">
388 <syntax>directio <argument>size</argument> | <value>off</value></syntax>
389 <default>directio off</default>
390 <context>http</context>
391 <context>server</context>
392 <context>location</context>
393
394 <para>
395 Enables the use of
396 the <c-def>O_DIRECT</c-def> flag (FreeBSD, Linux),
397 the <c-def>F_NOCACHE</c-def> flag (Mac OS X),
398 or the <c-func>directio</c-func> function (Solaris),
399 when reading files that are larger than the specified <argument>size</argument>.
400 It automatically disables (0.7.15) the use of
401 <link id="sendfile">sendfile</link>
402 for a given request.
403 It could be useful for serving large files:
404 <example>
405 directio 4m;
406 </example>
407 or when using <link id="aio">aio</link> on Linux.
408 </para>
409
410 </directive>
411
412
413 <directive name="directio_alignment" appeared-in="0.8.11">
414 <syntax>directio_alignment <argument>size</argument></syntax>
415 <default>directio_alignment 512</default>
416 <context>http</context>
417 <context>server</context>
418 <context>location</context>
419
420 <para>
421 Sets an alignment for
422 <link id="directio">directio</link>.
423 In most cases, a 512-byte alignment is enough, however, when
424 using XFS under Linux, it needs to be increased to 4K.
425 </para>
426
427 </directive>
428
429
430 <directive name="error_page">
431 <syntax>error_page
432 <argument>code</argument> ...
433 [<value>=</value>[<argument>response</argument>]]
434 <argument>uri</argument>
435 </syntax>
436 <default/>
437 <context>http</context>
438 <context>server</context>
439 <context>location</context>
440 <context>if in location</context>
441
442 <para>
443 Defines the URI that will be shown for the specified errors.
444 These directives are inherited from the previous level if and
445 only if there are no
446 <code>error_page</code>
447 directives on
448 the current level.
449 A URI value can contain variables.
450 </para>
451
452 <para>
453 Example:
454 <example>
455 error_page 404 /404.html;
456 error_page 502 503 504 /50x.html;
457 error_page 403 http://example.com/forbidden.html;
458 </example>
459 </para>
460
461 <para>
462 Furthermore, it is possible to change the response code to another, for example:
463 <example>
464 error_page 404 =200 /empty.gif;
465 </example>
466 </para>
467
468 <para>
469 If an error response is processed by a proxied server, or a FastCGI server,
470 and the server may return different response codes (e.g., 200, 302, 401
471 or 404), it is possible to respond with a returned code:
472 <example>
473 error_page 404 = /404.php;
474 </example>
475 </para>
476
477 <para>
478 If there is no need to change URI during redirection it is possible to redirect
479 error processing into a named location:
480 <example>
481 location / {
482 error_page 404 = @fallback;
483 }
484
485 location @fallback {
486 proxy_pass http://backend;
487 }
488 </example>
489 </para>
490
491 </directive>
492
493
494 <directive name="if_modified_since" appeared-in="0.7.24">
495 <syntax>if_modified_since
496 <value>off</value> |
497 <value>exact</value> |
498 <value>before</value>
499 </syntax>
500 <default>if_modified_since exact</default>
501 <context>http</context>
502 <context>server</context>
503 <context>location</context>
504
505 <para>
506 Specifies how to compare modification time of a response
507 with the time in the
508 <header>If-Modified-Since</header>
509 request header:
510
511 <list type="tag">
512
513 <tag-name><value>off</value></tag-name>
514 <tag-desc>
515 the
516 <header>If-Modified-Since</header> request header is ignored (0.7.34);
517 </tag-desc>
518
519 <tag-name><value>exact</value></tag-name>
520 <tag-desc>
521 exact match;
522 </tag-desc>
523
524 <tag-name><value>before</value></tag-name>
525 <tag-desc>
526 modification time of a response is
527 less than or equal to the time in the <header>If-Modified-Since</header>
528 request header.
529 </tag-desc>
530
531 </list>
532 </para>
533
534 </directive>
535
536
537 <directive name="internal">
538 <syntax>internal</syntax>
539 <default/>
540 <context>location</context>
541
542 <para>
543 Specifies that a given location can only be used for internal requests.
544 For external requests, the client error
545 <http-status code="404" text="Not Found"/>
546 is returned.
547 Internal requests are the following:
548
549 <list type="bullet">
550
551 <listitem>
552 requests redirected by the <link id="error_page">error_page</link> directive;
553 </listitem>
554
555 <listitem>
556 subrequests formed by the
557 <command>include virtual</command>
558 command of the module
559 <link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>;
560 </listitem>
561
562 <listitem>
563 requests changed by the
564 <link doc="ngx_http_rewrite_module.xml" id="rewrite">rewrite</link>
565 directive of the module
566 <link doc="ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>.
567 </listitem>
568
569 </list>
570 </para>
571
572 <para>
573 Example:
574 <example>
575 error_page 404 /404.html;
576
577 location /404.html {
578 internal;
579 }
580 </example>
581 </para>
582
583 </directive>
584
585
586 <directive name="keepalive_requests" appeared-in="0.8.0">
587 <syntax>keepalive_requests <argument>number</argument></syntax>
588 <default>keepalive_requests 100</default>
589 <context>http</context>
590 <context>server</context>
591 <context>location</context>
592
593 <para>
594 Sets the maximum number of requests that can be
595 made through one keep-alive connection.
596 </para>
597
598 </directive>
599
600
601 <directive name="keepalive_timeout">
602 <syntax>keepalive_timeout
603 <argument>time</argument>
604 [<argument>time</argument>]
605 </syntax>
606 <default>keepalive_timeout 75</default>
607 <context>http</context>
608 <context>server</context>
609 <context>location</context>
610
611 <para>
612 The first argument sets a timeout during which a keep-alive
613 client connection will stay open on the server side.
614 The optional second argument sets a value in the
615 <dq><header>Keep-Alive: timeout=<argument>time</argument></header></dq>
616 response header.
617 Two arguments may differ.
618 </para>
619
620 <para>
621 The
622 <dq><header>Keep-Alive: timeout=</header></dq>
623 is understood by Mozilla and Konqueror.
624 MSIE will close keep-alive connection in about 60 seconds.
625 </para>
626
627 </directive>
628
629
630 <directive name="large_client_header_buffers">
631 <syntax>large_client_header_buffers <argument>number size</argument></syntax>
632 <default>large_client_header_buffers 4 4k/8k</default>
633 <context>http</context>
634 <context>server</context>
635
636 <para>
637 Sets the maximum <argument>number</argument> and <argument>size</argument> of
638 buffers used when reading large client request headers.
639 A request line cannot exceed the size of one buffer, or the client error
640 <http-status code="414" text="Request-URI Too Large"/>
641 is returned.
642 A request header field cannot exceed the size of one buffer as well, or the
643 client error
644 <http-status code="400" text="Bad Request"/>
645 is returned.
646 Buffers are allocated only on demand.
647 By default, the buffer size is equal to one memory page size.
648 It is either 4K or 8K, platform dependent.
649 If after the end of request processing a connection is transitioned
650 into the keep-alive state, these buffers are freed.
651 </para>
652
653 </directive>
654
655
656 <directive name="limit_except">
657 <syntax>limit_except <argument>method</argument> ... { ... }</syntax>
658 <default/>
659 <context>location</context>
660
661 <para>
662 Limits allowed HTTP methods inside a location.
663 The GET method also implies the HEAD method.
664 Access to other methods can be limited using the
665 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
666 and
667 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>
668 modules directives:
669 <example>
670 limit_except GET {
671 allow 192.168.1.0/32;
672 deny all;
673 }
674 </example>
675 Please note that this will limit access to all methods
676 <emphasis>except</emphasis> GET and HEAD.
677 </para>
678
679 </directive>
680
681
682 <directive name="limit_rate">
683 <syntax>limit_rate <argument>rate</argument></syntax>
684 <default/>
685 <context>http</context>
686 <context>server</context>
687 <context>location</context>
688 <context>if in location</context>
689
690 <para>
691 Rate limits the transmission of a response to a client.
692 The <argument>rate</argument> is specified in bytes per second.
693 <!--
694 The smaller the rate, the more accurate will be the limitation.
695 -->
696 The limit is per connection, so if a single client opens 2 connections,
697 an overall rate will be 2x more than specified.
698 </para>
699
700 <para>
701 This directive is not applicable if one wants to rate limit
702 a group of clients on the
703 <link id="server">server</link>
704 level.
705 If that is the case, the desired limit can be specified in the
706 <var>$limit_rate</var>
707 variable:
708 <example>
709 server {
710
711 if ($slow) {
712 set $limit_rate 4k;
713 }
714
715 ...
716 }
717 </example>
718 </para>
719
720 </directive>
721
722
723 <directive name="limit_rate_after" appeared-in="0.8.0">
724 <syntax>limit_rate_after <argument>size</argument></syntax>
725 <default/>
726 <context>http</context>
727 <context>server</context>
728 <context>location</context>
729 <context>if in location</context>
730
731 <para>
732 Sets the initial amount after which the further transmission
733 of a response to a client will be rate limited.
734 </para>
735
736 <para>
737 Example:
738 <example>
739 location /flv/ {
740 flv;
741 limit_rate_after 500k;
742 limit_rate 50k;
743 }
744 </example>
745 </para>
746
747 </directive>
748
749
750 <directive name="listen">
751 <syntax>listen
752 <argument>address</argument>[:<argument>port</argument>]
753 [<parameter>default</parameter> | <parameter>default_server</parameter>
754 [<parameter>backlog</parameter>=<argument>number</argument>]
755 [<parameter>rcvbuf</parameter>=<argument>size</argument>]
756 [<parameter>sndbuf</parameter>=<argument>size</argument>]
757 [<parameter>accept_filter</parameter>=<argument>filter</argument>]
758 [<parameter>deferred</parameter>]
759 [<parameter>bind</parameter>]
760 [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>]
761 [<parameter>ssl</parameter>]]
762 </syntax>
763 <syntax>listen
764 <argument>port</argument>
765 [<parameter>default</parameter> | <parameter>default_server</parameter>
766 [<parameter>backlog</parameter>=<argument>number</argument>]
767 [<parameter>rcvbuf</parameter>=<argument>size</argument>]
768 [<parameter>sndbuf</parameter>=<argument>size</argument>]
769 [<parameter>accept_filter</parameter>=<argument>filter</argument>]
770 [<parameter>deferred</parameter>]
771 [<parameter>bind</parameter>]
772 [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>]
773 [<parameter>ssl</parameter>]]
774 </syntax>
775 <default>listen *:80 | *:8000</default>
776 <context>server</context>
777
778 <para>
779 Sets an <argument>address</argument> and a <argument>port</argument>, on which
780 the server will accept requests.
781 Only one of <argument>address</argument> or <argument>port</argument> can be
782 specified.
783 An <argument>address</argument> may also be a hostname, for example:
784 <example>
785 listen 127.0.0.1:8000;
786 listen 127.0.0.1;
787 listen 8000;
788 listen *:8000;
789 listen localhost:8000;
790 </example>
791 IPv6 addresses (0.7.36) are specified in square brackets:
792 <example>
793 listen [::]:8000;
794 listen [fe80::1];
795 </example>
796 </para>
797
798 <para>
799 If only <argument>address</argument> is given, the port 80 is used.
800 </para>
801
802 <para>
803 If directive is not present then either the <code>*:80</code> is used
804 if nginx runs with superuser privileges, or <code>*:8000</code> otherwise.
805 </para>
806
807 <para>
808 The <parameter>default</parameter> parameter, if present,
809 will cause the server to become the default server for the specified
810 <argument>address</argument>:<argument>port</argument> pair.
811 If none of the directives have the <parameter>default</parameter>
812 parameter then the first server with the
813 <argument>address</argument>:<argument>port</argument> pair will be
814 the default server for this pair.
815 Starting from version 0.8.21 it is possible to use the
816 <parameter>default_server</parameter>
817 parameter.
818 </para>
819
820 <para>
821 A <code>listen</code> directive which has the <parameter>default</parameter>
822 parameter can have several additional parameters specific to system calls
823 <c-func>listen</c-func> and <c-func>bind</c-func>.
824 Starting from version 0.8.21, these parameters can be specified in any
825 <code>listen</code> directive, but only once for the given
826 <argument>address</argument>:<argument>port</argument> pair.
827 <list type="tag">
828
829 <tag-name>
830 <parameter>backlog</parameter>=<argument>number</argument>
831 </tag-name>
832 <tag-desc>
833 sets the <parameter>backlog</parameter> parameter in the
834 <c-func>listen</c-func> call.
835 By default, <parameter>backlog</parameter> equals -1 on FreeBSD
836 and 511 on other platforms.
837 </tag-desc>
838
839 <tag-name>
840 <parameter>rcvbuf</parameter>=<argument>size</argument>
841 </tag-name>
842 <tag-desc>
843 sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket.
844 </tag-desc>
845
846 <tag-name>
847 <parameter>sndbuf</parameter>=<argument>size</argument>
848 </tag-name>
849 <tag-desc>
850 sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket.
851 </tag-desc>
852
853 <tag-name>
854 <parameter>accept_filter</parameter>=<argument>filter</argument>
855 </tag-name>
856 <tag-desc>
857 sets the name of the accept filter.
858 This works only on FreeBSD, acceptable values are <value>dataready</value>
859 and <value>httpready</value>.
860 On receipt of the <c-def>SIGHUP</c-def> signal, an accept filter can only be
861 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE
862 and 4.11-STABLE.
863 </tag-desc>
864
865 <tag-name>
866 <parameter>deferred</parameter>
867 </tag-name>
868 <tag-desc>
869 instructs to use a deferred <c-func>accept</c-func> on Linux
870 using the <c-def>TCP_DEFER_ACCEPT</c-def> option.
871 </tag-desc>
872
873 <tag-name>
874 <parameter>bind</parameter>
875 </tag-name>
876 <tag-desc>
877 specifies to make a separate <c-func>bind</c-func> call for a given
878 <argument>address</argument>:<argument>port</argument> pair.
879 This is because nginx will only <c-func>bind</c-func> to
880 <code>*</code>:<argument>port</argument>
881 if there are several <code>listen</code> directives with
882 the same port but different addresses, and one of the
883 <code>listen</code> directives listens on all addresses
884 for the given port (<code>*</code>:<argument>port</argument>).
885 It should be noted that in this case a <c-func>getsockname</c-func>
886 system call will be made to determine an address that accepted a
887 connection.
888 If parameters <parameter>backlog</parameter>, <parameter>rcvbuf</parameter>,
889 <parameter>sndbuf</parameter>, <parameter>accept_filter</parameter>, or
890 <parameter>deferred</parameter> are used then for a given
891 <argument>address</argument>:<argument>port</argument> pair
892 a separate <c-func>bind</c-func> call will always be made.
893 </tag-desc>
894
895 <tag-name>
896 <parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>
897 </tag-name>
898 <tag-desc>
899 this parameter (0.7.42) sets the value of the <c-def>IPV6_V6ONLY</c-def>
900 parameter for the listening socket.
901 This parameter can only be set once on start.
902 </tag-desc>
903
904 <tag-name>
905 <parameter>ssl</parameter>
906 </tag-name>
907 <tag-desc>
908 this parameter (0.7.14) does not relate to system calls
909 <c-func>listen</c-func> and <c-func>bind</c-func>, but allows to
910 specify that all connections accepted on this port should work in
911 the SSL mode.
912 This allows for a more compact configuration for the server operating
913 in both HTTP and HTTPS modes simultaneously.
914 <example>
915 listen 80;
916 listen 443 default ssl;
917 </example>
918 </tag-desc>
919
920 </list>
921 </para>
922
923 <para>
924 Example:
925 <example>
926 listen 127.0.0.1 default accept_filter=dataready backlog=1024;
927 </example>
928 </para>
929
930 </directive>
931
932
933 <directive name="location">
934 <syntax>location [
935 <value>=</value> |
936 <value>~</value> |
937 <value>~*</value> |
938 <value>^~</value> |
939 <value>@</value>
940 ] <argument>uri</argument>
941 { ... }</syntax>
942 <default/>
943 <context>server</context>
944 <!--
945 <context>location</context>
946 -->
947
948 <para>
949 Sets a configuration based on a request URI.
950 A location can either be defined by a prefix string, or by a regular expression.
951 Regular expressions are specified by prepending them with the
952 <dq><value>~*</value></dq> prefix (for case-insensitive matching), or with the
953 <dq><value>~</value></dq> prefix (for case-sensitive matching).
954 To find a location matching a given request, nginx first checks
955 locations defined using the prefix strings (prefix locations).
956 Amongst them, the most specific one is searched.
957 Then regular expressions are checked, in the order of their appearance
958 in a configuration file.
959 A search terminates on the first match, and its corresponding
960 configuration is used.
961 If no match with a regular expression location is found then a
962 configuration of the most specific prefix location is used.
963 </para>
964
965 <para>
966 For case-insensitive operating systems such as Mac OS X and Cygwin,
967 the string matching ignores a case (0.7.7).
968 However, comparison is limited to one-byte locales.
969 </para>
970
971 <para>
972 Regular expressions can contain captures (0.7.40) that can later
973 be used in other directives.
974 </para>
975
976 <para>
977 If the most specific prefix location has the <dq><value>^~</value></dq> prefix
978 then regular expressions are not checked.
979 </para>
980
981 <para>
982 Also, using the <dq><value>=</value></dq> prefix it is possible to define
983 an exact match of URI and location.
984 If an exact match is found, the search terminates.
985 For example, if a <dq><code>/</code></dq> request happens frequently,
986 defining <dq><code>location = /</code></dq> will speed up the processing
987 of these requests, as search terminates right after the first
988 comparison.
989 </para>
990
991 <para>
992 In versions from 0.7.1 to 0.8.41, if a request matched the prefix
993 location without the <dq><value>=</value></dq> and <dq><value>^~</value></dq>
994 prefixes, the search also terminated and regular expressions were
995 not checked.
996 </para>
997
998 <para>
999 Let's illustrate the above by example:
1000 <example>
1001 location = / {
1002 [ configuration A ]
1003 }
1004
1005 location / {
1006 [ configuration B ]
1007 }
1008
1009 location ^~ /images/ {
1010 [ configuration C ]
1011 }
1012
1013 location ~* \.(gif|jpg|jpeg)$ {
1014 [ configuration D ]
1015 }
1016 </example>
1017 The <dq><code>/</code></dq> request will match configuration A,
1018 the <dq><code>/documents/document.html</code></dq> request will match
1019 configuration B,
1020 the <dq><code>/images/1.gif</code></dq> request will match configuration C, and
1021 the <dq><code>/documents/1.jpg</code></dq> request will match configuration D.
1022 </para>
1023
1024 <para>
1025 The <dq><value>@</value></dq> prefix defines a named location.
1026 Such a location is not used for a regular request processing, but instead
1027 used for request redirection.
1028 </para>
1029
1030 <!--
1031 <migration from="Apache" directive="Location" />
1032 -->
1033
1034 </directive>
1035
1036
1037 <directive name="log_not_found">
1038 <syntax>log_not_found <value>on</value> | <value>off</value></syntax>
1039 <default>log_not_found on</default>
1040 <context>http</context>
1041 <context>server</context>
1042 <context>location</context>
1043
1044 <para>
1045 Enables or disables logging of errors about not found files into the
1046 <link doc="../ngx_core_module.xml" id="error_log">error_log</link>.
1047 </para>
1048
1049 </directive>
1050
1051
1052 <directive name="log_subrequest">
1053 <syntax>log_subrequest <value>on</value> | <value>off</value></syntax>
1054 <default>log_subrequest off</default>
1055 <context>http</context>
1056 <context>server</context>
1057 <context>location</context>
1058
1059 <para>
1060 Enables or disables logging of subrequests into the
1061 <link doc="ngx_http_log_module.xml" id="access_log">access_log</link>.
1062 </para>
1063
1064 </directive>
1065
1066
1067 <directive name="merge_slashes">
1068 <syntax>merge_slashes <value>on</value> | <value>off</value></syntax>
1069 <default>merge_slashes on</default>
1070 <context>http</context>
1071 <context>server</context>
1072
1073 <para>
1074 Enables or disables compression of two or more adjacent slashes
1075 in a URI into a single slash.
1076 </para>
1077
1078 <para>
1079 Note that compression is essential for the correct prefix string
1080 and regular expressions location matching.
1081 Without it, the <dq><code>//scripts/one.php</code></dq> request would not match
1082 <example>
1083 location /scripts/ {
1084 ...
1085 }
1086 </example>
1087 and might be processed as a static file,
1088 so it gets converted to <dq><code>/scripts/one.php</code></dq>.
1089 </para>
1090
1091 <para>
1092 Turning the compression <value>off</value> can become necessary if a URI
1093 contains base64-encoded names, since base64 uses the "/" character internally.
1094 However, for security considerations, it is better to avoid turning off
1095 the compression.
1096 </para>
1097
1098 <para>
1099 If a directive is specified on the
1100 <link id="server">server</link>
1101 level, which is also a default server, its value will cover
1102 all virtual servers listening on the same address and port.
1103 </para>
1104
1105 </directive>
1106
1107
1108 <directive name="msie_padding">
1109 <syntax>msie_padding <value>on</value> | <value>off</value></syntax>
1110 <default>msie_padding on</default>
1111 <context>http</context>
1112 <context>server</context>
1113 <context>location</context>
1114
1115 <para>
1116 Enables or disables adding of comments to responses with status
1117 greater than 400 for MSIE clients, to pad the response size to 512 bytes.
1118 </para>
1119
1120 </directive>
1121
1122
1123 <directive name="msie_refresh">
1124 <syntax>msie_refresh <value>on</value> | <value>off</value></syntax>
1125 <default>msie_refresh off</default>
1126 <context>http</context>
1127 <context>server</context>
1128 <context>location</context>
1129
1130 <para>
1131 Enables or disables issuing refreshes instead of redirects, for MSIE clients.
1132 </para>
1133
1134 </directive>
1135
1136
1137 <directive name="open_file_cache">
1138 <syntax>open_file_cache
1139 <parameter>max</parameter>=<argument>N</argument>
1140 [<parameter>inactive</parameter>=<argument>time</argument>] |
1141 <value>off</value>
1142 </syntax>
1143 <default>open_file_cache off</default>
1144 <context>http</context>
1145 <context>server</context>
1146 <context>location</context>
1147
1148 <para>
1149 Configures a cache that can store:
1150 <list type="bullet">
1151
1152 <listitem>
1153 open file descriptors, their sizes and modification times;
1154 </listitem>
1155
1156 <listitem>
1157 directory lookups;
1158 </listitem>
1159
1160 <listitem>
1161 file lookup errors, such as "file not found", "no read permission",
1162 and so on.
1163 Caching of errors should be enabled separately by the
1164 <link id="open_file_cache_errors">open_file_cache_errors</link>
1165 directive.
1166 </listitem>
1167
1168 </list>
1169 </para>
1170
1171 <para>
1172 The directive has the following parameters:
1173 <list type="tag">
1174
1175 <tag-name>
1176 <parameter>max</parameter>
1177 </tag-name>
1178 <tag-desc>
1179 sets the maximum number of elements in the cache;
1180 on cache overflow the least recently used (LRU) elements get removed;
1181 </tag-desc>
1182
1183 <tag-name>
1184 <parameter>inactive</parameter>
1185 </tag-name>
1186 <tag-desc>
1187 defines a time, after which the element gets removed from the cache
1188 if there were no accesses to it during this time;
1189 by default, it is 60 seconds;
1190 </tag-desc>
1191
1192 <tag-name>
1193 <value>off</value>
1194 </tag-name>
1195 <tag-desc>
1196 disables the cache.
1197 </tag-desc>
1198
1199 </list>
1200 </para>
1201
1202 <para>
1203 Example:
1204 <example>
1205 open_file_cache max=1000 inactive=20s;
1206 open_file_cache_valid 30s;
1207 open_file_cache_min_uses 2;
1208 open_file_cache_errors on;
1209 <!--
1210 open_file_cache_events on;
1211 -->
1212 </example>
1213 </para>
1214
1215 </directive>
1216
1217
1218 <directive name="open_file_cache_errors">
1219 <syntax>open_file_cache_errors <value>on</value> | <value>off</value></syntax>
1220 <default>open_file_cache_errors off</default>
1221 <context>http</context>
1222 <context>server</context>
1223 <context>location</context>
1224
1225 <para>
1226 Enables or disables caching of file lookup errors by the
1227 <link id="open_file_cache">open_file_cache</link>.
1228 </para>
1229
1230 </directive>
1231
1232
1233 <!--
1234
1235 <directive name="open_file_cache_events">
1236 <syntax>open_file_cache_events <value>on</value> | <value>off</value></syntax>
1237 <default>open_file_cache_events off</default>
1238 <context>http</context>
1239 <context>server</context>
1240 <context>location</context>
1241
1242 <para>
1243 Enables to use kernel events to validate
1244 <link id="open_file_cache">open_file_cache</link>
1245 elements.
1246 This directive works with the
1247 <link doc="../events.xml" id="kqueue">kqueue</link>
1248 method only.
1249 Note that only NetBSD&nbsp;2.0+ and FreeBSD&nbsp;6.0+
1250 support events for arbitrary file system types.
1251 Other operating systems support events only for essential
1252 file systems such as UFS or FFS.
1253 </para>
1254
1255 </directive>
1256
1257 -->
1258
1259
1260 <directive name="open_file_cache_min_uses">
1261 <syntax>open_file_cache_min_uses <argument>number</argument></syntax>
1262 <default>open_file_cache_min_uses 1</default>
1263 <context>http</context>
1264 <context>server</context>
1265 <context>location</context>
1266
1267 <para>
1268 Sets the minimum <argument>number</argument> of file accesses during
1269 the period configured by the <parameter>inactive</parameter> parameter
1270 of the <link id="open_file_cache">open_file_cache</link> directive,
1271 after which a file descriptor will remain open in the cache.
1272 </para>
1273
1274 </directive>
1275
1276
1277 <directive name="open_file_cache_valid">
1278 <syntax>open_file_cache_valid <argument>time</argument></syntax>
1279 <default>open_file_cache_valid 60</default>
1280 <context>http</context>
1281 <context>server</context>
1282 <context>location</context>
1283
1284 <para>
1285 Sets a time after which
1286 <link id="open_file_cache">open_file_cache</link>
1287 elements should be validated.
1288 <!--
1289 When
1290 <link id="open_file_cache_events">open_file_cache_events</link>
1291 is enabled, open file descriptors
1292 are checked only once, and then updated right after they get changed.
1293 -->
1294
1295 </para>
1296
1297 </directive>
1298
1299
1300 <directive name="optimize_server_names">
1301 <syntax>optimize_server_names <value>on</value> | <value>off</value></syntax>
1302 <default>optimize_server_names on</default>
1303 <context>http</context>
1304 <context>server</context>
1305
1306 <para>
1307 This directive is obsolete.
1308 </para>
1309
1310 <para>
1311 Enables or disables optimization of hostname checking in name-based
1312 virtual servers.
1313 In particular, the checking affects hostnames used in redirects.
1314 If optimization is enabled, and all name-based servers listening on
1315 the same address:port pair have identical configuration, then
1316 names are not checked during request processing, and the first
1317 server name is used in redirects.
1318 In case redirects should use hostnames sent by clients,
1319 optimization needs to be disabled.
1320 </para>
1321
1322 </directive>
1323
1324
1325 <directive name="port_in_redirect">
1326 <syntax>port_in_redirect <value>on</value> | <value>off</value></syntax>
1327 <default>port_in_redirect on</default>
1328 <context>http</context>
1329 <context>server</context>
1330 <context>location</context>
1331
1332 <para>
1333 Enables or disables specifying the port in redirects issued by nginx.
1334 </para>
1335
1336 </directive>
1337
1338
1339 <directive name="read_ahead">
1340 <syntax>read_ahead <argument>size</argument></syntax>
1341 <default>read_ahead 0</default>
1342 <context>http</context>
1343 <context>server</context>
1344 <context>location</context>
1345
1346 <para>
1347 Sets the amount of pre-reading when working with files, in the kernel.
1348 </para>
1349
1350 <para>
1351 On Linux, the
1352 <code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code>
1353 system call is used, so the <argument>size</argument> argument is ignored.
1354 </para>
1355
1356 <para>
1357 On FreeBSD, the
1358 <code>fcntl(O_READAHEAD,</code><argument>size</argument><code>)</code>
1359 system call is used, supported in FreeBSD&nbsp;9.0-CURRENT.
1360 FreeBSD&nbsp;7 needs to be
1361 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>.
1362 </para>
1363
1364 </directive>
1365
1366
1367 <directive name="recursive_error_pages">
1368 <syntax>recursive_error_pages <value>on</value> | <value>off</value></syntax>
1369 <default>recursive_error_pages off</default>
1370 <context>http</context>
1371 <context>server</context>
1372 <context>location</context>
1373
1374 <para>
1375 Enables or disables doing several redirects using the
1376 <link id="error_page">error_page</link>
1377 directive.
1378 </para>
1379
1380 </directive>
1381
1382
1383 <directive name="reset_timedout_connection">
1384 <syntax>reset_timedout_connection
1385 <value>on</value> | <value>off</value></syntax>
1386 <default>reset_timedout_connection off</default>
1387 <context>http</context>
1388 <context>server</context>
1389 <context>location</context>
1390
1391 <para>
1392 Enables or disables resetting of timed out connections.
1393 The reset is performed as follows: before closing a socket, the
1394 <c-def>SO_LINGER</c-def>
1395 option is set on it with a timeout value of 0.
1396 When the socket is closed, a client is sent TCP RST, and all memory
1397 occupied by this socket is freed.
1398 This avoids keeping of an already closed socket with filled buffers
1399 for a long time, in a FIN_WAIT1 state.
1400 </para>
1401
1402 <para>
1403 It should be noted that timed out keep-alive connections are still
1404 closed normally.
1405 </para>
1406
1407 </directive>
1408
1409
1410 <directive name="resolver">
1411 <syntax>resolver <argument>address</argument></syntax>
1412 <default/>
1413 <context>http</context>
1414 <context>server</context>
1415 <context>location</context>
1416
1417 <para>
1418 Sets the <argument>address</argument> of a name server, for example:
1419 <example>
1420 resolver 127.0.0.1;
1421 </example>
1422 </para>
1423
1424 </directive>
1425
1426
1427 <directive name="resolver_timeout">
1428 <syntax>resolver_timeout <argument>time</argument></syntax>
1429 <default>resolver_timeout 30s</default>
1430 <context>http</context>
1431 <context>server</context>
1432 <context>location</context>
1433
1434 <para>
1435 Sets a timeout for name resolution, for example:
1436 <example>
1437 resolver_timeout 5s;
1438 </example>
1439 </para>
1440
1441 </directive>
1442
1443
1444 <directive name="root">
1445 <syntax>root <argument>path</argument></syntax>
1446 <default>root html</default>
1447 <context>http</context>
1448 <context>server</context>
1449 <context>location</context>
1450 <context>if in location</context>
1451
1452 <para>
1453 Sets the root directory for requests.
1454 For example, with the following configuration
1455 <example>
1456 location /i/ {
1457 root /data/w3;
1458 }
1459 </example>
1460 <dq><code>/i/top.gif</code></dq> will be responded
1461 with the file
1462 <dq><pathname>/data/w3/i/top.gif</pathname></dq>.
1463 </para>
1464
1465 <para>
1466 The <argument>path</argument> value can contain variables.
1467 </para>
1468
1469 <para>
1470 A path to the file is constructed by merely adding a URI to the value
1471 of the <code>root</code> directive.
1472 If a URI need to be modified, the
1473 <link id="alias">alias</link> directive should be used.
1474 </para>
1475
1476 </directive>
1477
1478
1479 <directive name="satisfy">
1480 <syntax>satisfy <value>all</value> | <value>any</value></syntax>
1481 <default>satisfy all</default>
1482 <context>location</context>
1483
1484 <para>
1485 Allows access if any of the
1486 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
1487 or <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>
1488 modules grant access.
1489 <example>
1490 location / {
1491 satisfy any;
1492
1493 allow 192.168.1.0/32;
1494 deny all;
1495
1496 auth_basic "closed site";
1497 auth_basic_user_file conf/htpasswd;
1498 }
1499 </example>
1500 </para>
1501
1502 </directive>
1503
1504
1505 <directive name="satisfy_any">
1506 <syntax>satisfy_any <value>on</value> | <value>off</value></syntax>
1507 <default>satisfy_any off</default>
1508 <context>location</context>
1509
1510 <para>
1511 This directive was renamed to the <link id="satisfy">satisfy</link> directive.
1512 </para>
1513
1514 </directive>
1515
1516
1517 <directive name="send_timeout">
1518 <syntax>send_timeout <argument>time</argument></syntax>
1519 <default>send_timeout 60</default>
1520 <context>http</context>
1521 <context>server</context>
1522 <context>location</context>
1523
1524 <para>
1525 Sets a timeout for transmitting a response to the client.
1526 A timeout is only set between two successive write operations,
1527 not for the transmission of the whole response.
1528 If a client does not receive anything within this time,
1529 a connection is closed.
1530 </para>
1531
1532 </directive>
1533
1534
1535 <directive name="sendfile">
1536
1537 <syntax>sendfile <value>on</value> | <value>off</value></syntax>
1538 <default>sendfile off</default>
1539 <context>http</context>
1540 <context>server</context>
1541 <context>location</context>
1542
1543 <para>
1544 Enables or disables the use of
1545 <c-func>sendfile</c-func>.
1546 </para>
1547
1548 </directive>
1549
1550
1551 <directive name="server">
1552 <syntax>server { ... }</syntax>
1553 <default/>
1554 <context>http</context>
1555
1556 <para>
1557 Sets a configuration for the virtual server.
1558 There is no clean separation between IP-based (based on the IP address)
1559 and name-based (based on the <header>Host</header> request header field)
1560 virtual servers.
1561 Instead, the <link id="listen">listen</link> directives describe all
1562 addresses and ports that should accept connections for a server, and the
1563 <link id="server_name">server_name</link> directive lists all server names.
1564 An example configuration is provided in the
1565 <link doc="../virtual_hosts.xml">
1566 Setting Up Virtual Servers</link> document.
1567 </para>
1568
1569 </directive>
1570
1571
1572 <directive name="server_name">
1573 <syntax>server_name <argument>name</argument> ...</syntax>
1574 <default>server_name hostname</default>
1575 <context>server</context>
1576
1577 <para>
1578 Sets names of the virtual server, for example:
1579 <example>
1580 server {
1581 server_name example.com www.example.com;
1582 }
1583 </example>
1584 </para>
1585
1586 <para>
1587 The first name becomes a primary server name.
1588 By default, the machine's hostname is used.
1589 Server names can include an asterisk (<dq><code>*</code></dq>)
1590 to replace the first or last part of a name:
1591 <example>
1592 server {
1593 server_name example.com *.example.com www.example.*;
1594 }
1595 </example>
1596 </para>
1597
1598 <para>
1599 The first two of the above mentioned names can be combined:
1600 <example>
1601 server {
1602 server_name .example.com;
1603 }
1604 </example>
1605 </para>
1606
1607 <para>
1608 It is also possible to use regular expressions in server names,
1609 prepending the name with a tilde (<dq><code>~</code></dq>):
1610 <example>
1611 server {
1612 server_name www.example.com ~^www\d+\.example\.com$;
1613 }
1614 </example>
1615 </para>
1616
1617 <para>
1618 Regular expressions can contain captures (0.7.40) that can later
1619 be used in other directives:
1620 <example>
1621 server {
1622 server_name ~^(www\.)?(.+)$;
1623
1624 location / {
1625 root /sites/$2;
1626 }
1627 }
1628
1629 server {
1630 server_name _;
1631
1632 location / {
1633 root /sites/default;
1634 }
1635 }
1636 </example>
1637 </para>
1638
1639 <para>
1640 Starting from version 0.8.25, named captures in regular expressions create
1641 variables that can later be used in other directives:
1642 <example>
1643 server {
1644 server_name ~^(www\.)?(?&lt;domain&gt;.+)$;
1645
1646 location / {
1647 root /sites/$domain;
1648 }
1649 }
1650
1651 server {
1652 server_name _;
1653
1654 location / {
1655 root /sites/default;
1656 }
1657 }
1658 </example>
1659 </para>
1660
1661 <para>
1662 Starting from version 0.7.11, it is possible to specify an empty name:
1663 <example>
1664 server {
1665 server_name www.example.com "";
1666 }
1667 </example>
1668 It allows this server to process requests without the <header>Host</header>
1669 header, instead of the default server for the given address:port pair.
1670 </para>
1671
1672 <para>
1673 The name checking order is as follows:
1674 <list type="enum">
1675
1676 <listitem>
1677 full names
1678 </listitem>
1679
1680 <listitem>
1681 names with the prefix mask, e.g. <dq><code>*.example.com</code></dq>
1682 </listitem>
1683
1684 <listitem>
1685 names with the suffix mask, e.g. <dq><code>mail.*</code></dq>
1686 </listitem>
1687
1688 <listitem>
1689 regular expressions
1690 </listitem>
1691
1692 </list>
1693 </para>
1694
1695 </directive>
1696
1697
1698 <directive name="server_name_in_redirect">
1699 <syntax>server_name_in_redirect <value>on</value> | <value>off</value></syntax>
1700 <default>server_name_in_redirect on</default>
1701 <context>http</context>
1702 <context>server</context>
1703 <context>location</context>
1704
1705 <para>
1706 Enables or disables the use of the primary server name, specified by the
1707 <link id="server_name">server_name</link>
1708 directive, in redirects issued by nginx.
1709 When disabled, the name from the <header>Host</header> request header field
1710 is used.
1711 If this field is not present, an IP address of the server is used.
1712 </para>
1713
1714 </directive>
1715
1716
1717 <directive name="server_names_hash_max_size">
1718 <syntax>server_names_hash_max_size <argument>size</argument></syntax>
1719 <default>server_names_hash_max_size 512</default>
1720 <context>http</context>
1721
1722 <para>
1723 Sets the maximum <argument>size</argument> of the server names hash tables.
1724 For more information, please refer to
1725 <link doc="../hash.xml">Setting Up Hashes</link>.
1726 </para>
1727
1728 </directive>
1729
1730
1731 <directive name="server_names_hash_bucket_size">
1732 <syntax>server_names_hash_bucket_size <argument>size</argument></syntax>
1733 <default>server_names_hash_bucket_size 32/64/128</default>
1734 <context>http</context>
1735
1736 <para>
1737 Sets the bucket size for the server names hash tables.
1738 Default value depends on the size of the processor's cache line.
1739 For more information, please refer to
1740 <link doc="../hash.xml">Setting Up Hashes</link>.
1741 </para>
1742
1743 </directive>
1744
1745
1746 <directive name="server_tokens">
1747 <syntax>server_tokens <value>on</value> | <value>off</value></syntax>
1748 <default>server_tokens on</default>
1749 <context>http</context>
1750 <context>server</context>
1751 <context>location</context>
1752
1753 <para>
1754 Enables or disables emitting of nginx version in error messages and in the
1755 <header>Server</header> response header field.
1756 </para>
1757
1758 </directive>
1759
1760
1761 <directive name="tcp_nodelay">
1762 <syntax>tcp_nodelay <value>on</value> | <value>off</value></syntax>
1763 <default>tcp_nodelay on</default>
1764 <context>http</context>
1765 <context>server</context>
1766 <context>location</context>
1767
1768 <para>
1769 Enables or disables the use of the <c-def>TCP_NODELAY</c-def> option.
1770 The option is enabled only when a connection is transitioned into the
1771 keep-alive state.
1772 </para>
1773
1774 </directive>
1775
1776
1777 <directive name="tcp_nopush">
1778 <syntax>tcp_nopush <value>on</value> | <value>off</value></syntax>
1779 <default>tcp_nopush off</default>
1780 <context>http</context>
1781 <context>server</context>
1782 <context>location</context>
1783
1784 <para>
1785 Enables or disables the use of
1786 the <c-def>TCP_NOPUSH</c-def> socket option on FreeBSD
1787 or the <c-def>TCP_CORK</c-def> socket option on Linux.
1788 Opitons are enables only when <link id="sendfile">sendfile</link> is used.
1789 Enabling the option allows to
1790 <list type="bullet">
1791
1792 <listitem>
1793 send the response header and the beginning of a file in one packet,
1794 on Linux and FreeBSD&nbsp;4.*;
1795 </listitem>
1796
1797 <listitem>
1798 send a file in full packets.
1799 </listitem>
1800
1801 </list>
1802 </para>
1803
1804 </directive>
1805
1806
1807 <directive name="try_files">
1808 <syntax>try_files
1809 <argument>file</argument> ...
1810 <argument>uri</argument>
1811 </syntax>
1812 <syntax>try_files
1813 <argument>file</argument> ...
1814 =<argument>code</argument>
1815 </syntax>
1816 <default/>
1817 <context>location</context>
1818
1819 <para>
1820 Checks the existence of files in the specified order, and uses
1821 the first found file for request processing; the processing
1822 is performed in this location's context.
1823 It is possible to check the directory existence by specifying
1824 the slash at the end of a name, e.g. <dq><code>$uri/</code></dq>.
1825 If none of the files were found, an internal redirect to the
1826 <argument>uri</argument> specified by the last argument is made.
1827 As of version 0.7.51, the last argument can also be a
1828 <argument>code</argument>:
1829 <example>
1830 location / {
1831 try_files $uri $uri/index.html $uri.html =404;
1832 }
1833 </example>
1834 </para>
1835
1836 <para>
1837 Example when proxying Mongrel:
1838 <example>
1839 location / {
1840 try_files /system/maintenance.html
1841 $uri $uri/index.html $uri.html
1842 @mongrel;
1843 }
1844
1845 location @mongrel {
1846 proxy_pass http://mongrel;
1847 }
1848 </example>
1849 </para>
1850
1851 <para>
1852 Example for Drupal/FastCGI:
1853 <example>
1854 location / {
1855 try_files $uri $uri/ @drupal;
1856 }
1857
1858 location ~ \.php$ {
1859 try_files $uri @drupal;
1860
1861 fastcgi_pass ...;
1862
1863 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1864 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
1865 fastcgi_param QUERY_STRING $args;
1866
1867 ... other fastcgi_param's
1868 }
1869
1870 location @drupal {
1871 fastcgi_pass ...;
1872
1873 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1874 fastcgi_param SCRIPT_NAME /index.php;
1875 fastcgi_param QUERY_STRING q=$uri&amp;$args;
1876
1877 ... other fastcgi_param's
1878 }
1879 </example>
1880 In the following example,
1881 <example>
1882 location / {
1883 try_files $uri $uri/ @drupal;
1884 }
1885 </example>
1886 the <code>try_files</code> directive is equivalent to
1887 <example>
1888 location / {
1889 error_page 404 = @drupal;
1890 log_not_found off;
1891 }
1892 </example>
1893 And here,
1894 <example>
1895 location ~ \.php$ {
1896 try_files $uri @drupal;
1897
1898 fastcgi_pass ...;
1899
1900 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1901
1902 ...
1903 }
1904 </example>
1905 <code>try_files</code> checks the existence of the PHP file
1906 before passing the request to the FastCGI server.
1907 </para>
1908
1909 <para>
1910 Example for Wordpress and Joomla:
1911 <example>
1912 location / {
1913 try_files $uri $uri/ @wordpress;
1914 }
1915
1916 location ~ \.php$ {
1917 try_files $uri @wordpress;
1918
1919 fastcgi_pass ...;
1920
1921 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1922 ... other fastcgi_param's
1923 }
1924
1925 location @wordpress {
1926 fastcgi_pass ...;
1927
1928 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1929 ... other fastcgi_param's
1930 }
1931 </example>
1932 </para>
1933
1934 </directive>
1935
1936
1937 <directive name="types">
1938 <syntax>types { ... }</syntax>
1939 <default>see below</default>
1940 <context>http</context>
1941 <context>server</context>
1942 <context>location</context>
1943
1944 <para>
1945 Maps file name extensions to MIME types of responses.
1946 Several extensions can map to one type.
1947 The following mappings are configured by default:
1948 <example>
1949 types {
1950 text/html html;
1951 image/gif gif;
1952 image/jpeg jpg;
1953 }
1954 </example>
1955 </para>
1956
1957 <para>
1958 A sufficiently full mapping table is distributed with nginx in the
1959 <pathname>conf/mime.types</pathname> file.
1960 </para>
1961
1962 <para>
1963 To make a particular location emit the
1964 <dq><code>application/octet-stream</code></dq>
1965 MIME type for all requests, try the following:
1966 <example>
1967 location /download/ {
1968 types { }
1969 default_type application/octet-stream;
1970 }
1971 </example>
1972 </para>
1973
1974 </directive>
1975
1976
1977 <directive name="underscores_in_headers">
1978 <syntax>underscores_in_headers <value>on</value> | <value>off</value></syntax>
1979 <default>underscores_in_headers off</default>
1980 <context>http</context>
1981 <context>server</context>
1982
1983 <para>
1984 Enables or disables the use of underscores in client request header fields.
1985 </para>
1986
1987 </directive>
1988
1989 </section>
1990
1991 <section id="variables" name="Embedded Variables">
1992
1993 <para>
1994 The module <code>ngx_http_core_module</code> supports embedded variables with
1995 names matching those of the Apache Server.
1996 First of all, these are variables representing client request header
1997 fields, such as, <var>$http_user_agent</var>, <var>$http_cookie</var>,
1998 and so on.
1999 It also supports other variables:
2000 <list type="tag">
2001
2002 <tag-name><var>$args</var></tag-name>
2003 <tag-desc>
2004 arguments in the request line
2005 </tag-desc>
2006
2007 <tag-name><var>$arg_</var><argument>name</argument></tag-name>
2008 <tag-desc>
2009 argument <argument>name</argument> in the request line
2010 </tag-desc>
2011
2012 <tag-name><var>$binary_remote_addr</var></tag-name>
2013 <tag-desc>
2014 client address in a binary form, value's length is always 4 bytes
2015 </tag-desc>
2016
2017 <tag-name><var>$content_length</var></tag-name>
2018 <tag-desc>
2019 <header>Content-Length</header> request header field
2020 </tag-desc>
2021
2022 <tag-name><var>$content_type</var></tag-name>
2023 <tag-desc>
2024 <header>Content-Type</header> request header field
2025 </tag-desc>
2026
2027 <tag-name><var>$cookie_</var><argument>name</argument></tag-name>
2028 <tag-desc>
2029 the <argument>name</argument> cookie
2030 </tag-desc>
2031
2032 <tag-name><var>$document_root</var></tag-name>
2033 <tag-desc>
2034 <link id="root">root</link> directive's value for the current request
2035 </tag-desc>
2036
2037 <tag-name><var>$document_uri</var></tag-name>
2038 <tag-desc>
2039 same as <var>$uri</var>
2040 </tag-desc>
2041
2042 <tag-name><var>$host</var></tag-name>
2043 <tag-desc>
2044 <header>Host</header> request header field,
2045 or the server name matching a request if this field is not present
2046 </tag-desc>
2047
2048 <tag-name><var>$hostname</var></tag-name>
2049 <tag-desc>
2050 host name
2051 </tag-desc>
2052
2053 <tag-name><var>$http_</var><argument>name</argument></tag-name>
2054 <tag-desc>
2055 the <argument>name</argument> request header field
2056 </tag-desc>
2057
2058 <tag-name><var>$is_args</var></tag-name>
2059 <tag-desc>
2060 <dq><code>?</code></dq> if a request line has arguments,
2061 or an empty string otherwise
2062 </tag-desc>
2063
2064 <tag-name><var>$limit_rate</var></tag-name>
2065 <tag-desc>
2066 allows for connection rate limiting
2067 </tag-desc>
2068
2069 <tag-name><var>$pid</var></tag-name>
2070 <tag-desc>
2071 PID of the worker process
2072 </tag-desc>
2073
2074 <tag-name><var>$request_method</var></tag-name>
2075 <tag-desc>
2076 request method, usually
2077 <dq><code>GET</code></dq> or <dq><code>POST</code></dq>
2078 </tag-desc>
2079
2080 <tag-name><var>$remote_addr</var></tag-name>
2081 <tag-desc>
2082 client address
2083 </tag-desc>
2084
2085 <tag-name><var>$remote_port</var></tag-name>
2086 <tag-desc>
2087 client port
2088 </tag-desc>
2089
2090 <tag-name><var>$remote_user</var></tag-name>
2091 <tag-desc>
2092 user name supplied with the Basic authentication
2093 </tag-desc>
2094
2095 <tag-name><var>$realpath_root</var></tag-name>
2096 <tag-desc>
2097 <link id="root">root</link> directive's value
2098 for the current request, with all symbolic links resolved to real paths
2099 </tag-desc>
2100
2101 <tag-name><var>$request_filename</var></tag-name>
2102 <tag-desc>
2103 file path for the current query, based on the
2104 <link id="root">root</link> and <link id="alias">alias</link>
2105 directives, and the request URI
2106 </tag-desc>
2107
2108 <tag-name><var>$request_body</var></tag-name>
2109 <tag-desc>
2110 request body
2111 <para>
2112 The variable's value is made available in locations
2113 processed by the
2114 <link doc="ngx_http_proxy_module.xml" id="proxy_pass">proxy_pass</link>
2115 and
2116 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass">fastcgi_pass</link>
2117 directives.
2118 </para>
2119 </tag-desc>
2120
2121 <tag-name><var>$request_body_file</var></tag-name>
2122 <tag-desc>
2123 name of a temporary file with the request body
2124 <para>
2125 At the end of processing, the file needs to be removed.
2126 To always write a request body to a file,
2127 <link id="client_body_in_file_only">client_body_in_file_only on</link>
2128 needs be specified.
2129 When passing the name of a temporary file in a proxied request,
2130 or in a request to a FastCGI server,
2131 passing of the request body should be disabled by the
2132 <link doc="ngx_http_proxy_module.xml"
2133 id="proxy_pass_request_body">proxy_pass_request_body</link>
2134 and
2135 <link doc="ngx_http_fastcgi_module.xml"
2136 id="fastcgi_pass_request_body">fastcgi_pass_request_body</link>
2137 directives, respectively.
2138 </para>
2139 </tag-desc>
2140
2141 <tag-name><var>$request_uri</var></tag-name>
2142 <tag-desc>
2143 full original request URI (with arguments)
2144 </tag-desc>
2145
2146 <tag-name><var>$query_string</var></tag-name>
2147 <tag-desc>
2148 same as <var>$args</var>
2149 </tag-desc>
2150
2151 <tag-name><var>$scheme</var></tag-name>
2152 <tag-desc>
2153 request scheme, <dq><code>http</code></dq> or <dq><code>https</code></dq>
2154 </tag-desc>
2155
2156 <tag-name><var>$server_protocol</var></tag-name>
2157 <tag-desc>
2158 request protocol, usually
2159 <dq><code>HTTP/1.0</code></dq>
2160 or
2161 <dq><code>HTTP/1.1</code></dq>
2162 </tag-desc>
2163
2164 <tag-name><var>$server_addr</var></tag-name>
2165 <tag-desc>
2166 an address of the server which accepted a request
2167 <para>
2168 Computing a value of this variable usually requires one system call.
2169 To avoid a system call, the <link id="listen">listen</link> directives
2170 must specify addresses and use the <parameter>bind</parameter> parameter
2171 </para>
2172 </tag-desc>
2173
2174 <tag-name><var>$server_name</var></tag-name>
2175 <tag-desc>
2176 name of the server which accepted a request
2177 </tag-desc>
2178
2179 <tag-name><var>$server_port</var></tag-name>
2180 <tag-desc>
2181 port of the server which accepted a request
2182 </tag-desc>
2183
2184 <tag-name><var>$uri</var></tag-name>
2185 <tag-desc>
2186 current URI in request
2187 <para>
2188 It may differ from an original, e.g. when doing internal redirects,
2189 or when using index files.
2190 </para>
2191 </tag-desc>
2192
2193 </list>
2194 </para>
2195
2196 </section>
2197
2198 </module>