Модуль ngx_http_proxy_module

• Пример конфигурации
• Директивы
• proxy_bind
• 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_read_timeout
• proxy_redirect
• proxy_request_buffering
• proxy_send_lowat
• proxy_send_timeout
• proxy_set_body
• proxy_set_header
• proxy_socket_keepalive
• proxy_ssl_certificate
• proxy_ssl_certificate_key
• proxy_ssl_ciphers
• proxy_ssl_conf_command
• proxy_ssl_crl
• 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;
}

Директивы

Принимает исходящие соединения с проксируемым сервером с указанного локального 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, процессы worker унаследуют способность CAP_NET_RAW от master-процесса. Также необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с проксируемого сервера.

Устанавливает размер буфера для чтения первой части ответа, полученного от проксируемого сервера. Эта часть обычно содержит небольшой заголовок ответа. По умолчанию, размер буфера равен одной странице памяти. Это либо 4К, либо 8К, в зависимости от платформы. Его можно сделать меньше.

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

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

Устанавливает количество и размер буферов для чтения ответа с проксируемого сервера для одного соединения. По умолчанию, размер буфера равен одной странице памяти. Это либо 4К, либо 8К, в зависимости от платформы.

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

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

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

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

Специальный процесс «менеджер кэша» отслеживает максимальный размер кэша, установленный параметром 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 миллисекунд).

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

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

purger=on|off

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

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.

Если ключ кэша ключа кэша запроса на очистку заканчивается звездочкой («*»), все записи кэша, соответствующие ключу с подстановкой, будут удалены из кэша. Однако эти записи останутся на диске до тех пор, пока они не будут удалены из-за неактивности или обработаны очистителем кэша (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.0. Версия 1.1 рекомендуется для использования с keepalive соединениями и аутентификацией NTLM.

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

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

произошёл таймаут при установлении соединения с сервером, передаче запроса или чтении заголовка ответа;

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) не передаются следующему серверу, если запрос уже отправлен на upstream-сервер (1.9.13); явное включение этой опции позволяет повторно отправлять такие запросы;

off

отключает передачу запроса следующему серверу.

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

Директива также определяет, что считается неудачной попыткой связи с сервером. Случаи error, timeout и 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 для отображения местоположения. В качестве протокола можно указать «http» или «https». Адрес может быть указан как доменное имя или IP-адрес, а также необязательный порт:

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

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

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

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

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

URI запроса передаётся серверу следующим образом:

• Если директива proxy_pass указана с URI, то при передаче запроса серверу часть нормализованного URI запроса, соответствующая местоположению, заменяется 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 запроса, подлежащая замене, определить невозможно:

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

  В этих случаях директива proxy_pass должна быть указана без URI.

• Когда URI изменяется внутри прокси-местоположения с помощью директивы 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» и «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 / /;

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

При включённой буферизации всё тело запроса считывается с клиента перед отправкой запроса прокси-серверу.

При отключённой буферизации тело запроса отправляется прокси-серверу немедленно по мере получения. В этом случае запрос не может быть передан следующему серверу next server, если nginx уже начал отправлять тело запроса.

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

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

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

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

Разрешает переопределение тела запроса, передаваемого прокси-серверу. value может содержать текст, переменные и их комбинацию.

Разрешает переопределение или добавление полей в заголовки запроса, передаваемые прокси-серверу. value может содержать текст, переменные и их комбинации. Эти директивы наследуются с предыдущего уровня конфигурации только в том случае, если на текущем уровне нет proxy_set_header директив. По умолчанию переопределяются только два поля:

proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;

Если кеширование включено, поля заголовков «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 можно использовать переменные.

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

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

С версии 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.

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

По умолчанию используется часть хоста URL proxy_pass.

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

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

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

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

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

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

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

Устанавливает глубину проверки в цепочке сертификатов прокси-сервера HTTPS.

Включает сохранение файлов на диск. Параметр on сохраняет файлы с путями, соответствующими директивам alias или root. Параметр off отключает сохранение файлов. Кроме того, имя файла можно установить явно с помощью string с переменными:

proxy_store /data/www$original_uri;

Время изменения файлов устанавливается в соответствии с полученным заголовком ответа «Last-Modified». Ответ сначала записывается во временный файл, а затем файл переименовывается. Начиная с версии 0.8.9, временные файлы и постоянное хранилище могут находиться на разных файловых системах. Однако имейте в виду, что в этом случае файл копируется через две файловые системы вместо быстрой операции переименования. Поэтому рекомендуется, чтобы для любого заданного расположения как сохраненные файлы, так и директория, содержащая временные файлы, задаваемая директивой proxy_temp_path, находились на одной файловой системе.

Эта директива может быть использована для создания локальных копий статических неизменяемых файлов, например:

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;

Если указаны какие-либо права доступа group или all, то права user могут быть опущены:

proxy_store_access group:rw all:r;

Ограничивает size данных, записываемых во временный файл за один раз, когда включено буферирование ответов от проксируемого сервера во временные файлы. По умолчанию size ограничено двумя буферами, заданными директивами proxy_buffer_size и proxy_buffers. Максимальный размер временного файла устанавливается директивой proxy_max_temp_file_size.

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

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.