Поставляемые модули#

Модули, поставляемые в составе Nginx, приведены в таблице ниже.

Поставляемые модули Nginx#

Модуль

Описание

ngx_http_addition_module

Позволяет добавлять текст в начало и конец ответа

ngx_http_core_module

Отвечает за базовую функциональность Nginx

ngx_http_auth_request_module

Реализует авторизацию клиента на основе результата выполнения дополнительного запроса

ngx_http_dav_module

Упрощает управление файлами на сервере через протокол WebDAV, поддерживая методы PUT, DELETE, MKCOL, COPY и MOVE

ngx_http_flv_module

Обеспечивает поддержку псевдо-стриминга для видеофайлов в формате FLV

ngx_http_gunzip_module

Распаковывает ответы с Content-Encoding: gzip для клиентов, не поддерживающих сжатие gzip. Полезен для экономии ресурсов при хранении сжатых данных

ngx_http_gzip_static_module

Отдает предварительно сжатые файлы с расширением .gz вместо оригинальных

ngx_http_image_filter_module

Выполняет преобразование изображений форматов JPEG, GIF, PNG, WebP

ngx_http_mp4_module

Поддерживает псевдо-стриминг для файлов в формате MP4 (.mp4, .m4v, .m4a)

ngx_http_random_index_module

Возвращает случайный файл в качестве индексного при запросе каталога, оканчивающегося на /

ngx_http_realip_module

Заменяет IP-адрес и порт клиента на значения из указанного заголовка

ngx_http_slice_module

Делит запрос на части, возвращая данные по диапазонам, что улучшает кеширование для больших ответов

ngx_http_ssl_module

Обеспечивает поддержку HTTPS

ngx_http_stub_status_module

Предоставляет базовую статистику о состоянии сервера

ngx_http_sub_module

Заменяет указанную строку в ответе на другую

ngx_http_v2_module

Добавляет поддержку протокола HTTP/2

ngx_http_xslt_module

Преобразует XML-документы с использованием XSLT-шаблонов

ngx_mail_ssl_module

Обеспечивает защищенное соединение для почтового прокси-сервера через SSL/TLS

ngx_stream_realip_module

Заменяет IP-адрес и порт клиента на значения из заголовка PROXY

ngx_stream_ssl_module

Поддерживает SSL/TLS для потокового прокси-сервера

ngx_stream_ssl_preread_module

Извлекает данные из сообщения ClientHello, такие как SNI или ALPN, без завершения SSL/TLS-соединения

Подробное описание основных модулей и модулей, реализующих функции безопасности, приведено в следующих разделах.

ngx_http_core_module#

ngx_http_core_module — основной модуль Nginx, отвечающий за базовую функциональность HTTP-сервера.

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

  • конфигурацию серверов;

  • обработку запросов;

  • тайм-ауты и соединения;

  • обработку ошибок;

  • логирование;

  • оптимизацию;

  • безопасность.

Директивы#

Список директив модуля представлен в таблице ниже.

Директивы ngx_http_core_module#

Синтаксис

Значение по умолчанию

Контекст

Описание

absolute_redirect on | off;

absolute_redirect on;

http, server, location

Задает использование относительных URL при перенаправлениях, если off

aio on | off | threads[=pool];

aio off;

http, server, location

Включает или отключает асинхронный ввод-вывод (AIO) для файлов в FreeBSD и Linux

auth_delay <time>;

auth_delay 0s;

http, server, location

Устанавливает задержку для обработки неавторизованных запросов с кодом 401, чтобы предотвратить атаки по времени

chunked_transfer_encoding on | off;

chunked_transfer_encoding on;

http, server, location

Управляет использованием chunked transfer encoding в HTTP/1.1

client_body_buffer_size <size>;

client_body_buffer_size 8k| 16k;

http, server, location

Устанавливает размер буфера для чтения тела запроса клиента. Если данные превышают размер буфера, они записываются во временный файл

client_body_in_file_only on | clean | off;

client_body_in_file_only off;

http, server, location

Определяет, нужно ли сохранять тело запроса клиента в файл

client_body_in_single_buffer on | off;

client_body_in_single_buffer off;

http, server, location

Определяет, нужно ли сохранять тело запроса клиента в одном буфере

client_body_temp_path path [<level1> [<level2> [<level3>]]];

client_body_temp_path client_body_temp;

http, server, location

Задает каталог для временных файлов с телами запросов клиентов. Поддерживает иерархию подкаталогов до трех уровней (level1, level2, level3)

client_body_timeout <time>;

client_body_timeout 60s;

http, server, location

Устанавливает тайм-аут <time> для чтения тела запроса клиента

client_header_buffer_size <size>;

client_header_buffer_size

http, server

Устанавливает размер буфера <size> для чтения заголовков запроса клиента. Для большинства запросов достаточно 1 Кбайт

client_header_timeout <time>;

client_header_timeout 60s;

http, server, location

Устанавливает тайм-аут <time> для чтения заголовков запроса клиента

client_max_body_size <size>;

client_max_body_size 1m;

http, server, location

Устанавливает максимальный допустимый размер <size> тела запроса клиента

connection_pool_size <size>;

connection_pool_size 256| 512;

http, server

Настраивает выделение памяти для соединений

default_type <mime-type>;

default_type text/plain;

http, server, location

Указывает MIME-тип по умолчанию для ответов, если он не задан явно

directio <size> | off;

directio off;

http, server, location

Включает использование флагов O_DIRECT, F_NOCACHE или функцию directio() для чтения файлов размером <size> больше указанного

directio_alignment <size>;

directio_alignment 512;

http, server, location

Устанавливает выравнивание для directio

disable_symlinks off;
disable_symlinks on | if_not_owner [from=<part>];

disable_symlinks off;

http, server, location

Управляет обработкой символических ссылок при открытии файлов

error_page <code> ... [=[<response>]] uri;

http, server, location, if in location

Указывает URI для отображения при возникновении ошибок. В URI можно использовать переменные

etag on | off;

etag on;

http, server, location

Включает или отключает автоматическую генерацию заголовка ETag для статических ресурсов

http { ... }

main

Определяет контекст для настройки HTTP-сервера

if_modified_since off | exact | before;

if_modified_since exact;

http, server, location

Управляет сравнением времени модификации ответа с заголовком If-Modified-Since

ignore_invalid_headers on | off;

ignore_invalid_headers on;

http, server

Задает игнорирование заголовков с недопустимыми именами, если включено

internal;

location

Указывает, что location доступен только для внутренних запросов

keepalive_disable none | <browser> ...;

keepalive_disable msie6;

http, server, location

Отключает Keep-alive для определенных браузеров

keepalive_requests <number>;

keepalive_requests 1000;

http, server, location

Устанавливает максимальное количество запросов на одно Keep-alive-соединение

keepalive_time <time>;

keepalive_time 1h;

http, server, location

Устанавливает максимальное время <time> обработки запросов в рамках Keep-alive-соединения

keepalive_timeout <timeout> [<header_timeout>];

keepalive_timeout 75s;

http, server, location

Указывает время <timeout>, в течение которого Keep-alive-соединение остается открытым со стороны сервера

large_client_header_buffers <number> <size>;

large_client_header_buffers 4 8k;

http, server

Определяет количество <number> и размер <size> буферов для чтения больших заголовков запросов клиента

limit_except <method> ... { ... }

location

Ограничивает доступные HTTP-методы <method> в пределах location

limit_rate <rate>;

limit_rate 0;

http, server, location, if in location

Устанавливает ограничение скорости <rate> передачи данных клиенту (в байтах в секунду)

limit_rate_after <size>;

limit_rate_after 0;

http, server, location, if in location

Указывает объем данных <size>, после которого начинает действовать ограничение скорости

lingering_close off | on | always;

lingering_close on;

http, server, location

Управляет процессом закрытия соединений с клиентами

lingering_time< time>;

lingering_time 30s;

http, server, location

Устанавливает максимальное время <time> для обработки дополнительных данных от клиента

lingering_timeout <time>;

lingering_timeout 5s;

http, server, location

Указывает время <time> ожидания дополнительных данных от клиента

listen <address>[:<port>] [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=<number>] [fastopen=<number>] [backlog=<number>] [rcvbuf=<size>] [sndbuf=<size>] [accept_filter=<filter>] [deferred] [bind] [ipv6only=on | off] [reuseport] [so_keepalive=on | off | [keepidle]:[keepintvl]:[keepcnt]]; listen <port> [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=<number>] [fastopen=<number>] [backlog=<number>] [rcvbuf=<size>] [sndbuf=<size>] [accept_filter=<filter>] [deferred] [bind] [ipv6only=on | off] [reuseport] [so_keepalive=on | off | [keepidle]:[keepintvl]:[keepcnt]]; listen unix:<path> [default_server] [ssl] [http2 | quic] [proxy_protocol] [backlog=<number>] [rcvbuf=<size>] [sndbuf=<size>] [accept_filter=<filter>] [deferred] [bind] [so_keepalive=on | off | [keepidle]:[keepintvl]:[keepcnt]];

listen *:80 | *:8000;

server

Указывает адрес <address> и порт <port> для прослушивания запросов (IP или UNIX-сокет)

location [ = | ~ | ~* | ^~ ] uri { ... } location @name { ... }

server, location

Настраивает обработку запросов в зависимости от URI

log_not_found on | off;

log_not_found on;

http, server, location

Включает или отключает логирование ошибок о ненайденных файлах в error_log

log_subrequest on | off;

log_subrequest off;

http, server, location

Включает или отключает логирование подзапросов в access_log

max_ranges <number>;

http, server, location

Ограничивает максимальное количество диапазонов в запросах с указанием диапазонов байт

merge_slashes on | off;

merge_slashes on;

http, server

Управляет объединением нескольких слешей (/) в URI в один

msie_padding on | off;

msie_padding on;

http, server, location

Добавляет комментарии к ответам для MSIE, чтобы увеличить их размер до 512 байт

msie_refresh on | off;

msie_refresh off;

http, server, location

Использует refresh вместо перенаправлений для MSIE

open_file_cache off; open_file_cache max=N [inactive=<time>];

open_file_cache off;

http, server, location

Настраивает кеш для хранения информации о файлах, включая их размеры, время модификации и ошибки поиска

open_file_cache_errors on | off;

open_file_cache_errors off;

http, server, location

Включает или отключает кеширование ошибок при поиске файлов

open_file_cache_min_uses <number>;

open_file_cache_min_uses 1;

http, server, location

Устанавливает минимальное количество обращений к файлу для сохранения его дескриптора в кеше

open_file_cache_valid <time>;

open_file_cache_valid 60s;

http, server, location

Определяет время, через которое проверяется актуальность информации в кеше

output_buffers number size;

output_buffers 2 32k;

http, server, location

Устанавливает количество и размер буферов для чтения ответов с диска

port_in_redirect on | off;

port_in_redirect on;

http, server, location

Управляет включением порта в URL при перенаправлениях

postpone_output <size>;

postpone_output 1460;

http, server, location

Откладывает отправку данных клиенту до накопления указанного объема данных

read_ahead <size>;

read_ahead 0;

http, server, location

Устанавливает размер предчтения для файлов. Используется posix_fadvise

recursive_error_pages on | off;

recursive_error_pages off;

http, server, location

Разрешает или запрещает множественные перенаправления через error_page

request_pool_size <size>;

request_pool_size 4k;

http, server

Настраивает размер пула для хранения запросов

reset_timedout_connection on | off;

reset_timedout_connection off;

http, server, location

Управляет сбросом соединений по тайм-ауту

resolver <address> ... [valid=<time>] [ipv4=on | off] [ipv6=on | off] [status_zone=<zone>];

http, server, location

Настраивает DNS-resolver для преобразования имен в адреса

resolver_timeout <time>;

resolver_timeout 30s;

http, server, location

Устанавливает тайм-аут для DNS-запросов

root <path>;

root html;

http, server, location, if in location

Указывает корневой каталог для обработки запросов

satisfy all | any;

satisfy all;

http, server, location

Определяет условия успешного выполнения запроса

send_lowat <size>;

send_lowat 0;

http, server, location

Минимизирует количество операций отправки данных на клиентских сокетах

send_timeout <time>;

send_timeout 60s;

http, server, location

Устанавливает тайм-аут между операциями записи при передаче ответа клиенту

sendfile on | off;

sendfile off;

http, server, location, if in location

Включает или выключает использование sendfile() для передачи файлов

sendfile_max_chunk <size>;

sendfile_max_chunk 2m;

http, server, location

Ограничивает объем данных, передаваемых за один вызов sendfile()

server { ... }

http

Определяет настройки виртуального сервера. Виртуальные серверы могут быть настроены как на основе IP-адресов, так и на основе имен (через поле Host). Директива listen задает адреса и порты для прослушивания, а server_name — имена серверов

server_name <name> ...;

server_name "";

server

Указывает имена виртуальных серверов, на которые должны быть направлены запросы

server_name_in_redirect on | off;

server_name_in_redirect off;

http, server, location

Определяет, будет ли основное имя сервера (из директивы server_name) использоваться в абсолютных перенаправлениях

server_names_hash_bucket_size <size>;

server_names_hash_bucket_size 32 | 64 | 128;

http

Задает размер корзины в хеш-таблицах для имен серверов. Размер зависит от кеша процессора

server_names_hash_max_size <size>;

server_names_hash_max_size 512;

http

Устанавливает максимальный размер хеш-таблиц для имен серверов

server_tokens on | off | build | <string>;

server_tokens on;

http, server, location

Управляет отображением информации о версии Nginx на страницах ошибок и в заголовке Server

subrequest_output_buffer_size <size>;

subrequest_output_buffer_size 4k | 8k;

http, server, location

Определяет размер буфера для хранения тела ответа подзапроса

tcp_nodelay on | off;

tcp_nodelay on;

http, server, location

Управляет параметром TCP_NODELAY, который уменьшает задержку при передаче данных по TCP

tcp_nopush on | off;

tcp_nopush off;

http, server, location

Управляет параметром TCP_NOPUSH, который позволяет объединять заголовки и данные в один пакет

try_files <file> ... uri; try_files <file> ... =<code>;

server, location

Проверяет наличие указанных файлов и возвращает первый найденный или перенаправляет на указанный URI

types { ... }

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

http, server, location

Сопоставляет расширения файлов с MIME-типами ответов

types_hash_bucket_size

64

http, server, location

Задает размер корзины в хеш-таблицах для типов

types_hash_max_size

1024

http, server, location

Устанавливает максимальный размер хеш-таблиц для типов

underscores_in_headers

off

http, server

Разрешает или запрещает использование символов подчеркивания (_) в заголовках запросов

variables_hash_bucket_size

64

http

Определяет размер корзины в хеш-таблице для переменных

variables_hash_max_size

1024

http

Устанавливает максимальный размер хеш-таблицы для переменных

Встроенные переменные#

Модуль ngx_http_core_module предоставляет набор встроенных переменных, например:

  • $bytes_sent — количество байт, переданных клиенту;

  • $connection — уникальный номер соединения;

  • $hostname — имя хоста сервера;

  • $https — значение on, если используется SSL-соединение, иначе пустая строка;

  • $nginx_version — текущая версия Nginx.

ngx_http_auth_request_module#

Модуль ngx_http_auth_request_module обеспечивает авторизацию клиента на основе результата подзапроса. Если подзапрос возвращает код ответа 2xx, доступ разрешается. Если подзапрос возвращает код 401 или 403, доступ блокируется с соответствующим кодом ошибки. Все остальные коды ответа, полученные от подзапроса, интерпретируются как ошибочные.

Пример конфигурации#

location /private/ {
    auth_request /auth;
    ...
}

location = /auth {
    proxy_pass ...
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

Директивы#

Список директив модуля представлен в таблице ниже.

Директивы ngx_http_auth_request_module#

Синтаксис

Значение по умолчанию

Контекст

Описание

auth_request uri | off;

auth_request off;

http, server, location

Включает авторизацию на основне результата подзапроса и задает URI для отправки подзапроса

auth_request_set $variable value;

-

http, server, location

Задает значение value для переменной variable в запросе после завершения авторизации. Значение может включать переменные из запроса авторизации, например, $upstream_http_*

ngx_http_ssl_module#

Модуль ngx_http_ssl_module реализует поддержку протокола HTTPS.

Важно

Для сборки и работы этого модуля нужна библиотека OpenSSL.

Пример конфигурации#

worker_processes auto;

http {

    ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

Директивы#

Список директив модуля представлен в таблице ниже.

Директивы ngx_http_ssl_module#

Синтаксис

Значение по умолчанию

Контекст

Описание

ssl_buffer_size;

ssl_buffer_size 16k;

http, server

Устанавливает размер буфера для передачи данных

ssl_certificate;

http, server

Задает путь к файлу сертификата в формате PEM для виртуального сервера

ssl_certificate_key <file>;

http, server

Указывает путь к файлу с приватным ключом в формате PEM для виртуального сервера

ssl_ciphers <ciphers>;

ssl_ciphers HIGH:!aNULL:!MD5;

http, server

Определяет список допустимых шифров в формате, совместимом с OpenSSL

ssl_client_certificate <file>;

http, server

Задает файл с сертификатами доверенных центров сертификации (CA) в формате PEM для проверки клиентских сертификатов

ssl_conf_command <name> <value>;

http, server

Позволяет задавать пользовательские команды конфигурации OpenSSL

ssl_crl <file>;

http, server

Указывает файл со списком отозванных сертификатов (CRL) в формате PEM для проверки клиентских сертификатов

ssl_dhparam <file>;

http, server

Задает файл с параметрами для DHE-шифрования

ssl_early_data on | off;

ssl_early_data off;

http, server

Включает или отключает использование ранних данных (early data) в протоколе TLS 1.3

ssl_ecdh_curve <curve>;

ssl_ecdh_curve auto

http, server

Задает кривую curve для ECDHE-шифрования

ssl_key_log <path>;

http, server

Включает запись SSL-ключей клиентских соединений в указанный файл

ssl_ocsp on | off | leaf;

ssl_ocsp off;

http, server

Активирует проверку статуса сертификатов через OCSP. Параметр leaf ограничивает проверку только клиентским сертификатом

ssl_ocsp_cache off | [shared:<name>:<size>];

ssl_ocsp_cache off;

http, server

Настраивает кеш для хранения результатов проверки статуса сертификатов через OCSP

ssl_ocsp_responder <url>;

http, server

Переопределяет URL сервера OCSP для проверки статуса сертификатов

ssl_password_file <file>;

http, server

Указывает файл с паролями для доступа к приватным ключам, где каждый пароль записан на отдельной строке

ssl_prefer_server_ciphers on | off;

sl_prefer_server_ciphers off;

http, server

Устанавливает приоритет шифров, предложенных сервером, над клиентскими при использовании SSLv3 и TLS

ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];

ssl_protocols TLSv1.2 TLSv1.3;

http, server

Разрешает использование указанных протоколов. Доступные опции зависят от версии OpenSSL

ssl_reject_handshake on | off;

ssl_reject_handshake off;

http, server

Если включено, отклоняет попытки установления SSL-соединения в блоке server

ssl_session_cache off | none | [builtin[:<size>]] [shared:<name>:<size>];

ssl_session_cache none;

http, server

Настраивает тип и размер кеша для хранения параметров SSL-сессий

ssl_session_ticket_key <file>;

http, server

Указывает файл с ключом для шифрования и дешифрования TLS session tickets

ssl_session_tickets on | off;

ssl_session_tickets on;

http, server

Включает или отключает возможность возобновления сессий с использованием TLS session tickets

ssl_session_timeout <time>;

ssl_session_timeout 5m;

http, server

Устанавливает срок действия параметров SSL-сессии, в течение которого клиент может их повторно использовать

ssl_stapling on | off;

ssl_stapling off;

http, server

Включает или отключает прикрепление OCSP-ответов к сертификатам сервера

ssl_stapling_file <file>;

http, server

Задает получение OCSP-ответов из файла <file> без запроса у сервера OCSP

ssl_stapling_responder url;

http, server

Переопределяет URL сервера OCSP, указанный в расширении сертификата Authority Information Access

ssl_stapling_verify on | off;

ssl_stapling_verify off;

http, server

Включает или отключает проверку сервером OCSP-ответов

ssl_trusted_certificate <file>;

http, server

Задает файл с сертификатами доверенных центров сертификации (CA) в формате PEM для проверки клиентских сертификатов и OCSP-ответов

ssl_verify_client on | off | optional | optional_no_ca;

ssl_verify_client off;

http, server

Включает проверку клиентских сертификатов. Результат проверки доступен через переменную $ssl_client_verify

ssl_verify_depth <number>;

ssl_verify_depth 1;

http, server

Настраивает глубину проверки в цепочке клиентских сертификатов

Встроенные переменные#

Модуль ngx_http_ssl_module предоставляет набор встроенных переменных, таких как:

  • $ssl_cipher — название алгоритма шифрования, используемого в текущем SSL-соединении;

  • $ssl_protocol — версия протокола, применяемого для SSL-соединения;

  • $ssl_client_verify — результат проверки клиентского сертификата: SUCCESS - в случае успеха, FAILED:reason - при ошибке, NONE — если сертификат не был предоставлен;

  • $ssl_session_id — идентификатор сессии текущего SSL-соединения;

  • $ssl_session_reusedr — если сессия была повторно использована, . — если нет;

  • $ssl_server_name — имя сервера, запрошенное через SNI (Server Name Indication);

  • $ssl_client_cert — клиентский сертификат в формате PEM для установленного SSL-соединения;

  • $ssl_client_serial — ссерийный номер клиентского сертификата, используемого в SSL-соединении;

и другие.