Персональный
сайт
Игоря
Сысоева

01.12.2008

Содержание

alias

client_body_in_file_only

client_body_buffer_size

client_body_temp_path

client_body_timeout

client_header_buffer_size

client_header_timeout

client_max_body_size

default_type

directio

error_page

if_modified_since

internal

keepalive_timeout

large_client_header_buffers

limit_except

limit_rate

listen

location

log_subrequest

merge_slashes

msie_padding

msie_refresh

open_file_cache

open_file_cache_errors

open_file_cache_min_uses

open_file_cache_valid

optimize_server_names

port_in_redirect

recursive_error_pages

reset_timedout_connection

resolver

resolver_timeout

root

satisfy

satisfy_any

send_timeout

sendfile

server

server_name

server_name_in_redirect

server_names_hash_max_size

server_names_hash_bucket_size

server_tokens

tcp_nodelay

tcp_nopush

types

underscores_in_headers

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

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

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

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

При использовании параметра "on" временные файлы по окончании обработки запроса не удаляется.

Параметр "clean" разрешает удалять временные файлы, оставшиеся по окончании обработки запроса.

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

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

client_body_temp_path  /spool/nginx/client_temp 1 2;

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

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

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

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

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

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

Директива (0.7.7) разрешает использовать флаги O_DIRECT (FreeBSD, Linux), F_NOCACHE (Mac OS X) или функцию directio() (Solaris) при чтении файлов, размер которых больше либо равен указанному. Директива автоматически запрещает (0.7.15) использование sendfile'а для данного запроса. Рекомендуется использовать для больших файлов:

directio  4m;

Директива задаёт URI, который будет показываться для указанных ошибок. Директивы наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы error_page. В 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;

Если при перенаправлении не нужно менять URI, то можно перенаправить обработку ошибки в именованный location:

location / {
    error_page   404  =  @fallback;
}

location @fallback {
    proxy_pass   http://backend;
}

Директива определяет, как сравнивать время модификации ответа и время в заголовке запроса "If-Modified-Since":

• exact — точно совпадение;
• before — время модификации ответа меньше или равно времени, заданному в заголовке запроса "If-Modified-Since".

Директива указывает, что данный 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;
}

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

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

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

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

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

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

server {

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

    ...
}

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

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

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

Если директива не указана, то используется порт *:80, если nginx работает с правами пользователя root, или порт *:8000.

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

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

• backlog=число — задаёт параметр backlog в вызове listen(2). По умолчанию backlog равен -1 для FreeBSD и 511 для всех остальных платформ.
• 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) всегда делается отдельно.
• ssl — параметр (0.7.14) не имеет отношения к системным вызовам listen(2) и bind(2), а позволяет указать, что все соединения, принимаемые на этом порту, должны работать в режиме SSL. Это позволяет задать компактную конфигурацию для сервера, работающего сразу в двух режимах — HTTP и HTTPS.

  listen  80;
  listen  443 default ssl;
  

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

listen  127.0.0.1 default accept_filter=dataready backlog=1024;

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

Для операционных систем, не чувствительных к регистру символов, таких как Mac OS X и Cygwin, проверка обычных строк делается без учёта регистра (0.7.7). Однако, сравнение ограничено только однобайтными locale'ями.

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

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

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

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

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

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

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

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

Префикс "@" задаёт именнованный location. Такой location не используется при обычной обработке запросов, а предназначен только для перенаправления в него запросов.

Директива разрешает или запрещает записывать в access_log подзапросы.

Директива разрешает или запрещает объединять в URI два и более слэшей в один.

Необходимо иметь ввиду, что это объединение необходимо для корректной проверки location'ов и регулярных выражений. Например, запрос "//scripts/one.php" не попадает в

location /scripts/ {
    ...
}

Выключение объединения может понадобиться, если в URI используются имена, закодированные методом base64, который использует символ "/". Но по соображениям безопасности лучше избегать выключение объединения.

Если директива указана на уровне server в сервере по умолчанию, то её значение распространяется на все виртуальные сервера, слушающие на том же адресе и порту.

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

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

Директива задаёт кэш, в котором могут хранится

• дескрипторы открытых файлов, информация об их размерах и времени модификации;
• информация о существовании каталогов;
• информация об ошибках поиска файла — нет файла, нет прав на чтение и тому подобное. Кэширование ошибок нужно разрешить директивой open_file_cache_errors.

Параметры директивы:

• max — задаёт маскимальное число элементов в кэше; при переполнении кэша удаляются наиболее давно не используемые элементы (LRU);
• inactive — задаёт время, после которого элемент кэша удаляется, если к нему не было обращений в течение этого времени; по умолчанию 60 секунд;
• off — запрещает кэш.

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

open_file_cache          max=1000  inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

Директива определяет, кэшировать или нет ошибки поиска файлов в open_file_cache.

Директива определяет минимальное число использований файла в течение времени, заданного параметром inactive в директиве open_file_cache, после которого дескриптор файла будет оставаться окрытым в кэше.

Директива определяет, через какое время нужно проверять актуальность информации об элементе в open_file_cache.

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

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

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

Директива разрешает или запрещает сбрасывать соединение по таймауту. Сброс делается следующим образом — перед закрытием сокета для него ставится опция SO_LINGER с таймаутом 0. После чего при закрытии сокета клиенту отсылается пакет RST, а всё память, связанная с этим сокетом, освобождается. Это позволяет избежать длительного нахождения уже закрытого сокета в состоянии FIN_WAIT1 с заполненными буферами.

Необходимо отметить, что соединения, находящиеся в состоянии keepalive, по истечении таймаута закрываются обычным образом.

Директива задаёт адрес name-сервера, например:

    resolver   127.0.0.1;

Директива задаёт таймаут для определения имени, например:

    resolver_timeout   5s;

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

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

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

location / {
    satisfy  any;

    allow  192.168.1.0/32;
    deny   all;

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

Директива переименована в директиву satisfy.

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

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

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

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

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

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

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

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

     server {
         server_name   .example.com;
     }

Кроме того, в качестве имени сервера можно использовать регулярное выражение, указав перед ним "~":

     server {
         server_name   www.example.com   ~^www\d+\.example\.com$;
     }

Начиная с 0.7.11, можно использовать пустое имя "":

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

Порядок проверки имён следующий:

• полные имена,
• имена с маской в начале имени — *.example.com,
• имена с маской в конце имени — mail.*,
• регулярные выражения.

Директива разрешает или запрещает использовать в редиректах, выдаваемых nginx'ом, основное имя сервера, задаваемое директивой server_name. Если использование основного имени запрещено, то используется имя, указанного в строке "Host" в заголовке запроса. Если же этой строки нет, то используется IP-адрес сервера.

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

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

Директива разрешает или запрещает выдавать версию nginx'а в сообщениях об ошибках и в строке заговка ответа "Server".

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

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

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

Директива задаёт соответствие расширения и 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;
}

Директива разрешает или запрещает использование символов подчёркивания в строках заголовка запроса клиента.

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

• $args, эта переменная равна аргументам в строке запроса;
• $arg_name, эта переменная равна аргументу name в строке запроса;
• $binary_remote_addr, эта переменная равна адресу клиента в бинарном виде, длина её значения всегда 4 байта;
• $content_length, эта переменная равна строке "Content-Length" в заголовке запроса;
• $content_type, эта переменная равна строке "Content-Type" в заголовке запроса;
• $document_root, эта переменная равна значению директивы root для текущего запроса;
• $document_uri, то же самое, что и $uri;
• $host, эта переменная равна строке "Host" в заголовке запроса или имени сервера, на который пришёл запрос, если этой строки нет;
• $hostname, эта переменная равна имени хоста;
• $http_name, эта переменная равна строке name в заголовке запроса;
• $is_args, эта переменная равна "?", если в строке запроса есть аргументы, и пустой строке, если их нет;
• $limit_rate, эта переменная позволяет установить ограничие скорости соединения;
• $pid, эта переменная равна номеру рабочего процесса;
• $request_method, эта переменная равна методу запроса, обычно это "GET" или "POST";
• $remote_addr, эта переменная равна адресу клиента;
• $remote_port, эта переменная равна порту клиента;
• $remote_user, эта переменная равна имени пользователя, используемого в Basic аутентификации;
• $realpath_root, эта переменная равна значению директивы root для текущего запроса, при этом все символические ссылки преобразованны в реальные путь;
• $request_filename, эта переменная равна пути к файлу для текущего запроса, формируемому из директив root или alias и URI запроса;
• $request_body_file, эта переменная равна имени временного файла, в котором хранится тело запроса. По завершению работы файл необходимо удалить. Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно указать client_body_in_file_only on. При передаче имени в проксированном запросе или в запросе к FastCGI-серверу следует запретить передачу самого тела директивами "proxy_pass_request_body off" или "fastcgi_pass_request_body off" соответственно.
• $request_uri, эта переменная равна полному первоначальному URI вместе с аргументами;
• $query_string, то же самое, что и $args;
• $scheme, эта переменная равна схеме запроса — "http" или "https";
• $server_protocol, эта переменная равна протоколу запроса, обычно это "HTTP/1.0" или "HTTP/1.1";
• $server_addr, эта переменная равна адресу сервера, на который пришёл запрос. Как правило, для получения значения этой переменной делается один системный вызов. Для того, чтобы избежать системного вызова, нужно указывать адреса в директивах listen и использовать параметр bind;
• $server_name, эта переменная равна имени сервера, на который пришёл запрос;
• $server_port, эта переменная равна порту сервера, на который пришёл запрос;
• $uri, эта переменная равна текущему URI в запросе, он может отличаться от первоначального, например, при внутренних редиректах или при использовании индексных файлов.

(C) Игорь Сысоев
http://sysoev.ru