Contents 1 ngx_http_core_module 1.1 Директивы 1.2 Встроенные переменные 1.3 alias 1.4 client_body_in_file_only 1.5 client_body_buffer_size 1.6 client_body_temp_path 1.7 client_body_timeout 1.8 client_header_buffer_size 1.9 client_header_timeout 1.10 client_max_body_size 1.11 default_type 1.12 error_page 1.13 internal 1.14 keepalive_timeout 1.15 large_client_header_buffers 1.16 limit_except 1.17 limit_rate 1.18 listen 1.19 location 1.20 msie_padding 1.21 msie_refresh 1.22 optimize_server_names 1.23 port_in_redirect 1.24 recursive_error_pages 1.25 root 1.26 satisfy_any 1.27 send_timeout 1.28 sendfile 1.29 server 1.30 server_name 1.31 server_names_hash_max_size 1.32 server_names_hash_bucket_size 1.33 tcp_nodelay 1.34 tcp_nopush 1.35 types 1.36 Встроенные переменные

[edit] ngx_http_core_module

[edit] Директивы

• [#alias alias]
• [#client_body_in_file_only client_body_in_file_only]
• [#client_body_buffer_size client_body_buffer_size]
• [#client_body_temp_path client_body_temp_path]
• [#client_body_timeout client_body_timeout]
• [#client_header_buffer_size client_header_buffer_size]
• [#client_header_timeout client_header_timeout]
• [#client_max_body_size client_max_body_size]
• [#default_type default_type]
• [#error_page error_page]
• [#internal internal]
• [#keepalive_timeout keepalive_timeout]
• [#large_client_header_buffers large_client_header_buffers]
• [#limit_except limit_except]
• [#limit_rate limit_rate]
• [#listen listen]
• [#location location]
• [#msie_padding msie_padding]
• [#msie_refresh msie_refresh]
• [#optimize_server_names optimize_server_names]
• [#port_in_redirect port_in_redirect]
• [#recursive_error_pages recursive_error_pages]
• [#root root]
• [#satisfy_any satisfy_any]
• [#send_timeout send_timeout]
• [#sendfile sendfile]
• [#server server]
• [#server_name server_name]
• [#server_names_hash_max_size server_names_hash_max_size]
• [#server_names_hash_bucket_size server_names_hash_bucket_size]
• [#tcp_nodelay tcp_nodelay]
• [#tcp_nopush tcp_nopush]
• [#types types]

[edit] Встроенные переменные

• [#var_args $args]
• [#var_content_length $content_length]
• [#var_content_type $content_type]
• [#var_document_root $document_root]
• [#var_document_uri $document_uri]
• [#var_host $host]
• [#var_http_user_agent $http_user_agent]
• [#var_http_cookie $http_cookie]
• [#var_limit_rate $limit_rate]
• [#var_request_method $request_method]
• [#var_remote_addr $remote_addr]
• [#var_remote_port $remote_port]
• [#var_remote_user $remote_user]
• [#var_request_filename $request_filename]
• [#var_request_uri $request_uri]
• [#var_query_string $query_string]
• [#var_server_protocol $server_protocol]
• [#var_server_addr $server_addr]
• [#var_server_name $server_name]
• [#var_server_port $server_port]
• [#var_uri $uri]

Template:Anchor

[edit] alias

syntax: alias путь default: нет context: location

Директива задаёт замену для указанного location. Например, при такой конфигурации

location  /i/ {
: alias  /spool/w3/images/;
}

на запрос "/i/top.gif" будет отдан файл "/spool/w3/images/top.gif".

В значении пути можно использовать переменные. Директива alias не может использоваться внутри location, заданного регулярным выражением.

Template:Anchor

[edit] client_body_in_file_only

syntax: client_body_in_file_only on|off

default: client_body_in_file_only off

context: http, server, location

Директива определяет, сохранять ли всё тело запроса клиента в файл. Необходимо учитывать, что при разрешной директиве файл по окончании запроса не удаляется. Директиву можно использовать для отладки и при использовании метода $r->request_body_file модуля ngx_http_perl_module.

Template:Anchor

[edit] client_body_buffer_size

syntax: client_body_buffer_size размер default: client_body_buffer_size 8k/16k context: http, server, location

Директива задаёт размер буфера для чтения тела запроса клиента. Если тело запроса больше заданного буфера, то всё тело запроса или только его часть записывается во временный файл. По умолчанию размер одного буфера равен двум размерам страницы, в зависимости от платформы это или 8K, или 16K.

Template:Anchor

[edit] client_body_temp_path

syntax: client_body_temp_path путь [ уровень1 [ уровень2 [ уровень3 ]

default: client_body_temp_path client_body_temp

context: http, server, location

Директива задаёт имя каталога для хранения временных файлов с телом запроса клиента. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации

: client_body_temp_path  /spool/nginx/client_temp 1 2;

имя временного будет такого вида:

: /spool/nginx/client_temp/7/45/00000123457

Template:Anchor

[edit] client_body_timeout

syntax: client_body_timeout время default: client_body_timeout 60 context: http, server, location

Директива задаёт таймаут при чтении тела запроса клиента. Таймаут устанавливается не на всю передачу тела запроса, а только между двумя операциями чтения. Если по истечении этого времени клиент ничего не передаст, то ему возвращается ошибка "Request time out" (408).

Template:Anchor

[edit] client_header_buffer_size

syntax: client_header_buffer_size размер

default: client_header_buffer_size 1k

context: http, server

Директива задаёт размер буфера для чтения заголовка запроса клиента. Для подавляющего большинства запросов вполне достаточно буфера размером в 1K. Однако если в запросе есть большие cookies или же запрос пришёл от wap-клиента, то он может не поместиться в 1K. Поэтому, если строка запроса или строка заголовка запроса не помещается полностью в этот буфер, то выделяются большие буферы, задаваемые директивой large_client_header_buffers.

Template:Anchor

[edit] client_header_timeout

syntax: client_header_timeout время

default: client_header_timeout 60

context: http, server

Директива задаёт таймаут при чтении заголовка запроса клиента. Если по истечении этого времени клиент не передаст полностью заголовок запроса, то ему возвращается ошибка "Request time out" (408).

Template:Anchor

[edit] client_max_body_size

syntax: client_max_body_size размер default: client_max_body_size 1m context: http, server, location

Директива задаёт максимально допустимый размер тела запроса клиента, указываемый в строке "Content-Length" в заголовке запроса. Если размер больше заданного, то клиенту возвращается ошибка "Request Entity Too Large" (413). Следует иметь в виду, что браузеры не умеют корректно показывать эту ошибку.

Template:Anchor

[edit] default_type

syntax: default_type MIME-тип default: default_type text/plain context: http, server, location

Директива задаёт MIME-тип ответов по умолчанию.

Template:Anchor

[edit] error_page

syntax: error_page код [код ...] [=|=ответ] uri

default: нет

context: http, server, location, if в location

Директива задаёт URI, который будет показываться для указанных ошибок. В URI можно использовать переменные.

Пример использования:

: error_page   404          /404.html;
: error_page   502 503 504  /50x.html;
: error_page   403          http://example.com/forbidden.html;

Кроме того, можно поменять код ответа на другой, например:

: error_page   404  =200  /empty.gif;

Если ошибочный ответ обрабатывается проксированным сервером или FastCGI-сервером и этот сервер может вернуть разные коды ответов, например, 200, 302, 401 или 404, то можно выдавать возвращаемый код:

: error_page   404  =  /404.php;

Template:Anchor

[edit] internal

syntax: internal

default: нет

context: location

Директива указывает, что данный location может использоваться только для внутренних запросов. Для внешних запросов будет возвращаться ошибка "Not found" (404). Внутренними запросами являются

• запросы, перенаправленные директивой error_page;
• подзапросы, формируемые командой include virtual модуля ngx_http_ssi_module;
• запросы, изменённые директивой rewrite модуля ngx_http_rewrite_module.

Пример использования:

: error_page   404   /404.html;

: location  /404.html {
: internal;
: }

Template:Anchor

[edit] keepalive_timeout

syntax: keepalive_timeout время [время]

default: keepalive_timeout 75

context: http, server, location

Директива задаёт таймаут, в течение которого keep-alive соединение с клиентом не будет закрыто со стороны сервера. Второй параметр задаёт значение в строке "Keep-Alive: timeout=время" в заголовке ответа. Параметры могут отличаться друг от друга. Строку "Keep-Alive: timeout=время" понимают Mozilla и Konqueror. MSIE сам закрывает keep-alive соединение примерно через 60 секунд.

Template:Anchor

[edit] large_client_header_buffers

syntax: large_client_header_buffers число размер

default: large_client_header_buffers 4 4k/8k

context: http, server

Директива задаёт максимальное число и размер буферов для чтения большого заголовка запроса клиента. Строка запроса должна быть не больше размера одного буфера, иначе клиенту возвращается ошибка "Request URI too large" (414). Длинная строка заголовка запроса также должна быть не больше размера одного буфера, иначе клиенту возвращается ошибка "Bad request" (400). Буферы выделяются только по мере необходимости. По умолчанию размер одного буфера равен размеру страницы, в зависимости от платформы это или 4K, или 8K. Если по окончании обработки запроса соединение переходит в состояние keep-alive, то эти буферы освобождаются.

Template:Anchor

[edit] limit_except

syntax: limit_except методы { ... }

default: нет

context: location

Директива ограничивает HTTP-методы, доступные внутри location. Для ограничения могут использоваться директивы модулей ngx_http_access_module и ngx_http_auth_basic_module:

: limit_except  GET {
: allow  192.168.1.0/32;
: deny   all;
: }

Template:Anchor

[edit] limit_rate

syntax: limit_rate скорость

default: нет

context: http, server, location, if в location

Директива задаёт скорость передачи ответа клиенту. Скорость задаётся в байтах в секунду. Ограничение работает только для одного соединения, то есть, если клиент откроет 2 соединения, то суммарная скорость будет в 2 раза выше ограниченной.

Если необходимо ограничить скорость для части клиентов на уровне сервера, то директива limit_rate для этого не подходит. Вместо этого следует задать нужную скорость переменной $limit_rate:

: server {

: if ($slow) {
: set $limit_rate  4k;
: }

: ...
: }

Template:Anchor

[edit] listen

syntax: listen адрес:порт [default [backlog=число | rcvbuf=размер | sndbuf=размер | accept_filter=фильтр | deferred | bind ] default: listen 80

context: server

Директива задаёт адрес и порт, на которых сервер принимает запросы. Можно указать только адрес или только порт, кроме того, адрес может быть именем сервера, например:

: listen  127.0.0.1:8000;
: listen  127.0.0.1;
: listen  8000;
: listen  *:8000;
: listen  localhost:8000;

Если указан только адрес, то используется порт 80.

Если у директивы есть параметр default, то сервер, в котором описана эта директива, будет сервером по умолчанию для указанной пары адрес:порт. Если же директив с параметром default нет, то сервером по умолчанию будет первый сервер, в котором описана пара адрес:порт.

В директиве listen с параметром default можно также указать несколько параметров, специфичных для системных вызовов listen(2) и bind(2).

• backlog=число — задаёт параметр backlog в вызове listen(2). По умолчанию backlog равен -1.
• rcvbuf=размер — задаёт параметр SO_RCVBUF для слушающего сокета.
• sndbuf=размер — задаёт параметр SO_SNDBUF для слушающего сокета.
• accept_filter=фильтр — задаёт название accept-фильтра. Работает только на FreeBSD, можно использовать два фильтра — dataready и httpready. По сигналу -HUP accept-фильтр можно менять только в самых последних версиях FreeBSD: 6.0, 5.4-STABLE и 4.11-STABLE.
• deferred — указывает использовать отложенный accept(2) на Linux с помощью опции TCP_DEFER_ACCEPT.
• bind — указывает, что для данной пары адрес:порт нужно делать bind(2) отдельно. Дело в том, что если описаны несколько директив listen с одинаковым портом, но разными адресами и одна из директив listen слушает на всех адресах для данного порта (*:порт), то nginx сделает bind(2) только на *:порт. Необходимо учитывать, что в этом случае для определения адреса, на которой пришло соединение, делается системный вызов getsockname(). Если же используются параметры backlog, rcvbuf, sndbuf, accept_filter или deferred, то для данной пары адрес:порт bind(2) всегда делается отдельно.

Пример использования параметров:

: listen  127.0.0.1 default accept_filter=dataready backlog=1024;

Template:Anchor

[edit] location

syntax: location [=|~|~*|^~] /uri/ { ... }

default: нет

context: server

Директива устанавливает конфигурацию в зависимости от URI запроса. location можно задать обычной строкой или регулярным выражением. Регулярные выражения задаются префиксом "~*" — без учёта регистра символов, и "~" — с учётом. Для определения соответствия location'а и запроса сначала проверяются location'ы, заданные обычными строками. Среди них ищется максимальное совпадение. Так как строки лексически отсортированы, то поиск прекращается, как только URI становится лексически больше location'а. Конфигурация максимально совпавшего location'а запоминается. Затем проверяются регулярные выражения. В отличие от обычных строк, они не сортируются, а проверяются в порядке их следования в конфигурационном файле. И, кроме того, поиск прекращается уже после первого совпадения.

Если нужно запретить проверку регулярных выражений после проверки обычных строк, то это можно сделать с помощью префикса "^~". Если у максимально совпавшего location'а есть этот префикс, то регулярные выражения не проверяются.

Кроме того, с помощью префикса "=" можно задать точное совпадение URI и location. При совпадении поиск сразу же прекращается, так как дальше искать не имеет смысла. Например, если запрос "/" очень частый, то указав "location = /", можно ускорить обработку этого запроса, так как поиск location прекратится после первого же сравнения.

Проиллюстрируем вышесказанное примером:

: location  = / {
: [ конфигурация A ] 
: }

: location  / {
: [ конфигурация B ] 
: }

: location ^~ /images/ {
: [ конфигурация C ] 
: }

: location ~* \.(gif|jpg|jpeg)$ {
: [ конфигурация D ] 
: }

Для запроса "/" будет выбрана конфигурация A, для запроса "/documents/document.html" — конфигурация B, для запроса "/images/1.gif" — конфигурация C, для запроса "/documents/1.jpg" — конфигурация D.

Template:Anchor

[edit] msie_padding

syntax: msie_padding [on|off]

default: msie_padding on

context: http, server, location

Директива разрешает или запрещает добавлять в ответы для MSIE со статусом больше 400 комментарий для увеличения размера ответа до 512 байт.

Template:Anchor

[edit] msie_refresh

syntax: msie_refresh [on|off]

default: msie_refresh off

context: http, server, location

Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо редиректов.

Template:Anchor

[edit] optimize_server_names

syntax: optimize_server_names [on|off]

default: optimize_server_names on

context: http, server

Директива разрешает или запрещает оптимизировать проверку имени хоста в name-based виртуальных серверах. Проверка в частности влияет на имя хоста, используемого в редиректах. Если оптимизация разрешена и все name-based сервера, слушающие на одной паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения запроса имена не проверяются и в редиректах используется первое имя сервера. Если в редиректе нужно использовать имя хоста, переданное клиентом, то оптимизацию нужно выключить.

Template:Anchor

[edit] port_in_redirect

syntax: port_in_redirect [on|off]

default: port_in_redirect on

context: http, server, location

Директива разрешает или запрещает указывать порт в редиректах, выдаваемых nginx'ом.

Template:Anchor

[edit] recursive_error_pages

syntax: recursive_error_pages [on|off]

default: recursive_error_pages off

context: http, server, location

Директива разрешает или запрещает делать несколько перенаправлений через директиву error_page.

Template:Anchor

[edit] root

syntax: root путь

default: root html

context: http, server, location, if в location

Директива задаёт корневой каталог для запросов. Например, при такой конфигурации

: location  /i/ {
: root  /spool/w3;
: }

на запрос "/i/top.gif" будет отдан файл "/spool/w3/i/top.gif". В значении пути можно использовать переменные.

Template:Anchor

[edit] satisfy_any

syntax: satisfy_any on|off

default: satisfy_any off

context: location

Директива разрешает доступ при хотя бы одной успешной проверке, выполненной модулями ngx_http_access_module или ngx_http_auth_basic_module:

: location / {
: satisfy_any  on;

: allow  192.168.1.0/32;
: deny   all;

: auth_basic            "closed site";
: auth_basic_user_file  conf/htpasswd;
: }

Template:Anchor

[edit] send_timeout

syntax: send_timeout время

default: send_timeout 60

context: http, server, location

Директива задаёт таймаут при передаче ответа клиенту. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени клиент ничего не примет, то nginx закрывает соединение.

Template:Anchor

[edit] sendfile

syntax: sendfile [on|off]

default: sendfile off

context: http, server, location

Директива разрешает или запрещает использовать sendfile().

Template:Anchor

[edit] server

syntax: server { ... }

default: нет

context: http

Директива задаёт конфигурацию для виртуального сервера. Чёткого разделения виртуальных серверов ip-based (на основании ip-адреса) и name-based (на основании имени, передаваемого в строке "Host" заголовка запроса), нет. Вместо этого директивами listen описываются все адреса и порты, на которых нужно принимать соединения для этого сервера, и в директиве server_name указываются все имена серверов. Пример конфигурации описан в настройке виртуальных серверов.

Template:Anchor

[edit] server_name

syntax: server_name имя [...] default: server_name hostname context: server

Директива задаёт имена виртуального сервера, например:

: server {
: server_name   example.com  www.example.com;
: }

Первое имя становится основным именем сервера. По умолчанию используется имя машины (hostname). В именах серверов можно использовать "*" для замены первой части имени:

: server {
: server_name   example.com  *.example.com;
: }

Два вышеприведённых имени можно объединить в одно:

: server {
: server_name   .example.com;
: }

Если строка "Host" в запросе не совпала ни с одним описаным сервером или маской и в ответ на запрос выдаётся редирект, то в редиректе будет использовано основное имя сервера. Если же нужно использовать имя, пришедшее строке запроса "Host", то нужно использовать маску "*":

: server {
: server_name   www.example.com  *;
: }

Template:Anchor

[edit] server_names_hash_max_size

syntax: server_names_hash_max_size число

default: server_names_hash_max_size 512

context: http

Директива задаёт максимальный размер хэш-таблиц имён серверов. Подробнее смотри в описании настройки хэшей.

{{Anchor|server_names_hash_bucket_size)

[edit] server_names_hash_bucket_size

syntax: server_names_hash_bucket_size число

default: server_names_hash_bucket_size 32/64/128

context: http

Директива задаёт размер корзины в хэш-таблицах имён серверов. Значение по умолчанию зависит от размера строки кэша процессора. Подробнее смотри в описании настройки хэшей.

Template:Anchor

[edit] tcp_nodelay

syntax: tcp_nodelay [on|off]

default: tcp_nodelay on

context: http, server, location

Директива разрешает или запрещает использовать опцию TCP_NODELAY. Опция включаются только при переходе соединения в состояние keep-alive.

Template:Anchor

[edit] tcp_nopush

syntax: tcp_nopush [on|off] default: tcp_nopush off context: http, server, location

Директива разрешает или запрещает использовать опции TCP_NOPUSH во FreeBSD или TCP_CORK в Linux. Опции включаются только при использовании sendfile. Включение опции позволяет

• передавать заголовок ответа и начало файла в одном пакете в Linux и во FreeBSD 4.x;
• передавать файл в полных пакетах.

Template:Anchor

[edit] types

syntax: types { ... }

context: http, server, location

Директива задаёт соответствие расширения и MIME-типов ответов. Одному MIME-типу может соответствовать несколько расширений. По умолчанию используется такие соответствия:

: types {
: text/html    html;
: image/gif    gif;
: image/jpeg   jpg;
: }

Достаточно полная таблица соотвествий входит в дистрибутив и находится в файле conf/mime.types.

Для того, чтобы для определённого location'а для всех ответов выдавался MIME-тип "application/octet-stream", можно использовать следующее:

: location /download/ {
: types         { }
: default_type  application/octet-stream;
: }

[edit] Встроенные переменные

Модуль ngx_http_core_module поддерживает встроенные переменные, имена которых совпадают с именами переменных в Apache. Прежде всего, это переменные, представляющие из себя строки заголовка запроса клиента, например, $http_user_agent, $http_cookie и тому подобное. Кроме того, есть и другие переменные:

• $args, эта переменная равна аргументам в строке запроса;
• Template:Anchor$content_length, эта переменная равна строке "Content-Length" в заголовке запроса;
• Template:Anchor$content_type, эта переменная равна строке "Content-Type" в заголовке запроса;
• Template:Anchor$document_root, эта переменная равна значению директивы root для текущего запроса;
• Template:Anchor$document_uri, то же самое, что и $uri;
• Template:Anchor$host, эта переменная равна строке "Host" в заголовке запроса или имени сервера, на который пришёл запрос, если этой строки нет;
• Template:Anchor$limit_rate, эта переменная позволяет установить ограничие скорости соединения;
• Template:Anchor$request_method, эта переменная равна методу запроса, обычно это "GET" или "POST";
• Template:Anchor$remote_addr, эта переменная равна адресу клиента;
• Template:Anchor$remote_port, эта переменная равна порту клиента;
• Template:Anchor$remote_user, эта переменная равна имени пользователя, используемого в Basic аутентификации;
• Template:Anchor$request_filename, эта переменная равна пути к файлу для текущего запроса, формируемому из директив root или alias и URI запроса;
• Template:Anchor$request_uri, эта переменная равна полному первоначальному URI вместе с аргументами;
• Template:Anchor$query_string, то же самое, что и $args;
• Template:Anchor$server_protocol, эта переменная равна протоколу запроса, обычно это "HTTP/1.0" или "HTTP/1.1";
• Template:Anchor$server_addr, эта переменная равна адресу сервера, на который пришёл запрос. Как правило, для получения значения этой переменной делается один системный вызов. Для того, чтобы избежать системного вызова, нужно указывать адреса в директивах listen и использовать параметр bind;
• Template:Anchor$server_name, эта переменная равна имени сервера, на который пришёл запрос;
• Template:Anchor$server_port, эта переменная равна порту сервера, на который пришёл запрос;
• Template:Anchor$uri, эта переменная равна текущему URI в запросе, он может отличаться от первоначального, например, при внутренних редиректах или при использовании индексных файлов.