Модуль 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_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;
}

Директивы

Определяет условия, при которых доступ к проксируемому серверу разрешён или запрещён. Если все строковые параметры не пусты и не равны «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;
        ...
    }
}

Эта директива доступна в рамках нашей коммерческой подписки.

Указывает локальный IP-адрес и необязательный порт (1.11.2), с которых устанавливаются исходящие соединения с проксируемым сервером. Значение параметра может содержать переменные (1.3.12). Специальное значение off (1.3.12) отменяет действие директивы proxy_bind, унаследованной с предыдущего уровня конфигурации, и позволяет системе автоматически назначать локальный IP-адрес и порт.

Параметр transparent (1.11.0) позволяет устанавливать исходящие соединения с проксируемым сервером с нелокального IP-адреса, например с реального IP-адреса клиента:

proxy_bind $remote_addr transparent;

Для работы этого параметра обычно необходимо запускать рабочие процессы nginx с привилегиями суперпользователя. В Linux это не требуется (1.13.8): если указан параметр transparent, рабочие процессы наследуют возможность CAP_NET_RAW от главного процесса. Также необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика от проксируемого сервера.

Если директива включена, операция bind выполняется при каждой попытке соединения.

Эта директива доступна в рамках нашей коммерческой подписки.

Задаёт size буфера, используемого для чтения первой части ответа, полученного от проксируемого сервера. Эта часть обычно содержит небольшой заголовок ответа; если он превышает размер буфера, ответ считается недопустимым. По умолчанию размер буфера равен одной странице памяти. В зависимости от платформы это 4K или 8K. Однако его можно уменьшить.

Включает или отключает буферизацию ответов проксируемого сервера.

При включённой буферизации 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.

Задаёт number и size буферов, используемых для чтения ответа проксируемого сервера в рамках одного соединения. По умолчанию размер буфера равен одной странице памяти. В зависимости от платформы это 4K или 8K.

Если буферизация ответов проксируемого сервера включена, ограничивает общий size буферов, занятых отправкой ответа клиенту, пока ответ ещё не прочитан полностью. Тем временем остальные буферы можно использовать для чтения ответа и, при необходимости, для буферизации части ответа во временный файл. По умолчанию size ограничен размером двух буферов, заданных директивами proxy_buffer_size и proxy_buffers.

Определяет зону разделяемой памяти, используемую для кэширования. Одну и ту же зону можно использовать в нескольких местах. Значение параметра может содержать переменные (1.7.9). Параметр off отключает кэширование, унаследованное с предыдущего уровня конфигурации.

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

Определяет условия, при которых ответ не будет браться из кэша. Если хотя бы одно значение строковых параметров не пусто и не равно «0», ответ не будет браться из кэша:

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;

Можно использовать вместе с директивой proxy_no_cache.

Включает или отключает преобразование метода «HEAD» в «GET» для кэширования. Если преобразование отключено, ключ кэша необходимо настроить так, чтобы он включал $request_method.

Определяет ключ кэширования, например

proxy_cache_key "$host$request_uri $cookie_user";

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

proxy_cache_key $scheme$proxy_host$uri$is_args$args;

Если директива включена, только один запрос за раз может заполнить новый элемент кэша, идентифицируемый директивой proxy_cache_key, передав запрос проксируемому серверу. Остальные запросы для того же элемента кэша будут ждать появления ответа в кэше или снятия блокировки этого элемента в течение времени, заданного директивой proxy_cache_lock_timeout.

Если последний запрос, переданный проксируемому серверу для заполнения нового элемента кэша, не завершился за указанный time, проксируемому серверу может быть передан ещё один запрос.

Задаёт тайм-аут для proxy_cache_lock. По истечении time запрос будет передан проксируемому серверу, однако ответ не будет кэширован.

До версии 1.7.8 ответ мог быть кэширован.

Задаёт смещение в байтах для запросов диапазона байтов. Если диапазон выходит за пределы смещения, запрос диапазона передаётся проксируемому серверу, а ответ не кэшируется.

Если метод клиентского запроса указан в этой директиве, ответ будет кэширован. Методы «GET» и «HEAD» всегда добавляются в список, хотя рекомендуется указывать их явно. См. также директиву proxy_no_cache.

Задаёт number запросов, после которого ответ будет кэшироваться.

Задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Имя файла в кэше получается в результате применения функции 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 временные файлы и кэш можно размещать в разных файловых системах. Однако учтите, что в этом случае файл копируется между двумя файловыми системами вместо дешёвой операции переименования. Поэтому рекомендуется для каждого location размещать кэш и каталог временных файлов в одной файловой системе. Каталог временных файлов задаётся параметром use_temp_path (1.7.10). Если этот параметр опущен или установлен в значение on, будет использоваться каталог, заданный директивой proxy_temp_path для данного location. Если значение установлено в off, временные файлы будут помещаться непосредственно в каталог кэша.

Кроме того, все активные ключи и сведения о данных хранятся в зоне разделяемой памяти, name и size которой задаются параметром keys_zone. Зона размером один мегабайт может хранить около 8 тысяч ключей.

В рамках коммерческой подписки в зоне разделяемой памяти также хранится расширенная информация о кэше, поэтому для того же количества ключей требуется указать больший размер зоны. Например, зона размером один мегабайт может хранить около 4 тысяч ключей.

Кэшированные данные, к которым не обращались в течение времени, указанного параметром inactive, удаляются из кэша независимо от их актуальности. По умолчанию inactive устанавливается в 10 минут.

Специальный процесс «cache manager» отслеживает максимальный размер кэша, заданный параметром max_size, и минимальный объём свободного места, задаваемый параметром min_free (1.19.1), в файловой системе с кэшем. Если размер превышен или свободного места недостаточно, процесс удаляет данные, к которым обращались давнее всего. Удаление выполняется итерациями, настраиваемыми параметрами manager_files, manager_threshold и manager_sleep (1.11.5). За одну итерацию удаляется не более manager_files элементов (по умолчанию — 100). Длительность одной итерации ограничена параметром manager_threshold (по умолчанию — 200 миллисекунд). Между итерациями делается пауза, задаваемая параметром manager_sleep (по умолчанию — 50 миллисекунд).

Через минуту после запуска активируется специальный процесс «cache loader». Он загружает в зону кэша сведения о ранее кэшированных данных, хранящихся в файловой системе. Загрузка также выполняется итерациями. За одну итерацию загружается не более loader_files элементов (по умолчанию — 100). Кроме того, длительность одной итерации ограничена параметром loader_threshold (по умолчанию — 200 миллисекунд). Между итерациями делается пауза, задаваемая параметром loader_sleep (по умолчанию — 50 миллисекунд).

Кроме того, в рамках нашей коммерческой подписки доступны следующие параметры:

purger=on|off

Указывает, следует ли удалять с диска записи кэша, соответствующие шаблону с подстановочными знаками, с помощью очистителя кэша (1.7.12). Установка параметра в on (по умолчанию — off) активирует процесс «cache purger», который постоянно перебирает все записи кэша и удаляет записи, соответствующие шаблону с подстановочными знаками.

purger_files=number

Задаёт количество элементов, которые будут просканированы за одну итерацию (1.7.12). По умолчанию purger_files устанавливается в 10.

purger_threshold=number

Задаёт длительность одной итерации (1.7.12). По умолчанию purger_threshold устанавливается в 50 миллисекунд.

purger_sleep=number

Задаёт паузу между итерациями (1.7.12). По умолчанию purger_sleep устанавливается в 50 миллисекунд.

В версиях 1.7.3, 1.7.7 и 1.11.10 был изменён формат заголовка кэша. После обновления до более новой версии nginx ранее кэшированные ответы будут считаться недействительными.

Определяет условия, при которых запрос считается запросом на очистку кэша. Если хотя бы одно значение строковых параметров не пусто и не равно «0», запись кэша с соответствующим ключом кэша удаляется. Успешное выполнение операции подтверждается ответом 204 (No Content).

Если ключ кэша запроса на очистку заканчивается звёздочкой («*»), из кэша будут удалены все записи, соответствующие ключу-шаблону. Однако эти записи останутся на диске, пока не будут удалены из-за бездействия, не будут обработаны очистителем кэша (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;
    }
}

Эта функциональность доступна в рамках нашей коммерческой подписки.

Включает повторную проверку актуальности устаревших элементов кэша с помощью условных запросов с полями заголовка «If-Modified-Since» и «If-None-Match».

Определяет, в каких случаях при обмене данными с проксируемым сервером можно использовать устаревший кэшированный ответ. Параметры директивы соответствуют параметрам директивы proxy_next_upstream.

Параметр error также разрешает использовать устаревший кэшированный ответ, если не удаётся выбрать проксируемый сервер для обработки запроса.

Кроме того, параметр updating разрешает использовать устаревший кэшированный ответ, если он в данный момент обновляется. Это позволяет свести к минимуму количество обращений к проксируемым серверам при обновлении кэшированных данных.

Использование устаревшего кэшированного ответа также можно разрешить непосредственно в заголовке ответа на указанное количество секунд после того, как ответ устарел (1.11.10). Этот способ имеет более низкий приоритет, чем параметры директивы.

• Расширение “stale-while-revalidate” поля заголовка “Cache-Control” разрешает использовать устаревший кэшированный ответ, если он в данный момент обновляется.
• Расширение “stale-if-error” поля заголовка “Cache-Control” разрешает использовать устаревший кэшированный ответ в случае ошибки.

Чтобы свести к минимуму количество обращений к проксируемым серверам при заполнении нового элемента кэша, можно использовать директиву proxy_cache_lock.

Задаёт время кэширования для различных кодов ответа. Например, следующие директивы

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

задают кэширование на 10 минут для ответов с кодами 200 и 302 и на 1 минуту для ответов с кодом 404.

Если указано только кэширование time

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” задаёт время кэширования ответа в секундах. Нулевое значение отключает кэширование ответа. Если значение начинается с префикса @, оно задаёт абсолютное время в секундах с начала эпохи, до которого ответ может кэшироваться.
• Если заголовок не содержит поля “X-Accel-Expires”, параметры кэширования можно задать в полях заголовка “Expires” или “Cache-Control”.
• Если заголовок содержит поле “Set-Cookie”, такой ответ не будет кэшироваться.
• Если заголовок содержит поле “Vary” со специальным значением “*”, такой ответ не будет кэшироваться (1.7.7). Если заголовок содержит поле “Vary” с другим значением, такой ответ будет кэшироваться с учётом соответствующих полей заголовка запроса (1.7.7).

Обработку одного или нескольких из этих полей заголовка ответа можно отключить с помощью директивы proxy_ignore_headers.

Задаёт тайм-аут установления соединения с проксируемым сервером. Следует учитывать, что обычно этот тайм-аут не может превышать 75 секунд.

Задаёт текст, который следует изменить в атрибуте domain полей заголовка “Set-Cookie” в ответе проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка “Set-Cookie” с атрибутом “domain=localhost”. Директива

proxy_cookie_domain localhost example.org;

перепишет этот атрибут в «domain=example.org».

Точка в начале строк domain и replacement, а также атрибут domain игнорируется. Сопоставление не учитывает регистр.

Строки domain и replacement могут содержать переменные:

proxy_cookie_domain www.$host $host;

Директиву также можно задать с помощью регулярных выражений. В этом случае domain должно начинаться с символа «~». Регулярное выражение может содержать именованные и позиционные захваты, на которые может ссылаться replacement:

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;

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

Параметр off отменяет действие директив proxy_cookie_domain, унаследованных с предыдущего уровня конфигурации.

Устанавливает один или несколько флагов для файла cookie. cookie может содержать текст, переменные и их комбинации. flag может содержать текст, переменные и их комбинации (1.19.8). Параметры secure, httponly, samesite=strict, samesite=lax, samesite=none добавляют соответствующие флаги. Параметры nosecure, nohttponly, nosamesite удаляют соответствующие флаги.

Файл cookie также можно задать с помощью регулярных выражений. В этом случае cookie должно начинаться с символа «~».

На одном уровне конфигурации можно задать несколько директив proxy_cookie_flags:

proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;

Если к файлу cookie применимо несколько директив, будет выбрана первая совпавшая. В примере флаг httponly добавляется к файлу cookie one, а для всех остальных файлов cookie добавляется флаг samesite=strict и удаляется флаг secure.

Параметр off отменяет действие директив proxy_cookie_flags, унаследованных с предыдущего уровня конфигурации.

Задает текст, который следует изменить в атрибуте path полей заголовка «Set-Cookie» ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка «Set-Cookie» с атрибутом «path=/two/some/uri/». Директива

proxy_cookie_path /two/ /;

перепишет этот атрибут в «path=/some/uri/».

Строки path и replacement могут содержать переменные:

proxy_cookie_path $uri /some$uri;

Директиву также можно задать с помощью регулярных выражений. В этом случае path должно начинаться либо с символа «~» для сопоставления с учетом регистра, либо с символов «~*» для сопоставления без учета регистра. Регулярное выражение может содержать именованные и позиционные захваты, на которые может ссылаться replacement:

proxy_cookie_path ~*^/user/([^/]+) /u/$1;

На одном уровне можно задать несколько директив proxy_cookie_path:

proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;

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

Параметр off отменяет действие директив proxy_cookie_path, унаследованных с предыдущего уровня конфигурации.

Включает поддержку диапазонов байтов для кэшируемых и некэшируемых ответов проксируемого сервера независимо от поля «Accept-Ranges» в этих ответах.

Задает размер сегмента size для хеш-таблиц, используемых директивами proxy_hide_header и proxy_set_header. Подробное описание настройки хеш-таблиц приведено в отдельном документе.

Задает максимальный size хеш-таблиц, используемых директивами proxy_hide_header и proxy_set_header. Подробное описание настройки хеш-таблиц приведено в отдельном документе.

По умолчанию nginx не передает клиенту поля заголовка «Date», «Server», «X-Pad» и «X-Accel-...» из ответа проксируемого сервера. Директива proxy_hide_header задает дополнительные поля, которые не будут передаваться. Если же необходимо разрешить передачу полей, можно использовать директиву proxy_pass_header.

Задает версию протокола HTTP для проксирования. Начиная с версии 1.29.7 по умолчанию используется версия 1.1. До версии 1.29.7 по умолчанию использовалась версия 1.0. Для использования с соединениями keepalive и аутентификацией NTLM рекомендуется версия 1.1 или 2 (1.29.4).

Для версии 2 требуется модуль ngx_http_v2_module.

Определяет, следует ли закрыть соединение с проксируемым сервером, если клиент закрывает соединение, не дождавшись ответа.

Отключает обработку некоторых полей заголовка ответа проксируемого сервера. Можно игнорировать следующие поля: «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» задает требуемую кодировку ответа.

Определяет, следует ли передавать клиенту ответы проксируемого сервера с кодом не меньше 300 или перехватывать их и перенаправлять в nginx для обработки директивой error_page.

Ограничивает скорость чтения ответа от проксируемого сервера. rate задается в байтах в секунду. Нулевое значение отключает ограничение скорости. Ограничение задается для одного запроса, поэтому, если nginx одновременно открывает два соединения с проксируемым сервером, общая скорость будет вдвое выше заданного ограничения. Ограничение действует только при включенной буферизации ответов проксируемого сервера. Значение параметра может содержать переменные (1.27.0).

Если включена буферизация ответов проксируемого сервера и ответ целиком не помещается в буферы, заданные директивами proxy_buffer_size и proxy_buffers, часть ответа может быть сохранена во временный файл. Эта директива задает максимальный size временного файла. Размер данных, записываемых во временный файл за один раз, задается директивой proxy_temp_file_write_size.

Нулевое значение отключает буферизацию ответов во временные файлы.

Это ограничение не распространяется на ответы, которые будут кэшироваться или сохраняться на диске.

Задает HTTP-метод method, используемый в запросах к проксируемому серверу вместо метода клиентского запроса. Значение параметра может содержать переменные (1.11.6).

Задает случаи, в которых запрос следует передать следующему серверу:

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 никогда не считаются неудачными попытками.

Передача запроса следующему серверу может быть ограничена числом попыток и временем.

Ограничивает время, в течение которого запрос может передаваться следующему серверу. Значение 0 отключает это ограничение.

Ограничивает число попыток передачи запроса следующему серверу. Значение 0 отключает это ограничение.

Задает условия, при которых ответ не будет сохраняться в кэш. Если хотя бы одно значение строковых параметров не пусто и не равно «0», ответ не будет сохранен:

proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;

Можно использовать вместе с директивой proxy_cache_bypass.

Задает протокол и адрес проксируемого сервера, а также необязательный URI, на который следует перенаправить location. В качестве протокола можно указать «http» или «https». Адрес можно задать как доменное имя или IP-адрес, а также указать необязательный порт:

proxy_pass http://localhost:8000/uri/;

либо путь к доменному сокету UNIX, указанный после слова «unix» и заключенный в двоеточия:

proxy_pass http://unix:/tmp/backend.socket:/uri/;

Если доменное имя разрешается в несколько адресов, все они будут использоваться по очереди. Кроме того, адрес можно задать как группу серверов.

Значение параметра может содержать переменные. В этом случае, если адрес задан как доменное имя, имя ищется среди описанных групп серверов, а если оно не найдено — определяется с помощью резолвера.

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 запроса, которую нужно заменить:

• Когда location задана с помощью регулярного выражения, а также внутри именованных location.

  В таких случаях proxy_pass следует задавать без URI.

• Когда URI изменяется внутри проксируемой location с помощью директивы rewrite и эта же конфигурация используется для обработки запроса (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.

Разрешает передачу клиенту полей заголовка проксируемого сервера, отключенных по умолчанию.

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

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.

Определяет, передаются ли поля заголовка исходного запроса проксируемому серверу.

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.

Разрешает передачу клиенту полей трейлера проксируемого сервера.

Секцию трейлера следует явно включить:

location / {
    # proxy_http_version 1.1;  #for versions before 1.29.7
    proxy_set_header     Connection "te";
    proxy_set_header     TE "trailers";
    proxy_pass_trailers  on;

    proxy_pass ...
}

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

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

Задает текст, который следует изменить в полях заголовка «Location» и «Refresh» ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка «Location: http://localhost:8000/two/some/uri/». Директива

proxy_redirect http://localhost:8000/two/ http://frontend/one/;

перепишет эту строку в «Location: http://frontend/one/some/uri/».

Имя сервера в строке replacement можно опустить:

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 используются переменные.

Строка replacement может содержать переменные:

proxy_redirect http://localhost:8000/ http://$host:$server_port/;

redirect также может содержать переменные (1.1.11):

proxy_redirect http://$proxy_host:8000/ /;

Директиву можно задать с помощью регулярных выражений (1.1.11). В этом случае redirect должно начинаться либо с символа «~» для сопоставления с учетом регистра, либо с символов «~*» для сопоставления без учета регистра. Регулярное выражение может содержать именованные и позиционные захваты, на которые может ссылаться replacement:

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 / /;

Включает или отключает буферизацию тела клиентского запроса.

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

Если буферизация отключена, тело запроса отправляется проксируемому серверу сразу по мере получения. В этом случае запрос нельзя передать следующему серверу, если nginx уже начал отправлять тело запроса.

Если для отправки исходного тела запроса используется фрагментированное кодирование передачи HTTP/1.1, тело запроса будет буферизоваться независимо от значения директивы, если для проксирования не включена версия HTTP/1.1 или HTTP/2.

Включает или отключает создание отдельного экземпляра запроса для каждого проксируемого сервера. По умолчанию для всех проксируемых серверов используется один запрос. Если директива включена, создается отдельный экземпляр запроса, что позволяет настраивать запросы для каждого сервера. Например, можно задать поле заголовка запроса «Host» для конкретного сервера:

proxy_request_dynamic on;
proxy_set_header      Host $upstream_last_server_name;

Эта директива доступна в рамках нашей коммерческой подписки.

Если директиве задано ненулевое значение, nginx попытается уменьшить количество операций отправки в исходящих соединениях с проксируемым сервером, используя либо флаг NOTE_LOWAT метода kqueue, либо параметр сокета SO_SNDLOWAT с указанным значением size.

В Linux, Solaris и Windows эта директива игнорируется.

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

Позволяет переопределить тело запроса, передаваемое проксируемому серверу. value может содержать текст, переменные и их комбинации.

Позволяет переопределять или добавлять поля заголовка запроса, передаваемого проксируемому серверу. value может содержать текст, переменные и их сочетания. Эти директивы наследуются с предыдущего уровня конфигурации тогда и только тогда, когда на текущем уровне не определены директивы 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 "";

Настраивает поведение “TCP keepalive” для исходящих подключений к проксируемому серверу. По умолчанию для сокета используются настройки операционной системы. Если директива задана со значением “on”, для сокета включается параметр сокета SO_KEEPALIVE.

Задаёт file с сертификатом в формате PEM, используемым для аутентификации на проксируемом HTTPS-сервере.

Начиная с версии 1.21.0 в имени file можно использовать переменные.

Определяет кэш для хранения 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;

Задаёт file с секретным ключом в формате PEM, используемым для аутентификации на проксируемом HTTPS-сервере.

Вместо file можно указать значение engine:name:id (1.7.9), которое загружает секретный ключ с заданным id из движка OpenSSL name.

Вместо file можно указать значение store:scheme:id (1.29.0), которое используется для загрузки секретного ключа с заданным id и URI, зарегистрированным в провайдере OpenSSL, scheme, например pkcs11.

Начиная с версии 1.21.0 в имени file можно использовать переменные.

Задаёт разрешённые шифры для запросов к проксируемому HTTPS-серверу. Шифры указываются в формате, поддерживаемом библиотекой OpenSSL.

Полный список можно просмотреть с помощью команды “openssl ciphers”.

Задаёт произвольные команды конфигурации OpenSSL при установлении соединения с проксируемым HTTPS-сервером.

Директива поддерживается при использовании OpenSSL версии 1.0.2 или выше.

На одном уровне можно указать несколько директив proxy_ssl_conf_command. Эти директивы наследуются с предыдущего уровня конфигурации тогда и только тогда, когда на текущем уровне не определены директивы proxy_ssl_conf_command.

Обратите внимание: непосредственная настройка OpenSSL может привести к неожиданному поведению.

Задаёт file со списком отозванных сертификатов (CRL) в формате PEM, используемый для проверки сертификата проксируемого HTTPS-сервера. При использовании промежуточных сертификатов их списки отзыва следует указать в том же файле.

Включает журналирование SSL-ключей соединений с проксируемым HTTPS-сервером и задаёт путь к файлу журнала ключей. Ключи записываются в формате SSLKEYLOGFILE, совместимом с Wireshark.

Эта директива доступна в рамках нашей коммерческой подписки.

Позволяет переопределить имя сервера, используемое для проверки сертификата проксируемого HTTPS-сервера и передаваемое через SNI при установлении соединения с проксируемым HTTPS-сервером.

По умолчанию используется часть URL-адреса proxy_pass, содержащая имя хоста.

Задаёт file с парольными фразами для секретных ключей, каждая из которых указана на отдельной строке. При загрузке ключа парольные фразы перебираются по очереди.

Включает указанные протоколы для запросов к проксируемому HTTPS-серверу.

Параметр TLSv1.3 используется по умолчанию начиная с версии 1.23.4.

Включает или отключает передачу имени сервера через расширение TLS Server Name Indication (SNI, RFC 6066) при установлении соединения с проксируемым HTTPS-сервером.

Определяет, можно ли повторно использовать SSL-сеансы при работе с проксируемым сервером. Если в журналах появляются ошибки “digest check failed”, попробуйте отключить повторное использование сеансов.

Задаёт file с доверенными сертификатами CA в формате PEM, используемый для проверки сертификата проксируемого HTTPS-сервера.

Включает или отключает проверку сертификата проксируемого HTTPS-сервера.

proxy_store /data/www$original_uri;

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 user:rw group:rw all:r;

proxy_store_access group:rw all:r;

proxy_temp_path /spool/nginx/proxy_temp 1 2;

/spool/nginx/proxy_temp/7/45/00000123457