Proxy

Позволяет передавать запросы другому (проксируемому) серверу.

При сборке из исходного кода модуль собирается по умолчанию; его можно отключить с помощью параметра сборки --without-http_proxy_module.

В пакетах и образах из наших репозиториев модуль включен в сборку.

Связанные руководства

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

• Управление во время выполнения: зона кэша с file= переживает перезапуск.

• Обработка соединений: проксирование и таймаут WebSocket.

• Балансировка нагрузки: условия повтора в proxy_next_upstream.

• Панель Console Light: зоны кэша наполняют вкладку «Кэши».

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

location / {
    proxy_pass       http://localhost:8000;
    proxy_set_header Host      $host;
    proxy_set_header X-Real-IP $remote_addr;

    proxy_cache       cache_zone;
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404      1m;
}

Директивы

proxy_bind

Синтаксис	proxy_bind адрес [transparent] | off;
По умолчанию	—
Контекст	http, server, location

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

По умолчанию это значение вычисляется один раз при инициализации запроса, до выбора проксируемого сервера. В Angie PRO вычисление происходит после каждого выбора проксируемого сервера (в том числе при повторных попытках), поэтому адрес привязки может зависеть от выбранного сервера; например, с помощью переменной $upstream_current_addr. Если вычисленное значение пусто, привязка не выполняется.

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

proxy_bind $remote_addr transparent;

Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями суперпользователя. В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.

Примечание

Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с проксируемого сервера.

proxy_buffer_size

Синтаксис	proxy_buffer_size размер;
По умолчанию	proxy_buffer_size 4k|8k;
Контекст	http, server, location

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

proxy_buffering

Синтаксис	proxy_buffering on | off;
По умолчанию	proxy_buffering on;
Контекст	http, server, location

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

on

Angie отправляет ответ клиенту параллельно с чтением ответа от проксируемого сервера; клиент не ждет ответа целиком. Ответ читается в буферы, заданные директивами proxy_buffer_size и proxy_buffers. Буфер передается на отправку, как только заполнится целиком, причем суммарный размер буферов, занятых отправкой, ограничен значением proxy_busy_buffers_size. Заполненный частично буфер ждет, пока не заполнится или пока не закончится ответ, поэтому данные обычно попадают к клиенту целыми буферами. Ответам, которые должны доходить до клиента по мере их формирования, поэтому нужен режим off. Часть ответа записывается на диск во временный файл, когда все буферы заполнены, а клиент читает медленнее, чем отдает проксируемый сервер. Ответы, которые кэшируются или сохраняются на диске, всегда проходят через временный файл. Запись во временные файлы контролируется директивами proxy_max_temp_file_size и proxy_temp_file_write_size. При буферизации проксируемый сервер освобождается сразу, как только отдаст ответ целиком: соединение с ним не удерживается все то время, пока ответ читает медленный клиент.

off

Каждая порция данных, прочитанная от проксируемого сервера, сразу же передается клиенту, без какого-либо минимального размера: прочитанные 10 байт из буфера 4K отправляются немедленно. Angie использует один буфер, заданный директивой proxy_buffer_size, поэтому за один раз он читает не больше этого размера. Временный файл не используется, поэтому ответы не кэшируются и не сохраняются на диске, а proxy_limit_rate и limit_rate не действуют. Режим off подходит для ответов, которые должны доходить до клиента по мере их формирования: Server-Sent Events, длинные опросы (long polling), потоковая передача.

Буферизация может быть также включена или выключена путем передачи значения "yes" или "no" в поле X-Accel-Buffering заголовка ответа. Эту возможность можно запретить с помощью директивы proxy_ignore_headers.

proxy_buffers

Синтаксис	proxy_buffers число размер;
По умолчанию	proxy_buffers 8 4k | 8k;
Контекст	http, server, location

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

По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.

proxy_busy_buffers_size

Синтаксис	proxy_busy_buffers_size размер;
По умолчанию	proxy_busy_buffers_size 8k | 16k;
Контекст	http, server, location

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

По умолчанию размер ограничен величиной двух буферов, заданных директивами proxy_buffer_size и proxy_buffers.

proxy_cache

Синтаксис	proxy_cache зона | off [path=путь];
По умолчанию	proxy_cache off;
Контекст	http, server, location

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

off	запрещает кэширование, унаследованное с предыдущего уровня конфигурации.

В Angie PRO можно указать несколько директив proxy_cache_path, использующих одно и то же значение keys_zone, чтобы включить шардинг кэша. При этом следует задать параметр path директивы proxy_cache, использующей это значение keys_zone:

path=путь

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

Это позволяет выбирать нужный путь кэша, применяя директивы map или скрипты к ответам от бэкенда. Пример для Content-Type:

proxy_cache_path /cache/one keys_zone=zone:10m;
proxy_cache_path /cache/two keys_zone=zone;

map $upstream_http_content_type $cache {
   ~^text/  one;
   default  two;
}

server {
   ...
   location / {
       proxy_pass http://backend;
       proxy_cache zone path=/cache/$cache;
       proxy_cache_valid 200 10m;
   }
}

Здесь есть два пути кэша и отображение переменной, чтобы их различать. Если Content-Type начинается с text/, будет выбран первый путь, иначе — второй.

Примечание

При использовании proxy_cache обычно необходимо также задать директиву proxy_cache_valid, чтобы явно указать время действия кэшированных ответов. Если она не задана, Angie не использует значения по умолчанию, а определяет время хранения ответа в кэше на основе HTTP-заголовков ответа от сервера в следующем порядке приоритета:

1. Заголовок X-Accel-Expires (наивысший приоритет).

2. Заголовок Cache-Control с параметрами max-age или s-maxage.

3. Заголовок Expires.

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

proxy_cache_background_update

Синтаксис	proxy_cache_background_update on | off;
По умолчанию	proxy_cache_background_update off;
Контекст	http, server, location

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

Предупреждение

Использование устаревшего кэшированного ответа в момент его обновления должно быть разрешено.

proxy_cache_bypass

Синтаксис	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

Синтаксис	proxy_cache_convert_head on | off;
По умолчанию	proxy_cache_convert_head on;
Контекст	http, server, location

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

proxy_cache_key

Синтаксис	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

Синтаксис	proxy_cache_lock on | off;
По умолчанию	proxy_cache_lock off;
Контекст	http, server, location

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

proxy_cache_lock_age

Синтаксис	proxy_cache_lock_age время;
По умолчанию	proxy_cache_lock_age 5s;
Контекст	http, server, location

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

proxy_cache_lock_timeout

Синтаксис	proxy_cache_lock_timeout время;
По умолчанию	proxy_cache_lock_timeout 5s;
Контекст	http, server, location

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

proxy_cache_max_range_offset

Синтаксис	proxy_cache_max_range_offset число;
По умолчанию	—
Контекст	http, server, location

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

proxy_cache_methods

Синтаксис	proxy_cache_methods GET | HEAD | POST ...;
По умолчанию	proxy_cache_methods GET HEAD;
Контекст	http, server, location

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

proxy_cache_min_uses

Синтаксис	proxy_cache_min_uses число;
По умолчанию	proxy_cache_min_uses 1;
Контекст	http, server, location

Задает число запросов, после которого ответ будет кэширован.

Предупреждение

Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не сбрасывает счетчики и может привести к непредсказуемому поведению. Для полного сброса остановите сервер, удалите директорию кэша и запустите снова.

Примечание

Сторонние модули очистки кэша (например, Cache Purge) удаляют только файлы, но не сбрасывают счетчик proxy_cache_min_uses. Директива предназначена для защиты кэша от загрязнения редкими запросами, и сброс счетчика при очистке может негативно повлиять на производительность.

proxy_cache_path

Синтаксис	proxy_cache_path путь [levels=уровни] [use_temp_path=on | off] keys_zone=имя:размер[:file=файл] [inactive=время] [max_size=размер] [min_free=размер] [manager_files=число] [manager_sleep=время] [manager_threshold=время] [loader_files=число] [loader_sleep=время] [loader_threshold=время];
По умолчанию	—
Контекст	http

Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Именем файла в кэше является результат функции MD5 от ключа кэширования.

levels

задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2.

Например, при использовании

proxy_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;

имена файлов в кэше будут такого вида:

/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c

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

use_temp_path=on | off	определяет каталог, который будет использоваться для временных файлов
on	Если параметр не задан или установлен в значение on, будет использоваться каталог, задаваемый директивой proxy_temp_path для данного location
off	временные файлы будут располагаться непосредственно в каталоге кэша
keys_zone	Задает имя и размер зоны разделяемой памяти для хранения всех активных ключей и информации о данных. Метаданные кэша хранятся в разделяемой памяти. Размер зоны задается в байтах и должен составлять не менее двух системных страниц памяти. Также допустимы суффиксы k и m; суффикс g, в отличие от max_size, здесь не поддерживается. Зоны размером в 1 мегабайт достаточно для хранения около 8000 ключей. Когда с keys_zone задан необязательный файл, Angie сбрасывает содержимое этой зоны на диск при завершении работы основного процесса и пытается восстановить ее по тому же адресу памяти при следующем запуске или после обновления бинарных файлов, чтобы обеспечить более надежную сохраняемость данных и сократить время загрузки кэша. Если содержимое файла несовместимо, например файл записан несовместимой сборкой, Angie переименовывает его с суффиксом .old, записывает в лог discarded due to incompatible content и создает зону заново. Затем загрузчик кэша заполняет зону из каталога кэша, как при запуске без файла, поэтому закэшированные ответы не теряются. Переименованный файл можно либо удалить, либо восстановить его имя и вернуть Angie к конфигурации и версии, в которых этот файл был изначально создан. Если размер зоны в конфигурации не совпадает с размером, сохраненным в файле, конфигурация не загружается, пока файл не удален или не возвращен прежний размер. Конфигурация не загружается и тогда, когда зону не удается отобразить в память по адресу, сохраненному в файле: Angie записывает в лог mmap(MAP_ANON|MAP_SHARED, ...) failed, если этот адрес уже занят, или failed to restore zone at address, если операционная система отображает зону по другому адресу. Предупреждение Убедитесь, что путь к файлу указан правильно и имеет необходимые права доступа для использования Angie, а также защищен от несанкционированного доступа; относительные пути основаны на префиксе.
inactive	Если к данным кэша не обращаются в течение времени, заданного этим параметром, они удаляются независимо от их свежести; каждое обращение сбрасывает этот таймер. Это отличается от вытеснения по размеру, выполняемого менеджером кэша (см. ниже): удаление по неактивности происходит, даже когда кэш не достиг max_size, и не зависит от сроков кэширования, заданных директивой proxy_cache_valid. По умолчанию inactive равен 10 минутам.

Примечание

В Angie PRO можно задавать несколько директив proxy_cache_path с одним и тем же значением keys_zone. Размер зоны разделяемой памяти можно указывать только в первой из них. Выбор между директивами будет производиться на основе параметра path соответствующей директивы proxy_cache.

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

max_size	максимальное пороговое значение размера кэша Значение задается в байтах; допустимы суффиксы k, m и g. По умолчанию размер кэша не ограничен.
min_free	минимальное пороговое значение объема свободного места на файловой системе с кэшем Задается в тех же единицах, что и max_size. По умолчанию 0 — отслеживание свободного места отключено. На платформах, где статистика файловой системы недоступна, параметр игнорируется, а Angie записывает в журнал предупреждение min_free is not supported on this platform, ignored.
manager_files	максимальное количество удаляемых элементов кэша за одну итерацию По умолчанию: 100.
manager_threshold	ограничивает время работы одной итерации По умолчанию: 200 миллисекунд.
manager_sleep	время, в течение которого выдерживается пауза между итерациями По умолчанию: 50 миллисекунд.

Через минуту после запуска Angie активируется специальный процесс загрузчика кэша. Он сканирует файловую систему в поисках ранее закэшированных данных и загружает эту информацию в область кэша. Этот процесс выполняется итеративно; каждая итерация обрабатывает ограниченное количество элементов, заданное параметром loader_files, следит за тем, чтобы не превышать loader_threshold, затем делает короткую паузу, заданную loader_sleep, перед переходом к следующей партии. Итерации продолжаются до тех пор, пока загрузчик не обработает все существующие записи кэша на диске:

loader_files	максимальное количество элементов кэша к загрузке в одну итерацию По умолчанию: 100
loader_threshold	ограничивает время работы одной итерации По умолчанию: 200 миллисекунд
loader_sleep	время, в течение которого выдерживается пауза между итерациями По умолчанию: 50 миллисекунд

Примечание

Зона, восстановленная из файла параметра keys_zone, сохраняет ключи кэша, которые были в ней в момент сохранения. Если загрузчик кэша к этому моменту закончил работу, он не сканирует каталог кэша заново, и зона полностью готова сразу после запуска Angie. Если Angie был остановлен до запуска загрузчика, то есть в первую минуту после старта, загрузчик заполняет восстановленную зону, как описано выше.

Если Angie останавливается, пока загрузчик еще работает, постепенное завершение работы (angie -s quit) дожидается, пока загрузчик закончит сканирование. Быстрое завершение работы, при котором сигнал получает только главный процесс, например angie -s stop или docker stop, прерывает загрузчик. После перезапуска загрузчик не возобновляет работу, и восстановленная зона остается неполной; ее поле cold в разделе API /status/http/caches/ сохраняет значение true. Чтобы загрузчик заново построил такую зону, удалите файл перед запуском Angie. Если сигнал получает и сам процесс загрузчика, например когда он отправлен всем процессам Angie, загрузчик корректно останавливается и после перезапуска снова сканирует каталог кэша.

proxy_cache_revalidate

Синтаксис	proxy_cache_revalidate on | off;
По умолчанию	proxy_cache_revalidate off;
Контекст	http, server, location

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

proxy_cache_use_stale

Синтаксис	proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;
По умолчанию	proxy_cache_use_stale off;
Контекст	http, server, location

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

error	Позволяет использовать устаревший кэшированный ответ при невозможности выбора проксированного сервера для обработки запроса.
updating	Дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к проксированным серверам при обновлении кэшированных данных.
non_idempotent	Позволяет использовать устаревший кэшированный ответ, если запрос с неидемпотентным методом уже был отправлен проксированному серверу, а при дальнейшей работе с этим сервером произошла любая ошибка; из неидемпотентных методов кэшировать можно только POST, и он должен быть разрешен директивой proxy_cache_methods.

Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел:

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

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

Примечание

Такой способ менее приоритетен, чем задание параметров директивы.

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

proxy_cache_valid

Синтаксис	proxy_cache_valid [код ... | any] время;
По умолчанию	—
Контекст	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 со специальным значением "*", не будет кэшироваться. Ответ, в заголовке которого есть поле Vary с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.

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

proxy_connect_timeout

Синтаксис	proxy_connect_timeout время;
По умолчанию	proxy_connect_timeout 60s;
Контекст	http, server, location

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

Примечание

Этот таймаут не управляет неактивными соединениями: время, в течение которого уже открытое соединение сохраняется для повторного использования, задается директивой keepalive_timeout в блоке upstream, соединения которого кэшируются директивой keepalive.

proxy_connection_drop

Синтаксис	proxy_connection_drop время | on | off;
По умолчанию	proxy_connection_drop off;
Контекст	http, server, location

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

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

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

proxy_cookie_domain

Синтаксис	proxy_cookie_domain off; proxy_cookie_domain домен замена;
По умолчанию	proxy_cookie_domain off;
Контекст	http, server, location

Задает текст, который нужно изменить в атрибуте 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;

Если к cookie могут быть применены несколько директив, будет выбрана первая из них.

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

proxy_cookie_flags

Синтаксис	proxy_cookie_flags off | cookie [флаг] [флаг] [флаг];
По умолчанию	proxy_cookie_flags off;
Контекст	http, server, location

Задает один или несколько флагов для cookie. В качестве cookie можно использовать переменные. В качестве флага можно использовать переменные.

Параметры 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.

proxy_cookie_path

Синтаксис	proxy_cookie_path off; proxy_cookie_path путь замена;
По умолчанию	proxy_cookie_path off;
Контекст	http, server, location

Задает текст, который нужно изменить в атрибуте 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/;

Если к cookie могут быть применены несколько директив, будет выбрана первая из них.

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

proxy_force_ranges

Синтаксис	proxy_force_ranges on | off;
По умолчанию	proxy_force_ranges off;
Контекст	http, server, location

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

proxy_headers_hash_bucket_size

Синтаксис	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 размер;
По умолчанию	proxy_headers_hash_max_size 512;
Контекст	http, server, location

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

proxy_hide_header

Синтаксис	proxy_hide_header поле;
По умолчанию	—
Контекст	http, server, location

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

proxy_http3_hq

Синтаксис	proxy_http3_hq on | off;
По умолчанию	proxy_http3_hq off;
Контекст	http, server, location

Отключает или включает особый режим согласования hq-interop, используемый в функциональных тестах QUIC, на которые полагается Angie.

Предупреждение

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

proxy_http3_max_concurrent_streams

Синтаксис	proxy_http3_max_concurrent_streams число;
По умолчанию	proxy_http3_max_concurrent_streams 128;
Контекст	http, server, location

Инициализирует настройки HTTP/3 и QUIC, а также задает максимальное число параллельных HTTP/3-потоков в соединении. Требует включения постоянных соединений.

proxy_http3_max_table_capacity

Синтаксис	proxy_http3_max_table_capacity число;
Значение по умолчанию	proxy_http3_max_table_capacity 4096;
Контекст	http, server, location

Определяет емкость динамической таблицы для прокси-соединений.

Примечание

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

proxy_http3_stream_buffer_size

Синтаксис	proxy_http3_stream_buffer_size размер;
По умолчанию	proxy_http3_stream_buffer_size 64k;
Контекст	http, server, location

Задает размер буфера, используемого для чтения и записи QUIC-потоков.

proxy_http_version

Синтаксис	proxy_http_version 1.0 | 1.1 | 2 | 3;
По умолчанию	proxy_http_version 1.1;
Контекст	http, server, location, if в location, limit_except

Задает версию протокола HTTP для проксирования. Для работы постоянных соединений рекомендуется версия 1.1 или выше.

proxy_ignore_client_abort

Синтаксис	proxy_ignore_client_abort on | off;
По умолчанию	proxy_ignore_client_abort off;
Контекст	http, server, location

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

proxy_ignore_headers

Синтаксис	proxy_ignore_headers поле ...;
По умолчанию	—
Контекст	http, server, location

Запрещает обработку некоторых полей заголовка из ответа проксированного сервера. В директиве можно указать поля X-Accel-Redirect, X-Accel-Expires, X-Accel-Limit-Rate, X-Accel-Buffering, X-Accel-Charset, Expires, Cache-Control, Set-Cookie и Vary.

Если не запрещено, обработка этих полей заголовка заключается в следующем:

• X-Accel-Expires, Expires, Cache-Control, Set-Cookie и Vary задают параметры кэширования ответа;

• X-Accel-Redirect производит внутреннее перенаправление на указанный URI или в именованный location;

• X-Accel-Limit-Rate задает ограничение скорости передачи ответа клиенту;

• X-Accel-Buffering включает или выключает буферизацию ответа;

• X-Accel-Charset задает желаемую кодировку ответа.

proxy_intercept_errors

Синтаксис	proxy_intercept_errors on | off;
По умолчанию	proxy_intercept_errors off;
Контекст	http, server, location

Определяет, передавать ли клиенту проксированные ответы с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы error_page.

proxy_limit_rate

Синтаксис	proxy_limit_rate скорость;
По умолчанию	proxy_limit_rate 0;
Контекст	http, server, location

Ограничивает скорость чтения ответа от проксируемого сервера. Скорость задается в байтах в секунду; можно использовать переменные.

0	отключает ограничение скорости

Примечание

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

proxy_max_temp_file_size

Синтаксис	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

Синтаксис	proxy_method метод;
По умолчанию	—
Контекст	http, server, location

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

proxy_next_upstream

Синтаксис	proxy_next_upstream error | timeout | 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

Определяет, в каких случаях запрос будет передан следующему в группе upstream серверу:

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;
non_idempotent	обычно запросы с неидемпотентным методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы;
off	запрещает передачу запроса следующему серверу.

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

Примечание

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

Директива также определяет, что считается неудачной попыткой работы с сервером.

error timeout invalid_header	всегда считаются неудачными попытками, даже если они не указаны в директиве
http_500 http_502 http_503 http_504 http_429	считаются неудачными попытками, только если они указаны в директиве
http_403 http_404	никогда не считаются неудачными попытками

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

proxy_next_upstream_timeout

Синтаксис	proxy_next_upstream_timeout время;
По умолчанию	proxy_next_upstream_timeout 0;
Контекст	http, server, location

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

0	отключает это ограничение

proxy_next_upstream_tries

Синтаксис	proxy_next_upstream_tries число;
По умолчанию	proxy_next_upstream_tries 0;
Контекст	http, server, location

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

0	отключает это ограничение

proxy_no_cache

Синтаксис	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

Синтаксис	proxy_pass uri;
По умолчанию	—
Контекст	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'а.

Примечание

Доменное имя в proxy_pass, которое не содержит переменных и не совпадает с именем описанной группы серверов, неявно создает группу серверов из одного сервера, эквивалентную:

upstream example.com {
    server example.com;
}

Имена таких групп серверов являются общими в пределах всей конфигурации http, независимо от блока server, в котором используется proxy_pass. Поскольку у неявно созданного server нет параметра resolve, имя разрешается один раз, на этапе загрузки конфигурации, и полученные адреса используются вплоть до следующей перезагрузки, даже если задан resolver.

В результате proxy_pass, переменная которого принимает то же самое имя, повторно использует эту существующую группу серверов с адресами, полученными при загрузке, вместо того чтобы разрешать имя при каждом запросе через resolver. Чтобы повторно разрешать имя во время работы и отслеживать изменения DNS, опишите группу серверов явно и добавьте параметр resolve к ее server.

URI запроса передается на сервер так:

• Если директива proxy_pass указана с URI, то при передаче запроса серверу часть нормализованного URI запроса, соответствующая location, заменяется на URI, указанный в директиве:

  location /name/ {
      proxy_pass http://127.0.0.1/remote/;
  }
  

  Запрос /name/page сервер получает как /remote/page.

• Если директива proxy_pass указана без URI, сервер получает URI запроса вместе с аргументами точно в том виде, в каком его прислал клиент (значение $request_uri), при условии, что до проксирования Angie не менял URI или аргументы запроса. В противном случае сервер получает текущее значение $uri, то есть нормализованный URI, а за ним текущие аргументы. Символы, недопустимые в пути URI без кодирования (например, пробелы), в этом случае снова кодируются; аргументы передаются как есть.

  URI или аргументы считаются измененными, когда:

  • срабатывает регулярное выражение директивы rewrite;

  • переменной $args присваивается значение, даже прежнее;

  • запрос внутренне перенаправляется на URI, например директивой index или error_page, последним параметром директивы try_files или полем X-Accel-Redirect заголовка ответа.

  Перенаправление в именованный location не меняет URI, будь то директивы goto, error_page, try_files или поле X-Accel-Redirect.

  Например, клиент запрашивает /some/path/%7Euser//a%20b?x=1. При такой конфигурации сервер получает URI запроса в неизменном виде:

  location /some/path/ {
      proxy_pass http://127.0.0.1;
  }
  

  В этой конфигурации URI меняет директива rewrite:

  location /some/path/ {
      rewrite    ^/some/path/(.*)$ /other/$1 break;
      proxy_pass http://127.0.0.1;
  }
  

  Сервер получает /other/~user/a%20b?x=1: последовательность %7E декодирована, двойная косая черта заменена одной, а пробел снова закодирован.

В ряде случаев часть URI запроса, подлежащую замене, выделить невозможно:

• Если location задан регулярным выражением, а также в именованных и комбинированных location и внутри блоков if и limit_except.

  В этих случаях proxy_pass без переменных нужно указывать без URI, иначе Angie не загрузит конфигурацию.

• Если внутри проксируемого location URI меняет директива rewrite с флагом break, так что запрос остается в этом location:

  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 требует особой настройки.

Примечание

Если proxy_pass стоит в location с косой чертой в конце префикса (например, location /name/), и при этом в директиве auto_redirect указано default, запросы без косой черты в конце будут перенаправляться (/name -> /name/).

proxy_pass_header

Синтаксис	proxy_pass_header поле;
По умолчанию	—
Контекст	http, server, location

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

proxy_pass_request_body

Синтаксис	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

Синтаксис	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

Синтаксис	proxy_pass_trailers on | off;
По умолчанию	proxy_pass_trailers off;
Контекст	http, server, location

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

Секция трейлеров в HTTP/1.1 включается явно.

location / {
    proxy_http_version 1.1;
    proxy_set_header Connection "te";
    proxy_set_header TE "trailers";
    proxy_pass_trailers on;

    proxy_pass ...;
}

proxy_quic_active_connection_id_limit

Синтаксис	proxy_quic_active_connection_id_limit число;
По умолчанию	proxy_quic_active_connection_id_limit 2;
Контекст	http, server, location

Задает значение транспортного параметра QUIC active_connection_id_limit. Это максимальное число активных идентификаторов соединений, поддерживаемых для одного сервера.

proxy_quic_gso

Синтаксис	proxy_quic_gso on | off;
По умолчанию	proxy_quic_gso off;
Контекст	http, server, location

Отключает или включает отправку данных в оптимизированном пакетном режиме QUIC, использующем программное снижение нагрузки путем сегментации (generic segmentation offload).

proxy_quic_host_key

Синтаксис	proxy_quic_host_key файл;
По умолчанию	—
Контекст	http, server, location

Задает файл с секретным ключом, применяемым в QUIC при шифровании токенов Stateless Reset и Address Validation. По умолчанию случайный ключ создается при каждом перезапуске. Токены, созданные при помощи старых ключей, не принимаются.

proxy_read_timeout

Синтаксис	proxy_read_timeout время;
По умолчанию	proxy_read_timeout 60s;
Контекст	http, server, location

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

proxy_redirect

Синтаксис	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/;

В строке перенаправление тоже можно использовать переменные:

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

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

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

Синтаксис	proxy_request_buffering on | off;
По умолчанию	proxy_request_buffering on;
Контекст	http, server, location

Разрешает или запрещает использовать буферизацию тела запроса клиента.

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

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

proxy_send_lowat

Синтаксис	proxy_send_lowat размер;
По умолчанию	proxy_send_lowat 0;
Контекст	http, server, location

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

Примечание

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

proxy_send_timeout

Синтаксис	proxy_send_timeout время;
По умолчанию	proxy_send_timeout 60s;
Контекст	http, server, location

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

proxy_set_body

Синтаксис	proxy_set_body значение;
По умолчанию	—
Контекст	http, server, location

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

proxy_set_header

Синтаксис	proxy_set_header поле значение;
По умолчанию	proxy_set_header Host $proxy_host;
Контекст	http, server, location

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

proxy_socket_keepalive

Синтаксис	proxy_socket_keepalive on | off;
По умолчанию	proxy_socket_keepalive off;
Контекст	http, server, location

Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.

off	По умолчанию для сокета действуют настройки операционной системы.
on	для сокета включается параметр SO_KEEPALIVE

proxy_ssl_certificate

Синтаксис	proxy_ssl_certificate файл [файл] | data:сертификат;
По умолчанию	—
Контекст	http, server, location

Задает сертификат в формате PEM для аутентификации на проксируемом HTTPS-сервере.

Значение интерпретируется так же, как в директиве ssl_certificate: как путь к файлу или, после префикса data:, как сам сертификат в виде текста PEM. Значение может содержать переменные; они вычисляются каждый раз, когда Angie устанавливает соединение с проксируемым HTTPS-сервером, поэтому доступны все переменные запроса, включая присвоенные директивой set. Если вычисленное значение сертификата пустое, клиентский сертификат не отправляется. Чтобы сертификаты не загружались для каждого соединения, включите proxy_ssl_certificate_cache.

При включенном proxy_ssl_ntls директива принимает два аргумента вместо одного:

location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}

proxy_ssl_certificate_cache

Синтаксис	proxy_ssl_certificate_cache off; proxy_ssl_certificate_cache max=N [inactive=time] [valid=time];
Значение по умолчанию	proxy_ssl_certificate_cache off;
Контекст	http, server, location

Определяет кэш для хранения SSL-сертификатов и секретных ключей, заданных через переменные.

Директива поддерживает следующие параметры:

• max — устанавливает максимальное количество элементов в кэше. При переполнении кэша удаляются наименее недавно использованные (LRU) элементы.

• inactive — определяет время, после которого элемент будет удален, если к нему не было обращений в течение этого времени, даже если он еще находится в пределах своего периода valid; каждое обращение сбрасывает этот таймер. Значение по умолчанию — 10 секунд.

• valid — определяет время, в течение которого элемент кэша используется повторно без проверок. Значение по умолчанию — 60 секунд. По истечении этого времени элемент, загруженный из файла, перезагружается, только если файл изменился, а ключ, загруженный с префиксом engine: или store:, загружается заново; элемент, заданный с префиксом data:, остается действительным.

• off — отключает кэш.

Ключи, защищенные паролем (см. proxy_ssl_password_file), не кэшируются.

Пример:

proxy_ssl_certificate       /etc/angie/ssl/$host.crt;
proxy_ssl_certificate_key   /etc/angie/ssl/$host.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;

proxy_ssl_certificate_key

Синтаксис	proxy_ssl_certificate_key файл [файл] | data:ключ | engine:имя:id | store:uri;
По умолчанию	—
Контекст	http, server, location

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

Значение, включая префиксы engine: и store:, интерпретируется так же, как в директиве ssl_certificate_key, а переменные в нем работают, как описано в proxy_ssl_certificate. Ключ, защищенный паролем, расшифровывается паролями из proxy_ssl_password_file.

При включенном proxy_ssl_ntls директива принимает два аргумента вместо одного:

location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}

proxy_ssl_ciphers

Синтаксис	proxy_ssl_ciphers шифры;
По умолчанию	proxy_ssl_ciphers DEFAULT;
Контекст	http, server, location

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

Список шифров зависит от установленной версии OpenSSL. Полный список можно посмотреть с помощью команды openssl ciphers.

Предупреждение

При использовании OpenSSL директива proxy_ssl_ciphers не настраивает шифры TLS 1.3: их задает команда Ciphersuites директивы proxy_ssl_conf_command. Имена шифров TLS 1.3 в значении директивы proxy_ssl_ciphers игнорируются и не ограничивают соединения TLS 1.3. Если значение состоит только из таких имен, например TLS_AES_128_GCM_SHA256, загрузка конфигурации завершается ошибкой no cipher match.

• В LibreSSL шифры TLS 1.3 можно настраивать с помощью proxy_ssl_ciphers.

• В BoringSSL шифры TLS 1.3 настроить невозможно.

proxy_ssl_conf_command

Синтаксис	proxy_ssl_conf_command имя значение;
По умолчанию	—
Контекст	http, server, location

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

Примечание

Директива поддерживается при использовании OpenSSL 1.0.2 и выше. Шифры TLS 1.3 настраиваются командой Ciphersuites, доступной в OpenSSL 1.1.1 и выше.

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

Предупреждение

Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.

proxy_ssl_crl

Синтаксис	proxy_ssl_crl файл;
По умолчанию	—
Контекст	http, server, location

Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при проверке сертификата проксируемого HTTPS-сервера.

proxy_ssl_keylog_file

Добавлено в версии 1.12.0.

Синтаксис	proxy_ssl_keylog_file файл;
По умолчанию	—
Контекст	http, server, location

Задает файл для журналирования SSL/TLS-ключей соединений с проксируемыми HTTPS-серверами в контексте, использующий формат SSLKEYLOGFILE, который применяется, например, в Wireshark для расшифровки перехваченного TLS-трафика.

Директиву не следует использовать с LibreSSL.

Предупреждение

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

proxy_ssl_name

Синтаксис	proxy_ssl_name имя;
По умолчанию	proxy_ssl_name $proxy_host;
Контекст	http, server, location

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

Имя сервера также можно задать с помощью переменных.

По умолчанию используется имя хоста из URL'а, заданного директивой proxy_pass.

proxy_ssl_ntls

Синтаксис	proxy_ssl_ntls on | off;
По умолчанию	proxy_ssl_ntls off;
Контекст	http, server, location

Включает клиентскую поддержку NTLS при использовании TLS библиотеки Tongsuo.

location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}

Примечание

Angie необходимо собрать с параметром конфигурации --with-ntls и SSL-библиотекой с поддержкой NTLS:

$ ./configure --with-openssl=../Tongsuo-8.3.0 \
              --with-openssl-opt=enable-ntls  \
              --with-ntls

proxy_ssl_password_file

Синтаксис	proxy_ssl_password_file файл;
По умолчанию	—
Контекст	http, server, location

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

proxy_ssl_protocols

Синтаксис	proxy_ssl_protocols SSLv2 | SSLv3 | TLSv1 | TLSv1.1 | TLSv1.2 | TLSv1.3 ...;
По умолчанию	proxy_ssl_protocols TLSv1.2 TLSv1.3;
Контекст	http, server, location

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

proxy_ssl_server_name

Синтаксис	proxy_ssl_server_name on | off;
По умолчанию	proxy_ssl_server_name off;
Контекст	http, server, location

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

proxy_ssl_session_reuse

Синтаксис	proxy_ssl_session_reuse on | off;
По умолчанию	proxy_ssl_session_reuse on;
Контекст	http, server, location

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

proxy_ssl_trusted_certificate

Синтаксис	proxy_ssl_trusted_certificate файл;
По умолчанию	—
Контекст	http, server, location

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

proxy_ssl_verify

Синтаксис	proxy_ssl_verify on | off;
По умолчанию	proxy_ssl_verify off;
Контекст	http, server, location

Разрешает или запрещает проверку сертификата проксируемого HTTPS-сервера.

proxy_ssl_verify_depth

Синтаксис	proxy_ssl_verify_depth число;
По умолчанию	proxy_ssl_verify_depth 1;
Контекст	http, server, location

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

proxy_store

Синтаксис	proxy_store on | off | строка;
По умолчанию	proxy_store off;
Контекст	http, server, location

Разрешает сохранение на диск файлов.

on	сохраняет файлы в соответствии с путями, указанными в директивах alias или root
off	запрещает сохранение файлов

Имя файла можно задать явно с помощью строки с переменными:

proxy_store /data/www$original_uri;

Время изменения файлов выставляется согласно полученному полю Last-Modified в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой 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 пользователи:права [пользователи:права] [пользователи:права];
По умолчанию	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 размер;
По умолчанию	proxy_temp_file_write_size 8k|16k;
Контекст	http, server, location

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

proxy_temp_path

Синтаксис	proxy_temp_path путь [уровень1 [уровень2 [уровень3]]];
По умолчанию	proxy_temp_path proxy_temp; (путь зависит от параметра сборки --http-proxy-temp-path)
Контекст	http, server, location

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

proxy_temp_path /spool/angie/proxy_temp 1 2;

временный файл будет следующего вида:

/spool/angie/proxy_temp/7/45/00000123457

См. также параметр use_temp_path директивы proxy_cache_path.

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

В модуле есть встроенные переменные, которые можно использовать для формирования заголовков с помощью директивы proxy_set_header:

$proxy_add_x_forwarded_for

поле заголовка запроса клиента X-Forwarded-For и добавленная к нему через запятую переменная $remote_addr. Если же поля X-Forwarded-For в заголовке запроса клиента нет, то переменная $proxy_add_x_forwarded_for равна переменной $remote_addr.

$proxy_host

имя и порт проксируемого сервера, как указано в директиве proxy_pass;

$proxy_port

порт проксируемого сервера, как указано в директиве proxy_pass, или стандартный порт протокола;