RuHttpCoreModule
[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]
[edit] alias
syntax: alias путь default: нет context: location
Директива задаёт замену для указанного location. Например, при такой конфигурации
location /i/ {
: alias /spool/w3/images/;
}
на запрос "/i/top.gif" будет отдан файл "/spool/w3/images/top.gif".
В значении пути можно использовать переменные. Директива alias не может использоваться внутри location, заданного регулярным выражением.
[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.
[edit] client_body_buffer_size
syntax: client_body_buffer_size размер default: client_body_buffer_size 8k/16k context: http, server, location
Директива задаёт размер буфера для чтения тела запроса клиента. Если тело запроса больше заданного буфера, то всё тело запроса или только его часть записывается во временный файл. По умолчанию размер одного буфера равен двум размерам страницы, в зависимости от платформы это или 8K, или 16K.
[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
[edit] client_body_timeout
syntax: client_body_timeout время default: client_body_timeout 60 context: http, server, location
Директива задаёт таймаут при чтении тела запроса клиента. Таймаут устанавливается не на всю передачу тела запроса, а только между двумя операциями чтения. Если по истечении этого времени клиент ничего не передаст, то ему возвращается ошибка "Request time out" (408).
[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.
[edit] client_header_timeout
syntax: client_header_timeout время
default: client_header_timeout 60
context: http, server
Директива задаёт таймаут при чтении заголовка запроса клиента. Если по истечении этого времени клиент не передаст полностью заголовок запроса, то ему возвращается ошибка "Request time out" (408).
[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). Следует иметь в виду, что браузеры не умеют корректно показывать эту ошибку.
[edit] default_type
syntax: default_type MIME-тип default: default_type text/plain context: http, server, location
Директива задаёт MIME-тип ответов по умолчанию.
[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;
[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;
: }
[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 секунд.
[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, то эти буферы освобождаются.
[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;
: }
[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;
: }
: ...
: }
[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;
[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.
[edit] msie_padding
syntax: msie_padding [on|off]
default: msie_padding on
context: http, server, location
Директива разрешает или запрещает добавлять в ответы для MSIE со статусом больше 400 комментарий для увеличения размера ответа до 512 байт.
[edit] msie_refresh
syntax: msie_refresh [on|off]
default: msie_refresh off
context: http, server, location
Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо редиректов.
[edit] optimize_server_names
syntax: optimize_server_names [on|off]
default: optimize_server_names on
context: http, server
Директива разрешает или запрещает оптимизировать проверку имени хоста в name-based виртуальных серверах. Проверка в частности влияет на имя хоста, используемого в редиректах. Если оптимизация разрешена и все name-based сервера, слушающие на одной паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения запроса имена не проверяются и в редиректах используется первое имя сервера. Если в редиректе нужно использовать имя хоста, переданное клиентом, то оптимизацию нужно выключить.
[edit] port_in_redirect
syntax: port_in_redirect [on|off]
default: port_in_redirect on
context: http, server, location
Директива разрешает или запрещает указывать порт в редиректах, выдаваемых nginx'ом.
[edit] recursive_error_pages
syntax: recursive_error_pages [on|off]
default: recursive_error_pages off
context: http, server, location
Директива разрешает или запрещает делать несколько перенаправлений через директиву error_page.
[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". В значении пути можно использовать переменные.
[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;
: }
[edit] send_timeout
syntax: send_timeout время
default: send_timeout 60
context: http, server, location
Директива задаёт таймаут при передаче ответа клиенту. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени клиент ничего не примет, то nginx закрывает соединение.
[edit] sendfile
syntax: sendfile [on|off]
default: sendfile off
context: http, server, location
Директива разрешает или запрещает использовать sendfile().
[edit] server
syntax: server { ... }
default: нет
context: http
Директива задаёт конфигурацию для виртуального сервера. Чёткого разделения виртуальных серверов ip-based (на основании ip-адреса) и name-based (на основании имени, передаваемого в строке "Host" заголовка запроса), нет. Вместо этого директивами listen описываются все адреса и порты, на которых нужно принимать соединения для этого сервера, и в директиве server_name указываются все имена серверов. Пример конфигурации описан в настройке виртуальных серверов.
[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 *;
: }
[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
Директива задаёт размер корзины в хэш-таблицах имён серверов. Значение по умолчанию зависит от размера строки кэша процессора. Подробнее смотри в описании настройки хэшей.
[edit] tcp_nodelay
syntax: tcp_nodelay [on|off]
default: tcp_nodelay on
context: http, server, location
Директива разрешает или запрещает использовать опцию TCP_NODELAY. Опция включаются только при переходе соединения в состояние keep-alive.
[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;
- передавать файл в полных пакетах.
[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 в запросе, он может отличаться от первоначального, например, при внутренних редиректах или при использовании индексных файлов.
