Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_core_module.xml @ 253:ff1e139a8c98

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bring the ngx_http_core_module documentation up to date.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 19 Dec 2011 13:10:05 +0000
parents bfe3eff81d04
children 945d7299c26c
comparison
equal deleted inserted replaced
252:6f710464be38 253:ff1e139a8c98
1 <?xml version="1.0"?> 1 <?xml version="1.0"?>
2 2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4 4
5 <module name="Директивы модуля ngx_http_core_module" 5 <module name="Модуль ngx_http_core_module"
6 link="/ru/docs/http/ngx_http_core_module.html" 6 link="/ru/docs/http/ngx_http_core_module.html"
7 lang="ru"> 7 lang="ru">
8 8
9 <section name="Директивы" id="directives"> 9 <section id="directives" name="Директивы">
10 10
11 <directive name="aio"> 11 <directive name="aio">
12 <syntax><value>[on|off|sendfile]</value></syntax> 12 <syntax>
13 <value>on</value> |
14 <value>off</value> |
15 <value>sendfile</value>
16 </syntax>
13 <default>off</default> 17 <default>off</default>
14 <context>http, server, location</context> 18 <context>http</context>
15 19 <context>server</context>
16 <para> 20 <context>location</context>
17 Директива (0.8.11) разрешает или запрещает использовать файловый AIO 21 <appeared-in>0.8.11</appeared-in>
22
23 <para>
24 Разрешает или запрещает использование файлового асинхронного ввода-вывода (AIO)
18 во FreeBSD и Linux. 25 во FreeBSD и Linux.
19 </para> 26 </para>
20 27
21 <para> 28 <para>
22 Во FreeBSD AIO можно использовать, начиная с FreeBSD 4.3 версии. 29 Во FreeBSD AIO можно использовать, начиная с FreeBSD&nbsp;4.3.
23 AIO можно собрать в ядре статически 30 AIO можно либо собрать в ядре статически:
24 <example> 31 <example>
25 options VFS_AIO 32 options VFS_AIO
26 </example> 33 </example>
27 или же подгрузить динамически 34 либо загрузить динамически через загружаемый модуль ядра:
28 <example> 35 <example>
29 kldload aio 36 kldload aio
30 </example> 37 </example>
31 </para> 38 </para>
32 39
33 <para> 40 <para>
34 Во FreeBSD 5 и 6 при включении AIO статически или динамически на стадии 41 В версиях FreeBSD 5 и 6 включение AIO статически или динамически
35 загрузки ядра вся сетевая подсистема будет использовать GiantLock, 42 на стадии загрузки ядра приводит к тому, что вся сетевая подсистема
36 что может негативно сказаться на производительности системы в целом. 43 будет использовать блокировку Giant, что может негативно сказаться на
37 Эта зависимость устранена во FreeBSD-6.4 STABLE от 2009 года и во FreeBSD 7. 44 производительности системы в целом.
38 Однако, начиная с FreeBSD 5.3, есть возможность включать AIO, 45 Это ограничение устранено во FreeBSD&nbsp;6.4-STABLE в 2009 году
39 не связывая сетевую подсистему GiantLock'ом — для этого модуль AIO 46 и во FreeBSD&nbsp;7.
40 нужно подгружать уже после загрузки ядра. 47 Однако, начиная с FreeBSD&nbsp;5.3 есть возможность включать AIO,
41 В этом случае в /var/log/messages появится сообщение 48 не связывая сетевую подсистему блокировкой Giant — для этого модуль
49 AIO нужно подгружать уже после загрузки ядра.
50 В этом случае в <path>/var/log/messages</path> появится следующее сообщение:
42 <example> 51 <example>
43 WARNING: Network stack Giant-free, but aio requires Giant. 52 WARNING: Network stack Giant-free, but aio requires Giant.
44 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0 53 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
45 </example> 54 </example>
46 которое можно смело проигнорировать. 55 которое можно смело проигнорировать.
47 <note> 56 <note>
48 Требование использовать GiantLock в AIO связано с тем, что FreeBSD 57 Требование использовать блокировку Giant в AIO связано с тем, что
49 поддерживает асинхронные вызовы aio_read()/aio_write() для работы с сокетами. 58 FreeBSD поддерживает асинхронные вызовы
50 Но поскольку nginx использует AIO только для работы с диском, то проблем 59 <c-func>aio_read</c-func>
51 не возникает. 60 и
61 <c-func>aio_write</c-func>
62 для работы с сокетами.
63 Но поскольку nginx использует AIO только для работы с диском,
64 то проблем не возникает.
52 </note> 65 </note>
53 </para> 66 </para>
54 67
55 <para> 68 <para>
56 Для работы AIO нужно выключить sendfile: 69 Для работы AIO нужно выключить
57 <example> 70 <link id="sendfile"/>:
58 location /video/ { 71 <example>
59 sendfile off; 72 location /video/ {
60 aio on; 73 sendfile off;
61 output_buffers 1 64k; 74 aio on;
62 } 75 output_buffers 1 64k;
63 </example> 76 }
64 </para> 77 </example>
65 78 </para>
66 <para> 79
67 Кроме того, начиная с FreeBSD 5.2.1 и nginx-0.8.12, AIO также можно 80 <para>
68 использовать для подгрузки данных для sendfile(): 81 Кроме того, начиная с FreeBSD&nbsp;5.2.1 и nginx&nbsp;0.8.12, AIO также можно
69 <example> 82 использовать для подгрузки данных для <c-func>sendfile</c-func>:
70 location /video/ { 83 <example>
71 sendfile on; 84 location /video/ {
72 tcp_nopush on; 85 sendfile on;
73 aio sendfile; 86 tcp_nopush on;
74 } 87 aio sendfile;
75 </example> 88 }
76 В такой конфигурации используется флаг SF_NODISKIO и sendfile() 89 </example>
77 не блокируется на диске, а сообщает об отсутствии данных в памяти, 90 В такой конфигурации функция <c-func>sendfile</c-func> вызывается с флагом
78 после чего nginx инициирует асинхронную подгрузку данных, 91 <c-def>SF_NODISKIO</c-def>, в результате она не блокируется на диске, а
79 читая только один байт. При этом ядро FreeBSD подгружает в память 92 сообщает об отсутствии данных в памяти, после чего nginx инициирует
80 первые 128K файла, однако при последующих чтениях файл подгружается 93 асинхронную подгрузку данных, читая только один байт.
81 частями только по 16K. Изменить это можно с помощью директивы 94 При этом ядро FreeBSD подгружает в память первые 128K байт файла, однако
95 при последующих чтениях файл подгружается частями только по 16K.
96 Изменить это можно с помощью директивы
82 <link id="read_ahead"/>. 97 <link id="read_ahead"/>.
83 </para> 98 </para>
84 99
85 <para> 100 <para>
86 В Linux AIO можно использовать, только начиная с версии ядра 2.6.22, 101 В Linux AIO можно использовать только начиная с версии ядра 2.6.22, и,
87 и, кроме того, ещё необходимо дополнительно включать 102 кроме того, ещё необходимо дополнительно включать
88 <link id="directio"/>, иначе чтение будет блокирующимся: 103 <link id="directio"/>,
89 <example> 104 иначе чтение будет блокирующимся:
90 location /video/ { 105 <example>
91 aio on; 106 location /video/ {
92 directio 512; 107 aio on;
93 output_buffers 1 128k; 108 directio 512;
94 } 109 output_buffers 1 128k;
95 </example> 110 }
96 </para> 111 </example>
97 112 </para>
98 <para> 113
99 Поскольку directio в Linux можно использовать только для чтения блоков, 114 <para>
100 выравненных по 512 байт (или 4К для XFS), то невыравненный конец файла 115 Поскольку
101 будет читаться блокировано. То же относится к запросам части ответа 116 <link id="directio"/>
102 byte-ranges и к запросам FLV не с начала файла: чтение невыровненных начала 117 в Linux можно использовать только для чтения блоков, выравненных
103 и конца ответа будет блокирующимся. sendfile выключать не нужно, так 118 на границу 512 байт (или 4К для XFS), то невыравненный конец файла
104 как при использовании directio он выключается сам. 119 будет читаться блокированно.
120 То же относится к запросам с указанием диапазона запрашиваемых байт
121 (byte-range requests) и к запросам FLV не с начала файла: чтение
122 невыравненных начала и конца ответа будет блокирующимся.
123 Явно выключать
124 <link id="sendfile"/>
125 не нужно, так как при использовании
126 <link id="directio"/>
127 он выключается автоматически.
105 </para> 128 </para>
106 129
107 </directive> 130 </directive>
108 131
109 132
110 <directive name="alias"> 133 <directive name="alias">
111 <syntax><value>путь</value></syntax> 134 <syntax><argument>путь</argument></syntax>
112 <default/> 135 <default/>
113 <context>location</context> 136 <context>location</context>
114 137
115 <para> 138 <para>
116 Директива задаёт замену для указанного location'а. 139 Задаёт замену для указанного location'а.
117 Например, при такой конфигурации 140 Например, при такой конфигурации
118 <example> 141 <example>
119 location /i/ { 142 location /i/ {
120 alias /data/w3/images/; 143 alias /data/w3/images/;
121 } 144 }
122 </example> 145 </example>
123 на запрос "/i/top.gif" будет отдан файл "/data/w3/images/top.gif". 146 на запрос
124 </para> 147 “<code>/i/top.gif</code>” будет отдан файл
125 148 <path>/data/w3/images/top.gif</path>.
126 <para> 149 </para>
127 В значении пути можно использовать переменные. 150
128 </para> 151 <para>
129 152 В значении аргумента <argument>путь</argument> можно использовать переменные,
130 <para> 153 кроме <var>$document_root</var> и <var>$realpath_root</var>.
131 Если директива alias используется внутри location'а, заданного 154 </para>
132 регулярным выражением, то регулярное выражение должно содержать выделения, 155
133 а директива alias — ссылки на эти выделения (0.7.40), например: 156 <para>
157 Если <code>alias</code> используется внутри location'а, заданного
158 регулярным выражением, то регулярное выражение должно содержать
159 выделения, а сам <code>alias</code> — ссылки на эти выделения
160 (0.7.40), например:
134 <example> 161 <example>
135 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { 162 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
136 alias /data/w3/images/$1; 163 alias /data/w3/images/$1;
137 } 164 }
138 </example> 165 </example>
139 </para> 166 </para>
140 167
141 <para> 168 <para>
142 Если location и последняя часть значения директивы совпадают: 169 Если location и последняя часть значения директивы совпадают:
143 <example> 170 <example>
144 location /images/ { 171 location /images/ {
145 alias /data/w3/images/; 172 alias /data/w3/images/;
146 } 173 }
147 </example> 174 </example>
148 то лучше воспользоваться директивой <link id="root"/>: 175 то лучше воспользоваться директивой
149 <example> 176 <link id="root"/>:
150 location /images/ { 177 <example>
151 root /data/w3; 178 location /images/ {
152 } 179 root /data/w3;
153 </example> 180 }
181 </example>
182 </para>
183
184 </directive>
185
186
187 <directive name="chunked_transfer_encoding">
188 <syntax><value>on</value> | <value>off</value></syntax>
189 <default>on</default>
190 <context>http</context>
191 <context>server</context>
192 <context>location</context>
193
194 <para>
195 Позволяет запретить формат передачи данных частями (chunked transfer
196 encoding) в HTTP/1.1.
197 Это может понадобиться при использовании программ, не поддерживающих
198 chunked encoding, несмотря на требования стандарта.
199 </para>
200
201 </directive>
202
203
204 <directive name="client_body_buffer_size">
205
206 <syntax><argument>размер</argument></syntax>
207 <default>8k|16k</default>
208 <context>http</context>
209 <context>server</context>
210 <context>location</context>
211
212 <para>
213 Задаёт размер буфера для чтения тела запроса клиента.
214 Если тело запроса больше заданного буфера,
215 то всё тело запроса или только его часть записывается во
216 <link id="client_body_temp_path">временный файл</link>.
217 По умолчанию размер одного буфера равен двум размерам страницы.
218 На x86, других 32-битных платформах и x86-64 это 8K.
219 На других 64-битных платформах это обычно 16K.
154 </para> 220 </para>
155 221
156 </directive> 222 </directive>
157 223
158 224
159 <directive name="client_body_in_file_only"> 225 <directive name="client_body_in_file_only">
160 <syntax><value>on|clean|off</value></syntax> 226 <syntax>
227 <value>on</value> |
228 <value>clean</value> |
229 <value>off</value>
230 </syntax>
161 <default>off</default> 231 <default>off</default>
162 <context>http, server, location</context> 232 <context>http</context>
163 233 <context>server</context>
164 <para> 234 <context>location</context>
165 Директива определяет, сохранять ли всё тело запроса клиента в файл. 235
166 Директиву можно использовать для отладки и при использовании 236 <para>
167 переменной $request_body_file или метода 237 Определяет, сохранять ли всё тело запроса клиента в файл.
168 <link doc="ngx_http_perl_module.xml" id="methods">$r-&gt;request_body_file</link> 238 Директиву можно использовать для отладки и при использовании переменной
169 модуля ngx_http_perl_module. 239 <var>$request_body_file</var>
170 </para> 240 или метода
171 241 <link doc="ngx_http_perl_module.xml" id="methods">$r->request_body_file</link>
172 <para> 242 модуля
173 При использовании параметра "on" временные файлы по окончании 243 <link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>.
174 обработки запроса не удаляется. 244 </para>
175 </para> 245
176 246 <para>
177 <para> 247 При установке значения <value>on</value> временные файлы
178 Параметр "clean" разрешает удалять временные файлы, оставшиеся по окончании 248 по окончании обработки запроса не удаляются.
179 обработки запроса. 249 </para>
250
251 <para>
252 Значение <value>clean</value> разрешает удалять временные файлы,
253 оставшиеся по окончании обработки запроса.
180 </para> 254 </para>
181 255
182 </directive> 256 </directive>
183 257
184 258
185 <directive name="client_body_in_single_buffer"> 259 <directive name="client_body_in_single_buffer">
186 <syntax><value>on|off</value></syntax> 260 <syntax><value>on</value> | <value>off</value>
261 </syntax>
187 <default>off</default> 262 <default>off</default>
188 <context>http, server, location</context> 263 <context>http</context>
189 264 <context>server</context>
190 <para> 265 <context>location</context>
191 Директива определяет, хранить ли всё тело запроса клиента в одном буфере. 266
192 Директива рекомендуется при использовании переменной $request_body 267 <para>
193 для уменьшения операций копирования. 268 Определяет, сохранять ли всё тело запроса клиента в одном буфере.
194 </para> 269 Директива рекомендуется при использовании переменной
195 270 <var>$request_body</var>
196 </directive> 271 для уменьшения требуемого числа операций копирования.
197
198
199 <directive name="client_body_buffer_size">
200 <syntax><value>размер</value></syntax>
201 <default>8k/16k</default>
202 <context>http, server, location</context>
203
204 <para>
205 Директива задаёт размер буфера для чтения тела запроса клиента.
206 Если тело запроса больше заданного буфера, то всё тело запроса или только
207 его часть записывается во временный файл.
208 По умолчанию размер одного буфера равен двум размерам страницы, в зависимости
209 от платформы это или 8K, или 16K.
210 </para> 272 </para>
211 273
212 </directive> 274 </directive>
213 275
214 276
215 <directive name="client_body_temp_path"> 277 <directive name="client_body_temp_path">
216 <syntax><value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] 278 <syntax>
217 </value></syntax> 279 <argument>путь</argument>
280 [<argument>уровень1</argument>
281 [<argument>уровень2</argument>
282 [<argument>уровень3</argument>]]]
283 </syntax>
218 <default>client_body_temp</default> 284 <default>client_body_temp</default>
219 <context>http, server, location</context> 285 <context>http</context>
220 286 <context>server</context>
221 <para> 287 <context>location</context>
222 Директива задаёт имя каталога для хранения временных файлов с телом запроса 288
223 клиента. 289 <para>
290 Задаёт каталог для хранения временных файлов с телами запросов клиентов.
224 В каталоге может использоваться иерархия подкаталогов до трёх уровней. 291 В каталоге может использоваться иерархия подкаталогов до трёх уровней.
225 Например, при такой конфигурации 292 Например, при такой конфигурации
226 <example> 293 <example>
227 client_body_temp_path /spool/nginx/client_temp 1 2; 294 client_body_temp_path /spool/nginx/client_temp 1 2;
228 </example> 295 </example>
229 имя временного будет такого вида: 296 временный файл будет следующего вида:
230 <example> 297 <example>
231 /spool/nginx/client_temp/7/45/00000123457 298 /spool/nginx/client_temp/7/45/00000123457
232 </example> 299 </example>
233 </para> 300 </para>
234 301
235 </directive> 302 </directive>
236 303
237 304
238 <directive name="client_body_timeout"> 305 <directive name="client_body_timeout">
239 <syntax><value>время</value></syntax> 306 <syntax><argument>время</argument></syntax>
240 <default>60</default> 307 <default>60s</default>
241 <context>http, server, location</context> 308 <context>http</context>
242 309 <context>server</context>
243 <para> 310 <context>location</context>
244 Директива задаёт таймаут при чтении тела запроса клиента. 311
312 <para>
313 Задаёт таймаут при чтении тела запроса клиента.
245 Таймаут устанавливается не на всю передачу тела запроса, 314 Таймаут устанавливается не на всю передачу тела запроса,
246 а только между двумя операциями чтения. 315 а только между двумя последовательными операциями чтения.
247 Если по истечении этого времени клиент ничего не передаст, 316 Если по истечении этого времени клиент ничего не передаст,
248 то ему возвращается ошибка "Request time out" (408). 317 то клиенту возвращается ошибка
318 <http-status code="408" text="Request Time-out"/>.
249 </para> 319 </para>
250 320
251 </directive> 321 </directive>
252 322
253 323
254 <directive name="client_header_buffer_size"> 324 <directive name="client_header_buffer_size">
255 <syntax><value>размер</value></syntax> 325 <syntax><argument>размер</argument></syntax>
256 <default>1k</default> 326 <default>1k</default>
257 <context>http, server</context> 327 <context>http</context>
258 328 <context>server</context>
259 <para> 329
260 Директива задаёт размер буфера для чтения заголовка запроса клиента. 330 <para>
261 Для подавляющего большинства запросов вполне достаточно буфера размером в 1K. 331 Задаёт размер буфера для чтения заголовка запроса клиента.
262 Однако если в запросе есть большие cookies или же запрос пришёл 332 Для большинства запросов достаточно буфера размером в 1K байт.
263 от wap-клиента, то он может не поместиться в 1K. 333 Однако если в запросе есть длинные cookies, или же запрос
264 Поэтому, если строка запроса или строка заголовка запроса не помещается 334 пришёл от WAP-клиента, то он может не поместиться в 1K.
265 полностью в этот буфер, то выделяются большие буферы, задаваемые директивой 335 Поэтому, если строка запроса или поле заголовка запроса
336 не помещаются полностью в этот буфер, то выделяются буферы
337 большего размера, задаваемые директивой
266 <link id="large_client_header_buffers"/>. 338 <link id="large_client_header_buffers"/>.
267 </para> 339 </para>
268 340
269 </directive> 341 </directive>
270 342
271 343
272 <directive name="client_header_timeout"> 344 <directive name="client_header_timeout">
273 <syntax><value>время</value></syntax> 345 <syntax><argument>время</argument></syntax>
274 <default>60</default> 346 <default>60s</default>
275 <context>http, server</context> 347 <context>http</context>
276 348 <context>server</context>
277 <para> 349
278 Директива задаёт таймаут при чтении заголовка запроса клиента. 350 <para>
279 Если по истечении этого времени клиент не передаст полностью заголовок 351 Задаёт таймаут при чтении заголовка запроса клиента.
280 запроса, то ему возвращается ошибка "Request time out" (408). 352 Если по истечении этого времени клиент не передаст полностью заголовок,
353 то клиенту возвращается ошибка
354 <http-status code="408" text="Request Time-out"/>.
281 </para> 355 </para>
282 356
283 </directive> 357 </directive>
284 358
285 359
286 <directive name="client_max_body_size"> 360 <directive name="client_max_body_size">
287 <syntax><value>размер</value></syntax> 361 <syntax><argument>размер</argument></syntax>
288 <default>1m</default> 362 <default>1m</default>
289 <context>http, server, location</context> 363 <context>http</context>
290 364 <context>server</context>
291 <para> 365 <context>location</context>
292 Директива задаёт максимально допустимый размер тела запроса клиента, 366
293 указываемый в строке "Content-Length" в заголовке запроса. 367 <para>
368 Задаёт максимально допустимый размер тела запроса клиента,
369 указываемый в поле
370 <header>Content-Length</header>
371 заголовка запроса.
294 Если размер больше заданного, то клиенту возвращается ошибка 372 Если размер больше заданного, то клиенту возвращается ошибка
295 "Request Entity Too Large" (413). Следует иметь в виду, что 373 <http-status code="413" text="Request Entity Too Large"/>.
296 <link url="http://sysoev.ru/web/upload.html">браузеры не умеют 374 Следует иметь в виду, что
297 корректно показывать эту ошибку</link>. 375 <!--link doc="/web/upload.xml"-->браузеры не умеют корректно показывать
376 эту ошибку<!--/link-->.
377 Установка аргумента <argument>размер</argument> в 0 отключает
378 проверку размера тела запроса клиента.
379 </para>
380
381 </directive>
382
383
384 <directive name="connection_pool_size">
385 <syntax><argument>размер</argument></syntax>
386 <default>256</default>
387 <context>http</context>
388 <context>server</context>
389
390 <para>
391 Позволяет производить точную настройку выделений памяти
392 под конкретные соединения.
393 Эта директива не оказывает существенного влияния на
394 производительность и её не следует использовать.
298 </para> 395 </para>
299 396
300 </directive> 397 </directive>
301 398
302 399
303 <directive name="default_type"> 400 <directive name="default_type">
304 <syntax><value>MIME-тип</value></syntax> 401 <syntax><argument>mime-тип</argument></syntax>
305 <default>text/plain</default> 402 <default>text/plain</default>
306 <context>http, server, location</context> 403 <context>http</context>
307 404 <context>server</context>
308 <para> 405 <context>location</context>
309 Директива задаёт MIME-тип ответов по умолчанию. 406
407 <para>
408 Задаёт MIME-тип ответов по умолчанию.
409 См. также директиву <link id="types"/>.
310 </para> 410 </para>
311 411
312 </directive> 412 </directive>
313 413
314 414
315 <directive name="directio"> 415 <directive name="directio">
316 <syntax><value>[размер|off]</value></syntax> 416 <syntax><argument>размер</argument> | <value>off</value></syntax>
317 <default>off</default> 417 <default>off</default>
318 <context>http, server, location</context> 418 <context>http</context>
319 419 <context>server</context>
320 <para> 420 <context>location</context>
321 Директива (0.7.7) разрешает использовать флаги 421 <appeared-in>0.7.7</appeared-in>
322 O_DIRECT (FreeBSD, Linux), F_NOCACHE (Mac OS X) или функцию directio() (Solaris) 422
423 <para>
424 Разрешает использовать флаги
425 <c-def>O_DIRECT</c-def> (FreeBSD, Linux),
426 <c-def>F_NOCACHE</c-def> (Mac OS X)
427 или функцию <c-func>directio</c-func> (Solaris)
323 при чтении файлов, размер которых больше либо равен указанному. 428 при чтении файлов, размер которых больше либо равен указанному.
324 Директива автоматически запрещает (0.7.15) использование 429 Директива автоматически запрещает (0.7.15) использование
325 <link id="sendfile">sendfile'а</link> для данного запроса. 430 <link id="sendfile"/>
431 для данного запроса.
326 Рекомендуется использовать для больших файлов: 432 Рекомендуется использовать для больших файлов:
327 <example> 433 <example>
328 directio 4m; 434 directio 4m;
329 </example> 435 </example>
330 или при использовании <link id="aio"/> в Linux. 436 или при использовании <link id="aio"/> в Linux.
331 </para> 437 </para>
332 438
333 </directive> 439 </directive>
334 440
335 441
336 <directive name="directio_alignment"> 442 <directive name="directio_alignment">
337 <syntax><value>размер</value></syntax> 443 <syntax><argument>размер</argument></syntax>
338 <default>512</default> 444 <default>512</default>
339 <context>http, server, location</context> 445 <context>http</context>
340 446 <context>server</context>
341 <para> 447 <context>location</context>
342 Директива (0.8.11) устанавливает выравнивание для 448 <appeared-in>0.8.11</appeared-in>
449
450 <para>
451 Устанавливает выравнивание для
343 <link id="directio"/>. 452 <link id="directio"/>.
344 В большинстве случае достаточно выравнивания 512 байт, однако 453 В большинстве случаев достаточно 512-байтового выравнивания, однако
345 при использовании XFS под Linux его нужно увеличить до 4K. 454 при использовании XFS под Linux его нужно увеличить до 4K.
346 </para> 455 </para>
347 456
348 </directive> 457 </directive>
349 458
350 459
351 <directive name="error_page"> 460 <directive name="error_page">
352 <syntax><value>код [код ...] [=|=ответ] uri</value> 461 <syntax>
462 <argument>код</argument> ...
463 [<value>=</value>[<argument>ответ</argument>]]
464 <argument>uri</argument>
353 </syntax> 465 </syntax>
354 <default/> 466 <default/>
355 <context>http, server, location, if в location</context> 467 <context>http</context>
356 468 <context>server</context>
357 <para> 469 <context>location</context>
358 Директива задаёт URI, который будет показываться для указанных ошибок. 470 <context>if в location</context>
359 Директивы наследуются с предыдущего уровня при условии, что на данном 471
360 уровне не описаны свои директивы error_page. 472 <para>
361 В URI можно использовать переменные. 473 Задаёт URI, который будет показываться для указанных ошибок.
362 </para> 474 Директивы <code>error_page</code> наследуются с предыдущего уровня при условии,
363 475 что на данном уровне не описаны свои директивы
364 <para> 476 <code>error_page</code>.
365 Пример использования: 477 В значении URI можно использовать переменные.
366 <example> 478 </para>
367 error_page 404 /404.html; 479
368 error_page 502 503 504 /50x.html; 480 <para>
369 error_page 403 http://example.com/forbidden.html; 481 Пример:
482 <example>
483 error_page 404 /404.html;
484 error_page 502 503 504 /50x.html;
485 error_page 403 http://example.com/forbidden.html;
370 </example> 486 </example>
371 </para> 487 </para>
372 488
373 <para> 489 <para>
374 Кроме того, можно поменять код ответа на другой, например: 490 Кроме того, можно поменять код ответа на другой, например:
375 <example> 491 <example>
376 error_page 404 =200 /empty.gif; 492 error_page 404 =200 /empty.gif;
377 </example> 493 </example>
378 </para> 494 </para>
379 495
380 <para> 496 <para>
381 Если ошибочный ответ обрабатывается проксированным сервером или 497 Если ошибочный ответ обрабатывается проксированным сервером или
382 FastCGI-сервером и этот сервер может вернуть разные коды ответов, 498 FastCGI-сервером, и этот сервер может вернуть разные коды ответов,
383 например, 200, 302, 401 или 404, то можно выдавать возвращаемый код: 499 например, 200, 302, 401 или 404, то можно выдавать возвращаемый им код:
384 <example> 500 <example>
385 error_page 404 = /404.php; 501 error_page 404 = /404.php;
386 </example> 502 </example>
387 </para> 503 </para>
388 504
389 <para> 505 <para>
390 Если при перенаправлении не нужно менять URI, то можно перенаправить 506 Если при перенаправлении не нужно менять URI, то можно перенаправить
391 обработку ошибки в именованный location: 507 обработку ошибки в именованный location:
392 <example> 508 <example>
393 location / { 509 location / {
394 error_page 404 = @fallback; 510 error_page 404 = @fallback;
395 } 511 }
396 512
397 location @fallback { 513 location @fallback {
398 proxy_pass http://backend; 514 proxy_pass http://backend;
399 } 515 }
400 </example> 516 </example>
401 </para> 517 </para>
402 518
403 </directive> 519 </directive>
404 520
405 521
406 <directive name="if_modified_since"> 522 <directive name="if_modified_since">
407 <syntax><value>[off|exact|before]</value></syntax> 523 <syntax>
524 <value>off</value> |
525 <value>exact</value> |
526 <value>before</value>
527 </syntax>
408 <default>exact</default> 528 <default>exact</default>
409 <context>http, server, location</context> 529 <context>http</context>
410 530 <context>server</context>
411 <para> 531 <context>location</context>
412 Директива (0.7.24) определяет, как сравнивать время модификации ответа и 532 <appeared-in>0.7.24</appeared-in>
413 время в заголовке запроса "If-Modified-Since": 533
414 <list type="bullet"> 534 <para>
415 535 Определяет, как сравнивать время модификации ответа с
416 <listitem> 536 временем в поле
417 off — не проверять заголовок запроса 537 <header>If-Modified-Since</header>
418 "If-Modified-Since" (0.7.34); 538 заголовка запроса:
419 </listitem> 539
420 540 <list type="tag">
421 <listitem> 541
422 exact — точно совпадение; 542 <tag-name><value>off</value></tag-name>
423 </listitem> 543 <tag-desc>
424 544 не проверять поле
425 <listitem> 545 <header>If-Modified-Since</header> заголовка запроса (0.7.34);
426 before — время модификации ответа меньше или равно времени, заданному 546 </tag-desc>
427 в заголовке запроса "If-Modified-Since". 547
428 </listitem> 548 <tag-name><value>exact</value></tag-name>
549 <tag-desc>
550 точное совпадение;
551 </tag-desc>
552
553 <tag-name><value>before</value></tag-name>
554 <tag-desc>
555 время модификации ответа меньше или равно времени, заданному в поле
556 <header>If-Modified-Since</header> заголовка запроса.
557 </tag-desc>
429 558
430 </list> 559 </list>
560 </para>
561
562 </directive>
563
564
565 <directive name="ignore_invalid_headers">
566 <syntax><value>on</value> | <value>off</value></syntax>
567 <default>on</default>
568 <context>http</context>
569 <context>server</context>
570
571 <para>
572 Если включено, nginx игнорирует поля заголовка с недопустимыми именами.
573 Допустимыми считаются имена, состоящие из английских букв, цифр, дефисов
574 и возможно знаков подчёркивания (последнее контролируется директивой
575 <link id="underscores_in_headers"/>).
431 </para> 576 </para>
432 577
433 </directive> 578 </directive>
434 579
435 580
437 <syntax/> 582 <syntax/>
438 <default/> 583 <default/>
439 <context>location</context> 584 <context>location</context>
440 585
441 <para> 586 <para>
442 Директива указывает, что данный location может использоваться только 587 Указывает, что location может использоваться только для внутренних запросов.
443 для внутренних запросов. 588 Для внешних запросов клиенту будет возвращаться ошибка
444 Для внешних запросов будет возвращаться ошибка "Not found" (404). 589 <http-status code="404" text="Not Found"/>.
445 Внутренними запросами являются 590 Внутренними запросами являются:
591
446 <list type="bullet"> 592 <list type="bullet">
447 593
448 <listitem> 594 <listitem>
449 запросы, перенаправленные директивой error_page; 595 запросы, перенаправленные директивой <link id="error_page"/>;
450 </listitem> 596 </listitem>
451 597
452 <listitem> 598 <listitem>
453 подзапросы, формируемые командой include virtual модуля ngx_http_ssi_module; 599 подзапросы, формируемые командой
600 <command>include virtual</command>
601 модуля
602 <link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>;
603 ngx_http_ssi_module;
454 </listitem> 604 </listitem>
455 605
456 <listitem> 606 <listitem>
457 запросы, изменённые директивой rewrite модуля ngx_http_rewrite_module. 607 запросы, изменённые директивой
608 <link doc="ngx_http_rewrite_module.xml" id="rewrite"/>.
458 </listitem> 609 </listitem>
459 610
460 </list> 611 </list>
461 </para> 612 </para>
462 613
463 <para> 614 <para>
464 Пример использования: 615 Пример:
465 <example> 616 <example>
466 error_page 404 /404.html; 617 error_page 404 /404.html;
467 618
468 location /404.html { 619 location /404.html {
469 internal; 620 internal;
470 } 621 }
471 </example> 622 </example>
472 </para> 623 </para>
473 624
474 </directive> 625 </directive>
475 626
476 627
628 <directive name="keepalive_disable">
629 <syntax><value>none</value> | <argument>браузер</argument> ...</syntax>
630 <default>msie6 safari</default>
631 <context>http</context>
632 <context>server</context>
633 <context>location</context>
634
635 <para>
636 Запрещает keep-alive соединения с некорректно ведущими себя браузерами.
637 Аргументы <argument>браузер</argument> указывают, на какие браузеры это
638 распространяется.
639 Значение <value>msie6</value> запрещает keep-alive соединения
640 со старыми версиями MSIE после получения запроса POST.
641 Значение <value>safari</value> запрещает keep-alive соединения
642 с браузерами Safari.
643 Значение <value>none</value> разрешает keep-alive соединения
644 со всеми браузерами.
645 </para>
646
647 </directive>
648
649
477 <directive name="keepalive_requests"> 650 <directive name="keepalive_requests">
478 <syntax><value>число</value></syntax> 651 <syntax><argument>число</argument></syntax>
479 <default>100</default> 652 <default>100</default>
480 <context>http, server, location</context> 653 <context>http</context>
481 654 <context>server</context>
482 <para> 655 <context>location</context>
483 Директива (0.8.0) задаёт максимальное число запросов, которые можно 656 <appeared-in>0.8.0</appeared-in>
657
658 <para>
659 Задаёт максимальное число запросов, которые можно
484 сделать по одному keep-alive соединению. 660 сделать по одному keep-alive соединению.
661 После того, как будет сделано максимальное число запросов,
662 соединение закрывается.
485 </para> 663 </para>
486 664
487 </directive> 665 </directive>
488 666
489 667
490 <directive name="keepalive_timeout"> 668 <directive name="keepalive_timeout">
491 <syntax><value>время [время]</value></syntax> 669 <syntax>
492 <default>75</default> 670 <argument>таймаут</argument>
493 <context>http, server, location</context> 671 [<argument>заголовок_таймаута</argument>]
494 672 </syntax>
495 <para> 673 <default>75s</default>
496 Директива задаёт таймаут, в течение которого keep-alive соединение 674 <context>http</context>
497 с клиентом не будет закрыто со стороны сервера. 675 <context>server</context>
498 Второй параметр задаёт значение в строке "Keep-Alive: timeout=время" 676 <context>location</context>
499 в заголовке ответа. Параметры могут отличаться друг от друга. 677
500 Строку "Keep-Alive: timeout=время" понимают Mozilla и Konqueror. 678 <para>
679 Первый аргумент задаёт таймаут, в течение которого keep-alive
680 соединение с клиентом не будет закрыто со стороны сервера.
681 Второй необязательный параметр задаёт значение в поле
682 <header>Keep-Alive: timeout=<argument>время</argument></header>
683 заголовка ответа.
684 Два аргумента могут отличаться друг от друга.
685 </para>
686
687 <para>
688 Поле
689 <header>Keep-Alive: timeout=<argument>время</argument></header>
690 заголовка понимают Mozilla и Konqueror.
501 MSIE сам закрывает keep-alive соединение примерно через 60 секунд. 691 MSIE сам закрывает keep-alive соединение примерно через 60 секунд.
502 </para> 692 </para>
503 693
504 </directive> 694 </directive>
505 695
506 696
507 <directive name="large_client_header_buffers"> 697 <directive name="large_client_header_buffers">
508 <syntax><value>число размер</value> 698 <syntax><argument>число размер</argument></syntax>
509 </syntax> 699 <default>4 8k</default>
510 <default>4 4k/8k</default> 700 <context>http</context>
511 <context>http, server</context> 701 <context>server</context>
512 702
513 <para> 703 <para>
514 Директива задаёт максимальное число и размер буферов для чтения 704 Задаёт максимальное <argument>число</argument> и <argument>размер</argument>
515 большого заголовка запроса клиента. 705 буферов для чтения большого заголовка запроса клиента.
516 Строка запроса должна быть не больше размера одного буфера, иначе клиенту 706 Строка запроса не должна превышать размера одного буфера, иначе клиенту
517 возвращается ошибка "Request URI too large" (414). 707 возвращается ошибка
518 Длинная строка заголовка запроса также должна быть не больше размера одного 708 <http-status code="414" text="Request-URI Too Large"/>.
519 буфера, иначе клиенту возвращается ошибка "Bad request" (400). 709 Поле заголовка запроса также не должно превышать размера одного буфера,
710 иначе клиенту возвращается ошибка
711 <http-status code="400" text="Bad Request"/>.
520 Буферы выделяются только по мере необходимости. 712 Буферы выделяются только по мере необходимости.
521 По умолчанию размер одного буфера равен размеру страницы, в зависимости 713 По умолчанию размер одного буфера равен 8K байт.
522 от платформы это или 4K, или 8K.
523 Если по окончании обработки запроса соединение переходит в состояние 714 Если по окончании обработки запроса соединение переходит в состояние
524 keep-alive, то эти буферы освобождаются. 715 keep-alive, эти буферы освобождаются.
525 </para> 716 </para>
526 717
527 </directive> 718 </directive>
528 719
529 720
530 <directive name="limit_except"> 721 <directive name="limit_except">
531 <syntax block="yes"><value>методы</value></syntax> 722 <syntax block="yes"><argument>метод</argument> ...</syntax>
532 <default/> 723 <default/>
533 <context>location</context> 724 <context>location</context>
534 725
535 <para> 726 <para>
536 Директива ограничивает HTTP-методы, доступные внутри location. 727 Ограничивает HTTP-методы, доступные внутри location.
537 Метод GET также включает в себя метод HEAD. 728 Аргумент <argument>метод</argument> может быть одним из
538 Для ограничения могут использоваться директивы модулей 729 <value>GET</value>,
730 <value>HEAD</value>,
731 <value>POST</value>,
732 <value>PUT</value>,
733 <value>DELETE</value>,
734 <value>MKCOL</value>,
735 <value>COPY</value>,
736 <value>MOVE</value>,
737 <value>OPTIONS</value>,
738 <value>PROPFIND</value>,
739 <value>PROPPATCH</value>,
740 <value>LOCK</value>,
741 <value>UNLOCK</value>
742 или
743 <value>PATCH</value>.
744 Если разрешён метод <value>GET</value>, то метод
745 <value>HEAD</value> также будет разрешён.
746 Доступ к остальным методам может быть ограничен при помощи директив модулей
539 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> 747 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
540 и <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: 748 и
541 <example> 749 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>:
542 limit_except GET { 750 <example>
543 allow 192.168.1.0/32; 751 limit_except GET {
544 deny all; 752 allow 192.168.1.0/32;
545 } 753 deny all;
546 </example> 754 }
547 Обратите внимание, что данное ограничение будет выполняться для всех методов, 755 </example>
548 <value>кроме</value> методов GET и HEAD. 756 Обратите внимание, что данное ограничение действует для всех методов,
757 <emphasis>кроме</emphasis> GET и HEAD.
549 </para> 758 </para>
550 759
551 </directive> 760 </directive>
552 761
553 762
554 <directive name="limit_rate"> 763 <directive name="limit_rate">
555 764 <syntax><argument>скорость</argument></syntax>
556 <syntax><value>скорость</value></syntax> 765 <default>0</default>
557 <default/> 766 <context>http</context>
558 <context>http, server, location, if в location</context> 767 <context>server</context>
559 768 <context>location</context>
560 <para> 769 <context>if в location</context>
561 Директива задаёт скорость передачи ответа клиенту. 770
771 <para>
772 Ограничивает скорость передачи ответа клиенту.
562 Скорость задаётся в байтах в секунду. 773 Скорость задаётся в байтах в секунду.
563 774 Значение 0 (установка по умолчанию) отключает ограничение скорости.
564 Ограничение работает только для одного соединения, то есть, 775 <!--
565 если клиент откроет 2 соединения, то суммарная скорость будет в 2 раза 776 Чем меньше скорость, тем более аккуратным будет ограничение.
566 выше ограниченной. 777 -->
567 </para> 778 Ограничение срабатывает только для одного соединения, то есть если
568 779 клиент откроет 2 соединения, то суммарная скорость будет в 2 раза
569 <para> 780 выше заданного ограничения.
570 Если необходимо ограничить скорость для части клиентов на уровне сервера, 781 </para>
571 то директива limit_rate для этого не подходит. Вместо этого следует 782
572 задать нужную скорость переменной $limit_rate: 783 <para>
784 Если необходимо ограничить скорость для части клиентов на уровне
785 <link id="server">сервера</link>, то директива <code>limit_rate</code>
786 для этого не подходит.
787 Вместо этого следует задать желаемое ограничение скорости в переменной
788 <var>$limit_rate</var>:
573 <example> 789 <example>
574 server { 790 server {
575 791
576 if ($slow) { 792 if ($slow) {
577 set $limit_rate 4k; 793 set $limit_rate 4k;
578 } 794 }
579 795
580 ... 796 ...
581 } 797 }
582 </example> 798 </example>
584 800
585 </directive> 801 </directive>
586 802
587 803
588 <directive name="limit_rate_after"> 804 <directive name="limit_rate_after">
589 <syntax><value>размер</value></syntax> 805 <syntax><argument>размер</argument></syntax>
590 <default/> 806 <default>0</default>
591 <context>http, server, location, if в location</context> 807 <context>http</context>
592 808 <context>server</context>
593 <para> 809 <context>location</context>
594 Директива (0.8.0) задаёт объём данных, после передачи которого 810 <context>if в location</context>
595 начинает ограничиваться скорость передачи ответа клиенту, например: 811 <appeared-in>0.8.0</appeared-in>
812
813 <para>
814 Задаёт начальный объём данных, после передачи которого начинает
815 ограничиваться скорость передачи ответа клиенту.
816 </para>
817
818 <para>
819 Пример:
596 <example> 820 <example>
597 location /flv/ { 821 location /flv/ {
598 flv; 822 flv;
599 limit_rate_after 500k; 823 limit_rate_after 500k;
600 limit_rate 50k; 824 limit_rate 50k;
601 } 825 }
602 </example> 826 </example>
827 </para>
828
829 </directive>
830
831
832 <directive name="lingering_close">
833 <syntax><value>off</value> | <value>on</value> | <value>always</value></syntax>
834 <default>on</default>
835 <context>http</context>
836 <context>server</context>
837 <context>location</context>
838 <appeared-in>1.1.0</appeared-in>
839 <appeared-in>1.0.6</appeared-in>
840
841 <para>
842 Управляет закрытием соединений с клиентами.
843 </para>
844
845 <para>
846 Со значение по умолчанию “<value>on</value>” nginx будет
847 <link id="lingering_timeout">ждать</link> и
848 <link id="lingering_time">обрабатывать</link> дополнительные данные,
849 поступающие от клиента, перед полным закрытием соединения, но только
850 если эвристика указывает на то, что клиент может ещё послать данные.
851 </para>
852
853 <para>
854 Со значением “<value>always</value>” nginx всегда будет
855 ждать и обрабатывать дополнительные данные, поступающие от клиента.
856 </para>
857
858 <para>
859 Со значением “<value>off</value>” nginx не будет ждать поступления
860 дополнительных данных и сразу же закроет соединение.
861 Это нарушает протокол, поэтому не следует это использовать без нужды.
862 </para>
863
864 </directive>
865
866
867 <directive name="lingering_time">
868 <syntax><argument>время</argument></syntax>
869 <default>30s</default>
870 <context>http</context>
871 <context>server</context>
872 <context>location</context>
873
874 <para>
875 Если действует <link id="lingering_close"/>,
876 эта директива задаёт максимальное время, в течение которого nginx
877 будет обрабатывать (читать и игнорировать) дополнительные данные,
878 поступающие от клиента.
879 По прошествии этого времени соединение будет закрыто, даже если
880 будут ещё данные.
881 </para>
882
883 </directive>
884
885
886 <directive name="lingering_timeout">
887 <syntax><argument>время</argument></syntax>
888 <default>5s</default>
889 <context>http</context>
890 <context>server</context>
891 <context>location</context>
892
893 <para>
894 Если действует <link id="lingering_close"/>, эта директива задаёт
895 максимальное время ожидания поступления дополнительных данных от клиента.
896 Если в течение этого времени данные не были получены, соединение закрывается.
897 Иначе данные читаются и игнорируются, затем nginx снова ждёт поступления данных.
898 Цикл “ждать-читать-игнорировать” повторяется, но не дольше чем задано
899 директивой <link id="lingering_time"/>.
603 </para> 900 </para>
604 901
605 </directive> 902 </directive>
606 903
607 904
608 <directive name="listen"> 905 <directive name="listen">
609 <syntax><value>адрес:порт 906 <syntax>
610 [default|default_server| 907 <argument>адрес</argument>[:<argument>порт</argument>]
611 [backlog=число | 908 [<parameter>default_server</parameter>]
612 rcvbuf=размер | 909 [<parameter>setfib</parameter>=<argument>число</argument>]
613 sndbuf=размер | 910 [<parameter>backlog</parameter>=<argument>число</argument>]
614 accept_filter=фильтр | 911 [<parameter>rcvbuf</parameter>=<argument>размер</argument>]
615 deferred | 912 [<parameter>sndbuf</parameter>=<argument>размер</argument>]
616 bind | 913 [<parameter>accept_filter</parameter>=<argument>фильтр</argument>]
617 ipv6only=[on|off] | 914 [<parameter>deferred</parameter>]
618 ssl]] 915 [<parameter>bind</parameter>]
619 </value></syntax> 916 [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>]
917 [<parameter>ssl</parameter>]
918 [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax>
919 <syntax>
920 <argument>порт</argument>
921 [<parameter>default_server</parameter>]
922 [<parameter>setfib</parameter>=<argument>число</argument>]
923 [<parameter>backlog</parameter>=<argument>число</argument>]
924 [<parameter>rcvbuf</parameter>=<argument>размер</argument>]
925 [<parameter>sndbuf</parameter>=<argument>размер</argument>]
926 [<parameter>accept_filter</parameter>=<argument>фильтр</argument>]
927 [<parameter>deferred</parameter>]
928 [<parameter>bind</parameter>]
929 [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>]
930 [<parameter>ssl</parameter>]
931 [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax>
932 <syntax>
933 <value>unix:</value><argument>путь</argument>
934 [<parameter>default_server</parameter>]
935 [<parameter>backlog</parameter>=<argument>число</argument>]
936 [<parameter>rcvbuf</parameter>=<argument>размер</argument>]
937 [<parameter>sndbuf</parameter>=<argument>размер</argument>]
938 [<parameter>accept_filter</parameter>=<argument>фильтр</argument>]
939 [<parameter>deferred</parameter>]
940 [<parameter>bind</parameter>]
941 [<parameter>ssl</parameter>]
942 [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax>
620 <default>*:80 | *:8000</default> 943 <default>*:80 | *:8000</default>
621 <context>server</context> 944 <context>server</context>
622 945
623 <para> 946 <para>
624 Директива задаёт адрес и порт, на которых сервер принимает запросы. 947 Задаёт <argument>адрес</argument> и <argument>порт</argument> для IP
625 Можно указать только адрес или только порт, кроме того, адрес может 948 или <argument>путь</argument> для UNIX-сокета,
626 быть именем сервера, например: 949 на которых сервер будет принимать запросы.
627 <example> 950 Можно указать только <argument>адрес</argument>
628 listen 127.0.0.1:8000; 951 или только <argument>порт</argument>.
629 listen 127.0.0.1; 952 Кроме того, <argument>адрес</argument> может быть именем хоста, например:
630 listen 8000; 953 <example>
631 listen *:8000; 954 listen 127.0.0.1:8000;
632 listen localhost:8000; 955 listen 127.0.0.1;
633 </example> 956 listen 8000;
634 адреса IPv6 (0.7.36) задаются в квадратных скобках: 957 listen *:8000;
635 <example> 958 listen localhost:8000;
636 listen [::]:8000; 959 </example>
637 listen [fe80::1]; 960 IPv6-адреса (0.7.36) задаются в квадратных скобках:
638 </example> 961 <example>
639 </para> 962 listen [::]:8000;
640 963 listen [fe80::1];
641 <para> 964 </example>
642 Если указан только адрес, то используется порт 80. 965 UNIX-сокеты (0.8.21) задаются при помощи префикса “<code>unix:</code>”:
643 </para> 966 <example>
644 967 listen unix:/var/run/nginx.sock;
645 <para> 968 </example>
646 Если директива не указана, то используется порт *:80, если nginx работает 969 </para>
647 с правами пользователя root, или порт *:8000. 970
648 </para> 971 <para>
649 972 Если указан только <argument>адрес</argument>, то используется порт 80.
650 <para> 973 </para>
651 Если у директивы есть параметр default, то сервер, в котором описана 974
652 эта директива, будет сервером по умолчанию для указанной пары адрес:порт. 975 <para>
653 Если же директив с параметром default нет, то сервером по умолчанию 976 Если директива не указана, то используется либо <code>*:80</code>
654 будет первый сервер, в котором описана пара адрес:порт. 977 (если nginx работает с привилегиями суперпользователя),
655 Начиная с версии 0.8.21, можно использовать параметр default_server. 978 либо <code>*:8000</code>.
656 </para> 979 </para>
657 980
658 <para> 981 <para>
659 В директиве listen с параметром default можно также указать несколько 982 Если у директивы есть параметр <parameter>default_server</parameter>, то сервер,
660 параметров, специфичных для системных вызовов listen(2) и bind(2). 983 в котором описана эта директива, будет сервером по умолчанию для указанной пары
661 Начиная с версии 0.8.21, эти параметры можно задать в любой директиве 984 <argument>адрес</argument>:<argument>порт</argument>.
662 listen, но только один раз для указанной пары адрес:порт. 985 Если же директив с параметром <parameter>default_server</parameter> нет, то
663 <list type="bullet"> 986 сервером по умолчанию будет первый сервер, в котором описана пара
664 987 <argument>адрес</argument>:<argument>порт</argument>.
665 <listitem> 988 адрес:порт.
666 backlog=число — задаёт параметр backlog в вызове listen(2). 989 <note>
667 По умолчанию backlog равен -1 для FreeBSD и 511 для всех остальных 990 До версии 0.8.21 этот параметр назывался просто
668 платформ. 991 <parameter>default</parameter>.
669 </listitem> 992 </note>
670 993 </para>
671 <listitem> 994
672 rcvbuf=размер — задаёт параметр SO_RCVBUF для слушающего сокета. 995 <para>
673 </listitem> 996 В директиве <code>listen</code> можно также указать несколько
674 997 дополнительных параметров, специфичных для системных вызовов
675 <listitem> 998 <c-func>listen</c-func> и <c-func>bind</c-func>.
676 sndbuf=размер — задаёт параметр SO_SNDBUF для слушающего сокета. 999 Эти параметры можно задать в любой директиве <code>listen</code>,
677 </listitem> 1000 но только один раз для указанной пары
678 1001 <argument>адрес</argument>:<argument>порт</argument>.
679 <listitem> 1002 <note>
680 accept_filter=фильтр — задаёт название accept-фильтра. 1003 До версии 0.8.21 их можно было указывать лишь в директиве
681 Работает только на FreeBSD, можно использовать два фильтра — dataready 1004 <code>listen</code> с параметром <parameter>default</parameter>.
682 и httpready. 1005 </note>
683 По сигналу -HUP accept-фильтр можно менять только в последних 1006 <list type="tag">
684 версиях FreeBSD, начиная с 6.0, 5.4-STABLE и 4.11-STABLE. 1007
685 </listitem> 1008 <tag-name>
686 1009 <parameter>setfib</parameter>=<argument>число</argument>
687 <listitem> 1010 </tag-name>
688 deferred — указывает использовать отложенный accept(2) на Linux 1011 <tag-desc>
689 с помощью опции TCP_DEFER_ACCEPT. 1012 этот параметр (0.8.44) задаёт для слушающего сокета соответствующую
690 </listitem> 1013 таблицу маршрутизации (FIB).
691 1014 В настоящий момент это работает только на FreeBSD.
692 <listitem> 1015 </tag-desc>
693 bind — указывает, что для данной пары адрес:порт нужно делать bind(2) 1016
694 отдельно. 1017 <tag-name>
695 Дело в том, что если описаны несколько директив listen с одинаковым портом, 1018 <parameter>backlog</parameter>=<argument>число</argument>
696 но разными адресами и одна из директив listen слушает на всех адресах 1019 </tag-name>
697 для данного порта (*:порт), то nginx сделает bind(2) только на *:порт. 1020 <tag-desc>
698 Необходимо учитывать, что в этом случае для определения адреса, на которой 1021 задаёт параметр <parameter>backlog</parameter> в вызове
699 пришло соединение, делается системный вызов getsockname(). 1022 <c-func>listen</c-func>.
700 Если же используются параметры backlog, rcvbuf, sndbuf, accept_filter 1023 По умолчанию <parameter>backlog</parameter> равен -1 для FreeBSD
701 или deferred, то для данной пары адрес:порт bind(2) всегда делается отдельно. 1024 и 511 для других платформ.
702 </listitem> 1025 </tag-desc>
703 1026
704 <listitem> 1027 <tag-name>
705 ipv6only — параметр (0.7.42) задаёт значение параметра IPV6_V6ONLY 1028 <parameter>rcvbuf</parameter>=<argument>размер</argument>
1029 </tag-name>
1030 <tag-desc>
1031 задаёт параметр <c-def>SO_RCVBUF</c-def> для слушающего сокета
1032 </tag-desc>
1033
1034 <tag-name>
1035 <parameter>sndbuf</parameter>=<argument>размер</argument>
1036 </tag-name>
1037 <tag-desc>
1038 задаёт параметр <c-def>SO_SNDBUF</c-def> для слушающего сокета
1039 </tag-desc>
1040
1041 <tag-name>
1042 <parameter>accept_filter</parameter>=<argument>фильтр</argument>
1043 </tag-name>
1044 <tag-desc>
1045 задаёт название accept-фильтра.
1046 Работает только на FreeBSD, можно использовать два фильтра —
1047 <value>dataready</value> и <value>httpready</value>.
1048 По сигналу <c-def>SIGHUP</c-def> accept-фильтр можно менять только в
1049 последних версиях FreeBSD, начиная с 6.0, 5.4-STABLE и 4.11-STABLE.
1050 </tag-desc>
1051
1052 <tag-name>
1053 <parameter>deferred</parameter>
1054 </tag-name>
1055 <tag-desc>
1056 указывает использовать отложенный <c-func>accept</c-func> на Linux
1057 с помощью опции <c-def>TCP_DEFER_ACCEPT</c-def>.
1058 </tag-desc>
1059
1060 <tag-name>
1061 <parameter>bind</parameter>
1062 </tag-name>
1063 <tag-desc>
1064 указывает, что для данной пары
1065 <argument>адрес</argument>:<argument>порт</argument> нужно делать
1066 <c-func>bind</c-func> отдельно.
1067 Дело в том, что если описаны несколько директив <code>listen</code>
1068 с одинаковым портом, но разными адресами и одна из директив
1069 <code>listen</code> слушает на всех адресах для данного порта
1070 (<code>*</code>:<argument>порт</argument>, то nginx сделает
1071 <c-func>bind</c-func> только на <code>*</code>:<argument>порт</argument>.
1072 Необходимо заметить, что в этом случае для определения адреса, на которой
1073 пришло соединение, делается системный вызов <c-func>getsockname</c-func>.
1074 Если же используются параметры <parameter>backlog</parameter>,
1075 <parameter>rcvbuf</parameter>, <parameter>sndbuf</parameter>,
1076 <parameter>accept_filter</parameter>, <parameter>deferred</parameter>
1077 или <parameter>so_keepalive</parameter>, то для данной пары
1078 <argument>адрес</argument>:<argument>порт</argument> всегда делается
1079 отдельный вызов <c-func>bind</c-func>.
1080 </tag-desc>
1081
1082 <tag-name>
1083 <parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>
1084 </tag-name>
1085 <tag-desc>
1086 параметр (0.7.42) задаёт значение параметра <c-def>IPV6_V6ONLY</c-def>
706 для слушающего сокета. 1087 для слушающего сокета.
707 Установить этот параметр можно только один раз на старте. 1088 Установить этот параметр можно только один раз на старте.
708 </listitem> 1089 </tag-desc>
709 1090
710 <listitem> 1091 <tag-name>
711 ssl — параметр (0.7.14) не имеет отношения к системным вызовам 1092 <parameter>ssl</parameter>
712 listen(2) и bind(2), а позволяет указать, что все соединения, 1093 </tag-name>
713 принимаемые на этом порту, должны работать в режиме SSL. 1094 <tag-desc>
1095 этот параметр (0.7.14) не имеет отношения к системным вызовам
1096 <c-func>listen</c-func> и <c-func>bind</c-func>, а позволяет указать,
1097 что все соединения, принимаемые на этом порту, должны работать
1098 в режиме SSL.
714 Это позволяет задать компактную конфигурацию для сервера, 1099 Это позволяет задать компактную конфигурацию для сервера,
715 работающего сразу в двух режимах — HTTP и HTTPS. 1100 работающего сразу в двух режимах — HTTP и HTTPS.
716 <example> 1101 <example>
717 listen 80; 1102 listen 80;
718 listen 443 default ssl; 1103 listen 443 default ssl;
719 </example> 1104 </example>
720 </listitem> 1105 </tag-desc>
1106
1107 <tag-name>
1108 <parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]
1109 </tag-name>
1110 <tag-desc>
1111 этот параметр (1.1.11) конфигурирует для слушающего сокета
1112 поведение “TCP keepalive”.
1113 Если этот параметр опущен, то для сокета будут действовать
1114 стандартные системные настройки.
1115 Если он установлен в значение “<value>on</value>”, то для сокета
1116 включается опция <c-def>SO_KEEPALIVE</c-def>.
1117 Если он установлен в значение “<value>off</value>”, то для сокета
1118 опция <c-def>SO_KEEPALIVE</c-def> выключается.
1119 Некоторые операционные системы поддерживают настройку параметров
1120 “TCP keepalive” на уровне сокета посредством опций
1121 <c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def> и
1122 <c-def>TCP_KEEPCNT</c-def>.
1123 На таких системах (в настоящий момент это Linux 2.4+ и NetBSD 5+)
1124 их можно сконфигурировать с помощью аргументов <argument>keepidle</argument>,
1125 <argument>keepintvl</argument> и <argument>keepcnt</argument>.
1126 Один или два аргумента могут быть опущены, в таком случае для
1127 соответствующей опции сокета будут действовать стандартные
1128 системные настройки.
1129 Например,
1130 <example>so_keepalive=30m::10</example>
1131 установит таймаут бездействия (<c-def>TCP_KEEPIDLE</c-def>) в 30 минут,
1132 для интервала проб (<c-def>TCP_KEEPINTVL</c-def>) будет действовать
1133 стандартная системная настройка, а счётчик проб (<c-def>TCP_KEEPCNT</c-def>)
1134 будет равен 10.
1135 </tag-desc>
721 1136
722 </list> 1137 </list>
723 </para> 1138 </para>
724 1139
725 <para> 1140 <para>
726 Пример использования параметров: 1141 Пример:
727 <example> 1142 <example>
728 listen 127.0.0.1 default accept_filter=dataready backlog=1024; 1143 listen 127.0.0.1 default accept_filter=dataready backlog=1024;
729 </example> 1144 </example>
730 </para> 1145 </para>
731 1146
732 </directive> 1147 </directive>
733 1148
734 1149
735 <directive name="location"> 1150 <directive name="location">
736 <syntax block="yes">[<value>=|~|~*|^~|@</value>] <value>/uri/</value> 1151 <syntax block="yes">[
1152 <value>=</value> |
1153 <value>~</value> |
1154 <value>~*</value> |
1155 <value>^~</value>
1156 ] <argument>uri</argument>
737 </syntax> 1157 </syntax>
1158 <syntax block="yes"><value>@</value><argument>имя</argument></syntax>
738 <default/> 1159 <default/>
739 <context>server</context> 1160 <context>server</context>
740 1161 <context>location</context>
741 <para> 1162
742 Директива устанавливает конфигурацию в зависимости от URI запроса. 1163 <para>
743 location можно задать обычной строкой или регулярным выражением. 1164 Устанавливает конфигурацию в зависимости от URI запроса.
744 Регулярные выражения задаются префиксом "~*" — без учёта регистра 1165 location можно задать префиксной строкой или регулярным выражением.
745 символов, и "~" — с учётом. 1166 Регулярные выражения задаются либо с префиксом “<value>~*</value>”
746 Для определения соответствия location'а и запроса 1167 (для поиска совпадения без учёта регистра символов),
747 сначала проверяются location'ы, заданные обычными строками. 1168 либо с префиксом “<value>~</value>” (с учётом регистра).
1169 Чтобы найти location, соответствующий запросу, вначале проверяются
1170 location'ы, заданные префиксными строками (префиксные location'ы).
748 Среди них ищется максимальное совпадение. 1171 Среди них ищется максимальное совпадение.
749 Затем проверяются регулярные выражения. 1172 Затем проверяются регулярные выражения, в порядке их следования
750 В отличие от обычных строк, они не сортируются, а проверяются в порядке 1173 в конфигурационном файле.
751 их следования в конфигурационном файле. 1174 Проверка регулярных выражений прекращается после первого же совпадения,
752 Проверка регулярных выражений прекращается после первого же совпадения. 1175 и используется соответствующая конфигурация.
753 Если совпадение с регулярным выражением не найдено, то используется 1176 Если совпадение с регулярным выражением не найдено, то используется
754 конфигурация максимально совпавшего location'а. 1177 конфигурация максимально совпавшего префиксного location'а.
755 </para> 1178 </para>
756 1179
757 <para> 1180 <para>
758 Для операционных систем, не чувствительных к регистру символов, таких 1181 location'ы могут быть вложенными, с некоторыми исключениями,
759 как Mac OS X и Cygwin, проверка обычных строк делается без учёта 1182 о которых говорится ниже.
760 регистра (0.7.7). 1183 </para>
1184
1185 <para>
1186 Для операционных систем, нечувствительных к регистру символов, таких
1187 как Mac OS X и Cygwin, сравнение с префиксными строками производится
1188 без учёта регистра (0.7.7).
761 Однако, сравнение ограничено только однобайтными locale'ями. 1189 Однако, сравнение ограничено только однобайтными locale'ями.
762 </para> 1190 </para>
763 1191
764 <para> 1192 <para>
765 Регулярное выражение может содержать выделения (0.7.40), которые 1193 Регулярные выражения могут содержать выделения (0.7.40), которые могут
766 могут затем использоваться в других директивах. 1194 затем использоваться в других директивах.
767 </para> 1195 </para>
768 1196
769 <para> 1197 <para>
770 Если нужно запретить проверку регулярных выражений после проверки 1198 Если у максимального совпавшего префиксного location'а указан префикс
771 обычных строк, то это можно сделать с помощью префикса "^~". 1199 “<value>^~</value>”, то регулярные выражения не проверяются.
772 Если у максимально совпавшего location'а есть этот префикс, то 1200 </para>
773 регулярные выражения не проверяются. 1201
774 </para> 1202 <para>
775 1203 Кроме того, с помощью префикса “<value>=</value>” можно задать точное
776 <para> 1204 совпадение URI и location.
777 Кроме того, с помощью префикса "=" можно задать точное совпадение 1205 При точном совпадении поиск сразу же прекращается.
778 URI и location. При совпадении поиск сразу же прекращается, так как 1206 Например, если запрос “<code>/</code>” случается часто, то
779 дальше искать не имеет смысла. Например, если запрос "/" очень частый, 1207 указав “<code>location = /</code>”, можно ускорить обработку
780 то указав "location = /", можно ускорить обработку этого запроса, 1208 этих запросов, так как поиск прекратится после первого же сравнения.
781 так как поиск location прекратится после первого же сравнения. 1209 Очевидно, что такой location не может иметь вложенные location'ы.
782 </para> 1210 </para>
783 1211
784 <para> 1212 <para>
785 В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с обычным location'ом 1213 <note>
786 без префиксов "=" и "^~", то поиск тоже сразу же прекращается и 1214 В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с префиксным
787 регулярные выражения также не проверяются. 1215 location'ом без префиксов “<value>=</value>” и “<value>^~</value>”,
1216 то поиск тоже сразу же прекращается и регулярные выражения также
1217 не проверяются.
1218 </note>
788 </para> 1219 </para>
789 1220
790 <para> 1221 <para>
791 Проиллюстрируем вышесказанное примером: 1222 Проиллюстрируем вышесказанное примером:
792 <example> 1223 <example>
793 location = / { 1224 location = / {
794 [ конфигурация A ] 1225 [ конфигурация А ]
795 } 1226 }
796 1227
797 location / { 1228 location / {
798 [ конфигурация B ] 1229 [ конфигурация Б ]
799 } 1230 }
800 1231
801 location ^~ /images/ { 1232 location ^~ /images/ {
802 [ конфигурация C ] 1233 [ конфигурация В ]
803 } 1234 }
804 1235
805 location ~* \.(gif|jpg|jpeg)$ { 1236 location ~* \.(gif|jpg|jpeg)$ {
806 [ конфигурация D ] 1237 [ конфигурация Г ]
807 } 1238 }
808 </example> 1239 </example>
809 Для запроса "/" будет выбрана конфигурация A, 1240 Для запроса “<code>/</code>” будет выбрана конфигурация А,
810 для запроса "/documents/document.html" — конфигурация B, 1241 для запроса “<code>/documents/document.html</code>” — конфигурация Б,
811 для запроса "/images/1.gif" — конфигурация C, 1242 для запроса “<code>/images/1.gif</code>” — конфигурация В,
812 для запроса "/documents/1.jpg" — конфигурация D. 1243 а для запроса “<code>/documents/1.jpg</code>” — конфигурация Г.
813 </para> 1244 </para>
814 1245
815 <para> 1246 <para>
816 Префикс "@" задаёт именованный location. Такой location не используется 1247 Префикс “<value>@</value>” задаёт именованный location.
817 при обычной обработке запросов, а предназначен только для перенаправления 1248 Такой location не используется при обычной обработке запросов, а
818 в него запросов. 1249 предназначен только для перенаправления в него запросов.
819 </para> 1250 Такие location'ы не могут быть вложенными и не могут содержать
1251 вложенные location'ы.
1252 </para>
1253
1254 <!--
1255 <migration from="Apache" directive="Location" />
1256 -->
820 1257
821 </directive> 1258 </directive>
822 1259
823 1260
824 <directive name="log_not_found"> 1261 <directive name="log_not_found">
825 <syntax><value>[on|off]</value></syntax> 1262 <syntax><value>on</value> | <value>off</value></syntax>
826 <default>on</default> 1263 <default>on</default>
827 <context>http, server, location</context> 1264 <context>http</context>
828 1265 <context>server</context>
829 <para> 1266 <context>location</context>
830 Директива разрешает или запрещает записывать в error_log 1267
1268 <para>
1269 Разрешает или запрещает записывать в
1270 <link doc="../ngx_core_module.xml" id="error_log"/>
831 ошибки о том, что файл не найден. 1271 ошибки о том, что файл не найден.
832 </para> 1272 </para>
833 1273
834 </directive> 1274 </directive>
835 1275
836 1276
837 <directive name="log_subrequest"> 1277 <directive name="log_subrequest">
838 <syntax><value>[on|off]</value></syntax> 1278 <syntax><value>on</value> | <value>off</value></syntax>
839 <default>off</default> 1279 <default>off</default>
840 <context>http, server, location</context> 1280 <context>http</context>
841 1281 <context>server</context>
842 <para> 1282 <context>location</context>
843 Директива разрешает или запрещает записывать в 1283
1284 <para>
1285 Разрешает или запрещает записывать в
844 <link doc="ngx_http_log_module.xml" id="access_log"/> 1286 <link doc="ngx_http_log_module.xml" id="access_log"/>
845 подзапросы. 1287 подзапросы.
846 </para> 1288 </para>
847 1289
848 </directive> 1290 </directive>
849 1291
850 1292
1293 <directive name="max_ranges">
1294 <syntax><argument>число</argument></syntax>
1295 <default/>
1296 <context>http</context>
1297 <context>server</context>
1298 <context>location</context>
1299
1300 <para>
1301 Ограничивает максимальное допустимое число диапазонов в запросах с
1302 указанием диапазона запрашиваемых байт (byte-range requests).
1303 Запросы, превышающие указанное ограничение, обрабатываются как
1304 если бы они не содержали указания диапазонов.
1305 По умолчанию ограничения нет.
1306 Значение 0 полностью запрещает поддержку диапазонов.
1307 </para>
1308
1309 </directive>
1310
1311
851 <directive name="merge_slashes"> 1312 <directive name="merge_slashes">
852 <syntax><value>[on|off]</value></syntax> 1313 <syntax><value>on</value> | <value>off</value></syntax>
853 <default>on</default> 1314 <default>on</default>
854 <context>http, server</context> 1315 <context>http</context>
855 1316 <context>server</context>
856 <para> 1317
857 Директива разрешает или запрещает объединять в URI два и более слэшей в один. 1318 <para>
858 </para> 1319 Разрешает или запрещает преобразование URI путём замены двух и более подряд
859 1320 идущих слэшей (“<code>/</code>”) в один.
860 <para> 1321 </para>
861 Необходимо иметь ввиду, что это объединение необходимо для корректной 1322
862 проверки location'ов и регулярных выражений. 1323 <para>
863 Например, запрос "//scripts/one.php" не попадает в 1324 Необходимо иметь ввиду, что это преобразование необходимо для корректной
1325 проверки префиксных строк и регулярных выражений.
1326 Если его не делать, то запрос “<code>//scripts/one.php</code>” не попадёт в
864 <example> 1327 <example>
865 location /scripts/ { 1328 location /scripts/ {
866 ... 1329 ...
867 } 1330 }
868 </example> 1331 </example>
869 и может быть обслужен как статический файл, 1332 и может быть обслужен как статический файл.
870 поэтому он приводится в "/scripts/one.php". 1333 Поэтому он преобразуется к виду “<code>/scripts/one.php</code>”.
871 </para> 1334 </para>
872 1335
873 <para> 1336 <para>
874 Выключение объединения может понадобиться, если в URI используются имена, 1337 Запрет преобразования может понадобиться, если в URI используются имена,
875 закодированные методом base64, который использует символ "/". 1338 закодированные методом base64, в котором задействован символ “<code>/</code>”.
876 Но по соображениям безопасности лучше избегать выключения объединения. 1339 Однако по соображениям безопасности лучше избегать отключения преобразования.
877 </para> 1340 </para>
878 1341
879 <para> 1342 <para>
880 Если директива указана на уровне server в сервере по умолчанию, 1343 Если директива указана на уровне
881 то её значение распространяется на все виртуальные сервера, слушающие 1344 <link id="server"/>
882 на том же адресе и порту. 1345 в сервере по умолчанию, то её значение распространяется на
1346 все виртуальные сервера, слушающие на том же адресе и порту.
883 </para> 1347 </para>
884 1348
885 </directive> 1349 </directive>
886 1350
887 1351
888 <directive name="msie_padding"> 1352 <directive name="msie_padding">
889 <syntax><value>[on|off]</value></syntax> 1353 <syntax><value>on</value> | <value>off</value></syntax>
890 <default>on</default> 1354 <default>on</default>
891 <context>http, server, location</context> 1355 <context>http</context>
892 1356 <context>server</context>
893 <para> 1357 <context>location</context>
894 Директива разрешает или запрещает добавлять в ответы для MSIE 1358
895 со статусом больше 400 1359 <para>
1360 Разрешает или запрещает добавлять в ответы для MSIE со статусом больше 400
896 комментарий для увеличения размера ответа до 512 байт. 1361 комментарий для увеличения размера ответа до 512 байт.
897 </para> 1362 </para>
898 1363
899 </directive> 1364 </directive>
900 1365
901 1366
902 <directive name="msie_refresh"> 1367 <directive name="msie_refresh">
903 <syntax><value>[on|off]</value></syntax> 1368 <syntax><value>on</value> | <value>off</value></syntax>
904 <default>off</default> 1369 <default>off</default>
905 <context>http, server, location</context> 1370 <context>http</context>
906 1371 <context>server</context>
907 <para> 1372 <context>location</context>
908 Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо 1373
909 редиректов. 1374 <para>
1375 Разрешает или запрещает выдавать для MSIE клиентов refresh'ы вместо
1376 перенаправлений.
910 </para> 1377 </para>
911 1378
912 </directive> 1379 </directive>
913 1380
914 1381
915 <directive name="open_file_cache"> 1382 <directive name="open_file_cache">
916 <syntax><value>max=N [inactive=время]|off</value> 1383 <syntax><value>off</value></syntax>
1384 <syntax>
1385 <parameter>max</parameter>=<argument>N</argument>
1386 [<parameter>inactive</parameter>=<argument>время</argument>]
917 </syntax> 1387 </syntax>
918 <default>off</default> 1388 <default>off</default>
919 <context>http, server, location</context> 1389 <context>http</context>
920 1390 <context>server</context>
921 <para> 1391 <context>location</context>
922 Директива задаёт кэш, в котором могут хранится 1392
1393 <para>
1394 Задаёт кэш, в котором могут храниться:
923 <list type="bullet"> 1395 <list type="bullet">
924 1396
925 <listitem> 1397 <listitem>
926 дескрипторы открытых файлов, информация об их размерах и времени модификации; 1398 дескрипторы открытых файлов, информация об их размерах и времени модификации;
927 </listitem> 1399 </listitem>
929 <listitem> 1401 <listitem>
930 информация о существовании каталогов; 1402 информация о существовании каталогов;
931 </listitem> 1403 </listitem>
932 1404
933 <listitem> 1405 <listitem>
934 информация об ошибках поиска файла — нет файла, нет прав на чтение 1406 информация об ошибках поиска файла — “нет файла”, “нет прав на чтение”
935 и тому подобное. Кэширование ошибок нужно разрешить директивой 1407 и тому подобное.
1408 <note>
1409 Кэширование ошибок нужно разрешить отдельно директивой
936 <link id="open_file_cache_errors"/>. 1410 <link id="open_file_cache_errors"/>.
1411 </note>
937 </listitem> 1412 </listitem>
938 1413
939 </list> 1414 </list>
940 </para> 1415 </para>
941 1416
942 <para> 1417 <para>
943 Параметры директивы: 1418 У директивы есть следующие параметры:
944 <list type="bullet"> 1419 <list type="tag">
945 1420
946 <listitem> 1421 <tag-name>
947 max — задаёт максимальное число элементов в кэше; 1422 <parameter>max</parameter>
1423 </tag-name>
1424 <tag-desc>
1425 задаёт максимальное число элементов в кэше;
948 при переполнении кэша удаляются наиболее давно не используемые элементы (LRU); 1426 при переполнении кэша удаляются наиболее давно не используемые элементы (LRU);
949 </listitem> 1427 </tag-desc>
950 1428
951 <listitem> 1429 <tag-name>
952 inactive — задаёт время, после которого элемент кэша удаляется, 1430 <parameter>inactive</parameter>
953 если к нему не было обращений в течение этого времени; 1431 </tag-name>
954 по умолчанию 60 секунд; 1432 <tag-desc>
955 </listitem> 1433 задаёт время, после которого элемент кэша удаляется, если к нему
956 1434 не было обращений в течение этого времени; по умолчанию 60 секунд;
957 <listitem> 1435 </tag-desc>
958 off — запрещает кэш. 1436
959 </listitem> 1437 <tag-name>
1438 <value>off</value>
1439 </tag-name>
1440 <tag-desc>
1441 запрещает кэш.
1442 </tag-desc>
960 1443
961 </list> 1444 </list>
962 </para> 1445 </para>
963 1446
964 <para> 1447 <para>
965 Пример использования: 1448 Пример:
966 <example> 1449 <example>
967 open_file_cache max=1000 inactive=20s; 1450 open_file_cache max=1000 inactive=20s;
968 open_file_cache_valid 30s; 1451 open_file_cache_valid 30s;
969 open_file_cache_min_uses 2; 1452 open_file_cache_min_uses 2;
970 open_file_cache_errors on; 1453 open_file_cache_errors on;
1454 <!--
1455 open_file_cache_events on;
1456 -->
971 </example> 1457 </example>
972 </para> 1458 </para>
973 1459
974 </directive> 1460 </directive>
975 1461
976 1462
977 <directive name="open_file_cache_errors"> 1463 <directive name="open_file_cache_errors">
978 <syntax><value>on|off</value></syntax> 1464 <syntax><value>on</value> | <value>off</value></syntax>
979 <default>off</default> 1465 <default>off</default>
980 <context>http, server, location</context> 1466 <context>http</context>
981 1467 <context>server</context>
982 <para> 1468 <context>location</context>
983 Директива определяет, кэшировать или нет ошибки поиска файлов в 1469
1470 <para>
1471 Разрешает или запрещает кэширование ошибок поиска файлов в
984 <link id="open_file_cache"/>. 1472 <link id="open_file_cache"/>.
985 </para> 1473 </para>
986 1474
987 </directive> 1475 </directive>
988 1476
989 1477
1478 <!--
1479
1480 <directive name="open_file_cache_events">
1481 <syntax><value>on</value> | <value>off</value></syntax>
1482 <default>off</default>
1483 <context>http</context>
1484 <context>server</context>
1485 <context>location</context>
1486
1487 <para>
1488 Разрешает использование событий ядра для проверки актуальности элементов
1489 <link id="open_file_cache"/>.
1490 Эта директива работает только совместно с методом
1491 <link doc="../events.xml" id="kqueue"/>.
1492 Заметьте, что только NetBSD&nbsp;2.0+ и FreeBSD&nbsp;6.0+
1493 поддерживают события для файловых систем произвольного типа.
1494 Другие операционные системы поддерживают события только для
1495 основных файловых систем, таких как UFS или FFS.
1496 </para>
1497
1498 </directive>
1499
1500 -->
1501
1502
990 <directive name="open_file_cache_min_uses"> 1503 <directive name="open_file_cache_min_uses">
991 <syntax><value>число</value></syntax> 1504 <syntax><argument>число</argument></syntax>
992 <default>1</default> 1505 <default>1</default>
993 <context>http, server, location</context> 1506 <context>http</context>
994 1507 <context>server</context>
995 <para> 1508 <context>location</context>
996 Директива определяет минимальное число использований файла в течение 1509
997 времени, заданного параметром inactive в директиве 1510 <para>
998 <link id="open_file_cache"/>, после которого дескриптор файла 1511 Задаёт минимальное <argument>число</argument> обращений к файлу
999 будет оставаться открытым в кэше. 1512 в течение времени, заданного параметром <parameter>inactive</parameter>
1513 директивы <link id="open_file_cache"/>, после которого дескриптор
1514 файла будет оставаться открытым в кэше.
1000 </para> 1515 </para>
1001 1516
1002 </directive> 1517 </directive>
1003 1518
1004 1519
1005 <directive name="open_file_cache_valid"> 1520 <directive name="open_file_cache_valid">
1006 <syntax><value>время</value></syntax> 1521 <syntax><argument>время</argument></syntax>
1007 <default>60</default> 1522 <default>60s</default>
1008 <context>http, server, location</context> 1523 <context>http</context>
1009 1524 <context>server</context>
1010 <para> 1525 <context>location</context>
1011 Директива определяет, через какое время нужно проверять актуальность 1526
1012 информации об элементе в <link id="open_file_cache"/>. 1527 <para>
1013 1528 Определяет время, через которое следует проверять актуальность информации
1529 об элементе в
1530 <link id="open_file_cache"/>.
1531 <!--
1532 При включенном
1533 <link id="open_file_cache_events"/>
1534 открытые дескрипторы файлов проверяются лишь единожды, а затем обновляются
1535 по факту их изменения.
1536 -->
1014 </para> 1537 </para>
1015 1538
1016 </directive> 1539 </directive>
1017 1540
1018 1541
1019 <directive name="optimize_server_names"> 1542 <directive name="optimize_server_names">
1020 <syntax><value>[on|off]</value></syntax> 1543 <syntax><value>on</value> | <value>off</value></syntax>
1544 <default>off</default>
1545 <context>http</context>
1546 <context>server</context>
1547
1548 <para>
1549 Директива устарела, вместо неё следует использовать директиву
1550 <link id="server_name_in_redirect"/>.
1551 </para>
1552
1553 <!--
1554 <para>
1555 Разрешает или запрещает оптимизировать проверку имени хоста в name-based
1556 виртуальных серверах.
1557 Проверка в частности влияет на имя хоста, используемого в перенаправлениях.
1558 Если оптимизация разрешена и все name-based сервера, слушающие на одной
1559 паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения запроса
1560 имена не проверяются и в перенаправлениях используется первое имя сервера.
1561 Если в перенаправлении нужно использовать имя хоста, переданное клиентом,
1562 то оптимизацию нужно выключить.
1563 </para>
1564 -->
1565
1566 </directive>
1567
1568
1569 <directive name="port_in_redirect">
1570 <syntax><value>on</value> | <value>off</value></syntax>
1021 <default>on</default> 1571 <default>on</default>
1022 <context>http, server</context> 1572 <context>http</context>
1023 1573 <context>server</context>
1024 <para> 1574 <context>location</context>
1025 Устаревшая директива. 1575
1026 </para> 1576 <para>
1027 1577 Разрешает или запрещает указывать порт в перенаправлениях, выдаваемых nginx'ом.
1028 <para> 1578 </para>
1029 Директива разрешает или запрещает оптимизировать проверку имени хоста 1579
1030 в name-based виртуальных серверах. 1580 <para>
1031 Проверка в частности влияет на имя хоста, используемого в редиректах. 1581 См. также директиву <link id="server_name_in_redirect"/>.
1032 Если оптимизация разрешена и все name-based сервера, слушающие на одной 1582 </para>
1033 паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения 1583
1034 запроса имена не проверяются и в редиректах используется первое имя сервера. 1584 </directive>
1035 Если в редиректе нужно использовать имя хоста, переданное клиентом, 1585
1036 то оптимизацию нужно выключить. 1586
1037 </para> 1587 <directive name="postpone_output">
1038 1588 <syntax><argument>размер</argument></syntax>
1039 </directive> 1589 <default>1460</default>
1040 1590 <context>http</context>
1041 1591 <context>server</context>
1042 <directive name="port_in_redirect"> 1592 <context>location</context>
1043 <syntax><value>[on|off]</value></syntax> 1593
1044 <default>on</default> 1594 <para>
1045 <context>http, server, location</context> 1595 Если это возможно, то отправка данных клиенту будет отложена пока nginx не
1046 1596 накопит по крайней мере указанное количество байт для отправки.
1047 <para> 1597 Значение 0 запрещает отложенную отправку данных.
1048 Директива разрешает или запрещает указывать порт в редиректах,
1049 выдаваемых nginx'ом.
1050 </para> 1598 </para>
1051 1599
1052 </directive> 1600 </directive>
1053 1601
1054 1602
1055 <directive name="read_ahead"> 1603 <directive name="read_ahead">
1056 <syntax><value>размер</value></syntax> 1604 <syntax><argument>размер</argument></syntax>
1057 <default>0</default> 1605 <default>0</default>
1058 <context>http, server, location</context> 1606 <context>http</context>
1059 1607 <context>server</context>
1060 <para> 1608 <context>location</context>
1061 Директива задаёт ядру размер предчтения при работе с файлами. 1609
1062 Под Линуксом используется системный вызов 1610 <para>
1063 <example> 1611 Задаёт ядру размер предчтения при работе с файлами.
1064 posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL); 1612 </para>
1065 </example> 1613
1066 поэтому размер игнорируется. 1614 <para>
1067 </para> 1615 На Linux используется системный вызов
1068 1616 <code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code>,
1069 <para> 1617 поэтому аргумент <argument>размер</argument> там игнорируется.
1070 Под FreeBSD используется fcntl(O_READAHEAD, размер), появившийся 1618 </para>
1071 во FreeBSD-9 CURRENT. Для FreeBSD 7 нужно установить 1619
1620 <para>
1621 На FreeBSD используется системный вызов
1622 <code>fcntl(O_READAHEAD,</code><argument>размер</argument><code>)</code>,
1623 появившийся во FreeBSD&nbsp;9.0-CURRENT.
1624 Для FreeBSD&nbsp;7 необходимо установить
1072 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">патч</link>. 1625 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">патч</link>.
1073 </para> 1626 </para>
1074 1627
1075 </directive> 1628 </directive>
1076 1629
1077 1630
1078 <directive name="recursive_error_pages"> 1631 <directive name="recursive_error_pages">
1079 <syntax><value>[on|off]</value></syntax> 1632 <syntax><value>on</value> | <value>off</value></syntax>
1080 <default>off</default> 1633 <default>off</default>
1081 <context>http, server, location</context> 1634 <context>http</context>
1082 1635 <context>server</context>
1083 <para> 1636 <context>location</context>
1084 Директива разрешает или запрещает делать несколько перенаправлений через 1637
1085 директиву <link id="error_page"/>. 1638 <para>
1639 Разрешает или запрещает делать несколько перенаправлений через директиву
1640 <link id="error_page"/>.
1641 </para>
1642
1643 </directive>
1644
1645
1646 <directive name="request_pool_size">
1647 <syntax><argument>размер</argument></syntax>
1648 <default>4k</default>
1649 <context>http</context>
1650 <context>server</context>
1651
1652 <para>
1653 Позволяет производить точную настройку выделений памяти
1654 под конкретные запросы.
1655 Эта директива не оказывает существенного влияния на
1656 производительность и её не следует использовать.
1086 </para> 1657 </para>
1087 1658
1088 </directive> 1659 </directive>
1089 1660
1090 1661
1091 <directive name="reset_timedout_connection"> 1662 <directive name="reset_timedout_connection">
1092 <syntax><value>[on|off]</value></syntax> 1663 <syntax>
1664 <value>on</value> | <value>off</value></syntax>
1093 <default>off</default> 1665 <default>off</default>
1094 <context>http, server, location</context> 1666 <context>http</context>
1095 1667 <context>server</context>
1096 <para> 1668 <context>location</context>
1097 Директива разрешает или запрещает сбрасывать соединение по таймауту. 1669
1098 Сброс делается следующим образом — перед закрытием сокета для него 1670 <para>
1099 ставится опция SO_LINGER с таймаутом 0. После чего при закрытии сокета 1671 Разрешает или запрещает сброс соединений по таймауту.
1100 клиенту отсылается пакет RST, а всё память, связанная с этим сокетом, 1672 Сброс делается следующим образом — перед закрытием сокета для него
1101 освобождается. Это позволяет избежать длительного нахождения уже закрытого 1673 ставится опция
1102 сокета в состоянии FIN_WAIT1 с заполненными буферами. 1674 <c-def>SO_LINGER</c-def>
1103 </para> 1675 с таймаутом 0.
1104 1676 После чего при закрытии сокета клиенту отсылается TCP RST, а вся память,
1105 <para> 1677 связанная с этим сокетом, освобождается.
1106 Необходимо отметить, что соединения, находящиеся в состоянии keepalive, 1678 Это позволяет избежать длительного нахождения уже закрытого сокета в
1107 по истечении таймаута закрываются обычным образом. 1679 состоянии FIN_WAIT1 с заполненными буферами.
1680 </para>
1681
1682 <para>
1683 Необходимо отметить, что keep-alive соединения по истечении таймаута
1684 закрываются обычным образом.
1108 </para> 1685 </para>
1109 1686
1110 </directive> 1687 </directive>
1111 1688
1112 1689
1113 <directive name="resolver"> 1690 <directive name="resolver">
1114 <syntax><value>адрес</value></syntax> 1691 <syntax>
1692 <argument>адрес</argument> ...
1693 [<parameter>valid</parameter>=<argument>время</argument>]
1694 </syntax>
1115 <default/> 1695 <default/>
1116 <context>http, server, location</context> 1696 <context>http</context>
1117 1697 <context>server</context>
1118 <para> 1698 <context>location</context>
1119 Директива задаёт адрес name-сервера, например: 1699
1120 <example> 1700 <para>
1121 resolver 127.0.0.1; 1701 Задаёт серверы DNS, используемые для преобразования имён апстрим серверов
1122 </example> 1702 в адреса, например:
1703 <example>
1704 resolver 127.0.0.1 192.0.2.1;
1705 </example>
1706 Аргумент <argument>адрес</argument> может быть задан либо
1707 IPv4-адресом, либо именем хоста;
1708 во втором случае используется первый полученный IPv4-адрес.
1709 Серверы DNS опрашиваются циклически.
1710 <note>
1711 До версии 1.1.7 можно было задать лишь один DNS-сервер.
1712 </note>
1713 По умолчанию nginx кэширует ответы, используя значение TTL из ответа.
1714 Необязательный параметр <parameter>valid</parameter> позволяет это
1715 переопределить:
1716 <example>
1717 resolver 127.0.0.1 192.0.2.1 valid=30s;
1718 </example>
1719 <note>
1720 До версии 1.1.9 настройка времени кэширования была невозможна
1721 и nginx всегда кэшировал ответы на срок в 5 минут.
1722 </note>
1123 </para> 1723 </para>
1124 1724
1125 </directive> 1725 </directive>
1126 1726
1127 1727
1128 <directive name="resolver_timeout"> 1728 <directive name="resolver_timeout">
1129 <syntax><value>время</value></syntax> 1729 <syntax><argument>время</argument></syntax>
1130 <default>30s</default> 1730 <default>30s</default>
1131 <context>http, server, location</context> 1731 <context>http</context>
1132 1732 <context>server</context>
1133 <para> 1733 <context>location</context>
1134 Директива задаёт таймаут для определения имени, например: 1734
1135 <example> 1735 <para>
1136 resolver_timeout 5s; 1736 Задаёт таймаут для преобразования имени в адрес, например:
1737 <example>
1738 resolver_timeout 5s;
1137 </example> 1739 </example>
1138 </para> 1740 </para>
1139 1741
1140 </directive> 1742 </directive>
1141 1743
1142 1744
1143 <directive name="root"> 1745 <directive name="root">
1144 <syntax><value>путь</value></syntax> 1746 <syntax><argument>путь</argument></syntax>
1145 <default>html</default> 1747 <default>html</default>
1146 <context>http, server, location, if в location</context> 1748 <context>http</context>
1147 1749 <context>server</context>
1148 <para> 1750 <context>location</context>
1149 Директива задаёт корневой каталог для запросов. 1751 <context>if в location</context>
1752
1753 <para>
1754 Задаёт корневой каталог для запросов.
1150 Например, при такой конфигурации 1755 Например, при такой конфигурации
1151 <example> 1756 <example>
1152 location /i/ { 1757 location /i/ {
1153 root /data/w3; 1758 root /data/w3;
1154 } 1759 }
1155 </example> 1760 </example>
1156 на запрос "/i/top.gif" будет отдан файл "/data/w3/i/top.gif". 1761 в ответ на запрос “<code>/i/top.gif</code>” будет отдан файл
1157 </para> 1762 <path>/data/w3/i/top.gif</path>.
1158 1763 </para>
1159 <para> 1764
1160 В значении пути можно использовать переменные. 1765 <para>
1161 </para> 1766 В значении аргумента <argument>путь</argument> можно использовать переменные,
1162 1767 кроме <var>$document_root</var> и <var>$realpath_root</var>.
1163 <para> 1768 </para>
1164 Путь к файлу формируется как простое добавление URI к значению директивы root. 1769
1165 Если же необходима модификация URI, то нужно воспользоваться директивой 1770 <para>
1771 Путь к файлу формируется путём простого добавления URI к значению директивы
1772 <code>root</code>.
1773 Если же URI необходимо поменять, следует воспользоваться директивой
1166 <link id="alias"/>. 1774 <link id="alias"/>.
1167 </para> 1775 </para>
1168 1776
1169 </directive> 1777 </directive>
1170 1778
1171 1779
1172 <directive name="satisfy"> 1780 <directive name="satisfy">
1173 <syntax><value>all|any</value></syntax> 1781 <syntax><value>all</value> | <value>any</value></syntax>
1174 <default>all</default> 1782 <default>all</default>
1175 <context>location</context> 1783 <context>http</context>
1176 1784 <context>server</context>
1177 <para> 1785 <context>location</context>
1178 Директива разрешает доступ при хотя бы одной успешной проверке, 1786
1179 выполненной модулями <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> 1787 <para>
1180 или <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: 1788 Разрешает доступ, если оба (<value>all</value>)
1789 или хотя бы один (<value>any</value>) из модулей
1790 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
1791 и <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>
1792 разрешают доступ.
1793 </para>
1794
1795 <para>
1796 Пример:
1181 <example> 1797 <example>
1182 location / { 1798 location / {
1183 satisfy any; 1799 satisfy any;
1184 1800
1185 allow 192.168.1.0/32; 1801 allow 192.168.1.0/32;
1186 deny all; 1802 deny all;
1187 1803
1188 auth_basic "closed site"; 1804 auth_basic "closed site";
1189 auth_basic_user_file conf/htpasswd; 1805 auth_basic_user_file conf/htpasswd;
1190 } 1806 }
1191 </example> 1807 </example>
1192 </para> 1808 </para>
1193 1809
1194 </directive> 1810 </directive>
1195 1811
1196 1812
1197 <directive name="satisfy_any"> 1813 <directive name="satisfy_any">
1198 <syntax><value>on|off</value></syntax> 1814 <syntax><value>on</value> | <value>off</value></syntax>
1199 <default>off</default> 1815 <default>off</default>
1200 <context>location</context> 1816 <context>http</context>
1201 1817 <context>server</context>
1202 <para> 1818 <context>location</context>
1203 Директива переименована в директиву <link id="satisfy"/>. 1819
1820 <para>
1821 Эта директива была переименована в директиву
1822 <link id="satisfy">satisfy any</link>.
1823 </para>
1824
1825 </directive>
1826
1827
1828 <directive name="send_lowat">
1829 <syntax><argument>размер</argument></syntax>
1830 <default>0</default>
1831 <context>http</context>
1832 <context>server</context>
1833 <context>location</context>
1834
1835 <para>
1836 При установке в ненулевое значение nginx будет пытаться минимизировать
1837 число операций отправки на клиентских сокетах либо при помощи флага
1838 <c-def>NOTE_LOWAT</c-def> метода
1839 <link doc="../events.xml" id="kqueue"/>,
1840 либо при помощи опции сокета <c-def>SO_SNDLOWAT</c-def>,
1841 с указанным размером.
1842 </para>
1843
1844 <para>
1845 Эта директива игнорируется на Linux, Solaris и Windows.
1204 </para> 1846 </para>
1205 1847
1206 </directive> 1848 </directive>
1207 1849
1208 1850
1209 <directive name="send_timeout"> 1851 <directive name="send_timeout">
1210 <syntax><value>время</value></syntax> 1852 <syntax><argument>время</argument></syntax>
1211 <default>60</default> 1853 <default>60s</default>
1212 <context>http, server, location</context> 1854 <context>http</context>
1213 1855 <context>server</context>
1214 <para> 1856 <context>location</context>
1215 Директива задаёт таймаут при передаче ответа клиенту. 1857
1858 <para>
1859 Задаёт таймаут при передаче ответа клиенту.
1216 Таймаут устанавливается не на всю передачу ответа, 1860 Таймаут устанавливается не на всю передачу ответа,
1217 а только между двумя операциями записями. 1861 а только между двумя операциями записями.
1218 Если по истечении этого времени клиент ничего не примет, 1862 Если по истечении этого времени клиент ничего не примет,
1219 то nginx закрывает соединение. 1863 соединение будет закрыто.
1220 </para> 1864 </para>
1221 1865
1222 </directive> 1866 </directive>
1223 1867
1224 1868
1225 <directive name="sendfile"> 1869 <directive name="sendfile">
1226 <syntax><value>[on|off]</value></syntax> 1870
1871 <syntax><value>on</value> | <value>off</value></syntax>
1227 <default>off</default> 1872 <default>off</default>
1228 <context>http, server, location</context> 1873 <context>http</context>
1229 1874 <context>server</context>
1230 <para> 1875 <context>location</context>
1231 Директива разрешает или запрещает использовать sendfile(). 1876 <context>if в location</context>
1877
1878 <para>
1879 Разрешает или запрещает использовать
1880 <c-func>sendfile</c-func>.
1881 </para>
1882
1883 </directive>
1884
1885
1886 <directive name="sendfile_max_chunk">
1887
1888 <syntax><argument>размер</argument></syntax>
1889 <default>0</default>
1890 <context>http</context>
1891 <context>server</context>
1892 <context>location</context>
1893
1894 <para>
1895 При установке в ненулевое значение ограничивает объём данных,
1896 который может передан за один вызов <c-func>sendfile</c-func>.
1897 Без этого ограничения одно быстрое соединение может целиком
1898 захватить рабочий процесс.
1232 </para> 1899 </para>
1233 1900
1234 </directive> 1901 </directive>
1235 1902
1236 1903
1238 <syntax block="yes"/> 1905 <syntax block="yes"/>
1239 <default/> 1906 <default/>
1240 <context>http</context> 1907 <context>http</context>
1241 1908
1242 <para> 1909 <para>
1243 Директива задаёт конфигурацию для виртуального сервера. 1910 Задаёт конфигурацию для виртуального сервера.
1244 Чёткого разделения виртуальных серверов ip-based (на основании ip-адреса) 1911 Чёткого разделения виртуальных серверов на IP-based (на основании IP-адреса)
1245 и name-based (на основании имени, передаваемого в строке "Host" 1912 и name-based (на основании поля <header>Host</header> заголовка запроса) нет.
1246 заголовка запроса), нет. 1913 Вместо этого директивами <link id="listen"/> описываются все
1247 Вместо этого директивами <link id="listen"/> описываются все адреса 1914 адреса и порты, на которых нужно принимать соединения для этого сервера,
1248 и порты, на которых нужно принимать соединения для этого сервера, 1915 а в директиве <link id="server_name"/> указываются все имена серверов.
1249 и в директиве <link id="server_name"/> указываются все имена серверов. 1916 Пример конфигурации описан в документе по
1250 Пример конфигурации описан в <link doc="../virtual_hosts.xml"> 1917 <link doc="../virtual_hosts.xml">
1251 настройке виртуальных серверов</link>. 1918 настройке виртуальных серверов</link>.
1252 </para> 1919 </para>
1253 1920
1254 </directive> 1921 </directive>
1255 1922
1256 1923
1257 <directive name="server_name"> 1924 <directive name="server_name">
1258 <syntax><value>имя [...]</value></syntax> 1925 <syntax><argument>имя</argument> ...</syntax>
1259 <default>hostname</default> 1926 <default>""</default>
1260 <context>server</context> 1927 <context>server</context>
1261 1928
1262 <para> 1929 <para>
1263 Директива задаёт имена виртуального сервера, например: 1930 Задаёт имена виртуального сервера, например:
1264 <example> 1931 <example>
1265 server { 1932 server {
1266 server_name example.com www.example.com; 1933 server_name example.com www.example.com;
1267 } 1934 }
1268 </example> 1935 </example>
1269 </para> 1936 </para>
1270 1937
1271 <para> 1938 <para>
1272 Первое имя становится основным именем сервера. 1939 Первое имя становится основным именем сервера.
1273 По умолчанию используется имя машины (hostname). 1940 В именах серверов можно использовать звёздочку (“<code>*</code>”)
1274 В именах серверов можно использовать "*" для замены первой или последней 1941 для замены первой или последней части имени:
1275 части имени:
1276 <example> 1942 <example>
1277 server { 1943 server {
1278 server_name example.com *.example.com www.example.*; 1944 server_name example.com *.example.com www.example.*;
1279 } 1945 }
1280 </example> 1946 </example>
1281 </para> 1947 </para>
1282 1948
1283 <para> 1949 <para>
1284 Два первых вышеприведённых имени можно объединить в одно: 1950 Два первых вышеприведённых имени можно объединить в одно:
1285 <example> 1951 <example>
1286 server { 1952 server {
1287 server_name .example.com; 1953 server_name .example.com;
1288 } 1954 }
1289 </example> 1955 </example>
1290 </para> 1956 </para>
1291 1957
1292 <para> 1958 <para>
1293 Кроме того, в качестве имени сервера можно использовать регулярное 1959 Если аргумент равен “<var>$hostname</var>” (0.9.4), то
1294 выражение, указав перед ним "~": 1960 подставляется имя хоста (hostname) машины.
1961 </para>
1962
1963 <para>
1964 В качестве имени сервера можно также использовать регулярное выражение,
1965 указав перед ним тильду (“<code>~</code>”):
1295 <example> 1966 <example>
1296 server { 1967 server {
1297 server_name www.example.com ~^www\d+\.example\.com$; 1968 server_name www.example.com ~^www\d+\.example\.com$;
1298 } 1969 }
1299 </example> 1970 </example>
1300 </para> 1971 </para>
1301 1972
1302 <para> 1973 <para>
1303 Регулярное выражение может содержать выделения (0.7.40), которые 1974 Регулярное выражение может содержать выделения (0.7.40),
1304 могут затем использоваться в других директивах: 1975 которые могут затем использоваться в других директивах:
1305 <example> 1976 <example>
1306 server { 1977 server {
1307 server_name ~^(www\.)?(.+)$; 1978 server_name ~^(www\.)?(.+)$;
1308 1979
1309 location / { 1980 location / {
1310 root /sites/$2; 1981 root /sites/$2;
1311 } 1982 }
1312 } 1983 }
1313 1984
1314 server { 1985 server {
1315 server_name _; 1986 server_name _;
1316 1987
1317 location / { 1988 location / {
1318 root /sites/default; 1989 root /sites/default;
1319 } 1990 }
1320 } 1991 }
1321 </example> 1992 </example>
1322 </para> 1993 </para>
1323 1994
1324 <para> 1995 <para>
1325 Начиная с 0.8.25, именованные выделения в регулярном выражении создают 1996 Именованные выделения в регулярном выражении создают переменные (0.8.25),
1326 переменные, которые могут затем использоваться в других директивах: 1997 которые могут затем использоваться в других директивах:
1327 <example> 1998 <example>
1328 server { 1999 server {
1329 server_name ~^(www\.)?(<emphasis>?&lt;domain&gt;</emphasis>.+)$; 2000 server_name ~^(www\.)?(?&lt;domain&gt;.+)$;
1330 2001
1331 location / { 2002 location / {
1332 root /sites/<emphasis>$domain</emphasis>; 2003 root /sites/$domain;
1333 } 2004 }
1334 } 2005 }
1335 2006
1336 server { 2007 server {
1337 server_name _; 2008 server_name _;
1338 2009
1339 location / { 2010 location / {
1340 root /sites/default; 2011 root /sites/default;
1341 } 2012 }
1342 } 2013 }
1343 </example> 2014 </example>
1344 </para> 2015 </para>
1345 2016
1346 <para> 2017 <para>
1347 Начиная с 0.7.11, можно использовать пустое имя "": 2018 Возможно также указать пустое имя сервера (0.7.11):
1348 <example> 2019 <example>
1349 server { 2020 server {
1350 server_name www.example.com ""; 2021 server_name www.example.com "";
1351 } 2022 }
1352 </example> 2023 </example>
1353 что позволяет обрабатывать запросы без строки "Host" в заголовке запроса 2024 Это позволяет обрабатывать запросы без поля <header>Host</header> заголовка
1354 в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт. 2025 запроса в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт.
2026 Это настройка по умолчанию.
2027 <note>
2028 До 0.8.48 по умолчанию использовалось имя хоста (hostname) машины.
2029 </note>
1355 </para> 2030 </para>
1356 2031
1357 <para> 2032 <para>
1358 Порядок проверки имён следующий: 2033 Порядок проверки имён следующий:
1359 <list type="bullet"> 2034 <list type="enum">
1360 2035
1361 <listitem> 2036 <listitem>
1362 полные имена, 2037 полные имена
1363 </listitem> 2038 </listitem>
1364 2039
1365 <listitem> 2040 <listitem>
1366 имена с маской в начале имени — *.example.com, 2041 имена с маской в начале имени, например “<code>*.example.com</code>”
1367 </listitem> 2042 </listitem>
1368 2043
1369 <listitem> 2044 <listitem>
1370 имена с маской в конце имени — mail.*, 2045 имена с маской в конце имени, например “<code>mail.*</code>”
1371 </listitem> 2046 </listitem>
1372 2047
1373 <listitem> 2048 <listitem>
1374 регулярные выражения. 2049 регулярные выражения
1375 </listitem> 2050 </listitem>
1376 2051
1377 </list> 2052 </list>
1378 </para> 2053 </para>
1379 2054
1380 </directive> 2055 </directive>
1381 2056
1382 2057
1383 <directive name="server_name_in_redirect"> 2058 <directive name="server_name_in_redirect">
1384 <syntax><value>[on|off]</value></syntax> 2059 <syntax><value>on</value> | <value>off</value></syntax>
2060 <default>off</default>
2061 <context>http</context>
2062 <context>server</context>
2063 <context>location</context>
2064
2065 <para>
2066 Разрешает или запрещает использовать в перенаправлениях, выдаваемых nginx'ом,
2067 основное имя сервера, задаваемое директивой
2068 <link id="server_name"/>.
2069 Если запрещено, то используется имя, указанное в поле <header>Host</header>
2070 заголовка запроса.
2071 Если же этого поля нет, то используется IP-адрес сервера.
2072 </para>
2073
2074 <para>
2075 См. также директиву <link id="port_in_redirect"/>.
2076 </para>
2077
2078 </directive>
2079
2080
2081 <directive name="server_names_hash_bucket_size">
2082 <syntax><argument>размер</argument></syntax>
2083 <default>32|64|128</default>
2084 <context>http</context>
2085
2086 <para>
2087 Задаёт размер корзины в хэш-таблицах имён серверов.
2088 Значение по умолчанию зависит от размера строки кэша процессора.
2089 Подробнее смотрите в документе по
2090 <link doc="../hash.xml">настройке хэшей</link>.
2091 </para>
2092
2093 </directive>
2094
2095
2096 <directive name="server_names_hash_max_size">
2097 <syntax><argument>размер</argument></syntax>
2098 <default>512</default>
2099 <context>http</context>
2100
2101 <para>
2102 Задаёт максимальный <argument>размер</argument> хэш-таблиц имён серверов.
2103 Подробнее смотрите в документе по
2104 <link doc="../hash.xml">настройке хэшей</link>.
2105 </para>
2106
2107 </directive>
2108
2109
2110 <directive name="server_tokens">
2111 <syntax><value>on</value> | <value>off</value></syntax>
1385 <default>on</default> 2112 <default>on</default>
1386 <context>http, server, location</context> 2113 <context>http</context>
1387 2114 <context>server</context>
1388 <para> 2115 <context>location</context>
1389 Директива разрешает или запрещает использовать в редиректах, выдаваемых 2116
1390 nginx'ом, основное имя сервера, задаваемое директивой 2117 <para>
1391 <link id="server_name"/>. 2118 Разрешает или запрещает выдавать версию nginx'а в сообщениях об ошибках и
1392 Если использование основного имени запрещено, то используется имя, 2119 в поле <header>Server</header> заголовка ответа.
1393 указанного в строке "Host" в заголовке запроса. 2120 </para>
1394 Если же этой строки нет, то используется IP-адрес сервера. 2121
1395 </para> 2122 </directive>
1396 2123
1397 </directive> 2124
1398 2125 <directive name="tcp_nodelay">
1399 2126 <syntax><value>on</value> | <value>off</value></syntax>
1400 <directive name="server_names_hash_max_size">
1401 <syntax><value>число</value></syntax>
1402 <default>512</default>
1403 <context>http</context>
1404
1405 <para>
1406 Директива задаёт максимальный размер хэш-таблиц имён серверов.
1407 Подробнее смотри в <link doc="../hash.xml">описании
1408 настройки хэшей</link>.
1409 </para>
1410
1411 </directive>
1412
1413
1414 <directive name="server_names_hash_bucket_size">
1415 <syntax><value>число</value></syntax>
1416 <default>32/64/128</default>
1417 <context>http</context>
1418
1419 <para>
1420 Директива задаёт размер корзины в хэш-таблицах имён серверов.
1421 Значение по умолчанию зависит от размера строки кэша процессора.
1422 Подробнее смотри в <link doc="../hash.xml">описании
1423 настройки хэшей</link>.
1424 </para>
1425
1426 </directive>
1427
1428
1429 <directive name="server_tokens">
1430 <syntax><value>[on|off]</value></syntax>
1431 <default>on</default> 2127 <default>on</default>
1432 <context>http, server, location</context> 2128 <context>http</context>
1433 2129 <context>server</context>
1434 <para> 2130 <context>location</context>
1435 Директива разрешает или запрещает выдавать версию nginx'а 2131
1436 в сообщениях об ошибках и в строке заголовка ответа "Server". 2132 <para>
1437 </para> 2133 Разрешает или запрещает использование опции <c-def>TCP_NODELAY</c-def>.
1438
1439 </directive>
1440
1441
1442 <directive name="tcp_nodelay">
1443 <syntax><value>[on|off]</value></syntax>
1444 <default>on</default>
1445 <context>http, server, location</context>
1446
1447 <para>
1448 Директива разрешает или запрещает использовать опцию TCP_NODELAY.
1449 Опция включаются только при переходе соединения в состояние keep-alive. 2134 Опция включаются только при переходе соединения в состояние keep-alive.
1450 </para> 2135 </para>
1451 2136
1452 </directive> 2137 </directive>
1453 2138
1454 2139
1455 <directive name="tcp_nopush"> 2140 <directive name="tcp_nopush">
1456 <syntax><value>[on|off]</value></syntax> 2141 <syntax><value>on</value> | <value>off</value></syntax>
1457 <default>off</default> 2142 <default>off</default>
1458 <context>http, server, location</context> 2143 <context>http</context>
1459 2144 <context>server</context>
1460 <para> 2145 <context>location</context>
1461 Директива разрешает или запрещает использовать опции 2146
1462 TCP_NOPUSH во FreeBSD или TCP_CORK в Linux. 2147 <para>
2148 Разрешает или запрещает использование опции сокета
2149 <c-def>TCP_NOPUSH</c-def> во FreeBSD или
2150 <c-def>TCP_CORK</c-def> в Linux.
1463 Опции включаются только при использовании <link id="sendfile"/>. 2151 Опции включаются только при использовании <link id="sendfile"/>.
1464 Включение опции позволяет 2152 Включение опции позволяет
1465 <list type="bullet"> 2153 <list type="bullet">
1466 2154
1467 <listitem> 2155 <listitem>
1468 передавать заголовок ответа и начало файла в одном пакете в Linux 2156 передавать заголовок ответа и начало файла в одном пакете
1469 и во FreeBSD 4.x; 2157 в Linux и во FreeBSD&nbsp;4.*;
1470 </listitem> 2158 </listitem>
1471 2159
1472 <listitem> 2160 <listitem>
1473 передавать файл в полных пакетах. 2161 передавать файл полными пакетами.
1474 </listitem> 2162 </listitem>
1475 2163
1476 </list> 2164 </list>
1477 </para> 2165 </para>
1478 2166
1479 </directive> 2167 </directive>
1480 2168
1481 2169
1482 <directive name="try_files"> 2170 <directive name="try_files">
1483 <syntax><value>файл [файл ...] (uri|=код)</value></syntax> 2171 <syntax>
2172 <argument>файл</argument> ...
2173 <argument>uri</argument>
2174 </syntax>
2175 <syntax>
2176 <argument>файл</argument> ...
2177 =<argument>код</argument>
2178 </syntax>
1484 <default/> 2179 <default/>
1485 <context>location</context> 2180 <context>server</context>
1486 2181 <context>location</context>
1487 <para> 2182
1488 Директива проверяет существование файлов в заданном порядке 2183 <para>
1489 и использует для обработки запроса первый найденный файл, причём 2184 Проверяет существование файлов в заданном порядке и использует
1490 обработка делается в контексте этого же location'а. 2185 для обработки запроса первый найденный файл, причём обработка
1491 С помощью слэша в конце имени можно задать проверку существования 2186 делается в контексте этого же location'а.
1492 каталога, например, так — "$uri/". 2187 Путь к файлу строится из аргумента <argument>файл</argument>
1493 В случае, если ни один файл не найден, то делается внутренний редирект 2188 в соответствии с директивами
1494 на последний параметр. 2189 <link id="root"/> и <link id="alias"/>.
1495 Последний параметр может быть кодом (0.7.51): 2190 С помощью слэша в конце имени можно проверить существование каталога,
2191 например, “<code>$uri/</code>”.
2192 В случае, если ни один файл не найден, то делается внутреннее
2193 перенаправление на <argument>uri</argument>, заданный последним аргументом.
2194 Например:
2195 <example>
2196 location /images/ {
2197 try_files $uri /images/default.gif;
2198 }
2199
2200 location = /images/default.gif {
2201 expires 30s;
2202 }
2203 </example>
2204 Последний аргумент может также указывать на именованный location,
2205 смотрите примеры ниже.
2206 С версии 0.7.51 последний аргумент может также быть кодом:
1496 <example> 2207 <example>
1497 location / { 2208 location / {
1498 try_files $uri $uri/index.html $uri.html =404; 2209 try_files $uri $uri/index.html $uri.html =404;
1499 } 2210 }
1500 </example> 2211 </example>
1501 </para> 2212 </para>
1502 2213
1503 <para> 2214 <para>
1504 Пример использования при проксировании Mongrel: 2215 Пример использования при проксировании Mongrel:
1505 <example> 2216 <example>
1506 location / { 2217 location / {
1507 try_files /system/maintenance.html 2218 try_files /system/maintenance.html
1508 $uri $uri/index.html $uri.html 2219 $uri $uri/index.html $uri.html
1509 @mongrel; 2220 @mongrel;
1510 } 2221 }
1511 2222
1512 location @mongrel { 2223 location @mongrel {
1513 proxy_pass http://mongrel; 2224 proxy_pass http://mongrel;
1514 } 2225 }
1515 </example> 2226 </example>
1516 </para> 2227 </para>
1517 2228
1518 <para> 2229 <para>
1519 Пример использования вместе с Drupal/FastCGI: 2230 Пример использования вместе с Drupal/FastCGI:
1520 <example> 2231 <example>
1521 location / { 2232 location / {
1522 try_files $uri $uri/ @drupal; 2233 try_files $uri $uri/ @drupal;
1523 } 2234 }
1524 2235
1525 location ~ \.php$ { 2236 location ~ \.php$ {
1526 try_files $uri @drupal; 2237 try_files $uri @drupal;
1527 2238
1528 fastcgi_pass ...; 2239 fastcgi_pass ...;
1529 2240
1530 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; 2241 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1531 fastcgi_param SCRIPT_NAME $fastcgi_script_name; 2242 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
1532 fastcgi_param QUERY_STRING $args; 2243 fastcgi_param QUERY_STRING $args;
1533 2244
1534 ... прочие fastcgi_param 2245 ... прочие fastcgi_param
1535 } 2246 }
1536 2247
1537 location @drupal { 2248 location @drupal {
1538 fastcgi_pass ...; 2249 fastcgi_pass ...;
1539 2250
1540 fastcgi_param SCRIPT_FILENAME /path/to/index.php; 2251 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1541 fastcgi_param SCRIPT_NAME /index.php; 2252 fastcgi_param SCRIPT_NAME /index.php;
1542 fastcgi_param QUERY_STRING q=$uri&amp;$args; 2253 fastcgi_param QUERY_STRING q=$uri&amp;$args;
1543 2254
1544 ... прочие fastcgi_param 2255 ... прочие fastcgi_param
1545 } 2256 }
1546 </example> 2257 </example>
1547 В этом примере директива try_files 2258 В следующем примере директива <code>try_files</code>
1548 <example> 2259 <example>
1549 location / { 2260 location / {
1550 try_files $uri $uri/ @drupal; 2261 try_files $uri $uri/ @drupal;
1551 } 2262 }
1552 </example> 2263 </example>
1553 аналогична директивам 2264 аналогична директивам
1554 <example> 2265 <example>
1555 location / { 2266 location / {
1556 error_page 404 = @drupal; 2267 error_page 404 = @drupal;
1557 log_not_found off; 2268 log_not_found off;
1558 } 2269 }
1559 </example> 2270 </example>
1560 А здесь 2271 А здесь
1561 <example> 2272 <example>
1562 location ~ \.php$ { 2273 location ~ \.php$ {
1563 try_files $uri @drupal; 2274 try_files $uri @drupal;
1564 2275
1565 fastcgi_pass ...; 2276 fastcgi_pass ...;
1566 2277
1567 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; 2278 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1568 2279
1569 ... 2280 ...
1570 } 2281 }
1571 </example> 2282 </example>
1572 try_files тестирует существование PHP-файла, 2283 <code>try_files</code> проверяет существование PHP-файла,
1573 прежде чем передать запрос FastCGI-серверу. 2284 прежде чем передать запрос FastCGI-серверу.
1574 </para> 2285 </para>
1575 2286
1576 <para> 2287 <para>
1577 Пример использования вместе с Wordpress и Joomla: 2288 Пример использования вместе с Wordpress и Joomla:
1578 <example> 2289 <example>
1579 location / { 2290 location / {
1580 try_files $uri $uri/ @wordpress; 2291 try_files $uri $uri/ @wordpress;
1581 } 2292 }
1582 2293
1583 location ~ \.php$ { 2294 location ~ \.php$ {
1584 try_files $uri @wordpress; 2295 try_files $uri @wordpress;
1585 2296
1586 fastcgi_pass ...; 2297 fastcgi_pass ...;
1587 2298
1588 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; 2299 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1589 ... прочие fastcgi_param 2300 ... прочие fastcgi_param
1590 } 2301 }
1591 2302
1592 location @wordpress { 2303 location @wordpress {
1593 fastcgi_pass ...; 2304 fastcgi_pass ...;
1594 2305
1595 fastcgi_param SCRIPT_FILENAME /path/to/index.php; 2306 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1596 ... прочие fastcgi_param 2307 ... прочие fastcgi_param
1597 } 2308 }
1598 </example> 2309 </example>
1599 </para> 2310 </para>
1600 2311
1606 <default> 2317 <default>
1607 text/html html; 2318 text/html html;
1608 image/gif gif; 2319 image/gif gif;
1609 image/jpeg jpg; 2320 image/jpeg jpg;
1610 </default> 2321 </default>
1611 <context>http, server, location</context> 2322 <context>http</context>
1612 2323 <context>server</context>
1613 <para> 2324 <context>location</context>
1614 Директива задаёт соответствие расширения и MIME-типов ответов. 2325
1615 Одному MIME-типу может соответствовать несколько расширений. 2326 <para>
1616 </para> 2327 Задаёт соответствие расширений имён файлов и MIME-типов ответов.
1617 2328 Расширения нечувствительны к регистру символов.
1618 <para> 2329 Одному MIME-типу может соответствовать несколько расширений, например:
1619 Достаточно полная таблица соответствий входит в дистрибутив 2330 <example>
1620 и находится в файле conf/mime.types. 2331 types {
1621 </para> 2332 application/octet-stream bin exe dll;
1622 2333 application/octet-stream deb;
1623 <para> 2334 application/octet-stream dmg;
1624 Для того, чтобы для определённого location'а для всех ответов выдавался 2335 }
1625 MIME-тип "application/octet-stream", можно использовать следующее: 2336 </example>
2337 </para>
2338
2339 <para>
2340 Достаточно полная таблица соответствий входит в дистрибутив nginx
2341 и находится в файле <path>conf/mime.types</path>.
2342 </para>
2343
2344 <para>
2345 Для того, чтобы для определённого location'а для всех ответов
2346 выдавался MIME-тип “<code>application/octet-stream</code>”,
2347 можно использовать следующее:
1626 <example> 2348 <example>
1627 location /download/ { 2349 location /download/ {
1628 types { } 2350 types { }
1629 default_type application/octet-stream; 2351 default_type application/octet-stream;
1630 } 2352 }
1631 </example> 2353 </example>
2354 </para>
2355
2356 </directive>
2357
2358
2359 <directive name="types_hash_bucket_size">
2360 <syntax><argument>размер</argument></syntax>
2361 <default>32|64|128</default>
2362 <context>http</context>
2363 <context>server</context>
2364 <context>location</context>
2365
2366 <para>
2367 Задаёт размер корзины в хэш-таблицах типов.
2368 Значение по умолчанию зависит от размера строки кэша процессора.
2369 Подробнее смотрите в документе по
2370 <link doc="../hash.xml">настройке хэшей</link>.
2371 </para>
2372
2373 </directive>
2374
2375
2376 <directive name="types_hash_max_size">
2377 <syntax><argument>размер</argument></syntax>
2378 <default>1024</default>
2379 <context>http</context>
2380 <context>server</context>
2381 <context>location</context>
2382
2383 <para>
2384 Задаёт максимальный <argument>размер</argument> хэш-таблиц типов.
2385 Подробнее смотрите в документе по
2386 <link doc="../hash.xml">настройке хэшей</link>.
1632 </para> 2387 </para>
1633 2388
1634 </directive> 2389 </directive>
1635 2390
1636 2391
1637 <directive name="underscores_in_headers"> 2392 <directive name="underscores_in_headers">
1638 <syntax><value>[on|off]</value></syntax> 2393 <syntax><value>on</value> | <value>off</value></syntax>
1639 <default>off</default> 2394 <default>off</default>
1640 <context>http, server</context> 2395 <context>http</context>
1641 2396 <context>server</context>
1642 <para> 2397
1643 Директива разрешает или запрещает использование символов подчёркивания 2398 <para>
1644 в строках заголовка запроса клиента. 2399 Разрешает или запрещает использование символов подчёркивания в
2400 полях заголовка запроса клиента.
2401 Если запрещено, поля заголовка запроса, в чьих именах есть подчёркивания,
2402 помечаются как недопустимые и подпадают под действие директивы
2403 <link id="ignore_invalid_headers"/>.
2404 </para>
2405
2406 </directive>
2407
2408
2409 <directive name="variables_hash_bucket_size">
2410 <syntax><argument>размер</argument></syntax>
2411 <default>64</default>
2412 <context>http</context>
2413
2414 <para>
2415 Задаёт размер корзины в хэш-таблице переменных.
2416 Подробнее смотрите в документе по
2417 <link doc="../hash.xml">настройке хэшей</link>.
2418 </para>
2419
2420 </directive>
2421
2422
2423 <directive name="variables_hash_max_size">
2424 <syntax><argument>размер</argument></syntax>
2425 <default>512</default>
2426 <context>http</context>
2427
2428 <para>
2429 Задаёт максимальный <argument>размер</argument> хэш-таблицы переменных.
2430 Подробнее смотрите в документе по
2431 <link doc="../hash.xml">настройке хэшей</link>.
1645 </para> 2432 </para>
1646 2433
1647 </directive> 2434 </directive>
1648 2435
1649 </section> 2436 </section>
1650 2437
1651 2438 <section id="variables" name="Встроенные переменные">
1652 <section name="Встроенные переменные" id="variables"> 2439
1653 2440 <para>
1654 <para> 2441 Модуль <code>ngx_http_core_module</code> поддерживает встроенные переменные,
1655 Модуль ngx_http_core_module поддерживает встроенные переменные, имена 2442 имена которых совпадают с именами переменных веб-сервера Apache.
1656 которых совпадают с именами переменных в Apache. 2443 Прежде всего, это переменные, представляющие из себя поля заголовка
1657 Прежде всего, это переменные, представляющие из себя строки заголовка 2444 запроса клиента, такие как <var>$http_user_agent</var>, <var>$http_cookie</var>
1658 запроса клиента, например, $http_user_agent, $http_cookie 2445 и тому подобное.
1659 и тому подобное. Кроме того, есть и другие переменные: 2446 Кроме того, есть и другие переменные:
1660 <list type="bullet"> 2447 <list type="tag">
1661 2448
1662 <listitem> 2449 <tag-name><var>$arg_</var><argument>имя</argument></tag-name>
1663 $args, эта переменная равна аргументам в строке запроса; 2450 <tag-desc>
1664 </listitem> 2451 аргумент <argument>имя</argument> в строке запроса
1665 2452 </tag-desc>
1666 <listitem> 2453
1667 $arg_<value>name</value>, эта переменная равна аргументу <value>name</value> 2454 <tag-name><var>$args</var></tag-name>
1668 в строке запроса; 2455 <tag-desc>
1669 </listitem> 2456 аргументы в строке запроса
1670 2457 </tag-desc>
1671 <listitem> 2458
1672 $binary_remote_addr, эта переменная равна адресу клиента в бинарном виде, 2459 <tag-name><var>$binary_remote_addr</var></tag-name>
1673 длина её значения всегда 4 байта; 2460 <tag-desc>
1674 </listitem> 2461 адрес клиента в бинарном виде, длина значения всегда 4 байта
1675 2462 </tag-desc>
1676 <listitem> 2463
1677 $content_length, эта переменная равна строке "Content-Length" в заголовке 2464 <tag-name><var>$body_bytes_sent</var></tag-name>
1678 запроса; 2465 <tag-desc>
1679 </listitem> 2466 число байт, переданное клиенту, без учёта заголовка ответа
1680 2467 </tag-desc>
1681 <listitem> 2468
1682 $content_type, эта переменная равна строке "Content-Type" в заголовке запроса; 2469 <tag-name><var>$content_length</var></tag-name>
1683 </listitem> 2470 <tag-desc>
1684 2471 поле <header>Content-Length</header> заголовка запроса
1685 <listitem> 2472 </tag-desc>
1686 $cookie_<value>name</value>, эта переменная равна cookie <value>name</value>; 2473
1687 </listitem> 2474 <tag-name><var>$content_type</var></tag-name>
1688 2475 <tag-desc>
1689 <listitem> 2476 поле <header>Content-Type</header> заголовка запроса
1690 $document_root, эта переменная равна значению директивы root для 2477 </tag-desc>
1691 текущего запроса; 2478
1692 </listitem> 2479 <tag-name><var>$cookie_</var><argument>имя</argument></tag-name>
1693 2480 <tag-desc>
1694 <listitem> 2481 cookie <argument>имя</argument>
1695 $document_uri, то же самое, что и $uri; 2482 </tag-desc>
1696 </listitem> 2483
1697 2484 <tag-name><var>$document_root</var></tag-name>
1698 <listitem> 2485 <tag-desc>
1699 $host, эта переменная равна строке "Host" в заголовке запроса 2486 значение директивы <link id="root"/> для текущего запроса
1700 или имени сервера, на который пришёл запрос, если этой строки нет; 2487 </tag-desc>
1701 </listitem> 2488
1702 2489 <tag-name><var>$document_uri</var></tag-name>
1703 <listitem> 2490 <tag-desc>
1704 $hostname, эта переменная равна имени хоста; 2491 то же, что и <var>$uri</var>
1705 </listitem> 2492 </tag-desc>
1706 2493
1707 <listitem> 2494 <tag-name><var>$host</var></tag-name>
1708 $http_<value>name</value>, эта переменная равна строке <value>name</value> 2495 <tag-desc>
1709 в заголовке запроса; 2496 поле <header>Host</header> заголовка запроса,
1710 </listitem> 2497 или имя сервера, соответствующего запросу, если этого поля нет
1711 2498 </tag-desc>
1712 <listitem> 2499
1713 $is_args, эта переменная равна "?", если в строке запроса есть аргументы, 2500 <tag-name><var>$hostname</var></tag-name>
1714 и пустой строке, если их нет; 2501 <tag-desc>
1715 </listitem> 2502 имя хоста
1716 2503 </tag-desc>
1717 <listitem> 2504
1718 $limit_rate, эта переменная позволяет установить ограничение 2505 <tag-name><var>$http_</var><argument>имя</argument></tag-name>
1719 скорости соединения; 2506 <tag-desc>
1720 </listitem> 2507 поле <argument>имя</argument> заголовка запроса
1721 2508 </tag-desc>
1722 <listitem> 2509
1723 $pid, эта переменная равна номеру рабочего процесса; 2510 <tag-name><var>$https</var></tag-name>
1724 </listitem> 2511 <tag-desc>
1725 2512 “<code>on</code>”
1726 <listitem> 2513 если соединение работает в режиме SSL,
1727 $request_method, эта переменная равна методу запроса, 2514 либо пустая строка
1728 обычно это "GET" или "POST"; 2515 </tag-desc>
1729 </listitem> 2516
1730 2517 <tag-name><var>$is_args</var></tag-name>
1731 <listitem> 2518 <tag-desc>
1732 $remote_addr, эта переменная равна адресу клиента; 2519 “<code>?</code>”, если в строке запроса есть аргументы,
1733 </listitem> 2520 и пустая строка, если их нет
1734 2521 </tag-desc>
1735 <listitem> 2522
1736 $remote_port, эта переменная равна порту клиента; 2523 <tag-name><var>$limit_rate</var></tag-name>
1737 </listitem> 2524 <tag-desc>
1738 2525 позволяет ограничивать скорость соединения
1739 <listitem> 2526 </tag-desc>
1740 $remote_user, эта переменная равна имени пользователя, используемого 2527
1741 в Basic аутентификации; 2528 <tag-name><var>$nginx_version</var></tag-name>
1742 </listitem> 2529 <tag-desc>
1743 2530 версия nginx
1744 <listitem> 2531 </tag-desc>
1745 $realpath_root, эта переменная равна значению директивы root для 2532
1746 текущего запроса, при этом все символические ссылки преобразованы 2533 <tag-name><var>$pid</var></tag-name>
1747 в реальные путь; 2534 <tag-desc>
1748 </listitem> 2535 номер (PID) рабочего процесса
1749 2536 </tag-desc>
1750 <listitem> 2537
1751 $request_filename, эта переменная равна пути к файлу для текущего 2538 <tag-name><var>$query_string</var></tag-name>
1752 запроса, формируемому из директив root или alias и URI запроса; 2539 <tag-desc>
1753 </listitem> 2540 то же, что и <var>$args</var>
1754 2541 </tag-desc>
1755 <listitem> 2542
1756 $request_body, эта переменная содержит тело запроса. 2543 <tag-name><var>$realpath_root</var></tag-name>
1757 Значение переменной появляется в location'ах, обрабатываемых директивами 2544 <tag-desc>
2545 значение директивы <link id="root"/> для текущего запроса,
2546 при этом все символические ссылки преобразованы в реальные путь
2547 </tag-desc>
2548
2549 <tag-name><var>$remote_addr</var></tag-name>
2550 <tag-desc>
2551 адрес клиента
2552 </tag-desc>
2553
2554 <tag-name><var>$remote_port</var></tag-name>
2555 <tag-desc>
2556 порт клиента
2557 </tag-desc>
2558
2559 <tag-name><var>$remote_user</var></tag-name>
2560 <tag-desc>
2561 имя пользователя, использованное в Basic аутентификации
2562 </tag-desc>
2563
2564 <tag-name><var>$request</var></tag-name>
2565 <tag-desc>
2566 оригинальная строка запроса целиком
2567 </tag-desc>
2568
2569 <tag-name><var>$request_body</var></tag-name>
2570 <tag-desc>
2571 тело запроса
2572 <para>
2573 Значение переменной появляется в location'ах, обрабатываемых
2574 директивами
1758 <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/> 2575 <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>
1759 и <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>. 2576 и
1760 </listitem> 2577 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>.
1761 2578 </para>
1762 <listitem> 2579 </tag-desc>
1763 $request_body_file, эта переменная равна имени временного файла, в котором 2580
1764 хранится тело запроса. 2581 <tag-name><var>$request_body_file</var></tag-name>
1765 По завершению работы файл необходимо удалить. 2582 <tag-desc>
1766 Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно 2583 имя временного файла, в котором хранится тело запроса
1767 указать <link doc="ngx_http_core_module.xml" id="client_body_in_file_only">client_body_in_file_only on</link>. 2584 <para>
1768 При передаче имени в проксированном запросе или в запросе к FastCGI-серверу 2585 По завершению обработки файл необходимо удалить.
1769 следует запретить передачу самого тела директивами 2586 Для того, чтобы тело запроса всегда записывалось в файл,
1770 "proxy_pass_request_body off" или 2587 следует указать
1771 "fastcgi_pass_request_body off" соответственно. 2588 <link id="client_body_in_file_only">client_body_in_file_only on</link>.
1772 </listitem> 2589 При передаче имени временного файла в проксированном запросе
1773 2590 или в запросе к FastCGI-серверу следует запретить передачу самого
1774 <listitem> 2591 тела директивами
1775 $request_uri, эта переменная равна полному первоначальному URI вместе 2592 <link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body">
1776 с аргументами; 2593 proxy_pass_request_body off</link>
1777 </listitem> 2594 или
1778 2595 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body">
1779 <listitem> 2596 fastcgi_pass_request_body off</link>
1780 $query_string, то же самое, что и $args; 2597 соответственно.
1781 </listitem> 2598 </para>
1782 2599 </tag-desc>
1783 <listitem> 2600
1784 $scheme, эта переменная равна схеме запроса — "http" или "https"; 2601 <tag-name><var>$request_completion</var></tag-name>
1785 </listitem> 2602 <tag-desc>
1786 2603 “<code>OK</code>” если запрос завершился,
1787 <listitem> 2604 либо пустая строка
1788 $server_protocol, эта переменная равна протоколу запроса, 2605 </tag-desc>
1789 обычно это "HTTP/1.0" или "HTTP/1.1"; 2606
1790 </listitem> 2607 <tag-name><var>$request_filename</var></tag-name>
1791 2608 <tag-desc>
1792 <listitem> 2609 путь к файлу для текущего запроса, формируемый из директив
1793 $server_addr, эта переменная равна адресу сервера, на который пришёл запрос. 2610 <link id="root"/> или <link id="alias"/> и URI запроса
1794 Как правило, для получения значения этой переменной делается один системный 2611 </tag-desc>
1795 вызов. Для того, чтобы избежать системного вызова, нужно указывать 2612
1796 адреса в директивах listen и использовать параметр bind; 2613 <tag-name><var>$request_method</var></tag-name>
1797 </listitem> 2614 <tag-desc>
1798 2615 метод запроса, обычно
1799 <listitem> 2616 “<code>GET</code>” или “<code>POST</code>”
1800 $server_name, эта переменная равна имени сервера, на который пришёл запрос; 2617 </tag-desc>
1801 </listitem> 2618
1802 2619 <tag-name><var>$request_uri</var></tag-name>
1803 <listitem> 2620 <tag-desc>
1804 $server_port, эта переменная равна порту сервера, на который пришёл запрос; 2621 оригинальный URI запроса целиком (с аргументами)
1805 </listitem> 2622 </tag-desc>
1806 2623
1807 <listitem> 2624 <tag-name><var>$scheme</var></tag-name>
1808 $uri, эта переменная равна текущему URI в запросе, он 2625 <tag-desc>
1809 может отличаться от первоначального, например, при внутренних редиректах 2626 схема запроса, “<code>http</code>” или “<code>https</code>”
1810 или при использовании индексных файлов. 2627 </tag-desc>
1811 </listitem> 2628
2629 <tag-name><var>$sent_http_</var><argument>имя</argument></tag-name>
2630 <tag-desc>
2631 поле <argument>имя</argument> заголовка ответа
2632 </tag-desc>
2633
2634 <tag-name><var>$server_addr</var></tag-name>
2635 <tag-desc>
2636 адрес сервера, принявшего запрос
2637 <para>
2638 Получение значения этой переменной обычно требует одного системного вызова.
2639 Чтобы избежать системного вызова, в директивах <link id="listen"/>
2640 следует указывать адреса и использовать параметр <parameter>bind</parameter>.
2641 </para>
2642 </tag-desc>
2643
2644 <tag-name><var>$server_name</var></tag-name>
2645 <tag-desc>
2646 имя сервера, принявшего запрос
2647 </tag-desc>
2648
2649 <tag-name><var>$server_port</var></tag-name>
2650 <tag-desc>
2651 порт сервера, принявшего запрос
2652 </tag-desc>
2653
2654 <tag-name><var>$server_protocol</var></tag-name>
2655 <tag-desc>
2656 протокол сервера, обычно
2657 “<code>HTTP/1.0</code>”
2658 или
2659 “<code>HTTP/1.1</code>”
2660 </tag-desc>
2661
2662 <tag-name><var>$uri</var></tag-name>
2663 <tag-desc>
2664 текущий URI запроса
2665 <para>
2666 Он может отличаться от первоначального, например, при внутренних
2667 перенаправлениях или при использовании индексных файлов.
2668 </para>
2669 </tag-desc>
1812 2670
1813 </list> 2671 </list>
1814 </para> 2672 </para>
1815 2673
1816 </section> 2674 </section>