Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_core_module.xml @ 76:4a4caa566120

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Russian documentation import. Changes in module.dtd: <example> now allowed to contain <value> and <emphasis> elements (we need this to show important parts in examples), less strict checking of <directive> syntax (we don't want to fully document some directives, notably deprecated ones). Known issues: 1. <syntax> elements are preserved as is, they will require manual conversion (likely to some not-yet-existed format a la DocBook cmdsynopsis, as currently used one seems to be incomplete); 2. <value> no longer corresponds to replaceable content, and it's use in examples isn't correct; 3. <link doc="document#fragment"> doesn't work with current xslt, either should be supported or changed to <link doc="document" id="fragment">. The following files are intentionally omitted: maillists.xml (support.xml should be used instead), experimental.xml (obsolete), faq.xml (conflicts with existing one, needs discussion). Not yet linked to site.
author Maxim Dounin <mdounin@mdounin.ru>
date Tue, 11 Oct 2011 12:57:50 +0000
parents
children 0a45870d0160
comparison
equal deleted inserted replaced
75:2bf4cd2787c5 76:4a4caa566120
1 <?xml version="1.0" encoding="utf-8"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Директивы модуля ngx_http_core_module"
6 link="/ru/docs/http/ngx_http_core_module.html"
7 lang="ru">
8
9 <section name="Директивы" id="directives">
10
11 <directive name="aio">
12 <syntax>aio <value>[on|off|sendfile]</value></syntax>
13 <default>aio off</default>
14 <context>http, server, location</context>
15
16 <para>
17 Директива (0.8.11) разрешает или запрещает использовать файловый AIO
18 во FreeBSD и Linux.
19 </para>
20
21 <para>
22 Во FreeBSD AIO можно использовать, начиная с FreeBSD 4.3 версии.
23 AIO можно собрать в ядре статически
24 <example>
25 options VFS_AIO
26 </example>
27 или же подгрузить динамически
28 <example>
29 kldload aio
30 </example>
31 </para>
32
33 <para>
34 Во FreeBSD 5 и 6 при включении AIO статически или динамически на стадии
35 загрузки ядра вся сетевая подсистема будет использовать GiantLock,
36 что может негативно сказаться на производительности системы в целом.
37 Эта зависимость устранена во FreeBSD-6.4 STABLE от 2009 года и во FreeBSD 7.
38 Однако, начиная с FreeBSD 5.3, есть возможность включать AIO,
39 не связывая сетевую подсистему GiantLock'ом — для этого модуль AIO
40 нужно подгружать уже после загрузки ядра.
41 В этом случае в /var/log/messages появится сообщение
42 <example>
43 WARNING: Network stack Giant-free, but aio requires Giant.
44 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
45 </example>
46 которое можно смело проигнорировать.
47 <note>
48 Требование использовать GiantLock в AIO связано с тем, что FreeBSD
49 поддерживает асинхронные вызовы aio_read()/aio_write() для работы с сокетами.
50 Но поскольку nginx использует AIO только для работы с диском, то проблем
51 не возникает.
52 </note>
53 </para>
54
55 <para>
56 Для работы AIO нужно выключить sendfile:
57 <example>
58 location /video/ {
59 sendfile off;
60 aio on;
61 output_buffers 1 64k;
62 }
63 </example>
64 </para>
65
66 <para>
67 Кроме того, начиная с FreeBSD 5.2.1 и nginx-0.8.12, AIO также можно
68 использовать для подгрузки данных для sendfile():
69 <example>
70 location /video/ {
71 sendfile on;
72 tcp_nopush on;
73 aio sendfile;
74 }
75 </example>
76 В такой конфигурации используется флаг SF_NODISKIO и sendfile()
77 не блокируется на диске, а сообщает об отсутствии данных в памяти,
78 после чего nginx инициирует асинхронную подгрузку данных,
79 читая только один байт. При этом ядро FreeBSD подгружает в память
80 первые 128K файла, однако при последующих чтениях файл подгружается
81 частями только по 16K. Изменить это можно с помощью директивы
82 <link id="read_ahead">read_ahead</link>.
83 </para>
84
85 <para>
86 В Linux AIO можно использовать, только начиная с версии ядра 2.6.22,
87 и, кроме того, ещё необходимо дополнительно включать
88 <link id="directio">directio</link>, иначе чтение будет блокирующимся:
89 <example>
90 location /video/ {
91 aio on;
92 directio 512;
93 output_buffers 1 128k;
94 }
95 </example>
96 </para>
97
98 <para>
99 Поскольку directio в Linux можно использовать только для чтения блоков,
100 выравненных по 512 байт (или 4К для XFS), то невыравненный конец файла
101 будет читаться блокировано. То же относится к запросам части ответа
102 byte-ranges и к запросам FLV не с начала файла: чтение невыровненных начала
103 и конца ответа будет блокирующимся. sendfile выключать не нужно, так
104 как при использовании directio он выключается сам.
105 </para>
106
107 </directive>
108
109
110 <directive name="alias">
111 <syntax>alias <value>путь</value></syntax>
112 <default>нет</default>
113 <context>location</context>
114
115 <para>
116 Директива задаёт замену для указанного location'а.
117 Например, при такой конфигурации
118 <example>
119 location /i/ {
120 alias /data/w3/images/;
121 }
122 </example>
123 на запрос "/i/top.gif" будет отдан файл "/data/w3/images/top.gif".
124 </para>
125
126 <para>
127 В значении пути можно использовать переменные.
128 </para>
129
130 <para>
131 Если директива alias используется внутри location'а, заданного
132 регулярным выражением, то регулярное выражение должно содержать выделения,
133 а директива alias — ссылки на эти выделения (0.7.40), например:
134 <example>
135 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
136 alias /data/w3/images/$1;
137 }
138 </example>
139 </para>
140
141 <para>
142 Если location и последняя часть значения директивы совпадают:
143 <example>
144 location /images/ {
145 alias /data/w3/images/;
146 }
147 </example>
148 то лучше воспользоваться директивой <link id="root"/>:
149 <example>
150 location /images/ {
151 root /data/w3;
152 }
153 </example>
154 </para>
155
156 </directive>
157
158
159 <directive name="client_body_in_file_only">
160 <syntax>client_body_in_file_only <value>on|clean|off</value></syntax>
161 <default>client_body_in_file_only off</default>
162 <context>http, server, location</context>
163
164 <para>
165 Директива определяет, сохранять ли всё тело запроса клиента в файл.
166 Директиву можно использовать для отладки и при использовании
167 переменной $request_body_file или метода <link doc="ngx_http_perl_module.xml#methods">$r-&gt;request_body_file</link>
168 модуля ngx_http_perl_module.
169 </para>
170
171 <para>
172 При использовании параметра "on" временные файлы по окончании
173 обработки запроса не удаляется.
174 </para>
175
176 <para>
177 Параметр "clean" разрешает удалять временные файлы, оставшиеся по окончании
178 обработки запроса.
179 </para>
180
181 </directive>
182
183
184 <directive name="client_body_in_single_buffer">
185 <syntax>client_body_in_single_buffer <value>on|off</value></syntax>
186 <default>client_body_in_single_buffer off</default>
187 <context>http, server, location</context>
188
189 <para>
190 Директива определяет, хранить ли всё тело запроса клиента в одном буфере.
191 Директива рекомендуется при использовании переменной $request_body
192 для уменьшения операций копирования.
193 </para>
194
195 </directive>
196
197
198 <directive name="client_body_buffer_size">
199 <syntax>client_body_buffer_size <value>размер</value></syntax>
200 <default>client_body_buffer_size 8k/16k</default>
201 <context>http, server, location</context>
202
203 <para>
204 Директива задаёт размер буфера для чтения тела запроса клиента.
205 Если тело запроса больше заданного буфера, то всё тело запроса или только
206 его часть записывается во временный файл.
207 По умолчанию размер одного буфера равен двум размерам страницы, в зависимости
208 от платформы это или 8K, или 16K.
209 </para>
210
211 </directive>
212
213
214 <directive name="client_body_temp_path">
215 <syntax>client_body_temp_path <value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ]
216 </value></syntax>
217 <default>client_body_temp_path client_body_temp</default>
218 <context>http, server, location</context>
219
220 <para>
221 Директива задаёт имя каталога для хранения временных файлов с телом запроса
222 клиента.
223 В каталоге может использоваться иерархия подкаталогов до трёх уровней.
224 Например, при такой конфигурации
225 <example>
226 client_body_temp_path /spool/nginx/client_temp 1 2;
227 </example>
228 имя временного будет такого вида:
229 <example>
230 /spool/nginx/client_temp/7/45/00000123457
231 </example>
232 </para>
233
234 </directive>
235
236
237 <directive name="client_body_timeout">
238 <syntax>client_body_timeout <value>время</value></syntax>
239 <default>client_body_timeout 60</default>
240 <context>http, server, location</context>
241
242 <para>
243 Директива задаёт таймаут при чтении тела запроса клиента.
244 Таймаут устанавливается не на всю передачу тела запроса,
245 а только между двумя операциями чтения.
246 Если по истечении этого времени клиент ничего не передаст,
247 то ему возвращается ошибка "Request time out" (408).
248 </para>
249
250 </directive>
251
252
253 <directive name="client_header_buffer_size">
254 <syntax>client_header_buffer_size <value>размер</value></syntax>
255 <default>client_header_buffer_size 1k</default>
256 <context>http, server</context>
257
258 <para>
259 Директива задаёт размер буфера для чтения заголовка запроса клиента.
260 Для подавляющего большинства запросов вполне достаточно буфера размером в 1K.
261 Однако если в запросе есть большие cookies или же запрос пришёл
262 от wap-клиента, то он может не поместиться в 1K.
263 Поэтому, если строка запроса или строка заголовка запроса не помещается
264 полностью в этот буфер, то выделяются большие буферы, задаваемые директивой
265 <link id="large_client_header_buffers"/>.
266 </para>
267
268 </directive>
269
270
271 <directive name="client_header_timeout">
272 <syntax>client_header_timeout <value>время</value></syntax>
273 <default>client_header_timeout 60</default>
274 <context>http, server</context>
275
276 <para>
277 Директива задаёт таймаут при чтении заголовка запроса клиента.
278 Если по истечении этого времени клиент не передаст полностью заголовок
279 запроса, то ему возвращается ошибка "Request time out" (408).
280 </para>
281
282 </directive>
283
284
285 <directive name="client_max_body_size">
286 <syntax>client_max_body_size <value>размер</value></syntax>
287 <default>client_max_body_size 1m</default>
288 <context>http, server, location</context>
289
290 <para>
291 Директива задаёт максимально допустимый размер тела запроса клиента,
292 указываемый в строке "Content-Length" в заголовке запроса.
293 Если размер больше заданного, то клиенту возвращается ошибка
294 "Request Entity Too Large" (413). Следует иметь в виду, что
295 <link url="http://sysoev.ru/web/upload.html">браузеры не умеют
296 корректно показывать эту ошибку</link>.
297 </para>
298
299 </directive>
300
301
302 <directive name="default_type">
303 <syntax>default_type <value>MIME-тип</value></syntax>
304 <default>default_type text/plain</default>
305 <context>http, server, location</context>
306
307 <para>
308 Директива задаёт MIME-тип ответов по умолчанию.
309 </para>
310
311 </directive>
312
313
314 <directive name="directio">
315 <syntax>directio <value>[размер|off]</value></syntax>
316 <default>directio off</default>
317 <context>http, server, location</context>
318
319 <para>
320 Директива (0.7.7) разрешает использовать флаги
321 O_DIRECT (FreeBSD, Linux), F_NOCACHE (Mac OS X) или функцию directio() (Solaris)
322 при чтении файлов, размер которых больше либо равен указанному.
323 Директива автоматически запрещает (0.7.15) использование
324 <link id="sendfile">sendfile'а</link> для данного запроса.
325 Рекомендуется использовать для больших файлов:
326 <example>
327 directio 4m;
328 </example>
329 или при использовании <link id="aio">aio</link> в Linux.
330 </para>
331
332 </directive>
333
334
335 <directive name="directio_alignment">
336 <syntax>directio_alignment <value>размер</value></syntax>
337 <default>directio_alignment 512</default>
338 <context>http, server, location</context>
339
340 <para>
341 Директива (0.8.11) устанавливает выравнивание для
342 <link id="directio">directio</link>.
343 В большинстве случае достаточно выравнивания 512 байт, однако
344 при использовании XFS под Linux его нужно увеличить до 4K.
345 </para>
346
347 </directive>
348
349
350 <directive name="error_page">
351 <syntax>error_page <value>код [код ...] [=|=ответ] uri</value>
352 </syntax>
353 <default>нет</default>
354 <context>http, server, location, if в location</context>
355
356 <para>
357 Директива задаёт URI, который будет показываться для указанных ошибок.
358 Директивы наследуются с предыдущего уровня при условии, что на данном
359 уровне не описаны свои директивы error_page.
360 В URI можно использовать переменные.
361 </para>
362
363 <para>
364 Пример использования:
365 <example>
366 error_page 404 /404.html;
367 error_page 502 503 504 /50x.html;
368 error_page 403 http://example.com/forbidden.html;
369 </example>
370 </para>
371
372 <para>
373 Кроме того, можно поменять код ответа на другой, например:
374 <example>
375 error_page 404 =200 /empty.gif;
376 </example>
377 </para>
378
379 <para>
380 Если ошибочный ответ обрабатывается проксированным сервером или
381 FastCGI-сервером и этот сервер может вернуть разные коды ответов,
382 например, 200, 302, 401 или 404, то можно выдавать возвращаемый код:
383 <example>
384 error_page 404 = /404.php;
385 </example>
386 </para>
387
388 <para>
389 Если при перенаправлении не нужно менять URI, то можно перенаправить
390 обработку ошибки в именованный location:
391 <example>
392 location / {
393 error_page 404 = @fallback;
394 }
395
396 location @fallback {
397 proxy_pass http://backend;
398 }
399 </example>
400 </para>
401
402 </directive>
403
404
405 <directive name="if_modified_since">
406 <syntax>if_modified_since <value>[off|exact|before]</value></syntax>
407 <default>if_modified_since exact</default>
408 <context>http, server, location</context>
409
410 <para>
411 Директива (0.7.24) определяет, как сравнивать время модификации ответа и
412 время в заголовке запроса "If-Modified-Since":
413 <list type="bullet">
414
415 <listitem>
416 off — не проверять заголовок запроса
417 "If-Modified-Since" (0.7.34);
418 </listitem>
419
420 <listitem>
421 exact — точно совпадение;
422 </listitem>
423
424 <listitem>
425 before — время модификации ответа меньше или равно времени, заданному
426 в заголовке запроса "If-Modified-Since".
427 </listitem>
428
429 </list>
430 </para>
431
432 </directive>
433
434
435 <directive name="internal">
436 <syntax>internal</syntax>
437 <default>нет</default>
438 <context>location</context>
439
440 <para>
441 Директива указывает, что данный location может использоваться только
442 для внутренних запросов.
443 Для внешних запросов будет возвращаться ошибка "Not found" (404).
444 Внутренними запросами являются
445 <list type="bullet">
446
447 <listitem>
448 запросы, перенаправленные директивой error_page;
449 </listitem>
450
451 <listitem>
452 подзапросы, формируемые командой include virtual модуля ngx_http_ssi_module;
453 </listitem>
454
455 <listitem>
456 запросы, изменённые директивой rewrite модуля ngx_http_rewrite_module.
457 </listitem>
458
459 </list>
460 </para>
461
462 <para>
463 Пример использования:
464 <example>
465 error_page 404 /404.html;
466
467 location /404.html {
468 internal;
469 }
470 </example>
471 </para>
472
473 </directive>
474
475
476 <directive name="keepalive_requests">
477 <syntax>keepalive_requests <value>число</value></syntax>
478 <default>keepalive_requests 100</default>
479 <context>http, server, location</context>
480
481 <para>
482 Директива (0.8.0) задаёт максимальное число запросов, которые можно
483 сделать по одному keep-alive соединению.
484 </para>
485
486 </directive>
487
488
489 <directive name="keepalive_timeout">
490 <syntax>keepalive_timeout <value>время [время]</value></syntax>
491 <default>keepalive_timeout 75</default>
492 <context>http, server, location</context>
493
494 <para>
495 Директива задаёт таймаут, в течение которого keep-alive соединение
496 с клиентом не будет закрыто со стороны сервера.
497 Второй параметр задаёт значение в строке "Keep-Alive: timeout=время"
498 в заголовке ответа. Параметры могут отличаться друг от друга.
499 Строку "Keep-Alive: timeout=время" понимают Mozilla и Konqueror.
500 MSIE сам закрывает keep-alive соединение примерно через 60 секунд.
501 </para>
502
503 </directive>
504
505
506 <directive name="large_client_header_buffers">
507 <syntax>large_client_header_buffers <value>число размер</value>
508 </syntax>
509 <default>large_client_header_buffers 4 4k/8k</default>
510 <context>http, server</context>
511
512 <para>
513 Директива задаёт максимальное число и размер буферов для чтения
514 большого заголовка запроса клиента.
515 Строка запроса должна быть не больше размера одного буфера, иначе клиенту
516 возвращается ошибка "Request URI too large" (414).
517 Длинная строка заголовка запроса также должна быть не больше размера одного
518 буфера, иначе клиенту возвращается ошибка "Bad request" (400).
519 Буферы выделяются только по мере необходимости.
520 По умолчанию размер одного буфера равен размеру страницы, в зависимости
521 от платформы это или 4K, или 8K.
522 Если по окончании обработки запроса соединение переходит в состояние
523 keep-alive, то эти буферы освобождаются.
524 </para>
525
526 </directive>
527
528
529 <directive name="limit_except">
530 <syntax>limit_except <value>методы</value> { ... }</syntax>
531 <default>нет</default>
532 <context>location</context>
533
534 <para>
535 Директива ограничивает HTTP-методы, доступные внутри location.
536 Метод GET также включает в себя метод HEAD.
537 Для ограничения могут использоваться директивы модулей <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
538 и <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>:
539 <example>
540 limit_except GET {
541 allow 192.168.1.0/32;
542 deny all;
543 }
544 </example>
545 Обратите внимание, что данное ограничение будет выполняться для всех методов,
546 <value>кроме</value> методов GET и HEAD.
547 </para>
548
549 </directive>
550
551
552 <directive name="limit_rate">
553
554 <syntax>limit_rate <value>скорость</value></syntax>
555 <default>нет</default>
556 <context>http, server, location, if в location</context>
557
558 <para>
559 Директива задаёт скорость передачи ответа клиенту.
560 Скорость задаётся в байтах в секунду.
561
562 Ограничение работает только для одного соединения, то есть,
563 если клиент откроет 2 соединения, то суммарная скорость будет в 2 раза
564 выше ограниченной.
565 </para>
566
567 <para>
568 Если необходимо ограничить скорость для части клиентов на уровне сервера,
569 то директива limit_rate для этого не подходит. Вместо этого следует
570 задать нужную скорость переменной $limit_rate:
571 <example>
572 server {
573
574 if ($slow) {
575 set $limit_rate 4k;
576 }
577
578 ...
579 }
580 </example>
581 </para>
582
583 </directive>
584
585
586 <directive name="limit_rate_after">
587 <syntax>limit_rate_after <value>размер</value></syntax>
588 <default>нет</default>
589 <context>http, server, location, if в location</context>
590
591 <para>
592 Директива (0.8.0) задаёт объём данных, после передачи которого
593 начинает ограничиваться скорость передачи ответа клиенту, например:
594 <example>
595 location /flv/ {
596 flv;
597 limit_rate_after 500k;
598 limit_rate 50k;
599 }
600 </example>
601 </para>
602
603 </directive>
604
605
606 <directive name="listen">
607 <syntax>listen <value>адрес:порт
608 [default|default_server|
609 [backlog=число |
610 rcvbuf=размер |
611 sndbuf=размер |
612 accept_filter=фильтр |
613 deferred |
614 bind |
615 ipv6only=[on|off] |
616 ssl]]
617 </value></syntax>
618 <default>listen *:80 | *:8000</default>
619 <context>server</context>
620
621 <para>
622 Директива задаёт адрес и порт, на которых сервер принимает запросы.
623 Можно указать только адрес или только порт, кроме того, адрес может
624 быть именем сервера, например:
625 <example>
626 listen 127.0.0.1:8000;
627 listen 127.0.0.1;
628 listen 8000;
629 listen *:8000;
630 listen localhost:8000;
631 </example>
632 адреса IPv6 (0.7.36) задаются в квадратных скобках:
633 <example>
634 listen [::]:8000;
635 listen [fe80::1];
636 </example>
637 </para>
638
639 <para>
640 Если указан только адрес, то используется порт 80.
641 </para>
642
643 <para>
644 Если директива не указана, то используется порт *:80, если nginx работает
645 с правами пользователя root, или порт *:8000.
646 </para>
647
648 <para>
649 Если у директивы есть параметр default, то сервер, в котором описана
650 эта директива, будет сервером по умолчанию для указанной пары адрес:порт.
651 Если же директив с параметром default нет, то сервером по умолчанию
652 будет первый сервер, в котором описана пара адрес:порт.
653 Начиная с версии 0.8.21, можно использовать параметр default_server.
654 </para>
655
656 <para>
657 В директиве listen с параметром default можно также указать несколько
658 параметров, специфичных для системных вызовов listen(2) и bind(2).
659 Начиная с версии 0.8.21, эти параметры можно задать в любой директиве
660 listen, но только один раз для указанной пары адрес:порт.
661 <list type="bullet">
662
663 <listitem>
664 backlog=число — задаёт параметр backlog в вызове listen(2).
665 По умолчанию backlog равен -1 для FreeBSD и 511 для всех остальных
666 платформ.
667 </listitem>
668
669 <listitem>
670 rcvbuf=размер — задаёт параметр SO_RCVBUF для слушающего сокета.
671 </listitem>
672
673 <listitem>
674 sndbuf=размер — задаёт параметр SO_SNDBUF для слушающего сокета.
675 </listitem>
676
677 <listitem>
678 accept_filter=фильтр — задаёт название accept-фильтра.
679 Работает только на FreeBSD, можно использовать два фильтра — dataready
680 и httpready.
681 По сигналу -HUP accept-фильтр можно менять только в последних
682 версиях FreeBSD, начиная с 6.0, 5.4-STABLE и 4.11-STABLE.
683 </listitem>
684
685 <listitem>
686 deferred — указывает использовать отложенный accept(2) на Linux
687 с помощью опции TCP_DEFER_ACCEPT.
688 </listitem>
689
690 <listitem>
691 bind — указывает, что для данной пары адрес:порт нужно делать bind(2)
692 отдельно.
693 Дело в том, что если описаны несколько директив listen с одинаковым портом,
694 но разными адресами и одна из директив listen слушает на всех адресах
695 для данного порта (*:порт), то nginx сделает bind(2) только на *:порт.
696 Необходимо учитывать, что в этом случае для определения адреса, на которой
697 пришло соединение, делается системный вызов getsockname().
698 Если же используются параметры backlog, rcvbuf, sndbuf, accept_filter
699 или deferred, то для данной пары адрес:порт bind(2) всегда делается отдельно.
700 </listitem>
701
702 <listitem>
703 ipv6only — параметр (0.7.42) задаёт значение параметра IPV6_V6ONLY
704 для слушающего сокета.
705 Установить этот параметр можно только один раз на старте.
706 </listitem>
707
708 <listitem>
709 ssl — параметр (0.7.14) не имеет отношения к системным вызовам
710 listen(2) и bind(2), а позволяет указать, что все соединения,
711 принимаемые на этом порту, должны работать в режиме SSL.
712 Это позволяет задать компактную конфигурацию для сервера,
713 работающего сразу в двух режимах — HTTP и HTTPS.
714 <example>
715 listen 80;
716 listen 443 default ssl;
717 </example>
718 </listitem>
719
720 </list>
721 </para>
722
723 <para>
724 Пример использования параметров:
725 <example>
726 listen 127.0.0.1 default accept_filter=dataready backlog=1024;
727 </example>
728 </para>
729
730 </directive>
731
732
733 <directive name="location">
734 <syntax>location [<value>=|~|~*|^~|@</value>] <value>/uri/</value>
735 { ... }</syntax>
736 <default>нет</default>
737 <context>server</context>
738
739 <para>
740 Директива устанавливает конфигурацию в зависимости от URI запроса.
741 location можно задать обычной строкой или регулярным выражением.
742 Регулярные выражения задаются префиксом "~*" — без учёта регистра
743 символов, и "~" — с учётом.
744 Для определения соответствия location'а и запроса
745 сначала проверяются location'ы, заданные обычными строками.
746 Среди них ищется максимальное совпадение.
747 Затем проверяются регулярные выражения.
748 В отличие от обычных строк, они не сортируются, а проверяются в порядке
749 их следования в конфигурационном файле.
750 Проверка регулярных выражений прекращается после первого же совпадения.
751 Если совпадение с регулярным выражением не найдено, то используется
752 конфигурация максимально совпавшего location'а.
753 </para>
754
755 <para>
756 Для операционных систем, не чувствительных к регистру символов, таких
757 как Mac OS X и Cygwin, проверка обычных строк делается без учёта
758 регистра (0.7.7).
759 Однако, сравнение ограничено только однобайтными locale'ями.
760 </para>
761
762 <para>
763 Регулярное выражение может содержать выделения (0.7.40), которые
764 могут затем использоваться в других директивах.
765 </para>
766
767 <para>
768 Если нужно запретить проверку регулярных выражений после проверки
769 обычных строк, то это можно сделать с помощью префикса "^~".
770 Если у максимально совпавшего location'а есть этот префикс, то
771 регулярные выражения не проверяются.
772 </para>
773
774 <para>
775 Кроме того, с помощью префикса "=" можно задать точное совпадение
776 URI и location. При совпадении поиск сразу же прекращается, так как
777 дальше искать не имеет смысла. Например, если запрос "/" очень частый,
778 то указав "location = /", можно ускорить обработку этого запроса,
779 так как поиск location прекратится после первого же сравнения.
780 </para>
781
782 <para>
783 В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с обычным location'ом
784 без префиксов "=" и "^~", то поиск тоже сразу же прекращается и
785 регулярные выражения также не проверяются.
786 </para>
787
788 <para>
789 Проиллюстрируем вышесказанное примером:
790 <example>
791 location = / {
792 [ конфигурация A ]
793 }
794
795 location / {
796 [ конфигурация B ]
797 }
798
799 location ^~ /images/ {
800 [ конфигурация C ]
801 }
802
803 location ~* \.(gif|jpg|jpeg)$ {
804 [ конфигурация D ]
805 }
806 </example>
807 Для запроса "/" будет выбрана конфигурация A,
808 для запроса "/documents/document.html" — конфигурация B,
809 для запроса "/images/1.gif" — конфигурация C,
810 для запроса "/documents/1.jpg" — конфигурация D.
811 </para>
812
813 <para>
814 Префикс "@" задаёт именованный location. Такой location не используется
815 при обычной обработке запросов, а предназначен только для перенаправления
816 в него запросов.
817 </para>
818
819 </directive>
820
821
822 <directive name="log_not_found">
823 <syntax>log_not_found <value>[on|off]</value></syntax>
824 <default>log_not_found on</default>
825 <context>http, server, location</context>
826
827 <para>
828 Директива разрешает или запрещает записывать в error_log
829 ошибки о том, что файл не найден.
830 </para>
831
832 </directive>
833
834
835 <directive name="log_subrequest">
836 <syntax>log_subrequest <value>[on|off]</value></syntax>
837 <default>log_subrequest off</default>
838 <context>http, server, location</context>
839
840 <para>
841 Директива разрешает или запрещает записывать в <link doc="ngx_http_log_module.xml#access_log">access_log</link>
842 подзапросы.
843 </para>
844
845 </directive>
846
847
848 <directive name="merge_slashes">
849 <syntax>merge_slashes <value>[on|off]</value></syntax>
850 <default>merge_slashes on</default>
851 <context>http, server</context>
852
853 <para>
854 Директива разрешает или запрещает объединять в URI два и более слэшей в один.
855 </para>
856
857 <para>
858 Необходимо иметь ввиду, что это объединение необходимо для корректной
859 проверки location'ов и регулярных выражений.
860 Например, запрос "//scripts/one.php" не попадает в
861 <example>
862 location /scripts/ {
863 ...
864 }
865 </example>
866 и может быть обслужен как статический файл,
867 поэтому он приводится в "/scripts/one.php".
868 </para>
869
870 <para>
871 Выключение объединения может понадобиться, если в URI используются имена,
872 закодированные методом base64, который использует символ "/".
873 Но по соображениям безопасности лучше избегать выключения объединения.
874 </para>
875
876 <para>
877 Если директива указана на уровне server в сервере по умолчанию,
878 то её значение распространяется на все виртуальные сервера, слушающие
879 на том же адресе и порту.
880 </para>
881
882 </directive>
883
884
885 <directive name="msie_padding">
886 <syntax>msie_padding <value>[on|off]</value></syntax>
887 <default>msie_padding on</default>
888 <context>http, server, location</context>
889
890 <para>
891 Директива разрешает или запрещает добавлять в ответы для MSIE
892 со статусом больше 400
893 комментарий для увеличения размера ответа до 512 байт.
894 </para>
895
896 </directive>
897
898
899 <directive name="msie_refresh">
900 <syntax>msie_refresh <value>[on|off]</value></syntax>
901 <default>msie_refresh off</default>
902 <context>http, server, location</context>
903
904 <para>
905 Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо
906 редиректов.
907 </para>
908
909 </directive>
910
911
912 <directive name="open_file_cache">
913 <syntax>open_file_cache <value>max=N [inactive=время]|off</value>
914 </syntax>
915 <default>open_file_cache off</default>
916 <context>http, server, location</context>
917
918 <para>
919 Директива задаёт кэш, в котором могут хранится
920 <list type="bullet">
921
922 <listitem>
923 дескрипторы открытых файлов, информация об их размерах и времени модификации;
924 </listitem>
925
926 <listitem>
927 информация о существовании каталогов;
928 </listitem>
929
930 <listitem>
931 информация об ошибках поиска файла — нет файла, нет прав на чтение
932 и тому подобное. Кэширование ошибок нужно разрешить директивой
933 <link id="open_file_cache_errors"/>.
934 </listitem>
935
936 </list>
937 </para>
938
939 <para>
940 Параметры директивы:
941 <list type="bullet">
942
943 <listitem>
944 max — задаёт максимальное число элементов в кэше;
945 при переполнении кэша удаляются наиболее давно не используемые элементы (LRU);
946 </listitem>
947
948 <listitem>
949 inactive — задаёт время, после которого элемент кэша удаляется,
950 если к нему не было обращений в течение этого времени;
951 по умолчанию 60 секунд;
952 </listitem>
953
954 <listitem>
955 off — запрещает кэш.
956 </listitem>
957
958 </list>
959 </para>
960
961 <para>
962 Пример использования:
963 <example>
964 open_file_cache max=1000 inactive=20s;
965 open_file_cache_valid 30s;
966 open_file_cache_min_uses 2;
967 open_file_cache_errors on;
968 </example>
969 </para>
970
971 </directive>
972
973
974 <directive name="open_file_cache_errors">
975 <syntax>open_file_cache_errors <value>on|off</value></syntax>
976 <default>open_file_cache_errors off</default>
977 <context>http, server, location</context>
978
979 <para>
980 Директива определяет, кэшировать или нет ошибки поиска файлов в
981 <link id="open_file_cache"/>.
982 </para>
983
984 </directive>
985
986
987 <directive name="open_file_cache_min_uses">
988 <syntax>open_file_cache_min_uses <value>число</value></syntax>
989 <default>open_file_cache_min_uses 1</default>
990 <context>http, server, location</context>
991
992 <para>
993 Директива определяет минимальное число использований файла в течение
994 времени, заданного параметром inactive в директиве
995 <link id="open_file_cache"/>, после которого дескриптор файла
996 будет оставаться открытым в кэше.
997 </para>
998
999 </directive>
1000
1001
1002 <directive name="open_file_cache_valid">
1003 <syntax>open_file_cache_valid <value>время</value></syntax>
1004 <default>open_file_cache_valid 60</default>
1005 <context>http, server, location</context>
1006
1007 <para>
1008 Директива определяет, через какое время нужно проверять актуальность
1009 информации об элементе в <link id="open_file_cache"/>.
1010
1011 </para>
1012
1013 </directive>
1014
1015
1016 <directive name="optimize_server_names">
1017 <syntax>optimize_server_names <value>[on|off]</value></syntax>
1018 <default>optimize_server_names on</default>
1019 <context>http, server</context>
1020
1021 <para>
1022 Устаревшая директива.
1023 </para>
1024
1025 <para>
1026 Директива разрешает или запрещает оптимизировать проверку имени хоста
1027 в name-based виртуальных серверах.
1028 Проверка в частности влияет на имя хоста, используемого в редиректах.
1029 Если оптимизация разрешена и все name-based сервера, слушающие на одной
1030 паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения
1031 запроса имена не проверяются и в редиректах используется первое имя сервера.
1032 Если в редиректе нужно использовать имя хоста, переданное клиентом,
1033 то оптимизацию нужно выключить.
1034 </para>
1035
1036 </directive>
1037
1038
1039 <directive name="port_in_redirect">
1040 <syntax>port_in_redirect <value>[on|off]</value></syntax>
1041 <default>port_in_redirect on</default>
1042 <context>http, server, location</context>
1043
1044 <para>
1045 Директива разрешает или запрещает указывать порт в редиректах,
1046 выдаваемых nginx'ом.
1047 </para>
1048
1049 </directive>
1050
1051
1052 <directive name="read_ahead">
1053 <syntax>read_ahead <value>размер</value></syntax>
1054 <default>read_ahead 0</default>
1055 <context>http, server, location</context>
1056
1057 <para>
1058 Директива задаёт ядру размер предчтения при работе с файлами.
1059 Под Линуксом используется системный вызов
1060 <example>
1061 posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL);
1062 </example>
1063 поэтому размер игнорируется.
1064 </para>
1065
1066 <para>
1067 Под FreeBSD используется fcntl(O_READAHEAD, размер), появившийся
1068 во FreeBSD-9 CURRENT. Для FreeBSD 7 нужно установить
1069 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">патч</link>.
1070 </para>
1071
1072 </directive>
1073
1074
1075 <directive name="recursive_error_pages">
1076 <syntax>recursive_error_pages <value>[on|off]</value></syntax>
1077 <default>recursive_error_pages off</default>
1078 <context>http, server, location</context>
1079
1080 <para>
1081 Директива разрешает или запрещает делать несколько перенаправлений через
1082 директиву <link id="error_page"/>.
1083 </para>
1084
1085 </directive>
1086
1087
1088 <directive name="reset_timedout_connection">
1089 <syntax>reset_timedout_connection <value>[on|off]</value></syntax>
1090 <default>reset_timedout_connection off</default>
1091 <context>http, server, location</context>
1092
1093 <para>
1094 Директива разрешает или запрещает сбрасывать соединение по таймауту.
1095 Сброс делается следующим образом — перед закрытием сокета для него
1096 ставится опция SO_LINGER с таймаутом 0. После чего при закрытии сокета
1097 клиенту отсылается пакет RST, а всё память, связанная с этим сокетом,
1098 освобождается. Это позволяет избежать длительного нахождения уже закрытого
1099 сокета в состоянии FIN_WAIT1 с заполненными буферами.
1100 </para>
1101
1102 <para>
1103 Необходимо отметить, что соединения, находящиеся в состоянии keepalive,
1104 по истечении таймаута закрываются обычным образом.
1105 </para>
1106
1107 </directive>
1108
1109
1110 <directive name="resolver">
1111 <syntax>resolver <value>адрес</value></syntax>
1112 <default>нет</default>
1113 <context>http, server, location</context>
1114
1115 <para>
1116 Директива задаёт адрес name-сервера, например:
1117 <example>
1118 resolver 127.0.0.1;
1119 </example>
1120 </para>
1121
1122 </directive>
1123
1124
1125 <directive name="resolver_timeout">
1126 <syntax>resolver_timeout <value>время</value></syntax>
1127 <default>resolver_timeout 30s</default>
1128 <context>http, server, location</context>
1129
1130 <para>
1131 Директива задаёт таймаут для определения имени, например:
1132 <example>
1133 resolver_timeout 5s;
1134 </example>
1135 </para>
1136
1137 </directive>
1138
1139
1140 <directive name="root">
1141 <syntax>root <value>путь</value></syntax>
1142 <default>root html</default>
1143 <context>http, server, location, if в location</context>
1144
1145 <para>
1146 Директива задаёт корневой каталог для запросов.
1147 Например, при такой конфигурации
1148 <example>
1149 location /i/ {
1150 root /data/w3;
1151 }
1152 </example>
1153 на запрос "/i/top.gif" будет отдан файл "/data/w3/i/top.gif".
1154 </para>
1155
1156 <para>
1157 В значении пути можно использовать переменные.
1158 </para>
1159
1160 <para>
1161 Путь к файлу формируется как простое добавление URI к значению директивы root.
1162 Если же необходима модификация URI, то нужно воспользоваться директивой
1163 <link id="alias"/>.
1164 </para>
1165
1166 </directive>
1167
1168
1169 <directive name="satisfy">
1170 <syntax>satisfy <value>all|any</value></syntax>
1171 <default>satisfy all</default>
1172 <context>location</context>
1173
1174 <para>
1175 Директива разрешает доступ при хотя бы одной успешной проверке,
1176 выполненной модулями <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
1177 или <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>:
1178 <example>
1179 location / {
1180 satisfy any;
1181
1182 allow 192.168.1.0/32;
1183 deny all;
1184
1185 auth_basic "closed site";
1186 auth_basic_user_file conf/htpasswd;
1187 }
1188 </example>
1189 </para>
1190
1191 </directive>
1192
1193
1194 <directive name="satisfy_any">
1195 <syntax>satisfy_any <value>on|off</value></syntax>
1196 <default>satisfy_any off</default>
1197 <context>location</context>
1198
1199 <para>
1200 Директива переименована в директиву <link id="satisfy"/>.
1201 </para>
1202
1203 </directive>
1204
1205
1206 <directive name="send_timeout">
1207 <syntax>send_timeout <value>время</value></syntax>
1208 <default>send_timeout 60</default>
1209 <context>http, server, location</context>
1210
1211 <para>
1212 Директива задаёт таймаут при передаче ответа клиенту.
1213 Таймаут устанавливается не на всю передачу ответа,
1214 а только между двумя операциями записями.
1215 Если по истечении этого времени клиент ничего не примет,
1216 то nginx закрывает соединение.
1217 </para>
1218
1219 </directive>
1220
1221
1222 <directive name="sendfile">
1223 <syntax>sendfile <value>[on|off]</value></syntax>
1224 <default>sendfile off</default>
1225 <context>http, server, location</context>
1226
1227 <para>
1228 Директива разрешает или запрещает использовать sendfile().
1229 </para>
1230
1231 </directive>
1232
1233
1234 <directive name="server">
1235 <syntax>server { ... }</syntax>
1236 <default>нет</default>
1237 <context>http</context>
1238
1239 <para>
1240 Директива задаёт конфигурацию для виртуального сервера.
1241 Чёткого разделения виртуальных серверов ip-based (на основании ip-адреса)
1242 и name-based (на основании имени, передаваемого в строке "Host"
1243 заголовка запроса), нет.
1244 Вместо этого директивами <link id="listen"/> описываются все адреса
1245 и порты, на которых нужно принимать соединения для этого сервера,
1246 и в директиве <link id="server_name"/> указываются все имена серверов.
1247 Пример конфигурации описан в <link doc="../virtual_hosts.xml">
1248 настройке виртуальных серверов</link>.
1249 </para>
1250
1251 </directive>
1252
1253
1254 <directive name="server_name">
1255 <syntax>server_name <value>имя [...]</value></syntax>
1256 <default>server_name hostname</default>
1257 <context>server</context>
1258
1259 <para>
1260 Директива задаёт имена виртуального сервера, например:
1261 <example>
1262 server {
1263 server_name example.com www.example.com;
1264 }
1265 </example>
1266 </para>
1267
1268 <para>
1269 Первое имя становится основным именем сервера.
1270 По умолчанию используется имя машины (hostname).
1271 В именах серверов можно использовать "*" для замены первой или последней
1272 части имени:
1273 <example>
1274 server {
1275 server_name example.com *.example.com www.example.*;
1276 }
1277 </example>
1278 </para>
1279
1280 <para>
1281 Два первых вышеприведённых имени можно объединить в одно:
1282 <example>
1283 server {
1284 server_name .example.com;
1285 }
1286 </example>
1287 </para>
1288
1289 <para>
1290 Кроме того, в качестве имени сервера можно использовать регулярное
1291 выражение, указав перед ним "~":
1292 <example>
1293 server {
1294 server_name www.example.com ~^www\d+\.example\.com$;
1295 }
1296 </example>
1297 </para>
1298
1299 <para>
1300 Регулярное выражение может содержать выделения (0.7.40), которые
1301 могут затем использоваться в других директивах:
1302 <example>
1303 server {
1304 server_name ~^(www\.)?(.+)$;
1305
1306 location / {
1307 root /sites/$2;
1308 }
1309 }
1310
1311 server {
1312 server_name _;
1313
1314 location / {
1315 root /sites/default;
1316 }
1317 }
1318 </example>
1319 </para>
1320
1321 <para>
1322 Начиная с 0.8.25, именованные выделения в регулярном выражении создают
1323 переменные, которые могут затем использоваться в других директивах:
1324 <example>
1325 server {
1326 server_name ~^(www\.)?(<emphasis>?&lt;domain&gt;</emphasis>.+)$;
1327
1328 location / {
1329 root /sites/<emphasis>$domain</emphasis>;
1330 }
1331 }
1332
1333 server {
1334 server_name _;
1335
1336 location / {
1337 root /sites/default;
1338 }
1339 }
1340 </example>
1341 </para>
1342
1343 <para>
1344 Начиная с 0.7.11, можно использовать пустое имя "":
1345 <example>
1346 server {
1347 server_name www.example.com "";
1348 }
1349 </example>
1350 что позволяет обрабатывать запросы без строки "Host" в заголовке запроса
1351 в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт.
1352 </para>
1353
1354 <para>
1355 Порядок проверки имён следующий:
1356 <list type="bullet">
1357
1358 <listitem>
1359 полные имена,
1360 </listitem>
1361
1362 <listitem>
1363 имена с маской в начале имени — *.example.com,
1364 </listitem>
1365
1366 <listitem>
1367 имена с маской в конце имени — mail.*,
1368 </listitem>
1369
1370 <listitem>
1371 регулярные выражения.
1372 </listitem>
1373
1374 </list>
1375 </para>
1376
1377 </directive>
1378
1379
1380 <directive name="server_name_in_redirect">
1381 <syntax>server_name_in_redirect <value>[on|off]</value></syntax>
1382 <default>server_name_in_redirect on</default>
1383 <context>http, server, location</context>
1384
1385 <para>
1386 Директива разрешает или запрещает использовать в редиректах, выдаваемых
1387 nginx'ом, основное имя сервера, задаваемое директивой
1388 <link id="server_name"/>.
1389 Если использование основного имени запрещено, то используется имя,
1390 указанного в строке "Host" в заголовке запроса.
1391 Если же этой строки нет, то используется IP-адрес сервера.
1392 </para>
1393
1394 </directive>
1395
1396
1397 <directive name="server_names_hash_max_size">
1398 <syntax>server_names_hash_max_size <value>число</value></syntax>
1399 <default>server_names_hash_max_size 512</default>
1400 <context>http</context>
1401
1402 <para>
1403 Директива задаёт максимальный размер хэш-таблиц имён серверов.
1404 Подробнее смотри в <link doc="../hash.xml">описании
1405 настройки хэшей</link>.
1406 </para>
1407
1408 </directive>
1409
1410
1411 <directive name="server_names_hash_bucket_size">
1412 <syntax>server_names_hash_bucket_size <value>число</value></syntax>
1413 <default>server_names_hash_bucket_size 32/64/128</default>
1414 <context>http</context>
1415
1416 <para>
1417 Директива задаёт размер корзины в хэш-таблицах имён серверов.
1418 Значение по умолчанию зависит от размера строки кэша процессора.
1419 Подробнее смотри в <link doc="../hash.xml">описании
1420 настройки хэшей</link>.
1421 </para>
1422
1423 </directive>
1424
1425
1426 <directive name="server_tokens">
1427 <syntax>server_tokens <value>[on|off]</value></syntax>
1428 <default>server_tokens on</default>
1429 <context>http, server, location</context>
1430
1431 <para>
1432 Директива разрешает или запрещает выдавать версию nginx'а
1433 в сообщениях об ошибках и в строке заголовка ответа "Server".
1434 </para>
1435
1436 </directive>
1437
1438
1439 <directive name="tcp_nodelay">
1440 <syntax>tcp_nodelay <value>[on|off]</value></syntax>
1441 <default>tcp_nodelay on</default>
1442 <context>http, server, location</context>
1443
1444 <para>
1445 Директива разрешает или запрещает использовать опцию TCP_NODELAY.
1446 Опция включаются только при переходе соединения в состояние keep-alive.
1447 </para>
1448
1449 </directive>
1450
1451
1452 <directive name="tcp_nopush">
1453 <syntax>tcp_nopush <value>[on|off]</value></syntax>
1454 <default>tcp_nopush off</default>
1455 <context>http, server, location</context>
1456
1457 <para>
1458 Директива разрешает или запрещает использовать опции
1459 TCP_NOPUSH во FreeBSD или TCP_CORK в Linux.
1460 Опции включаются только при использовании <link id="sendfile"/>.
1461 Включение опции позволяет
1462 <list type="bullet">
1463
1464 <listitem>
1465 передавать заголовок ответа и начало файла в одном пакете в Linux
1466 и во FreeBSD 4.x;
1467 </listitem>
1468
1469 <listitem>
1470 передавать файл в полных пакетах.
1471 </listitem>
1472
1473 </list>
1474 </para>
1475
1476 </directive>
1477
1478
1479 <directive name="try_files">
1480 <syntax>try_files <value>файл [файл ...] (uri|=код)</value></syntax>
1481 <default>нет</default>
1482 <context>location</context>
1483
1484 <para>
1485 Директива проверяет существование файлов в заданном порядке
1486 и использует для обработки запроса первый найденный файл, причём
1487 обработка делается в контексте этого же location'а.
1488 С помощью слэша в конце имени можно задать проверку существования
1489 каталога, например, так — "$uri/".
1490 В случае, если ни один файл не найден, то делается внутренний редирект
1491 на последний параметр.
1492 Последний параметр может быть кодом (0.7.51):
1493 <example>
1494 location / {
1495 try_files $uri $uri/index.html $uri.html =404;
1496 }
1497 </example>
1498 </para>
1499
1500 <para>
1501 Пример использования при проксировании Mongrel:
1502 <example>
1503 location / {
1504 try_files /system/maintenance.html
1505 $uri $uri/index.html $uri.html
1506 @mongrel;
1507 }
1508
1509 location @mongrel {
1510 proxy_pass http://mongrel;
1511 }
1512 </example>
1513 </para>
1514
1515 <para>
1516 Пример использования вместе с Drupal/FastCGI:
1517 <example>
1518 location / {
1519 try_files $uri $uri/ @drupal;
1520 }
1521
1522 location ~ \.php$ {
1523 try_files $uri @drupal;
1524
1525 fastcgi_pass ...;
1526
1527 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1528 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
1529 fastcgi_param QUERY_STRING $args;
1530
1531 ... прочие fastcgi_param
1532 }
1533
1534 location @drupal {
1535 fastcgi_pass ...;
1536
1537 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1538 fastcgi_param SCRIPT_NAME /index.php;
1539 fastcgi_param QUERY_STRING q=$uri&amp;$args;
1540
1541 ... прочие fastcgi_param
1542 }
1543 </example>
1544 В этом примере директива try_files
1545 <example>
1546 location / {
1547 try_files $uri $uri/ @drupal;
1548 }
1549 </example>
1550 аналогична директивам
1551 <example>
1552 location / {
1553 error_page 404 = @drupal;
1554 log_not_found off;
1555 }
1556 </example>
1557 А здесь
1558 <example>
1559 location ~ \.php$ {
1560 try_files $uri @drupal;
1561
1562 fastcgi_pass ...;
1563
1564 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1565
1566 ...
1567 }
1568 </example>
1569 try_files тестирует существование PHP-файла,
1570 прежде чем передать запрос FastCGI-серверу.
1571 </para>
1572
1573 <para>
1574 Пример использования вместе с Wordpress и Joomla:
1575 <example>
1576 location / {
1577 try_files $uri $uri/ @wordpress;
1578 }
1579
1580 location ~ \.php$ {
1581 try_files $uri @wordpress;
1582
1583 fastcgi_pass ...;
1584
1585 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1586 ... прочие fastcgi_param
1587 }
1588
1589 location @wordpress {
1590 fastcgi_pass ...;
1591
1592 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1593 ... прочие fastcgi_param
1594 }
1595 </example>
1596 </para>
1597
1598 </directive>
1599
1600
1601 <directive name="types">
1602 <syntax>types <value>{ ... }</value></syntax>
1603 <default>see below</default>
1604 <context>http, server, location</context>
1605
1606 <para>
1607 Директива задаёт соответствие расширения и MIME-типов ответов.
1608 Одному MIME-типу может соответствовать несколько расширений.
1609 По умолчанию используется такие соответствия:
1610 <example>
1611 types {
1612 text/html html;
1613 image/gif gif;
1614 image/jpeg jpg;
1615 }
1616 </example>
1617 </para>
1618
1619 <para>
1620 Достаточно полная таблица соответствий входит в дистрибутив
1621 и находится в файле conf/mime.types.
1622 </para>
1623
1624 <para>
1625 Для того, чтобы для определённого location'а для всех ответов выдавался
1626 MIME-тип "application/octet-stream", можно использовать следующее:
1627 <example>
1628 location /download/ {
1629 types { }
1630 default_type application/octet-stream;
1631 }
1632 </example>
1633 </para>
1634
1635 </directive>
1636
1637
1638 <directive name="underscores_in_headers">
1639 <syntax>underscores_in_headers <value>[on|off]</value></syntax>
1640 <default>underscores_in_headers off</default>
1641 <context>http, server</context>
1642
1643 <para>
1644 Директива разрешает или запрещает использование символов подчёркивания
1645 в строках заголовка запроса клиента.
1646 </para>
1647
1648 </directive>
1649
1650 </section>
1651
1652
1653 <section name="Встроенные переменные" id="variables">
1654
1655 <para>
1656 Модуль ngx_http_core_module поддерживает встроенные переменные, имена
1657 которых совпадают с именами переменных в Apache.
1658 Прежде всего, это переменные, представляющие из себя строки заголовка
1659 запроса клиента, например, $http_user_agent, $http_cookie
1660 и тому подобное. Кроме того, есть и другие переменные:
1661 <list type="bullet">
1662
1663 <listitem>
1664 $args, эта переменная равна аргументам в строке запроса;
1665 </listitem>
1666
1667 <listitem>
1668 $arg_<value>name</value>, эта переменная равна аргументу <value>name</value>
1669 в строке запроса;
1670 </listitem>
1671
1672 <listitem>
1673 $binary_remote_addr, эта переменная равна адресу клиента в бинарном виде,
1674 длина её значения всегда 4 байта;
1675 </listitem>
1676
1677 <listitem>
1678 $content_length, эта переменная равна строке "Content-Length" в заголовке
1679 запроса;
1680 </listitem>
1681
1682 <listitem>
1683 $content_type, эта переменная равна строке "Content-Type" в заголовке запроса;
1684 </listitem>
1685
1686 <listitem>
1687 $cookie_<value>name</value>, эта переменная равна cookie <value>name</value>;
1688 </listitem>
1689
1690 <listitem>
1691 $document_root, эта переменная равна значению директивы root для
1692 текущего запроса;
1693 </listitem>
1694
1695 <listitem>
1696 $document_uri, то же самое, что и $uri;
1697 </listitem>
1698
1699 <listitem>
1700 $host, эта переменная равна строке "Host" в заголовке запроса
1701 или имени сервера, на который пришёл запрос, если этой строки нет;
1702 </listitem>
1703
1704 <listitem>
1705 $hostname, эта переменная равна имени хоста;
1706 </listitem>
1707
1708 <listitem>
1709 $http_<value>name</value>, эта переменная равна строке <value>name</value>
1710 в заголовке запроса;
1711 </listitem>
1712
1713 <listitem>
1714 $is_args, эта переменная равна "?", если в строке запроса есть аргументы,
1715 и пустой строке, если их нет;
1716 </listitem>
1717
1718 <listitem>
1719 $limit_rate, эта переменная позволяет установить ограничение
1720 скорости соединения;
1721 </listitem>
1722
1723 <listitem>
1724 $pid, эта переменная равна номеру рабочего процесса;
1725 </listitem>
1726
1727 <listitem>
1728 $request_method, эта переменная равна методу запроса,
1729 обычно это "GET" или "POST";
1730 </listitem>
1731
1732 <listitem>
1733 $remote_addr, эта переменная равна адресу клиента;
1734 </listitem>
1735
1736 <listitem>
1737 $remote_port, эта переменная равна порту клиента;
1738 </listitem>
1739
1740 <listitem>
1741 $remote_user, эта переменная равна имени пользователя, используемого
1742 в Basic аутентификации;
1743 </listitem>
1744
1745 <listitem>
1746 $realpath_root, эта переменная равна значению директивы root для
1747 текущего запроса, при этом все символические ссылки преобразованы
1748 в реальные путь;
1749 </listitem>
1750
1751 <listitem>
1752 $request_filename, эта переменная равна пути к файлу для текущего
1753 запроса, формируемому из директив root или alias и URI запроса;
1754 </listitem>
1755
1756 <listitem>
1757 $request_body, эта переменная содержит тело запроса.
1758 Значение переменной появляется в location'ах, обрабатываемых директивами
1759 <link doc="ngx_http_proxy_module.xml#proxy_pass">proxy_pass</link>
1760 и <link doc="ngx_http_fastcgi_module.xml#fastcgi_pass">fastcgi_pass</link>.
1761 </listitem>
1762
1763 <listitem>
1764 $request_body_file, эта переменная равна имени временного файла, в котором
1765 хранится тело запроса.
1766 По завершению работы файл необходимо удалить.
1767 Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно
1768 указать <link doc="ngx_http_core_module.xml#client_body_in_file_only">client_body_in_file_only on</link>.
1769 При передаче имени в проксированном запросе или в запросе к FastCGI-серверу
1770 следует запретить передачу самого тела директивами
1771 "proxy_pass_request_body off" или
1772 "fastcgi_pass_request_body off" соответственно.
1773 </listitem>
1774
1775 <listitem>
1776 $request_uri, эта переменная равна полному первоначальному URI вместе
1777 с аргументами;
1778 </listitem>
1779
1780 <listitem>
1781 $query_string, то же самое, что и $args;
1782 </listitem>
1783
1784 <listitem>
1785 $scheme, эта переменная равна схеме запроса — "http" или "https";
1786 </listitem>
1787
1788 <listitem>
1789 $server_protocol, эта переменная равна протоколу запроса,
1790 обычно это "HTTP/1.0" или "HTTP/1.1";
1791 </listitem>
1792
1793 <listitem>
1794 $server_addr, эта переменная равна адресу сервера, на который пришёл запрос.
1795 Как правило, для получения значения этой переменной делается один системный
1796 вызов. Для того, чтобы избежать системного вызова, нужно указывать
1797 адреса в директивах listen и использовать параметр bind;
1798 </listitem>
1799
1800 <listitem>
1801 $server_name, эта переменная равна имени сервера, на который пришёл запрос;
1802 </listitem>
1803
1804 <listitem>
1805 $server_port, эта переменная равна порту сервера, на который пришёл запрос;
1806 </listitem>
1807
1808 <listitem>
1809 $uri, эта переменная равна текущему URI в запросе, он
1810 может отличаться от первоначального, например, при внутренних редиректах
1811 или при использовании индексных файлов.
1812 </listitem>
1813
1814 </list>
1815 </para>
1816
1817 </section>
1818
1819 </module>