Модуль ngx_http_proxy_module
Join us for the first quarterly
NGINX Community Call
on July 22nd to connect and discuss NGINX development.
english
русский
новости [en]
об nginx
скачать
безопасность [en]
документация
faq
книги [en]
сообщество
компания
x.com
blog
njs
ingress controller
gateway fabric
Модуль ngx_http_proxy_moduleПример конфигурации
Директивы
proxy_allow_upstream
proxy_bind
proxy_bind_dynamic
proxy_buffer_size
proxy_buffering
proxy_buffers
proxy_busy_buffers_size
proxy_cache
proxy_cache_background_update
proxy_cache_bypass
proxy_cache_convert_head
proxy_cache_key
proxy_cache_lock
proxy_cache_lock_age
proxy_cache_lock_timeout
proxy_cache_max_range_offset
proxy_cache_methods
proxy_cache_min_uses
proxy_cache_path
proxy_cache_purge
proxy_cache_revalidate
proxy_cache_use_stale
proxy_cache_valid
proxy_connect_timeout
proxy_cookie_domain
proxy_cookie_flags
proxy_cookie_path
proxy_force_ranges
proxy_headers_hash_bucket_size
proxy_headers_hash_max_size
proxy_hide_header
proxy_http_version
proxy_ignore_client_abort
proxy_ignore_headers
proxy_intercept_errors
proxy_limit_rate
proxy_max_temp_file_size
proxy_method
proxy_next_upstream
proxy_next_upstream_timeout
proxy_next_upstream_tries
proxy_no_cache
proxy_pass
proxy_pass_header
proxy_pass_request_body
proxy_pass_request_headers
proxy_pass_trailers
proxy_read_timeout
proxy_redirect
proxy_request_buffering
proxy_request_dynamic
proxy_send_lowat
proxy_send_timeout
proxy_set_body
proxy_set_header
proxy_socket_keepalive
proxy_socket_rcvbuf
proxy_socket_sndbuf
proxy_ssl_certificate
proxy_ssl_certificate_cache
proxy_ssl_certificate_key
proxy_ssl_ciphers
proxy_ssl_conf_command
proxy_ssl_crl
proxy_ssl_key_log
proxy_ssl_name
proxy_ssl_password_file
proxy_ssl_protocols
proxy_ssl_server_name
proxy_ssl_session_reuse
proxy_ssl_trusted_certificate
proxy_ssl_verify
proxy_ssl_verify_depth
proxy_store
proxy_store_access
proxy_temp_file_write_size
proxy_temp_path
Встроенные переменные
Модуль ngx_http_proxy_module позволяет передавать
запросы другому серверу.
Пример конфигурации
location / {
proxy_pass       http://localhost:8000;
proxy_set_header Host      $host;
proxy_set_header X-Real-IP $remote_addr;
}
Директивы
Синтаксис:
proxy_allow_upstream строка ...;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.29.3.
Задаёт условия, при которых доступ к проксируемому серверу
будет разрешён или запрещён.
Если все значения строковых параметров непустые
и не равны “0”, то доступ разрешён.
Условия проверяются каждый раз
перед установлением соединения с проксируемым сервером.
В значении параметров допустимо использование переменных:
geo $upstream_last_addr $allow {
volatile;
10.10.0.0/24        1;
}
server {
listen 127.0.0.1:8080;
location / {
proxy_pass           localhost:8000;
proxy_allow_upstream $allow;
...
}
}
Директива доступна как часть
коммерческой подписки.
Синтаксис:
proxy_bind
адрес
[transparent] |
off;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 0.8.22.
Задаёт локальный IP-адрес с необязательным портом (1.11.2),
который будет использоваться в исходящих соединениях с проксируемым сервером.
В значении параметра допустимо использование переменных (1.3.12).
Специальное значение off (1.3.12) отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы proxy_bind, позволяя системе
самостоятельно выбирать локальный IP-адрес и порт.
Параметр transparent (1.11.0) позволяет
задать нелокальный IP-aдрес, который будет использоваться в
исходящих соединениях с проксируемым сервером,
например, реальный IP-адрес клиента:
proxy_bind $remote_addr transparent;
Для работы параметра
обычно требуется
запустить рабочие процессы nginx с привилегиями
суперпользователя.
В Linux этого не требуется (1.13.8), так как если
указан параметр transparent, то рабочие процессы
наследуют capability CAP_NET_RAW из главного процесса.
Также необходимо настроить таблицу маршрутизации ядра
для перехвата сетевого трафика с проксируемого сервера.
Синтаксис:
proxy_bind_dynamic on | off;
Умолчание:
proxy_bind_dynamic off;
Контекст:
http, server, location
Эта директива появилась в версии 1.29.3.
Если включено, операция bind осуществляется
при каждой попытке соединения.
Директива доступна как часть
коммерческой подписки.
Синтаксис:
proxy_buffer_size размер;
Умолчание:
proxy_buffer_size 4k|8k;
Контекст:
http, server, location
Задаёт размер буфера, в который будет читаться
первая часть ответа, получаемого от проксируемого сервера.
В этой части ответа находится, как правило, небольшой заголовок ответа;
если его размер больше заданного, то такой ответ считается
неверным.
По умолчанию размер одного буфера равен размеру страницы памяти.
В зависимости от платформы это или 4K, или 8K,
однако его можно сделать меньше.
Синтаксис:
proxy_buffering on | off;
Умолчание:
proxy_buffering on;
Контекст:
http, server, location
Разрешает или запрещает использовать буферизацию ответов проксируемого сервера.
Если буферизация включена, то nginx принимает ответ проксируемого сервера
как можно быстрее, сохраняя его в буферы, заданные директивами
proxy_buffer_size и proxy_buffers.
Если ответ не вмещается целиком в память, то его часть может быть записана
на диск во временный файл.
Запись во временные файлы контролируется директивами
proxy_max_temp_file_size и
proxy_temp_file_write_size.
Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же
по мере его поступления.
nginx не пытается считать весь ответ проксируемого сервера.
Максимальный размер данных, который nginx может принять от сервера
за один раз, задаётся директивой proxy_buffer_size.
Буферизация может быть также включена или выключена путём передачи
значения “yes” или “no” в поле
“X-Accel-Buffering” заголовка ответа.
Эту возможность можно запретить с помощью директивы
proxy_ignore_headers.
Синтаксис:
proxy_buffers число размер;
Умолчание:
proxy_buffers 8 4k|8k;
Контекст:
http, server, location
Задаёт число и размер буферов
для одного соединения,
в которые будет читаться ответ, получаемый от проксируемого сервера.
По умолчанию размер одного буфера равен размеру страницы.
В зависимости от платформы это или 4K, или 8K.
Синтаксис:
proxy_busy_buffers_size размер;
Умолчание:
proxy_busy_buffers_size 8k|16k;
Контекст:
http, server, location
При включённой буферизации ответов
проксируемого сервера, ограничивает суммарный размер
буферов, которые могут быть заняты для отправки ответа клиенту, пока
ответ ещё не прочитан целиком.
Оставшиеся буферы тем временем могут использоваться для чтения ответа
и, при необходимости, буферизации части ответа во временный файл.
По умолчанию размер ограничен величиной двух буферов, заданных
директивами proxy_buffer_size и proxy_buffers.
Синтаксис:
proxy_cache зона | off;
Умолчание:
proxy_cache off;
Контекст:
http, server, location
Задаёт зону разделяемой памяти, используемой для кэширования.
Одна и та же зона может использоваться в нескольких местах.
В значении параметра можно использовать переменные (1.7.9).
Параметр off запрещает кэширование, унаследованное
с предыдущего уровня конфигурации.
Синтаксис:
proxy_cache_background_update on | off;
Умолчание:
proxy_cache_background_update off;
Контекст:
http, server, location
Эта директива появилась в версии 1.11.10.
Позволяет запустить фоновый подзапрос
для обновления просроченного элемента кэша,
в то время как клиенту возвращается устаревший закэшированный ответ.
Использование устаревшего закэшированного ответа в момент его обновления
должно быть
разрешено.
Синтаксис:
proxy_cache_bypass строка ...;
Умолчание:
—
Контекст:
http, server, location
Задаёт условия, при которых ответ не будет браться из кэша.
Если значение хотя бы одного из строковых параметров непустое и не равно “0”,
то ответ не берётся из кэша:
proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;
Можно использовать совместно с директивой proxy_no_cache.
Синтаксис:
proxy_cache_convert_head on | off;
Умолчание:
proxy_cache_convert_head on;
Контекст:
http, server, location
Эта директива появилась в версии 1.9.7.
Разрешает или запрещает преобразование метода “HEAD”
в “GET” для кэширования.
Если преобразование выключено, то
необходимо, чтобы ключ кэширования
включал в себя $request_method.
Синтаксис:
proxy_cache_key строка;
Умолчание:
proxy_cache_key $scheme$proxy_host$request_uri;
Контекст:
http, server, location
Задаёт ключ для кэширования, например,
proxy_cache_key "$host$request_uri $cookie_user";
По умолчанию значение директивы близко к строке
proxy_cache_key $scheme$proxy_host$uri$is_args$args;
Синтаксис:
proxy_cache_lock on | off;
Умолчание:
proxy_cache_lock off;
Контекст:
http, server, location
Эта директива появилась в версии 1.1.12.
Если включено, одновременно только одному запросу будет позволено
заполнить новый элемент кэша, идентифицируемый согласно директиве
proxy_cache_key, передав запрос на проксируемый сервер.
Остальные запросы этого же элемента будут либо ожидать
появления ответа в кэше, либо освобождения блокировки
этого элемента, в течение времени, заданного директивой
proxy_cache_lock_timeout.
Синтаксис:
proxy_cache_lock_age время;
Умолчание:
proxy_cache_lock_age 5s;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.8.
Если последний запрос, переданный на проксируемый сервер
для заполнения нового элемента кэша,
не завершился за указанное время,
на проксируемый сервер может быть передан ещё один запрос.
Синтаксис:
proxy_cache_lock_timeout время;
Умолчание:
proxy_cache_lock_timeout 5s;
Контекст:
http, server, location
Эта директива появилась в версии 1.1.12.
Задаёт таймаут для proxy_cache_lock.
По истечении указанного времени
запрос будет передан на проксируемый сервер,
однако ответ не будет закэширован.
До версии 1.7.8 такой ответ мог быть закэширован.
Синтаксис:
proxy_cache_max_range_offset число;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.11.6.
Задаёт смещение в байтах для запросов с указанием диапазона запрашиваемых байт
(byte-range requests).
Если диапазон находится за указанным смещением,
range-запрос будет передан на проксируемый сервер
и ответ не будет закэширован.
Синтаксис:
proxy_cache_methods
GET |
HEAD |
POST
...;
Умолчание:
proxy_cache_methods GET HEAD;
Контекст:
http, server, location
Эта директива появилась в версии 0.7.59.
Если метод запроса клиента указан в этой директиве,
то ответ будет закэширован.
Методы “GET” и “HEAD” всегда добавляются
в список, но тем не менее рекомендуется перечислять их явно.
См. также директиву proxy_no_cache.
Синтаксис:
proxy_cache_min_uses число;
Умолчание:
proxy_cache_min_uses 1;
Контекст:
http, server, location
Задаёт число запросов, после которого ответ будет закэширован.
Синтаксис:
proxy_cache_path
путь
[levels=уровни]
[use_temp_path=on|off]
keys_zone=имя:размер
[inactive=время]
[max_size=размер]
[min_free=размер]
[manager_files=число]
[manager_sleep=время]
[manager_threshold=время]
[loader_files=число]
[loader_sleep=время]
[loader_threshold=время]
[purger=on|off]
[purger_files=число]
[purger_sleep=время]
[purger_threshold=время];
Умолчание:
—
Контекст:
http
Задаёт путь и другие параметры кэша.
Данные кэша хранятся в файлах.
Именем файла в кэше является результат функции MD5
от ключа кэширования.
Параметр levels задаёт уровни иерархии кэша:
можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2.
Например, при использовании
proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
имена файлов в кэше будут такого вида:
/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл
переименовывается.
Начиная с версии 0.8.9 временные файлы и кэш
могут располагаться на разных файловых системах.
Однако нужно учитывать,
что в этом случае вместо дешёвой операции переименовывания в пределах
одной файловой системы файл копируется с одной файловой системы на другую.
Поэтому лучше, если кэш будет находиться на той же файловой
системе, что и каталог с временными файлами.
Какой из каталогов будет использоваться для временных файлов
определяется параметром use_temp_path (1.7.10).
Если параметр не задан или установлен в значение “on”,
то будет использоваться каталог, задаваемый директивой
proxy_temp_path для данного location.
Если параметр установлен в значение “off”,
то временные файлы будут располагаться непосредственно в каталоге кэша.
Кроме того, все активные ключи и информация о данных хранятся в зоне
разделяемой памяти, имя и размер которой
задаются параметром keys_zone.
Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей.
Как часть
коммерческой подписки
в зоне разделяемой памяти также хранится расширенная
информация о кэше,
поэтому для хранения аналогичного количества ключей необходимо указывать
больший размер зоны.
Например
зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч ключей.
Если к данным кэша не обращаются в течение времени, заданного параметром
inactive, то данные удаляются, независимо от их свежести.
По умолчанию inactive равен 10 минутам.
Специальный процесс “cache manager” следит за максимальным размером кэша,
заданным параметром max_size,
а также за минимальным объёмом свободного места на файловой системе с кэшем,
заданным параметром min_free (1.19.1).
При превышении максимального размера кэша
или недостаточном объёме свободного места
процесс удаляет наименее востребованные данные.
Удаление данных происходит итерациями, настраиваемыми параметрами (1.11.5)
manager_files,
manager_threshold и
manager_sleep.
За одну итерацию загружается не более manager_files
элементов (по умолчанию 100).
Время работы одной итерации ограничено параметром
manager_threshold (по умолчанию 200 миллисекунд).
Между итерациями делается пауза на время, заданное параметром
manager_sleep (по умолчанию 50 миллисекунд).
Через минуту после старта активируется специальный процесс “cache loader”,
который загружает в зону кэша информацию о ранее закэшированных данных,
хранящихся на файловой системе.
Загрузка также происходит итерациями.
За одну итерацию загружается не более loader_files
элементов (по умолчанию 100).
Кроме того, время работы одной итерации ограничено параметром
loader_threshold (по умолчанию 200 миллисекунд).
Между итерациями делается пауза на время, заданное параметром
loader_sleep (по умолчанию 50 миллисекунд).
Кроме того,
следующие параметры доступны как часть
коммерческой подписки:
purger=on|off
Указывает, будут ли записи в кэше, соответствующие
маске,
удалены с диска при помощи процесса “cache purger” (1.7.12).
Установка параметра в значение on
(по умолчанию off)
активирует процесс “cache purger”, который
проходит по всем записям в кэше
и удаляет записи, соответствующие этой маске.
purger_files=число
Задаёт число элементов, которые будут сканироваться за одну итерацию (1.7.12).
По умолчанию purger_files равен 10.
purger_threshold=время
Задаёт продолжительность одной итерации (1.7.12).
По умолчанию purger_threshold равен 50 миллисекундам.
purger_sleep=время
Задаёт паузу между итерациями (1.7.12).
По умолчанию purger_sleep равен 50 миллисекундам.
В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша был изменён.
При обновлении на более новую версию nginx
ранее закэшированные ответы будут считаться недействительными.
Синтаксис:
proxy_cache_purge строка ...;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.5.7.
Задаёт условия, при которых запрос будет считаться запросом
на очистку кэша.
Если значение хотя бы одного из строковых параметров непустое и не равно “0”,
то запись в кэше с соответствующим
ключом кэширования удаляется.
В результате успешной операции возвращается ответ с кодом
204 (No Content).
Если ключ кэширования
запроса на очистку заканчивается
звёздочкой (“*”), то все записи в кэше, соответствующие
этой маске, будут удалены из кэша.
Тем не менее, эти записи будут оставаться на диске или до момента удаления
из-за отсутствия обращения к данным,
или до обработки их процессом “cache purger” (1.7.12),
или до попытки клиента получить к ним доступ.
Пример конфигурации:
proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;
map $request_method $purge_method {
PURGE   1;
default 0;
}
server {
...
location / {
proxy_pass http://backend;
proxy_cache cache_zone;
proxy_cache_key $uri;
proxy_cache_purge $purge_method;
}
}
Функциональность доступна как часть
коммерческой подписки.
Синтаксис:
proxy_cache_revalidate on | off;
Умолчание:
proxy_cache_revalidate off;
Контекст:
http, server, location
Эта директива появилась в версии 1.5.7.
Разрешает ревалидацию просроченных элементов кэша при помощи
условных запросов с полями заголовка
“If-Modified-Since” и “If-None-Match”.
Синтаксис:
proxy_cache_use_stale
error |
timeout |
invalid_header |
updating |
http_500 |
http_502 |
http_503 |
http_504 |
http_403 |
http_404 |
http_429 |
off
...;
Умолчание:
proxy_cache_use_stale off;
Контекст:
http, server, location
Определяет, в каких случаях можно использовать
устаревший закэшированный ответ.
Параметры директивы совпадают с параметрами
директивы proxy_next_upstream.
Параметр error также позволяет использовать
устаревший закэшированный ответ при невозможности выбора
проксированного сервера для обработки запроса.
Кроме того, дополнительный параметр updating
разрешает использовать устаревший закэшированный ответ,
если на данный момент он уже обновляется.
Это позволяет минимизировать число обращений к проксированным серверам
при обновлении закэшированных данных.
Использование устаревшего закэшированного ответа
может также быть разрешено непосредственно в заголовке ответа
на определённое количество секунд после того, как ответ устарел (1.11.10).
Такой способ менее приоритетен, чем задание параметров директивы.
Расширение
“stale-while-revalidate”
поля заголовка “Cache-Control” разрешает
использовать устаревший закэшированный ответ,
если на данный момент он уже обновляется.
Расширение
“stale-if-error”
поля заголовка “Cache-Control” разрешает
использовать устаревший закэшированный ответ в случае ошибки.
Чтобы минимизировать число обращений к проксированным серверам при
заполнении нового элемента кэша, можно воспользоваться директивой
proxy_cache_lock.
Синтаксис:
proxy_cache_valid [код ...] время;
Умолчание:
—
Контекст:
http, server, location
Задаёт время кэширования для разных кодов ответа.
Например, директивы
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;
задают время кэширования 10 минут для ответов с кодами 200 и 302
и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
proxy_cache_valid 5m;
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра
any:
proxy_cache_valid 200 302 10m;
proxy_cache_valid 301      1h;
proxy_cache_valid any      1m;
Параметры кэширования могут также быть заданы непосредственно
в заголовке ответа.
Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
Поле заголовка “X-Accel-Expires” задаёт время кэширования
ответа в секундах.
Значение 0 запрещает кэшировать ответ.
Если значение начинается с префикса @, оно задаёт абсолютное
время в секундах с начала эпохи, до которого ответ может быть закэширован.
Если в заголовке нет поля “X-Accel-Expires”,
параметры кэширования определяются по полям заголовка
“Expires” или “Cache-Control”.
Ответ, в заголовке которого есть поле “Set-Cookie”,
не будет кэшироваться.
Ответ, в заголовке которого есть поле “Vary”
со специальным значением “*”,
не будет кэшироваться (1.7.7).
Ответ, в заголовке которого есть поле “Vary”
с другим значением, будет закэширован
с учётом соответствующих полей заголовка запроса (1.7.7).
Обработка одного или более из этих полей заголовка может быть отключена
при помощи директивы proxy_ignore_headers.
Синтаксис:
proxy_connect_timeout время;
Умолчание:
proxy_connect_timeout 60s;
Контекст:
http, server, location
Задаёт таймаут для установления соединения с проксированным сервером.
Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
Синтаксис:
proxy_cookie_domain off;
proxy_cookie_domain домен замена;
Умолчание:
proxy_cookie_domain off;
Контекст:
http, server, location
Эта директива появилась в версии 1.1.15.
Задаёт текст, который нужно изменить в атрибуте domain
полей “Set-Cookie” заголовка ответа проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка
“Set-Cookie” с атрибутом
“domain=localhost”.
Директива
proxy_cookie_domain localhost example.org;
перепишет данный атрибут в виде
“domain=example.org”.
Точка в начале строк домен и замена,
а равно как и в атрибуте domain игнорируется.
Регистр значения не имеет.
В строках домен и замена можно использовать
переменные:
proxy_cookie_domain www.$host $host;
Директиву также можно задать при помощи регулярных выражений.
При этом домен должен начинаться с символа
“~”.
Регулярное выражение может содержать именованные и позиционные выделения,
а замена ссылаться на них:
proxy_cookie_domain ~\.(?P<sl_domain>[-0-9a-z]+\.[a-z]+)$ $sl_domain;
На одном уровне может быть указано
несколько директив proxy_cookie_domain:
proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;
Если к куке могут быть применены несколько директив,
будет выбрана первая из них.
Параметр off отменяет действие
унаследованных с предыдущего уровня конфигурации
директив proxy_cookie_domain.
Синтаксис:
proxy_cookie_flags
off |
кука
[флаг ...];
Умолчание:
proxy_cookie_flags off;
Контекст:
http, server, location
Эта директива появилась в версии 1.19.3.
Задаёт один или несколько флагов для куки.
В качестве куки
можно использовать текст, переменные и их комбинации.
В качестве флага
можно использовать текст, переменные и их комбинации (1.19.8).
Параметры
secure,
httponly,
samesite=strict,
samesite=lax,
samesite=none
добавляют соответствующие флаги.
Параметры
nosecure,
nohttponly,
nosamesite
удаляют соответствующие флаги.
Куки также можно задать при помощи регулярных выражений.
При этом кука должна начинаться с символа
“~”.
На одном уровне конфигурации может быть указано
несколько директив proxy_cookie_flags:
proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;
Если к куке могут быть применены несколько директив,
будет выбрана первая из них.
В данном примере флаг httponly
добавляется к куке one,
для остальных кук
добавляется флаг samesite=strict и
удаляется флаг secure.
Параметр off отменяет действие всех директив
proxy_cookie_flags
на данном уровне.
Синтаксис:
proxy_cookie_path off;
proxy_cookie_path путь замена;
Умолчание:
proxy_cookie_path off;
Контекст:
http, server, location
Эта директива появилась в версии 1.1.15.
Задаёт текст, который нужно изменить в атрибуте path
полей “Set-Cookie” заголовка ответа проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка
“Set-Cookie” с атрибутом
“path=/two/some/uri/”.
Директива
proxy_cookie_path /two/ /;
перепишет данный атрибут в виде
“path=/some/uri/”.
В строках путь и замена можно использовать
переменные:
proxy_cookie_path $uri /some$uri;
Директиву также можно задать при помощи регулярных выражений.
При этом путь должен начинаться либо с символа
“~”, если при сравнении следует учитывать регистр символов,
либо с символов “~*”, если регистр символов учитывать
не нужно.
Регулярное выражение может содержать именованные и позиционные выделения,
а замена ссылаться на них:
proxy_cookie_path ~*^/user/([^/]+) /u/$1;
На одном уровне может быть указано
несколько директив proxy_cookie_path:
proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;
Если к куке могут быть применены несколько директив,
будет выбрана первая из них.
Параметр off отменяет действие
унаследованных с предыдущего уровня конфигурации
директив proxy_cookie_path.
Синтаксис:
proxy_force_ranges on | off;
Умолчание:
proxy_force_ranges off;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.7.
Включает поддержку диапазонов запрашиваемых байт (byte-range)
для кэшированных и некэшированных ответов проксируемого сервера
вне зависимости от наличия поля “Accept-Ranges”
в заголовках этих ответов.
Синтаксис:
proxy_headers_hash_bucket_size размер;
Умолчание:
proxy_headers_hash_bucket_size 64;
Контекст:
http, server, location
Задаёт размер корзины для хэш-таблиц,
используемых директивами proxy_hide_header
и proxy_set_header.
Подробнее настройка хэш-таблиц обсуждается в отдельном
документе.
Синтаксис:
proxy_headers_hash_max_size размер;
Умолчание:
proxy_headers_hash_max_size 512;
Контекст:
http, server, location
Задаёт максимальный размер хэш-таблиц,
используемых директивами proxy_hide_header и
proxy_set_header.
Подробнее настройка хэш-таблиц обсуждается в отдельном
документе.
Синтаксис:
proxy_hide_header поле;
Умолчание:
—
Контекст:
http, server, location
По умолчанию
nginx не передаёт клиенту поля заголовка “Date”,
“Server”, “X-Pad” и
“X-Accel-...” из ответа проксированного сервера.
Директива proxy_hide_header задаёт дополнительные поля,
которые не будут передаваться.
Если же передачу полей нужно разрешить, можно воспользоваться
директивой proxy_pass_header.
Синтаксис:
proxy_http_version
1.0 | 1.1 |
2;
Умолчание:
proxy_http_version 1.1;
Контекст:
http, server, location
Эта директива появилась в версии 1.1.4.
Задаёт версию протокола HTTP для проксирования.
Начиная с 1.29.7 по умолчанию используется версия 1.1.
До версии 1.29.7 по умолчанию использовалась версия 1.0.
Для работы
постоянных
соединений и
проверки подлинности
NTLM рекомендуется версия 1.1 или 2 (1.29.4).
Для версии 2 необходим
модуль ngx_http_v2_module.
Синтаксис:
proxy_ignore_client_abort on | off;
Умолчание:
proxy_ignore_client_abort off;
Контекст:
http, server, location
Определяет, закрывать ли соединение с проксированным сервером
в случае, если клиент закрыл соединение, не дождавшись ответа.
Синтаксис:
proxy_ignore_headers поле ...;
Умолчание:
—
Контекст:
http, server, location
Запрещает обработку некоторых полей заголовка из ответа проксированного сервера.
В директиве можно указать поля “X-Accel-Redirect”,
“X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6),
“X-Accel-Buffering” (1.1.6),
“X-Accel-Charset” (1.1.6), “Expires”,
“Cache-Control”, “Set-Cookie” (0.8.44)
и “Vary” (1.7.7).
Если не запрещено, обработка этих полей заголовка заключается в следующем:
“X-Accel-Expires”, “Expires”,
“Cache-Control”, “Set-Cookie”
и “Vary”
задают параметры кэширования ответа;
“X-Accel-Redirect” производит
внутреннее
перенаправление на указанный URI;
“X-Accel-Limit-Rate” задаёт
ограничение
скорости передачи ответа клиенту;
“X-Accel-Buffering” включает или выключает
буферизацию ответа;
“X-Accel-Charset” задаёт желаемую
кодировку
ответа.
Синтаксис:
proxy_intercept_errors on | off;
Умолчание:
proxy_intercept_errors off;
Контекст:
http, server, location
Определяет, передавать ли клиенту проксированные ответы с кодом
больше либо равным 300,
или же перехватывать их и перенаправлять на обработку nginx’у с помощью
директивы error_page.
Синтаксис:
proxy_limit_rate скорость;
Умолчание:
proxy_limit_rate 0;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.7.
Ограничивает скорость чтения ответа от проксируемого сервера.
Скорость задаётся в байтах в секунду.
Значение 0 отключает ограничение скорости.
Ограничение устанавливается на запрос,
поэтому, если nginx одновременно
откроет два соединения к проксируемому серверу,
суммарная скорость будет вдвое выше заданного ограничения.
Ограничение работает только в случае, если включена
буферизация ответов проксируемого сервера.
В значении параметра можно использовать переменные (1.27.0).
Синтаксис:
proxy_max_temp_file_size размер;
Умолчание:
proxy_max_temp_file_size 1024m;
Контекст:
http, server, location
Если включена буферизация ответов
проксируемого сервера, и ответ не вмещается целиком в буферы,
заданные директивами proxy_buffer_size и
proxy_buffers, часть ответа может быть записана во временный файл.
Эта директива задаёт максимальный размер временного файла.
Размер данных, сбрасываемых во временный файл за один раз, задаётся
директивой proxy_temp_file_write_size.
Значение 0 отключает возможность буферизации ответов во временные файлы.
Данное ограничение не распространяется на ответы,
которые будут закэшированы
или сохранены на диске.
Синтаксис:
proxy_method метод;
Умолчание:
—
Контекст:
http, server, location
Задаёт HTTP-метод, который будет использоваться
в передаваемых на проксируемый сервер запросах вместо метода
из клиентского запроса.
В значении параметра допустимо использование переменных (1.11.6).
Синтаксис:
proxy_next_upstream
error |
timeout |
denied |
invalid_header |
http_500 |
http_502 |
http_503 |
http_504 |
http_403 |
http_404 |
http_429 |
non_idempotent |
off
...;
Умолчание:
proxy_next_upstream error timeout;
Контекст:
http, server, location
Определяет, в каких случаях запрос будет передан следующему серверу:
error
произошла ошибка соединения с сервером, передачи ему запроса или
чтения заголовка ответа сервера;
timeout
произошёл таймаут во время соединения с сервером,
передачи ему запроса или чтения заголовка ответа сервера;
denied
сервер отклонил
соединение (1.29.3);
Параметр доступен как часть
коммерческой подписки.
invalid_header
сервер вернул пустой или неверный ответ;
http_500
сервер вернул ответ с кодом 500;
http_502
сервер вернул ответ с кодом 502;
http_503
сервер вернул ответ с кодом 503;
http_504
сервер вернул ответ с кодом 504;
http_403
сервер вернул ответ с кодом 403;
http_404
сервер вернул ответ с кодом 404;
http_429
сервер вернул ответ с кодом 429 (1.11.13);
non_idempotent
обычно запросы с
неидемпотентным
методом
(POST, LOCK, PATCH)
не передаются на другой сервер,
если запрос серверу группы уже был отправлен (1.9.13);
включение параметра явно разрешает повторять подобные запросы;
off
запрещает передачу запроса следующему серверу.
Необходимо понимать, что передача запроса следующему серверу возможна
только при условии, что клиенту ещё ничего не передавалось.
То есть, если ошибка или таймаут возникли в середине передачи ответа
клиенту, то исправить это уже невозможно.
Директива также определяет, что считается
неудачной
попыткой работы с сервером.
Случаи error, timeout,
denied и
invalid_header
всегда считаются неудачными попытками, даже если они не указаны в директиве.
Случаи http_500, http_502,
http_503, http_504
и http_429
считаются неудачными попытками, только если они указаны в директиве.
Случаи http_403 и http_404
никогда не считаются неудачными попытками.
Передача запроса следующему серверу может быть ограничена по
количеству попыток
и по времени.
Синтаксис:
proxy_next_upstream_timeout время;
Умолчание:
proxy_next_upstream_timeout 0;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.5.
Ограничивает время, в течение которого возможна передача запроса
следующему серверу.
Значение 0 отключает это ограничение.
Синтаксис:
proxy_next_upstream_tries число;
Умолчание:
proxy_next_upstream_tries 0;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.5.
Ограничивает число допустимых попыток для передачи запроса
следующему серверу.
Значение 0 отключает это ограничение.
Синтаксис:
proxy_no_cache строка ...;
Умолчание:
—
Контекст:
http, server, location
Задаёт условия, при которых ответ не будет сохраняться в кэш.
Если значение хотя бы одного из строковых параметров непустое и не равно “0”,
то ответ не будет сохранён:
proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;
Можно использовать совместно с директивой proxy_cache_bypass.
Синтаксис:
proxy_pass URL;
Умолчание:
—
Контекст:
location, if в location, limit_except
Задаёт протокол и адрес проксируемого сервера, а также необязательный URI,
на который должен отображаться location.
В качестве протокола можно указать
“http” или “https”.
Адрес может быть указан в виде доменного имени или IP-адреса,
и необязательного порта:
proxy_pass http://localhost:8000/uri/;
или в виде пути UNIX-сокета, который указывается после слова
“unix” и заключается в двоеточия:
proxy_pass http://unix:/tmp/backend.socket:/uri/;
Если доменному имени соответствует несколько адресов, то все они будут
использоваться по очереди (round-robin).
Кроме того, в качестве адреса можно указать
группу серверов.
В значении параметра можно использовать переменные.
В этом случае, если адрес указан в виде доменного имени,
имя ищется среди описанных групп серверов
и если не найдено, то определяется с помощью
resolver’а.
URI запроса передаётся на сервер так:
Если директива proxy_pass указана с URI,
то при передаче запроса серверу часть
нормализованного
URI запроса, соответствующая location, заменяется на URI,
указанный в директиве:
location /name/ {
proxy_pass http://127.0.0.1/remote/;
}
Если директива proxy_pass указана без URI,
то при обработке первоначального запроса на сервер передаётся
URI запроса в том же виде, в каком его прислал клиент,
а при обработке изменённого URI -
нормализованный URI запроса целиком:
location /some/path/ {
proxy_pass http://127.0.0.1;
}
До версии 1.1.12,
если proxy_pass указана без URI,
в ряде случаев при изменении URI на сервер мог передаваться
URI первоначального запроса вместо изменённого URI.
В ряде случаев часть URI запроса, подлежащую замене, выделить невозможно:
Если location задан регулярным выражением,
а также в именованных location’ах.
В этих случаях
proxy_pass следует указывать без URI.
Если внутри проксируемого location с помощью директивы
rewrite изменяется
URI, и именно с этой конфигурацией будет обрабатываться запрос
(break):
location /name/ {
rewrite    /name/([^/]+) /users?name=$1 break;
proxy_pass http://127.0.0.1;
}
В этом случае URI, указанный в директиве, игнорируется, и на сервер
передаётся изменённый URI запроса целиком.
При использовании переменных в proxy_pass:
location /name/ {
proxy_pass http://127.0.0.1$request_uri;
}
В этом случае если в директиве указан URI,
он передаётся на сервер как есть,
заменяя URI первоначального запроса.
Проксирование WebSocket требует особой
настройки и поддерживается начиная с версии 1.3.13.
Синтаксис:
proxy_pass_header поле;
Умолчание:
—
Контекст:
http, server, location
Разрешает передавать от проксируемого сервера клиенту
запрещённые для передачи поля заголовка.
Синтаксис:
proxy_pass_request_body on | off;
Умолчание:
proxy_pass_request_body on;
Контекст:
http, server, location
Позволяет запретить передачу исходного тела запроса
на проксируемый сервер.
location /x-accel-redirect-here/ {
proxy_method GET;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_pass ...
}
См. также директивы proxy_set_header и
proxy_pass_request_headers.
Синтаксис:
proxy_pass_request_headers on | off;
Умолчание:
proxy_pass_request_headers on;
Контекст:
http, server, location
Позволяет запретить передачу полей заголовка исходного запроса на
проксируемый сервер.
location /x-accel-redirect-here/ {
proxy_method GET;
proxy_pass_request_headers off;
proxy_pass_request_body off;
proxy_pass ...
}
См. также директивы proxy_set_header и
proxy_pass_request_body.
Синтаксис:
proxy_pass_trailers on | off;
Умолчание:
proxy_pass_trailers off;
Контекст:
http, server, location
Эта директива появилась в версии 1.27.2.
Разрешает передавать от проксируемого сервера клиенту поля заголовка
в конце ответа.
Использование заголовков в конце ответа включается
явным образом:
location / {
# proxy_http_version  1.1;  # версии до 1.29.7
proxy_set_header      Connection "te";
proxy_set_header      TE "trailers";
proxy_pass_trailers   on;
proxy_pass ...
}
Заголовки в конце ответа, полученные от
вышестоящего сервера, передаются клиенту как есть, без интерпретации.
Синтаксис:
proxy_read_timeout время;
Умолчание:
proxy_read_timeout 60s;
Контекст:
http, server, location
Задаёт таймаут при чтении ответа проксированного сервера.
Таймаут устанавливается не на всю передачу ответа,
а только между двумя операциями чтения.
Если по истечении этого времени проксируемый сервер ничего не передаст,
соединение закрывается.
Синтаксис:
proxy_redirect default;
proxy_redirect off;
proxy_redirect перенаправление замена;
Умолчание:
proxy_redirect default;
Контекст:
http, server, location
Задаёт текст, который нужно изменить в полях заголовка
“Location” и “Refresh” в ответе
проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка
“Location: http://localhost:8000/two/some/uri/”.
Директива
proxy_redirect http://localhost:8000/two/ http://frontend/one/;
перепишет эту строку в виде
“Location: http://frontend/one/some/uri/”.
В заменяемой строке можно не указывать имя сервера:
proxy_redirect http://localhost:8000/two/ /;
тогда будут подставлены основное имя сервера и порт, если он отличен от 80.
Стандартная замена, задаваемая параметром default,
использует параметры директив
location и
proxy_pass.
Поэтому две нижеприведённые конфигурации одинаковы:
location /one/ {
proxy_pass     http://upstream:port/two/;
proxy_redirect default;
location /one/ {
proxy_pass     http://upstream:port/two/;
proxy_redirect http://upstream:port/two/ /one/;
Параметр default недопустим, если в proxy_pass
используются переменные.
В строке замена можно использовать переменные:
proxy_redirect http://localhost:8000/ http://$host:$server_port/;
В строке перенаправление тоже можно использовать (1.1.11)
переменные:
proxy_redirect http://$proxy_host:8000/ /;
Директиву также можно задать (1.1.11) при помощи регулярных выражений.
При этом перенаправление должно начинаться либо с символа
“~”, если при сравнении следует учитывать регистр символов,
либо с символов “~*”, если регистр символов учитывать
не нужно.
Регулярное выражение может содержать именованные и позиционные выделения,
а замена ссылаться на них:
proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;
На одном уровне может быть указано
несколько директив proxy_redirect:
proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;
Если к полям заголовка в ответе проксируемого сервера
могут быть применены несколько директив,
будет выбрана первая из них.
Параметр off отменяет действие
унаследованных с предыдущего уровня конфигурации
директив proxy_redirect.
С помощью этой директивы можно также добавлять имя хоста к относительным
перенаправлениям, выдаваемым проксируемым сервером:
proxy_redirect / /;
Синтаксис:
proxy_request_buffering on | off;
Умолчание:
proxy_request_buffering on;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.11.
Разрешает или запрещает использовать буферизацию тела запроса клиента.
Если буферизация включена, то тело запроса полностью
читается
от клиента перед отправкой запроса на проксируемый сервер.
Если буферизация выключена, то тело запроса отправляется
на проксируемый сервер сразу же по мере его поступления.
В этом случае запрос не может быть передан
следующему серверу,
если nginx уже начал отправку тела запроса.
Если для отправки тела исходного запроса используется HTTP/1.1
и передача данных частями (chunked transfer encoding),
то тело запроса буферизуется независимо от значения директивы,
если для проксирования также не
включён HTTP/1.1 или HTTP/2.
Синтаксис:
proxy_request_dynamic on | off;
Умолчание:
proxy_request_dynamic off;
Контекст:
http, server, location
Эта директива появилась в версии 1.29.3.
Разрешает или запрещает создание отдельного экземпляра запроса
для каждого проксируемого сервера.
По умолчанию для всех проксируемых серверов используется единый запрос.
Если разрешено, то для каждого сервера создаётся отдельный экземпляр запроса,
что позволяет кастомизировать запрос для конкретного сервера.
Например каждому серверу можно назначить своё значение
поля “Host” в заголовке запроса:
proxy_request_dynamic on;
proxy_set_header      Host $upstream_last_server_name;
Директива доступна как часть
коммерческой подписки.
Синтаксис:
proxy_send_lowat размер;
Умолчание:
proxy_send_lowat 0;
Контекст:
http, server, location
При установке директивы в ненулевое значение nginx будет пытаться минимизировать
число операций отправки на исходящих соединениях с проксируемым сервером либо
при помощи флага NOTE_LOWAT метода
kqueue,
либо при помощи параметра сокета SO_SNDLOWAT,
с указанным размером.
Эта директива игнорируется на Linux, Solaris и Windows.
Синтаксис:
proxy_send_timeout время;
Умолчание:
proxy_send_timeout 60s;
Контекст:
http, server, location
Задаёт таймаут при передаче запроса проксированному серверу.
Таймаут устанавливается не на всю передачу запроса,
а только между двумя операциями записи.
Если по истечении этого времени проксируемый сервер не примет новых данных,
соединение закрывается.
Синтаксис:
proxy_set_body значение;
Умолчание:
—
Контекст:
http, server, location
Позволяет переопределить тело запроса, передаваемое на проксируемый сервер.
В качестве значения можно использовать текст, переменные и их комбинации.
Синтаксис:
proxy_set_header поле значение;
Умолчание:
proxy_set_header Host $proxy_host;
proxy_set_header Connection close;
Контекст:
http, server, location
Позволяет переопределять или добавлять поля заголовка запроса,
передаваемые проксируемому серверу.
В качестве значения можно использовать текст, переменные и их комбинации.
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы proxy_set_header.
По умолчанию поля заголовка
“Host”
и
“Connection”
исходного запроса не передаются на проксируемый сервер.
Если для проксирования
включён HTTP/1.0 или HTTP/1.1,
эти поля переопределяются:
proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;
Для HTTP/2 по умолчанию передаётся поле псевдо-заголовка
“:authority”
со значением
$proxy_host,
при условии что поле заголовка “Host” не задано явно.
Если включено кэширование, поля заголовка
“If-Modified-Since”,
“If-Unmodified-Since”,
“If-None-Match”,
“If-Match”,
“Range”
и
“If-Range”
исходного запроса не передаются на проксируемый сервер.
Неизменённое поле заголовка запроса “Host” можно передать так:
proxy_set_header Host       $http_host;
Однако, если это поле отсутствует в заголовке запроса клиента, то ничего
передаваться не будет.
В этом случае лучше воспользоваться переменной $host - её
значение равно имени сервера в поле “Host”
заголовка запроса, или же основному имени сервера, если поля нет:
proxy_set_header Host       $host;
Кроме того, можно передать имя сервера вместе с портом проксируемого сервера:
proxy_set_header Host       $host:$proxy_port;
Если значение поля заголовка — пустая строка, то поле вообще
не будет передаваться проксируемому серверу:
proxy_set_header Accept-Encoding "";
Синтаксис:
proxy_socket_keepalive on | off;
Умолчание:
proxy_socket_keepalive off;
Контекст:
http, server, location
Эта директива появилась в версии 1.15.6.
Конфигурирует поведение “TCP keepalive”
для исходящих соединений к проксируемому серверу.
По умолчанию для сокета действуют настройки операционной системы.
Если указано значение “on”, то
для сокета включается параметр SO_KEEPALIVE.
Синтаксис:
proxy_socket_rcvbuf size;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.31.3.
Задаёт размер буфера приёма
(параметр SO_RCVBUF)
для исходящих соединений к проксируемому серверу.
Специальное значение 0 отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы proxy_socket_rcvbuf, позволяя
использовать настройки операционной системы.
Синтаксис:
proxy_socket_sndbuf size;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.31.3.
Задаёт размер буфера передачи
(параметр SO_SNDBUF)
для исходящих соединений к проксируемому серверу.
Специальное значение 0 отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы proxy_socket_sndbuf, позволяя
использовать настройки операционной системы.
Синтаксис:
proxy_ssl_certificate файл;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.7.8.
Задаёт файл с сертификатом в формате PEM
для аутентификации на проксируемом HTTPS-сервере.
Начиная с версии 1.21.0 в имени файла можно использовать переменные.
Синтаксис:
proxy_ssl_certificate_cache off;
proxy_ssl_certificate_cache
max=N
[inactive=время]
[valid=время];
Умолчание:
proxy_ssl_certificate_cache off;
Контекст:
http, server, location
Эта директива появилась в версии 1.27.4.
Задаёт кэш, в котором могут храниться
SSL-сертификаты и
секретные ключи,
полученные из переменных.
У директивы есть следующие параметры:
max
задаёт максимальное число элементов в кэше;
при переполнении кэша удаляются наименее востребованные элементы (LRU);
inactive
задаёт время, после которого элемент кэша удаляется,
если к нему не было обращений в течение этого времени;
по умолчанию 10 секунд;
valid
задает время, в течение которого
элемент кэша считается действительным
и может быть повторно использован,
по умолчанию 60 секунд.
По завершении этого времени сертификат будет обновлён или повторно проверен;
off
запрещает кэш.
Пример:
proxy_ssl_certificate       $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key   $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;
Синтаксис:
proxy_ssl_certificate_key файл;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.7.8.
Задаёт файл с секретным ключом в формате PEM
для аутентификации на проксируемом HTTPS-сервере.
Вместо файла можно указать значение
engine:имя:id (1.7.9),
которое загружает ключ с указанным id
из OpenSSL engine с заданным именем.
Вместо файла можно указать значение
store:схема:id (1.29.0),
которое используется для загрузки ключа с указанным id
и зарегистрированной провайдером OpenSSL схемой URI, такой как
pkcs11.
Начиная с версии 1.21.0 в имени файла можно использовать переменные.
Синтаксис:
proxy_ssl_ciphers шифры;
Умолчание:
proxy_ssl_ciphers DEFAULT;
Контекст:
http, server, location
Эта директива появилась в версии 1.5.6.
Описывает разрешённые шифры для запросов к проксируемому HTTPS-серверу.
Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Полный список можно посмотреть с помощью команды
“openssl ciphers”.
Синтаксис:
proxy_ssl_conf_command имя значение;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.19.4.
Задаёт произвольные конфигурационные
команды
OpenSSL
при установлении соединения с проксируемым HTTPS-сервером.
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
На одном уровне может быть указано
несколько директив proxy_ssl_conf_command.
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны
свои директивы proxy_ssl_conf_command.
Следует учитывать, что изменение настроек OpenSSL напрямую
может привести к неожиданному поведению.
Синтаксис:
proxy_ssl_crl файл;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.7.0.
Указывает файл с отозванными сертификатами (CRL)
в формате PEM, используемыми при проверке
сертификата проксируемого HTTPS-сервера.
Если используются промежуточные сертификаты,
их списки CRL должны находиться в этом же файле.
Синтаксис:
proxy_ssl_key_log путь;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.27.2.
Включает логирование SSL-ключей соединений с проксируемым HTTPS-сервером
и указывает путь к лог-файлу ключей.
Ключи записываются в формате
SSLKEYLOGFILE
совместимом с Wireshark.
Директива доступна как часть
коммерческой подписки.
Синтаксис:
proxy_ssl_name имя;
Умолчание:
proxy_ssl_name $proxy_host;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.0.
Позволяет переопределить имя сервера, используемое при
проверке
сертификата проксируемого HTTPS-сервера, а также для
передачи его через SNI
при установлении соединения с проксируемым HTTPS-сервером.
По умолчанию используется имя хоста из URL’а, заданного
директивой proxy_pass.
Синтаксис:
proxy_ssl_password_file файл;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.7.8.
Задаёт файл с паролями от
секретных ключей,
где каждый пароль указан на отдельной строке.
Пароли применяются по очереди в момент загрузки ключа.
Синтаксис:
proxy_ssl_protocols
[SSLv2]
[SSLv3]
[TLSv1]
[TLSv1.1]
[TLSv1.2]
[TLSv1.3];
Умолчание:
proxy_ssl_protocols TLSv1.2 TLSv1.3;
Контекст:
http, server, location
Эта директива появилась в версии 1.5.6.
Разрешает указанные протоколы для запросов к проксируемому HTTPS-серверу.
Параметр TLSv1.3 используется по умолчанию
начиная с 1.23.4.
Синтаксис:
proxy_ssl_server_name on | off;
Умолчание:
proxy_ssl_server_name off;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.0.
Разрешает или запрещает передачу имени сервера через
расширение
Server Name Indication протокола TLS (SNI, RFC 6066)
при установлении соединения с проксируемым HTTPS-сервером.
Синтаксис:
proxy_ssl_session_reuse on | off;
Умолчание:
proxy_ssl_session_reuse on;
Контекст:
http, server, location
Определяет, использовать ли повторно SSL-сессии при
работе с проксированным сервером.
Если в логах появляются ошибки
“digest check failed”,
то можно попробовать выключить
повторное использование сессий.
Синтаксис:
proxy_ssl_trusted_certificate файл;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.7.0.
Задаёт файл с доверенными сертификатами CA в формате PEM,
используемыми при проверке
сертификата проксируемого HTTPS-сервера.
Синтаксис:
proxy_ssl_verify on | off;
Умолчание:
proxy_ssl_verify off;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.0.
Разрешает или запрещает проверку сертификата проксируемого HTTPS-сервера.
Синтаксис:
proxy_ssl_verify_depth число;
Умолчание:
proxy_ssl_verify_depth 1;
Контекст:
http, server, location
Эта директива появилась в версии 1.7.0.
Устанавливает глубину проверки в цепочке сертификатов
проксируемого HTTPS-сервера.
Синтаксис:
proxy_store
on |
off |
строка;
Умолчание:
proxy_store off;
Контекст:
http, server, location
Разрешает сохранение на диск файлов.
Параметр on сохраняет файлы в соответствии с путями,
указанными в директивах
alias или
root.
Параметр off запрещает сохранение файлов.
Кроме того, имя файла можно задать явно с помощью строки с переменными:
proxy_store /data/www$original_uri;
Время изменения файлов выставляется согласно полученному полю
“Last-Modified” в заголовке ответа.
Ответ сначала записывается во временный файл, а потом этот файл
переименовывается.
Начиная с версии 0.8.9 временный файл и постоянное место хранения ответа
могут располагаться на разных файловых системах.
Однако нужно учитывать,
что в этом случае вместо дешёвой операции переименовывания в пределах
одной файловой системы файл копируется с одной файловой системы на другую.
Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой
системе, что и каталог с временными файлами, задаваемый директивой
proxy_temp_path для данного location.
Директиву можно использовать для создания локальных копий статических
неизменяемых файлов, например, так:
location /images/ {
root               /data/www;
error_page         404 = /fetch$uri;
}
location /fetch/ {
internal;
proxy_pass         http://backend/;
proxy_store        on;
proxy_store_access user:rw group:rw all:r;
proxy_temp_path    /data/temp;
alias              /data/www/;
}
или так:
location /images/ {
root               /data/www;
error_page         404 = @fetch;
}
location @fetch {
internal;
proxy_pass         http://backend;
proxy_store        on;
proxy_store_access user:rw group:rw all:r;
proxy_temp_path    /data/temp;
root               /data/www;
}
Синтаксис:
proxy_store_access пользователи:права ...;
Умолчание:
proxy_store_access user:rw;
Контекст:
http, server, location
Задаёт права доступа для создаваемых файлов и каталогов, например,
proxy_store_access user:rw group:rw all:r;
Если заданы какие-либо права для group или
all, то права для user
указывать необязательно:
proxy_store_access group:rw all:r;
Синтаксис:
proxy_temp_file_write_size размер;
Умолчание:
proxy_temp_file_write_size 8k|16k;
Контекст:
http, server, location
Ограничивает размер данных, сбрасываемых во временный файл
за один раз, при включённой буферизации ответов проксируемого сервера
во временные файлы.
По умолчанию размер ограничен двумя буферами, заданными
директивами proxy_buffer_size и proxy_buffers.
Максимальный размер временного файла задаётся директивой
proxy_max_temp_file_size.
Синтаксис:
proxy_temp_path
путь
[уровень1
[уровень2
[уровень3]]];
Умолчание:
proxy_temp_path proxy_temp;
Контекст:
http, server, location
Задаёт имя каталога для хранения временных файлов с данными,
полученными от проксируемых серверов.
В каталоге может использоваться иерархия подкаталогов до трёх уровней.
Например, при такой конфигурации
proxy_temp_path /spool/nginx/proxy_temp 1 2;
временный файл будет следующего вида:
/spool/nginx/proxy_temp/7/45/00000123457
См. также параметр use_temp_path директивы
proxy_cache_path.
Встроенные переменные
В модуле ngx_http_proxy_module есть встроенные переменные,
которые можно использовать для формирования заголовков с помощью директивы
proxy_set_header:
$proxy_host
имя и порт проксируемого сервера, как указано в
директиве proxy_pass;
$proxy_port
порт проксируемого сервера, как указано в
директиве proxy_pass, или стандартный порт протокола;
$proxy_add_x_forwarded_for
поле заголовка запроса клиента “X-Forwarded-For”
и добавленная к нему через запятую переменная $remote_addr.
Если же поля “X-Forwarded-For” в заголовке запроса клиента нет,
то переменная $proxy_add_x_forwarded_for
равна переменной $remote_addr.