Документация HAProxy 3.4.6-66

• 1: Основы балансировки нагрузки
• 2: Что такое HAProxy и как он работает
• 3: Базовые возможности
• 4: Стандартные возможности
• 5: Расширенные возможности
• 6: Расчёт ресурсов и производительность
• 7: Выпуски, пакеты и обновления
• 8: Сопутствующие продукты и альтернативы
• 9: Документация и сообщество
• 10: 1. Краткое напоминание об HTTP
• 11: 2. Настройка HAProxy
• 12: 3. Секция global
• 13: 4. Прокси
• 14: 5. Параметры bind и server
• 15: 6. Кеш
• 16: 7. ACL и извлечение образцов
• 17: 8. Ведение журнала
• 18: 9. Поддерживаемые фильтры
• 19: 10. Приложения FastCGI
• 20: 11. Таблицы привязок и одноранговые узлы
• 21: 12. Другие секции
• 22: 1. Предварительные требования
• 23: 2. Архитектура HAProxy
• 24: 3. Запуск HAProxy
• 25: 4. Остановка и перезапуск HAProxy
• 26: 5. Ограничения файловых дескрипторов
• 27: 6. Управление памятью
• 28: 7. Использование CPU
• 29: 8. Ведение журнала
• 30: 9. Статистика и мониторинг
• 31: 10. Упрощение управления конфигурацией
• 32: 11. Известные подводные камни, которых следует избегать
• 33: 12. Отладка и проблемы производительности
• 34: 13. Соображения безопасности

1 - Основы балансировки нагрузки

Этот документ знакомит с HAProxy тех, кто ещё не знает продукт, а также тех, кто знаком с его старыми версиями и хочет открыть его заново. Главная цель — предоставить все сведения, необходимые для решения, подходит ли HAProxy пользователю. Опытные пользователи могут найти здесь отдельные элементы решений ранее возникших задач, о которых они не знали из-за незнакомства с новой функцией. Также приведены сведения для расчёта ресурсов, описан жизненный цикл продукта и даны сравнения с продуктами, чьи возможности частично пересекаются с HAProxy.

Этот документ не содержит помощи или советов по настройке, но объясняет, где искать соответствующую документацию. Руководство представлено плоской последовательностью тематических страниц в боковой панели HAProxy.

Балансировка нагрузки объединяет несколько компонентов, чтобы получить общую производительность выше производительности каждого из них, без вмешательства конечного пользователя и с возможностью масштабирования. В результате за время, необходимое одному компоненту для выполнения одной операции, одновременно выполняется больше операций. Однако отдельная операция по-прежнему выполняется только на одном компоненте и не ускоряется по сравнению с работой без балансировки. Чтобы задействовать все компоненты и полностью использовать преимущества балансировки, всегда нужно как минимум столько же операций, сколько компонентов, а также эффективный механизм распределения нагрузки. Наглядный пример — число полос на автомагистрали: оно позволяет пропустить больше автомобилей за одно и то же время без увеличения скорости каждого автомобиля.

Примеры балансировки нагрузки:

• Планирование процессов в многопроцессорных системах.
• Балансировка нагрузки каналов связи (например, EtherChannel, Bonding).
• Балансировка по IP-адресам (например, ECMP, циклический выбор DNS).
• Балансировка нагрузки серверов (с помощью балансировщиков нагрузки).

Механизм или компонент, выполняющий распределение нагрузки, называется балансировщиком нагрузки. В веб-средах такие компоненты называют «сетевыми балансировщиками нагрузки», а чаще просто «балансировщиками нагрузки», поскольку это наиболее известная область их применения.

Балансировщик нагрузки может действовать:

• На уровне канала: балансировка нагрузки каналов связи выбирает сетевой канал, по которому отправить пакет.

• На уровне сети: сетевая балансировка нагрузки выбирает маршрут для последовательности пакетов.

• На уровне сервера: балансировка нагрузки серверов определяет сервер, который обработает соединение или запрос.

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

Первая технология работает на уровне пакетов и обрабатывает их более или менее независимо. Между входными и выходными пакетами существует соответствие 1-к-1, поэтому трафик по обе стороны балансировщика можно отслеживать обычным анализатором сетевого трафика. Эта технология может быть очень дешёвой и чрезвычайно быстрой. Обычно она реализуется аппаратно, на ASIC, и позволяет достичь скорости линии — например, в коммутаторах с ECMP. Чаще всего она не хранит состояние, но может учитывать сеанс, к которому относится пакет; такой вариант называют layer4-LB или L4. Если пакеты не изменяются, возможна поддержка DSR — прямого ответа сервера без повторного прохождения через балансировщик. Однако содержимое практически не анализируется. Эта технология отлично подходит для балансировки на уровне сети, хотя иногда применяется и для простейшей высокоскоростной балансировки нагрузки серверов.

Вторая технология работает с содержимым сеансов. Для этого входной поток необходимо собрать и обработать целиком. Содержимое можно изменить, а выходной поток разбивается на новые пакеты. Поэтому такую обработку обычно выполняют прокси, часто называемые балансировщиками нагрузки уровня 7 или L7. Это подразумевает два отдельных соединения по обе стороны балансировщика и отсутствие связи между размерами и числом входных и выходных пакетов. Клиенты и серверы не обязаны использовать один и тот же протокол: например, возможны IPv4 и IPv6 или незашифрованный трафик и SSL. Операции всегда сохраняют состояние, а обратный трафик обязательно проходит через балансировщик. Дополнительная обработка требует ресурсов, поэтому достичь скорости линии удаётся не всегда, особенно на маленьких пакетах. Зато технология даёт широкие возможности и обычно реализуется целиком программно, даже во встроенных аппаратных устройствах. Она отлично подходит для балансировки нагрузки серверов.

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

Балансировщики на основе прокси развёртываются как серверы с собственными IP-адресами и портами, без изменения архитектуры. Иногда приходится адаптировать приложения, чтобы клиенты направлялись на IP-адрес балансировщика, а не прямо к серверу. Некоторым балансировщикам для этого нужно изменять ответы серверов — например, поле заголовка HTTP Location, используемое при перенаправлениях. Некоторые балансировщики на основе прокси умеют перехватывать трафик для чужого адреса и подставлять адрес клиента при соединении с сервером. Это позволяет развёртывать их как обычный маршрутизатор или межсетевой экран, в режиме сквозной пересылки, очень похожем на режим пакетных балансировщиков. Это особенно ценится в продуктах, сочетающих режим обработки пакетов и режим прокси. Очевидно, что DSR в таком случае по-прежнему невозможен, а обратный трафик необходимо направлять через балансировщик.

Хорошо масштабируемая многоуровневая схема может начинаться с пограничного маршрутизатора, принимающего трафик из нескольких сбалансированных каналов и распределяющего его с помощью ECMP на первый уровень из нескольких пакетных балансировщиков с состоянием (L4). Эти балансировщики L4 передают трафик ещё большему числу балансировщиков на основе прокси (L7), которые разбирают содержимое и выбирают конечный сервер-получатель.

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

Самый распространённый метод — периодические пробы, подтверждающие работоспособность компонента. Их называют «проверками работоспособности». Они должны соответствовать типам отказов, которые требуется выявить. Например, проверка ping не обнаружит, что веб-сервер аварийно завершился и больше не прослушивает порт. Соединение с портом выявит такую проблему, а более сложный запрос может также подтвердить работоспособность сервера и доступность используемой им базы данных. Проверки часто повторяют несколько раз, чтобы исключить случайные ошибки измерения. Интервал между ними должен быть достаточно мал, чтобы неисправный компонент не использовался слишком долго после возникновения ошибки.

Другие методы анализируют выборку рабочего трафика, отправляемого адресату, проверяют правильность его обработки и исключают компоненты с некорректными ответами. Однако при этом приходится жертвовать частью рабочего трафика, что не всегда допустимо. Сочетание обоих механизмов объединяет их преимущества: для выявления отказа применяются оба, а для определения восстановления — только проверки работоспособности. Ещё один метод основан на централизованных сообщениях: центральный агент мониторинга периодически сообщает всем балансировщикам состояние всех компонентов. Это даёт каждому компоненту общее представление об инфраструктуре, хотя иногда с меньшей точностью или оперативностью. Такой подход лучше всего подходит для сред с большим числом балансировщиков и серверов.

Балансировщики уровня 7 сталкиваются и с другой задачей — привязкой сеансов, также называемой сохранением привязки. Обычно несколько последовательных запросов или соединений от одного источника, например конечного пользователя, нужно направлять одному адресату. Самый известный пример — корзина интернет-магазина. Если каждый щелчок создаёт новое соединение, пользователя всегда необходимо отправлять на сервер, где хранится его корзина. Анализ содержимого позволяет легче выделить в запросе элементы для определения нужного сервера, но этого не всегда достаточно. Например, если ключом выбора сервера служит исходный адрес, можно применить алгоритм хеширования: один IP-адрес всегда направляется на один сервер на основе деления адреса на число доступных серверов. Но при отказе сервера результат изменится, и все пользователи внезапно попадут на другие серверы, потеряв свои корзины. Решение — запоминать выбранного адресата и при каждом появлении того же посетителя направлять его на тот же сервер независимо от числа доступных серверов. Сведения можно хранить в памяти балансировщика; если он не единственный, их может потребоваться реплицировать другим балансировщикам. Либо их можно разными способами хранить у клиента, если он способен передавать их с каждым запросом: посредством вставки cookie, перенаправления на поддомен и т. п. Дополнительное преимущество такого механизма — отсутствие зависимости от нестабильных или неравномерно распределённых сведений, например исходного IP-адреса. Именно это является главным доводом в пользу балансировщика уровня 7 вместо уровня 4.

Чтобы извлечь cookie, поле заголовка host, URL или другие сведения, балансировщику может потребоваться расшифровать трафик SSL/TLS и, возможно, снова зашифровать его перед передачей серверу. Высокая стоимость этой операции объясняет, почему в некоторых инфраструктурах с большим объёмом трафика бывает много балансировщиков.

Поскольку балансировщик уровня 7 выполняет множество сложных операций с трафиком — расшифровывает, разбирает, изменяет, сопоставляет cookie, выбирает сервер и т. п., — он действительно может вызывать проблемы. Но очень часто его обвиняют и в тех проблемах, которые он лишь выявил. Нередко обнаруживается нестабильность серверов, которые периодически отключаются и возвращаются в работу; жёстко заданные ссылки на веб-страницах, заставляющие клиентов обращаться прямо к определённому серверу в обход балансировщика; либо очень медленные ответы под высокой нагрузкой, вызывающие тайм-ауты. Поэтому ведение журнала — исключительно важная часть балансировки уровня 7. После сообщения о проблеме необходимо выяснить, принял ли балансировщик неверное решение и, если да, почему, чтобы исключить повторение.

2 - Что такое HAProxy и как он работает

Название «HAProxy» обозначает продукт, а «haproxy» — исполняемую программу, программный пакет или процесс. Однако оба варианта часто используются в обоих значениях и произносятся как H-A-Proxy. На раннем этапе «haproxy» расшифровывалось как «прокси высокой доступности», а название писалось в два отдельных слова, хотя сейчас оно означает только «HAProxy».

3.1. Чем является и чем не является HAProxy

HAProxy — это:

• TCP-прокси: он может принять TCP-соединение на прослушивающем сокете, подключиться к серверу и связать эти сокеты, обеспечивая передачу трафика в обоих направлениях; с обеих сторон поддерживаются IPv4, IPv6 и даже сокеты UNIX, что даёт простой способ преобразовывать адреса между разными семействами.

• обратный HTTP-прокси (в терминологии HTTP — «шлюз»): он выступает в качестве сервера, получает HTTP-запросы по соединениям, принятым на прослушивающем TCP-сокете, и передаёт запросы из этих соединений серверам по другим соединениям. Он может использовать любую комбинацию HTTP/1.x и HTTP/2 с любой стороны и даже автоматически определяет протокол каждой стороны при использовании ALPN поверх TLS.

• средство завершения, инициирования и разгрузки SSL: SSL/TLS можно использовать на соединении от клиента, на соединении к серверу или даже на обоих соединениях. Многие параметры можно задавать для отдельных имён (SNI) и обновлять во время выполнения без перезапуска. Такие конфигурации прекрасно масштабируются: сообщалось о развёртываниях, использующих от десятков до сотен тысяч сертификатов.

• нормализатор TCP: поскольку соединения локально завершаются операционной системой, их стороны не связаны между собой, поэтому аномальный трафик, например некорректные пакеты, сочетания флагов, объявления окон, номера последовательности, незавершённые соединения (SYN-флуд) и тому подобное, не передаётся на другую сторону. Это защищает уязвимые стеки TCP от атак на протокол, а также позволяет оптимизировать параметры соединения с клиентом без изменения настроек стеков TCP на серверах.

• нормализатор HTTP: при настройке обработки HTTP-трафика передаются только корректные полные запросы. Это защищает от множества атак на протокол. Кроме того, отклонения от протокола, допустимые по спецификации, исправляются, чтобы не вызывать проблем на серверах (например, многострочные заголовки).

• инструмент исправления HTTP: он может изменять, исправлять, добавлять, удалять и переписывать URL или любой заголовок запроса либо ответа. Это помогает устранять проблемы совместимости в сложных средах.

• коммутатор на основе содержимого: он может учитывать любой элемент запроса, решая, какому серверу передать запрос или соединение. Поэтому через один порт можно обслуживать несколько протоколов (например, HTTP, HTTPS, SSH).

• балансировщик серверной нагрузки: он может распределять TCP-соединения и HTTP-запросы. В режиме TCP решение о балансировке принимается для всего соединения. В режиме HTTP решение принимается для каждого запроса.

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

• средство защиты от DDoS и злоупотребления сервисом: он может вести обширную статистику по IP-адресам, URL, файлам cookie и другим признакам, выявлять злоупотребления и принимать меры (замедлять нарушителей, блокировать их, перенаправлять к устаревшему содержимому и т. д.).

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

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

• кэширующий прокси: он может кэшировать ответы в оперативной памяти, чтобы последующие запросы того же объекта не требовали повторной передачи по сети с сервера, пока объект остаётся в кэше и сохраняет актуальность. При этом объекты не сохраняются в постоянном хранилище. Учтите, что эта функция кэширования не требует обслуживания и направлена исключительно на экономию ценных ресурсов haproxy, а не ресурсов сервера. Кэши, предназначенные для оптимизации серверов, требуют гораздо более тонкой настройки и гибкости. Если нужен такой расширенный кэш, используйте Varnish Cache, который прекрасно интегрируется с haproxy, особенно когда SSL/TLS требуется с любой из сторон.

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

HAProxy не является:

• явным HTTP-прокси, то есть прокси, через который браузеры выходят в Интернет. Для этой задачи есть отличное специализированное ПО с открытым исходным кодом, например Squid. Однако HAProxy можно установить перед таким прокси для балансировки нагрузки и обеспечения высокой доступности.

• средством очистки данных: он не изменяет тела запросов или ответов.

• статическим веб-сервером: при запуске он изолирует себя в окружении chroot и сбрасывает привилегии, поэтому после запуска вообще не обращается к файловой системе. По этой причине его невозможно превратить в статический веб-сервер (однако динамические серверы поддерживаются через FastCGI). Для этого есть отличное ПО с открытым исходным кодом, например Apache и Nginx, а HAProxy можно легко установить перед ними для балансировки нагрузки, обеспечения высокой доступности и ускорения.

• балансировщиком нагрузки на уровне пакетов: он не видит IP-пакеты или UDP-дейтаграммы, не выполняет NAT и тем более DSR. Эти задачи относятся к нижним уровням. Некоторые компоненты на уровне ядра, например IPVS (Linux Virtual Server), уже прекрасно с ними справляются и отлично дополняют HAProxy.

3.2. Как работает HAProxy

HAProxy — это неблокирующий движок с событийной архитектурой, сочетающий очень быстрый уровень ввода-вывода с многопоточным планировщиком на основе приоритетов. Поскольку он изначально предназначен для пересылки данных, его архитектура оптимизирована для максимально быстрой передачи данных с минимальным числом операций. Особое внимание уделяется эффективному использованию кэша CPU: соединения закрепляются за одним CPU как можно дольше. Для этого реализована многоуровневая модель с механизмами обхода на каждом уровне, которые гарантируют, что данные не попадут на более высокие уровни без необходимости. Основная обработка происходит в ядре, а HAProxy старается помочь ядру выполнить работу как можно быстрее, передавая подсказки или избегая определённых операций, если предполагает, что их можно будет сгруппировать позже. В результате типичное распределение времени обработки составляет 15% в HAProxy и 85% в ядре в режиме TCP или HTTP close и около 30% в HAProxy и 70% в ядре в режиме HTTP keep-alive.

Один процесс может запускать множество экземпляров прокси; сообщалось об успешной работе конфигураций с 300000 отдельными прокси в одном процессе. Системы с одним процессором и одним ядром более чем достаточно для более чем 99% пользователей, поэтому пользователям контейнеров и виртуальных машин рекомендуется выбирать самые маленькие доступные образы, чтобы снизить эксплуатационные затраты и упростить устранение неполадок. Однако машина, на которой работает HAProxy, ни при каких обстоятельствах не должна использовать подкачку, а её CPU нельзя искусственно ограничивать (выделяя долю CPU в гипервизоре) или делить с ресурсоёмкими вычислительными процессами, которые создавали бы очень большую задержку переключения контекста.

Многопоточность позволяет задействовать всю доступную вычислительную мощность, используя один поток на ядро CPU. Это особенно полезно для SSL или когда требуется скорость пересылки данных выше 40 Гбит/с. В таких случаях критически важно избегать взаимодействия между несколькими физическими CPU: оно может создавать серьёзные узкие места в сетевом стеке и в самом HAProxy. Хотя некоторым это кажется нелогичным, при возникновении проблем с производительностью первым действием часто должно быть уменьшение числа CPU, на которых работает HAProxy.

Для работы HAProxy нужны только исполняемый файл haproxy и файл конфигурации. Для ведения журнала настоятельно рекомендуется настроить демон syslog и ротацию журналов. Журналы также можно отправлять в stdout/stderr, что бывает полезно внутри контейнеров. Файлы конфигурации разбираются до запуска, затем HAProxy пытается привязать все прослушивающие сокеты и отказывается запускаться, если что-либо не удалось. После этого сбои уже невозможны. Это означает, что ошибок во время выполнения не возникает и, если запуск прошёл успешно, программа будет работать до остановки.

После запуска HAProxy выполняет ровно 3 действия:

• обрабатывает входящие соединения;

• периодически проверяет состояние серверов (проверки работоспособности);

• обменивается информацией с другими узлами haproxy.

Обработка входящих соединений — безусловно, самая сложная задача, поскольку зависит от множества вариантов конфигурации, однако её можно свести к следующим 9 шагам:

• принять входящие соединения с прослушивающих сокетов, принадлежащих сущности конфигурации «frontend», которая ссылается на один или несколько прослушиваемых адресов;

• применить к этим соединениям правила обработки фронтенда, которые могут привести к их блокировке, изменению некоторых заголовков или перехвату для выполнения внутренних апплетов, таких как страница статистики или CLI;

• передать эти входящие соединения другой сущности конфигурации, представляющей группу серверов «backend», которая содержит список серверов и стратегию балансировки нагрузки для этой группы серверов;

• применить к этим соединениям правила обработки бэкенда;

• выбрать сервер для передачи соединения в соответствии со стратегией балансировки нагрузки;

• применить к данным ответа правила обработки бэкенда;

• применить к данным ответа правила обработки фронтенда;

• создать запись в журнале с подробным описанием произошедшего;

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

Фронтенды и бэкенды иногда считают половинами прокси, поскольку каждый из них работает только с одной стороной сквозного соединения: фронтенд — только с клиентами, а бэкенд — только с серверами. HAProxy также поддерживает полные прокси, которые представляют собой точное объединение фронтенда и бэкенда. Когда нужна обработка HTTP, конфигурацию обычно разделяют на фронтенды и бэкенды: это открывает много возможностей, поскольку любой фронтенд может передать соединение любому бэкенду. Для прокси, работающих только с TCP, разделение на фронтенды и бэкенды редко даёт преимущество, а конфигурация с полными прокси может быть удобнее для чтения.

3 - Базовые возможности

В этом разделе перечислены возможности HAProxy: одни обычно ожидаются от любого современного балансировщика нагрузки, другие непосредственно вытекают из архитектуры HAProxy. Более сложные возможности подробно рассматриваются в следующем разделе.

3.3.1. Базовые возможности: проксирование

Проксирование — передача данных между клиентом и сервером по двум независимым соединениям. HAProxy поддерживает следующие базовые возможности проксирования и управления соединениями:

• Предоставление серверу корректного соединения для защиты от любых ошибок или атак со стороны клиента.

• Прослушивание нескольких IP-адресов и/или портов, в том числе диапазонов портов.

• Прозрачный приём: перехват трафика к произвольному IP-адресу, даже не принадлежащему локальной системе.

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

• Прозрачное подключение: при необходимости подстановка IP-адреса клиента или любого другого адреса при соединении с сервером.

• Предоставление серверам надёжного IP-адреса для обратного трафика при балансировке между несколькими площадками.

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

• Оптимизация стеков TCP, например SACK, управления перегрузкой и уменьшение влияния RTT.

• Поддержка разных семейств протоколов по обе стороны, например IPv4/IPv6/Unix.

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

• Проверка протокола: анализ HTTP, SSL или полезной нагрузки с отклонением некорректных элементов протокола, если явно не предписано их принимать.

• Применение политик: пересылается только разрешённый трафик.

• Ограничение входящих и исходящих соединений определёнными сетевыми пространствами имён (только Linux), упрощающее создание балансировщика между контейнерами для нескольких арендаторов.

• Протокол PROXY передаёт серверу IP-адрес клиента даже для трафика, отличного от HTTP. Это расширение HAProxy уже принято рядом сторонних продуктов; на момент написания как минимум следующими:

  • клиент: haproxy, stud, stunnel, exaproxy, ELB, squid;
  • сервер: haproxy, stud, postfix, exim, nginx, squid, node.js, varnish.

3.3.2. Базовые возможности: SSL

Инженеры Google считают стек SSL HAProxy одним из самых функциональных (http://istlsfastyet.com/ ). Наиболее часто используемые возможности, обеспечивающие его полноту:

• Обслуживание нескольких сайтов на основе SNI без ограничения их числа и с упором на производительность. Известно как минимум одно развёртывание с 50000 доменов и отдельными сертификатами для них.

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

• Аутентификация клиентов по сертификатам с настраиваемыми действиями при отсутствии действительного сертификата. Например, можно направить клиента на другую серверную ферму для повторного выпуска его сертификата.

• Аутентификация сервера бэкенда, подтверждающая, что это настоящий сервер, а не посредник.

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

• Расширения TLS NPN и ALPN, позволяющие надёжно завершать зашифрованные соединения SPDY/HTTP2 и передавать их серверам бэкенда в открытом виде.

• OCSP stapling, дополнительно сокращающий время загрузки первой страницы за счёт передачи ответа OCSP вместе с остальными данными, когда клиент запрашивает Certificate Status Request.

• Динамический размер записей, обеспечивающий одновременно высокую производительность и низкую задержку и заметно сокращающий время загрузки страницы: браузер может начинать получать новые объекты, пока предыдущие пакеты ещё находятся в пути.

• Постоянный доступ ко всем существенным сведениям уровня SSL/TLS для журналирования, контроля доступа, отчётности и т. п. Эти сведения можно включать в заголовки HTTP или даже в расширение протокола PROXY, чтобы сервер получил всю информацию, доступную ему при самостоятельном завершении SSL.

• Обнаружение, запись в журнал и блокировка известных атак даже при уязвимых библиотеках SSL, например атаки Heartbleed на некоторые версии OpenSSL.

• Поддержка возобновления сеансов без хранения состояния (расширение TLS Ticket из RFC 5077). Билеты TLS можно обновлять через CLI, что позволяет реализовать совершенную прямую секретность, часто меняя билеты.

3.3.3. Базовые возможности: мониторинг

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

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

• Проверки работоспособности поддерживают два порога гистерезиса для переходов в рабочее и нерабочее состояния, защищая от частого переключения состояний.

• Проверки можно отправлять на другой адрес, порт или по другому протоколу. Это позволяет проверять одну службу как показатель работоспособности нескольких, например порт HTTPS у сервера HTTP+HTTPS.

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

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

• Доступны разные методы проверки: соединение TCP, запрос HTTP, приветствие SMTP, приветствие SSL, LDAP, SQL, Redis, сценарии send/expect — все с SSL или без него.

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

• Состояние сервера отображается в интерфейсе статистики и может использоваться при маршрутизации: трафик можно направлять на разные фермы в зависимости от их размера и/или работоспособности, например при потере связи между ЦОД.

• Через запросы проверки работоспособности HAProxy может передавать серверам сведения: их имена, вес, число других серверов в ферме и т. п. Серверы могут учитывать их при ответах и принятии решений, например отложить резервное копирование, чтобы сохранить больше ресурсов CPU.

• Через проверки работоспособности серверы могут сообщать более подробное состояние, чем просто включён/выключен: например, запросить остановку направления новых посетителей перед своим выключением.

• Сам HAProxy может сообщать состояние внешним компонентам — маршрутизаторам или другим балансировщикам, что позволяет строить полноценные инфраструктуры с несколькими путями и уровнями.

3.3.4. Базовые возможности: высокая доступность

Как любой серьёзный балансировщик нагрузки, HAProxy уделяет большое внимание доступности и максимальной непрерывности обслуживания:

• Используются только работоспособные серверы, остальные автоматически исключаются из ферм балансировки. Однако при определённых условиях их всё же можно принудительно использовать.

• Поддерживается плавный вывод серверов из фермы без воздействия на существующие соединения.

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

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

• Архитектура без сохранения состояния упрощает создание кластеров: HAProxy стремится обеспечить максимальную непрерывность обслуживания без хранения сведений, которые можно потерять при отказе. Благодаря этому передача обслуживания происходит максимально плавно.

• Хорошая интеграция со стандартным демоном VRRP keepalived: HAProxy легко сообщает ему своё состояние и хорошо работает с плавающими виртуальными IP-адресами. Примечание: используйте только протоколы резервирования IP (VRRP/CARP), а не кластерные решения (Heartbeat и т. п.), поскольку они обеспечивают наиболее быстрое, плавное и надёжное переключение.

3.3.5. Базовые возможности: балансировка нагрузки

HAProxy предлагает довольно полный набор средств балансировки нагрузки, большинство из которых, к сожалению, отсутствует в ряде других продуктов:

• Поддерживается не менее 10 алгоритмов балансировки, некоторые из которых используют входные данные и дают неограниченное число вариантов применения. Наиболее распространены round-robin — поочерёдный выбор серверов для коротких соединений; leastconn — выбор сервера, который дольше всего не использовался, среди серверов с минимальным числом соединений, подходящий для длительных соединений; source — прямой выбор по исходному адресу клиента для ферм SSL или терминальных серверов; URI — прямой выбор по URI HTTP для кешей HTTP; hdr — прямой выбор по содержимому определённого поля заголовка HTTP; first — сосредоточение всех соединений на минимальном числе серверов, чтобы неиспользуемые короткоживущие виртуальные машины можно было выключить.

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

• Для round-robin, leastconn и согласованного хеширования поддерживаются динамические веса. Их можно менять на лету через CLI или даже с помощью агента на сервере.

• Везде, где поддерживается динамический вес, доступен slow-start — постепенное принятие сервером трафика. Это важно для чувствительных серверов приложений, которым нужно компилировать классы во время работы, и холодных кешей, которые необходимо заполнить перед полной нагрузкой.

• Хеширование может применяться к разным элементам: исходному адресу клиента, компонентам URL, элементу строки запроса, значениям полей заголовков, параметру POST, cookie RDP.

• Согласованное хеширование защищает фермы от массового перераспределения нагрузки при добавлении или удалении серверов. Это особенно важно для больших кеширующих ферм и позволяет использовать slow-start для заполнения холодных кешей.

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

3.3.6. Базовые возможности: привязка сеансов

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

• При необходимости сведения для привязки можно независимо сопоставлять и запоминать из разных источников. Например, JSESSIONID можно искать и в cookie, и в URL. Одновременно можно запоминать до 8 источников, каждый из которых может указывать на отдельную таблицу stick-table.

• Источником привязки может быть всё, что видно в запросе или ответе: исходный адрес, смещение и длина полезной нагрузки TCP, элементы строки запроса HTTP, значения полей заголовков, cookie и т. п.

• Таблицы stick-tables реплицируются между всеми узлами в режиме с несколькими ведущими узлами.

• Часто используемые элементы, например SSL-ID или cookie RDP для ферм TSE, доступны непосредственно, что упрощает работу с ними.

• Все правила привязки могут динамически зависеть от условий ACL.

• Можно отказаться от привязки к определённым серверам, например резервным, чтобы после возвращения основного сервера нагрузка автоматически перешла к нему. Это часто используется в средах с несколькими путями.

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

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

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

• Специальный механизм ограничения времени бездействия и срока действия cookie позволяет плавно прекращать привязку на постоянно работающих устройствах — смартфонах, телевизорах, бытовой технике — без хранения этих сведений в постоянном хранилище.

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

• soft-stop гарантирует, что к назначенному серверу продолжат обращаться только пользователи, уже имеющие сведения о привязке, а новые туда не попадут.

3.3.7. Базовые возможности: ведение журнала

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

HAProxy предоставляет очень подробные журналы с миллисекундной точностью и точным временем приёма соединения, которое можно найти в журналах межсетевого экрана, например для сопоставления NAT. По умолчанию журналы TCP и HTTP содержат все необходимые для устранения неполадок сведения: исходный IP-адрес и порт, фронтенд, бэкенд, сервер, таймеры получения запроса, ожидания в очереди, установки соединения, получения заголовков ответа и передачи данных; общее состояние процесса; число соединений; состояние очередей; число повторных попыток; подробные действия привязки и причины отключения; захваченные заголовки с безопасным кодированием вывода. Формат можно расширить или заменить, включив любые извлечённые образцы, переменные и захваченные значения, чтобы получить очень подробные сведения. Например, можно записывать суммарное число запросов клиента или число посещённых им разных URL.

Уровень журналирования можно настраивать для каждого запроса обычными ACL: автоматически подавлять шумные записи и повышать уровень до предупреждения при аномальном поведении небольшой части трафика, например при слишком большом числе URL или ошибок HTTP с одного исходного адреса. Административные сообщения также имеют свои уровни и сообщают, например, об отказе или восстановлении сервера.

Каждый фронтенд и бэкенд может использовать несколько независимых направлений вывода журналов, что упрощает обслуживание нескольких арендаторов. Журналы предпочтительно отправлять по UDP, возможно в JSON, обрезая строки до настраиваемой длины для гарантированной доставки. Их также можно отправлять в stdout/stderr, любой файловый дескриптор или кольцевой буфер, на который клиент может подписаться для получения записей.

3.3.8. Базовые возможности: статистика

HAProxy предоставляет веб-интерфейс статистики с аутентификацией, уровнями безопасности и областями видимости. Поэтому каждому заказчику хостинга можно дать отдельную страницу только с его экземплярами. Её можно разместить по скрытому URL обычного сайта, не открывая новый порт. Страница также может показывать доступность других узлов HAProxy, позволяя с первого взгляда оценить работоспособность всей системы. Представление компактно, но доступны многочисленные подробности: причины ошибок, время с последнего обращения и изменения и т. п. Те же данные доступны в виде таблицы CSV, которую другие инструменты могут импортировать для построения графиков. Страница может автоматически обновляться для использования как панели мониторинга на большом экране. В административном режиме она также позволяет менять состояние серверов, упрощая обслуживание.

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

4 - Стандартные возможности

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

3.4.1. Стандартные возможности: извлечение и преобразование сведений

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

Образцы можно извлекать из разных источников:

• Константы: целые числа, строки, IP-адреса, двоичные блоки.

• Процесс: дата, переменные окружения, состояние сервера/фронтенда/бэкенда/процесса, число и интенсивность передачи байтов/соединений, длина очереди, генератор случайных чисел и т. п.

• Переменные: на уровне сеанса, запроса или ответа.

• Клиентское соединение: исходные и целевые адреса и порты и все связанные статистические счётчики.

• Клиентский сеанс SSL: протокол, версия, алгоритм, шифр, размер ключа, идентификатор сеанса, все поля сертификатов клиента и сервера, серийный номер сертификата, SNI, ALPN, NPN, поддержка клиентом определённых расширений.

• Содержимое буферов запроса и ответа: произвольная полезная нагрузка по смещению и длине, длина данных, cookie RDP, декодирование типа приветствия SSL, декодирование TLS SNI.

• HTTP, запрос и ответ: метод, URI, путь, аргументы строки запроса, код состояния, значения заголовков, значение заголовка по позиции, cookie, захваченные значения, аутентификация, элементы тела.

Затем образец может пройти через операторы, называемые преобразователями. Преобразователь принимает образец и создаёт новый, возможно совершенно другого типа. Например, он может вернуть целочисленную длину входной строки или перевести строку в верхний регистр. До окончательного использования к образцу можно последовательно применить любое число преобразователей. Среди доступных чаще всего используются:

• Арифметические и логические операторы для сложных вычислений над входными данными: отношений, процентов или просто перевода между единицами измерения.

• Маски IP-адресов, полезные для объединения адресов в более крупные сети.

• Представление данных: декодирование URL, base64, шестнадцатеричный формат, строки JSON, хеширование.

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

• Преобразование дат: в формат даты HTTP, из местного времени в UTC и обратно, добавление и вычитание смещения.

• Поиск записи в таблице привязок для получения статистики или назначенного сервера.

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

3.4.2. Стандартные возможности: карты отображения

Карты отображения — мощный тип преобразователя. При запуске в память загружается файл с двумя столбцами, затем каждый входной образец ищется в первом столбце. Если запись найдена, возвращается соответствующее значение из второго столбца, иначе — значение по умолчанию. Результат тоже является образцом, поэтому к нему можно применять последующие преобразования, включая поиск в других картах. Чаще всего карты используют для преобразования IP-адреса клиента в номер AS или код страны, поскольку они поддерживают наиболее длинное совпадение сетевых адресов, но возможны и многие другие применения.

Одно из их преимуществ — обновление на лету через CLI или определённые действия с использованием других образцов. Это позволяет хранить и извлекать сведения между последовательными обращениями. Другое преимущество — индексирование на основе двоичных деревьев: даже при сотнях тысяч записей поиск чрезвычайно быстр, поэтому геолокация требует мало ресурсов и легко настраивается.

3.4.3. Стандартные возможности: ACL и условия

Большинство операций HAProxy может выполняться условно. Условия строятся объединением нескольких ACL логическими операторами AND, OR и NOT. Каждая ACL представляет собой последовательность проверок на основе следующих элементов:

• Метод извлечения образца для получения проверяемого элемента.

• Необязательная последовательность преобразователей элемента.

• Список шаблонов для сопоставления.

• Метод сопоставления, определяющий способ сравнения шаблонов с образцом.

Например, образец можно получить из заголовка HTTP «Host», перевести в нижний регистр, а затем сопоставить с несколькими регулярными выражениями соответствующим методом.

Технически ACL построены на той же основе, что карты отображения: у них одинаковые внутренние структуры, методы сопоставления шаблонов и производительность. Единственное существенное отличие: вместо образца они возвращают только «found» или «not found». Шаблоны ACL можно объявлять прямо в конфигурации, отдельный файл не требуется. Для удобства и понятности конфигурации ACL можно именовать. Именованную ACL можно объявить несколько раз: все определения будут проверяться по очереди до первого совпадения.

Предоставляется около 13 методов сопоставления шаблонов, включая маску IP-адреса, диапазоны целых чисел, подстроки и регулярные выражения. Они работают как функции, и, как в любом языке программирования, вычисляется только необходимое. Если условие с OR уже истинно, следующие части не вычисляются; если условие с AND уже ложно, оставшаяся часть также не вычисляется.

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

3.4.4. Стандартные возможности: переключение содержимого

HAProxy реализует механизм переключения на основе содержимого. Соединение или запрос поступает во фронтенд, затем обрабатываются переданные с ним сведения. На их основе можно задать условия ACL для выбора бэкенда, который обработает запрос. Так трафик направляется в разные бэкенды в зависимости от содержимого запроса. Типичный пример — использование заголовка Host и/или частей пути (подкаталогов либо расширений файлов), чтобы определить, относится ли запрос HTTP к статическому объекту или приложению. Статические объекты направляются в бэкенд из быстрых лёгких серверов, а остальной трафик — на более сложный сервер приложений. Получается гибкая схема виртуального хостинга, удобная для объединения нескольких технологий в общее решение.

Другой вариант применения — выбор алгоритма балансировки по разным критериям. Например, кеш может использовать хеш URI, а приложение — round-robin.

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

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

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

Таблицы привязок обычно хранят сведения о привязке сеансов — ссылку на сервер, куда был направлен посетитель. Ключом служит связанный с посетителем идентификатор: исходный адрес, идентификатор SSL соединения, cookie HTTP или RDP, номер заказчика из URL или полезной нагрузки и т. п. Сохраняемое значение — идентификатор сервера.

Таблицы привязок поддерживают 3 типа образцов в ключах: целые числа, строки и адреса. В прокси можно ссылаться только на одну таблицу привязок, везде обозначаемую именем прокси. Параллельно можно отслеживать до 8 ключей. Идентификатор сервера фиксируется при обработке запроса или ответа, когда известны и ключ, и сервер.

Содержимое таблиц может реплицироваться в режиме active-active с другими узлами HAProxy, называемыми «peers», а при перезагрузке конфигурации — также с новым процессом. Тогда все узлы балансировки имеют одинаковые сведения и принимают одинаковые решения о маршрутизации, даже если запросы клиента распределяются между несколькими узлами.

Поскольку таблицы индексируются по признаку, позволяющему распознать клиента, в них часто хранят и дополнительные сведения, например статистику по клиентам. Дополнительная статистика занимает место и должна объявляться явно. Можно хранить входящую и исходящую пропускную способность, число одновременных соединений, интенсивность и число соединений за период, количество и частоту ошибок, специальные метки и счётчики и т. п. Чтобы сохранять такие сведения без обязательной привязки к серверу, реализована специальная функция отслеживания. Она позволяет одновременно отслеживать до 3 ключей из разных таблиц независимо от правил привязки. Любую сохраняемую статистику можно искать, выгружать и очищать через CLI, расширяя возможности устранения неполадок в реальном времени.

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

3.4.6. Стандартные возможности: форматированные строки

HAProxy работает со строками во многих местах: в журналах, перенаправлениях, добавляемых заголовках и т. п. Для максимальной гибкости введены форматированные строки, первоначально для журналирования, поэтому механизм до сих пор называется «log-format». Такие строки содержат управляющие последовательности для вставки динамических данных, включая переменные и выражения извлечения образцов, и даже изменения кодирования при преобразовании результата в строку, например добавления кавычек. Это мощное средство формирования заголовков, данных ответа и даже шаблонов ответов, а также настройки строк журнала. Чтобы обычные строки оставались простыми в составлении, предусмотрено около 50 специальных меток — сокращений для часто используемых в журналах сведений.

3.4.7. Стандартные возможности: переписывание HTTP и перенаправления

Установка балансировщика перед приложением, которое на это не рассчитано, без подходящих инструментов может оказаться сложной. Одна из самых частых задач — изменить заголовки запросов и ответов, чтобы балансировщик выглядел исходным сервером, и исправить жёстко заданные сведения. Сюда относятся изменение пути запроса (что настоятельно не рекомендуется), поля Host, поля Location в ответах перенаправления, атрибутов пути и домена cookie и т. п. Также многие серверы слишком многословны и раскрывают в ответах лишние сведения, повышая уязвимость к целевым атакам. Хотя теоретически очищать ответы не задача балансировщика, на практике он расположен в наиболее удобной точке инфраструктуры для гарантированной очистки.

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

Для этого HAProxy поддерживает разные возможности переписывания и перенаправления, в том числе:

• Переписывание URL и заголовков запросов и ответов по регулярным выражениям. Это самый распространённый способ изменения значений заголовков благодаря понятности и удобству регулярных выражений.

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

• Перенаправления HTTP с любым кодом 3xx на относительный, абсолютный или полностью динамический URI из форматированной строки.

• Дополнительные параметры перенаправлений: установка или удаление cookie, отбрасывание строки запроса, добавление отсутствующей завершающей косой черты и т. п.

• Мощная директива «return», позволяющая настроить любую часть ответа — состояние, заголовки, тело — с динамическим содержимым или даже файлами шаблонов.

• Условия на основе ACL для всех операций.

3.4.8. Стандартные возможности: защита серверов

HAProxy стремится максимально повысить доступность службы и для этого защищает серверы от перегрузки и атак. Первый и самый важный принцип: серверам пересылаются только полные корректные запросы. Прежде всего HAProxy должен найти элементы протокола, необходимые для синхронизации с потоком байтов. Кроме того, пока запрос не получен полностью, нельзя знать, не изменят ли некоторые элементы его смысл. Прямое преимущество — серверы не получают некорректные или неполные запросы. Это очень эффективная защита от атак slowloris, практически не влияющих на HAProxy.

Другой важный момент — буферы HAProxy для запросов и ответов. Отправляя запрос серверу только после полного получения и быстро считывая весь ответ из локальной сети, HAProxy занимает соединение с сервером на очень короткое время, максимально сохраняя его ресурсы.

Из этого непосредственно следует возможность искусственно ограничивать число одновременных соединений или незавершённых запросов к серверу. Это гарантирует отсутствие перегрузки, даже если во время всплесков трафика сервер непрерывно работает на 100% мощности. Все лишние запросы просто ждут в очереди освобождения места. Такая огромная экономия ресурсов обычно настолько улучшает время ответа, что работа оказывается быстрее, чем при перегрузке сервера. Запросы из очереди можно перераспределять на другие серверы или даже отменять в очереди при отказе клиента от запроса. Это защищает и от «эффекта обновления страницы»: каждый щелчок «обновить» на медленно загружаемой странице обычно создаёт новый запрос и поддерживает перегрузку.

Механизм slow-start также защищает перезапускаемые серверы от интенсивного трафика, пока они ещё завершают запуск или компилируют классы.

На уровне протокола парсер HTTP можно ослабить, чтобы принимать не соответствующие стандарту, но безвредные запросы и ответы и даже исправлять их. Это сохраняет доступность ошибочных приложений на время разработки исправления. Одновременно проблемные сообщения полностью захватываются с подробным отчётом, помогающим разработчикам найти ошибку. Наиболее опасные нарушения протокола корректно выявляются, обрабатываются и исправляются. Например, некорректный запрос или ответ с двумя заголовками Content-length исправляется, если их значения в точности совпадают, и отклоняется при различии, поскольку это уже угроза безопасности. Анализ протокола не ограничен HTTP: он доступен и для других протоколов, например TLS или RDP.

При обнаружении нарушения протокола или атаки возможны разные реакции: обычный ответ «HTTP 400 bad request», закрытие соединения сбросом TCP или имитация ошибки после длительной задержки — ловушка соединений («tarpit»), сбивающая атакующего с толку. Всё это защищает серверы, делая продолжение атаки слишком затратным для нарушителя.

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

5 - Расширенные возможности

3.5.1. Расширенные возможности: управление

HAProxy спроектирован для исключительно стабильной работы и безопасного управления в обычной рабочей среде. Он поставляется одним исполняемым файлом и не требует процедуры установки. Несколько версий легко могут сосуществовать: экземпляры можно и рекомендуется обновлять постепенно, в порядке важности, вместо одновременного переноса всех экземпляров. Файлы конфигурации удобно хранить под контролем версий. Проверка конфигурации выполняется отдельно от работающей службы, поэтому не нужно перезапускать службу, рискуя получить сбой. При проверке могут обнаруживаться сложные ошибки (например, правило, скрывающее другое правило, или неработоспособная привязка сеансов); для их устранения выдаются подробные предупреждения и рекомендации. Обратная совместимость конфигурации охватывает очень давние версии: версия 1.5 полностью поддерживала конфигурации версии 1.1, написанные 13 лет назад, а в 1.6 прекращена поддержка лишь почти неиспользуемых устаревших директив, которые можно заменить другими средствами. Обновление конфигурации и программы происходит плавно и без прерывания обслуживания: старые и новые процессы могут сосуществовать в системе, каждый обрабатывая свои соединения. При запуске выводятся состояние системы, параметры сборки и сведения о совместимости библиотек.

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

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

Интерфейс командной строки (CLI) доступен через сокет UNIX или TCP и позволяет выполнять различные операции и получать сведения для устранения неполадок. Действия через этот сокет не требуют изменения конфигурации, поэтому его в основном используют для временных изменений. Через интерфейс можно менять адрес, вес и состояние сервера; просматривать статистику и сбрасывать счётчики; выгружать и очищать таблицы привязок, в том числе выборочно по критериям ключей; выводить и принудительно закрывать соединения со стороны клиентов и серверов; выгружать сохранённые ошибки с подробным анализом точной причины и места; выводить, добавлять и удалять записи ACL и карт отображения; обновлять общие секреты TLS; на лету ограничивать число соединений и их интенсивность для произвольных фронтендов (полезно в средах совместного хостинга); отключать отдельный фронтенд, освобождая прослушиваемый порт (полезно, если операции в дневное время запрещены, но исправление всё же необходимо). Также разрешены обновление сертификатов и их конфигурации на лету, включение и просмотр трассировки каждого этапа обработки трафика.

Для сред, где обязателен SNMP, существуют как минимум два агента. Один поставляется с исходным кодом HAProxy и использует модуль Perl Net-SNMP. Другой входит в коммерческие пакеты и не требует Perl. По охвату возможностей они примерно эквивалентны.

На машине с HAProxy часто рекомендуется установить 4 утилиты:

• socat — для подключения к CLI, хотя некоторые варианты netcat тоже в определённой мере это умеют;

• halog из последней версии HAProxy — инструмент анализа журналов, который чрезвычайно быстро (от 1 до 2 GB в секунду) разбирает собственные журналы TCP и HTTP и извлекает полезные сведения и статистику: запросы по URL и исходным адресам, URL, отсортированные по времени ответа или частоте ошибок, коды завершения и т. п. Он предназначен для установки на рабочих серверах и устранения неполадок в реальном времени, поэтому должен быть установлен и готов к использованию;

• tcpdump — настоятельно рекомендуется для получения сетевых трассировок при исследовании проблем, замеченных в журналах. В какой-то момент анализ приложения и haproxy может разойтись, и только сетевые трассировки позволяют определить, кто прав. С помощью tcpdump также довольно часто обнаруживают ошибки сетевых стеков и гипервизоров;

• strace — дополнение к tcpdump. Он показывает, что в действительности видит HAProxy, и помогает отделить проблемы операционной системы от проблем самого HAProxy. Strace часто запрашивают при подозрении на ошибку в HAProxy.

3.5.2. Расширенные возможности: системные функции

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

Прозрачная привязка и установка соединений, привязка соединений к определённому сетевому интерфейсу, а также привязка нескольких процессов к одним IP-адресам и портам доступны только в Linux и BSD. При этом лишь Linux распределяет входящие запросы между доступными процессами средствами ядра.

Linux также предоставляет дополнительные возможности и оптимизации: поддержку сетевых пространств имён (также известных как «контейнеры»), позволяющую HAProxy служить шлюзом между всеми контейнерами; установку MSS, меток Netfilter и поля IP TOS для клиентского соединения; поддержку TCP FastOpen на стороне прослушивания; пользовательские тайм-ауты TCP, позволяющие ядру быстро закрыть соединение, если оно обнаружило исчезновение клиента до истечения заданных тайм-аутов; TCP splicing, при котором ядро пересылает данные между сторонами соединения без многократного копирования памяти; параметр привязки «defer-accept», чтобы получать уведомление о входящем соединении только после появления данных в буферах ядра; отправку запроса вместе с ACK, подтверждающим установку соединения (иногда называемую «piggy-back»), включаемую параметром «tcp-smart-connect». Кроме того, в Linux HAProxy тщательно управляет отложенными ACK TCP, чтобы максимально сократить число пакетов в сети.

В некоторых системах часы ненадёжны и скачут то назад, то вперёд. Раньше это встречалось на отдельных системах NUMA, где процессоры видели немного разное время. В последнее время проблема чаще возникает в виртуализированных средах, где виртуальные часы не связаны с реальными, из-за чего возможны огромные скачки времени — наблюдались даже скачки до 30 секунд. Это создаёт серьёзные проблемы с соблюдением тайм-аутов. Чтобы обойти этот недостаток, HAProxy поддерживает собственные монотонные часы, основанные на системных, но с измерением и компенсацией отклонения. Благодаря этому даже при очень плохих системных часах таймеры остаются достаточно точными, а тайм-ауты продолжают работать. Учтите, что проблема затрагивает все программы в такой системе и не специфична для HAProxy. Типичные проявления — ложные тайм-ауты или зависания приложений. Поэтому при обнаружении такого поведения систему необходимо исправить, даже несмотря на защиту HAProxy.

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

3.5.3. Расширенные возможности: скрипты

HAProxy можно собрать с поддержкой встроенного языка Lua. Это открывает широкие возможности сложной обработки запросов и ответов, принятия решений о маршрутизации, обработки статистики и многого другого. Через Lua можно даже устанавливать параллельные соединения с другими серверами для обмена сведениями. Так можно, например, разработать систему аутентификации, хотя это и непросто. Подробнее об использовании Lua см. документацию в файле «doc/lua-api/index.rst».

3.5.4. Расширенные возможности: трассировка

Администратор в любой момент может подключиться к CLI и включить трассировку различных внутренних подсистем. По умолчанию доступны разные уровни детализации: на практике можно получать от одной строки до 500 строк на запрос. Доступны фильтры и механизм автоматического включения, выключения и приостановки захвата, позволяющие дождаться определённого события и подробно изучить его. Это исключительно удобно для диагностики нарушений протокола неисправными серверами и клиентами или атак отказа в обслуживании.

6 - Расчёт ресурсов и производительность

Типичные показатели использования CPU: в режиме TCP или HTTP с закрытием соединений на HAProxy приходится 15% времени обработки, а на ядро — 85%; в режиме постоянных соединений HTTP на HAProxy приходится около 30%, а на ядро — 70%. Это означает, что операционная система и её настройка сильно влияют на общую производительность.

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

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

При обработке запросов в рамках соединения можно утверждать следующее:

• Пересылка данных требует меньше ресурсов, чем разбор заголовков запроса или ответа.

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

• Установка и закрытие соединения требуют меньше ресурсов, чем возобновление TLS.

• Возобновление TLS требует меньше ресурсов, чем полное рукопожатие TLS с вычислением ключа.

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

• Контекст TLS требует ещё больше памяти, чем соединение с данными.

На практике обработка байтов полезной нагрузки обходится дешевле обработки байтов заголовков, поэтому высокой пропускной способности сети проще добиться с большими объектами (мало запросов на единицу объёма), чем с маленькими (много запросов на единицу объёма). Этим объясняется, почему максимальную пропускную способность всегда измеряют на больших объектах, а интенсивность запросов или соединений — на маленьких.

Некоторые операции хорошо масштабируются при использовании нескольких процессов на разных CPU, другие — хуже. Пропускная способность сети масштабируется лишь до определённого предела, поскольку для больших объектов узким местом редко бывает CPU: обычно ограничение задают сеть и шины данных, по которым передаются данные к сетевым интерфейсам. Интенсивность соединений плохо масштабируется на несколько процессоров из-за ряда системных блокировок при работе с таблицей локальных портов. Интенсивность запросов по постоянным соединениям масштабируется очень хорошо: такие запросы не требуют большого объёма памяти или пропускной способности сети и не обращаются к структурам с блокировками. Вычисление ключей TLS также отлично масштабируется, поскольку полностью ограничено ресурсами CPU. Возобновление TLS масштабируется умеренно хорошо, но примерно на 4 процессах достигает предела: накладные расходы доступа к общей таблице нивелируют небольшой выигрыш от дополнительных вычислительных ресурсов.

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

Следующие результаты получены на Core i7 с частотой 3.7 GHz и двухпортовыми сетевыми адаптерами 10 Gbps под управлением ядра Linux 3.10, HAProxy 1.6 и OpenSSL 1.0.2. HAProxy работал одним процессом на одном выделенном ядре CPU, а ещё два ядра были выделены для сетевых прерываний:

• Максимальная пропускная способность сети без шифрования — 20 Gbps для объектов размером 256 kB и больше, 10 Gbps для объектов размером 41kB и больше.

• 4.6 Gbps трафика TLS с шифром AES256-GCM на больших объектах.

• 83000 соединений TCP в секунду от клиента до сервера.

• 82000 соединений HTTP в секунду от клиента до сервера.

• 97000 запросов HTTP в секунду в режиме server-close (постоянное соединение с клиентом, закрытие соединения с сервером).

• 243000 запросов HTTP в секунду в режиме постоянных соединений на всём пути.

• 300000 отфильтрованных соединений TCP в секунду (защита от DDoS).

• 160000 запросов HTTPS в секунду в режиме постоянных соединений поверх постоянных соединений TLS.

• 13100 запросов HTTPS в секунду с возобновляемыми соединениями TLS.

• 1300 соединений HTTPS в секунду с повторным согласованием соединений TLS с использованием RSA2048.

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

• Около 8000 одновременных соединений TLS (только со стороны клиента) на GB оперативной памяти, включая память системных буферов.

• Около 5000 одновременных сквозных соединений TLS (с обеих сторон) на GB оперативной памяти, включая память системных буферов.

В более новом тесте многопоточный HAProxy 2.4 на 64-ядерном процессоре ARM Graviton2 в AWS достиг 2 миллионов запросов HTTPS в секунду при времени ответа менее миллисекунды и объёме трафика 100 Gbps:

https://www.haproxy.com/blog/haproxy-forwards-over-2-million-http-requests-per-second-on-a-single-aws-arm-instance/

Полезный практический ориентир: интенсивность запросов уменьшается в 10 раз при переходе от постоянных соединений TLS к возобновлению TLS и от возобновления TLS к повторному согласованию TLS, тогда как при переходе от постоянных соединений HTTP к закрытию соединений HTTP она уменьшается лишь в 3 раза. Ещё один ориентир: высокочастотное ядро с инструкциями AES может обрабатывать около 20 Gbps AES-GCM на ядро.

Также полезно учитывать, что на том же сервере HAProxy способен полностью загрузить:

• около 5-10 серверов статических файлов или кеширующих прокси;

• около 100 антивирусных прокси;

• около 100-1000 серверов приложений в зависимости от используемой технологии.

7 - Выпуски, пакеты и обновления

HAProxy — проект с открытым исходным кодом под лицензией GPLv2. Это означает, что его разрешено распространять при условии предоставления доступа к исходному коду по запросу, особенно если в него внесены изменения.

HAProxy развивается в основной ветке разработки «master» или «mainline», от которой создают новые ветки, когда код считается стабильным. Многие сайты добровольно используют ветки разработки в рабочей среде — чтобы участвовать в проекте или потому, что им нужна самая новая функция. Их обратная связь очень ценна для исправления ошибок и оценки общего качества и стабильности разрабатываемой версии.

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

Номер ветки состоит из двух чисел, разделённых точкой, например «1.6». Начиная с 1.9 ветки с нечётным вторым числом в основном предназначены для существенных технических изменений и опытных пользователей, поскольку в них вероятнее появление ошибок. Они сопровождаются лишь около года, и их нельзя развёртывать там, где невозможно экстренно откатить обновление. Полный номер версии включает один или два номера подверсии, обозначающих уровень исправлений. Например, 1.5.14 — это 14-й корректирующий выпуск ветки 1.5 после выхода 1.5.0. Он содержит 126 исправлений отдельных ошибок, 24 обновления документации и 75 других перенесённых патчей, большинство из которых требовалось для исправления указанных 126 ошибок. Существующую функцию в стабильной ветке нельзя изменять или удалять: это гарантирует безопасность обновлений в пределах одной ветки.

HAProxy доступен из нескольких источников с разной частотой выпусков:

• Официальный сайт сообщества http://www.haproxy.org/ предоставляет исходный код последнего выпуска разработки, всех стабильных выпусков и ночные снимки каждой ветки. Цикл выпусков небыстрый: между стабильными выпусками или снимками разработки проходит несколько месяцев. Там по-прежнему поддерживаются очень старые версии. Всё предоставляется только в виде исходного кода, поэтому полученное оттуда нужно собирать и/или упаковывать заново.

• GitHub https://github.com/haproxy/haproxy/ — зеркало только ветки разработки, обеспечивающее интеграцию с системой отслеживания задач, непрерывной интеграцией и инструментами покрытия кода. Оно предназначено исключительно для участников разработки.

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

• Коммерческие версии с http://www.haproxy.com/ — профессиональные пакеты с поддержкой, собранные для разных операционных систем или поставляемые как готовые устройства. Они основаны на последних стабильных версиях и включают востребованные функции, перенесённые из следующего выпуска. Это лучший вариант для пользователей, которым нужны новейшие функции с надёжностью стабильной ветки, максимально быстрое исправление ошибок либо просто договор поддержки продукта с открытым исходным кодом.

Чтобы убедиться, что используется последняя версия своей ветки, действуйте следующим образом:

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

• Определите источник своей версии HAProxy. Обычно достаточно команды «haproxy -v». Версия разработки выглядит следующим образом: после номера ветки стоит слово «dev».

HAProxy version 2.4-dev18-a5357c-137 2021/05/09 - https://haproxy.org/

Стабильная версия выглядит следующим образом, как и неизменённые стабильные

версии, поставляемые производителями операционных систем:

HAProxy version 1.5.14 2015/07/02

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

вместо даты выпуска:

HAProxy version 1.5.14-e4766ba 2015/07/29

Любой другой формат может указывать на пакет для конкретной системы
с собственным набором патчей. Например, версии HAProxy Enterprise отображаются

в следующем формате (<branch>-<latest commit>-<revision>):

HAProxy version 1.5.0-994126-357 2015/07/02

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

Наконец, версии 2.1 и выше включают строку "Status", указывающую,
безопасно ли использовать версию в рабочей среде и, если да, до какого
срока, а также ссылку на список известных ошибок этой версии.

• Для системных пакетов проверьте репозиторий пакетов или систему обновлений поставщика, чтобы убедиться, что система всё ещё поддерживается и для вашей ветки выпускаются исправления. Для версий сообщества с haproxy.org посетите сайт, проверьте состояние ветки и сравните последнюю версию со своей. Если ваша версия не последняя, её можно обновить. Если ветка больше не сопровождается, вы сильно отстали и должны рассмотреть переход на более новую ветку, внимательно прочитав README.

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

8 - Сопутствующие продукты и альтернативы

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

4.1. HTTP-сервер Apache

Apache — фактический стандарт среди серверов HTTP. Это очень функциональный модульный проект, поддерживающий как выдачу файлов, так и динамическое содержимое. Он может служить фронтендом для серверов приложений, а также проксировать запросы и кешировать ответы. Во всех этих сценариях перед ним обычно требуется балансировщик нагрузки. Apache может работать в разных режимах, одни из которых требуют больше ресурсов, чем другие. Некоторые модули до сих пор требуют более тяжёлой модели с заранее созданными процессами, что мешает Apache эффективно работать с большим числом соединений. В таком случае HAProxy может значительно помочь: он ограничивает число соединений с каждым сервером безопасным значением, заметно ускоряя сервер и сохраняя его ресурсы для приложения.

Apache может извлекать адрес клиента из заголовка X-Forwarded-For с помощью расширения «mod_rpaf». HAProxy автоматически заполняет этот заголовок, если в конфигурации задано «option forwardfor». HAProxy также может хорошо защищать Apache, доступный из интернета, поскольку лучше противостоит многим видам атак DoS.

4.2. NGINX

NGINX — второй фактический стандарт среди серверов HTTP. Как и Apache, он предоставляет широкий набор функций. NGINX построен по модели, сходной с HAProxy, поэтому без труда обрабатывает десятки тысяч одновременных соединений. При использовании в качестве шлюза к приложениям (например, через включённый PHP FPM) часто полезно ограничить число соединений на входе, чтобы снизить нагрузку на приложение PHP. Здесь HAProxy пригодится и как обычный балансировщик нагрузки, и как регулятор трафика, ускоряющий PHP за счёт устранения перегрузки. Кроме того, благодаря событийной архитектуре оба продукта потребляют мало CPU, и их часто легко разместить в одной системе. NGINX поддерживает протокол PROXY от HAProxy, поэтому HAProxy легко передаёт ему сведения о клиентском соединении, необходимые приложению. Некоторые тесты также показали, что при выдаче больших статических файлов согласованное хеширование в HAProxy перед NGINX может повысить долю попаданий в кеш операционной системы, фактически умножая её на число серверных узлов.

4.3. Varnish

Varnish — интеллектуальный кеширующий обратный прокси, который, пожалуй, точнее всего назвать ускорителем веб-приложений. Varnish не реализует SSL/TLS, предпочитая отдавать все ресурсы CPU тому, что умеет лучше всего. Он также поддерживает протокол PROXY от HAProxy, поэтому HAProxy легко развернуть перед Varnish для обработки SSL и балансировки нагрузки с передачей всех необходимых сведений о клиенте. Кроме того, Varnish умеет распаковывать объекты из кеша, если сервер передал их сжатыми, но сам сжатие не выполняет. Если серверы бэкенда не поддерживают сжатие, исходящие данные можно сжимать в HAProxy, хотя делать это на балансировщике редко бывает хорошей идеей, кроме случаев небольшого трафика.

При построении больших кеширующих ферм из нескольких узлов HAProxy может применять согласованное хеширование URL для разумного распределения нагрузки между кеширующими узлами и предотвращения дублирования кеша. Тогда общий размер кеша равен сумме кешей всех узлов. Кроме того, кратковременное кеширование очень маленьких простых объектов в HAProxy иногда позволяет избежать сетевых обменов и снизить нагрузку на CPU как узлов HAProxy, так и Varnish. Это возможно только тогда, когда Varnish никак не обрабатывает эти объекты. Такой подход часто называют «кешем favicon»: иногда он позволяет исключить заметную долю бесполезных запросов к следующему уровню. Однако не включайте длительное кеширование в HAProxy (более нескольких секунд) перед другим кешем: это значительно усложнит устранение неполадок без существенной экономии ресурсов.

4.4. Альтернативы

Linux Virtual Server (LVS или IPVS) — балансировщик нагрузки уровня 4, встроенный в ядро Linux. Он работает на уровне пакетов и обрабатывает TCP и UDP. В большинстве случаев он скорее дополняет HAProxy, чем заменяет его, поскольку совершенно не понимает уровень 7.

Pound — ещё один известный балансировщик нагрузки. Он значительно проще HAProxy и обладает гораздо меньшим числом функций, но для многих простейших конфигураций подходят оба продукта. Автор Pound всегда ставил на первое место возможность аудита кода и стремится сохранять небольшой набор функций. Его архитектура на основе потоков хуже масштабируется при большом числе соединений, но это хороший продукт.

Pen — довольно лёгкий балансировщик нагрузки. Он поддерживает SSL и сохраняет привязку с помощью таблицы фиксированного размера с IP-адресами клиентов. У него есть режим работы с пакетами, позволяющий в определённых пределах поддерживать прямой ответ сервера и UDP. Он рассчитан на небольшие нагрузки: таблица привязок содержит всего 2048 записей.

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

Varnish также балансирует нагрузку между своими серверами бэкенда и поддерживает полноценные проверки работоспособности. Однако привязку сеансов он не реализует, поэтому, как и в случае NGINX, его может быть достаточно для начала, если привязка не нужна. И аналогично, благодаря хорошей совместимости HAProxy и Varnish, HAProxy легко добавить позже, чтобы расширить набор возможностей.

9 - Документация и сообщество

1. Доступная документация

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

• intro.txt (этот документ): здесь представлены основы балансировки нагрузки, HAProxy как продукт, его возможности и ограничения, известные подводные камни, которых следует избегать, некоторые ограничения конкретных ОС, способы получения, развитие проекта, способы убедиться, что используются все известные исправления, обновление, дополнения и альтернативы.

• management.txt : объясняет, как запускать haproxy, управлять им во время выполнения, управлять им на нескольких узлах и выполнять обновления без перерыва в обслуживании.

• configuration.txt : справочное руководство подробно описывает все ключевые слова конфигурации и их параметры. Оно используется, когда требуется изменить конфигурацию.

• coding-style.txt: предназначен для разработчиков, которые хотят предложить проекту свой код. В нём объясняется стиль, которого следует придерживаться при написании кода. Правила не очень строгие, и не вся кодовая база полностью им соответствует, но изменения, слишком сильно от них отклоняющиеся, будут отклонены.

• proxy-protocol.txt: фактическая спецификация протокола PROXY, реализованного в HAProxy и ряде сторонних продуктов.

• security.txt: как сообщить о проблеме безопасности и что считается или не считается уязвимостью.

• README: как собрать HAProxy из исходного кода

5. Контакты

Если требуется связаться с разработчиками или любым участником сообщества по какому-либо вопросу, обычно лучше всего воспользоваться списком рассылки, отправив сообщение на haproxy@formilux.org . Учтите, что список рассылки и его архивы общедоступны, поэтому следует избегать раскрытия конфиденциальной информации. В нём участвует тысяча пользователей с разным уровнем опыта, и даже на самые сложные вопросы обычно удаётся сравнительно быстро найти оптимальный ответ. Предложения тоже приветствуются. Для пользователей, которым сложно пользоваться электронной почтой, доступна платформа Discourse по адресу http://discourse.haproxy.org/ . Однако учитывайте, что вопросы там читает меньше людей и на большинство из них отвечает очень небольшая команда. В любом случае проявляйте терпение и уважение к тем, кто посвящает своё свободное время помощи другим.

Если кажется, что обнаружена ошибка, но уверенности нет, лучше сообщить об этом в список рассылки. Если есть твёрдая уверенность, что обнаружена ошибка, используется актуальная версия своей ветки и уже есть учётная запись GitHub, можно сразу перейти на https://github.com/haproxy/haproxy/ и создать сообщение об ошибке со всеми доступными подробностями. Этот ресурс тоже общедоступен, поэтому не публикуйте информацию, о раскрытии которой впоследствии можно пожалеть. Поскольку система отслеживания ошибок представляет обсуждение в виде очень длинной ветки, не вставляйте очень длинные дампы (несколько сотен строк и более) в текст, а прикладывайте их как вложения.

Если есть основания полагать, что обнаружена проблема безопасности, обратитесь к файлу doc/security.txt. Он объясняет, что считается или не считается уязвимостью HAProxy и как конфиденциально сообщить о настоящей уязвимости. Большинство предполагаемых проблем безопасности оказываются обычными ошибками, о которых лучше сообщать описанным выше способом.

Полный комплект локальных руководств

• Руководство для начинающих
• Руководство по конфигурации
• Руководство по управлению

Происхождение издания

• Издание: HAProxy 3.4.6-66, снимок документации ветки сопровождения
• Последний стабильный выпуск: HAProxy 3.4.6, тег v3.4.6
• Коммит исходного кода: 16acce1dac1d
• Опубликованный комплект проекта: docs.haproxy.org/3.4/
• Локальные копии лицензий: лицензионное уведомление HAProxy и GPLv2

10 - 1. Краткое напоминание об HTTP

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

Когда HAProxy работает в режиме HTTP, и запрос, и ответ полностью анализируются и индексируются. Это позволяет строить критерии сопоставления практически по любым элементам содержимого.

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

Прежде всего, HTTP стандартизован серией RFC, которым HAProxy следует максимально точно:

• RFC 9110: семантика HTTP (объясняет смысл элементов протокола).
• RFC 9111: кеширование HTTP (описывает правила, которым должен следовать кеш HTTP).
• RFC 9112: HTTP/1.1 (представление, правила взаимодействия, безопасность).
• RFC 9113: HTTP/2 (представление, правила взаимодействия, безопасность).
• RFC 9114: HTTP/3 (представление, правила взаимодействия, безопасность).

Кроме того, RFC с 8999 по 9002 определяют транспортный уровень QUIC, используемый протоколом HTTP/3.

1.1. Модель транзакций HTTP

Протокол HTTP основан на транзакциях. Это означает, что каждый запрос приводит ровно к одному ответу. Изначально, в версии 1.0, на соединение приходился один запрос: клиент устанавливал соединение TCP с сервером, отправлял по нему запрос, сервер отвечал, после чего соединение закрывалось. Для нового запроса требовалось новое соединение:

[CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...

В этом режиме, часто называемом «HTTP close», число установок соединений равно числу транзакций HTTP. Поскольку сервер закрывает соединение после ответа, клиенту не нужно знать длину содержимого: он считает ответ завершённым при закрытии соединения. Это также означает, что при обрыве ответа из-за сетевой ошибки клиент мог ошибочно счесть его полным; раньше это иногда приводило к отображению обрезанных изображений.

Транзакционная природа протокола позволила усовершенствовать его, исключив закрытие соединения между двумя последовательными транзакциями. Однако в таком режиме сервер обязан указывать длину содержимого каждого ответа, чтобы клиент не ждал бесконечно. Для этого используется специальный заголовок «Content-length». Этот режим называется «keep-alive» и появился в HTTP/1.1 (его поддерживают некоторые агенты HTTP/1.0), а соединения, повторно используемые между запросами, называются постоянными:

[CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...

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

В этом режиме размер ответа нужно знать заранее, что не всегда возможно для динамически формируемого или сжатого содержимого. Поэтому был реализован другой режим — «chunked mode». Вместо объявления полного размера отправитель сообщает только размер следующего фрагмента ответа, уже находящегося в буфере, и может завершить передачу в любой момент фрагментом нулевого размера. В этом режиме заголовок Content-Length не используется.

Ещё одно улучшение обмена — конвейерный режим. Он по-прежнему использует постоянные соединения, но клиент не ждёт первого ответа, чтобы отправить второй запрос. Это удобно при загрузке большого числа изображений страницы:

[CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...

Очевидно, что устранение сетевой задержки между последовательными запросами может значительно повысить производительность. Многие агенты HTTP некорректно поддерживают конвейерную обработку, поскольку HTTP не позволяет явно связать ответ с соответствующим запросом. Поэтому сервер обязан отвечать строго в порядке получения запросов. На практике после нескольких попыток внедрения в разных клиентах от этого режима полностью отказались из-за ненадёжной работы с некоторыми серверами. Однако серверы обязаны его поддерживать.

Следующее усовершенствование — мультиплексирование, реализованное в HTTP/2 и HTTP/3. В этом режиме несколько транзакций, то есть пар «запрос — ответ», передаются параллельно по одному соединению и продвигаются независимо, каждая со своей скоростью. Для описания таких параллельных обменов в одном соединении протоколы с мультиплексированием ввели понятие потока. Каждому потоку обычно назначается уникальный в рамках соединения идентификатор, по которому обе стороны определяют, куда направлять данные. Клиенты довольно часто запускают множество потоков (до 100, иногда больше) параллельно по одному соединению, позволяя серверу обрабатывать их и отвечать в любом порядке по мере готовности ответов. Главное преимущество мультиплексирования — значительное сокращение числа сетевых обменов и ускорение загрузки страниц в сетях с высокой задержкой. Иногда это заметно на сайтах с большим числом изображений, где все изображения будто загружаются одновременно.

Эти протоколы также повысили эффективность за счёт механизмов сжатия полей заголовков, уменьшающих число передаваемых байтов. Поэтому без соответствующих инструментов их практически невозможно обрабатывать вручную или читать невооружённым глазом, как HTTP/1. По этой причине в литературе, включая этот документ, примеры сообщений HTTP продолжают представлять в синтаксисе HTTP/1 даже для новых версий протокола.

У HTTP/2 есть ограничения архитектуры: например, потеря пакетов затрагивает сразу все потоки. Если клиент слишком долго получает объект, например записывает его на диск, он может замедлить получение и тем самым временно сделать недоступными данные, ожидающие за этим объектом. Это называется блокировкой начала очереди — «head of line blocking», «HoL blocking» или просто «HoL».

HTTP/3 реализован поверх QUIC, который, в свою очередь, работает поверх UDP. QUIC устраняет блокировку начала очереди на транспортном уровне за счёт независимой обработки потоков. При потере данных затронутый поток не влияет на остальные, и все потоки доступны параллельно. QUIC также поддерживает миграцию соединений, но в настоящее время haproxy её не поддерживает.

По умолчанию HAProxy использует режим постоянных соединений: для каждого соединения он обрабатывает запросы и ответы и оставляет соединение открытым, но бездействующим с обеих сторон между окончанием ответа и началом следующего запроса. При получении клиентского соединения HTTP/2 он параллельно обрабатывает все запросы и оставляет соединение в ожидании новых, как обычное постоянное соединение HTTP.

В основном HAProxy поддерживает 3 режима соединений:

• keep alive: обрабатываются все запросы и ответы, а соединения со стороны клиента и сервера сохраняются для новых запросов. Это режим по умолчанию, подходящий для современного веба и современных протоколов HTTP/2 и HTTP/3.

• server close: соединение с сервером закрывается после ответа.

• close: после завершения ответа соединение активно закрывается с обеих сторон.

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

1.2. Терминология

Терминология HAProxy со временем немного менялась вслед за развитием протокола HTTP и способов его использования. Изначально существенных различий между соединением, сеансом, потоком и транзакцией не было. Со временем понятия уточнили в соответствии с современными версиями HTTP, хотя ради исторической совместимости некоторые термины сохранились в конфигурации и интерфейсе командной строки.

Следующие определения относятся к текущей версии HAProxy:

• Соединение: отдельный двунаправленный канал связи между удалённым агентом (клиентом или сервером) и haproxy на самом низком возможном уровне. Обычно это сокет TCP между парой IP-адресов и портов. На клиентской стороне соединения создаются самыми первыми при подключении клиента к haproxy, и правила уровня соединения применяются раньше всех остальных.

• Сеанс: добавляет к соединению контекстные сведения, в том числе информацию транспортного уровня (например, ключи TLS) или переменные. Долгое время этот термин в HAProxy обозначал сквозной обмен HTTP/1.0 между двумя сторонами. Поэтому он сохранился в именах некоторых команд CLI и статистических показателей, хотя теперь они представляют потоки; справка и описания стараются устранить неоднозначность. Термин по-прежнему уместен на сетевом уровне (например, сеансы TCP в операционной системе или через межсетевой экран) и в пользовательских приложениях, не использующих HTTP (например, сеанс telnet или SSH). Его нельзя путать с сеансами приложения, которые хранят полный контекст пользователя в cookie и требуют направления запросов на один сервер.

• Поток: в точности соответствует сквозному двунаправленному обмену на уровне приложения, где могут применяться анализ и преобразования. В HTTP он содержит один запрос и связанный с ним ответ, создаётся при поступлении запроса и завершается по окончании доставки ответа. В этом контексте между таким потоком и потоком мультиплексируемого протокола существует соответствие 1:1. При обмене по TCP на соединение приходится один поток.

• Транзакция: только пара из запроса и связанного с ним ответа. До появления потоков термин использовали вместе с сеансами, но теперь транзакция и поток находятся в отношении 1:1. Главным образом он встречается в области видимости переменных «txn», действующей на протяжении всей транзакции, а значит, и потока.

• Запрос: трафик от клиента к серверу. Термин преимущественно используется в HTTP для указания направления выполнения операций. Он также применяется к операциям TCP, обозначая направление обработки данных. Запросы часто используются в счётчиках как единица трафика или активности. Не каждый запрос получает ответ, например из-за ошибок, но поскольку самопроизвольных ответов без запросов не бывает, запросы остаются подходящей мерой общей активности. В TCP число запросов равно числу соединений.

• Ответ: трафик от сервера к клиенту, а иногда от HAProxy к клиенту, если HAProxy сам формирует ответ, например перенаправление HTTP.

• Служба: обычно внутренняя обработка в HAProxy, не требующая сервера, например страница статистики, кеш или код Lua, реализующий небольшое приложение. Как правило, служба читает запрос, выполняет операции и формирует ответ.

1.3. Запрос HTTP

Сначала рассмотрим следующий запрос HTTP:

Номер    Содержимое
строки
   1     GET /serv/login.php?lang=en&profile=2 HTTP/1.1
   2     Host: www.mydomain.com
   3     User-agent: my small browser
   4     Accept: image/jpeg, image/gif
   5     Accept: image/png

1.3.1. Строка запроса

Строка 1 — это строка запроса. Она всегда состоит из 3 полей:

• Метод: GET.
• URI: /serv/login.php?lang=en&profile=2.
• Метка версии: HTTP/1.1.

Все поля разделяются тем, что стандарт называет LWS — линейными пробельными символами. Обычно это пробелы, но возможны также табуляции либо переводы строки/возвраты каретки с последующими пробелами или табуляциями. Сам метод не может содержать двоеточие (’:’) и состоит только из букв алфавита. Из-за множества комбинаций лучше, чтобы HAProxy сам разбивал строку на части, а не заставлял пользователя писать сложное или неточное регулярное выражение.

URI может иметь несколько форм:

• Относительный URI:

  /serv/login.php?lang=en&profile=2

Это полный URL без части, обозначающей узел. Обычно именно в таком виде
его получают серверы, обратные прокси и прозрачные прокси.

• Абсолютный URI, также называемый URL:

  http://192.168.0.12:8080/serv/login.php?lang=en&profile=2

Он состоит из схемы (имени протокола с последующим '://'), имени или
адреса узла, необязательного двоеточия (':') с номером порта, а затем
относительного URI, начинающегося с первой косой черты ('/') после
адресной части. Обычно такую форму получают прокси, но сервер,
поддерживающий HTTP/1.1, также обязан её принимать.

• Звёздочка (’*’): эта форма разрешена только с методом OPTIONS и не подлежит ретрансляции. Она используется для запроса возможностей следующего узла.

• Сочетание адреса и порта: 192.168.0.12:80. Используется с методом CONNECT для установки туннелей TCP через прокси HTTP, обычно для HTTPS, но иногда и для других протоколов.

В относительном URI выделяют две части. Часть до вопросительного знака называется путём. Обычно это относительный путь к статическим объектам на сервере. Часть после вопросительного знака называется строкой запроса. Она в основном используется в запросах GET к динамическим скриптам и сильно зависит от языка, фреймворка или приложения.

HTTP/2 и HTTP/3 не передают сведения о версии вместе с запросом: предполагается версия используемого протокола, например «HTTP/2». Кроме того, эти протоколы не передают строку запроса целиком, а разбивают её на отдельные поля — псевдозаголовки, имена которых начинаются с двоеточия. HAProxy для удобства собирает их в эквивалентную строку запроса. Поэтому строки запросов в журналах могут немного различаться для HTTP/1.x и HTTP/2 или HTTP/3.

1.3.2. Заголовки запроса

Заголовки начинаются со второй строки. В начале строки находится имя, сразу за ним — двоеточие (’:’). Традиционно после двоеточия добавляют LWS, но это не обязательно. Далее идут значения. Несколько одноимённых заголовков можно объединить в одну строку, разделяя значения запятыми и сохраняя их порядок. Это часто встречается в поле «Cookie:». Заголовок может занимать несколько строк, если последующие строки начинаются с LWS. В примере из 1.3 строки 4 и 5 задают суммарно 3 значения заголовка «Accept:». Наконец, согласно спецификации все LWS в начале и конце заголовка игнорируются и не входят в значение.

Вопреки распространённому заблуждению, имена заголовков нечувствительны к регистру. Их значения также нечувствительны к регистру, если ссылаются на имена других заголовков, как в «Connection:». В HTTP/2 и HTTP/3 имена заголовков всегда передаются в нижнем регистре, что видно в режиме отладки. Внутри HAProxy все имена заголовков приводятся к нижнему регистру, чтобы HTTP/1.x и HTTP/2 или HTTP/3 использовали одно и то же представление, и в таком виде передаются другой стороне. Поэтому запрос HTTP/1.x, введённый с именами в смешанном регистре, доставляется с именами в нижнем регистре.

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

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

Важное примечание:

Как рекомендует RFC7231, HAProxy нормализует заголовки, заменяя переводы
строк внутри них на LWS, чтобы объединить многострочные заголовки.
Это необходимо для корректного анализа и помогает менее совершенным
средствам разбора HTTP работать правильно, не позволяя таким сложным
конструкциям вводить их в заблуждение.

1.4. Ответ HTTP

Ответ HTTP очень похож на запрос HTTP. И тот и другой называют сообщениями HTTP. Рассмотрим следующий ответ:

Номер    Содержимое
строки
   1     HTTP/1.1 200 OK
   2     Content-length: 350
   3     Content-Type: text/html

Особый случай в HTTP — так называемые информационные ответы с кодами состояния 1xx. Они не содержат никакой части ответа, а служат сигнальными сообщениями, например чтобы попросить клиента продолжить отправку запроса. При коде 100 запрошенные сведения содержатся в следующем после информационного сообщении ответа с кодом, отличным от 100. Это означает, что на один запрос может быть отправлено несколько ответов и что такое возможно только при включённых постоянных соединениях (сообщения 1xx появились в HTTP/1.1). HAProxy умеет корректно пересылать и пропускать эти сообщения, обрабатывая лишь следующий ответ с кодом, отличным от 100. Поэтому такие сообщения не записываются в журнал и не преобразуются, если явно не указано иное. Сообщения с кодом 101 означают смену протокола в том же соединении, и HAProxy должен перейти в туннельный режим, как после CONNECT. Заголовок Upgrade в таком случае содержит дополнительные сведения о протоколе, на который переключается соединение.

1.4.1. Строка ответа

Строка 1 — это строка ответа. Она всегда состоит из 3 полей:

• Метка версии: HTTP/1.1.
• Код состояния: 200.
• Причина: OK.

Код состояния всегда состоит из 3 цифр. Первая обозначает общую категорию:

• 1xx = информационное сообщение, которое следует пропустить (например, 100, 101).
• 2xx = OK, далее следует содержимое (например, 200, 206).
• 3xx = OK, далее содержимого нет (например, 302, 304).
• 4xx = ошибка по вине клиента (например, 401, 403, 404).
• 5xx = ошибка по вине сервера (например, 500, 502, 503).

Коды состояния выше 599 запрещено передавать при обмене, хотя некоторые агенты могут записывать их в журналы для обозначения внутренних состояний. Подробное значение всех кодов описано в RFC9110. В HTTP/2 и новее нет метки версии, а код состояния передаётся в псевдозаголовке «:status».

Поле причины служит лишь подсказкой и не разбирается клиентами. В нём может быть что угодно, но принято использовать общеизвестные сообщения. Оно может состоять из одного или нескольких слов, например «OK», «Found» или «Authentication Required». В HTTP/2 и новее этого поля нет и оно не передаётся. При передаче ответа из HTTP/2 или новее клиенту HTTP/1 HAProxy формирует стандартное поле причины, соответствующее коду состояния.

HAProxy может самостоятельно выдавать следующие коды состояния:

Код   Условие / причина
 200  при обращении к странице статистики и при ответе на запросы мониторинга
 301  при перенаправлении, в зависимости от настроенного кода
 302  при перенаправлении, в зависимости от настроенного кода
 303  при перенаправлении, в зависимости от настроенного кода
 307  при перенаправлении, в зависимости от настроенного кода
 308  при перенаправлении, в зависимости от настроенного кода
 400  при некорректном или слишком большом запросе
 401  если для выполнения действия требуется аутентификация
      (при обращении к странице статистики)
 403  если запрос запрещён правилом "http-request deny"
 404  если запрошенный ресурс не найден
 408  если время ожидания запроса истекло до его полного получения
 410  если запрошенный ресурс больше недоступен и впредь доступен не будет
 413  если запрос HTTP/1.0 GET/HEAD/DELETE содержит полезную нагрузку;
      см. также параметр "h1-accept-payload-with-any-method"
 500  если HAProxy сталкивается с невосстановимой внутренней ошибкой,
      например с ошибкой выделения памяти, чего никогда не должно происходить
 501  если HAProxy не может выполнить запрос клиента из-за отсутствия
      поддержки необходимой функции
 502  если сервер возвращает пустой, некорректный или неполный ответ либо
      если правило "http-response deny" блокирует ответ
 503  если нет доступного сервера для обработки запроса либо в ответ на
      запросы мониторинга, соответствующие условию "monitor fail"
 504  если время ожидания ответа истекло до того, как сервер ответил

Приведённые выше ответы с кодами ошибок 4xx и 5xx можно настраивать (см. «errorloc» в разделе 4.2 ). Другие коды состояния можно выдавать намеренно с помощью специальных действий (например, «deny», «return» и «redirect» в разделе 4.3 ).

1.4.2. Заголовки ответа

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

11 - 2. Настройка HAProxy

2.1. Формат файла конфигурации

При настройке HAProxy используются 3 основных источника параметров:

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

Файл конфигурации имеет довольно простой иерархический формат, подчиняющийся нескольким основным правилам:

1. Файл конфигурации — упорядоченная последовательность инструкций.

2. Инструкция — одна непустая строка до первого незащищённого символа "#"
   (решётки).

3. Строка — последовательность токенов, или «слов», разделённых
   незащищёнными пробелами или табуляциями.

4. Первое слово или последовательность слов в строке — одно из ключевых
   слов или сочетаний ключевых слов, перечисленных в этом документе.

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

6. Некоторые ключевые слова открывают секцию, внутри которой поддерживается
   только определённое подмножество ключевых слов.

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

Этого достаточно для создания простого, но надёжного генератора конфигурации, однако недостаточно для надёжного разбора произвольной конфигурации и обработки некоторых особых случаев.

Из этих правил следует несколько выводов. Правила 6 и 7 означают, что ключевые слова, определяющие новую секцию, допустимы везде и не могут иметь другого смысла в какой-либо отдельной секции. Такие ключевые слова всегда состоят из одного слова, а не из последовательности слов. Традиционно следующую за ними секцию называют так же. Например, «секция global» — это часть конфигурации после ключевого слова “global”. Такое обозначение часто используется в сообщениях об ошибках, чтобы указать место, требующее исправления.

Некоторые секции создают внутренний объект или область конфигурации, которую необходимо отличать от других. В этом случае дополнительное слово задаёт имя секции. Для некоторых типов секций имя обязательно. Например, “frontend foo” создаёт секцию типа “frontend” с именем “foo”. Обычно имя относится только к своему типу секций, и две секции разных типов могут иметь одинаковое имя, но это не рекомендуется, поскольку усложняет управление конфигурацией.

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

Правило 1 указывает, что порядок имеет значение. Некоторые ключевые слова создают директивы, которые можно повторять, формируя последовательность правил для применения в заданном порядке. Например, “tcp-request” позволяет чередовать правила “accept” и “reject” с разными критериями. Поэтому средство обработки конфигурации при редактировании файла обязано сохранять порядок элементов внутри секции. Порядок самих секций обычно неважен, кроме секции global, которая должна находиться перед остальными, но при необходимости может повторяться. Кроме того, некоторым создаваемым объектам, например прокси, автоматически назначаются идентификаторы, которые меняются при перестановке секций. Эти идентификаторы встречаются, например, в статистике. В приведённой ниже конфигурации “foo” получит меньший идентификатор, чем “bar”. Если поменять секции местами, соотношение изменится:

listen foo
    bind :80

listen bar
    bind :81

Согласно правилам 2 и 3, пустые строки, пробелы, табуляции и комментарии после незащищённого символа “#” не входят в конфигурацию: они служат только разделителями. Поэтому следующие конфигурации полностью эквивалентны:

    global#this is the global section
daemon#daemonize
    frontend         foo
mode             http   # or tcp

и:

global
    daemon

# this is the public web frontend
frontend foo
    mode http

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

Табуляция удобна для отступов, но плохо переносится при копировании и вставке. Если вместо неё используются пробелы, рекомендуется ограничиться небольшим числом (от 2 до 4), чтобы редактирование на месте не становилось обременительным в простых редакторах без автоматических отступов.

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

2.2. Кавычки и экранирование

В современных конфигурациях некоторые аргументы требуют символов, которые раньше использовались только как разделители. Для этого HAProxy поддерживает экранирование обратной косой чертой (’\’) перед нужным символом, слабое цитирование двойными кавычками ("") вокруг текста и сильное цитирование одинарными кавычками (’’).

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

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

Вне кавычек специальный символ экранируют обратной косой чертой (’\’), стоящей перед ним:

\    пробел, который следует отличать от разделителя
\#   решётка, которую следует отличать от начала комментария
\\   обратная косая черта
\'   одинарная кавычка, которую следует отличать от границы сильного цитирования
\"   двойная кавычка, которую следует отличать от границы слабого цитирования

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

\n   перевод строки (LF, символ \x0a или десятичный код ASCII 10)
\r   возврат каретки (CR, символ \x0d или десятичный код ASCII 13)
\t   табуляция (символ \x09 или десятичный код ASCII 9)
\xNN символ с шестнадцатеричным кодом ASCII NN (например, \x0a для LF).

Для слабого цитирования защищаемый символ или последовательность символов заключают в двойные кавычки (""). Это предотвращает интерпретацию следующих символов:

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

#    решётка как начало комментария

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

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

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

  Символ     |  Без кавычек  |  В двойных кавычках         |  В одинарных
  -----------+---------------+-----------------------------+-----------------
    <TAB>    |  \<TAB>, \x09 |  "<TAB>", "\<TAB>", "\x09"  |  '<TAB>'
  -----------+---------------+-----------------------------+-----------------
    <LF>     |  \n, \x0a     |  "\n", "\x0a"               |
  -----------+---------------+-----------------------------+-----------------
    <CR>     |  \r, \x0d     |  "\r", "\x0d"               |
  -----------+---------------+-----------------------------+-----------------
    <SPC>    |  \<SPC>, \x20 |  "<SPC>", "\<SPC>", "\x20"  |  '<SPC>'
  -----------+---------------+-----------------------------+-----------------
    "        |  \", \x22     |  "\"", "\x22"               |  '"'
  -----------+---------------+-----------------------------+-----------------
    #        |  \#, \x23     |  "#", "\#", "\x23"          |  '#'
  -----------+---------------+-----------------------------+-----------------
    $        |  $, \$, \x24  |  "\$", "\x24"               |  '$'
  -----------+---------------+-----------------------------+-----------------
    '        |  \', \x27     |  "'", "\'", "\x27"          |
  -----------+---------------+-----------------------------+-----------------
    \        |  \\, \x5c     |  "\\", "\x5c"               |  '\'
  -----------+---------------+-----------------------------+-----------------

Пример:

# those are all strictly equivalent:
log-format %{+Q}o\ %t\ %s\ %{-Q}r
log-format "%{+Q}o %t %s %{-Q}r"
log-format '%{+Q}o %t %s %{-Q}r'
log-format "%{+Q}o %t"' %s %{-Q}r'
log-format "%{+Q}o %t"' %s'\ %{-Q}r

В одном особом случае может потребоваться второй уровень цитирования или экранирования. Некоторые ключевые слова принимают аргументы в круглых скобках, иногда разделённые запятыми. Обычно это целые числа или предопределённые слова. Однако для произвольных строк может потребоваться дополнительный уровень экранирования, чтобы отличить символы самого аргумента от разделителей аргументов. Типичный пример — преобразователь “regsub”, принимающий регулярное выражение. Если в нём нужна закрывающая круглая скобка, её необходимо отдельно заключить в кавычки.

Анализатор аргументов ключевых слов обрабатывает кавычки точно так же, как анализатор верхнего уровня, за исключением того, что последовательности \#, \$ и \xNN не обрабатываются. Менее очевидно то, что используемые внутри разделители сначала нужно экранировать или заключить в кавычки, чтобы они не были обработаны на верхнем уровне.

Рассмотрим пример с преобразователем “regsub”, принимающим 3 аргумента: регулярное выражение, строку замены и набор флагов:

# replace all occurrences of "foo" with "blah" in the path:
http-request set-path %[path,regsub(foo,blah,g)]

Здесь специальные кавычки не требовались. Но для замены “foo” или “bar” на “blah” нужно регулярное выражение “(foo|bar)”. Нельзя написать так:

http-request set-path %[path,regsub((foo|bar),blah,g)]

поскольку строку требуется разделить так:

    http-request set-path %[path,regsub((foo|bar),blah,g)]
                                       |---------|----|-|
                                 arg1 _/         /    /
                                 arg2 __________/    /
                                 arg3 ______________/

но на самом деле передаётся строка между открывающей и закрывающей скобками, затем мусор:

    http-request set-path %[path,regsub((foo|bar),blah,g)]
                                       |--------|--------|
                        arg1=(foo|bar _/        /
                    лишние символы    _________/

Кажется, достаточно заключить закрывающую скобку в кавычки. Однако это не сработает: как сказано выше, анализатор верхнего уровня обработает кавычки ещё до разбора этого слова:

http-request set-path %[path,regsub("(foo|bar)",blah,g)]
------------ -------- ----------------------------------
   word1       word2    word3=%[path,regsub((foo|bar),blah,g)]

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

    http-request set-path %[path,regsub(\"(foo|bar)\",blah,g)]
    ------------ -------- ------------------------------------
       word1       word2    word3=%[path,regsub("(foo|bar)",blah,g)]
                                                |---------||----|-|
                                arg1=(foo|bar) _/          /    /
                                    arg2=blah  ___________/    /
                                        arg3=g _______________/

Другой подход заключается в использовании одинарных кавычек снаружи всей строки и двойных кавычек внутри (таким образом, двойные кавычки не удаляются повторно):

    http-request set-path '%[path,regsub("(foo|bar)",blah,g)]'
    ------------ --------  ----------------------------------
       word1       word2    word3=%[path,regsub("(foo|bar)",blah,g)]
                                                |---------||----|-|
                                arg1=(foo|bar) _/          /    /
                                          arg2 ___________/    /
                                          arg3 _______________/

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

    http-request set-path '%[path, regsub("(foo|bar)", blah, g)]'
    ------------ --------  --------------------------------------
       word1       word2    word3=%[path, regsub("(foo|bar)", blah, g)]
                                        |--------|---------||-----|--|
                  преобразователь=" regsub" _/        /         /   /
                                    arg1=(foo|bar) _/         /   /
                                     arg2=" blah" ___________/   /
                                        arg3=" g" ______________/

Из-за пробелов вокруг запятых эти пробелы стали частью полей. Поэтому преобразователь " regsub", начинающийся с пробела, не будет найден, что вызовет ошибку. Менее заметная проблема — строка замены " blah" добавит пробел в результат. Практическое правило: никогда не вставлять в выражения ненужные пробелы.

При использовании регулярных выражений может возникнуть ситуация, когда символ доллара (’$’) присутствует в выражении или используется обратный слеш (’\’) в строке замены. В таком случае эти символы будут обработаны внутри двойных кавычек, поэтому предпочтительны одинарные кавычки (или двойное экранирование). Пример:

    http-request set-path '%[path,regsub("^/(here)(/|$)","my/\1",g)]'
    ------------ --------  -----------------------------------------
       word1       word2    word3=%[path,regsub("^/(here)(/|$)","my/\1",g)]
                                                |-------------| |-----||-|
                              arg1=(here)(/|$) _/               /      /
                                    arg2=my/\1 ________________/      /
                                          arg3 ______________________/

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

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

http-request set-var(txn.foo) str("\\'foo\\'")
http-request set-var(txn.foo) str(\"\'foo\'\")
http-request set-var(txn.foo) str(\\\'foo\\\')

При сомнениях начните с варианта без кавычек. Затем заключите в одинарные или двойные кавычки аргументы, которым нужна запятая или закрывающая скобка, и при наличии в строке знака доллара или обратной косой черты предусмотрите экранирование этих кавычек обратной косой чертой. Это похоже на двойное экранирование команды, передаваемой “eval” в оболочке Bourne. Разработчикам API, вероятно, удобнее заключать каждый аргумент в экранированные кавычки независимо от его содержимого. Для пользователей, вероятно, более читаема конфигурация с одинарными кавычками вокруг всего выражения и двойными вокруг каждого аргумента.

2.3. Переменные окружения

В конфигурации HAProxy поддерживаются переменные окружения. Они интерпретируются только внутри двойных кавычек, а их значения подставляются при разборе конфигурации. Перед именем переменной должен стоять знак доллара ("$"); само имя можно заключить в фигурные скобки ("{}"), как в оболочке Bourne. Имена могут содержать буквы, цифры и знак подчёркивания ("_"), но их не следует начинать с цифры. Если переменная содержит несколько значений, разделённых пробелами, их можно подставить как отдельные аргументы: для этого переменную заключают в фигурные скобки и добавляют суффикс ‘[*]’ перед закрывающей скобкой. Также можно задать значение по умолчанию для случая, когда переменная не определена: его добавляют после имени переменной через дефис ‘-’. Значение по умолчанию заменяет только отсутствующую переменную, а не переменную с пустым значением.

Пример:

bind "fd@${FD_APP1}"

log "${LOCAL_SYSLOG-127.0.0.1}:514" local0 notice  # send to local server

user "$HAPROXY_USER"

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

• доступна: переменную можно использовать в конфигурации — подставить её значение либо использовать её в условных блоках или предикатах, чтобы включать или отключать фрагменты конфигурации, как описано в разделе 2.4 «Условные блоки».

• изменяема: переменную можно переопределить или удалить в конфигурации с помощью ключевых слов “setenv”/“unsetenv”.

• выводится: переменная присутствует в выводе команды CLI “show env”, описанной в разделе 9.3 «Команды сокетов Unix» руководства по управлению.

Также есть две подкатегории — главный и рабочий процессы, обозначенные в таблице ниже соответственно ‘M’ и ‘W’. Они показывают различия между процессами при запуске HAProxy в режиме master-worker.

• главный процесс: переменная задана и доступна в главном процессе. Она отображается в выводе “show env” интерфейса CLI главного процесса и может использоваться в условных блоках или директивах для включения специальных настроек этого процесса (см. примеры в разделе 2.4 «Условные блоки»).

• рабочий процесс: переменная задана и доступна в рабочем процессе. Она отображается в выводе “show env” интерфейса CLI рабочего процесса или “@1 show env” интерфейса CLI главного процесса. От неё также могут зависеть параметры рабочего процесса (см. примеры в разделе 2.4 «Условные блоки»).

В автономном режиме, без параметра “-W” и ключевого слова “master-worker”, процесс ведёт себя как рабочий, но переменные “HAPROXY_MASTER_CLI” и “HAPROXY_MWORKER” не определены.

Некоторые переменные помечены как недоступные и неизменяемые:

• HAPROXY_CFGFILES
• HAPROXY_MWORKER
• HAPROXY_CLI
• HAPROXY_MASTER_CLI
• HAPROXY_LOCALPEER

При разборе конфигурации их значения не определены: они устанавливаются позднее, на этапе инициализации. Поэтому рекомендуется не использовать эти переменные в условных блоках и не ссылаться на них в директивах “setenv”/“resetenv”/“unsetenv” секции global.

Таблица ниже содержит краткое описание состояния каждой переменной для различных режимов работы:

  +---------------------------+---------+------------+-----------+
  |        Переменная         |Доступна | Изменяема  | Выводится |
  |                           +---------+------------+-----------+
  |                           |  M | W  |   M  |  W  |  M  |  W  |
  +---------------------------+----+----+------+-----+-----+-----+
  | HAPROXY_STARTUP_VERSION   |  X | X  |      |     |  X  |  X  |
  | HAPROXY_BRANCH            |  X | X  |      |     |  X  |  X  |
  | HAPROXY_CFGFILES          |    |    |      |     |  X  |  X  |
  | HAPROXY_MWORKER           |    |    |      |     |  X  |  X  |
  | HAPROXY_CLI               |    |    |      |     |     |  X  |
  | HAPROXY_MASTER_CLI        |    |    |      |     |  X  |     |
  | HAPROXY_LOCALPEER         |    | X  |      |     |     |  X  |
  | HAPROXY_HTTP_LOG_FMT      |    | X  |      |  X  |     |     |
  | HAPROXY_HTTP_CLF_LOG_FMT  |    | X  |      |  X  |     |     |
  | HAPROXY_HTTPS_LOG_FMT     |    | X  |      |  X  |     |     |
  | HAPROXY_TCP_LOG_FMT       |    | X  |      |  X  |     |     |
  | HAPROXY_TCP_CLF_LOG_FMT   |    | X  |      |  X  |     |     |
  | HAPROXY_KEYLOG_FC_LOG_FMT |    | X  |      |  X  |     |     |
  | HAPROXY_KEYLOG_BC_LOG_FMT |    | X  |      |  X  |     |     |
  +---------------------------+----+----+------+-----+-----+-----+

Речь идёт о следующих переменных:

• HAPROXY_LOCALPEER: определяется при запуске процесса и содержит имя локального однорангового узла. См. “-L” в руководстве по управлению.

• HAPROXY_CFGFILES: список файлов конфигурации, загруженных HAProxy, разделённых точками с запятой. Полезен, если при запуске был указан каталог.

• HAPROXY_HTTP_LOG_FMT: содержит значение формата журнала HTTP по умолчанию, описанного в разделе 8.2.3 “Формат журнала HTTP”. Позволяет переопределить формат журнала по умолчанию без копирования всего исходного определения.

• HAPROXY_HTTP_CLF_LOG_FMT: содержит значение формата журнала HTTP CLF по умолчанию, описанного в разделе 8.2.3 “Формат журнала HTTP”. Позволяет переопределить формат журнала по умолчанию без копирования всего исходного определения.

Пример:

# Add the rule that gave the final verdict to the log
log-format "${HAPROXY_TCP_LOG_FMT} lr=%[last_rule_file]:%[last_rule_line]"

• HAPROXY_HTTPS_LOG_FMT: аналогична HAPROXY_HTTP_LOG_FMT, но содержит формат журнала HTTPS, описанный в разделе 8.2.4 «Формат журнала HTTPS».

• HAPROXY_TCP_LOG_FMT: аналогична HAPROXY_HTTP_LOG_FMT, но содержит формат журнала TCP, описанный в разделе 8.2.2 «Формат журнала TCP».

• HAPROXY_TCP_CLF_LOG_FMT: аналогична HAPROXY_HTTP_CLF_LOG_FMT, но содержит формат журнала TCP CLF, описанный в разделе 8.2.2 «Формат журнала TCP».

• HAPROXY_KEYLOG_FC_LOG_FMT: содержит формат журнала ключей для соединения TLS со стороны фронтенда, то есть клиента. Записи ключей разделяются переводами строк, поэтому формат может оказаться несовместимым с используемым сервером syslog. Требуется “tune.ssl.keylog on”.

• HAPROXY_KEYLOG_BC_LOG_FMT: аналогична HAPROXY_KEYLOG_FC_LOG_FMT, но относится к соединению TLS со стороны бэкенда, то есть сервера. Записи ключей разделяются переводами строк, поэтому формат может оказаться несовместимым с используемым сервером syslog. Требуется “tune.ssl.keylog on”.

• HAPROXY_MWORKER: В режиме master-worker, эта переменная устанавливается в 1.

• HAPROXY_CLI: настроенные адреса слушателей сокета статистики каждого процесса, эти адреса разделяются точками с запятой.

• HAPROXY_MASTER_CLI: В режиме master-worker, адреса слушателей главного CLI, разделённые точками с запятой.

• HAPROXY_STARTUP_VERSION: содержит версию, использованную при запуске. В режиме master-worker это версия, с которой запущен главный процесс, даже после обновления исполняемого файла и перезагрузки конфигурации.

• HAPROXY_BRANCH: содержит версию ветки HAProxy (например, “2.8”). В ней не содержится полная версия. Может быть полезна при миграции, если ресурсы (например, карты или сертификаты) находятся в пути, содержащем номер ветки.

Кроме того, некоторые псевдопеременные вычисляются внутри HAProxy и могут использоваться как обычные переменные. Их имена всегда начинаются с точки (’.’); только в именах псевдопеременных разрешена точка. Текущий список псевдопеременных:

• .FILE: имя разбираемого в данный момент файла конфигурации.

• .LINE: номер разбираемой в данный момент строки файла конфигурации, начиная с единицы.

• .SECTION: имя разбираемой в данный момент секции, её тип, если имя отсутствует (например, “global”), либо пустая строка до первой секции.

Значения этих переменных вычисляются в месте их разбора. Например, если переменная “.LINE” используется в директиве “log-format” секции defaults, номер строки вычисляется до разбора и компиляции этой директивы “log-format”. Поэтому последующие прокси будут использовать тот же номер строки.

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

2.4. Условные блоки

Иногда удобно включать или отключать произвольные части конфигурации по условию: например, SSL, шифры или слушатели для предэксплуатационной среды без изменения конфигурации, либо адаптировать синтаксис для двух версий HAProxy во время миграции. HAProxy предоставляет набор директив с поддержкой вложенности, похожих на директивы препроцессора. Они позволяют включать или игнорировать блоки текста. Каждая директива должна находиться на отдельной строке и действует на следующие за ней строки. Две директивы принимают выражение, остальные переключаются на альтернативный блок или завершают текущий уровень. Для условных блоков определены следующие 4 директивы:

• .if <condition>
• .elif <condition>
• .else
• .endif

Директива “.if” открывает новый уровень вложенности, “.elif” и “.else” остаются на том же уровне, а “.endif” закрывает уровень. Каждой “.if” должна соответствовать завершающая “.endif”. Директива “.elif” допустима только после “.if” или “.elif”; длина цепочки “.elif” не ограничена. На каждую “.if” допускается только одна “.else”, которая должна находиться после “.if” или последней “.elif” этого блока.

Комментарии могут быть размещены на той же строке, если необходимо, после ‘#’, они будут проигнорированы. Директивы токенизируются так же, как и другие директивы конфигурации, и, следовательно, возможно использование переменных среды в условиях.

Условия также можно вычислить при запуске с параметром -cc. См. «3. Запуск HAProxy» в руководстве по управлению.

Условия могут быть либо пустой строкой (в этом случае возвращается ложь), либо выражением, состоящим из любой комбинации:

• целое число ноль (‘0’), которое всегда возвращает “false”
• ненулевое целое число, например ‘1’, которое всегда возвращает “true”.
• предикат, за которым могут следовать аргументы в круглых скобках.
• условие в круглых скобках ‘(’ и ‘)’
• восклицательный знак (’!’) перед любым из перечисленных непустых элементов, отрицающий его значение.
• выражения, объединённые логическим И (’&&’); они вычисляются слева направо, пока одно из них не вернёт ложь
• выражения, объединённые логическим ИЛИ (’||’); они вычисляются справа налево, пока одно из них не вернёт истину

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

.if defined( HAPROXY_MWORKER )

проверит наличие переменной " HAPROXY_MWORKER " (с пробелами), и это:

.if streq("$ENABLE_SSL",     1)

сравнивает переменную окружения “ENABLE_SSL” со значением " 1" (с одним ведущим пробелом). Причина заключается в том, что строка сначала разбивается на слова так:

   .if streq("$ENABLE_SSL",     1)
  |---|--------------------|   |--|
    1           2               3

затем обрабатываются двойные кавычки и подставляется значение переменной окружения “$ENABLE_SSL”, например ENABLE_SSL=0. Наконец, слова вновь объединяются в строку с одним пробелом между ними:

   .if streq(0, 1)
  |---|-------|--|
    1     2     3

и только после этого строка разбирается как единое выражение. Пробел между запятой и “1” остаётся частью значения аргумента, поэтому аргумент равен " 1":

   .if streq(0, 1)
  |---|-----|-|--|
    \    \    \  \_ аргумент2: " 1"
     \    \    \___ аргумент1: "0"
      \    \_______ функция: "streq"
       \___________ директива: ".if"

Здесь видно, что даже если ENABLE_SSL был равен “1”, это не совпадало с " 1", поскольку строка отличалась одним пробелом.

Примечание: как объяснено в секции “2.2. Цитирование и экранирование”, хорошим правилом является никогда не вставлять ненужные пробелы внутри выражений.

Как и в других языках, оператор И имеет приоритет над ИЛИ, поэтому “A && B || C && D” вычисляется как “(A && B) || (C && D)”.

Список поддерживаемых на данный момент предикатов следующий:

• awslc_api_atleast(<ver>): возвращает true, если текущее значение awslc API не старше <ver>, иначе false. Пример: awslc_api_atleast(35)

• awslc_api_before(<ver>): возвращает true, если текущий номер awslc API строго старше <ver> иначе false. Пример: awslc_api_before(26)

• defined(<name>) : возвращает true, если переменная среды <name> существует, независимо от её содержимого

• feature(<name>) : возвращает true, если возможность <name> отмечена как доступная в списке, выводимом командой “haproxy -vv”, то есть <name> стоит после знака ‘+’.

• openssl_version_atleast(<ver>): возвращает true, если текущая версия OpenSSL не старше <ver>, в противном случае — false. Библиотеки, такие как LibreSSL, AWS-LC и WolfSSL, также предоставляют псевдо-версию OpenSSL. Пример:

ssllib_name_startswith(OpenSSL) && openssl_version_atleast(1.1.1)

• openssl_version_before(<ver>): возвращает true, если текущая версия OpenSSL строго старше <ver>, иначе false. Библиотеки, такие как LibreSSL, AWS-LC и WolfSSL, также предоставляют псевдоверсию OpenSSL. Пример: openssl_version_before(3.5.0)

• ssllib_name_startswith(<name>) : возвращает true, если имя библиотеки SSL, с которой скомпонован HAProxy, начинается с <name>. Пример: ssllib_name_startswith(wolfSSL)

• streq(<str1>,<str2>) : возвращает true только в случае равенства двух строк

• strneq(<str1>,<str2>): возвращает true только если две строки различаются

• strstr(<str1>,<str2>): возвращает true только если вторая строка содержится в первой.

• version_atleast(<ver>): возвращает true, если текущая версия HAProxy не старше <ver>, в противном случае — false. Синтаксис версии совпадает с тем, что показано командой “haproxy -v”, отсутствующие компоненты считаются равными нулю.

• version_before(<ver>): возвращает true, если текущая версия HAProxy строго старше <ver> в противном случае — false. Синтаксис версии соответствует тому, что показывает “haproxy -v” и отсутствующие компоненты считаются нулевыми.

• enabled(<opt>) : возвращает true, если параметр <opt> включён во время работы. Поддерживается только часть параметров:

POLL, EPOLL, KQUEUE, EVPORTS, SPLICE,
GETADDRINFO, REUSEPORT, FAST-FORWARD,
SERVER-SSL-VERIFY-NONE

Пример:

# 1. HAPROXY_MWORKER variable is set automatically by HAProxy in master and
# in worker process environments (see HAProxy variables matrix from
# 2.3. Environment variables). Its presence enables an additional listener.

global
  master-worker

.if defined(HAPROXY_MWORKER)
    listen mwcli_px
       bind :1111
       ...
.endif

# 2. HAPROXY_BRANCH is set automatically by HAProxy in master and in worker
# process environments (see HAProxy variables matrix from 2.3. Environment
# variables). We check HAPROXY_BRANCH value and conditionally enable
# mworker-max-reloads parameter.

global
  master-worker

.if streq("$HAPROXY_BRANCH",3.1)
     mworker-max-reloads 5
.endif

# 3. Some arbitrary environment variables are set by user in the global
# section. If HAProxy is started in master-worker mode, they are presented in
# master and in worker process environments. We check values of these
# variables and conditionally enable ports 80 and 443. Environment variables
# checks can be mixed with features and version checks.

global
  setenv WITH_SSL yes
  unsetenv SSL_ONLY

.if strneq("$SSL_ONLY",yes)
       bind :80
.endif

.if streq("$WITH_SSL",yes)
  .if feature(OPENSSL)
       bind :443 ssl crt ...
  .endif
.endif

.if feature(OPENSSL) && (streq("$WITH_SSL",yes) || streq("$SSL_ONLY",yes))
       bind :443 ssl crt ...
.endif

.if version_atleast(2.4-dev19)
    profiling.memory on
.endif

.if !feature(OPENSSL)
    .alert "SSL support is mandatory"
.endif

Четыре другие директивы предоставляются для отображения некоторых состояний:

• .diag “message” : выводит сообщение только в режиме диагностики (-dD)
• .notice “message” : выводит сообщение с уровнем NOTICE
• .warning “message”: выводит сообщение с уровнем WARNING
• .alert “message” : выводит сообщение с уровнем ALERT

Сообщения уровня WARNING могут помешать запуску процесса, если включён “zero-warning”. Сообщения уровня ALERT всегда приводят к неустранимой ошибке. Эти директивы позволяют выявлять неподходящие условия и давать пользователю рекомендации.

Пример:

.if "${A}"
  .if "${B}"
     .notice "A=1, B=1"
  .elif "${C}"
     .notice "A=1, B=0, C=1"
  .elif "${D}"
     .warning "A=1, B=0, C=0, D=1"
  .else
     .alert "A=1, B=0, C=0, D=0"
  .endif
.else
     .notice "A=0"
.endif

.diag "WTA/2021-05-07: replace 'redirect' with 'return' after switch to 2.4"
      http-request redirect location /goaway if ABUSE

2.5. Формат времени

Некоторые параметры включают значения, представляющие время, такие как тайм-ауты. Эти значения обычно выражаются в миллисекундах (если не указано иное), но могут быть выражены в любой другой единице путём добавления этой единицы к числовому значению. Важно учитывать это, поскольку оно не будет повторяться для каждого ключевого слова. Поддерживаемые единицы:

• us: микросекунды. 1 микросекунда = 1/1000000 секунды
• ms: миллисекунды. 1 миллисекунда = 1/1000 секунды. Это значение по умолчанию.
• s : секунды. 1s = 1000ms
• m : минуты. 1m = 60s = 60000ms
• h : часы. 1h = 60m = 3600s = 3600000ms
• d : дни. 1d = 24h = 1440m = 86400s = 86400000ms

2.6. Формат размера

Некоторые параметры включают значения, представляющие объём, такие как ограничения пропускной способности. Эти значения обычно выражаются в байтах (кроме случаев, когда это явно указано иначе), но могут быть выражены в любой другой единице путём добавления суффикса единицы к числовому значению. Важно учитывать это, поскольку оно не будет повторяться для каждого ключевого слова. Поддерживаемые единицы являются нечувствительными к регистру:

• k: килобайты. 1 килобайт = 1024 байт
• m: мегабайты. 1 мегабайт = 1048576 байт
• g: гигабайты. 1 гигабайт = 1073741824 байт

Оба формата времени и объёма требуют целых чисел; дробная запись не допускается.

2.7. Формат имён карт отображения и ACL

Возможно использовать список шаблонов для карт или ACL. Список шаблонов определяется его именем и может использоваться в разных местах конфигурации. Списки шаблонов делятся на три категории в зависимости от формата имени:

• Списки шаблонов из обычных файлов: вариант по умолчанию. В качестве имени используется абсолютный или относительный путь к файлу. Файл должен существовать, иначе возникает ошибка, но может быть пустым. Также можно указать префикс “file@”, который не входит в имя списка. Имя файла с префиксом и без него обозначает один и тот же список шаблонов.

• Списки шаблонов из необязательных файлов: перед именем файла должен стоять префикс “opt@”. Наличие файла необязательно. Если он существует, его содержимое загружается; отсутствие файла не вызывает ошибки. Префикс не входит в имя списка, поэтому при одинаковом имени обычный и необязательный файлы обозначают один и тот же список шаблонов.

• Списки шаблонов, основанные на виртуальных файлах: имя служит лишь идентификатором. Оно не ссылается на какой-либо файл. Обязательно использовать префикс “virt@”. Он входит в идентификатор. Следовательно, такие списки не могут смешиваться с другими типами списков.

Виртуальные файлы полезны, когда шаблоны полностью управляются динамически и отсутствуют при запуске и перезагрузке конфигурации. В тех же условиях можно использовать необязательные файлы, но в них можно сохранять шаблоны, например внешним скриптом на основе команды CLI “show map”. Это позволяет сохранить шаблоны при перезагрузке конфигурации.

Примечание: хотя это маловероятный случай, обычный файл с именем, начинающимся с “file@”, “opt@” или “virt@”, нельзя загрузить без явного добавления “./” перед именем, например “file@./virt@map”.

2.8. Переменные

В конфигурации HAProxy переменные можно использовать в функциях извлечения образца, преобразователях, строках log-format и действиях TCP/HTTP. Можно определять переменные уровня процесса, доступные глобально на протяжении всей его работы. Другие переменные имеют меньший срок жизни. Как и в сценариях оболочки, переменная — это символическое имя области памяти. Размер переменных не ограничен, память для них выделяется динамически. Поэтому переменные необходимо использовать осторожно, особенно при интенсивном обращении к ним. Максимальный объём занимаемой ими памяти можно ограничить глобальными параметрами “tune.vars”.

Переменные должны обозначаться в формате “<scope>.<name>”. <scope> — одно слово, указывающее срок жизни переменной. Часть <name> может содержать только символы ‘a-z’, ‘A-Z’, ‘0-9’ и ‘_’. Имя уникально в пределах области видимости, но одинаковые имена в разных областях допустимы и обозначают разные переменные. Поддерживаются следующие области видимости:

• proc : переменные, существующие на протяжении всей работы процесса и доступные глобально. С переменными “proc” можно работать через CLI с помощью команд “get var” и “set var”. Их также можно задавать в секциях “global” директивами “set-var” и “set-var-fmt”.

• sess : для переменных, известных на протяжении всего жизненного цикла сессии. Переменные “sess” являются приватными для сессии, недоступными снаружи и не используются совместно с другими сессиями.

• txn : для переменных, известных на протяжении всего жизненного цикла транзакции. Переменные “txn” являются приватными для потока, недоступными снаружи и не используются совместно с другими потоками.

• req : для переменных, известных в процессе обработки запроса для конкретного потока. Переменные “req” доступны с момента создания потока и до первой попытки соединения с сервером. Они являются приватными для потока, недоступными снаружи и не используются совместно с другими потоками. Между переменными “req” и “res” нет пересечений вовсе.

• res : для переменных, известных во время обработки ответа для конкретного потока. Переменные “res” видны с первой попытки соединения с сервером и до уничтожения потока. Они являются приватными для потока, недоступными снаружи и не используются совместно с другими потоками. Между переменными “req” и “res” нет никакого пересечения.

• check: для переменных, известных во время выполнения проверки работоспособности. Переменные “check” являются приватными для проверки работоспособности, недоступными снаружи и не используются совместно с другими проверками работоспособности. Их можно задавать с помощью специализированных директив “tcp-check” или “http-check”.

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

• psess: то же, что и “sess”, но с использованием сессии родительского потока, если такой имеется.

• ptxn : то же, что и “txn”, но с использованием транзакции родительского потока, если такой имеется.

• preq : то же, что и “req”, но с использованием родительского потока, если такой имеется. Переменные “preq” доступны только во время обработки запроса родительского потока.

• pres : то же, что и “res”, но с использованием родительского потока, если такой имеется. Переменные “pres” доступны только во время обработки ответа родительского потока.

Области, отражающие родительский поток, доступны с момента определения потока. В большинстве случаев отсутствует родительский поток. Однако, если это применимо, такой факт будет явно указан. В настоящее время возможно только извлечение значений переменных, определённых в области родительского потока. Установка или удаление таких переменных невозможны. Обычно дочерний поток выполняет обработку для родительского потока в определённый момент и останавливает его выполнение до завершения операции. Это означает, что родительский поток может быть остановлен на этапе обработки запроса или ответа. В связи с этим, определённые области недоступны из дочернего потока. Например, если запрос подвергается анализу в дочернем потоке, дочерний поток не найдёт переменные в области “pres”, поскольку родительский поток не обрабатывает ответ, и, следовательно, не имеет переменных в его области “res”.

Содержимое переменной — результат вычисления выражения извлечения образца; переменная наследует тип результата этого выражения. При использовании переменной её тип должен соответствовать выполняемой операции. Например, для успешного применения преобразователя “add()” строковое значение должно преобразовываться в корректное целое число. Это особенно важно при сравнении переменных со статическими значениями: необходимо выбрать правильный метод сопоставления.

2.9. Форматы адресов

Некоторым директивам, в том числе “bind”, “server”, “nameserver” и “log”, требуется адрес.

Адресом может быть имя узла, адрес IPv4, адрес IPv6 или ‘’. Значение ‘’ эквивалентно специальному адресу “0.0.0.0” и в директивах “bind” или “dgram-bind” позволяет слушать все адреса IPv4 системы. Эквивалент для IPv6 — ‘::’.

В зависимости от директивы за IP-адресом следует порт или диапазон портов. Для ‘bind’ он обязателен, для ‘server’ — нет.

Адрес также может начинаться с косой черты ‘/’. В этом случае он относится к семейству “unix”, а ‘/’ и следующие символы должны задавать путь.

Тип сокета или способ передачи по умолчанию, “datagram” либо “stream”, зависит от директивы, в которой указан адрес. Для ‘bind’ и ‘server’ по умолчанию используется тип “stream”, а для ’log’, ’nameserver’ и ‘dgram-bind’ — “datagram”.

С помощью необязательного префикса можно явно задать семейство адресов, тип сокета и/или способ передачи.

2.9.1. Префиксы семейств адресов

‘abns@<name>’ — следующее за префиксом <name> относится к абстрактному пространству имён (только Linux).

‘abnsz@<name>’ — следующее за префиксом <name> относится к абстрактному пространству имён и завершается нулевым символом (только Linux).

‘fd@<n>’ — далее указан файловый дескриптор <n>, унаследованный от родительского процесса. Он должен быть привязан к адресу и может уже слушать соединения, но это необязательно.

‘ip@<address>[:port1[-port2]]’ — следующее за префиксом <address> считается адресом IPv4 или IPv6 в зависимости от синтаксиса. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным.

‘ipv4@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv4. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным.

‘ipv6@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv6. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным.

‘sockpair@<n>’ — далее указан файловый дескриптор соединённого сокета Unix или пары сокетов. При установке соединения инициатор создаёт пару соединённых сокетов и передаёт один из них другой стороне через этот дескриптор. Слушатель ждёт получения дескриптора через сокет Unix и использует его как дескриптор, возвращённый accept(). Следует использовать с осторожностью.

           Ошибки: известно, что этот протокол ненадёжен на macOS из-за
           ошибки в реализации sendmsg(2) в macOS. Соединение может быть
           принято некорректно.

‘unix@<path>’ — следующая строка рассматривается как путь <path> к сокету UNIX. Этот префикс удобен для пути к сокету UNIX, который не начинается с косой черты ‘/’.

2.9.2. Префиксы типов сокетов

Перед описанными выше префиксами семейства адресов можно добавить ещё один префикс, чтобы явно задать тип сокета и способ передачи. Значение по умолчанию зависит от директивы, использующей адрес, но в некоторых случаях его можно изменить. Например, директива “log” по умолчанию использует syslog поверх UDP, но её можно настроить на syslog поверх TCP.

Эти префиксы предназначены для внутреннего использования. Пользователям следует применять вместо них псевдонимы из следующего раздела «2.9.3. Префиксы протоколов». Однако иногда такие префиксы удобны, например с унаследованными сокетами, известными по номерам файловых дескрипторов: в этом случае семейство адресов — “fd”, а тип сокета необходимо указать явно.

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

‘stream+<family>@<address>’ — явно задаёт тип сокета и способ передачи “stream”.

‘dgram+<family>@<address>’ — явно задаёт тип сокета и способ передачи “datagram”.

‘quic+<family>@<address>’ — явно задаёт тип сокета “datagram” и способ передачи “stream”.

2.9.3. Префиксы протоколов

‘quic4@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv4, но тип сокета явно задаётся как “datagram”, а способ передачи — как “stream”. В зависимости от директивы, использующей этот адрес, UDP-порт или диапазон портов может быть необязательным либо обязательным. Эквивалентно “quic+ipv4@”.

‘quic6@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv6, но тип сокета явно задаётся как “datagram”, а способ передачи — как “stream”. В зависимости от директивы, использующей этот адрес, UDP-порт или диапазон портов может быть необязательным либо обязательным. Эквивалентно “quic+ipv6@”.

’tcp@<address>[:port1[-port2]]’ — следующее за префиксом <address> считается адресом IPv4 или IPv6 в зависимости от синтаксиса, но тип сокета и способ передачи явно задаются как “stream”. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным. Это псевдоним ‘stream+ip@’.

’tcp4@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv4, но тип сокета и способ передачи явно задаются как “stream”. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным. Это псевдоним ‘stream+ipv4@’.

’tcp6@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv6, но тип сокета и способ передачи явно задаются как “stream”. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным. Это псевдоним ‘stream+ipv6@’.

‘mptcp@<address>[:port1[-port2]]’ — следующее за префиксом <address> считается адресом IPv4 или IPv6 в зависимости от синтаксиса, но тип сокета и способ передачи явно задаются как “stream”, с протоколом MPTCP. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным.

‘mptcp4@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv4, но тип сокета и способ передачи явно задаются как “stream”, с протоколом MPTCP. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным.

‘mptcp6@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv6, но тип сокета и способ передачи явно задаются как “stream”, с протоколом MPTCP. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным.

‘udp@<address>[:port1[-port2]]’ — следующее за префиксом <address> считается адресом IPv4 или IPv6 в зависимости от синтаксиса, но тип сокета и способ передачи явно задаются как “datagram”. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным. Это псевдоним ‘dgram+ip@’.

‘udp4@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv4, но тип сокета и способ передачи явно задаются как “datagram”. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным. Это псевдоним ‘dgram+ipv4@’.

‘udp6@<address>[:port1[-port2]]’ — следующее за префиксом <address> всегда считается адресом IPv6, но тип сокета и способ передачи явно задаются как “datagram”. В зависимости от директивы, использующей этот адрес, порт или диапазон портов может быть необязательным либо обязательным. Это псевдоним ‘dgram+ipv6@’.

‘uxdg@<path>’ — следующая строка рассматривается как путь <path> к сокету unix, но способ передачи явно задаётся как “datagram”. Это псевдоним ‘dgram+unix@’.

‘uxst@<path>’ — следующая строка рассматривается как путь <path> к сокету unix, но способ передачи явно задаётся как “stream”. Это псевдоним ‘stream+unix@’.

В будущих версиях могут появиться другие префиксы для протоколов, таких как QUIC, обеспечивающих потоковую передачу поверх сокетов типа “datagram”.

2.10. Примеры

# Simple configuration for an HTTP proxy listening on port 80 on all
    # interfaces and forwarding requests to a single backend "servers" with a
    # single server "server1" listening on 127.0.0.1:8000
    global
        daemon
        maxconn 256

    defaults
        mode http
        timeout connect 5000ms
        timeout client 50000ms
        timeout server 50000ms

    frontend http-in
        bind *:80
        default_backend servers

    backend servers
        server server1 127.0.0.1:8000 maxconn 32


    # The same configuration defined with a single listen block. Shorter but
    # less expressive, especially in HTTP mode.
    global
        daemon
        maxconn 256

    defaults
        mode http
        timeout connect 5000ms
        timeout client 50000ms
        timeout server 50000ms

    listen http-in
        bind *:80
        server server1 127.0.0.1:8000 maxconn 32

Если haproxy находится в $PATH, проверить эти конфигурации можно следующей командой оболочки:

$ sudo haproxy -f configuration.conf -c

12 - 3. Секция global

Параметры секции “global” действуют на весь процесс и часто зависят от ОС. Обычно их задают один раз, и после правильной настройки менять их не требуется. У некоторых есть эквиваленты в командной строке.

В секции “global” поддерживаются следующие ключевые слова:

• Управление процессами и безопасность

  • 51degrees-allow-unmatched
  • 51degrees-cache-size
  • 51degrees-data-file
  • 51degrees-difference
  • 51degrees-drift
  • 51degrees-property-name-list
  • 51degrees-property-separator
  • 51degrees-use-performance-graph
  • 51degrees-use-predictive-graph
  • ca-base
  • chroot
  • cluster-secret
  • cpu-affinity
  • cpu-map
  • cpu-policy
  • cpu-set
  • crt-base
  • daemon
  • default-path
  • description
  • deviceatlas-json-file
  • deviceatlas-log-level
  • deviceatlas-properties-cookie
  • deviceatlas-separator
  • dns-accept-family
  • expose-deprecated-directives
  • expose-experimental-directives
  • external-check
  • fd-hard-limit
  • gid
  • grace
  • group
  • h1-accept-payload-with-any-method
  • h1-case-adjust
  • h1-case-adjust-file
  • h1-do-not-close-on-insecure-transfer-encoding
  • h2-workaround-bogus-websocket-clients
  • hard-stop-after
  • harden.reject-privileged-ports.tcp
  • harden.reject-privileged-ports.quic
  • insecure-fork-wanted
  • insecure-setuid-wanted
  • issuers-chain-path
  • jwt.allow_none_alg
  • jwt.decrypt_alg_list
  • jwt.decrypt_enc_list
  • key-base
  • limited-quic
  • localpeer
  • log
  • log-send-hostname
  • log-tag
  • lua-load
  • lua-load-per-thread
  • lua-prepend-path
  • max-threads-per-group
  • mworker-max-reloads
  • nbthread
  • node
  • numa-cpu-mapping
  • ocsp-update.disable
  • ocsp-update.maxdelay
  • ocsp-update.mindelay
  • ocsp-update.httpproxy
  • ocsp-update.mode
  • pidfile
  • pp2-never-send-local
  • presetenv
  • prealloc-fd
  • resetenv
  • set-dumpable
  • set-var
  • setenv
  • ssl-default-bind-ciphers
  • ssl-default-bind-ciphersuites
  • ssl-default-bind-client-sigalgs
  • ssl-default-bind-curves
  • ssl-default-bind-options
  • ssl-default-bind-sigalgs
  • ssl-default-server-ciphers
  • ssl-default-server-ciphersuites
  • ssl-default-server-client-sigalgs
  • ssl-default-server-curves
  • ssl-default-server-options
  • ssl-default-server-sigalgs
  • ssl-dh-param-file
  • ssl-propquery
  • ssl-provider
  • ssl-provider-path
  • ssl-security-level
  • ssl-server-verify
  • ssl-skip-self-issued-ca
  • stats
  • stats-file
  • strict-limits
  • uid
  • ulimit-n
  • unix-bind
  • unsetenv
  • user
  • wurfl-cache-size
  • wurfl-data-file
  • wurfl-information-list
  • wurfl-information-list-separator

• Настройка производительности

  • busy-polling
  • max-spread-checks
  • maxcompcpuusage
  • maxcomprate
  • maxconn
  • maxconnrate
  • maxpipes
  • maxsessrate
  • maxsslconn
  • maxsslrate
  • maxzlibmem
  • no-memory-trimming
  • noepoll
  • noevports
  • nogetaddrinfo
  • nokqueue
  • noktls
  • nopoll
  • noreuseport
  • nosplice
  • profiling.memory
  • profiling.tasks
  • server-state-base
  • server-state-file
  • spread-checks
  • ssl-engine
  • ssl-mode-async
  • tune.applet.zero-copy-forwarding
  • tune.buffers.limit
  • tune.buffers.reserve
  • tune.bufsize
  • tune.bufsize.large
  • tune.bufsize.small
  • tune.cli.max-payload-size
  • tune.comp.maxlevel
  • tune.defaults.purge
  • tune.disable-fast-forward
  • tune.disable-zero-copy-forwarding
  • tune.epoll.mask-events
  • tune.events.max-events-at-once
  • tune.fail-alloc
  • tune.fd.edge-triggered
  • tune.h1.be.glitches-threshold
  • tune.h1.fe.glitches-threshold
  • tune.h1.zero-copy-fwd-recv
  • tune.h1.zero-copy-fwd-send
  • tune.h2.be.glitches-threshold
  • tune.h2.be.initial-window-size
  • tune.h2.be.max-concurrent-streams
  • tune.h2.be.max-frames-at-once
  • tune.h2.be.rxbuf
  • tune.h2.fe.glitches-threshold
  • tune.h2.fe.initial-window-size
  • tune.h2.fe.max-concurrent-streams
  • tune.h2.fe.max-frames-at-once
  • tune.h2.fe.max-rst-at-once
  • tune.h2.fe.max-total-streams
  • tune.h2.fe.rxbuf
  • tune.h2.header-table-size
  • tune.h2.initial-window-size
  • tune.h2.max-concurrent-streams
  • tune.h2.max-frame-size
  • tune.h2.zero-copy-fwd-send
  • tune.http.cookielen
  • tune.http.logurilen
  • tune.http.maxhdr
  • tune.idle-pool.shared
  • tune.idletimer
  • tune.lua.bool-sample-conversion
  • tune.lua.burst-timeout
  • tune.lua.forced-yield
  • tune.lua.log.loggers
  • tune.lua.log.stderr
  • tune.lua.maxmem
  • tune.lua.openlibs
  • tune.lua.service-timeout
  • tune.lua.session-timeout
  • tune.lua.task-timeout
  • tune.max-checks-per-thread
  • tune.maxaccept
  • tune.maxpollevents
  • tune.maxrewrite
  • tune.max-rules-at-once
  • tune.memory.hot-size
  • tune.pattern.cache-size
  • tune.peers.max-updates-at-once
  • tune.pipesize
  • tune.pool-high-fd-ratio
  • tune.pool-low-fd-ratio
  • tune.pt.zero-copy-forwarding
  • tune.quic.be.cc.cubic-min-losses
  • tune.quic.be.cc.hystart
  • tune.quic.be.cc.max-frame-loss
  • tune.quic.be.cc.max-win-size
  • tune.quic.be.cc.reorder-ratio
  • tune.quic.be.max-idle-timeout
  • tune.quic.be.sec.glitches-threshold
  • tune.quic.be.stream.data-ratio
  • tune.quic.be.stream.max-concurrent
  • tune.quic.be.stream.rxbuf
  • tune.quic.be.tx.pacing
  • tune.quic.be.tx.udp-gso
  • tune.quic.cc.cubic.min-losses (устарело)
  • tune.quic.cc-hystart (устарело)
  • tune.quic.disable-tx-pacing (устарело)
  • tune.quic.disable-udp-gso (устарело)
  • tune.quic.fe.cc.cubic-min-losses
  • tune.quic.fe.cc.hystart
  • tune.quic.fe.cc.max-frame-loss
  • tune.quic.fe.cc.max-win-size
  • tune.quic.fe.cc.reorder-ratio
  • tune.quic.fe.max-idle-timeout
  • tune.quic.fe.sec.glitches-threshold
  • tune.quic.fe.sec.retry-threshold
  • tune.quic.fe.sock-per-conn
  • tune.quic.fe.stream.data-ratio
  • tune.quic.fe.stream.max-concurrent
  • tune.quic.fe.stream.max-total
  • tune.quic.fe.stream.rxbuf
  • tune.quic.fe.tx.pacing
  • tune.quic.fe.tx.udp-gso
  • tune.quic.frontend.max-data-size (устарело)
  • tune.quic.frontend.max-idle-timeout (устарело)
  • tune.quic.frontend.max-streams-bidi (устарело)
  • tune.quic.frontend.max-tx-mem (устарело)
  • tune.quic.frontend.stream-data-ratio (устарело)
  • tune.quic.frontend.default-max-window-size (устарело)
  • tune.quic.listen
  • tune.quic.max-frame-loss (устарело)
  • tune.quic.mem.tx-max
  • tune.quic.reorder-ratio (устарело)
  • tune.quic.retry-threshold (устарело)
  • tune.quic.socket-owner (устарело)
  • tune.quic.zero-copy-fwd-send
  • tune.renice.runtime
  • tune.renice.startup
  • tune.rcvbuf.backend
  • tune.rcvbuf.client
  • tune.rcvbuf.frontend
  • tune.rcvbuf.server
  • tune.recv_enough
  • tune.ring.queues
  • tune.runqueue-depth
  • tune.sched.low-latency
  • tune.sndbuf.backend
  • tune.sndbuf.client
  • tune.sndbuf.frontend
  • tune.sndbuf.server
  • tune.streams-elasticity
  • tune.stick-counters
  • tune.ssl.cachesize
  • tune.ssl.capture-buffer-size
  • tune.ssl.capture-cipherlist-size (устарело)
  • tune.ssl.certificate-compression
  • tune.ssl.default-dh-param
  • tune.ssl.force-private-cache
  • tune.ssl.hard-maxrecord
  • tune.ssl.keylog
  • tune.ssl.keyupdate-rate-limit
  • tune.ssl.lifetime
  • tune.ssl.maxrecord
  • tune.ssl.ssl-ctx-cache-size
  • tune.ssl.ocsp-update.maxdelay (устарело)
  • tune.ssl.ocsp-update.mindelay (устарело)
  • tune.takeover-other-tg-connections
  • tune.vars.global-max-size
  • tune.vars.proc-max-size
  • tune.vars.reqres-max-size
  • tune.vars.sess-max-size
  • tune.vars.txn-max-size
  • tune.zlib.memlevel
  • tune.zlib.windowsize

• Debugging

  • anonkey
  • debug.counters
  • force-cfg-parser-pause
  • quiet
  • warn-blocked-traffic-after
  • zero-warning

• HTTPClient

  • httpclient.resolvers.disabled
  • httpclient.resolvers.id
  • httpclient.resolvers.prefer
  • httpclient.retries
  • httpclient.ssl.ca-file
  • httpclient.ssl.verify
  • httpclient.timeout.connect

3.1. Управление процессами и безопасность

51degrees-data-file <file path>

51degrees-data-file <file path>

Путь к файлу данных 51Degrees для определения устройств. Файл следует распаковать и предоставить HAProxy необходимые права доступа к нему.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES.

51degrees-property-name-list [<string> ...]

51degrees-property-name-list [<string> ...]

Список имён свойств 51Degrees, которые нужно загрузить из набора данных. Полный список имён доступен на сайте 51Degrees: https://51degrees.com/resources/property-dictionary

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES.

51degrees-property-separator <char>

51degrees-property-separator <char>

Символ, добавляемый после каждого значения свойства в заголовке ответа с результатами 51Degrees. Если не задан, используется ‘,’.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES.

51degrees-cache-size <number>

51degrees-cache-size <number>

Задаёт размер кэша преобразователя 51Degrees: <number> записей. Этот кэш LRU хранит результаты предыдущих определений устройств. По умолчанию кэш отключён.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES.

51degrees-use-performance-graph { on | off }

51degrees-use-performance-graph { on | off }

Включает (‘on’) или отключает (‘off’) использование графа производительности при определении устройства. Значение по умолчанию зависит от библиотеки 51Degrees.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES и 51DEGREES_VER=4.

51degrees-use-predictive-graph { on | off }

51degrees-use-predictive-graph { on | off }

Включает (‘on’) или отключает (‘off’) использование прогнозного графа при определении устройства. Значение по умолчанию зависит от библиотеки 51Degrees.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES и 51DEGREES_VER=4.

51degrees-drift <number>

51degrees-drift <number>

Задаёт допустимую величину смещения при определении устройства.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES и 51DEGREES_VER=4.

51degrees-difference <number>

51degrees-difference <number>

Задаёт допустимую величину различия при определении устройства.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES и 51DEGREES_VER=4.

51degrees-allow-unmatched { on | off }

51degrees-allow-unmatched { on | off }

Включает (‘on’) или отключает (‘off’) использование несовпавших узлов при определении устройства. Значение по умолчанию зависит от библиотеки 51Degrees.

Обратите внимание: этот параметр доступен только в том случае, если HAProxy собран с USE_51DEGREES и 51DEGREES_VER=4.

acme.scheduler { auto | off }

acme.scheduler { auto | off }

Включает или отключает планировщик ACME.

Планировщик ACME запускается при старте HAProxy. Он перебирает сертификаты и запускает задачу обновления ACME, когда значение notAfter оказывается раньше curtime + (notAfter - notBefore) / 12; если notBefore не определено, используется интервал 7 дней. Затем планировщик переходит в режим ожидания и просыпается через 12 часов.

Значение по умолчанию — “auto”.

См. также: acme

ca-base <dir>

ca-base <dir>

Задаёт каталог по умолчанию для загрузки сертификатов центров сертификации SSL и списков отзыва CRL, когда в директивах “ca-file”, “ca-verify-file” или “crl-file” указан относительный путь. Абсолютные пути в “ca-file”, “ca-verify-file” и “crl-file” имеют приоритет; “ca-base” в этом случае игнорируется.

chroot { <jail dir> | auto }

chroot { <jail dir> | auto }

Меняет текущий каталог на <jail dir> и выполняет в нём chroot() перед сбросом привилегий. Это повышает безопасность при эксплуатации неизвестной уязвимости, поскольку существенно затрудняет атакующему дальнейшее воздействие на систему. Важно убедиться, что каталог <jail dir> пуст и никому не доступен для записи. Если процесс запущен с правами суперпользователя, chroot() выполняется напрямую. В Linux при запуске без привилегий haproxy пытается выполнить его в новом пользовательском пространстве имён, созданном с помощью unshare(CLONE_NEWUSER); если этот механизм недоступен, chroot() завершается обычной ошибкой.

В качестве особого случая для <jail dir> можно указать “auto”. Тогда haproxy создаёт анонимный временный каталог, удаляет ссылку на него и выполняет chroot в этот каталог. Полученная изолированная среда не имеет имени в файловой системе, пуста и доступна только для чтения; отдельный каталог для неё подготавливать не требуется.

Если при запуске с правами суперпользователя chroot не используется, выводится предупреждение, призывающее всегда применять этот механизм. Если есть веская причина отказаться от chroot, например доступ к серверу через сокет UNIX с неудобным путём, предупреждение можно отключить, явно добавив “chroot /”. Преимущество такой записи в том, что она видна в конфигурации.

close-spread-time <time>

close-spread-time <time>

Задаёт временной интервал, по которому распределяется закрытие простаивающих и активных соединений при плавной остановке. После получения SIGUSR1 и окончания льготного периода, если он задан, при отсутствии этого параметра все простаивающие соединения закрываются сразу. Активные соединения HTTP или HTTP2 завершаются после получения следующего запроса: в ответ HTTP добавляется строка “Connection: close”, а в случае HTTP2 отправляется кадр GOAWAY. Если параметр задан, закрытие соединений распределяется по указанному интервалу <time>. Если close-spread-time имеет значение “infinite”, закрытие активных соединений при плавной остановке отключается. Заголовок “Connection: close” больше не добавляется в ответы HTTP, а GOAWAY не отправляется для HTTP2; простаивающие соединения закрываются только по истечении их тайм-аутов, определяемых соответствующими параметрами конфигурации.

Аргументы:

<time>  — временной интервал (по умолчанию в миллисекундах), на протяжении
        которого распределяется закрытие соединений при мягкой остановке;
        значение "infinite" отключает активное закрытие соединений.

Если используется параметр “hard-stop-after”, для этого параметра рекомендуется задать меньшее значение, чтобы все соединения успели корректно закрыться до остановки процесса.

См. также: grace, hard-stop-after, idle-close-on-response

cluster-secret <secret>

cluster-secret <secret>

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

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

cpu-map [auto:]<thread-group>[/<thread-set>] <cpu-set>[,...] [...]

cpu-map [auto:]<thread-group>[/<thread-set>] <cpu-set>[,...] [...]

В некоторых операционных системах группу потоков или отдельный поток можно привязать к определённому набору CPU. Это означает, что указанные потоки никогда не будут выполняться на других CPU. Директива “cpu-map” задаёт наборы CPU для отдельных потоков или групп потоков. Первый аргумент — диапазон групп потоков, за которым можно указать набор потоков. Эти диапазоны имеют следующий формат:

all | odd | even | number[-[number]]

<number> должен быть числом от 1 до 32 или 64 в зависимости от разрядности машинного слова. Идентификаторы групп, превышающие ’thread-groups’, и идентификаторы потоков, превышающие разрядность машинного слова, игнорируются. Все номера потоков отсчитываются относительно группы, к которой они принадлежат. Диапазон можно задать двумя такими числами, разделёнными дефисом (’-’). Можно также указать все потоки сразу с помощью “all”, только потоки с нечётными номерами с помощью “odd” или с чётными номерами с помощью “even”, как и в директиве привязки “thread”. Второй и последующие аргументы — наборы CPU. Каждый набор CPU задаётся либо одним номером, начиная с 0 для первого CPU, либо диапазоном из двух таких номеров, разделённых дефисом (’-’). Номера и диапазоны CPU можно перечислять через запятую или передавать дополнительные диапазоны как новые аргументы в той же строке. В операционных системах, отличных от Linux и BSD, максимальный индекс CPU может быть ограничен значением 31 или 63. Можно задать несколько директив “cpu-map”, но каждая из них заменяет предыдущие в той части, где они пересекаются.

Диапазоны можно задавать частично: верхнюю границу можно опустить. Тогда вместо неё используется соответствующее максимальное значение — 32 или 64 в зависимости от разрядности машинного слова.

Перед набором потоков можно добавить префикс “auto:”, чтобы HAProxy автоматически привязывал потоки к CPU, последовательно увеличивая номера потоков и CPU в наборах. Оба набора должны иметь одинаковый размер. Независимо от порядка объявления наборов CPU привязка выполняется от меньшего номера к большему. С префиксом “auto:” нельзя одновременно задавать диапазон групп и диапазон потоков. Поддерживается только один диапазон; второй элемент должен быть фиксированным числом.

Обратите внимание: диапазоны групп поддерживаются по историческим причинам. Сейчас отдельное число обозначает группу потоков; если группы потоков не используются, оно должно быть равно 1. При указании номера или диапазона потоков без использования групп потоков перед ним необходимо добавить “1/”. Запись “1” полностью эквивалентна “1/all” и обозначает все потоки группы.

Примеры:

cpu-map 1/all 0-3 # bind all threads of the first group on the
                  # first 4 CPUs

cpu-map 1/1- 0-   # will be replaced by "cpu-map 1/1-64 0-63"
                  # or "cpu-map 1/1-32 0-31" depending on the machine's
                  # word size.

# all these lines bind thread 1 to the cpu 0, the thread 2 to cpu 1
# and so on.
cpu-map auto:1/1-4   0-3
cpu-map auto:1/1-4   0-1 2-3
cpu-map auto:1/1-4   3 2 1 0
cpu-map auto:1/1-4   3,2,1,0

# bind each thread to exactly one CPU using all/odd/even keyword
cpu-map auto:1/all   0-63
cpu-map auto:1/even  0-31
cpu-map auto:1/odd   32-63

# invalid cpu-map because thread and CPU sets have different sizes.
cpu-map auto:1/1-4   0    # invalid
cpu-map auto:1/1     0-3  # invalid

# map 40 threads of those 4 groups to individual CPUs
cpu-map auto:1/1-10   0-9
cpu-map auto:2/1-10   10-19
cpu-map auto:3/1-10   20-29
cpu-map auto:4/1-10   30-39

# Map 80 threads to one physical socket and 80 others to another socket
# without forcing assignment. These are split into 4 groups since no
# group may have more than 64 threads.
cpu-map 1/1-40   0-39,80-119    # node0, siblings 0 & 1
cpu-map 2/1-40   0-39,80-119
cpu-map 3/1-40   40-79,120-159  # node1, siblings 0 & 1
cpu-map 4/1-40   40-79,120-159

cpu-affinity <affinity>

cpu-affinity <affinity>

Определяет способ привязки потоков к CPU. Сейчас поддерживаются следующие значения:

• per-core: каждый поток привязывается ко всем аппаратным потокам одного ядра.
• per-group: каждый поток привязывается ко всем аппаратным потокам группы. Это значение по умолчанию, если в “cpu-policy” не задано “threads-per-core 1”. “per-group” принимает необязательный аргумент, определяющий распределение CPU. Когда список CPU превышает максимально допустимое число CPU в группе и его нужно разделить между несколькими группами, дополнительный параметр позволяет выбрать способ привязки групп к этим CPU:
  • auto: каждой группе потоков выделяется соразмерная доля последовательных ядер CPU, которые используются только ею и не разделяются с другими группами. Это значение по умолчанию, поскольку обычно оно обеспечивает более оптимальную работу.
  • loose: каждой группе по-прежнему разрешается использовать любой CPU из списка. Обычно это усиливает конкуренцию за ресурсы, но иногда помогает лучше справляться с посторонней нагрузкой на тех же CPU.
• auto: обычно используется “per-group”. Если в “cpu-policy” задано “threads-per-core 1”, используется “per-core”. Это значение по умолчанию.
• per-thread: каждый поток привязывается только к одному аппаратному потоку. Если в “cpu-policy” задано “threads-per-core 1”, каждый поток привязывается к одному аппаратному потоку отдельного ядра.
• per-ccx: каждый поток привязывается ко всем аппаратным потокам одного CCX.

cpu-policy <policy> [threads-per-core 1 | auto]

cpu-policy <policy> [threads-per-core 1 | auto]

Выбирает политику распределения CPU.

В системах с несколькими CPU может быть много причин не использовать все доступные ядра или распределять их по разным группам потоков: производительность, задержки, стоимость или управление ресурсами всей системы. Директива “cpu-set” уже позволяет исключить часть CPU, но после этого нужно решить, как распределить оставшиеся между потоками и группами потоков.

Обычно это распределение задаётся директивой “cpu-map”, однако в неоднородных системах поддерживать такую настройку может быть особенно трудно.

Если “cpu-map” не используется, директива “cpu-policy” позволяет выбрать вместо него одну из нескольких политик распределения. Сейчас поддерживаются следующие политики; по умолчанию используется “performance”:

• none: дополнительный отбор не выполняется. Можно использовать все включённые CPU. Если число потоков не задано, оно принимается равным числу доступных CPU, но не более 32 в 32-битных системах или 64 в 64-битных системах на одну группу потоков. Если число групп потоков не задано, используется 1.

• efficiency: работает так же, как описанная ниже “group-by-ccx”, но исключает кластеры CPU из ядер, производительность которых более чем на 25% превышает производительность следующего, менее производительного типа. Обычно это ядра “big” или “performance”. Таким образом, при обнаружении нескольких типов ядер CPU используется только энергоэффективный. Это может быть полезно при умеренной нагрузке, когда самые мощные ядра нужно оставить приложению или компоненту безопасности. Некоторые современные CPU имеют много таких энергоэффективных ядер, которые вместе обеспечивают приемлемую производительность при меньшем энергопотреблении.

• first-usable-node: если набор CPU ранее не был ограничен при запуске, например утилитой “taskset”, и директива “nbthread” не задана, используется первый узел NUMA с включёнными CPU. Число этих CPU принимается за число потоков. Для всех них включается одна группа потоков с ограничением в 32 или 64 в зависимости от системы.

• group-by-2-ccx: работает так же, как описанная ниже “group-by-ccx”, но создаёт одну группу на каждые два CCX. Это может быть полезно для CPU с большим числом CCX, в каждом из которых мало ядер, чтобы не создавать слишком много групп или немного выровнять распределение, когда используются не все ядра. Обратите внимание: при медленном обмене между CCX производительность может существенно ухудшиться. Обычно эту политику использовать не рекомендуется.

• group-by-2-clusters: работает так же, как описанная “group-by-cluster”, но создаёт одну группу на каждые два кластера. Это может быть полезно для CPU с большим числом кластеров, в каждом из которых мало ядер, чтобы не создавать слишком много групп или немного выровнять распределение, когда используются не все ядра. Обратите внимание: при медленном обмене между кластерами производительность может существенно ухудшиться. Обычно эту политику использовать не рекомендуется.

• group-by-3-ccx: работает так же, как описанная ниже “group-by-ccx”, но создаёт одну группу на каждые три CCX. Это может быть полезно для CPU с большим числом CCX, в каждом из которых мало ядер, чтобы не создавать слишком много групп или немного выровнять распределение, когда используются не все ядра. Обратите внимание: при медленном обмене между CCX производительность может существенно ухудшиться. Обычно эту политику использовать не рекомендуется.

• group-by-3-clusters: работает так же, как описанная “group-by-cluster”, но создаёт одну группу на каждые три кластера. Это может быть полезно для CPU с большим числом кластеров, в каждом из которых мало ядер, чтобы не создавать слишком много групп или немного выровнять распределение, когда используются не все ядра. Обратите внимание: при медленном обмене между кластерами производительность может существенно ухудшиться. Обычно эту политику использовать не рекомендуется.

• group-by-4-ccx: работает так же, как описанная ниже “group-by-ccx”, но создаёт одну группу на каждые четыре CCX. Это может быть полезно для CPU с большим числом CCX, в каждом из которых мало ядер, чтобы не создавать слишком много групп или немного выровнять распределение, когда используются не все ядра. Обратите внимание: при медленном обмене между CCX производительность может существенно ухудшиться. Обычно эту политику использовать не рекомендуется.

• group-by-4-clusters: работает так же, как описанная “group-by-cluster”, но создаёт одну группу на каждые четыре кластера. Это может быть полезно для CPU с большим числом кластеров, в каждом из которых мало ядер, чтобы не создавать слишком много групп или немного выровнять распределение, когда используются не все ядра. Обратите внимание: при медленном обмене между кластерами производительность может существенно ухудшиться. Обычно эту политику использовать не рекомендуется.

• group-by-ccx: если не заданы ни “nbthread”, ни “nbtgroups”, для каждого комплекса ядер CPU (“CCX”) с доступными CPU создаётся одна группа потоков с числом потоков, равным числу CPU. CCX объединяет CPU с одинаково быстрым доступом к кэшу последнего уровня (“LLC”), обычно к L3. В большинстве современных систем для производительности критически важно не объединять CPU из удалённых CCX в одну группу потоков. Все потоки группы привязываются ко всем CPU этого CCX, чтобы обмен внутри группы оставался локальным для CCX без чрезмерно жёсткой привязки. Соблюдаются ограничения на число потоков в группе и на число групп потоков. Эта политика рекомендуется для многосокетных систем и систем NUMA, а также для CPU с большими задержками обмена между CCX.

• group-by-cluster: если не заданы ни “nbthread”, ни “nbtgroups”, для каждого кластера CPU с доступными CPU создаётся одна группа потоков с числом потоков, равным числу CPU. Все потоки группы привязываются ко всем CPU кластера, чтобы обмен внутри группы оставался локальным для кластера без чрезмерно жёсткой привязки. Соблюдаются ограничения на число потоков в группе и на число групп потоков. Эта политика рекомендуется для многосокетных систем и систем NUMA, а также для CPU с большими задержками обмена между CCX. В большинстве серверных систем кластеры и CCX совпадают, но в неоднородных системах (“performance” и “efficiency” либо “big” и “little”) кластер обычно включает лишь часть CCX с очень похожими CPU: одного типа и с разницей частот не более +/-5%. Это различие заметно на современных ноутбуках и настольных компьютерах, на которых разработчики и администраторы проверяют конфигурации.

• performance: работает так же, как описанная выше “group-by-ccx”, но исключает кластеры CPU из ядер, производительность которых составляет менее 80% от производительности следующего, более производительного типа. Обычно это ядра “little” или “efficient”: их добавление, как правило, не даёт существенного выигрыша и легко может ухудшить результат, например при рукопожатиях TLS. Часто гораздо эффективнее оставить такие ядра для других задач, например обработки сети. В системах разработки на них также можно запускать вспомогательные средства, например генераторы нагрузки и средства мониторинга. Это политика по умолчанию.

• resource: работает так же, как описанная выше “group-by-cluster”, но использует только самый маленький и энергоэффективный кластер CPU, игнорируя все остальные. Это позволяет ограничить использование ресурсов необходимым минимумом, при котором ещё сохраняется приемлемая производительность. Например, можно дополнительно снизить энергопотребление или сократить число ядер для вспомогательного процесса sidecar в арендованной системе, чтобы было проще уменьшить выделенные ей ресурсы. Обратите внимание: если кластер всего один, он всё равно используется целиком.

Можно добавить необязательное ключевое слово “threads-per-core”. Оно принимает значения “1” и “auto”. При значении 1 создаётся только один поток на ядро независимо от числа аппаратных потоков этого ядра. При значении auto создаётся по одному потоку на каждый аппаратный поток. Если привязка явно не задана и используется threads-per-core 1, по умолчанию применяется привязка per-core.

См. также: “cpu-map”, “cpu-set”, “nbthread”

cpu-set <directive>...

cpu-set <directive>...

Позволяет символически описать наборы CPU для выполнения. Директива поддерживает следующие ключевые слова: - reset отменяет все прежние ограничения, которые могли быть унаследованы, например, от диспетчера служб или команды “taskset”. - drop-cpu <set> не привязывает к CPU из этого набора - only-cpu <set> не привязывает к CPU вне этого набора - drop-node <set> не привязывает к CPU этого узла NUMA - only-node <set> не привязывает к CPU других узлов NUMA - drop-cluster <set> не привязывает к CPU аппаратного кластера с этим номером - only-cluster <set> не привязывает к CPU аппаратных кластеров с другими номерами - drop-core <set> не привязывает к CPU аппаратного ядра с этим номером - only-core <set> не привязывает к CPU аппаратных ядер с другими номерами - drop-thread <set> не привязывает к CPU аппаратного потока с этим номером - only-thread <set> не привязывает к CPU аппаратных потоков с другими номерами См. также: “cpu-policy”

crt-base <dir>

crt-base <dir>

Задаёт каталог по умолчанию для загрузки сертификатов SSL, когда в директивах “crtfile” или “crt” используется относительный путь. Заданные абсолютные пути имеют приоритет; “crt-base” в этом случае игнорируется.

daemon

daemon

Переводит процесс в фоновый режим через fork. Это рекомендуемый режим работы. Он эквивалентен аргументу командной строки “-D” и может быть отключён аргументом “-db”. В режиме systemd этот параметр игнорируется.

default-path { current | config | parent | origin <path> }

default-path { current | config | parent | origin <path> }

По умолчанию HAProxy загружает все файлы с относительными путями из каталога, в котором был запущен процесс. В некоторых случаях желательно принудительно отсчитывать относительные пути от другого каталога, как если бы процесс был запущен из него. Для этого и предназначена эта директива. Технически она временно выполняет chdir() в указанный каталог при обработке каждого конфигурационного файла и возвращается в исходный каталог после обработки каждого файла. Аргумент задаёт политику загрузки файлов, путь к которым не начинается с косой черты (’/’): - “current” означает, что все файлы с относительными путями загружаются из каталога запуска процесса; это значение по умолчанию.

- "config" означает, что все файлы с относительными путями следует загружать из каталога конфигурационного файла. Точнее, если путь к конфигурационному файлу содержит косую черту ('/'), для перехода используется вся часть пути до последней косой черты; иначе используется текущий каталог. Этот режим удобен для объединения таблиц соответствий, файлов ошибок, сертификатов и сценариев Lua в перемещаемые пакеты. При загрузке нескольких конфигурационных файлов каталог обновляется для каждого из них.

- "parent" означает, что все файлы с относительными путями следует загружать из родительского каталога по отношению к каталогу конфигурационного файла. Точнее, если путь к конфигурационному файлу содержит косую черту ('/'), к части пути до последней косой черты добавляется ".."; полученный путь используется для перехода. В противном случае используется каталог "..". Этот режим удобен для объединения таблиц соответствий, файлов ошибок, сертификатов и сценариев Lua в перемещаемые пакеты, где каждая часть находится в своём подкаталоге, например "config/", "certs/", "maps/" и т. д.

- "origin" означает, что все файлы с относительными путями следует загружать из каталога, путь к которому обязательно должен быть указан. Это упрощает управление несколькими экземплярами HAProxy, работающими параллельно в одной системе: у каждого экземпляра может быть собственный префикс, а остальные секции остаются легко перемещаемыми.

Каждая директива “default-path” немедленно заменяет предыдущую и может привести к переходу в другой каталог. Хотя это должно давать ожидаемый результат, использовать несколько директив default-path не рекомендуется. Если они всё же используются, следует придерживаться согласованной политики во всех конфигурационных файлах.

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

description <text>

description <text>

Добавляет текст с описанием экземпляра.

Обратите внимание: некоторые символы, например #, необходимо экранировать. Поскольку этот текст вставляется в страницу HTML, следует избегать символов “<” и “>”.

deviceatlas-json-file <path>

deviceatlas-json-file <path>

Задаёт путь к файлу данных DeviceAtlas в формате JSON, который загружает API. Путь должен указывать на корректный файл данных JSON, доступный процессу HAProxy.

deviceatlas-log-level <value>

deviceatlas-log-level <value>

Задаёт уровень информации, возвращаемой API. Директива необязательна; если она не задана, по умолчанию используется 0.

deviceatlas-properties-cookie <name>

deviceatlas-properties-cookie <name>

Задаёт имя клиентского cookie, используемого для определения устройства, если при запросе применялся клиентский компонент DeviceAtlas. Директива необязательна; если она не задана, по умолчанию используется DAPROPS.

deviceatlas-separator <char>

deviceatlas-separator <char>

Задаёт символ-разделитель для результатов свойств API. Директива необязательна; если она не задана, по умолчанию используется |.

dns-accept-family <family>[,...]

dns-accept-family <family>[,...]

По умолчанию резолверы DNS принимают адреса IPv4 и IPv6. На выбор можно влиять ключевым словом “resolve-prefer” в строках server и аргументом семейства в действии “do-resolve”, однако это только предпочтение: оно не запрещает использовать другое семейство, если доступно только оно. В средах, где невозможно использовать оба стека, недоступная запись DNS только с адресом IPv6 может вызвать серьёзные проблемы: она заменит прежнюю запись IPv4, которая, возможно, продолжала бы работать до следующего запроса. Глобальный параметр “dns-accept-family” позволяет принудительно использовать только одно семейство адресов или оба. Аргумент — список следующих слов через запятую: - “ipv4”: запрашивать и принимать адреса IPv4 (записи “A”) - “ipv6”: запрашивать и принимать адреса IPv6 (записи “AAAA”) - “auto”: использовать IPv4, а также IPv6, если в системе для него есть шлюз по умолчанию. Результат последней проверки кэшируется на 30 секунд.

Если используется одно семейство, запросы к резолверам для другого семейства не отправляются, а любые ответы для него игнорируются. Начиная с 3.3 значение по умолчанию — “auto”: оба семейства включаются только после подтверждения возможности маршрутизации IPv6; иначе используется только IPv4. См. также: “resolve-prefer”, “do-resolve”

expose-deprecated-directives

expose-deprecated-directives

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

expose-experimental-directives

expose-experimental-directives

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

external-check [preserve-env]

external-check [preserve-env]

Разрешает использовать внешний агент для проверок работоспособности. По соображениям безопасности по умолчанию это отключено. Даже после включения проверки могут завершаться неудачей, если также не включён “insecure-fork-wanted”. Если запускаемая программа использует исполняемый файл с setuid, чего ей действительно не следует делать, в секции global может также потребоваться “insecure-setuid-wanted”. По умолчанию проверки запускаются с чистым окружением, содержащим только переменные, определённые командой “external-check” в секции backend. Иногда желательно сохранить окружение, например если сложные сценарии получают из него дополнительные пути или сведения. Для этого можно добавить ключевое слово “preserve-env”. Однако в таком случае настоятельно рекомендуется не запускать программу с setuid или от привилегированного пользователя, поскольку это открывает возможности для атак на программу проверки. Подробности см. в “option external-check”, “insecure-fork-wanted” и “insecure-setuid-wanted”.

fd-hard-limit <number>

fd-hard-limit <number>

Задаёт верхнюю границу числа файловых дескрипторов, используемых процессом, независимо от системных лимитов. Значение можно принудительно задать через “ulimit-n” и “maxconn”; если они не заданы, процесс ограничивается жёстким лимитом RLIMIT_NOFILE, который показывает “ulimit -n -H”. Однако некоторые современные ОС допускают здесь чрезвычайно большие значения, порядка 1 миллиарда, что при обычной работе потребовало бы слишком много RAM. Параметр fd-hard-limit позволяет установить для этого лимита, возможно, более низкую верхнюю границу. Если системные лимиты ниже <number>, они всегда соблюдаются; если выше, используется заданное значение. По умолчанию fd-hard-limit равен 1048576. Это значение можно изменить переменной времени компиляции DEFAULT_MAXFD, которая может служить максимальным системным лимитом ядра при чрезмерно большом жёстком лимите RLIMIT_NOFILE. Параметр fd-hard-limit в секции global позволяет временно переопределить значение DEFAULT_MAXFD, заданное при сборке. В следующем примере другие параметры не заданы, и maxconn автоматически подстраивается под меньшее из значений “fd-hard-limit” и лимита RLIMIT_NOFILE:

global
    # use as many FDs as possible but no more than 50000
    fd-hard-limit 50000

См. также: ulimit-n, maxconn

gid <number>

gid <number>

Меняет идентификатор группы процесса на <number>. Рекомендуется выделить эту группу для HAProxy или небольшого набора схожих демонов. HAProxy должен запускаться от пользователя, входящего в эту группу, либо с правами суперпользователя. Обратите внимание: если пользователь запуска имеет дополнительные группы, HAProxy сможет отказаться от них только при запуске с правами суперпользователя. См. также “group” и “uid”.

grace <time>

grace <time>

Задаёт задержку между SIGUSR1 и фактической плавной остановкой.

Аргументы:

<time>  — дополнительная задержка (по умолчанию в миллисекундах) после
        получения сигнала SIGUSR1, которую нужно выждать перед переходом
        к мягкой остановке.

Используется для совместимости с устаревшими средами, где процесс haproxy нужно остановить, но внешние компоненты должны обнаружить его состояние до освобождения слушающих сокетов. Внутренняя переменная “stopping”, которую возвращает одноимённая функция извлечения образца “stopping”, переключается в true. При этом слушающие сокеты продолжают принимать соединения без изменений до истечения задержки, после чего начинается обычная плавная остановка. Это нельзя использовать для процессов, конфигурация которых перезагружается: старый процесс не сможет освободить сокеты, что может помешать запуску нового или вызвать другие проблемы.

Пример:

global
  grace 10s

# Returns 200 OK until stopping is set via SIGUSR1
frontend ext-check
  bind :9999
  monitor-uri /ext-check
  monitor fail if { stopping }

Обратите внимание: более гибкий и устойчивый подход — чтобы система оркестрации задавала глобальную переменную через CLI, использовала её при ответах на внешние проверки, а затем после задержки отправляла сигнал SIGUSR1.

Пример:

# Returns 200 OK until proc.stopping is set to non-zero. May be done
# from HTTP using set-var(proc.stopping) or from the CLI using:
# > set var proc.stopping int(1)
frontend ext-check
  bind :9999
  monitor-uri /ext-check
  monitor fail if { var(proc.stopping) -m int gt 0 }

См. также: hard-stop-after, monitor

group <group name>

group <group name>

Аналогичен “gid”, но использует GID группы с именем <group name> из /etc/group. См. также “gid” и “user”.

h1-accept-payload-with-any-method

h1-accept-payload-with-any-method

Не отклоняет запросы HTTP/1.0 GET/HEAD/DELETE с полезной нагрузкой ответом HTTP 413 Payload Too Large.

Хотя HTTP/1.1 явно разрешает такую полезную нагрузку, HTTP/1.0 не даёт однозначного ответа, и некоторые старые серверы не ожидают её и вообще не проверяют длину тела по заголовкам Content-Length или Transfer-Encoding. Поэтому одни промежуточные узлы могут правильно обработать полезную нагрузку запросов HTTP/1.0 GET/HEAD/DELETE, а другие — полностью её проигнорировать. Это создаёт риск для безопасности, поскольку возможна атака с подменой границ запросов. Поэтому по умолчанию HAProxy отклоняет запросы HTTP/1.0 GET/HEAD/DELETE с полезной нагрузкой.

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

h1-do-not-close-on-insecure-transfer-encoding

h1-do-not-close-on-insecure-transfer-encoding

Если где-либо в цепочке до или после узла есть агент HTTP/1.0, одновременное наличие полей Transfer-Encoding и Content-Length в одном сообщении создаёт серьёзный риск атаки с подменой границ содержимого. Согласно спецификации HTTP/1.1 (RFC9112#6.1), в такой ситуации агент обязан закрыть соединение после ответа, чтобы исключить эксплуатацию этой уязвимости. Однако это может снизить производительность некоторых очень старых клиентов, особенно если им приходится заново согласовывать соединение TLS для каждого запроса. Этот параметр позволяет попросить HAProxy не применять такое правило: сообщение очищается, но соединение остаётся открытым после ответа. Это допустимо только при полной уверенности, что в цепочке нет агентов HTTP/1.0 и все реализации перед HAProxy полностью соблюдают правила HTTP/1.1 для этих полей заголовков. В любом случае HAProxy продолжает игнорировать и удалять лишний заголовок Content-Length, чтобы не вводить следующий узел в заблуждение.

При включении этого параметра для обхода ошибки старого клиента или сервера важно понимать: независимо от того, нужен ли этот параметр, сообщения такого агента, нарушающего правило, могут быть усечены старыми агентами, которые учитывают Content-Length и игнорируют Transfer-Encoding. Причина в том, что не учитывается общий объём данных, которыми закодированы размеры блоков. Поэтому приведённое выше правило касается не только безопасности, но и отказа от агентов, у которых могут возникать проблемы обмена из-за несовместимости со старыми реализациями.

h1-case-adjust <from> <to>

h1-case-adjust <from> <to>

Задаёт преобразование регистра имени заголовка <from> в <to> перед отправкой клиентам или серверам HTTP/1, если такое преобразование включено. <from> должен быть в нижнем регистре, а <from> и <to> должны различаться только регистром. Если нужно изменить несколько имён заголовков, директиву можно повторять. Дубликаты запрещены. Если имён много, удобнее может быть “h1-case-adjust-file”. Обратите внимание: преобразование не применяется, пока для прокси не задано “option h1-case-adjust-bogus-client” или “option h1-case-adjust-bogus-server”.

Стандартного регистра имён заголовков нет: как указано в RFC7230, они нечувствительны к регистру. Поэтому приложения должны обрабатывать их без учёта регистра. Однако некоторые некорректные приложения нарушают стандарты и ошибочно полагаются на регистр, который чаще всего используют браузеры. Для HTTP/2 эта проблема критична, поскольку все имена заголовков должны передаваться в нижнем регистре; HAProxy следует тому же правилу. Все имена заголовков отправляются клиентам и серверам в нижнем регистре независимо от версии HTTP.

Для приложений, которые неправильно обрабатывают запросы или ответы, могут временно потребоваться такие обходные меры, меняющие регистр отправляемых им имён заголовков, пока приложение не будет исправлено. Обратите внимание: приложение, которому нужны такие обходные меры, может быть уязвимо к атакам с подменой границ содержимого и обязательно должно быть исправлено.

Пример:

global
  h1-case-adjust content-length Content-Length

См. “h1-case-adjust-file”, “option h1-case-adjust-bogus-client” и “option h1-case-adjust-bogus-server”.

h1-case-adjust-file <hdrs-file>

h1-case-adjust-file <hdrs-file>

Задаёт файл со списком пар ключ/значение для изменения регистра некоторых имён заголовков перед отправкой клиентам или серверам HTTP/1. В файле <hdrs-file> каждая строка должна содержать 2 имени заголовка. Первое должно быть в нижнем регистре, а оба имени должны различаться только регистром. Строки, начинающиеся с ‘#’, игнорируются, как и пустые строки. Начальные и конечные табуляции и пробелы удаляются. Дубликаты запрещены. Обратите внимание: преобразование не применяется, пока для прокси не задано “option h1-case-adjust-bogus-client” или “option h1-case-adjust-bogus-server”.

Если директива повторяется, обрабатывается только последняя. Она служит альтернативой “h1-case-adjust”, когда нужно изменить регистр многих имён заголовков. Прочитайте описание рисков, связанных с её использованием.

См. “h1-case-adjust”, “option h1-case-adjust-bogus-client” и “option h1-case-adjust-bogus-server”.

h2-workaround-bogus-websocket-clients

h2-workaround-bogus-websocket-clients

Отключает объявление клиентам о поддержке WebSocket по h2. Это позволяет обойти проблемы клиентов с реализацией относительно нового RFC8441, например Firefox 88. Чтобы клиенты могли автоматически перейти на http/1.1 для туннеля WebSocket, задайте поддержку h2 в строке bind с помощью “alpn” без явного ключевого слова “proto”. Если эта директива была включена ранее, её можно отключить, добавив перед ключевым словом “no”.

hard-stop-after <time>

hard-stop-after <time>

Задаёт максимальное время, отведённое на корректную плавную остановку.

Аргументы:

<time>  — максимальное время (по умолчанию в миллисекундах), в течение
        которого экземпляр продолжит работу после получения запроса
        мягкой остановки через сигнал SIGUSR1.

Позволяет гарантировать завершение экземпляра, даже если во время плавной остановки остаются открытые соединения, например при больших тайм-аутах прокси в режиме tcp. Применяется в режимах TCP и HTTP.

Пример:

global
  hard-stop-after 30s

См. также: grace

harden.reject-privileged-ports.tcp { on | off }

harden.reject-privileged-ports.tcp { on | off }
harden.reject-privileged-ports.quic { on | off }

Включает или отключает для каждого протокола защиту, запрещающую обмен с клиентами, которые используют привилегированные порты в качестве порта источника. Диапазон этих портов определён в RFC 6335. По умолчанию защита включена для QUIC, поскольку такое поведение подозрительно и может применяться для подмены источника или атак с усилением DNS/NTP.

http-err-codes [+-]<range>[,...] [...]

http-err-codes [+-]<range>[,...] [...]

Заменяет, сокращает или расширяет список кодов состояния, считающихся ошибкой для кодов завершения и счётчика “http_err_cnt” в таблицах привязок. По умолчанию ошибками считаются коды от 400 до 499. Однако некоторые пользователи предпочитают исключать отдельные коды в определённых условиях, особенно при учёте ошибок клиентов, например 404 в системах с динамически создаваемым содержимым. См. также “http-fail-codes” и “http_err_cnt”.

Диапазон без ‘+’ или ‘-’ заменяет существующий диапазон новым. Диапазон с начальным ‘+’ добавляется к существующему независимо от того, пересекаются они или нет. Диапазон с начальным ‘-’ удаляется из существующего. Диапазон задаётся числом от 100 до 599, после которого можно указать “-” и ещё одно число, не меньше первого, как верхнюю границу. Для одной операции добавления, удаления или замены можно указать несколько диапазонов через запятую.

Пример:

http-err-codes 400,402-444,446-480,490   # sets exactly these codes
http-err-codes 400-499 -450 +500         # sets 400 to 500 except 450
http-err-codes -450-459                  # removes 450 to 459 from range
http-err-codes +501,505                  # adds 501 and 505 to range

http-fail-codes [+-]<range>[,...] [...]

http-fail-codes [+-]<range>[,...] [...]

Заменяет, сокращает или расширяет список кодов состояния, считающихся сбоем для кодов завершения и счётчика “http_fail_cnt” в таблицах привязок. По умолчанию это коды от 500 до 599, кроме 501 и 505, которые могут быть вызваны клиентами. Обычно коды сбоев указывают на неспособность сервера обработать запрос. Некоторые пользователи предпочитают исключать коды в тех условиях, где известно, что они не относятся к сбоям, например 500 в некоторых средах SOAP, где этот код не означает ошибку сервера. Синтаксис точно такой же, как у описанного выше http-err-codes. См. также “http-err-codes” и “http_fail_cnt”.

insecure-fork-wanted

insecure-fork-wanted

По умолчанию HAProxy старается предотвратить любое создание потоков и процессов после запуска. Это особенно важно при использовании файлов Lua неизвестного происхождения и при работе с разрабатываемыми версиями, в которых ещё могут быть ошибки с неясными возможностями эксплуатации. В целом полезно гарантировать, что трафик не сможет вызвать непредвиденную фоновую активность. Однако эта защита мешает работе внешних проверок и может нарушать работу некоторых специфических сценариев Lua, которым необходим fork. Этот параметр отключает защиту. Обратите внимание: отключать её нежелательно, поскольку тогда уязвимость в библиотеке или самом HAProxy будет легче эксплуатировать. Кроме того, fork из Lua или любого другого места ненадёжен: дочерний процесс может случайно унаследовать блокировку, установленную другим потоком, и никогда не завершить операцию. Поэтому настоятельно рекомендуется никогда не использовать этот параметр, а задачи, требующие fork, пересмотреть и перенести на более безопасное решение, например использовать агентов вместо внешних проверок. Параметр поддерживает префикс “no” для отключения. Его также можно включить аргументом “-dI” в командной строке haproxy.

insecure-setuid-wanted

insecure-setuid-wanted

HAProxy не требуется запускать исполняемые файлы во время работы, кроме внешних проверок, от которых настоятельно рекомендуется отказаться. Более того, предполагается его изоляция в пустом chroot. Поэтому практически нет обоснованной причины разрешать запуск исполняемого файла с setuid без полного понимания пользователем рисков. Если HAProxy требуется вызывать внешние проверки или отключить chroot, эксплуатация уязвимости в библиотеке или самом HAProxy может привести к запуску внешней программы. В Linux процесс можно ограничить так, чтобы бит setuid любого такого исполняемого файла игнорировался. Это существенно снижает риск повышения привилегий; именно так HAProxy действует по умолчанию. Если это мешает внешней проверке, например использующей команду “ping”, защиту можно отключить, явно добавив эту директиву в секцию global. Если директива включена, её можно снова отключить, добавив перед ней ключевое слово “no”.

issuers-chain-path <dir>

issuers-chain-path <dir>

Задаёт каталог для загрузки цепочек сертификатов, используемых при достраивании цепочки издателя. Все файлы должны быть в формате PEM. Если для сертификата, загруженного через “crt” или “crt-list”, цепочка сертификатов не включена в PEM, HAProxy достроит её, когда издатель сертификата соответствует первому сертификату цепочки, загруженной через “issuers-chain-path”. Такие сертификаты цепочки также обычно называют промежуточными. Файл “crt” с PrivateKey+Certificate+IntermediateCA2+IntermediateCA1 можно заменить файлом с PrivateKey+Certificate. HAProxy достроит цепочку, если в каталоге “issuers-chain-path” есть файл с IntermediateCA2+IntermediateCA1. Все остальные сертификаты с тем же издателем будут совместно использовать эту цепочку в памяти.

Возможности OCSP могут использовать достроенную цепочку, если .issuer не использовался или цепочка не была предоставлена в PEM.

jwt.allow_none_alg

jwt.allow_none_alg

Разрешает JWT-токены с алгоритмом “none” в преобразователе ‘jwt_verify’. При включении этой опции такие токены всегда считаются действительными. По умолчанию неподписанные токены отклоняются как небезопасные (см. RFC8725 раздел 3.1 ).

jwt.decrypt_alg_list <list>

jwt.decrypt_alg_list <list>

Задаёт список алгоритмов, разрешённых в преобразователях jwt_decrypt_XXX. Токены JWT с неподдерживаемыми или отключёнными алгоритмами никогда не расшифровываются. Алгоритмы должны быть указаны в формате из раздела 4.1 RFC7518 и разделены двоеточиями. Специальное имя “ALL” включает все поддерживаемые алгоритмы; полный список см. в описании преобразователя “jwt_decrypt_jwk”. К имени алгоритма можно добавить ‘!’, чтобы явно отключить его. Обратите внимание: если “ALL” не указан, этот параметр отключает все алгоритмы, которые не перечислены явно.

Примеры:

# Enable all algorithms but the "ECDH-ES" one
jwt.decrypt_alg_list ALL:!ECDH-ES

# Only enable ECDH-ES algorithms
jwt.decrypt_alg_list ECDH-ES:ECDH-ES+A128KW:ECDH-ES+A192KW:ECDH-ES+A256KW

jwt.decrypt_enc_list <list>

jwt.decrypt_enc_list <list>

Задаёт список алгоритмов шифрования, разрешённых в преобразователях jwt_decrypt_XXX. Токены JWT с неподдерживаемыми или отключёнными алгоритмами шифрования никогда не расшифровываются. Алгоритмы должны быть указаны в формате из раздела 5.1 RFC7518 и разделены двоеточиями. Специальное имя “ALL” включает все поддерживаемые алгоритмы; полный список см. в описании преобразователя “jwt_decrypt_jwk”. К имени алгоритма можно добавить ‘!’, чтобы явно отключить его. Обратите внимание: если “ALL” не указан, этот параметр отключает все алгоритмы, которые не перечислены явно.

Примеры:

# Enable only AES GCM encrypting algorithms
jwt.decrypt_enc_list A128GCM:A192GCM:A256GCM

key-base <dir>

key-base <dir>

Задаёт каталог по умолчанию для загрузки закрытых ключей SSL, когда в директивах “key” используется относительный путь. Заданные абсолютные пути имеют приоритет; “key-base” в этом случае игнорируется. Этот параметр работает только со строкой load в crt-store.

limited-quic

limited-quic

Этот параметр необходимо использовать для явного включения слушающих сокетов QUIC, если haproxy собран с версией OpenSSL без поддержки QUIC. Он активирует внутренний слой совместимости haproxy, который должен быть выбран при сборке с помощью USE_QUIC_OPENSSL_COMPAT=1. Этот слой поддерживает большинство необходимых операций TLS, но не поддерживает QUIC 0-RTT.

Эта возможность предназначена прежде всего для OpenSSL до версии 3.5.2, где API QUIC отсутствовал или был реализован лишь частично. Слой совместимости можно включить и для версии 3.5.2 или новее, но, вероятно, это не требуется.

Если limited-quic задан, но слой совместимости не был выбран при сборке, параметр игнорируется без сообщения, а операции QUIC TLS выполняются средствами библиотеки TLS.

localpeer <name>

localpeer <name>

Задаёт имя локального экземпляра среди узлов peers. Оно игнорируется, если указан аргумент командной строки “-L” или директива использована после определений секций “peers”. В таких случаях при разборе конфигурации выводится предупреждение.

Этот параметр также задаёт переменную окружения HAPROXY_LOCALPEER. См. также “-L” в руководстве по управлению и секцию “peers” ниже.

log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]

log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
    [profile <prof>] <facility> [max level [min level]]

Добавляет глобальный сервер syslog. Можно задать несколько таких серверов. Они получают записи о запуске и завершении, а также все журналы прокси, настроенных с “log global”. Подробности см. в описании параметра “log” для прокси.

log-send-hostname [<string>]

log-send-hostname [<string>]

Задаёт поле имени хоста в заголовке syslog. Если указан необязательный параметр “string”, полю присваивается содержимое этой строки; иначе используется имя хоста системы. Обычно это нужно, если журналы не пересылаются через промежуточный сервер syslog, либо для изменения имени хоста, выводимого в журнале.

log-tag <string>

log-tag <string>

Задаёт этой строкой поле тега в заголовке syslog. По умолчанию используется имя программы при запуске из командной строки, обычно “haproxy”. Иногда это полезно для различения нескольких процессов на одном хосте. См. также директиву “log-tag” для отдельных прокси.

lua-load <file> [ <arg1> [ <arg2> [ ... ] ] ]

lua-load <file> [ <arg1> [ <arg2> [ ... ] ] ]

Эта глобальная директива загружает и выполняет файл Lua в общем контексте, видимом всем потокам. Любая переменная, заданная в таком контексте, видна из любого потока. Это самый простой и рекомендуемый способ загрузки программ Lua, но при большом числе вызовов Lua он плохо масштабируется: с глобальным состоянием одновременно может работать только один поток. Программа, загруженная таким способом, всегда видит 0 в переменной “core.thread”. Директиву можно использовать несколько раз.

Аргументы args доступны в файле Lua через приведённый ниже код в теле файла. Не забывайте, что индексы массивов Lua начинаются с 1. Переменная “local”, объявленная в файле, доступна во всём этом файле и недоступна в других файлах.

 local args = table.pack(...)

lua-load-per-thread <file> [ <arg1> [ <arg2> [ ... ] ] ]

lua-load-per-thread <file> [ <arg1> [ <arg2> [ ... ] ] ]

Эта глобальная директива загружает и выполняет файл Lua в каждом запущенном потоке. Глобальные переменные видимы только внутри потока, поэтому каждый поток может видеть своё значение. В программах, загруженных таким способом, настоятельно рекомендуется не использовать глобальные переменные. Для каждого потока загружается и инициализируется отдельная копия; всё выполняется последовательно, по возрастанию номеров потоков от 1 до nbthread. Если какие-то операции нужно выполнить только один раз, программе следует проверить переменную “core.thread”, чтобы определить, какой поток инициализируется. Загруженные таким способом программы выполняются параллельно во всех потоках и хорошо масштабируются. Это рекомендуемый способ загрузки простых функций, регистрирующих методы извлечения образцов, преобразователи, действия или службы, когда точно известно, что программа не зависит от глобальных переменных. Для простоты директива доступна и при использовании одного потока, и даже при отключённой поддержке потоков; в последнем случае она эквивалентна lua-load. Директиву можно использовать несколько раз.

Об использовании args см. lua-load.

lua-prepend-path <string> [<type>]

lua-prepend-path <string> [<type>]

Добавляет указанную строку с последующей точкой с запятой в начало переменной Lua package.<type>. <type> должен быть “path” или “cpath”. Если <type> не задан, по умолчанию используется “path”.

Пути Lua — списки шаблонов, разделённых точкой с запятой. Они определяют, как функция require пытается найти исходный файл библиотеки. Знаки вопроса (?) в шаблоне заменяются именем модуля. Путь проверяется слева направо, поэтому пути, добавленные в начало позже, проверяются раньше.

Например, если указать следующий путь:

lua-prepend-path /usr/share/haproxy-lua/?/init.lua
lua-prepend-path /usr/share/haproxy-lua/?.lua

При вызове require "example" Lua сначала пытается загрузить /usr/share/haproxy-lua/example.lua как сценарий. Если его нет, проверяется /usr/share/haproxy-lua/example/init.lua, а если нет и этого файла — пути по умолчанию.

Подробности см. в документации Lua: https://www.lua.org/pil/8.1.html .

master-worker (deprecated)

master-worker (deprecated)

Режим master-worker. Эквивалентен аргументу командной строки “-W”.

Это ключевое слово устарело; для запуска в режиме master-worker используйте “-W” или “-Ws”.

В этом режиме запускается главный процесс “master”, который после чтения конфигурации создаёт через fork рабочий процесс “worker” для обработки трафика. Главный процесс выполняет роль диспетчера процессов, следящего за рабочими процессами “workers”.

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

Режим master-worker совместим как с работой на переднем плане, так и с режимом демона.

По умолчанию, если рабочий процесс завершается с кодом ошибки, например из-за ошибки сегментации, все рабочие процессы принудительно завершаются, а главный процесс выходит. Это удобно сочетать с Restart=on-failure в файле модуля systemd для повторного запуска всех процессов. Чтобы отключить такое поведение, необходимо использовать ключевое слово “no-exit-on-failure”.

См. также “-W” в руководстве по управлению.

master-worker no-exit-on-failure

master-worker no-exit-on-failure

В режиме master-worker по умолчанию, если рабочий процесс завершается с кодом ошибки, например из-за ошибки сегментации, все рабочие процессы принудительно завершаются, а главный процесс выходит. Это удобно сочетать с Restart=on-failure в файле модуля systemd для повторного запуска всех процессов.

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

max-threads-per-group <number>

max-threads-per-group <number>

Задаёт максимальное число потоков в группе. Если число групп потоков не зафиксировано директивой “thread-groups”, haproxy создаёт столько групп, сколько нужно для запрошенного числа потоков. Минимальное значение — 1, максимальное — 64 в 64-битных системах или 32 в 32-битных. Меньшие значения снижают конкуренцию за общее состояние при атомарных операциях, но могут увеличить число сокетов, необходимых для всех слушателей и для хранения простаивающих соединений с бэкендами. Большие значения уменьшают эти затраты, но увеличивают использование CPU при конкуренции за ресурсы и снижают скорость установления соединений. Значение по умолчанию — 16: это лучший компромисс, выявленный экспериментально на разных системах, включая процессоры x86_64 нескольких производителей и большие системы Arm64, как на физическом оборудовании, так и под гипервизорами.

mworker-max-reloads <number>

mworker-max-reloads <number>

В режиме master-worker этот параметр ограничивает число перезагрузок, которые может пережить рабочий процесс. Если после перезагрузки он не завершился и число пережитых перезагрузок превысило указанное значение, процесс получает SIGTERM. Это помогает контролировать число рабочих процессов. См. также “show proc” в руководстве по управлению.

По умолчанию это значение равно 50.

nbthread <number>

nbthread <number>

Этот параметр доступен только при сборке с поддержкой потоков. Он запускает HAProxy с <number> потоками. “nbthread” работает и при запуске HAProxy на переднем плане. На некоторых платформах с поддержкой привязки к CPU значение “nbthread” по умолчанию автоматически принимается равным числу CPU, к которым процесс привязан при запуске. Поэтому число потоков можно легко регулировать из вызывающего процесса командами вроде “taskset” или “cpuset”. В остальных случаях по умолчанию используется 1. Значение по умолчанию показывается в выводе “haproxy -vv”. Обратите внимание: заданные здесь или автоматически определённые значения ограничиваются параметром “thread-hard-limit”, если он задан.

numa-cpu-mapping

numa-cpu-mapping

При работе на платформе с поддержкой NUMA позволяет директиве “cpu-policy” изучить топологию, выбрать оптимальный набор CPU и соответствующее число потоков. Если на конкретной архитектуре полученная привязка неоптимальна, её можно отключить записью ’no numa-cpu-mapping’. Автоматическая привязка также не применяется, если в конфигурации есть директива ’nbthread’, если привязка процесса уже задана, например директивой ‘cpu-map’ или утилитой taskset, либо если cpu-policy задано любое другое значение. См. также “cpu-map”, “cpu-policy”, “cpu-set”.

ocsp-update.disable [ on | off ]

ocsp-update.disable [ on | off ]

Полностью отключает ocsp-update в HAProxy. Любая конфигурация ocsp-update игнорируется. Значение по умолчанию — “off”. Подробности о механизме автоматического обновления см. в описании параметра “ocsp-update”.

ocsp-update.httpproxy <address>[:port]

ocsp-update.httpproxy <address>[:port]

Разрешает использовать прокси HTTP для обновлений OCSP. Работает только с HTTP; HTTPS не поддерживается. Этот параметр позволяет средству обновления OCSP отправлять абсолютный URI в запросе к прокси.

ocsp-update.maxdelay <number>

ocsp-update.maxdelay <number>
tune.ssl.ocsp-update.maxdelay <number> (deprecated)

Задаёт максимальный интервал между двумя автоматическими обновлениями одного ответа OCSP. Время задаётся в секундах; по умолчанию — 3600 (1 час). Значение должно быть больше “ocsp-update.mindelay”. Подробности о механизме автоматического обновления см. в описании параметра “ocsp-update”.

ocsp-update.mindelay <number>

ocsp-update.mindelay <number>
tune.ssl.ocsp-update.mindelay <number> (deprecated)

Задаёт минимальный интервал между двумя автоматическими обновлениями одного ответа OCSP. Время задаётся в секундах; по умолчанию — 300 (5 минут). Особенно полезно для ответов OCSP без явно заданного срока действия. Значение должно быть меньше “ocsp-update.maxdelay”. Подробности о механизме автоматического обновления см. в описании параметра “ocsp-update”.

ocsp-update.mode [ on | off ]

ocsp-update.mode [ on | off ]

Задаёт режим ocsp-update по умолчанию для всех сертификатов, используемых в конфигурации. Этот глобальный параметр может быть переопределён параметром “ocsp-update” в crt-list. По умолчанию он имеет значение “off”. Подробности о механизме автоматического обновления см. в описании параметра “ocsp-update”.

pidfile <pidfile>

pidfile <pidfile>

Записывает идентификаторы всех демонов в файл <pidfile> в режиме демона либо PID главного процесса в файл <pidfile> в режиме master-worker. Эквивалентен аргументу командной строки “-p”. Файл должен быть доступен пользователю, запускающему процесс. См. также “daemon” и “master-worker”.

pp2-never-send-local

pp2-never-send-local

В реализации протокола PROXY v2 в HAProxy вплоть до версии 2.1 была ошибка: для проверок работоспособности отправлялась команда PROXY вместо LOCAL. Это малозначительное отклонение, но оно вносит путаницу в журналы некоторых серверов. К сожалению, ошибку обнаружили очень поздно. Выяснилось, что некоторые серверы, возможно проверявшие свою реализацию протокола PROXY только с HAProxy, неправильно обрабатывают команду LOCAL и при проверках HAProxy постоянно остаются в состоянии “down”. В этом случае можно включить глобальный параметр, возвращающий прежнее ошибочное поведение, на время обращения к поставщикам затронутых компонентов и получения исправлений. По умолчанию параметр отключён и действует на все серверы с директивой “send-proxy-v2”.

presetenv <name> <value>

presetenv <name> <value>

Задаёт переменной окружения <name> значение <value>. Если переменная уже существует, она не перезаписывается. Изменения вступают в силу немедленно: следующая строка конфигурационного файла уже видит новое значение. См. также “setenv”, “resetenv” и “unsetenv”.

prealloc-fd

prealloc-fd

Однократно открывает максимальный файловый дескриптор, вызывая предварительное выделение структур данных ядра. Это предотвращает краткие паузы, возникающие при nbthread>1, когда HAProxy открывает файловый дескриптор и ядру требуется расширить свои структуры данных.

resetenv [<name> ...]

resetenv [<name> ...]

Удаляет все переменные окружения, кроме указанных в аргументе. Позволяет получить чистое управляемое окружение перед установкой новых значений через setenv или unsetenv. Обратите внимание: некоторые внутренние функции могут использовать переменные окружения, например функции работы со временем, а также OpenSSL и внешние проверки. Применять этот параметр необходимо крайне осторожно и только после полной проверки. Изменения вступают в силу немедленно: следующая строка конфигурационного файла уже видит новое окружение. См. также “setenv”, “presetenv” и “unsetenv”.

server-state-base <directory>

server-state-base <directory>

Задаёт префикс каталога, добавляемый перед именами всех файлов состояния серверов, которые не начинаются с ‘/’. См. также “server-state-file”, “load-server-state-from-file” и “server-state-file-name”.

server-state-file <file>

server-state-file <file>

Задаёт путь к файлу состояния серверов. Если путь начинается с косой черты (’/’), он считается абсолютным; иначе — относительным к каталогу “server-state-base”, если он задан, либо к текущему каталогу. Перед перезагрузкой HAProxy текущее состояние серверов можно сохранить командой статистики “show servers state”. Вывод этой команды должен быть записан в файл <file>. При запуске, до начала обработки трафика, HAProxy прочитает, загрузит и применит состояние каждого сервера, который найден в файле и присутствует в текущей рабочей конфигурации. См. также “server-state-base”, “show servers state”, “load-server-state-from-file” и “server-state-file-name”

set-dumpable [ on | off | libs ]

set-dumpable [ on | off | libs ]

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

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

• off: отключает ранее включённое создание дампов памяти.

• libs: включает создание дампов памяти со встроенной копией исполняемых файлов и библиотек, необходимых для отладки. Это может потребоваться разработчикам. В этом случае haproxy пытается загрузить в память библиотеки, от которых он зависит, и сохранить их там. Если процесс аварийно завершится, они попадут в дамп памяти, поэтому их больше не потребуется извлекать из файловой системы и не будет риска их несоответствия дампу. Для этого требуется от нескольких мегабайт до нескольких десятков мегабайт дополнительной RAM, поэтому на небольших системах этот режим лучше не использовать.

Этот параметр лучше оставить отключённым по умолчанию и включать только по запросу разработчика. По умолчанию он отключён. Без аргумента используется значение “on”. Если параметр включён, его всё равно можно принудительно отключить, добавив перед ним ключевое слово “no” или задав значение “off”. Он не влияет ни на производительность, ни на стабильность, но настойчиво пытается снова включить создание дампов памяти, которое могло быть отключено ограничением размера файла (ulimit -f), ограничением размера дампа (ulimit -c) или запретом создания дампа процесса после изменения его UID/GID (например, /proc/sys/fs/suid_dumpable в Linux). Создание дампов всё ещё могут ограничивать права доступа к текущему каталогу (следует проверить, из какого каталога запускается файл), права доступа к каталогу chroot (может потребоваться временно отключить директиву chroot или перенести его в отдельный каталог, доступный для записи) либо другие ограничения конкретной системы. Например, некоторые варианты Linux известны тем, что заменяют путь к файлу дампа по умолчанию путём к исполняемому файлу, которого даже нет в системе (следует проверить /proc/sys/kernel/core_pattern). Часто проблему решает простая запись “core”, “core.%p” или “/var/log/core/core.%p”. При включении этого параметра в ожидании повторного проявления редкой проблемы часто полезно сначала попытаться получить такой дамп, например отправив “kill -11” процессу “haproxy”, и проверить, что при завершении он оставляет дамп в ожидаемом месте.

set-var <var-name> <expr>

set-var <var-name> <expr>

Задаёт переменной уровня процесса ‘<var-name>’ результат вычисления выражения образца <expr>. Переменная ‘<var-name>’ может быть только переменной уровня процесса (с префиксом ‘proc.’). Работает точно так же, как действие ‘set-var’ в правилах TCP или HTTP, но выражение вычисляется при разборе конфигурации и переменная задаётся немедленно. В выражении разрешены только функции извлечения образцов и преобразователи, использующие внутренние данные, обычно ‘int(value)’ или ‘str(value)’. Можно также ссылаться на ранее выделенные переменные. Затем эти переменные будут доступны для чтения и изменения из обычных наборов правил.

Пример:

global
    set-var proc.current_state str(primary)
    set-var proc.prio int(100)
    set-var proc.threshold int(200),sub(proc.prio)

set-var-fmt <var-name> <fmt>

set-var-fmt <var-name> <fmt>

Задаёт переменной уровня процесса ‘<var-name>’ строку, полученную при вычислении формата журнала <fmt>. Переменная ‘<var-name>’ может быть только переменной уровня процесса (с префиксом ‘proc.’). Работает точно так же, как действие ‘set-var-fmt’ в правилах TCP или HTTP, но выражение вычисляется при разборе конфигурации и переменная задаётся немедленно. В выражении разрешены только функции извлечения образцов и преобразователи, использующие внутренние данные, обычно ‘int(value)’ или ‘str(value)’. Можно также ссылаться на ранее выделенные переменные. Затем эти переменные будут доступны для чтения и изменения из обычных наборов правил. Подробности о синтаксисе пользовательского формата журнала см. в разделе 8.2.6 .

Пример:

global
    set-var-fmt proc.current_state "primary"
    set-var-fmt proc.bootid        "%pid|%t"

setcap <name>[,<name>...]

setcap <name>[,<name>...]

Задаёт список полномочий, которые должны сохраняться при запуске и работе от имени пользователя без прав root (uid > 0) либо при запуске с uid 0 (root) и последующем переходе к пользователю без прав root. По умолчанию при смене uid теряются все права, но некоторые из них часто нужны при соединении с сервером с чужого адреса во время прозрачного проксирования либо при привязке к порту ниже 1024, например при использовании “tune.quic.fe.sock-per-conn default-on”. В результате такие конфигурации целиком работают с uid 0. Назначение полномочий обычно безопаснее, поскольку сохраняются только необходимые полномочия. Эта возможность зависит от ОС и включена только в Linux, если при сборке задано USE_LINUX_CAP=1. Список поддерживаемых полномочий также зависит от ОС и перечисляется в сообщении об ошибке, выводимом при передаче неверного или пустого имени полномочия. Можно передать несколько полномочий, разделённых запятыми. Из часто используемых полномочий “cap_net_raw” разрешает прозрачную привязку к чужому адресу, а “cap_net_bind_service” разрешает привязку к привилегированному порту и может использоваться QUIC. Если процесс запускается и работает от имени одного и того же пользователя без прав root, необходимые полномочия следует задать исполняемому файлу haproxy с помощью setcap вместе с этим ключевым словом. Подробнее о назначении полномочий исполняемому файлу haproxy см. в главе 13.1 о поддержке полномочий Linux в руководстве по управлению.

Пример:

global
    setcap cap_net_bind_service,cap_net_admin

setenv <name> <value>

setenv <name> <value>

Задаёт переменной окружения <name> значение <value>. Если переменная существует, она перезаписывается. Изменения вступают в силу немедленно: следующая строка конфигурационного файла уже видит новое значение. См. также “presetenv”, “resetenv” и “unsetenv”.

shm-stats-file <name>

shm-stats-file <name>

Эта директива включает использование разделяемой памяти для хранения статистических счётчиков. <name> передаётся как аргумент shm_open() для открытия разделяемой памяти в уникальном месте. Это также означает, что директива доступна только в системах с поддержкой shm_open(). При использовании SHM для статистики все счётчики фронтендов, бэкендов, слушателей и серверов, которые могут совместно использоваться, хранятся в SHM при условии, что для них задан GUID. При перезагрузке haproxy новый процесс пытается найти в SHM объекты, которые можно сопоставить с объектами конфигурации по GUID и типу, чтобы сохранить значения некоторых счётчиков при перезагрузке. При корректной остановке haproxy объекты SHM, напротив, освобождаются, то есть счётчики фактически сбрасываются. Для принудительного сброса можно также вручную удалить файл перед запуском нового процесса.

См. также “guid”, “guid-prefix” и “shm-stats-file-max-objects”

shm-stats-file-max-objects <number>

shm-stats-file-max-objects <number>

Задаёт максимальное число объектов, которые разделяемая память для общих счётчиков может хранить для каждой группы потоков. Значение напрямую связано с максимальным размером разделяемой памяти и используется для предварительного отображения shm заданного размера, чтобы избежать повторного отображения во время работы. По умолчанию используется 2k, что должно подходить для большинства конфигураций без риска чрезмерного использования памяти; при необходимости значение легко изменить. При запуске haproxy выдаст ошибку, если значение слишком мало для регистрации объектов, которые должны храниться в разделяемой памяти. Параметр имеет значение только при заданном “shm-stats-file”.

См. также “thread-groups”

ssl-default-bind-ciphers <ciphers>

ssl-default-bind-ciphers <ciphers>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов шифрования (наборов шифров), согласуемых при рукопожатии SSL/TLS вплоть до TLSv1.2, для всех строк “bind”, где такой список не задан явно. Формат строки определён в “man 1 ciphers” из справочных страниц OpenSSL. Справочную информацию и рекомендации см., например, в (https://wiki.mozilla.org/Security/Server_Side_TLS ) и (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Для настройки шифров TLSv1.3 см. ключевое слово “ssl-default-bind-ciphersuites”. Подробнее см. описание ключевого слова “bind”.

ssl-default-bind-ciphersuites <ciphersuites>

ssl-default-bind-ciphersuites <ciphersuites>

Этот параметр доступен только при сборке с поддержкой OpenSSL и использовании OpenSSL 1.1.1 или новее для сборки HAProxy. Он задаёт строку по умолчанию со списком алгоритмов шифрования (наборов шифров), согласуемых при рукопожатии TLSv1.3, для всех строк “bind”, где такой список не задан явно. Формат строки определён в разделе “ciphersuites” страницы “man 1 ciphers” из справочных страниц OpenSSL. Для настройки шифров TLSv1.2 и более ранних версий см. ключевое слово “ssl-default-bind-ciphers”. Этот параметр может принимать наборы шифров TLSv1.2, однако такое поведение не документировано и не рекомендуется, поскольку оно может быть непоследовательным или ошибочным. Наборы шифров TLSv1.3 по умолчанию в OpenSSL: “TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256”

TLSv1.3 поддерживает только 5 наборов шифров:

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_CCM_SHA256
• TLS_AES_128_CCM_8_SHA256

Подробнее см. описание ключевого слова “bind”.

Пример:

global
    ssl-default-bind-ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
    ssl-default-bind-ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

ssl-default-bind-client-sigalgs <sigalgs>

ssl-default-bind-client-sigalgs <sigalgs>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов подписи для аутентификации клиента для всех строк “bind”, где такой список не задан явно. Формат строки — список алгоритмов подписи, разделённых двоеточиями. Каждый алгоритм подписи можно записать в одной из двух форм: имя схемы подписи TLS1.3 (“rsa_pss_rsae_sha256”) либо алгоритм открытого ключа + алгоритм хеширования (“ECDSA+SHA256”). Список может содержать обе формы. Подробнее о формате см. SSL_CTX_set1_client_sigalgs(3). Список алгоритмов подписи также приведён в разделе 4.2.3 RFC8446 и в файле ssl/t1_lib.c в OpenSSL. Этот параметр неприменим к TLSv1.1 и более ранним версиям протокола, поскольку в них алгоритмы подписи отдельно не согласуются. Изменять этот параметр не рекомендуется, если не требуется совместимость с промежуточным сетевым устройством.

ssl-default-bind-curves <curves>

ssl-default-bind-curves <curves>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов эллиптических кривых (набором кривых), согласуемых при рукопожатии SSL/TLS с ECDHE. Формат строки — список имён кривых, разделённых двоеточиями. Подробнее см. описание ключевого слова “bind”.

ssl-default-bind-options [<option>]...

ssl-default-bind-options [<option>]...

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт параметры ssl-options по умолчанию, принудительно применяемые ко всем строкам “bind”. Доступные параметры см. в описании ключевого слова “bind”.

Пример:

global
   ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets

ssl-default-bind-sigalgs <sigalgs>

ssl-default-bind-sigalgs <sigalgs>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов подписи, согласуемых при рукопожатии TLSv1.2 и TLSv1.3, для всех строк “bind”, где такой список не задан явно. Формат строки — список алгоритмов подписи, разделённых двоеточиями. Каждый алгоритм подписи можно записать в одной из двух форм: имя схемы подписи TLS1.3 (“rsa_pss_rsae_sha256”) либо алгоритм открытого ключа + алгоритм хеширования (“ECDSA+SHA256”). Список может содержать обе формы. Подробнее о формате см. SSL_CTX_set1_sigalgs(3). Список алгоритмов подписи также приведён в разделе 4.2.3 RFC8446 и в файле ssl/t1_lib.c в OpenSSL. Этот параметр неприменим к TLSv1.1 и более ранним версиям протокола, поскольку в них алгоритмы подписи отдельно не согласуются. Изменять этот параметр не рекомендуется, если не требуется совместимость с промежуточным сетевым устройством.

ssl-default-server-ciphers <ciphers>

ssl-default-server-ciphers <ciphers>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов шифрования, согласуемых при рукопожатии SSL/TLS с сервером вплоть до TLSv1.2, для всех строк “server”, где такой список не задан явно. Формат строки определён в “man 1 ciphers” из справочных страниц OpenSSL. Справочную информацию и рекомендации см., например, в (https://wiki.mozilla.org/Security/Server_Side_TLS ) и (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Для настройки шифров TLSv1.3 см. ключевое слово “ssl-default-server-ciphersuites”. Подробнее см. описание ключевого слова “server”.

ssl-default-server-ciphersuites <ciphersuites>

ssl-default-server-ciphersuites <ciphersuites>

Этот параметр доступен только при сборке с поддержкой OpenSSL и использовании OpenSSL 1.1.1 или новее для сборки HAProxy. Он задаёт строку по умолчанию со списком алгоритмов шифрования, согласуемых при рукопожатии TLSv1.3 с сервером, для всех строк “server”, где такой список не задан явно. Формат строки определён в разделе “ciphersuites” страницы “man 1 ciphers” из справочных страниц OpenSSL. Для настройки шифров TLSv1.2 и более ранних версий см. ключевое слово “ssl-default-server-ciphers”. Подробнее см. описание ключевого слова “server”.

ssl-default-server-client-sigalgs <sigalgs>

ssl-default-server-client-sigalgs <sigalgs>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов подписи для аутентификации клиента для всех строк “server”, где такой список не задан явно. Формат строки — список алгоритмов подписи, разделённых двоеточиями. Каждый алгоритм подписи можно записать в одной из двух форм: имя схемы подписи TLS1.3 (“rsa_pss_rsae_sha256”) либо алгоритм открытого ключа + алгоритм хеширования (“ECDSA+SHA256”). Список может содержать обе формы. Подробнее о формате см. SSL_CTX_set1_client_sigalgs(3). Список алгоритмов подписи также приведён в разделе 4.2.3 RFC8446 и в файле ssl/t1_lib.c в OpenSSL. Этот параметр неприменим к TLSv1.1 и более ранним версиям протокола, поскольку в них алгоритмы подписи отдельно не согласуются. Изменять этот параметр не рекомендуется, если не требуется совместимость с промежуточным сетевым устройством.

ssl-default-server-curves <curves>

ssl-default-server-curves <curves>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов эллиптических кривых (набором кривых), согласуемых при рукопожатии SSL/TLS с ECDHE. Формат строки — список имён кривых, разделённых двоеточиями. Подробнее см. описание ключевого слова “server”.

ssl-default-server-options [<option>]...

ssl-default-server-options [<option>]...

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт параметры ssl-options по умолчанию, принудительно применяемые ко всем строкам “server”. Доступные параметры см. в описании ключевого слова “server”.

ssl-default-server-sigalgs <sigalgs>

ssl-default-server-sigalgs <sigalgs>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку по умолчанию со списком алгоритмов подписи, согласуемых при рукопожатии TLSv1.2 и TLSv1.3, для всех строк “server”, где такой список не задан явно. Формат строки — список алгоритмов подписи, разделённых двоеточиями. Каждый алгоритм подписи можно записать в одной из двух форм: имя схемы подписи TLS1.3 (“rsa_pss_rsae_sha256”) либо алгоритм открытого ключа + алгоритм хеширования (“ECDSA+SHA256”). Список может содержать обе формы. Подробнее о формате см. SSL_CTX_set1_sigalgs(3). Список алгоритмов подписи также приведён в разделе 4.2.3 RFC8446 и в файле ssl/t1_lib.c в OpenSSL. Этот параметр неприменим к TLSv1.1 и более ранним версиям протокола, поскольку в них алгоритмы подписи отдельно не согласуются. Изменять этот параметр не рекомендуется, если не требуется совместимость с промежуточным сетевым устройством.

ssl-dh-param-file <file>

ssl-dh-param-file <file>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт параметры DH по умолчанию, используемые при рукопожатии SSL/TLS с обменом ключами на основе эфемерного алгоритма Диффи — Хеллмана (DHE), для всех строк “bind”, где они не заданы явно. Их переопределяют пользовательские параметры DH из файла сертификата bind, если они там есть. Если пользовательские параметры DH не заданы ни с помощью ssl-dh-param-file, ни непосредственно в файле сертификата, шифры DHE не используются, если не задан tune.ssl.default-dh-param. В последнем случае используются предопределённые параметры DH указанного размера. Пользовательские параметры считаются более безопасными, поэтому рекомендуется использовать их. Пользовательские параметры DH можно создать командой OpenSSL “openssl dhparam <size>”, где размер следует выбирать не менее 2048, поскольку 1024-битные параметры DH больше не следует считать безопасными.

ssl-passphrase-cmd <cmd> <args> ...

ssl-passphrase-cmd <cmd> <args> ...

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он позволяет задать полную командную строку, вызываемую при загрузке зашифрованного сертификата во время инициализации. Команда может быть сценарием или любой другой программой. Первым параметром ей передаётся путь к зашифрованному закрытому ключу, затем заданные пользователем параметры “args”; ей следует вывести в стандартный вывод парольную фразу, позволяющую расшифровать закрытый ключ. Для каждого нового зашифрованного закрытого ключа, загружаемого при инициализации, HAProxy сначала пробует расшифровать его всеми другими уже известными парольными фразами и снова вызывает команду получения парольной фразы, только если ни одна из них не подошла.

ssl-propquery <query>

ssl-propquery <query>

Этот параметр доступен только при сборке с поддержкой OpenSSL версии не ниже 3.0. Он позволяет задать строку свойств по умолчанию, используемую при получении алгоритмов у провайдеров. Работает так же, как параметр openssl propquery, и использует тот же синтаксис (описан в https://www.openssl.org/docs/man3.0/man7/property.html ). Например, если загружены два провайдера, foo и default, запрос propquery “?provider=foo” позволяет по умолчанию выбирать реализации алгоритмов из провайдера foo и обращаться к реализации провайдера default, если нужная реализация не найдена.

ssl-provider <name>

ssl-provider <name>

Этот параметр доступен только при сборке с поддержкой OpenSSL версии не ниже 3.0. Он позволяет загрузить провайдер во время инициализации. При успешной загрузке HAProxy может использовать любые возможности, предоставляемые этим провайдером. В конфигурационном файле можно задать несколько параметров ‘ssl-provider’. Провайдеры загружаются в порядке их появления.

Обратите внимание: явная загрузка провайдера не позволяет OpenSSL автоматически загрузить провайдер ‘default’. OpenSSL также позволяет задать провайдеры, которые следует загрузить, непосредственно в своём конфигурационном файле (например, openssl.cnf), поэтому для их загрузки необязательно использовать параметр ‘ssl-provider’. Команда CLI “show ssl providers” позволяет показать все успешно загруженные провайдеры.

Путь поиска провайдеров OpenSSL по умолчанию можно найти в выводе команды “openssl version -a”. Если провайдер находится в другом каталоге, можно задать переменную окружения OPENSSL_MODULES, указав в ней каталог с провайдером.

См. также “ssl-propquery” и “ssl-provider-path”.

ssl-provider-path <path>

ssl-provider-path <path>

Этот параметр доступен только при сборке с поддержкой OpenSSL версии не ниже 3.0. Он позволяет задать путь, по которому OpenSSL ищет провайдеры. Работает так же, как переменная окружения OPENSSL_MODULES. Используется для всех последующих параметров ‘ssl-provider’ до задания нового ‘ssl-provider-path’. См. также “ssl-provider”.

ssl-load-extra-del-ext

ssl-load-extra-del-ext

Этот параметр позволяет настроить способ поиска дополнительных файлов SSL в HAProxy. По умолчанию HAProxy добавляет новое расширение к имени файла (например, для “foobar.crt” загружает “foobar.crt.key”). При включённом параметре HAProxy удаляет расширение перед добавлением нового (например, для “foobar.crt” загружает “foobar.key”).

Для работы этого параметра файл crt должен иметь расширение “.crt”.

Этот параметр несовместим с расширениями пакетов сертификатов (.ecdsa, .rsa. .dsa) и не пытается удалять их.

По умолчанию этот параметр отключён. См. также “ssl-load-extra-files”.

ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*

ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*

Этот параметр изменяет способ поиска файлов, не указанных явно, при загрузке сертификатов SSL в HAProxy. Он применяется к сертификатам строк “bind” и “server”, однако некоторые дополнительные файлы не влияют на работу сертификатов строк “server”.

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

“none”: загружать только файлы, указанные в конфигурации. Не пытаться загружать пакет сертификатов, если файл отсутствует. При загрузке каталога не пытаться объединять сертификаты с одинаковым базовым именем в пакет.

“all”: поведение по умолчанию; пытаться загрузить всё: пакеты сертификатов, sctl, ocsp, issuer, key.

“bundle”: если файл, указанный в конфигурации, отсутствует, HAProxy пытается загрузить пакет сертификатов. Пакеты сертификатов поддерживаются только на стороне фронтенда и не работают для сертификатов бэкенда.

Начиная с HAProxy 2.3 пакеты больше не загружаются в одно хранилище сертификатов OpenSSL: каждый сертификат загружается в отдельное хранилище, что эквивалентно объявлению нескольких “crt”. Для этого требуется OpenSSL 1.1.1. Следовательно, пакеты теперь используются только для обратной совместимости и больше не обязательны для гибридной конфигурации bind с RSA/ECC.

Чтобы объединить эти файлы PEM в пакет сертификатов, распознаваемый HAProxy, их нужно назвать следующим образом: все файлы PEM в пакете должны иметь одинаковое базовое имя и суффикс, обозначающий тип ключа. Сейчас поддерживаются три суффикса: rsa, dsa и ecdsa. Например, если у www.example.com есть два файла PEM, RSA и ECDSA, они должны называться “example.pem.rsa” и “example.pem.ecdsa”. Первая часть имени файла произвольна; имеет значение только суффикс. Для загрузки этого пакета в HAProxy следует указать только базовое имя:

Пример: bind :8443 ssl crt example.pem

Обратите внимание: суффикс не передаётся HAProxy; это указывает HAProxy, что нужно искать пакет сертификатов.

HAProxy загружает все файлы PEM пакета так, будто каждый из них задан отдельно в нескольких “crt”.

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

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

При объединении нескольких сертификатов в пакет поддерживаются файлы OCSP (.ocsp), файлы издателя (.issuer), Certificate Transparency (.sctl) и закрытые ключи (.key).

“sctl”: пытаться загрузить “<basename>.sctl” для каждого ключевого слова crt. Если файл указан для сертификата бэкенда, он загружается, но не влияет на работу.

“ocsp”: пытаться загрузить “<basename>.ocsp” для каждого ключевого слова crt. Если файл указан для сертификата бэкенда, он загружается, но не влияет на работу.

“issuer”: пытаться загрузить “<basename>.issuer”, если издатель файла OCSP не указан в файле PEM. Если файл указан для сертификата бэкенда, он загружается, но не влияет на работу.

“key”: если закрытый ключ отсутствует в файле PEM, пытаться загрузить файл “<basename>.key”, содержащий закрытый ключ.

Поведение по умолчанию — “all”.

Пример:

ssl-load-extra-files bundle sctl
ssl-load-extra-files sctl ocsp issuer
ssl-load-extra-files none

См. также: “crt”, раздел 5.1 о параметрах bind и раздел 5.2 о параметрах server.

ssl-security-level <number>

ssl-security-level <number>

Эта директива позволяет выбрать уровень безопасности OpenSSL, описанный в https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html . Уровень безопасности применяется ко всем контекстам SSL в HAProxy. Поддерживаются только значения от 0 до 5.

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

Для этой директивы требуется OpenSSL версии не ниже 1.1.1.

ssl-server-verify [none|required]

ssl-server-verify [none|required]

Поведение проверки SSL по умолчанию на стороне серверов. Если задано ’none’, сертификаты серверов не проверяются. Значение по умолчанию — ‘required’, если оно не переопределено параметром командной строки ‘-dV’.

ssl-skip-self-issued-ca

ssl-skip-self-issued-ca

CA, выпустивший сертификат для самого себя, он же корневой CA x509, служит якорем для проверки цепочки: серверу нет смысла отправлять его, а у клиента он должен быть. Стандартная конфигурация не должна включать такой CA в файл PEM. Этот параметр позволяет оставить такой CA в файле PEM, не отправляя его клиенту. Это позволяет предоставить издателя для ocsp без файла ‘.issuer’ и использовать его совместно с ‘issuers-chain-path’. Это касается всех сертификатов без промежуточных сертификатов. Для BoringSSL параметр бесполезен: .issuer игнорируется, поскольку механизму ocsp он не нужен. Требуется OpenSSL версии не ниже 1.0.2.

stats calculate-max-counters [on|off]

stats calculate-max-counters [on|off]

Включает или отключает вычисление максимальных значений статистических счётчиков. Если они не нужны, их отключение может немного повысить производительность. По умолчанию — on.

stats maxconn <connections>

stats maxconn <connections>

По умолчанию сокет статистики ограничен 10 одновременными соединениями. Изменить это значение можно с помощью “stats maxconn”.

stats socket [<address:port>|<path>] [param*]

stats socket [<address:port>|<path>] [param*]

Привязывает сокет UNIX к <path> или адрес TCPv4/v6 к <address:port>. Соединения с этим сокетом позволяют получать различные статистические данные и даже выполнять некоторые команды для изменения параметров во время работы. Подробнее см. раздел 9.3 «Команды Unix-сокета» руководства по управлению.

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

stats timeout <timeout, in milliseconds>

stats timeout <timeout, in milliseconds>

Тайм-аут сокета статистики по умолчанию составляет 10 секунд. Изменить его можно с помощью “stats timeout”. Значение должно передаваться в миллисекундах либо с суффиксом единицы времени из набора { us, ms, s, m, h, d }.

stats-file <path>

stats-file <path>

Путь к созданному файлу stats-file haproxy. При запуске haproxy предварительно загружает значения из него во внутренние счётчики. Для создания такого файла stats-file используется команда CLI “dump stats-file”. Подробнее см. руководство по управлению.

stress-level <level>

stress-level <level>

Включает альтернативный код для стрессовой нагрузки на исполняемый файл haproxy. Уровень — целое число от 0 до 9. Значение по умолчанию 0 отключает любое выполнение стрессового кода. Уровни от 1 до 9 увеличивают стрессовую нагрузку на исполняемый файл haproxy. Обратите внимание: любое положительное значение может существенно снизить производительность. Поэтому этот режим никогда не следует включать, кроме как для отладки по запросу разработчика.

strict-limits

strict-limits

Вызывает отказ при запуске процесса в случае неудачного вызова setrlimit. HAProxy пытается установить наилучшие ограничения setrlimit согласно расчётам. Если это не удаётся, он выводит предупреждение. Этот параметр обеспечивает явный отказ HAProxy при невозможности установить эти ограничения. По умолчанию включён. Его всё равно можно принудительно отключить, добавив перед ним ключевое слово “no”.

thread-group <group> [<thread-range>...]

thread-group <group> [<thread-range>...]

Этот параметр доступен только при сборке с поддержкой потоков. Он перечисляет потоки, которые входят в группу потоков <group>. Нумерация потоков и групп начинается с 1. Диапазоны потоков задаются либо отдельными номерами, либо нижней и верхней границами, разделёнными дефисом ‘-’ (например, “1-16”). Нераспределённые потоки автоматически назначаются группам потоков, которые ещё не распределены; группы, заданные этой директивой, никогда не получают больше потоков, чем указано. Повторное определение одной и той же группы заменяет предыдущие определения новым. См. также “nbthread” и “thread-groups”.

thread-groups <number>

thread-groups <number>

Этот параметр доступен только при сборке с поддержкой потоков. Он разбивает потоки HAProxy на <number> независимых групп. В настоящее время значение по умолчанию — 1. Группы потоков позволяют уменьшить объём совместно используемых данных между потоками и тем самым снизить конкуренцию за ресурсы ценой некоторой дополнительной настройки. Это также единственный способ использовать больше 64 потоков, поскольку в каждой группе можно настроить до 64 потоков. Максимальное число групп задаётся при компиляции и по умолчанию равно 16. См. также “nbthread”.

thread-hard-limit <number>

thread-hard-limit <number>

Этот параметр задаёт предел числа потоков, определённого автоматически или заданного в конфигурации. Особенно полезен в ОС с автоматическим определением числа потоков, когда в универсальных переносимых конфигурациях требуется меньше потоков, чем CPU. Параметр “nbthread” задаёт число потоков, которое при превышении числа доступных CPU приводит к предупреждению и низкой производительности, тогда как thread-hard-limit лишь ограничивает максимальное значение и автоматически не допускает превышения этого числа потоков, но не увеличивает меньшие значения. Если “nbthread” принудительно задан выше этого предела, приоритет имеет thread-hard-limit, а предупреждение позволяет исправить ошибку конфигурации. По умолчанию ограничения нет. См. также “nbthread”.

uid <number>

uid <number>

Изменяет идентификатор пользователя процесса на <number>. Рекомендуется выделить этот идентификатор пользователя для HAProxy или небольшой группы сходных демонов. Для возможности перехода к другому пользователю HAProxy должен быть запущен с правами суперпользователя. См. также “gid” и “user”.

ulimit-n <number>

ulimit-n <number>

Задаёт максимальное число файловых дескрипторов на процесс равным <number>. По умолчанию оно вычисляется автоматически, поэтому использовать этот параметр не рекомендуется. Если нужно лишь ограничить число файловых дескрипторов, лучше использовать “fd-hard-limit”.

Обратите внимание: динамические серверы не учитываются в этом автоматическом расчёте ресурсов. Если их много, может потребоваться задать значение вручную.

См. также: fd-hard-limit, maxconn

unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] [ group <group> ] [ gid <gid> ]

Задаёт общие параметры слушающих сокетов UNIX, объявленных в директивах “bind”. Это в основном упрощает объявление таких сокетов UNIX и снижает риск ошибок, поскольку эти параметры обычно необходимы, но зависят от процесса. Параметр <prefix> позволяет принудительно сделать все пути сокетов относительными к этому каталогу. Это может понадобиться для доступа к chroot другого компонента. Обратите внимание: эти пути разрешаются до перехода самого HAProxy в chroot, поэтому они абсолютные. Параметры <mode>, <user>, <uid>, <group> и <gid> имеют тот же смысл, что и одноимённые параметры директивы “bind”. Если заданы оба варианта, приоритет имеет директива “bind”, то есть параметры “unix-bind” можно считать значениями по умолчанию для всего процесса.

unsetenv [<name> ...]

unsetenv [<name> ...]

Удаляет переменные окружения, указанные в аргументах. Это может быть полезно для сокрытия конфиденциальной информации, иногда наследуемой из окружения пользователя во время некоторых операций. Несуществующие переменные молча игнорируются, поэтому после операции гарантированно не остаётся ни одной из указанных переменных. Изменения вступают в силу немедленно: следующая строка конфигурационного файла уже не видит эти переменные. См. также “setenv”, “presetenv” и “resetenv”.

user <user name>

user <user name>

Аналогично “uid”, но используется UID пользователя с именем <user name> из /etc/passwd. См. также “uid” и “group”.

node <name>

node <name>

Как и в именах DNS, разрешены только буквы, цифры, дефис и подчёркивание.

Эта директива полезна в конфигурациях HA, где два или более процесса или сервера используют один IP-адрес. Разные значения node-name на всех узлах позволяют сразу определить, какой сервер обрабатывает трафик.

wurfl-cache-size <size>

wurfl-cache-size <size>

Задаёт размер кэша агентов пользователя WURFL. Для ускорения поиска уже обработанные агенты пользователя хранятся в кэше LRU:

• “0” : кэш не используется.
• <size> : размер кэша lru в элементах.

Обратите внимание: этот параметр доступен только при сборке HAProxy с USE_WURFL=1.

wurfl-data-file <file path>

wurfl-data-file <file path>

Путь к файлу данных WURFL для служб распознавания устройств. HAProxy следует иметь доступ к этому файлу с соответствующими правами.

Обратите внимание: этот параметр доступен только при сборке HAProxy с USE_WURFL=1.

wurfl-information-list [<capability>]*

wurfl-information-list [<capability>]*

Разделённый пробелами список характеристик WURFL, виртуальных характеристик и имён свойств, которые предполагается использовать в добавляемых заголовках. Полный список имён характеристик и виртуальных характеристик доступен на сайте Scientiamobile:

https://www.scientiamobile.com/wurflCapability

Допустимые свойства WURFL:

• wurfl_id: содержит идентификатор распознанного устройства.

• wurfl_root_id: содержит корневой идентификатор распознанного устройства.

• wurfl_isdevroot: указывает, является ли распознанное устройство корневым. Возможные значения — “TRUE” и “FALSE”.

• wurfl_useragent: исходный агент пользователя, переданный в этом веб-запросе.

• wurfl_api_version: содержит строку с текущей используемой версией API Libwurfl.

• wurfl_info: строка с информацией о разобранном файле wurfl.xml и его полном пути.

• wurfl_last_load_time: содержит временную метку UNIX последней успешной загрузки WURFL.

• wurfl_normalized_useragent: нормализованный агент пользователя.

Обратите внимание: этот параметр доступен только при сборке HAProxy с USE_WURFL=1.

wurfl-information-list-separator <char>

wurfl-information-list-separator <char>

Символ для разделения значений в заголовке ответа с результатами WURFL. Если не задан, по умолчанию используется запятая (’,’).

Обратите внимание: этот параметр доступен только при сборке HAProxy с USE_WURFL=1.

wurfl-patch-file [<file path>]

wurfl-patch-file [<file path>]

Список путей к файлам исправлений WURFL. Обратите внимание: исправления загружаются при запуске, то есть до перехода в chroot.

Обратите внимание: этот параметр доступен только при сборке HAProxy с USE_WURFL=1.

3.2. Настройка производительности

busy-polling

busy-polling

В некоторых ситуациях, особенно при работе с малой задержкой на процессорах с переменной частотой или внутри виртуальных машин, всякий раз, когда процесс ожидает ввода-вывода через механизм опроса, процессор засыпает либо надолго передаётся другой VM, что вызывает чрезмерно высокие задержки. Этот параметр решает проблему, предотвращая засыпание процессора за счёт постоянного использования нулевого тайм-аута в механизмах опроса. Это значительно сокращает задержку (наблюдалось снижение на 30–100 микросекунд), но создаёт риск перегрева процессора. Параметр можно использовать и с потоками; тогда неверно привязанные потоки могут сильно конкурировать, ухудшая производительность и повышая значения полей CPU stolen в выводе “show info”, которые указывают на неправильно настроенные потоки. При использовании этого параметра важно не запускать процесс на том же процессоре, где обрабатываются сетевые прерывания. Также лучше не использовать его для нескольких потоков CPU, разделяющих одно ядро. По умолчанию параметр отключён. Если он включён, его всё равно можно принудительно отключить, добавив перед ним ключевое слово “no”. Механизмы опроса “select” и “poll” игнорируют этот параметр.

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

max-spread-checks <delay in milliseconds>

max-spread-checks <delay in milliseconds>

По умолчанию HAProxy пытается распределить начало проверок работоспособности в пределах наименьшего интервала проверок среди всех серверов группы. Это позволяет избежать чрезмерной нагрузки на службы, работающие на одном сервере. Но при больших интервалах проверок (10 секунд или больше) последние серверы группы начинают проверяться с задержкой, что может стать проблемой. Этот параметр задаёт верхнюю границу задержки между первой и последней проверкой, даже если интервалы проверок серверов больше. Однако если серверы используют меньшие интервалы, они соблюдаются.

maxcompcpuusage <number>

maxcompcpuusage <number>

Задаёт максимальное использование CPU, при достижении которого HAProxy прекращает сжатие новых запросов или снижает уровень сжатия текущих запросов. Работает как ‘maxcomprate’, но измеряет использование CPU вместо пропускной способности входящих данных. Значение выражается в процентах CPU, используемого HAProxy. Значение 100 отключает ограничение. Значение по умолчанию — 100. Меньшее значение не позволяет сжатию замедлять весь процесс и создавать высокие задержки.

maxcomprate <number>

maxcomprate <number>

Задаёт максимальную скорость входящих данных для сжатия на процесс равной <number> килобайт в секунду. Если максимум достигнут, уровень сжатия каждого потока снижается во время его обработки. Если максимум достигнут в начале потока, этот поток совсем не сжимается. Если максимум не достигнут, уровень сжатия повышается вплоть до tune.comp.maxlevel. Нулевое значение означает отсутствие ограничения; это значение по умолчанию.

maxconn <number>

maxconn <number>

Задаёт максимальное число одновременных соединений на процесс равным <number>. Эквивалентно аргументу командной строки “-n”. Значение, переданное аргументом “-n”, имеет приоритет над maxconn в секции global. Процесс HAProxy также может быть собран с переменной времени компиляции SYSTEM_MAXCONN, которая тогда служит системным максимумом maxconn. Аргумент командной строки “-n” также позволяет во время работы обойти ограничение SYSTEM_MAXCONN, если оно задано. При достижении maxconn прокси прекращают принимать соединения. Мягкий предел файловых дескрипторов процесса (его можно узнать командой “ulimit -n”) автоматически подстраивается под заданный maxconn. См. также “ulimit-n”. Примечание: на некоторых платформах механизм опроса “select” не может надёжно использовать больше 1024 файловых дескрипторов. Если платформа поддерживает только select и при запуске сообщает “select FAILED”, нужно уменьшать maxconn, пока запуск не станет успешным (обычно до значения чуть ниже 500). Если maxconn не задан, он автоматически вычисляется по текущим ограничениям файловых дескрипторов, выводимым командой “ulimit -nH” (берётся максимум из жёсткого и мягкого значений). Затем автоматически выбранное значение может быть уменьшено параметром “fd-hard-limit” и ограничением памяти, если оно задано параметром командной строки “-m”. Автоматическое значение также зависит от размера буфера, памяти для сжатия, размера кэша SSL, использования SSL и соответствующего maxsslconn, который тоже может выбираться автоматически.

См. также: fd-hard-limit, ulimit-n

maxconnrate <number>

maxconnrate <number>

Задаёт максимальное число соединений в секунду на процесс равным <number>. При достижении предела прокси прекращают принимать соединения. Параметр позволяет ограничить общую производительность независимо от возможностей каждого фронтенда. Следует учитывать, что он пригоден только как мера защиты службы: при достижении предела ресурсы не обязательно распределяются между фронтендами справедливо, поэтому полезно также ограничить каждый фронтенд значением, близким к его ожидаемой доле. Кроме того, уменьшение tune.maxaccept может повысить справедливость распределения.

maxpipes <number>

maxpipes <number>

Задаёт максимальное число каналов на процесс равным <number>. Сейчас каналы используются только для tcp splicing средствами ядра. Поскольку канал содержит два файловых дескриптора, значение “ulimit-n” соответственно увеличивается. Значение по умолчанию — maxconn/4, чего, по-видимому, более чем достаточно для большинства случаев интенсивного использования. Код splice динамически выделяет и освобождает каналы и может вернуться к обычному копированию, поэтому слишком низкое значение может повлиять лишь на производительность.

maxsessrate <number>

maxsessrate <number>

Задаёт максимальное число сеансов в секунду на процесс равным <number>. При достижении предела прокси прекращают принимать соединения. Параметр позволяет ограничить общую производительность независимо от возможностей каждого фронтенда. Следует учитывать, что он пригоден только как мера защиты службы: при достижении предела ресурсы не обязательно распределяются между фронтендами справедливо, поэтому полезно также ограничить каждый фронтенд значением, близким к его ожидаемой доле. Кроме того, уменьшение tune.maxaccept может повысить справедливость распределения.

maxsslconn <number>

maxsslconn <number>

Задаёт максимальное число одновременных соединений SSL на процесс равным <number>. По умолчанию отдельного ограничения для SSL нет, то есть глобальное значение maxconn применяется ко всем соединениям. Этот предел не позволяет openssl использовать слишком много памяти и аварийно завершаться, когда malloc возвращает NULL (к сожалению, он не всегда надёжно проверяет такие ситуации). Обратите внимание: ограничение касается как входящих, так и исходящих соединений, поэтому одно соединение, которое расшифровывается, а затем шифруется, учитывается как 2 соединения SSL. Если значение не задано, но есть ограничение памяти, оно автоматически вычисляется по этому ограничению, maxconn, размеру буфера, памяти для сжатия, размеру кэша SSL и использованию SSL во фронтендах, бэкендах или с обеих сторон. Если при ограничении памяти не заданы ни maxconn, ни maxsslconn, HAProxy автоматически подбирает их так, чтобы 100% соединений могли безопасно использовать SSL, с учётом сторон, где он включён (фронтенд, бэкенд или обе).

maxsslrate <number>

maxsslrate <number>

Задаёт максимальное число сеансов SSL в секунду на процесс равным <number>. При достижении предела слушатели SSL прекращают принимать соединения. Параметр позволяет ограничить общее использование CPU для SSL независимо от возможностей каждого фронтенда. Следует учитывать, что он пригоден только как мера защиты службы: при достижении предела ресурсы не обязательно распределяются между фронтендами справедливо, поэтому полезно также ограничить каждый фронтенд значением, близким к его ожидаемой доле. Следует также учитывать, что сеансы учитываются до попадания в стек SSL, а не после, что защищает стек и от некорректных рукопожатий. Кроме того, уменьшение tune.maxaccept может повысить справедливость распределения.

maxzlibmem <number>

maxzlibmem <number>

Задаёт максимальный объём RAM в мегабайтах на процесс, доступный zlib. При достижении максимума последующие потоки не сжимаются, пока RAM недоступна. Значение 0 означает отсутствие ограничения. Значение по умолчанию — 0. В сокете UNIX значение доступно в байтах в выводе “show info” в строке “MaxZlibMemUsage”; используемая zlib память указана в “ZlibMemUsage” в байтах.

no-memory-trimming

no-memory-trimming

Отключает возврат памяти системе (“malloc_trim”) в некоторых ситуациях, когда предпринимаются попытки освободить много памяти: при её нехватке или при перезагрузке. Такой возврат заставляет системный распределитель памяти просмотреть все неиспользуемые области и освободить их. Обычно это полезно, поскольку новому процессу остаётся больше доступной памяти, а старый едва ли будет активно её использовать. Но в некоторых системах с десятками или сотнями тысяч одновременных соединений сильная фрагментация памяти может сделать освобождение чрезвычайно длительным. В это время трафик через процесс больше не проходит, новые соединения не принимаются, некоторые проверки работоспособности могут завершаться неудачей, а сторожевой таймер может сработать и завершить неотвечающий процесс, оставив огромный дамп памяти. Если это происходит, рекомендуется использовать этот параметр, чтобы отключить возврат памяти и прекратить попытки уступать её новому процессу. Обратите внимание: современные распределители памяти обычно не страдают от такой проблемы.

noepoll

noepoll

Отключает систему опроса событий “epoll” в Linux. Эквивалентно аргументу командной строки “-de”. Следующей системой опроса обычно становится “poll”. См. также “nopoll”.

noevports

noevports

Отключает систему опроса событий event ports в системах SunOS на основе Solaris 10 и новее. Эквивалентно аргументу командной строки “-dv”. Следующей системой опроса обычно становится “poll”. См. также “nopoll”.

nogetaddrinfo

nogetaddrinfo

Отключает getaddrinfo(3) для разрешения имён. Эквивалентно аргументу командной строки “-dG”. Используется устаревшая функция gethostbyname(3).

nokqueue

nokqueue

Отключает систему опроса событий “kqueue” в BSD. Эквивалентно аргументу командной строки “-dk”. Следующей системой опроса обычно становится “poll”. См. также “nopoll”.

noktls

noktls

Отключает ktls. Эквивалентно аргументу командной строки “-dT”.

nopoll

nopoll

Отключает систему опроса событий “poll”. Эквивалентно аргументу командной строки “-dp”. Следующей системой опроса становится “select”. Отключать “poll” никогда не должно требоваться, поскольку он доступен на всех платформах, поддерживаемых HAProxy. См. также “nokqueue”, “noepoll” и “noevports”.

noreuseport

noreuseport

Отключает SO_REUSEPORT; см. socket(7). Эквивалентно аргументу командной строки “-dR”.

nosplice

nosplice

Отключает tcp splicing средствами ядра между сокетами в Linux. Эквивалентно аргументу командной строки “-dS”. После этого данные копируются обычными, более переносимыми вызовами recv/send. tcp splicing средствами ядра доступен лишь в некоторых самых новых вариантах ядра 2.6. Большинство версий от 2.6.25 до 2.6.28 содержат ошибки и пересылают повреждённые данные, поэтому их нельзя использовать. Этот параметр упрощает глобальное отключение splicing при сомнениях. См. также “option splice-auto”, “option splice-request” и “option splice-response”.

profiling.memory { on | off }

profiling.memory { on | off }

Включает (‘on’) или отключает (‘off’) профилирование памяти по функциям. Оно собирает статистику вызовов malloc/calloc/realloc/free во всём процессе, включая библиотеки; она доступна в CLI по команде “show profiling”. В основном это предназначено для случаев необычного использования памяти, которое нельзя объяснить пулами и для которого нужны дополнительные сведения. Потеря производительности обычно составляет около 1%, возможно немного больше на машинах с большим числом потоков, поэтому механизм обычно подходит для использования в рабочей среде. Того же результата можно добиться во время работы командой CLI “set profiling memory”; см. руководство по управлению.

profiling.tasks { auto | on | off | lock | no-lock | memory | no-memory }*

profiling.tasks { auto | on | off | lock | no-lock | memory | no-memory }*

Включает (‘on’) или отключает (‘off’) профилирование CPU по задачам. При значении ‘auto’ профилирование автоматически включается для потока, когда его средняя задержка достигает 1000 микросекунд или больше, согласно полю активности “avg_loop_us”, и автоматически отключается, когда задержка становится ниже 990 микросекунд. Это значение усредняется по последним 1024 циклам, поэтому меняется медленно и существенно сглаживает короткие всплески. Профилирование может также время от времени самопроизвольно включаться в перегруженных системах, контейнерах или виртуальных машинах либо при использовании системой подкачки, чего на балансировщике нагрузки категорически нельзя допускать.

При включённом профилировании задач HAProxy может также собирать время, которое каждая задача проводит с удерживаемой блокировкой или в ожидании блокировки, а также время ожидания успешного выделения памяти при промахе кэша пула. Иногда это помогает понять причины задержек. Для этого можно дополнительно передать ключевые слова “lock” (включить сбор времени блокировок), “no-lock” (отключить его), “memory” (включить сбор времени выделения памяти) или “no-memory” (отключить его). По умолчанию сбор этих данных не включён, поскольку на сильно нагруженных системах он может заметно влиять на использование CPU (3-10%). Обратите внимание: накладные расходы возникают только при фактически работающем профилировании, поэтому в режиме “auto” они появляются только тогда, когда HAProxy решает включить его.

Профилирование CPU по задачам удобно для определения, на что расходуется время и как одни запросы влияют на другие. Его включение обычно влияет на общую производительность менее чем на 1%, поэтому рекомендуется оставить значение по умолчанию ‘auto’, чтобы оно работало только при обнаружении проблемы. Для этой возможности нужна система с поддержкой системного вызова clock_gettime(2) с идентификаторами часов CLOCK_MONOTONIC и CLOCK_THREAD_CPUTIME_ID; в противном случае указанное время будет нулевым. Параметр можно изменить во время работы командой “set profiling” в CLI.

spread-checks <0..50, in percent>

spread-checks <0..50, in percent>

Иногда желательно не отправлять агентские проверки и проверки работоспособности серверам через строго одинаковые интервалы, например когда много логических серверов находятся на одном физическом сервере. Этот параметр позволяет добавить случайное отклонение интервала проверок в пределах от 0 до +/- 50%. Значения от 2 до 5, по-видимому, дают хорошие результаты. Значение по умолчанию остаётся 0.

ssl-engine <name> [algo <comma-separated list of algorithms>]

ssl-engine <name> [algo <comma-separated list of algorithms>]

Задаёт механизм OpenSSL равным <name>. Список допустимых значений <name> можно получить командой “openssl engine”. Директиву можно использовать несколько раз, что включит несколько криптографических механизмов. Указание неподдерживаемого механизма не позволит HAProxy запуститься. Обратите внимание: многие механизмы дают более низкую производительность HTTPS, чем чисто программная реализация на современных процессорах. Необязательная команда “algo” задаёт алгоритмы по умолчанию, предоставляемые ENGINE, с помощью функции OPENSSL ENGINE_set_default_string(). Значение “ALL” использует механизм для всех криптографических операций. Если список algo не задан, используется “ALL”. Можно задать разделённый запятыми список алгоритмов, в том числе RSA, DSA, DH, EC, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. Этот же формат используется в конфигурационном файле openssl: https://www.openssl.org/docs/man1.0.2/apps/config.html

В HAProxy версии 2.6 поддержка криптографических механизмов отключена в сборке по умолчанию. Этот параметр доступен только при сборке HAProxy с соответствующей поддержкой. Если требуется ssl-engine, HAProxy можно пересобрать с флагом USE_ENGINE=1.

ssl-mode-async

ssl-mode-async

Добавляет режим SSL_MODE_ASYNC в контекст SSL. Это включает асинхронные операции ввода-вывода TLS при использовании механизмов SSL с поддержкой асинхронной работы. Текущая реализация поддерживает не более 32 механизмов. API ASYNC в OpenSSL не поддерживает перемещение буферов чтения/записи и несовместим с управлением буферами HAProxy. Поэтому асинхронный режим отключён для операций чтения/записи: он включён только во время начального рукопожатия и повторного согласования.

tune.applet.zero-copy-forwarding { on | off }

tune.applet.zero-copy-forwarding { on | off }

Включает (‘on’) или отключает (‘off’) пересылку данных без копирования для апплетов. По умолчанию включена.

См. также: tune.disable-zero-copy-forwarding.

tune.buffers.limit <number>

tune.buffers.limit <number>

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

tune.buffers.reserve <number>

tune.buffers.reserve <number>

Задаёт число буферов на поток, которые предварительно выделяются и резервируются исключительно для условий нехватки памяти, приводящих к неудачному выделению памяти. Минимальное значение — 0, значение по умолчанию — 4. Изменять его нет причин, если только один из основных разработчиков не рекомендует это по совершенно конкретной причине.

tune.bufsize <size>

tune.bufsize <size>

Задаёт размер буфера в байтах. Меньшие значения позволяют большему числу потоков одновременно работать при том же объёме RAM, а большие — работать приложениям с очень большими cookie. Значение по умолчанию — 16384, его можно изменить при сборке. Настоятельно рекомендуется оставить значение по умолчанию: слишком малые значения нарушают работу некоторых служб, например статистики, а значения выше значения по умолчанию увеличивают потребление памяти и могут привести к её исчерпанию в системе. Как минимум глобальный параметр maxconn следует уменьшить во столько раз, во сколько увеличен этот размер. Кроме того, при использовании HTTP/2 значение обязательно должно быть не меньше 16384. Оно также должно быть меньше 256 MB (268435456 байт). Если блок заголовков запроса HTTP больше (tune.bufsize - tune.maxrewrite), HAProxy возвращает ошибку HTTP 400 (Bad Request). Аналогично, если блок заголовков ответа HTTP больше этого размера, HAProxy возвращает HTTP 502 (Bad Gateway). Обратите внимание: заданное этим параметром значение автоматически округляется вверх до ближайшего числа, кратного 8 на 32-битных машинах или 16 на 64-битных. См. также: tune.bufsize.large, tune.bufsize.small.

tune.bufsize.large <size>

tune.bufsize.large <size>

Задаёт размер больших буферов в байтах. По умолчанию поддержка больших буферов отключена; её нужно явно включить, задав это значение.

Эти буферы предназначены для отдельных ситуаций, когда нужно буферизовать больше данных, не меняя размер обычных буферов. Большие буферы не используются неявно. См. также: tune.bufsize.

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

tune.bufsize.small <size>

tune.bufsize.small <size>

Задаёт размер малых буферов в байтах. Значение по умолчанию — 1024.

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

Сейчас малые буферы автоматически используются только протоколом HTTP/3 для отправки заголовков ответа. В остальных случаях их поддержку можно включить для отдельных прокси параметром “use-small-buffers”. См. также: tune.bufsize.

См. также: option use-small-buffers

tune.cli.max-payload-size <size>

tune.cli.max-payload-size <size>

Задаёт максимально допустимый размер полезной нагрузки, передаваемой команде в CLI.

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

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

Подробности о CLI см. в руководстве по управлению.

tune.comp.maxlevel <number>

tune.comp.maxlevel <number>

Задаёт максимальный уровень сжатия. Уровень сжатия влияет на использование CPU при сжатии. Это значение влияет на использование CPU при сжатии. Каждый поток со сжатием инициализирует алгоритм сжатия этим значением. Значение по умолчанию — 1.

tune.defaults.purge

tune.defaults.purge

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

Это может потреблять много памяти при большом числе экземпляров defaults. В таком случае, если динамические бэкенды не нужны, этим параметром можно принудительно удалять секции defaults после разбора. Однако секции defaults, на которые есть ссылки и которые содержат параметры, не копируемые ссылающимися на них прокси, по-прежнему обязательно сохранять. Например, это касается секций defaults, определяющих правила TCP/HTTP или набор правил tcpcheck.

tune.disable-fast-forward

tune.disable-fast-forward

Отключает ускоренную пересылку данных. Этот механизм оптимизирует пересылку, передавая данные напрямую с одной стороны на другую без пробуждения потока. Директива позволяет отключить эту оптимизацию. Обратите внимание: она также отключает любое tcp splicing средствами ядра и пересылку без копирования. Команда не предназначена для обычного использования; как правило, разработчики рекомендуют её лишь во время сложной отладки.

tune.disable-zero-copy-forwarding

tune.disable-zero-copy-forwarding

Глобально отключает пересылку данных без копирования. Этот механизм оптимизирует ускоренную пересылку, обходясь без буфера канала. Директива позволяет отключить эту оптимизацию. Обратите внимание: она также отключает любое tcp splicing средствами ядра.

См. также: tune.pt.zero-copy-forwarding, tune.applet.zero-copy-forwarding, tune.h1.zero-copy-fwd-recv, tune.h1.zero-copy-fwd-send, tune.h2.zero-copy-fwd-send, tune.quic.zero-copy-fwd-send

tune.epoll.mask-events <event[,...]>

tune.epoll.mask-events <event[,...]>

За время существования HAProxy встречались некоторые сложные проблемы, вызванные ошибками механизма epoll в ядре Linux. Обычно они очень редки и невоспроизводимы вне среды автора сообщения; обойти их иногда можно только отключением epoll и переходом на poll, что не очень подходит для сред с высокой производительностью. Каждый раз проблемы затрагивают лишь совершенно определённые и редкие типы событий, а возможность их маскирования может стать более приемлемым обходным решением. Этот параметр предоставляет такую возможность: он позволяет молча игнорировать некоторые необычные события и заменять их входным событием, сообщающим о неопределённом входящем событии. В результате в некоторых местах не используются быстрые пути обработки ошибок, а применяются только обычные пути. Параметр никогда не следует использовать, если специалист не предложил это для диагностики или обхода ошибки ядра.

Параметр принимает один аргумент: разделённый запятыми список слов, каждое из которых обозначает маскируемое событие. Сейчас поддерживаются следующие события: - “err”: маскировать событие EPOLLERR - “hup”: маскировать события EPOLLHUP - “rdhup”: маскировать события EPOLLRDHUP

Пример:

# mask all non-traffic epoll events:
tune.epoll.mask-events err,hup,rdhup

tune.events.max-events-at-once <number>

tune.events.max-events-at-once <number>

Задаёт число событий, которые обработчик асинхронной задачи (из API event_hdl) может обработать за один раз. <number> следует выбирать в пределах от 1 до 10000. Большое число может вызвать конкуренцию между потоками, поскольку задача выполняет тяжёлую работу без прерываний; малое, напротив, может приводить к постоянному повторному планированию задачи, поскольку за один запуск она обрабатывает недостаточно событий и не успевает за их производителем. Значение по умолчанию можно задать при сборке; иначе оно равно 100.

tune.fail-alloc

tune.fail-alloc

При сборке с DEBUG_FAIL_ALLOC или запуске с “-dMfail” задаёт вероятность неудачи попытки выделения памяти в процентах. Она должна находиться в пределах от 0 (без неудач) до 100 (без успехов). Это полезно для отладки и проверки корректной обработки отказов выделения памяти. Если не задана, доля равна 0. Однако параметр командной строки “-dMfail” автоматически устанавливает частоту отказов 1%, поэтому для тестирования необязательно менять конфигурацию.

tune.fd.edge-triggered { on | off } [ EXPERIMENTAL ]

tune.fd.edge-triggered { on | off }  [ EXPERIMENTAL ]

Включает (‘on’) или отключает (‘off’) режим опроса по фронту события для поддерживающих его FD. Сейчас он поддерживается только с epoll. Он может заметно сократить число вызовов epoll_ctl() и немного повысить производительность в некоторых сценариях. Режим всё ещё экспериментальный: при наличии ошибок он может приводить к зависанию соединений и по умолчанию отключён.

tune.glitches.kill.cpu-usage <number>

tune.glitches.kill.cpu-usage <number>

Задаёт минимальное использование CPU от 0 до 100, при котором соединения со слишком большим числом нарушений будут принудительно закрываться. Это касается соединений, достигших предела glitches-threshold. В средах, где очень долгие соединения часто ведут себя некорректно, но не влияют на производительность, может быть желательно сохранять их, пока они не вредят, и начинать закрывать только при высокой загрузке CPU. Параметр задаёт, что соединение, достигшее порога нарушений, принудительно закрывается при использовании CPU на этом уровне или выше, но никогда не закрывается при меньшем уровне. Обратите внимание: использование CPU измеряется для каждого потока, поэтому может быть закрыто даже одно некорректно работающее соединение. Значение по умолчанию — ноль: соединение, достигшее glitches-threshold, автоматически закрывается. В качестве ориентира можно задать значение, равное удвоенному обычному использованию CPU либо обычному использованию CPU плюс половина незанятой доли (например, если CPU обычно достигает 60%, значение 80 может быть разумным). Параметр не действует без tune.h2.fe.glitches-threshold, tune.quic.fe.sec.glitches-threshold или tune.h1.fe.glitches-threshold. См. также глобальные параметры “tune.h2.fe.glitches-threshold”, “tune.h1.fe.glitches-threshold” и “tune.quic.fe.sec.glitches-threshold”.

tune.h1.be.glitches-threshold <number>

tune.h1.be.glitches-threshold <number>

Задаёт порог числа нарушений в соединении HTTP/1 с бэкендом, по достижении которого соединение автоматически принудительно закрывается. Это позволяет закрывать некорректно работающие соединения без явных правил. Значение по умолчанию — ноль: порог не задан, поэтому никакое событие не приводит к закрытию соединения. Типичные события — неверно оформленные заголовки, которые всё же были приняты благодаря “accept-unsafe-violations-in-http-response”. Ненулевое значение, вероятно, следует выбирать в сотнях или тысячах, чтобы механизм работал эффективно, не затрагивая серверы с небольшими отклонениями. С помощью “tune.glitches.kill.cpu-usage” можно также закрывать соединения только при достижении определённого уровня использования CPU. Обратите внимание: при 75% заданного порога предпринимается попытка плавного закрытия путём перехода в режим закрытия соединения и объявления “Connection: close”, когда это применимо. Это гарантирует, что соединение с небольшими ошибками через некоторое время перестанет использоваться без риска прервать текущую передачу данных.

См. также: tune.h1.fe.glitches-threshold, bc_glitches и tune.glitches.kill.cpu-usage

tune.h1.fe.glitches-threshold <number>

tune.h1.fe.glitches-threshold <number>

Задаёт порог числа нарушений в соединении HTTP/1 с фронтендом, по достижении которого соединение автоматически принудительно закрывается. Это позволяет закрывать некорректно работающие соединения без явных правил. Значение по умолчанию — ноль: порог не задан, поэтому никакое событие не приводит к закрытию соединения. Типичные события — неверно оформленные заголовки, которые всё же были приняты благодаря “accept-unsafe-violations-in-http-request”. Ненулевое значение, вероятно, следует выбирать в сотнях или тысячах, чтобы механизм работал эффективно, не затрагивая клиентов с небольшими отклонениями. С помощью “tune.glitches.kill.cpu-usage” можно также закрывать соединения только при достижении определённого уровня использования CPU. Обратите внимание: при 75% заданного порога предпринимается попытка плавного закрытия путём перехода в режим закрытия соединения и объявления “Connection: close”, когда это применимо. Это позволяет клиенту с небольшими отклонениями от протокола создать новое соединение и продолжить работу без помех, не вызывая принудительного закрытия с риском прерывания текущей передачи данных.

См. также: tune.h1.be.glitches-threshold, fc_glitches и tune.glitches.kill.cpu-usage

tune.h1.zero-copy-fwd-recv { on | off }

tune.h1.zero-copy-fwd-recv { on | off }

Включает (‘on’) или отключает (‘off’) приём данных без копирования для мультиплексора H1. По умолчанию включён.

См. также: tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-send

tune.h1.zero-copy-fwd-send { on | off }

tune.h1.zero-copy-fwd-send { on | off }

Включает (‘on’) или отключает (‘off’) отправку данных без копирования для мультиплексора H1. По умолчанию включена.

См. также: tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-recv

tune.h2.be.glitches-threshold <number>

tune.h2.be.glitches-threshold <number>

Задаёт порог числа нарушений в соединении с бэкендом, по достижении которого соединение автоматически принудительно закрывается. Это позволяет закрывать некорректно работающие соединения без явных правил. Значение по умолчанию — ноль: порог не задан, поэтому никакое событие не приводит к закрытию соединения. Следует учитывать, что некоторые серверы H2 иногда вызывают несколько нарушений за время долгого соединения, поэтому ненулевое значение, вероятно, следует выбирать в сотнях или тысячах, чтобы механизм работал эффективно, не затрагивая серверы с небольшими отклонениями. С помощью “tune.glitches.kill.cpu-usage” можно также закрывать соединения только при достижении определённого уровня использования CPU. Обратите внимание: при 75% заданного порога предпринимается попытка плавного закрытия путём объявления GOAWAY для будущего потока. Это гарантирует, что соединение с небольшими ошибками через некоторое время перестанет использоваться без риска прервать текущую передачу данных.

См. также: tune.h2.fe.glitches-threshold, bc_glitches и tune.glitches.kill.cpu-usage

tune.h2.be.initial-window-size <number>

tune.h2.be.initial-window-size <number>

Задаёт начальный размер окна HTTP/2 для исходящих соединений: число байт, которые сервер может отправить в ответ до ожидания подтверждения от HAProxy. Параметр влияет только на полезную нагрузку, а не на заголовки. Если не задан, применяется общее значение по умолчанию tune.h2.initial-window-size. Небольшое увеличение может ускорить загрузки или уменьшить использование CPU на серверах ценой несправедливого распределения ресурсов между клиентами. Вместо этого лучше использовать tune.h2.be.rxbuf, который не вызывает такого неравенства. На использование ресурсов параметр не влияет.

См. также: tune.h2.initial-window-size.

tune.h2.be.max-concurrent-streams <number>

tune.h2.be.max-concurrent-streams <number>

Задаёт максимальное число одновременных потоков HTTP/2 на исходящее соединение, то есть число незавершённых запросов в одном соединении с сервером. Если не задан, применяется значение по умолчанию tune.h2.max-concurrent-streams. Значение ниже значения по умолчанию 100 может улучшить отзывчивость сайта ценой большего числа установленных соединений с серверами. При значении “always” параметра “http-reuse” рекомендуется уменьшить это число, чтобы не смешивать слишком много разных клиентов в одном соединении: если один клиент медленнее других, механизм «блокировки начала очереди» может каскадно снижать скорость загрузки для всех клиентов, разделяющих соединение (в таком случае tune.h2.be.initial-window-size следует держать низким). Настоятельно рекомендуется не увеличивать это значение; в некоторых случаях оптимальны малые значения, обычно 1..5.

tune.h2.be.max-frames-at-once <number>

tune.h2.be.max-frames-at-once <number>

Задаёт максимальное число входящих кадров HTTP/2, обрабатываемых за один раз в соединении с бэкендом. При очень больших буферах полезно задать малое значение, от нескольких десятков до нескольких сотен, чтобы сохранить низкую задержку и более справедливое распределение ресурсов между соединениями. Значение по умолчанию — ноль, то есть ограничение не применяется.

tune.h2.be.rxbuf <size>

tune.h2.be.rxbuf <size>

Задаёт размер буфера приёма HTTP/2 для исходящих соединений в байтах. Размер округляется вверх до ближайшего числа, кратного tune.bufsize, и разделяется между всеми потоками, отправляющими данные (кадры HEADERS и DATA). В любом случае каждому потоку всегда предоставляется один буфер, а 7/8 неиспользуемых буферов разделяются между потоками, получающими полезную нагрузку. Это значительно повышает производительность отправки данных и устраняет блокировку начала очереди (HoL) в соединениях с бэкендом, разделяемых несколькими клиентами при значении “always” параметра http-reuse. Объявляемое окно каждого потока автоматически подстраивается под доступное пространство, поэтому на практике менять tune.h2.be.initial-window-size не должно требоваться. Если задан размер меньше необходимого для всех потоков, используется этот минимум. Значение по умолчанию — около 1600k (100 потоков с буферами по 16kB).

См. также: tune.h2.be.initial-window-size, tune.h2.fe.rxbuf, http-reuse.

tune.h2.fe.glitches-threshold <number>

tune.h2.fe.glitches-threshold <number>

Задаёт порог числа нарушений в соединении с фронтендом, по достижении которого соединение автоматически принудительно закрывается. Это позволяет закрывать некорректно работающие соединения без явных правил. Значение по умолчанию — ноль: порог не задан, поэтому никакое событие не приводит к закрытию соединения. Следует учитывать, что некоторые клиенты H2 иногда вызывают несколько нарушений за время долгого соединения, поэтому ненулевое значение, вероятно, следует выбирать в сотнях или тысячах, чтобы механизм работал эффективно, не затрагивая клиентов с небольшими отклонениями. С помощью “tune.glitches.kill.cpu-usage” можно также закрывать соединения только при достижении определённого уровня использования CPU. Обратите внимание: при 75% заданного порога предпринимается попытка плавного закрытия путём объявления GOAWAY для будущего потока. Это позволяет клиенту с небольшими отклонениями от протокола создать новое соединение и продолжить работу без помех, не вызывая принудительного закрытия с риском прерывания текущей передачи данных.

См. также: tune.h2.be.glitches-threshold, fc_glitches и tune.glitches.kill.cpu-usage

tune.h2.fe.initial-window-size <number>

tune.h2.fe.initial-window-size <number>

Задаёт начальный размер окна HTTP/2 для входящих соединений: число байт, которые клиент может отправить до ожидания подтверждения от HAProxy. Параметр влияет только на полезную нагрузку, то есть тело запросов POST, а не на заголовки. Если не задан, применяется общее значение по умолчанию tune.h2.initial-window-size. Увеличение может ускорить отправку данных. Значение по умолчанию равно tune.bufsize (16384) и обеспечивает пропускную способность не менее 1.25 Mbps на поток при времени ping 100 ms и 125 Mbps при времени ping 1 ms. На использование ресурсов оно не влияет. Слишком большие значения могут снижать отзывчивость для клиентов, которые обращаются к страницам одновременно с отправкой больших объёмов данных. Вместо этого лучше использовать tune.h2.fe.rxbuf, который не вызывает неравенства в распределении ресурсов.

См. также: tune.h2.initial-window-size.

tune.h2.fe.max-concurrent-streams <number> [args...]

tune.h2.fe.max-concurrent-streams <number> [args...]

Задаёт максимальное число одновременных потоков HTTP/2 на входящее соединение, то есть число незавершённых запросов в одном соединении от клиента. Если не задан, применяется значение по умолчанию tune.h2.max-concurrent-streams. Значение выше значения по умолчанию 100 иногда может немного ускорить загрузку страниц сложных сайтов с множеством небольших объектов в сетях с высокой задержкой, но также увеличивает использование памяти, позволяя клиенту выделять больше ресурсов одновременно. Значение по умолчанию 100 обычно подходит, и менять его не рекомендуется. Больший параллелизм также влияет на вычислительную нагрузку и задержки при большом числе соединений, каждое из которых использует много потоков, и может снижать порог для атак отказа в обслуживании. После числа команда поддерживает следующие необязательные аргументы:

• rq-load { <number> | auto | ignore }:

Необязательный аргумент "rq-load" позволяет динамически изменять объявляемый
уровень параллелизма в зависимости от загрузки очереди выполнения текущего
потока: пока загрузка потока остаётся ниже указанного порога, объявляется
настроенный предел числа потоков HTTP. Когда загрузка потока выполнения
превышает настроенный предел, объявляемый предел числа потоков HTTP
уменьшается пропорционально квадрату коэффициента превышения. Целевые
уровни загрузки от 50 до 100 обычно обеспечивают очень хорошее ограничение
при высокой нагрузке. Вместо явного числа ключевое слово также принимает
"ignore" — значение по умолчанию, при котором загрузка очереди выполнения
потока не учитывается при ограничении объявляемого числа потоков HTTP, —
и "auto", которое устанавливает предел равным значению "tune.runqueue-depth".
Последнее обычно даёт хорошие результаты без дальнейшей подстройки
конфигурации.

• min <number>:

Задаёт минимальный объявляемый уровень параллелизма при использовании rq-load,
даже если это приводит к более высокой загрузке, чем заданная целевая.
Это позволяет сохранить хорошую отзывчивость сайта при очень высокой
нагрузке. Минимальное значение и значение по умолчанию — 1, но значения
от 5 до 15 могут улучшить удобство работы пользователей.

Пример:

tune.h2.fe.max-concurrent-streams 100 rq-load auto min 15

tune.h2.fe.max-frames-at-once <number>

tune.h2.fe.max-frames-at-once <number>

Задаёт максимальное число входящих кадров HTTP/2, обрабатываемых за один раз в соединении с фронтендом. При очень больших буферах полезно задать малое значение, от нескольких десятков до нескольких сотен, чтобы сохранить низкую задержку и более справедливое распределение ресурсов между соединениями. Значение по умолчанию — ноль, то есть ограничение не применяется.

tune.h2.fe.max-rst-at-once <number>

tune.h2.fe.max-rst-at-once <number>

Задаёт максимальное число входящих RST_STREAM HTTP/2, обрабатываемых за один раз в соединении с фронтендом. После получения указанного числа кадров RST_STREAM обработчик соединения помещается в очередь с низким приоритетом и обрабатывается после всех остальных задач. Очень малое значение, 1 или несколько единиц, может значительно уменьшить последствия массовой отправки кадров RST_STREAM. Такие RST_STREAM возникают и при нажатии пользователем кнопки остановки в браузере, но дополнительные несколько миллисекунд из-за смены очереди обычно незаметны и при этом эффективно снижают нагрузку от такого наплыва кадров. Значение по умолчанию — ноль, то есть ограничение не применяется.

tune.h2.fe.max-total-streams <number>

tune.h2.fe.max-total-streams <number>

Задаёт максимальное общее число потоков HTTP/2, обрабатываемых на входящее соединение. При достижении предела HAProxy отправляет кадр GOAWAY для плавного закрытия, сообщая клиенту, что соединение будет закрыто после завершения всех ожидающих потоков. На практике клиенты обычно закрывают соединение как можно быстрее после получения кадра и устанавливают новое для следующих запросов. Иногда это полезно и желательно, если клиенты очень долго остаются подключёнными и вызывают неравномерное распределение нагрузки в группе серверов. Например, в некоторых очень динамичных средах новые балансировщики нагрузки создаются на лету при росте нагрузки, а после её снижения их следует останавливать, не разрывая установленные соединения. При задании предела соединения имеют ограниченный срок жизни и часто обновляются; некоторые новые соединения могут устанавливаться с другими узлами, поэтому существующие ресурсы быстро освобождаются.

Следует понимать, что этот предел неявно связан с указанным выше “tune.h2.fe.max-concurrent-streams”. HAProxy всегда принимает к обработке любые возможные ожидающие потоки, которые могут находиться в пути между клиентом и фронтендом, поэтому объявляемый предел всегда автоматически увеличивается на значение max-concurrent-streams. Полученное значение служит жёстким пределом: его превышение клиентом, не соблюдающим протокол, приводит к закрытию соединения. Поэтому при подсчёте запросов на соединение по журналам может наблюдаться любое число от max-total-streams до (max-total-streams + max-concurrent-streams) в зависимости от скорости создания потоков клиентом.

Значение по умолчанию — ноль: ограничений сверх установленных протоколом нет (2^30 ~= 1.07 миллиарда). Значения около 1000 уже могут вызывать частое обновление соединений без заметной задержки для большинства клиентов. Слишком малое значение может повысить использование CPU из-за частых повторных соединений TLS и увеличить время загрузки страниц. Обратите внимание: некоторые инструменты нагрузочного тестирования не поддерживают повторные соединения и могут сообщать об ошибках с этим параметром, поэтому при измерении производительности его может потребоваться отключить. См. также “tune.h2.fe.max-concurrent-streams”.

tune.h2.fe.rxbuf <size>

tune.h2.fe.rxbuf <size>

Задаёт размер буфера приёма HTTP/2 для входящих соединений в байтах. Размер округляется вверх до ближайшего числа, кратного tune.bufsize, и разделяется между всеми потоками, отправляющими данные (кадры HEADERS и DATA). В любом случае каждому потоку всегда предоставляется один буфер, а 7/8 неиспользуемых буферов разделяются между потоками, отправляющими полезную нагрузку, что значительно повышает производительность отправки данных. Объявляемое окно каждого потока автоматически подстраивается под доступное пространство, поэтому на практике менять tune.h2.fe.initial-window-size не должно требоваться. Если задан размер меньше необходимого для всех потоков, используется этот минимум. Значение по умолчанию 1600k (100 потоков с буферами по 16kB) обеспечивает клиенту скорость отправки примерно 130 Mbps при RTT 100ms.

См. также: tune.h2.fe.initial-window-size и tune.h2.be.rxbuf.

tune.h2.header-table-size <number>

tune.h2.header-table-size <number>

Задаёт размер динамической таблицы заголовков HTTP/2. По умолчанию — 4096 байт, максимум — 65536 байт. Большее значение может помочь некоторым клиентам отправлять более компактные запросы в зависимости от их возможностей. Этот объём памяти расходуется на каждое соединение HTTP/2. Менять значение не рекомендуется.

tune.h2.initial-window-size <number>

tune.h2.initial-window-size <number>

Задаёт значение начального размера окна HTTP/2 по умолчанию для входящих и исходящих соединений. Оно используется для входящих соединений, если не задан tune.h2.fe.initial-window-size, и для исходящих, если не задан tune.h2.be.initial-window-size. Параметр задаёт как начальное значение, так и минимум на поток. Значение по умолчанию — 16384 (tune.bufsize), что при отправке данных примерно обеспечивает пропускную способность не менее 1.25 Mbps на поток в сети со временем ping 100 ms либо 125 Mbps в локальной сети с задержкой в 1 миллисекунду. Когда буферов приёма используется меньше максимума, в пределах tune.h2.be.rxbuf и tune.h2.fe.rxbuf, неиспользуемые буферы разделяются между принимающими потоками. Поэтому менять это значение по умолчанию обычно нет смысла. Поскольку его изменение одновременно повышает скорость отправки и усиливает неравенство между клиентами при получении данных, рекомендуется вместо него использовать отдельные параметры сторон: tune.h2.fe.initial-window-size и tune.h2.be.initial-window-size.

tune.h2.log-errors { none | connection | stream }

tune.h2.log-errors { none | connection | stream }

Задаёт уровень ошибок демультиплексора H2, при котором создаётся запись журнала. По умолчанию — “stream”: любая ошибка декодирования в демультиплексоре вызывает запись журнала. Значение “connection” означает, что журналируется только то, что делает соединение недействительным. Наконец, “none” означает, что ни одна ошибка декодирования не вызывает записи журнала. Для обнаружения аномалий протокола рекомендуется задать как минимум “connection”, даже если в трудные периоды приходится временно переключаться на “none”.

tune.h2.max-concurrent-streams <number>

tune.h2.max-concurrent-streams <number>

Задаёт максимальное число одновременных потоков HTTP/2 на соединение по умолчанию, то есть число незавершённых запросов в одном соединении. Используется для входящих соединений, если не задан tune.h2.fe.max-concurrent-streams, и для исходящих, если не задан tune.h2.be.max-concurrent-streams. Значение по умолчанию — 100. Влияние зависит от стороны; подробнее см. два параметра выше. Рекомендуется отказаться от этого параметра в пользу отдельных параметров сторон. Нулевое значение отключает ограничение, и один клиент может создать столько потоков, сколько HAProxy способен выделить. Настоятельно рекомендуется не менять это значение.

tune.h2.max-frame-size <number>

tune.h2.max-frame-size <number>

Задаёт максимальный размер кадра HTTP/2, который HAProxy сообщает одноранговым узлам как допустимый для приёма. По умолчанию используется большее из 16384 и размера буфера (tune.bufsize). В любом случае HAProxy не объявляет поддержку кадров больше буферов. Основная цель параметра — ограничить максимальный размер кадра при больших буферах. Слишком большие кадры могут повлиять на производительность или вызвать некорректное поведение некоторых одноранговых узлов. Настоятельно рекомендуется не менять значение.

tune.h2.zero-copy-fwd-send { on | off }

tune.h2.zero-copy-fwd-send { on | off }

Включает (‘on’) или отключает (‘off’) отправку данных без копирования для мультиплексора H2. По умолчанию включена.

См. также: tune.disable-zero-copy-forwarding

tune.http.cookielen <number>

tune.http.cookielen <number>

Задаёт максимальную длину захватываемых cookie. Это максимальное значение, разрешённое для “capture cookie xxx len yyy”; любое большее значение автоматически усекается до него. Важно не задавать слишком большое значение, поскольку каждый захват cookie всё равно выделяет такой объём независимо от своей настройки: все захваты используют один пул. Этот объём выделяется отдельно на запрос и на ответ, поэтому на соединение расходуется вдвое больше памяти. Если не задано, ограничение составляет 63 символа. Менять значение не рекомендуется.

tune.http.logurilen <number>

tune.http.logurilen <number>

Задаёт максимальную длину URI запроса в журналах. Это предотвращает усечение длинных URI запросов с полезными строками параметров в записях журнала. Параметр не связан с ограничениями syslog. При увеличении предела можно также увеличить параметр ’log … len yyy’. Демону syslog тоже могут потребоваться специальные директивы конфигурации. Значение по умолчанию — 1024.

tune.http.maxhdr <number>

tune.http.maxhdr <number>

Задаёт максимальное число заголовков в получаемых сообщениях HTTP. Если число заголовков сообщения, включая первую строку, превышает это значение, запрос отклоняется с кодом состояния “400 Bad Request”, а ответ — с “502 Bad Gateway”. Значение по умолчанию — 101; его достаточно для всех случаев, поскольку широко распространённый сервер Apache использует тот же предел. Увеличение может временно позволить работать приложению с ошибками до его исправления. Допустимый диапазон — 1..32767. Следует учитывать, что каждый новый заголовок расходует 32bits памяти на каждый поток, поэтому не следует повышать предел слишком сильно.

Обратите внимание: HTTP/1.1 — текстовый протокол, поэтому при отправке сообщения отдельного ограничения нет. Ограничения при разборе достаточно. HTTP/2 и HTTP/3 — двоичные протоколы, требующие этапа кодирования. При кодировании заголовков также устанавливается предел для соблюдения ограничений протоколов. Он достаточно велик, но намеренно не документирован. По той же причине этот предел применяется и на первых этапах декодирования.

tune.idle-pool.shared { full | on | off }

tune.idle-pool.shared { full | on | off }

Управляет совместным использованием пулов простаивающих соединений потоками для одного сервера. Его можно включить для всех потоков одной группы (‘on’), для всех потоков (‘full’) или отключить (‘off’). По умолчанию пулы совместно используются потоками одной группы (‘on’), чтобы сократить число постоянных соединений с сервером и повысить долю повторного использования соединений. Совместное использование потоками других групп может влиять на производительность и по умолчанию отключено, но полезно, если максимальное повторное использование соединений приоритетно. Для отладки или при подозрении на ошибку HAProxy в повторном использовании соединений удобно принудительно отключить совместное использование пула несколькими потоками, задав “off”. Настоятельно не рекомендуется отключать этот параметр без консервативного значения “pool-low-conn” для всех серверов, чья высокая производительность зависит от повторного использования соединений; иначе с ростом числа потоков соединения могут закрываться очень часто.

tune.idletimer <timeout>

tune.idletimer <timeout>

Задаёт время, после которого HAProxy считает, что пустой буфер, вероятно, связан с простаивающим потоком. Это позволяет оптимально менять размеры некоторых пакетов при чередовании пересылки больших и малых объёмов данных. Параметр влияет на решение использовать splice() или отправлять большие буферы по SSL. Значение задаётся в миллисекундах от 0 до 65535. Ноль означает, что HAProxy не пытается обнаруживать простаивающие потоки. Значение по умолчанию — 1000; оно, по-видимому, правильно обнаруживает паузы пользователя, например чтение страницы перед щелчком. Причин для изменения этого значения быть не должно. См. ниже tune.ssl.maxrecord.

tune.listener.default-shards { by-process | by-thread | by-group }

tune.listener.default-shards { by-process | by-thread | by-group }

Обычно все строки “bind” создают один шард: один сокет, который слушают все потоки процесса. При большом числе потоков это не очень эффективно и может создавать значительные накладные расходы ядра при обновлении состояния опроса или распределении событий между потоками. Современные ОС поддерживают балансировку входящих соединений: несколько сокетов могут быть привязаны к одному адресу и порту, а все входящие соединения равномерно распределяются между ними, поэтому каждый поток видит только соединения, ожидающие в сокете, к которому он привязан. Это значительно сокращает накладные расходы ядра и повышает производительность при обработке входящих соединений. В HAProxy это обычно включается параметром “shards” строк “bind” со значением по умолчанию 1, при котором каждому слушателю в процессе соответствует единственный сокет. В системах с множеством процессоров удобнее изменить значение по умолчанию на “by-thread”, чтобы всегда создавать один слушающий сокет на поток, либо на “by-group”, чтобы создавать один слушающий сокет на группу потоков. При “by-thread” следует учитывать использование файловых дескрипторов: каждому слушателю нужно столько сокетов, сколько потоков. Кроме того, некоторые ОС, например FreeBSD, ограничивают число сокетов на одном адресе значением 256. Обратите внимание: “by-group” остаётся эквивалентом “by-process” в конфигурациях по умолчанию с одной группой потоков и возвращается к общему сокету в системах без поддержки этого механизма. Значение по умолчанию — “by-group” с переходом на “by-process” для систем или семейств сокетов, не поддерживающих множественные привязки.

tune.listener.multi-queue { on | fair | off }

tune.listener.multi-queue { on | fair | off }

Включает (‘on’ / ‘fair’) или отключает (‘off’) приём соединений слушателем с несколькими очередями. Он распределяет входящий трафик между всеми потоками, на которых разрешено работать строке “bind”, вместо приёма только для себя. Это даёт более плавное распределение трафика и гораздо лучше масштабируется, особенно если потоки нагружены неравномерно из-за внешней активности, например сетевых прерываний на одном из потоков. Режим по умолчанию “on” оптимизирует выбор потока, выбирая из выборки поток с наименьшим числом соединений. Часто это лучший выбор для долгих соединений, поскольку он поддерживает занятость всех потоков. Второй режим, “fair”, последовательно обходит все потоки независимо от их текущей нагрузки. Он может лучше подходить для коротких соединений или машин с очень большим числом потоков, где вероятность найти самый свободный поток в первом режиме мала. Наконец, “off” позволяет принудительно отключить перераспределение для устранения неполадок либо для коротких соединений, когда считается, что ОС уже достаточно хорошо распределяет их. Значение по умолчанию — “on”.

tune.lua.bool-sample-conversion { normal | pre-3.1-bug }

tune.lua.bool-sample-conversion { normal | pre-3.1-bug }

Явно задаёт haproxy способ обработки объектов образцов haproxy при передаче в Lua. Например, при использовании встроенных преобразователей, функций извлечения образцов или переменных из сценария Lua haproxy преобразует внутренний тип smp в соответствующий тип Lua. Из-за исторической реализации обработка логических значений неоднозначна: при преобразовании Lua -> haproxy smp логические значения сохраняются правильно, но при преобразовании haproxy smp -> Lua они ошибочно преобразовывались в целые числа. Поэтому функция извлечения образца или преобразователь, возвращающий логическое значение, при использовании из Lua возвращал целое число 0 или 1. К сожалению, в Lua логические значения и целые числа не взаимозаменяемы. Во избежание неоднозначности параметр “tune.lua.bool-sample-conversion” должен быть явно задан либо как “normal”, отказавшись от прежнего поведения ради согласованности, либо как “pre-3.1-bug”, сохранив прежнее поведение, чтобы не нарушить логику существующих сценариев. Если параметр не задан явно, а из конфигурации загружается сценарий Lua, haproxy выводит предупреждение, и неявно применяется “pre-3.1-bug” для сохранения прежнего поведения. Рекомендуется задать “normal”, предварительно убедившись, что используемые сценарии Lua правильно обрабатывают образцы bool haproxy как логические значения.

Чтобы параметр учитывался, он должен быть задан до любой директивы “lua-load” или “lua-load-per-thread”; иначе он игнорируется.

tune.lua.burst-timeout <timeout>

tune.lua.burst-timeout <timeout>

Тайм-аут выполнения “burst” применяется к любому обработчику Lua. Если обработчик не завершится или не уступит выполнение до достижения тайм-аута, он будет прерван, чтобы предотвратить конкуренцию между потоками, слишком долгое необслуживание трафика и в конечном счёте аварийное завершение процесса при срабатывании сторожевого таймера. В отличие от других тайм-аутов Lua, суммируемых между уступками выполнения, burst-timeout ограничивает время одного непрерывного окна выполнения Lua заданным тайм-аутом.

Уступка выполнения здесь означает, что выполнение Lua фактически прерывается либо явным вызовом функции, уступающей выполнение, например core.(m)sleep() или core.yield(), либо автоматической принудительной уступкой (см. tune.lua.forced-yield). Оно возобновится позднее, когда соответствующая задача будет запланирована заново. Не все обработчики Lua могут уступать выполнение: следует различать обработчики с такой возможностью и без неё.

Для обработчиков, способных уступать выполнение, например задач и действий, достижение тайм-аута может означать, что “tune.lua.forced-yield” слишком велик для системы и его уменьшение улучшит ситуацию. Можно также проверить, помогают ли явные уступки выполнения в ключевых точках функции Lua. Это может указывать и на то, что обработчик слишком долго находится в определённой библиотечной функции Lua, которую нельзя прервать.

Для обработчиков, неспособных уступать выполнение, например преобразователей Lua и функций извлечения образцов, это может означать слишком большой объём вычислений из-за неудачного проектирования: такие обработчики часто блокируют ход выполнения запроса и от них ожидается быстрое завершение, чтобы его обработка могла продолжиться. Обычно стоит попытаться оптимизировать функцию Lua по скорости, поскольку уменьшение “tune.lua.forced-yield” не поможет.

Этот тайм-аут учитывает только чистое время выполнения Lua. Если Lua вызывает core.sleep, время сна не учитывается. Тайм-аут по умолчанию — 1000ms.

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

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

- проверить, можно ли оптимизировать сценарий, чтобы уменьшить потребление памяти Lua
- настроить параметры GC Lua и / или явно запрашивать циклы GC
  (см.: https://www.lua.org/manual/5.4/manual.html#pdf-collectgarbage)
- увеличить tune.lua.burst-timeout

Значение 0 полностью отключает эту защиту.

tune.lua.forced-yield <number>

tune.lua.forced-yield <number>

Эта директива заставляет механизм Lua уступать выполнение через каждые <number> выполненных инструкций. Это позволяет прерывать длинный сценарий и даёт планировщику HAProxy возможность обрабатывать другие задачи, например принимать соединения или пересылать трафик. Значение по умолчанию — 10000 инструкций для сценариев, загруженных через “lua-load-per-thread”, и MAX(500, 10000 / nbthread) инструкций для сценариев, загруженных через “lua-load”. Экспериментально это оказалось оптимальным для производительности с учётом предотвращения конкуренции нескольких потоков за глобальную блокировку Lua.

Если HAProxy часто выполняет код Lua, но требуется большая отзывчивость, значение можно уменьшить. Если код Lua достаточно длинный и его результат совершенно необходим для обработки данных, <number> можно увеличить, но значение следует выбирать разумно: в многопоточной среде оно может усилить конкуренцию за ресурсы.

tune.lua.log.loggers { on | off }

tune.lua.log.loggers { on | off }

Включает (‘on’) или отключает (‘off’) запись вывода сценариев LUA через средства ведения журнала текущего прокси, если они есть.

По умолчанию — ‘on’.

tune.lua.log.stderr { on | auto | off }

tune.lua.log.stderr { on | auto | off }

Включает (‘on’) или отключает (‘off’) запись вывода сценариев LUA через stderr. При значении ‘auto’ запись через stderr условно включается (‘on’), если выполняется хотя бы одно из условий:

- tune.lua.log.loggers имеет значение 'off'
- сценарий выполняется вне контекста прокси и глобального средства ведения журнала нет
- сценарий выполняется в контексте прокси, к которому не подключено средство ведения журнала

Обратите внимание: при включении эта запись дополняет ведение журнала, настроенное через tune.lua.log.loggers.

По умолчанию — ‘auto’.

tune.lua.maxmem <number>

tune.lua.maxmem <number>

Задаёт максимальный объём RAM в мегабайтах на процесс, доступный Lua. По умолчанию — ноль, то есть без ограничения. Важно задать предел, чтобы ошибка сценария не привела к исчерпанию памяти системы.

tune.lua.openlibs [all | none | <lib>[,<lib>...]]

tune.lua.openlibs [all | none | <lib>[,<lib>...]]

Выбирает стандартные библиотеки Lua, загружаемые при инициализации состояния Lua. Аргумент — разделённый запятыми список имён библиотек из набора table, io, os, string, math, utf8, package, debug. Вместо списка можно использовать специальные значения “all” и “none”. Значение “none” нельзя сочетать с именами библиотек. Значение по умолчанию — “all”.

Библиотеки base и coroutine всегда загружаются независимо от этого параметра: base предоставляет основные функции Lua, необходимые HAProxy, а coroutine требуется, поскольку HAProxy заменяет coroutine.create() собственной безопасной реализацией.

Обратите внимание: fork() и создание новых потоков уже заблокированы в HAProxy по умолчанию независимо от этого параметра и могут быть снова включены только глобальной директивой “insecure-fork-wanted”. Ограничение набора загружаемых библиотек дополнительно уменьшает поверхность атаки, доступную сценариям Lua. В частности: - исключение “os” запрещает os.execute() и os.exit() - исключение “io” запрещает io.open() и io.popen() - исключение “package” запрещает загрузку нативных модулей C через require() - исключение “debug” запрещает изучение внутреннего состояния HAProxy через debug.getupvalue(), debug.getmetatable() или debug.sethook()

Примеры:

tune.lua.openlibs none                    # only base + coroutine
tune.lua.openlibs string,math,table,utf8  # safe subset, no I/O or OS
tune.lua.openlibs all                     # default, load everything

Этот параметр должен быть задан до любой директивы “lua-load”, “lua-load-per-thread” или “lua-prepend-path”; иначе возвращается ошибка разбора.

tune.lua.service-timeout <timeout>

tune.lua.service-timeout <timeout>

Тайм-аут выполнения служб Lua. Полезен для предотвращения бесконечных циклов или чрезмерно долгой работы Lua. Учитывает только чистое время выполнения Lua. Если Lua переходит в сон, время сна не учитывается. Тайм-аут по умолчанию — 4s.

tune.lua.session-timeout <timeout>

tune.lua.session-timeout <timeout>

Тайм-аут выполнения сеансов Lua. Полезен для предотвращения бесконечных циклов или чрезмерно долгой работы Lua. Учитывает только чистое время выполнения Lua. Если Lua переходит в сон, время сна не учитывается. Тайм-аут по умолчанию — 4s.

tune.lua.task-timeout <timeout>

tune.lua.task-timeout <timeout>

Назначение то же, что у “tune.lua.session-timeout”, но тайм-аут предназначен для задач. По умолчанию он не задан, поскольку задача может существовать всё время работы HAProxy, например задача проверки серверов.

tune.max-checks-per-thread <number>

tune.max-checks-per-thread <number>

Задаёт число активных проверок на поток, выше которого поток активно пытается найти менее нагруженный поток для проверки работоспособности либо ставит её в очередь до уменьшения числа выполняемых на нём проверок. Значение по умолчанию — ноль: такого ограничения нет. Параметр может понадобиться в средах с чрезвычайно большим числом дорогих проверок и множеством потоков, если нагрузка распределяется неравномерно и проверки работоспособности могут случайно достигать тайм-аута при запуске. Типичный случай — OpenSSL 3.0, где проверки работоспособности примерно в 20 раз сильнее нагружают CPU, чем в более ранних версиях. В результате работа по проверкам выравнивается между всеми потоками. Для подавляющего большинства конфигураций менять параметр не нужно. Обратите внимание: слишком малые значения могут значительно замедлить проверки работоспособности, если они выполняются медленно.

tune.maxaccept <number>

tune.maxaccept <number>

Задаёт максимальное число соединений, которые процесс может принять подряд перед переходом к другой работе. В однопроцессном режиме большие числа раньше повышали производительность при высокой интенсивности соединений, но с несколькими очередями это больше не так. Значение применяется отдельно к каждому слушателю с учётом числа процессов, к которым он привязан. Значение по умолчанию — 4, показавшее лучшие результаты. Если из старой конфигурации унаследовано значительно большее значение, его имеет смысл удалить: это повысит производительность и уменьшит время ответа. В многопроцессном режиме оно делится на удвоенное число процессов, к которым привязан слушатель. Значение -1 полностью отключает ограничение. Обычно подстраивать это значение не должно требоваться.

tune.maxpollevents <number>

tune.maxpollevents <number>

Задаёт максимальное число событий, обрабатываемых за один вызов системы опроса. Значение по умолчанию подбирается под ОС. Замечено, что уменьшение ниже 200 обычно немного снижает задержку ценой пропускной способности сети, а увеличение выше 200 обычно повышает задержку ради небольшого роста пропускной способности. Заданное значение должно быть не больше 1000000.

tune.maxrewrite <number>

tune.maxrewrite <number>

Задаёт размер зарезервированного пространства буфера в байтах. Оно используется для изменения или добавления заголовков. Первые чтения из сокетов никогда не заполняют больше bufsize-maxrewrite. Исторически значение по умолчанию составляло половину bufsize, хотя это не очень разумно, поскольку редко требуется добавлять много заголовков. Слишком большое значение не позволяет обрабатывать большие запросы или ответы. Слишком малое не позволяет добавлять заголовки в уже большие запросы или запросы POST. Обычно разумно выбрать около 1024. Если значение больше половины bufsize, оно автоматически уменьшается до этой половины. Поэтому при изменении bufsize об этом беспокоиться не нужно.

tune.max-rules-at-once <number>

tune.max-rules-at-once <number>

Задаёт максимальное число правил, вычисляемых за один раз функциями обработки наборов правил, если они поддерживают уступку выполнения. Например, нередки конфигурации с множеством правил “tcp-request content” или “http-request”. Большое число правил в сочетании с действиями, требующими много CPU, например работающими с содержимым, может вызвать конкуренцию между потоками: если вычисление не прерывается, все правила набора выполняются в одном цикле опроса. Для наборов правил, ориентированных на содержимое и уже поддерживающих уступку выполнения при его проверке, параметр гарантирует выполнение не более <number> правил в одном цикле опроса. Он принудительно заставляет функцию вычисления уступить выполнение, чтобы продолжить обработку в следующем цикле опроса.

Затрагиваемые наборы правил:

• “tcp-request content”
• “tcp-response content”
• “http-request”
• “http-response”

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

tune.memory.hot-size <number>

tune.memory.hot-size <number>

Задаёт объём памяти на поток, который сохраняется готовым к использованию в локальном кэше и никогда не может быть освобождён другими потоками. Доступ к этой памяти очень быстрый, без блокировок, а достаточный объём критичен для производительности при сильной конкуренции потоков. Значение выражается в байтах; значение по умолчанию задаётся при сборке через CONFIG_HAP_POOL_CACHE_SIZE и составляет 524288 (512 kB). Большее значение может повысить производительность в некоторых сценариях, особенно когда профили показывают высокую нагрузку на выделение памяти. По опыту, удачное значение находится между размером кэша L2 одного ядра CPU и удвоенным этим размером. Слишком большие значения ухудшают производительность из-за неэффективного использования кэшей L3 в CPU и потребляют больше памяти. Рекомендуется не менять значение либо увеличивать его небольшими шагами. Для полного отключения кэшей CPU на поток может подойти очень малое значение, но лучше использовать “-dMno-cache” в командной строке.

tune.notsent-lowat.client <size>

tune.notsent-lowat.client <size>
tune.notsent-lowat.server <size>

Подстраивает буферизацию ядра на сокет так, чтобы сторона отправки сокета считалась заполненной, когда объём буферизованных данных равен этому значению плюс измеренный размер окна. Принцип — оставлять в буферах сокета лишь строго необходимый минимум байт и небольшой запас, соответствующий объёму, который будет отправлен до следующей попытки отправки haproxy. Малое значение, обычно около tune.bufsize, значительно снижает потребление памяти системными буферами и задержку приложения при отправке буферизованных данных. В поддерживающих системах этот параметр обычно эффективнее и точнее, чем tune.sndbuf.client и tune.sndbuf.client. Применяется на соединение, от клиента или к серверу в зависимости от параметра, и используется только для TCP. Значение по умолчанию — ноль, то есть без ограничения. Доступен только в Linux.

tune.pattern.cache-size <number>

tune.pattern.cache-size <number>

Задаёт размер кэша поиска шаблонов равным <number> записей. Это кэш LRU, запоминающий предыдущие поиски и их результаты. Он используется ACL и таблицами соответствий для медленного поиска шаблонов: методов “sub”, “reg”, “dir”, “dom”, “end”, “bin” и строк без учёта регистра. Применяется к выражениям шаблонов, поэтому запоминает результат поиска среди всех шаблонов строки конфигурации, включая загруженные из файлов. Записи, обновлённые действиями HTTP или через CLI, автоматически становятся недействительными. Размер кэша по умолчанию — 10000 записей, что ограничивает объём памяти примерно 5 MB на процесс/поток в 32-битных системах и 8 MB на процесс/поток в 64-битных, поскольку кэши локальны для потока/процесса. Риск коллизии очень мал, порядка размера кэша, делённого на 2^64. Обычно при 10000 запросов в секунду и кэше по умолчанию из 10000 записей вероятность одной коллизии от атаки перебором составляет 1% за 60 лет или 0.1% за 6 лет. Это считается гораздо ниже риска повреждения памяти из-за старения компонентов. Если такой риск неприемлем, кэш можно отключить значением 0.

tune.peers.max-updates-at-once <number>

tune.peers.max-updates-at-once <number>

Задаёт максимальное число обновлений stick-table, которые haproxy пытается обработать за один раз при отправке сообщений. Получение данных обновлений требует блокировок, которые без ограничения могут сильно нагружать CPU на машинах с множеством потоков и увеличивать задержку трафика при начальной пакетной передаче между старым и новым процессом. Малые значения, напротив, тоже могут увеличить накладные расходы CPU и время завершения. Значение по умолчанию — 200, менять его не рекомендуется.

tune.pipesize <size>

tune.pipesize <size>

Задаёт размер буфера канала ядра в байтах. По умолчанию каналы имеют стандартный для системы размер. Иногда при TCP splicing увеличение каналов повышает производительность, особенно если предполагается, что каналы не заполняются и выполняется много вызовов splice(). Это влияет на потребление памяти ядром, поэтому значение нельзя менять без понимания последствий.

tune.pool-high-fd-ratio <number>

tune.pool-high-fd-ratio <number>

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

tune.pool-low-fd-ratio <number>

tune.pool-low-fd-ratio <number>

Задаёт максимальное число файловых дескрипторов, используемых HAProxy глобально, в процентах от максимума доступных HAProxy дескрипторов, при котором прекращается добавление соединений в пул простаивающих соединений для повторного использования. Значение по умолчанию — 20.

tune.pt.zero-copy-forwarding { on | off }

tune.pt.zero-copy-forwarding { on | off }

Включает (‘on’) или отключает (‘off’) пересылку данных без копирования для транзитного мультиплексора. Для её использования также должно быть настроено splicing средствами ядра. По умолчанию включена.

См. также: tune.disable-zero-copy-forwarding, option splice-auto, option splice-request и option splice-response

tune.quic.be.cc.cubic-min-losses <number>

tune.quic.be.cc.cubic-min-losses <number>
tune.quic.fe.cc.cubic-min-losses <number>

Определяет число потерянных пакетов, необходимое алгоритму управления перегрузкой Cubic для признания события потери. Обычно любое событие потери считается результатом перегрузки, и его достаточно, чтобы Cubic снова начал с меньшего окна. Но эксперименты показывают, что у потерь бывают разные причины, совершенно не связанные с перегрузкой: такие потери можно считать ложными, а изменение окна лишь замедляет связь, не давая другого эффекта. Частые причины — слабый радиосигнал, доставка не по порядку, высокое использование CPU клиента со случайными задержками и неточность системного таймера. Этот параметр делает Cubic немного терпимее к ложным потерям, изменяя минимальное суммарное число потерь между двумя ACKs, которое считается событием потери; по умолчанию оно равно 1. Экспериментально наблюдались значительные улучшения, но всегда с ростом пропускной способности, расходуемой на повторные передачи, и риска насыщения перегруженных каналов. Значение 2 можно кратковременно использовать для сравнения метрик. Нельзя превышать 2 без предварительного анализа ситуации специалистом. Значение по умолчанию и минимум — 1. Всегда используйте 1.

tune.quic.cc.cubic.min-losses <number> (deprecated)

tune.quic.cc.cubic.min-losses <number> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.cc.hystart { on | off }

tune.quic.be.cc.hystart { on | off }
tune.quic.fe.cc.hystart { on | off }

Включает (‘on’) или отключает (‘off’) алгоритм HyStart++ (RFC 9406) для соединений QUIC вместо фазы медленного старта алгоритмов управления перегрузкой, которые могут вызывать большие потери пакетов. По умолчанию отключён.

tune.quic.cc-hystart { on | off } (deprecated)

tune.quic.cc-hystart { on | off } (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.cc.max-frame-loss <number>

tune.quic.be.cc.max-frame-loss <number>
tune.quic.fe.cc.max-frame-loss <number>

Задаёт предел числа раз, когда один кадр QUIC может быть отмечен как потерянный. При превышении соединение считается неисправным и немедленно закрывается.

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

tune.quic.max-frame-loss <number> (deprecated)

tune.quic.max-frame-loss <number> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.cc.max-win-size <size>

tune.quic.be.cc.max-win-size <size>
tune.quic.fe.cc.max-win-size <size>

Задаёт максимальный размер окна по умолчанию для контроллера перегрузки одного соединения QUIC на стороне фронтенда или бэкенда. Значение должно быть целым числом с необязательным суффиксом ‘k’, ’m’ или ‘g’ и находиться в пределах от 10k до 4g.

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

Значение по умолчанию — 480k.

См. также параметры “quic-cc-algo” для bind и server.

tune.quic.frontend.default-max-window-size <size> (deprecated)

tune.quic.frontend.default-max-window-size <size> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.cc.reorder-ratio <0..100, in percent>

tune.quic.be.cc.reorder-ratio <0..100, in percent>
tune.quic.fe.cc.reorder-ratio <0..100, in percent>

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

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

tune.quic.reorder-ratio <0..100, in percent> (deprecated)

tune.quic.reorder-ratio <0..100, in percent> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.max-idle-timeout <timeout>

tune.quic.be.max-idle-timeout <timeout>
tune.quic.fe.max-idle-timeout <timeout>

Задаёт транспортный параметр QUIC max_idle_timeout на стороне фронтенда или бэкенда. Использует формат времени HAProxy и выражается в миллисекундах. Определяет время, после которого соединение молча закрывается, если оставалось неактивным в течение соответствующего периода. Обе стороны используют одно согласованное значение: - минимум двух параметров, если оба ненулевые, - максимум, если ненулевым является только один, - если оба параметра нулевые, механизм отключён.

Значение по умолчанию — 30s.

tune.quic.frontend.max-idle-timeout <timeout> (deprecated)

tune.quic.frontend.max-idle-timeout <timeout> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.sec.glitches-threshold <number>

tune.quic.be.sec.glitches-threshold <number>
tune.quic.fe.sec.glitches-threshold <number>

Задаёт порог числа нарушений на соединение на стороне фронтенда или бэкенда, по достижении которого соединение автоматически принудительно закрывается. Это позволяет закрывать некорректно работающие соединения без явных правил. Значение по умолчанию — ноль: порог не задан, поэтому никакое событие не приводит к закрытию соединения. Следует учитывать, что некоторые клиенты QUIC иногда вызывают несколько нарушений за время долгого соединения, поэтому ненулевое значение, вероятно, следует выбирать в сотнях или тысячах, чтобы механизм работал эффективно, не затрагивая клиентов с небольшими отклонениями. С помощью “tune.glitches.kill.cpu-usage” можно также закрывать соединения только при достижении определённого уровня использования CPU.

См. также: fc_glitches, tune.glitches.kill.cpu-usage

tune.quic.frontend.glitches-threshold <number> (deprecated)

tune.quic.frontend.glitches-threshold <number> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.fe.sec.retry-threshold <number>

tune.quic.fe.sec.retry-threshold <number>

Динамически включает Retry для всех настроенных слушателей QUIC при достижении указанного числа полуоткрытых соединений. Полуоткрытое соединение — соединение, рукопожатие которого ещё не завершилось успешно или неудачей. Для работы параметра должен быть задан секрет кластера; иначе он молча игнорируется (см. “cluster-secret”). Параметр также молча игнорируется при принудительном использовании QUIC Retry (см. “quic-force-retry”).

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

Подробнее о QUIC retry см. https://www.rfc-editor.org/rfc/rfc9000.html#section-8.1.2 .

tune.quic.retry-threshold <number> (deprecated)

tune.quic.retry-threshold <number> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.fe.sock-per-conn { default-on | force-off }

tune.quic.fe.sock-per-conn { default-on | force-off }

Глобально задаёт способ использования сокета соединениями QUIC фронтенда для приёма и отправки. Соединения могут совместно использовать сокет слушателя либо выделять собственный сокет для каждого соединения.

Значение по умолчанию — “default-on”: для каждого соединения QUIC выделяется отдельный сокет. Этот вариант предпочтителен для наилучшей производительности при большом трафике QUIC. Это также единственный способ гарантировать корректную мягкую остановку без потери данных для соединений QUIC и эффективную обработку временных ошибок sendto(). Однако он зависит от некоторых расширенных возможностей сетевого стека UDP. Если платформа считается несовместимой, haproxy при запуске автоматически переключается в режим “force-off”. Обратите внимание: слушатели QUIC на привилегированных портах могут требовать работы с uid 0 либо настройки ОС, разрешающей целевому uid привязываться к таким портам, например системных полномочий. См. также глобальную директиву “setcap”.

Значение “force-off” означает, что передача QUIC выполняется через общий сокет слушателя. Это может быть хорошим компромиссом при небольшом трафике, поскольку снижает потребление FD. Но производительность не будет оптимальной из-за более высокого использования CPU, если слушатели разделяются многими потоками или одновременно используется много соединений QUIC.

Этот параметр применяется совместно с параметрами bind “quic-socket”. При глобальном режиме “default-on” он включается для каждого слушателя, кроме настроенных с “quic-socket listener”. Однако глобальное значение “force-off” применяется ко всем экземплярам слушателей независимо от их индивидуальной конфигурации.

tune.quic.socket-owner { connection | listener } (deprecated)

tune.quic.socket-owner { connection | listener } (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Новый параметр называется “tune.quic.fe.sock-per-conn”; прежнее значение “connection” соответствует “default-on”, а “listener” — “force-off”.

tune.quic.be.stream.data-ratio <0..100, in percent>

tune.quic.be.stream.data-ratio <0..100, in percent>
tune.quic.fe.stream.data-ratio <0..100, in percent>

Позволяет задать жёсткий предел числа байт данных в пути по каждому потоку. Выражается в процентах относительно параметра rxbuf потоков соединения QUIC; результат округляется вверх до bufsize.

Значение по умолчанию — 90. Оно подходит для наиболее частого веб-сценария, где данные отправляются лишь по одному или нескольким потокам, а остальные используются только для получения данных. Если предел rxbuf потоков соединения остаётся разумным, это гарантирует, что лишь часть открытых потоков может выделить свой максимальный объём памяти.

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

См. также: “tune.quic.be.stream.rxbuf”, “tune.quic.fe.stream.rxbuf”, “tune.quic.be.stream.max-concurrent”, “tune.quic.fe.stream.max-concurrent”

tune.quic.frontend.stream-data-ratio <0..100, in percent> (deprecated)

tune.quic.frontend.stream-data-ratio  <0..100, in percent> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.stream.max-concurrent <number>

tune.quic.be.stream.max-concurrent <number>
tune.quic.fe.stream.max-concurrent <number>

На стороне фронтенда используется как объявляемое значение транспортного параметра initial_max_streams_bidi. Задаёт максимальное число двунаправленных потоков, которые удалённый одноранговый узел вправе открыть одновременно за время соединения. Фактически ограничивает число одновременных запросов HTTP/3 клиента.

Значение по умолчанию — 100. Обратите внимание: его уменьшение может ограничить возможности буферизации потоков при приёме и ухудшить пропускную способность отправки данных. Это можно исправить увеличением параметра rxbuf потоков соединения QUIC.

На стороне бэкенда haproxy локально ограничивает число одновременных запросов, мультиплексируемых в одном соединении. Управление потоком у однорангового узла может дополнительно снизить этот предел. Может потребоваться уменьшить значение по умолчанию 100 для улучшения отзывчивости сайта ценой большего числа открытых соединений с бэкендом. Как и на стороне фронтенда, параметр напрямую влияет на возможности буферизации Rx, но здесь ограничивает получение данных HTTP. Параметр rxbuf потоков QUIC можно увеличить, если большинство ответов HTTP больше “tune.bufsize”.

См. также: “tune.quic.be.stream.rxbuf”, “tune.quic.fe.stream.rxbuf”, “tune.quic.be.stream.data-ratio”, “tune.quic.fe.stream.data-ratio”

tune.quic.fe.stream.max-total <number>

tune.quic.fe.stream.max-total <number>

Задаёт максимальное число запросов, обслуживаемых одним соединением QUIC. При достижении общего числа начинается плавное завершение соединения. В HTTP/3 это означает отправку кадра GOAWAY. Окончательно соединение закрывается после завершения всех оставшихся передач данных.

Применяется как жёсткий предел соединения через механизм управления потоком QUIC. Если одноранговый узел нарушает его, соединение немедленно закрывается.

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

Значение по умолчанию — 0: отдельного ограничения сверх ограничения кодирования протокола QUIC нет (2^60, более миллиарда миллиардов).

tune.quic.frontend.max-streams-bidi <number> (deprecated)

tune.quic.frontend.max-streams-bidi <number> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.stream.rxbuf <size>

tune.quic.be.stream.rxbuf <size>
tune.quic.fe.stream.rxbuf <size>

Жёсткий предел числа байт данных в пути по соединению QUIC фронтенда. Используется как значение транспортного параметра initial_max_data. Напрямую влияет на пропускную способность отправки однорангового узла в зависимости от задержки и на потребление памяти одним соединением в haproxy.

По умолчанию — 0: значение должно автоматически вычисляться как произведение max-concurrent и bufsize. Его можно увеличить, например если приложение бэкенда зависит от отправки больших объёмов данных в сетях с высокой задержкой.

См. также: “tune.quic.be.stream.max-concurrent”, “tune.quic.fe.stream.max-concurrent”, “tune.quic.be.stream.data-ratio”, “tune.quic.fe.stream.data-ratio”

tune.quic.frontend.max-data-size <size> (deprecated)

tune.quic.frontend.max-data-size <size> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.tx.pacing { on | off }

tune.quic.be.tx.pacing { on | off }
tune.quic.fe.tx.pacing { on | off }

Включает (‘on’) или отключает (‘off’) равномерную отправку данных QUIC. По умолчанию включена. Цель — сгладить отправку данных и уменьшить потери в сети. В большинстве сценариев это значительно повышает пропускную способность, избегая повторных передач. Но в сетях с очень высокой пропускной способностью и низкой задержкой отключение может быть полезно для предотвращения нежелательной задержки и уменьшения использования CPU.

См. также параметры “quic-cc-algo” для bind и server.

tune.quic.disable-tx-pacing (deprecated)

tune.quic.disable-tx-pacing (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.be.tx.udp-gso { on | off }

tune.quic.be.tx.udp-gso { on | off }
tune.quic.fe.tx.udp-gso { on | off }

Включает (‘on’) или отключает (‘off’) поддержку UDP GSO для отправки QUIC. По умолчанию включена. Эта возможность ядра позволяет отправлять несколько датаграмм одним системным вызовом, что эффективнее при больших передачах. При подозрении на проблему отправки может быть полезно отключить её по рекомендации разработчиков.

tune.quic.disable-udp-gso (deprecated)

tune.quic.disable-udp-gso (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.listen { on | off }

tune.quic.listen { on | off }

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

Значение по умолчанию — “on”. При подозрении на проблему с трафиком QUIC параметр позволяет легко переключать слушатели QUIC, не меняя каждую отдельную строку конфигурации.

См. также функцию извлечения образца “quic_enabled”.

tune.quic.mem.tx-max <size>

tune.quic.mem.tx-max <size>

Задаёт максимальный объём памяти, доступный стеку QUIC для отправки на транспортном уровне. Ограничивает как байты в пути, так и выходные буферы мультиплексора. Обратите внимание: для предотвращения конкуренции потоков предел не соблюдается строго и иногда может быть превышен. Кроме того, каждое соединение всегда может использовать окно не менее 2 датаграмм, поэтому вместе с этим параметром следует задать подходящий maxconn.

tune.quic.frontend.max-tx-mem <size> (deprecated)

tune.quic.frontend.max-tx-mem <size> (deprecated)

Это ключевое слово объявлено устаревшим в 3.3 и будет удалено в 3.5. Это часть упрощения конфигурации QUIC. Если параметр используется, он применяется только к соединениям фронтенда.

tune.quic.zero-copy-fwd-send { on | off }

tune.quic.zero-copy-fwd-send { on | off }

Включает (‘on’) или отключает (‘off’) отправку данных без копирования для мультиплексора QUIC. По умолчанию включена.

См. также: tune.disable-zero-copy-forwarding

tune.renice.runtime <number>

tune.renice.runtime <number>

Этот параметр конфигурации принимает значения от -20 до 19. Задаёт приоритет планирования согласно man 2 setpriority. Приоритет применяется после разбора конфигурации, то есть только рабочим или самостоятельным процессом. Обычно он задаёт более высокий приоритет, чем у процесса, разбирающего конфигурацию (tune.renice.startup).

См. также: tune.renice.startup

tune.renice.startup <number>

tune.renice.startup <number>

Этот параметр конфигурации принимает значения от -20 до 19. Задаёт приоритет планирования согласно man 2 setpriority. Приоритет применяется перед остальной конфигурацией, что полезно для снижения приоритета её разбора. Он применяется к самостоятельному или рабочему процессу до разбора конфигурации. После разбора прежний приоритет восстанавливается, если не используется tune.renice.runtime.

См. также: tune.renice.runtime

tune.rcvbuf.backend <size>

tune.rcvbuf.backend  <size>
tune.rcvbuf.frontend <size>

Задаёт размер буфера приёма сокета ядра для неподключённых сокетов. Может использоваться для QUIC в режиме слушателя и log-forward на фронтенде. Системные буферы по умолчанию иногда слишком малы для сокетов, принимающих большой суммарный трафик, что вызывает потери и, в случае QUIC, возможные повторные передачи, а также может замедлять установление соединений при высокой нагрузке. Значение выражается в байтах и применяется к каждому сокету. В режиме слушателя сокеты разделяются всеми соединениями, а их общее число зависит от “shards” строки “bind”. Единого удачного значения нет: оно соответствует ожидаемому размеру на соединение, умноженному на ожидаемое число соединений. Ядро может уменьшать большие значения. См. также аналоги для подключённых сокетов “tune.rcvbuf.client” и “tune.rcvbuf.server”, а также параметры отправки “tune.sndbuf.backend” и “tune.sndbuf.frontend”.

tune.rcvbuf.client <size>

tune.rcvbuf.client <size>
tune.rcvbuf.server <size>

Принудительно задаёт размер буфера приёма сокета ядра на стороне клиента или сервера указанным значением в байтах. Применяется ко всем фронтендам и бэкендам TCP/HTTP. Обычно его никогда не следует задавать: размер по умолчанию 0 позволяет ядру автоматически подбирать значение по доступной памяти. Однако иногда очень малые значения, например 4096, помогают экономить память ядра, не позволяя буферизовать слишком много принятых данных. При этом малые значения значительно повышают использование CPU.

tune.recv_enough <size>

tune.recv_enough <size>

HAProxy использует несколько признаков, чтобы определить, что короткое чтение означает конец данных в буферах сокета. Один из них — чтение возвращает больше <recv_enough> байт; по умолчанию это 10136 (7 сегментов по 1448). Этим параметром можно изменить значение по умолчанию для лучшей работы с нагрузками, содержащими много коротких сообщений, например сеансами telnet или SSH.

tune.ring.queues <number>

tune.ring.queues <number>

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

tune.runqueue-depth <number>

tune.runqueue-depth <number>

Задаёт максимальное число задач, обрабатываемых за один раз при выполнении задач. Значение по умолчанию зависит от числа потоков, но находится между 35 и 280: такие значения обычно дают наибольшую интенсивность запросов и наименьшие задержки. Увеличение может добавить задержку при вводе-выводе, а слишком малое значение — дополнительные накладные расходы. При большем числе потоков полезны меньшие значения. При экспериментах со значительно большими значениями может быть полезно также включить tune.sched.low-latency и, возможно, tune.fd.edge-triggered, чтобы максимально снизить наибольшую задержку.

tune.sched.low-latency { on | off }

tune.sched.low-latency { on | off }

Включает (‘on’) или отключает (‘off’) планировщик задач с низкой задержкой. По умолчанию HAProxy обрабатывает задачи нескольких классов по одному классу за раз, поскольку это наиболее эффективно. Но при больших значениях tune.runqueue-depth это может заметно влиять на задержку запросов или соединений. При включении этого параметра задачи классов с более низким приоритетом, если они есть, всегда выполняются раньше остальных. Это уменьшает максимальную задержку новых запросов или соединений на фоне большого трафика, но сильнее влияет на этот большой трафик. Для обычного использования лучше оставить параметр выключенным. Значение по умолчанию — off.

tune.sndbuf.backend <size>

tune.sndbuf.backend  <size>
tune.sndbuf.frontend <size>

Задаёт размер буфера отправки сокета ядра для неподключённых сокетов. Используется для ведения журнала через сокет UNIX и UDP на стороне бэкенда и для QUIC в режиме слушателя на фронтенде. Системные буферы по умолчанию иногда слишком малы для сокетов, разделяемых множеством соединений или отправителей журналов, что вызывает потери, возможные повторные передачи и замедляет установление новых соединений при высоком трафике. Значение выражается в байтах и применяется к каждому сокету. В режиме слушателя сокеты разделяются всеми соединениями, а их общее число зависит от “shards” строки “bind”. Единого удачного значения нет: оно соответствует ожидаемому размеру на соединение, умноженному на ожидаемое число соединений. Ядро может уменьшать большие значения. См. также аналоги для подключённых сокетов “tune.sndbuf.client” и “tune.sndbuf.server”, а также параметры приёма “tune.rcvbuf.backend” и “tune.rcvbuf.frontend”.

tune.sndbuf.client <size>

tune.sndbuf.client <size>
tune.sndbuf.server <size>

Принудительно задаёт размер буфера отправки сокета ядра на стороне клиента или сервера указанным значением в байтах. Применяется ко всем фронтендам и бэкендам TCP/HTTP. Обычно его никогда не следует задавать: размер по умолчанию 0 позволяет ядру автоматически подбирать значение по доступной памяти. Однако иногда очень малые значения, например 4096, помогают экономить память ядра, не позволяя буферизовать слишком много принятых данных. При этом малые значения значительно повышают использование CPU. Ещё один случай использования — предотвращение тайм-аутов записи с чрезвычайно медленными клиентами, когда ядро ждёт чтения большой части буфера перед повторным уведомлением HAProxy. См. также tune.notsent-lowat.client и tune.notsent-lowat.server: в Linux они позволяют эффективнее и точнее управлять памятью и отзывчивостью без потери производительности.

tune.ssl.cachesize <number>

tune.ssl.cachesize <number>

Задаёт размер глобального кэша сеансов SSL в блоках. Блок достаточно велик для закодированного сеанса без сертификата однорангового узла. Сеанс с таким сертификатом хранится в нескольких блоках в зависимости от размера сертификата. Блок использует примерно 200 байт памяти согласно расчёту sizeof(struct sh_ssl_sess_hdr) + SHSESS_BLOCK_MIN_SIZE для функции shctx_init. Значение по умолчанию можно задать при сборке; иначе оно равно 20000. При заполнении кэша дольше всех неиспользуемые записи удаляются и назначаются заново. Большие значения сокращают такие удаления и число сильно нагружающих CPU рукопожатий SSL, позволяя всем пользователям сохранять сеансы как можно дольше. Все записи предварительно выделяются при запуске. Значение 0 отключает кэш сеансов SSL.

tune.ssl.capture-buffer-size <number>

tune.ssl.capture-buffer-size <number>
tune.ssl.capture-cipherlist-size <number> (deprecated)

Задаёт максимальный размер буфера для захвата списка шифров client hello, списка расширений, списка эллиптических кривых и форматов точек эллиптических кривых. При значении 0, используемом по умолчанию, захват отключён; иначе для каждого соединения SSL/TLS выделяется буфер.

tune.ssl.certificate-compression { auto | off }

tune.ssl.certificate-compression { auto | off }

Позволяет настроить поддержку сжатия сертификатов — расширения TLS 1.3 (RFC 8879).

При “auto” используется значение по умолчанию библиотеки TLS.

При “off” выполняется попытка явно отключить поддержку этой возможности. HAProxy больше не пытается отправлять сжатые сертификаты и не принимает их.

Настраивает стороны бэкенда и фронтенда.

Это ключевое слово поддерживается OpenSSL >= 3.2.0.

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

tune.ssl.default-dh-param <number>

tune.ssl.default-dh-param <number>

Задаёт максимальный размер параметров Диффи — Хеллмана для генерации эфемерного или временного ключа при обмене DHE. Конечный размер стремится совпасть с размером ключа RSA или DSA сервера, например временный ключ DH в 2048 бит для ключа RSA в 2048 бит, но не превышает этот максимум. Разрешены только значения 1024 или выше. Большие значения повышают нагрузку CPU; значения больше 1024 бит не поддерживаются клиентами Java 7 и более ранними. Параметр не используется, если статические параметры Диффи — Хеллмана заданы непосредственно в файле сертификата либо через ssl-dh-param-file. Если не определены ни default-dh-param, ни ssl-dh-param-file и файл PEM сервера данного фронтенда не содержит собственных параметров DH, шифры DHE недоступны для этого фронтенда.

tune.ssl.force-private-cache

tune.ssl.force-private-cache

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

tune.ssl.hard-maxrecord <number>

tune.ssl.hard-maxrecord <number>

Задаёт максимальное число байт, передаваемых SSL_write() за один раз. Значение по умолчанию 0 означает отсутствие ограничения. В отличие от tune.ssl.maxrecord этот параметр не подстраивается динамически. Меньшие записи могут снизить пропускную способность, но могут требоваться для клиентов с малым объёмом ресурсов.

tune.ssl.keylog { on | off }

tune.ssl.keylog { on | off }

Включает запись ключей TLS в журнал. Использовать следует осторожно: расходуется больше памяти на сеанс SSL и может снижаться производительность. По умолчанию отключено.

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

https://tlswg.org/sslkeylogfile/draft-ietf-tls-keylogfile.html

SSLKEYLOG представляет собой последовательность строк следующего формата:

<Label> <space> <ClientRandom> <space> <Secret>

Значение ClientRandom предоставляет функция извлечения образца %[ssl_fc_client_random,hex]; секрет и метку Label можно найти в таблице ниже. Нужно создать SSLKEYLOGFILE со всеми метками из этой таблицы.

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

  Метка SSLKEYLOGFILE             |  Извлечение образцов секретов
  --------------------------------|-----------------------------------------
  CLIENT_EARLY_TRAFFIC_SECRET     |  %[ssl_xx_client_early_traffic_secret]
  CLIENT_HANDSHAKE_TRAFFIC_SECRET |  %[ssl_xx_client_handshake_traffic_secret]
  SERVER_HANDSHAKE_TRAFFIC_SECRET |  %[ssl_xx_server_handshake_traffic_secret]
  CLIENT_TRAFFIC_SECRET_0         |  %[ssl_xx_client_traffic_secret_0]
  SERVER_TRAFFIC_SECRET_0         |  %[ssl_xx_server_traffic_secret_0]
  EXPORTER_SECRET                 |  %[ssl_xx_exporter_secret]
  EARLY_EXPORTER_SECRET           |  %[ssl_xx_early_exporter_secret]

Эти функции извлечения существуют для стороны фронтенда (fc) или бэкенда (bc); для нужной стороны следует заменить “xx” на “fc” или “bc”.

Доступно только с OpenSSL 1.1.1 и полезно для сеанса TLS1.3.

Для создания содержимого SSLKEYLOGFILE с TLS < 1.3 нужна только эта строка:

“CLIENT_RANDOM %[ssl_fc_client_random,hex] %[ssl_fc_session_key,hex]”

Полный журнал ключей можно создать следующим log-format, хотя для syslog это неидеально:

log-format "CLIENT_EARLY_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_client_early_traffic_secret]\n
            CLIENT_HANDSHAKE_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_client_handshake_traffic_secret]\n
            SERVER_HANDSHAKE_TRAFFIC_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_server_handshake_traffic_secret]\n
            CLIENT_TRAFFIC_SECRET_0 %[ssl_bc_client_random,hex] %[ssl_bc_client_traffic_secret_0]\n
            SERVER_TRAFFIC_SECRET_0 %[ssl_bc_client_random,hex] %[ssl_bc_server_traffic_secret_0]\n
            EXPORTER_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_exporter_secret]\n
            EARLY_EXPORTER_SECRET %[ssl_bc_client_random,hex] %[ssl_bc_early_exporter_secret]"

HAProxy также предоставляет эти форматы как предопределённые переменные окружения, которые можно напрямую использовать в директиве “log-format”:

$HAPROXY_KEYLOG_FC_LOG_FMT   ключи соединения фронтенда (со стороны клиента)
$HAPROXY_KEYLOG_BC_LOG_FMT   ключи соединения бэкенда (со стороны сервера)

tune.ssl.keyupdate-rate-limit <limit>

tune.ssl.keyupdate-rate-limit <limit>

Ограничивает принимаемое число KeyUpdate в секунду значением <limit>, после которого это считается потоком избыточных обновлений и соединение принудительно закрывается. Обработка KeyUpdate требует много CPU, и мало оснований получать их в большом числе. Значение “0” отключает ограничение интенсивности. Значение по умолчанию — 100.

tune.ssl.lifetime <timeout>

tune.ssl.lifetime <timeout>

Задаёт срок действия кэшированного сеанса SSL. Время выражается в секундах; по умолчанию — 300 (5 min). Следует понимать, что это не гарантирует сохранение сеансов на такой срок: при заполнении кэша дольше всех неиспользуемые сеансы удаляются независимо от заданного срока действия. Главная польза параметра — предотвращение слишком долгого использования сеансов.

tune.ssl.maxrecord <number>

tune.ssl.maxrecord <number>

Задаёт максимальное число байт, передаваемых SSL_write() в начале передачи данных. Значение по умолчанию 0 означает отсутствие ограничения. При SSL/TLS клиент может расшифровать данные только после получения полной записи. При больших записях ему может потребоваться загрузить до 16kB данных перед началом обработки. Ограничение может ускорить загрузку страниц в браузерах в сетях с высокой задержкой или низкой пропускной способностью. Рекомендуется подобрать оптимальные значения, помещающиеся в 1 или 2 сегмента TCP: обычно 1448 байт в Ethernet с включёнными временными метками TCP или 1460 при отключённых. Следует учитывать накладные расходы SSL/TLS. Типичные значения 1419 и 2859 показали хорошие результаты в тестах. Для выбора лучшего значения используется “strace -e trace=write”. HAProxy автоматически переключается на этот параметр после обнаружения простаивающего потока (см. выше tune.idletimer). См. также tune.ssl.hard-maxrecord.

tune.ssl.ssl-ctx-cache-size <number>

tune.ssl.ssl-ctx-cache-size <number>

Задаёт размер кэша созданных сертификатов равным <number> записей. Это кэш LRU. Динамическое создание сертификата SSL затратно, поэтому сертификаты кэшируются. Размер кэша по умолчанию — 1000 записей.

tune.streams-elasticity <number>

tune.streams-elasticity <number>

Задаёт целевой процент потоков на соединение фронтенда относительно максимального числа одновременных соединений (maxconn), когда все соединения установлены. Метрика применяется к мультиплексируемым протоколам, например HTTP/2 и QUIC, где каждое соединение может получать несколько потоков. Всегда гарантируется хотя бы один, поэтому процент должен быть не меньше 100%. При установлении соединений HAProxy динамически объявляет дополнительные потоки до заданного предела, сохраняя целевое соотношение. При установлении каждое соединение фронтенда получает хотя бы один поток; дополнительные назначаются по целевому проценту и настроенным ограничениям потоков. Это обеспечивает эффективное распределение потоков при меняющейся нагрузке: больше при низкой, меньше при высокой.

Очень динамичные сайты с множеством объектов на странице выигрывают от высоких коэффициентов, позволяющих использовать много потоков на соединение. Сайты с меньшим средним числом потоков, например WebSocket или код приложения, могут предпочесть малые коэффициенты около 120 или 150: потоков на 20–50% больше, чем соединений. Это предотвращает чрезмерное число потоков при длительной нагрузке.

Значение по умолчанию — 0: на этом уровне ограничение не применяется, действуют лишь настройки H2 и QUIC. При значении по умолчанию 100 потоков на соединение это соответствует 10000%. Это остаётся рекомендуемым вариантом для небольших развёртываний, где maxconn около тысячи. Конфигурации среднего размера, от нескольких тысяч до десятков тысяч соединений, обычно задают коэффициент от 1000 до 5000, позволяющий от 10 до 50 потоков на соединение при полной нагрузке. Крупные развёртывания, от сотен тысяч до миллионов соединений, могут использовать меньшие значения от 120 до 200, в среднем от 1.2 до 2 потоков на соединение при полной нагрузке.

В отличие от HTTP/2, QUIC способен динамически менять число одновременных потоков за время соединения. Однако управление потоком QUIC строже, чем в HTTP/2, поэтому лучше задавать достаточно большие значения, чтобы избежать дополнительной задержки соединения. Есть также ограничение для слушателей QUIC с включённым 0-RTT: начальное значение, объявляемое одноранговому узлу, игнорирует эластичность потоков и зависит только от “tune.quic.fe.stream.max-concurrent”. Но после этого начального объявления эластичность потоков продолжает действовать за время соединения.

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

tune.stick-counters <number>

tune.stick-counters <number>

Задаёт число счётчиков привязок, одновременно отслеживаемых соединением или запросом действиями “track-sc*” в правилах “tcp-request” или “http-request”. Значение по умолчанию задаётся при сборке макросом MAX_SESS_STK_CTR и равно 3. Параметр позволяет изменить его, игнорируя значение сборки, но нельзя задать больше 100. Увеличение может понадобиться при переносе сложных конфигураций в haproxy, однако следует учитывать затраты: каждая запись занимает 16 байт на соединение и 16 байт на запрос; для всех запросов эту память нужно выделять и обнулять, даже когда она не используется. Поэтому значение 10 увеличивает расход памяти на запрос на 320 байт и заставляет очищать её при каждом запросе, что заметно влияет на CPU. Если правил “track-sc” нет, значение, напротив, можно уменьшить; 0 допустим для полного отключения счётчиков привязок.

tune.takeover-other-tg-connections <value>

tune.takeover-other-tg-connections <value>

По умолчанию попыток использовать простаивающие соединения других групп потоков нет, но это можно изменить. Допустимые значения <value>: “none”, значение по умолчанию, не пытается использовать простаивающие соединения других групп; “restricted” пытается получить простаивающее соединение другого потока только при протоколах, которые не могут создавать новые соединения, например reverse http, а также при strict-maxconn; “full” всегда ищет простаивающие соединения в других группах потоков. Обратите внимание: соединения других групп могут снижать производительность, поэтому использовать их не следует без действительной необходимости. Теперь это поведение управляется tune.idle-pool.shared; это ключевое слово оставлено лишь для совместимости со старыми конфигурациями и будет объявлено устаревшим.

tune.vars.global-max-size <size>

tune.vars.global-max-size <size>
tune.vars.proc-max-size <size>
tune.vars.reqres-max-size <size>
tune.vars.sess-max-size <size>
tune.vars.txn-max-size <size>

Эти пять параметров помогают управлять максимальным объёмом памяти системы переменных. “global” ограничивает общую память всех областей действия; “proc” — память области процесса; “sess” — области сеанса; “txn” — области транзакции; “reqres” — обработки каждого запроса или ответа. Учёт памяти иерархический: более общие ограничения включают более узкие. “proc” включает “sess”, “sess” — “txn”, а “txn” — “reqres”.

Например, при ограничении “tune.vars.sess-max-size” до 100 значения “tune.vars.txn-max-size” и “tune.vars.reqres-max-size” тоже не могут превышать 100. Переменная “txn.var” со 100 байтами занимает всё доступное пространство. Обратите внимание: превышение ограничений во время работы не вызывает сообщения об ошибке, но значения могут усекаться или повреждаться. Поэтому следует точно планировать пространство для хранения всех переменных.

tune.zlib.memlevel <number>

tune.zlib.memlevel <number>

Задаёт параметр memLevel при инициализации zlib для каждого потока. Он определяет, сколько памяти следует выделить для внутреннего состояния сжатия. Значение 1 использует минимум памяти, но работает медленно и снижает степень сжатия; 9 использует максимум памяти для оптимальной скорости. Допустимы значения от 1 до 9. Значение по умолчанию — 8.

tune.zlib.windowsize <number>

tune.zlib.windowsize <number>

Задаёт размер окна, то есть буфера истории, как параметр инициализации zlib для каждого потока. Большие значения улучшают сжатие ценой потребления памяти. Допустимы значения от 8 до 15. Значение по умолчанию — 15.

3.3. Отладка

anonkey <key>

anonkey <key>

Задаёт глобальный ключ анонимизации <key>, который должен быть 32-битным числом от 0 до 4294967295. Он используется по умолчанию командами CLI при включённом режиме анонимизации. Его можно также задать во время работы командой CLI “set anon global-key”. См. также аргумент командной строки “-dC” в руководстве по управлению.

debug.counters { on | off }

debug.counters { on | off }

Включает (‘on’) или отключает (‘off’) обновление счётчиков событий в коде. Они выводятся под типом “CNT” командой CLI “debug counters”. Счётчики доступны только при сборке с DEBUG_COUNTERS не меньше 1. При значении 1 они по умолчанию не обновляются (“debug.counters off”), а при 2 обновляются (“debug.counters on”). Обычно менять параметр нет причин, если только этого не просит разработчик или не подозревается необычно большое использование CPU; в последнем случае необходимо отправить разработчикам сообщение с дампом счётчиков. Состояние можно также изменить во время работы командой CLI “debug counters”. См. руководство по управлению.

force-cfg-parser-pause <timeout>

force-cfg-parser-pause <timeout>

Приостанавливает разбор конфигурации на <timeout> миллисекунд. Полезно для разработки или проверки тайм-аутов сценариев инициализации, особенно для имитации очень долгой перезагрузки. Требует заданного expose-experimental-directives.

<timeout> — значение тайм-аута, по умолчанию в миллисекундах. Можно использовать любую другую единицу, добавив её суффиксом к числу, как объясняется в начале документа.

Пример:

global
    expose-experimental-directives
    force-cfg-parser-pause 10s

quick-exit

quick-exit

Ускоряет выход старого процесса при перезагрузке, пропуская освобождение объектов памяти и слушателей: ОС сама возвращает их при завершении процесса. Выигрыш невелик — максимум порядка нескольких сотен миллисекунд для огромных конфигураций. Основной случай использования — обнаруженная ошибка кода deinit(), которую таким образом можно обойти. Лучше не использовать параметр без указания разработчиков.

quiet

quiet

Не выводит никаких сообщений при запуске. Эквивалентно аргументу командной строки “-q”.

warn-blocked-traffic-after <time>

warn-blocked-traffic-after <time>

Позволяет задать задержку, после которой зависшая задача, блокирующая трафик, вызывает предупреждение в стандартном потоке ошибок. Задержка выражается в миллисекундах; по умолчанию — 100 ms. Допустимые значения должны находиться в пределах от 1 ms до 1000 ms включительно. Малые значения вызывают частые предупреждения, большие — редкие. В любом случае сторожевой таймер завершает вышедшую из-под контроля задачу, которая дважды по одной секунде не отвечает, поэтому задержка предупреждения 1000 ms обычно не вызывает предупреждений. Рекомендуется оставаться в пределах от 10 до 100ms для обнаружения ошибок конфигурации, ухудшающих работу пользователя долгими ответами или рывками интерактивных сеансов. Например, это может вызывать неудачно спроектированная функция извлечения образца Lua с тяжёлыми вычислениями либо очень большой файл таблицы соответствий map_reg или map_regm с высокой стоимостью вычисления. Для сравнения: рукопожатие TLS может занимать от одной до двух миллисекунд, а сжатие буфера ответа HTTP размером 16kB — около одной миллисекунды. Вывод содержит дамп потока проблемной задачи с трассировкой стека и контекстом, помогающим понять, на что расходуется время.

zero-warning

zero-warning

При заданном параметре HAProxy отказывается запускаться, если при разборе и применении конфигурации выдано хотя бы одно предупреждение. Предупреждения о неверных сочетаниях параметров, слишком высоких ограничениях, которые не удалось установить, и тому подобном завершают процесс с ошибкой при запуске. Некоторые поздние предупреждения запуска перехватить нельзя, например невозможность удалить дополнительные группы при смене идентификатора группы в режимах “daemon” или “master-worker” либо невозможность разрешить создание дампа процесса после fork(). Параметр не перехватывает предупреждения во время работы. Настоятельно рекомендуется включать его для редко изменяемых конфигураций: это помогает обнаруживать неочевидные ошибки и сохранять конфигурацию чистой и совместимой с будущими версиями. Обратите внимание: “haproxy -c” в таком случае тоже сообщает об ошибках. Параметр эквивалентен аргументу командной строки “-dW”.

3.4. Настройка HTTPClient

HTTPClient — внутренняя библиотека HTTP, доступная различным подсистемам, например сценариям LUA. Она не используется в тракте данных и не связана с трафиком HTTP, проходящим через HAProxy.

httpclient.resolvers.disabled <on|off>

httpclient.resolvers.disabled <on|off>

Отключает разрешение DNS httpclient. Предотвращает создание секции resolvers “default”.

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

httpclient.resolvers.id <resolvers id>

httpclient.resolvers.id <resolvers id>

Определяет секцию resolvers, с которой httpclient пытается разрешать имена.

По умолчанию используется идентификатор resolvers “default”. Если параметр не задан, при отсутствии секции разрешение имён просто отключается.

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

httpclient.resolvers.prefer <ipv4|ipv6>

httpclient.resolvers.prefer <ipv4|ipv6>

Позволяет выбрать семейство IP при разрешении имён, что удобно, если в сети нет IPv6. По умолчанию — “ipv6”.

httpclient.retries <number>

httpclient.retries <number>

Позволяет настроить число повторных попыток httpclient при неудачном запросе. Работает так же, как ключевое слово “retries” в бэкенде.

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

httpclient.ssl.ca-file <cafile>

httpclient.ssl.ca-file <cafile>

Определяет ca-file, который следует использовать для проверки сертификата сервера. Принимает те же параметры, что “ca-file” в строке server.

По умолчанию, если параметр не задан, используется “@system-ca”, пытающийся загрузить системные CA. При неудаче SSL для httpclient отключается.

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

httpclient.ssl.verify [none|required]

httpclient.ssl.verify [none|required]

Работает так же, как параметр verify строк server. При ’none’ сертификаты серверов не проверяются. По умолчанию — “required”.

По умолчанию, если параметр не задан, используется “required”. При неудаче SSL для httpclient отключается.

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

httpclient.timeout.connect <timeout>

httpclient.timeout.connect <timeout>

Задаёт максимальное время ожидания попытки соединения по умолчанию для httpclient.

Аргументы:

<timeout> — значение тайм-аута, по умолчанию в миллисекундах. Можно использовать
            и другую единицу измерения, добавив её к числу в качестве суффикса,
            как объясняется в начале этого документа.

Значение по умолчанию — 5000ms.

13 - 4. Прокси

Конфигурация прокси может размещаться в нескольких типах секций:

• defaults [<name>] [ from <defaults_name> ]
• frontend <name> [ from <defaults_name> ]
• backend <name> [ from <defaults_name> ]
• listen <name> [ from <defaults_name> ]

Секция “frontend” описывает набор слушающих сокетов, принимающих клиентские соединения.

Секция “backend” описывает набор серверов, к которым прокси подключается для пересылки входящих соединений.

Секция “listen” определяет полноценный прокси, у которого фронтенд и бэкенд объединены в одной секции. Обычно она удобна для трафика, использующего только TCP.

Секция “defaults” сбрасывает все настройки до документированных значений и задаёт новые значения для последующих секций. Все секции “frontend”, “backend” и “listen” всегда получают начальные настройки из секции defaults; по умолчанию это последняя такая секция перед вновь создаваемой секцией. Можно явно указать конкретную секцию “defaults”, из которой нужно загрузить начальные настройки: для этого в строке секции после необязательного ключевого слова “from” указывают её имя. Хотя имя секции “defaults” не обязательно, рекомендуется задавать его для удобства чтения. Кроме того, это единственный способ выбрать конкретную секцию вместо предыдущей, используемой по умолчанию. Поскольку имена секций “defaults” необязательны, по умолчанию к ним применяются очень мягкие требования и даже допускаются совпадающие имена. Однако если на секцию “defaults” ссылается любая другая секция, её имя должно соответствовать синтаксису имён прокси и быть уникальным среди секций defaults. Независимо от того, что допускается сейчас, в целом рекомендуется избегать повторяющихся имён секций и соблюдать тот же синтаксис, что и для имён прокси. В будущей версии это правило может стать обязательным. Кроме того, выдаётся предупреждение, если один прокси явно использует секцию defaults, а другой одновременно использует её неявно, поскольку она определена последней. Настоятельно рекомендуется не смешивать эти способы: либо всегда использовать явные ссылки, либо добавить в конце общую секцию defaults, предназначенную для всех неявных обращений.

Секция defaults может даже получать начальные настройки из другой такой секции, наследуя настройки через несколько уровней секций defaults. Это удобно для создания профилей конфигурации с группами настроек по умолчанию (например, для TCP и HTTP либо с короткими и длинными тайм-аутами), однако в такой иерархии легко запутаться.

По умолчанию именованные секции defaults сохраняются после разбора конфигурации. Это позволяет повторно использовать их при динамическом создании бэкендов. Такое поведение можно изменить глобально с помощью ключевого слова “tune.defaults.purge”.

Все имена прокси должны состоять из прописных и строчных букв, цифр, символов ‘-’ (дефис), ‘_’ (подчёркивание), ‘.’ (точка) и ‘:’ (двоеточие). Имена ACL чувствительны к регистру, поэтому “www” и “WWW” — два разных прокси.

Раньше имена прокси могли совпадать при выполнении определённых условий (например, если наборы их возможностей фронтенда/бэкенда различались), однако это вызывало слишком много проблем в журналах, а также путаницу при операциях через CLI, именовании таблиц привязок и получении статистики. Теперь два прокси обязательно должны иметь разные имена независимо от их возможностей.

В настоящее время поддерживаются два основных режима прокси: “tcp”, также известный как режим уровня 4, и “http”, также известный как режим уровня 7. В режиме уровня 4 HAProxy просто пересылает двунаправленный трафик между двумя сторонами. В режиме уровня 7 HAProxy анализирует протокол и может взаимодействовать с ним: разрешать, блокировать, переключать, добавлять, изменять или удалять произвольное содержимое запросов и ответов на основе произвольных критериев.

В режиме HTTP обработка запросов и ответов, проходящих через соединение, зависит от сочетания параметров HTTP фронтенда и бэкенда. HAProxy поддерживает 3 режима соединений:

• KAL: постоянное соединение (“option http-keep-alive”), режим по умолчанию: все запросы и ответы обрабатываются, а между ответами и новыми запросами соединения остаются открытыми, но неактивными.

• SCL: закрытие соединения с сервером (“option http-server-close”): соединение со стороны сервера закрывается после получения конца ответа, а соединение со стороны клиента остаётся открытым.

• CLO: закрытие (“option httpclose”): соединение закрывается после окончания ответа, а в обоих направлениях добавляется “Connection: close”.

Итоговый режим соединения, проходящего через фронтенд и бэкенд, определяется режимами обоих прокси по следующей матрице. Режимы симметричны: постоянное соединение имеет самый низкий приоритет, а закрытие — самый высокий.

               Режим бэкенда

                | KAL | SCL | CLO
            ----+-----+-----+----
            KAL | KAL | SCL | CLO
            ----+-----+-----+----
   режим    SCL | SCL | SCL | CLO
            ----+-----+-----+----
            CLO | CLO | CLO | CLO

Можно последовательно соединить фронтенд TCP с бэкендом HTTP. Если обрабатывается только трафик HTTP, это не имеет смысла. Однако такой подход позволяет обрабатывать несколько протоколов в одном фронтенде. В этом случае клиентское соединение сначала обрабатывается как обычное соединение tcp, а затем переводится в режим HTTP. До этого перехода обработка содержимого выполняется над необработанными данными. После перехода данные разбираются и хранятся во внутреннем представлении HTX, поэтому использовать их исходное представление больше невозможно. Обратный переход не предусмотрен.

Существует два типа переходов к HTTP: с сохранением прикладного потока и с его уничтожением. Первый тип — переход от TCP к HTTP/1. В HTTP/1 запросы обрабатываются последовательно, поэтому прикладной поток можно сохранить. Второй тип — переход от TCP к HTTP/2. Поскольку этот протокол использует мультиплексирование, прикладной поток нельзя связать с каким-либо потоком HTTP/2, и он уничтожается. Затем, когда HAProxy получает новые потоки HTTP/2 на нижнем уровне, в мультиплексоре H2, создаются новые прикладные потоки. Это различие необходимо понимать, поскольку оно существенно меняет способ обработки данных. При переходе к HTTP/1 результаты обработки содержимого, уже выполненной над необработанными данными, не теряются, а сама обработка не выполняется повторно. При переходе к HTTP/2 прикладные потоки различаются, и все правила фронтенда последовательно проверяются для каждого из них. Как уже было сказано, первый поток, то есть поток TCP, уничтожается, но только после проверки правил фронтенда.

При обработке HTTP из прокси TCP необходимо учитывать ещё один важный момент. HAProxy может разбирать HTTP/1 на лету в правилах tcp-request content, однако для HTTP/2 это невозможно: разобрать можно только преамбулу HTTP/2. Это серьёзно ограничивает анализ содержимого HTTP в TCP. По сути, можно лишь определить, являются ли полученные данные HTTP. Например, выбрать бэкенд по значению заголовка Host нельзя, хотя в HTTP/1 это делается легко. Однако существует способ смягчить это ограничение.

Перейти к HTTP можно двумя способами. Первый, используемый исторически, — выбрать бэкенд HTTP. Переход происходит при назначении бэкенда. Поэтому при переходе с сохранением потока для обработки данных HTTP учитывается только конфигурация бэкенда. При переходе с уничтожением потока прикладной поток уничтожается и его обработка прекращается. Как отмечено выше, при этом способе возможности выбора бэкенда для соединения HTTP/2 весьма ограничены и почти бесполезны, поскольку поток уничтожается. Второй способ — выполнить переход во время проверки правил tcp-request content с помощью действия “switch-mode http”. В этом случае переход выполняется в контексте фронтенда, в котором можно определить директивы HTTP. При переходе с сохранением потока это позволяет как можно раньше использовать все возможности анализа HTTP. Такой вариант мало отличается от фронтенда HTTP. При переходе с уничтожением потока это ничего не меняет, за исключением того, что выбирать бэкенд по ограниченным данным бессмысленно. Рекомендуется именно этот способ. Таким образом, для перехода к HTTP достаточно проверить протокол запроса в правилах tcp-request content. Остальную обработку HTTP можно перенести в набор правил http-request фронтенда. Однако правила tcp-request content по-прежнему проверяются для каждого потока; изменить это нельзя.

4.1. Матрица ключевых слов прокси

Поддерживается приведённый ниже список ключевых слов. Большинство из них можно использовать только в ограниченном наборе типов секций. Некоторые помечены как «устаревшие», поскольку они унаследованы от старого синтаксиса, который может быть неоднозначным или иметь функциональные ограничения, и для их замены рекомендуются новые ключевые слова. Действие ключевых слов с пометкой “(*)” при необходимости можно инвертировать с помощью префикса “no”, например “no option contstats”. Это имеет смысл, когда параметр включён по умолчанию, но его необходимо отключить для конкретного экземпляра. Перед такими параметрами также можно поставить “default”, чтобы восстановить настройки по умолчанию независимо от того, что было задано в предыдущей секции “defaults”. Ключевые слова, разрешённые в секциях defaults и отмеченные “(!)”, поддерживаются только в именованных секциях defaults, но не в анонимных.

Примечание: некоторые опасные и не рекомендуемые директивы намеренно не включены в следующую матрицу. Это сделано специально. Эти директивы описаны в документации, однако отсутствие их в таблице — ещё один способ предостеречь от их использования.

 ключевое слово                       defaults   frontend   listen    backend
------------------------------------+----------+----------+---------+---------
acl                                       X (!)      X         X         X
backlog                                   X          X         X         -
balance                                   X          -         X         X
be-unpublished                            -          -         X         X
bind                                      -          X         X         -
capture cookie                            -          X         X         -
capture request header                    -          X         X         -
capture response header                   -          X         X         -
clitcpka-cnt                              X          X         X         -
clitcpka-idle                             X          X         X         -
clitcpka-intvl                            X          X         X         -
compression                               X          X         X         X
cookie                                    X          -         X         X
crt                                       -          X         X         -
declare capture                           -          X         X         -
default-server                            X          -         X         X
default_backend                           X          X         X         -
description                               -          X         X         X
disabled                                  X          X         X         X
dispatch                    (устарело)    -          -         X         X
email-alert from                          X          X         X         X
email-alert level                         X          X         X         X
email-alert mailers                       X          X         X         X
email-alert myhostname                    X          X         X         X
email-alert to                            X          X         X         X
enabled                                   X          X         X         X
errorfile                                 X          X         X         X
errorfiles                                X          X         X         X
errorloc                                  X          X         X         X
errorloc302                               X          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
errorloc303                               X          X         X         X
error-log-format                          X          X         X         -
external-check command                    X          -         X         X
external-check path                       X          -         X         X
force-persist                             -          -         X         X
force-be-switch                           -          X         X         -
filter                                    -          X         X         X
fullconn                                  X          -         X         X
guid                                      -          X         X         X
hash-balance-factor                       X          -         X         X
hash-preserve-affinity                    X          -         X         X
hash-type                                 X          -         X         X
http-after-response                       X (!)      X         X         X
http-check comment                        X          -         X         X
http-check connect                        X          -         X         X
http-check disable-on-404                 X          -         X         X
http-check expect                         X          -         X         X
http-check send                           X          -         X         X
http-check send-state                     X          -         X         X
http-check set-var                        X          -         X         X
http-check unset-var                      X          -         X         X
http-error                                X          X         X         X
http-request                              X (!)      X         X         X
http-response                             X (!)      X         X         X
http-reuse                                X          -         X         X
http-send-name-header                     X          -         X         X
id                                        -          X         X         X
ignore-persist                            -          -         X         X
load-server-state-from-file               X          -         X         X
log                                  (*)  X          X         X         X
log-format                                X          X         X         -
log-format-sd                             X          X         X         -
log-tag                                   X          X         X         X
log-steps                                 X          X         X         -
max-keep-alive-queue                      X          -         X         X
max-session-srv-conns                     X          X         X         -
maxconn                                   X          X         X         -
mode                                      X          X         X         X
monitor fail                              -          X         X         -
monitor-uri                               X          X         X         -
option abortonclose                  (*)  X          X         X         X
option allbackups                    (*)  X          -         X         X
option checkcache                    (*)  X          -         X         X
option clitcpka                      (*)  X          X         X         -
option contstats                     (*)  X          X         X         -
option disable-h2-upgrade            (*)  X          X         X         -
option dontlog-normal                (*)  X          X         X         -
option dontlognull                   (*)  X          X         X         -
-- keyword -------------------------- defaults - frontend - listen -- backend -
option external-check                     X          -         X         X
option forwardfor                         X          X         X         X
option forwarded                     (*)  X          -         X         X
option h1-case-adjust-bogus-client   (*)  X          X         X         -
option h1-case-adjust-bogus-server   (*)  X          -         X         X
option http-buffer-request           (*)  X          X         X         X
option http-drop-request-trailers    (*)  X          -         -         X
option http-drop-response-trailers   (*)  X          -         X         -
option http-ignore-probes            (*)  X          X         X         -
option http-keep-alive               (*)  X          X         X         X
option http-no-delay                 (*)  X          X         X         X
option http-pretend-keepalive        (*)  X          -         X         X
option http-restrict-req-hdr-names        X          X         X         X
option http-server-close             (*)  X          X         X         X
option http-use-proxy-header         (*)  X          X         X         -
option httpchk                            X          -         X         X
option httpclose                     (*)  X          X         X         X
option httplog                            X          X         X         -
option httpslog                           X          X         X         -
option idle-close-on-response        (*)  X          X         X         -
option independent-streams           (*)  X          X         X         X
option ldap-check                         X          -         X         X
option log-health-checks             (*)  X          -         X         X
option log-separate-errors           (*)  X          X         X         -
option logasap                       (*)  X          X         X         -
option mysql-check                        X          -         X         X
option nolinger                      (*)  X          X         X         X
option originalto                         X          X         X         X
option persist                       (*)  X          -         X         X
option pgsql-check                        X          -         X         X
option prefer-last-server            (*)  X          -         X         X
option redispatch                    (*)  X          -         X         X
option redis-check                        X          -         X         X
option smtpchk                            X          -         X         X
option socket-stats                  (*)  X          X         X         -
option splice-auto                   (*)  X          X         X         X
option splice-request                (*)  X          X         X         X
option splice-response               (*)  X          X         X         X
option spop-check                         X          -         X         X
option srvtcpka                      (*)  X          -         X         X
option ssl-hello-chk                      X          -         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
option tcp-check                          X          -         X         X
option tcp-smart-accept              (*)  X          X         X         -
option tcp-smart-connect             (*)  X          -         X         X
option tcpka                              X          X         X         X
option tcplog                             X          X         X         -
option transparent      (устарело)   (*)  X          -         X         X
option use-small-buffers             (*)  X          -         X         X
persist rdp-cookie                        X          -         X         X
quic-initial                              X (!)      X         X         -
rate-limit sessions                       X          X         X         -
redirect                                  -          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
retries                                   X          -         X         X
retry-on                                  X          -         X         X
server                                    -          -         X         X
server-state-file-name                    X          -         X         X
server-template                           -          -         X         X
source                                    X          -         X         X
srvtcpka-cnt                              X          -         X         X
srvtcpka-idle                             X          -         X         X
srvtcpka-intvl                            X          -         X         X
stats admin                               -          X         X         X
stats auth                                X          X         X         X
stats enable                              X          X         X         X
stats hide-version                        X          X         X         X
stats http-request                        -          X         X         X
stats realm                               X          X         X         X
stats refresh                             X          X         X         X
stats scope                               X          X         X         X
stats show-desc                           X          X         X         X
stats show-legends                        X          X         X         X
stats show-node                           X          X         X         X
stats show-version                        X          X         X         X
stats uri                                 X          X         X         X
-- keyword -------------------------- defaults - frontend - listen -- backend -
stick match                               -          -         X         X
stick on                                  -          -         X         X
stick store-request                       -          -         X         X
stick store-response                      -          -         X         X
stick-table                               -          X         X         X
tcp-check comment                         X          -         X         X
tcp-check connect                         X          -         X         X
tcp-check expect                          X          -         X         X
tcp-check send                            X          -         X         X
tcp-check send-lf                         X          -         X         X
tcp-check send-binary                     X          -         X         X
tcp-check send-binary-lf                  X          -         X         X
tcp-check set-var                         X          -         X         X
tcp-check unset-var                       X          -         X         X
tcp-request connection                    X (!)      X         X         -
tcp-request content                       X (!)      X         X         X
tcp-request inspect-delay                 X (!)      X         X         X
tcp-request session                       X (!)      X         X         -
tcp-response content                      X (!)      -         X         X
tcp-response inspect-delay                X (!)      -         X         X
timeout check                             X          -         X         X
timeout client                            X          X         X         -
timeout client-fin                        X          X         X         -
timeout client-hs                         X          X         X         -
timeout connect                           X          -         X         X
timeout http-keep-alive                   X          X         X         X
timeout http-request                      X          X         X         X
timeout queue                             X          -         X         X
timeout server                            X          -         X         X
timeout server-fin                        X          -         X         X
timeout tarpit                            X          X         X         X
timeout tunnel                            X          -         X         X
transparent                 (устарело)    X          -         X         X
unique-id-format                          X          X         X         X
unique-id-header                          X          X         X         -
use_backend                               -          X         X         -
use-fcgi-app                              -          -         X         X
use-server                                -          -         X         X
------------------------------------+----------+----------+---------+---------
 ключевое слово                       defaults   frontend   listen    backend

4.2. Алфавитный справочник ключевых слов

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

acl <aclname> <criterion> [flags] [operator] <value> ...

acl <aclname> <criterion> [flags] [operator] <value> ...

Объявить или дополнить список контроля доступа.

Можно использовать в следующих контекстах: tcp, http

Можно использовать в секциях: defaults | frontend | listen | backend да(!) | да | да | да

Эта директива доступна только в именованных секциях defaults, а не в анонимных. Списки контроля доступа, определённые в секции defaults, недоступны из других секций, использующих её.

Пример:

acl invalid_src  src          0.0.0.0/7 224.0.0.0/3
acl invalid_src  src_port     0:1023
acl local_dst    hdr(host) -i localhost

Об использовании ACL см. раздел 7 .

backlog <conns>

backlog <conns>

Сообщить системе ориентировочный желаемый размер очереди входящих соединений

Можно использовать в следующих контекстах: tcp, http

Можно использовать в секциях: defaults | frontend | listen | backend да | да | да | нет

Аргументы:

<conns>   — количество ожидающих соединений. В зависимости от операционной системы это может
          быть количество уже подтверждённых соединений, неподтверждённых соединений или
          соединений обоих типов.

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

Для всех слушателей, кроме QUIC, один из способов защиты от атак SYN flood — увеличить размер системной очереди SYN. В одних системах её размер настраивается системным параметром, в других вообще не поддаётся настройке, а в третьих система учитывает подсказки приложения, передаваемые при системном вызове listen(). По умолчанию HAProxy передаёт в listen() значение maxconn фронтенда. На системах, способных использовать это значение, иногда полезно задавать другое значение; для этого и предназначен параметр backlog.

В Linux 2.4 система игнорирует этот параметр. В Linux 2.6 он используется как подсказка: система принимает количество соединений не больше ближайшей большей степени двойки и в любом случае не превышает определённые ограничения (обычно 32768).

Для слушателей QUIC backlog задаёт общий предел как для максимального числа активных согласований соединений, так и для числа соединений, ожидающих принятия. Длительность согласования в основном зависит от сетевой задержки до удалённого узла, а второй этап зависит только от нагрузки на haproxy. Когда достигается любой из этих пределов, haproxy начинает отбрасывать входящие пакеты INITIAL, предотвращая выделение ресурсов под новые соединения до тех пор, пока избыток соединений не начнёт уменьшаться. Это может привести к незаметному для пользователя переходу браузеров на более раннюю версию HTTP и к использованию TCP.

См. также: “maxconn” и руководство по настройке целевой операционной системы.

balance <algorithm> [ <arguments> ]

balance <algorithm> [ <arguments> ]
balance url_param <param> [check_post]

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

Можно использовать в следующих контекстах: tcp, http, log

Можно использовать в секциях: defaults | frontend | listen | backend да | нет | да | да

Аргументы:

<algorithm> — алгоритм выбора сервера при балансировке нагрузки. Он применяется только при
            отсутствии информации о привязке сеанса или при повторном распределении соединения
            на другой сервер. <algorithm> может принимать одно из следующих значений:

  roundrobin  Серверы используются по очереди с учётом их весов. Этот алгоритм обеспечивает
              наиболее плавное и справедливое распределение, когда время обработки на серверах
              распределено равномерно. Алгоритм динамический: веса серверов можно изменять на
              лету, например для плавного запуска. По устройству алгоритма один бэкенд может
              содержать не более 4095 активных серверов. В некоторых крупных пулах серверов
              после очень кратковременной недоступности сервера иногда требуется несколько сотен
              запросов, прежде чем он снова будет включён в пул и начнёт получать трафик. Такое
              поведение нормально, хотя встречается крайне редко. Оно описано здесь, чтобы при
              его обнаружении не возникало беспокойства. Примечание: для бэкендов в режиме
              LOG веса игнорируются.

  static-rr   Серверы используются по очереди с учётом их весов. Алгоритм похож на roundrobin, но
              является статическим: изменение веса сервера на лету не оказывает эффекта. При
              этом в устройстве алгоритма нет ограничения на число серверов, а ставший доступным
              сервер всегда сразу возвращается в пул после полного пересчёта карты. Кроме того,
              алгоритм потребляет немного меньше ресурсов CPU (примерно -1%). Этот
              алгоритм нельзя использовать в режиме LOG.

  leastconn   Соединение получает сервер с наименьшим числом соединений. Внутри групп серверов с
              одинаковой нагрузкой применяется циклическое распределение, чтобы использовались
              все серверы. Этот алгоритм рекомендуется для очень длительных сеансов, например
              LDAP, SQL, TSE и т. д., но плохо подходит для протоколов с короткими
              сеансами, таких как HTTP. Алгоритм динамический: веса серверов можно изменять
              на лету, например для плавного запуска. Для уменьшения очередей он учитывает не
              только установленные соединения, но и соединения в очереди. Этот алгоритм нельзя
              использовать в режиме LOG.

  first       Соединение получает первый сервер, у которого есть свободный слот для соединения.
              Серверы выбираются в порядке возрастания числового идентификатора (см. параметр
              сервера "id"), который по умолчанию соответствует позиции сервера в пуле. Как
              только сервер достигает своего значения maxconn, используется следующий сервер.
              Применять этот алгоритм без задания maxconn не имеет смысла. Его цель — всегда
              задействовать минимальное число серверов, чтобы в часы низкой нагрузки лишние
              серверы можно было выключить. Алгоритм игнорирует вес сервера и приносит больше
              пользы для длительных сеансов, например RDP или IMAP, чем для HTTP, хотя
              может быть полезен и там. Для эффективного использования алгоритма рекомендуется
              регулярно проверять загрузку серверов с помощью облачного контроллера и выключать
              неиспользуемые серверы, а также регулярно проверять очередь бэкенда и включать
              дополнительные серверы при её росте. Другой вариант — сообщать серверам о нагрузке
              с помощью "http-check send-state". Этот алгоритм нельзя использовать в режиме LOG.

  hash        Принимает в качестве аргумента обычное выражение для извлечения образца. Выражение
              вычисляется для каждого запроса, а его результат хешируется согласно настройке
              hash-type. Результат хеширования делится на суммарный вес работающих серверов, чтобы
              определить сервер, который получит запрос. Этот алгоритм можно использовать вместо
              "source", "uri", "hdr()", "url_param()", "rdp-cookie", чтобы применить преобразователь,
              уточнить вычисление или, например, извлечь данные из локальных переменных. Если
              данные недоступны, применяется циклическое распределение. По умолчанию алгоритм
              статический: изменение веса сервера на лету не оказывает эффекта, но это можно
              изменить с помощью "hash-type". Алгоритм нельзя использовать для бэкендов в режиме
              LOG; вместо него следует использовать "log-hash".

  source      IP-адрес источника хешируется, затем результат делится на суммарный вес
              работающих серверов, чтобы определить сервер, который получит запрос. Это
              гарантирует, что один и тот же IP-адрес клиента всегда будет направляться на
              один и тот же сервер, пока ни один сервер не станет недоступным или не вернётся в
              работу. Если изменение числа работающих серверов меняет результат хеширования,
              многие клиенты будут направлены на другой сервер. Обычно этот алгоритм используют
              в режиме TCP, где невозможно вставить cookie. Его также можно использовать в
              Интернете для привязки сеанса по мере возможности у клиентов, которые не принимают
              сеансовые cookie. По умолчанию алгоритм статический: изменение веса сервера на
              лету не оказывает эффекта, но это можно изменить с помощью "hash-type". См. также
              параметр "hash" выше. Алгоритм нельзя использовать для бэкендов в режиме LOG.

  uri         Алгоритм хеширует либо левую часть URI (до знака вопроса), либо URI
              целиком (при наличии параметра "whole"), затем делит значение хеша на суммарный
              вес работающих серверов. Результат определяет сервер, который получит запрос. Это
              гарантирует, что один и тот же URI всегда будет направляться на один и тот же
              сервер, пока ни один сервер не вернётся в работу или не станет недоступным.
              Алгоритм используют с кеширующими и антивирусными прокси, чтобы обеспечить
              максимальную долю попаданий в кеш. Его можно использовать только в бэкенде
              HTTP. По умолчанию алгоритм статический: изменение веса сервера на лету не
              оказывает эффекта, но это можно изменить с помощью "hash-type".

              Алгоритм поддерживает два необязательных параметра "len" и "depth", после
              каждого из которых указывается положительное целое число. Они полезны, когда
              нагрузку нужно распределять по серверам только по началу URI. Параметр "len"
              задаёт число начальных символов URI, которые алгоритм должен учитывать при
              вычислении хеша. Значение "len", равное 1, редко имеет смысл, поскольку
              большинство URI начинаются с "/".

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

              Параметр "path-only" указывает, что ключ хеширования начинается с первого символа
              '/' в пути. Это позволяет игнорировать компонент authority абсолютных URI
              и гарантировать, что URI HTTP/1 и HTTP/2 дадут одинаковый
              хеш. См. также параметр "hash" выше.

  url_param   Параметр URL, указанный в аргументе, будет искаться в строке запроса каждого
              запроса HTTP GET.

              При использовании модификатора "check_post" указанный параметр ищется в теле запроса
              HTTP POST, если он не найден в строке запроса после знака вопроса ('?')
              в URL. Анализ тела сообщения начинается только после получения объявленного
              объёма данных или заполнения буфера запроса. В маловероятном случае использования
              кодирования chunked просматривается только первый блок. Если значение параметра
              разделено границей блоков, распределение по серверам может оказаться случайным,
              если оно вообще будет выполнено. Раньше это ключевое слово поддерживало
              необязательный параметр <max_wait>, который теперь игнорируется.

              Если за найденным параметром следуют знак равенства ('=') и значение, это
              значение хешируется, затем результат делится на суммарный вес работающих серверов.
              Результат определяет сервер, который получит запрос.

              Этот механизм отслеживает идентификаторы пользователей в запросах и гарантирует,
              что один и тот же ID пользователя всегда будет направляться на один и тот же
              сервер, пока ни один сервер не вернётся в работу или не станет недоступным. Если
              значение не найдено или отсутствует сам параметр, применяется алгоритм
              циклического распределения. Алгоритм можно использовать только в бэкенде HTTP.
              По умолчанию он статический: изменение веса сервера на лету не оказывает эффекта,
              но это можно изменить с помощью "hash-type". См. также параметр "hash" выше.

  hdr(<name>) Заголовок HTTP <name> будет искаться в каждом запросе HTTP. Как и в
              эквивалентной функции ACL 'hdr()', имя заголовка в скобках не чувствительно к
              регистру. Если заголовок отсутствует или не содержит значения, вместо него
              применяется алгоритм roundrobin.

              Необязательный параметр 'use_domain_only' позволяет ограничить хеширование основной частью
              домена для некоторых заголовков, например 'Host'. Так, для значения Host "haproxy.1wt.eu"
              будет учитываться только "1wt".

              По умолчанию этот алгоритм является статическим, что означает, что изменение веса
              сервера в режиме реального времени не окажет никакого эффекта, но это поведение
              можно изменить с помощью "hash-type". См. также опцию "hash" выше.

  random
  random(<draws>)
              В качестве ключа для функции консистентного хеширования используется случайное
              число. Это означает, что веса серверов учитываются, а динамические изменения весов
              и добавление новых серверов немедленно вступают в силу. Случайная балансировка
              нагрузки полезна в крупных пулах или при частом добавлении и удалении серверов:
              она позволяет избежать резких всплесков нагрузки на отдельные серверы, которые в
              этих условиях могут возникать при roundrobin или leastconn. Директива hash-balance-factor
              позволяет ещё больше повысить равномерность распределения нагрузки, особенно если
              время ответа серверов сильно различается. Аргумент <draws>, если он указан, должен
              быть целым числом не меньше единицы и задаёт число случайных выборок перед выбором
              наименее загруженного из этих серверов. Показано, что для существенного улучшения
              равномерности алгоритма достаточно выбирать наименее загруженный из двух серверов:
              это всегда исключает выбор самого загруженного сервера в пуле и устраняет
              смещение, вызванное неравномерным распределением в списке консистентного
              хеширования. Большие значения N исключают N-1 наиболее загруженных серверов
              ценой производительности. При очень больших значениях результат приближается к
              leastconn, но вычисляется гораздо медленнее. Кроме того, в крупных пулах при очень
              низкой нагрузке (или идеальном балансе) нагрузки сравниваемых серверов часто
              оказываются одинаковыми. Если они равны у всех выбранных серверов, сравнивается
              интенсивность запросов за последнюю секунду. Это позволяет равномернее
              распределять использование серверов во времени, как при roundrobin, и сглаживает
              неравномерность консистентного хеширования. Значение по умолчанию — 2;
              обычно оно обеспечивает очень хорошее распределение и производительность. Для
              крупных пулов с низкой нагрузкой (менее нескольких запросов в секунду на сервер)
              может быть полезно увеличить его до 3 или даже 4. Этот алгоритм также
              известен как алгоритм двух случайных выборов (Power of Two Random Choices) и
              описан здесь: http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf

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

  rdp-cookie
  rdp-cookie(<name>)
              В каждом входящем запросе TCP ищется и хешируется cookie RDP с именем
              <name> (или "mstshash", если имя не указано). Как и в эквивалентной функции ACL
              'req.rdp_cookie()', регистр имени не учитывается. Этот механизм полезен как режим привязки
              сеанса с ограниченными возможностями: он позволяет всегда направлять одного и того
              же пользователя (или один и тот же ID сеанса) на один и тот же сервер. Если
              cookie не найден, используется обычный алгоритм roundrobin.

              Для работы этого механизма фронтенд должен гарантировать, что cookie RDP уже
              присутствует в буфере запроса. Для этого необходимо использовать правило 'tcp-request content accept'
              совместно с ACL 'req.rdp_cookie_cnt'.

              По умолчанию этот алгоритм является статическим, что означает, что изменение веса
              сервера в режиме реального времени не окажет никакого эффекта, но это поведение
              можно изменить с помощью "hash-type". См. также опцию "hash" выше.

  log-hash    Принимает в качестве аргумента список преобразователей, разделённых запятыми. Эти
              преобразователи применяются последовательно к входному сообщению журнала,
              результат преобразования приводится к строке, затем хешируется в соответствии с
              настроенным hash-type. Полученный хеш используется для выбора сервера назначения
              среди серверов, объявленных в бэкенде журнала. Целью этого алгоритма является
              возможность извлечь ключ из конечного сообщения журнала с помощью строковых
              преобразователей, а затем благодаря хешу всегда направлять сообщения на один и тот
              же сервер. В настоящее время поддерживаются только хеши "map-based". Этот алгоритм
              доступен только для бэкендов в режиме LOG, для других режимов следует
              использовать "hash".

  sticky      Стремится максимально привязаться к одному и тому же серверу. Первый сервер в
              списке доступных серверов получает все сообщения журнала. Когда сервер переходит в
              состояние DOWN, следующий сервер в списке занимает его место. Когда ранее
              DOWN сервер снова становится UP, он добавляется в конец списка, чтобы
              привязанный сервер не менялся до тех пор, пока он не станет DOWN.

<arguments> — необязательный список аргументов, которые могут потребоваться некоторым алгоритмам. В
            настоящее время только "url_param", "uri" и "log-hash" поддерживают необязательный
            аргумент.

Алгоритм балансировки нагрузки бэкенда устанавливается в “random”, если не заданы ни другой алгоритм, ни режим, ни параметр. Для каждого бэкенда алгоритм можно задать только один раз.

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

Примеры TCP/HTTP:

balance roundrobin
balance url_param userid
balance url_param session_id check_post 64
balance hdr(User-Agent)
balance hdr(host)
balance hdr(Host) use_domain_only
balance hash req.cookie(clientid)
balance hash var(req.client_id)
balance hash req.hdr_ip(x-forwarded-for,-1),ipmask(24)

Примеры бэкендов LOG:

global
  log backend@mylog-rrb local0 # send all logs to mylog-rrb backend
  log backend@mylog-hash local0 # send all logs to mylog-hash backend

backend mylog-rrb
  mode log
  balance roundrobin

  server s1 udp@127.0.0.1:514 # will receive 50% of log messages
  server s2 udp@127.0.0.1:514

backend mylog-hash
  mode log

  # extract "METHOD URL PROTO" at the end of the log message,
  # and let haproxy hash it so that log messages generated from
  # similar requests get sent to the same syslog server:
  balance log-hash 'field(-2,\")'

  # server list here
  server s1 127.0.0.1:514
  #...

Примечание: при использовании расширения “check_post” с “url_param” необходимо учитывать следующие ограничения и особенности:

- Рассматриваются все запросы POST, поскольку невозможно определить,
  окажутся ли параметры в теле или сущности, которая может содержать
  двоичные данные. Поэтому может потребоваться другой способ, чтобы
  исключить из рассмотрения запросы POST, в теле которых нет параметров
  URL. (см. acl http_end)

- Значение `<max_wait>`, превышающее размер буфера запроса, не имеет
  смысла и бесполезно. Размер буфера задаётся при сборке и по умолчанию
  составляет 16 kB.

- Content-Encoding не поддерживается; поиск параметра, вероятно,
  завершится неудачей, и балансировка нагрузки вернётся к алгоритму
  циклического распределения (Round Robin).

- Expect: 100-continue не поддерживается; балансировка нагрузки
  вернётся к алгоритму циклического распределения (Round Robin).

- Transfer-Encoding (RFC7230 3.3.1) поддерживается только в первом
  фрагменте. Если полное значение параметра отсутствует в первом
  фрагменте, выбор сервера не определён (фактически он определяется
  тем, какая малая часть значения оказалась в первом фрагменте).

- Эта возможность не поддерживает формирование ответов 100, 411 или 501.

- В некоторых случаях указание "check_post" МОЖЕТ привести к попытке
  просканировать всё содержимое тела сообщения. Обычно сканирование
  прекращается при обнаружении линейных пробельных или управляющих
  символов, указывающих на конец возможного списка параметров URL.
  Вероятно, для тел сообщений типа SGML это не представляет проблемы.

См. также: “dispatch”, “cookie”, “transparent”, “hash-type”.

be-unpublished

be-unpublished

Указывает бэкенду начинать работу в неопубликованном состоянии.

Можно использовать в следующих контекстах: tcp, http, log

Можно использовать в секциях: defaults | frontend | listen | backend нет | нет | да | да

По сути, любые правила use_backend и default_backend из другого прокси, ссылающиеся на текущий прокси, игнорируются, и оцениваются следующие правила переключения содержимого. Это поведение можно обойти с помощью правила “force-be-switch”.

Это состояние похоже на отключённое, но имеет некоторые отличия. Во-первых, неопубликованный бэкенд по-прежнему полностью инициализируется, в том числе выполняются проверки работоспособности серверов, которые остаются активными. Наконец, бэкенд можно опубликовать командой “publish backend” через CLI. См. руководство по управлению.

См. также: “force-be-switch”

bind [<address>]:<port_range> [, ...] [param*]

bind [<address>]:<port_range> [, ...] [param*]
bind /<path> [, ...] [param*]

Определяет во фронтенде один или несколько адресов и/или портов для прослушивания.

Можно использовать в следующих контекстах: tcp, http

Можно использовать в секциях: defaults | frontend | listen | backend нет | да | да | нет

Аргументы:

<address>     — необязательный параметр: имя хоста, адрес IPv4, адрес IPv6 или '*'. Он задаёт
              адрес, который будет прослушивать фронтенд. Если параметр не задан, прослушиваются
              все адреса IPv4 системы. То же относится к '*' и специальному адресу системы
              "0.0.0.0". Эквивалент для IPv6 — '::'. Для UDP привязка к нескольким адресам
              требует специальных возможностей операционной системы (OS), чтобы в ответе
              использовались правильные сетевой интерфейс и исходный адрес. Иными словами,
              слушатели QUIC следует привязывать к нескольким адресам только при работе в
              достаточно современной системе.

              Перед адресом можно указать префикс семейства адресов, чтобы принудительно выбрать
                  семейство независимо от формата адреса. Это может быть полезно для задания
                  пути к сокету unix без слэша ('/'). Поддерживаются следующие префиксы:
                - 'ipv4@'  -> адрес всегда IPv4
                - 'ipv6@'  -> адрес всегда IPv6
                - 'udp@'   -> адрес разрешается как IPv4 или IPv6, используется протокол
                  UDP. Сейчас такие слушатели поддерживаются только в секциях log-forward.
                - 'udp4@'  -> адрес всегда IPv4, используется протокол UDP. Сейчас
                  такие слушатели поддерживаются только в секциях log-forward.
                - 'udp6@'  -> адрес всегда IPv6, используется протокол UDP. Сейчас
                  такие слушатели поддерживаются только в секциях log-forward.
                - 'unix@'  -> адрес — путь к локальному сокету unix
                - 'abns@'  -> адрес находится в абстрактном пространстве имён (только
                  Linux).
                - 'abnsz@'  -> адрес находится в абстрактном пространстве имён (только
                  Linux), но явно заканчивается нулевым символом. Это означает, что дополнение
                  до полной длины sun_path символами \0 не используется. Это полезно для
                  взаимодействия с программами, которые не реализуют применяемую в haproxy
                  стандартную логику именования abns.
                - 'fd@<n>' -> использовать файловый дескриптор <n>, унаследованный от
                  родительского процесса. Дескриптор fd должен быть привязан; он может как
                  находиться в состоянии прослушивания, так и ещё не прослушивать соединения.
                - 'sockpair@<n>'-> аналогично fd@, но необходимо использовать дескриптор fd
                  подключённого сокета unix или пары сокетов socketpair. bind ожидает получения
                  FD через сокет unix и использует его как FD, полученный от accept().
                  Следует применять с осторожностью.
                - 'quic4@' -> адрес разрешается как IPv4, используется протокол UDP. Для
                  наилучшей производительности при большом объёме трафика следует сохранить
                  настройку "tune.quic.fe.sock-per-conn default-on". В противном случае соединения QUIC будут
                  мультиплексироваться через сокет слушателя. Другой вариант — продублировать
                  экземпляры слушателя QUIC в нескольких потоках, например с помощью
                  ключевого слова "shards", чтобы хотя бы уменьшить конкуренцию между потоками.
                - 'quic6@' -> адрес разрешается как IPv6, используется протокол UDP.
                  Примечание о производительности QUIC поверх IPv4 также применимо.
                - 'rhttp@' [ ЭКСПЕРИМЕНТАЛЬНО ] -> используется для обратного HTTP. Адрес
                  должен указывать на сервер в формате '<backend>/<server>'. Этот сервер будет использоваться
                  для создания соединений с удалённым адресом. Слушатель будет пытаться
                  поддерживать "nbconn" соединений. Эта экспериментальная возможность требует
                  указать "expose-experimental-directives" в строке перед данным bind.

              В параметре адреса можно ссылаться на переменные окружения; см. раздел 2.3 о
              переменных окружения.

<port_range>  — один порт TCP или диапазон портов, на которых прокси принимает соединения для
              указанного выше адреса IP. Для слушателей TCP порт обязателен. В случае
              адреса IPv6 порт всегда задаётся числом после последнего двоеточия (':').
              Диапазон можно задать следующим образом:
               - номером порта (например, '80')
               - диапазоном портов через дефис с явно указанными нижней и верхней границами
                 (например, '2000-2100'); обе границы входят в диапазон.

              С диапазонами портов необходимо обращаться особенно осторожно: каждая пара <address:port>
              занимает один сокет (= файловый дескриптор), поэтому даже простой диапазон может
              занять много дескрипторов и привести к исчерпанию сокетов. Кроме того, каждая пара
              <address:port> должна использоваться только один раз среди всех экземпляров, работающих в
              одной системе. Для привязки к портам ниже 1024 обычно требуются особые
              привилегии при запуске программы; они не зависят от параметра 'uid'.

<path>        — путь к сокету UNIX, начинающийся со слэша ('/'). Это альтернатива порту
              прослушивания TCP. HAProxy будет принимать соединения UNIX через сокет,
              расположенный по этому пути. Путь должен начинаться со слэша и по умолчанию
              является абсолютным. Он может быть задан относительно префикса, определённого
              директивой "unix-bind" в секции global. Общая длина префикса и следующего за ним пути
              к сокету не должна превышать системных ограничений для сокетов UNIX, которые
              обычно составляют 107 символов.

<param*>      — список параметров, общих для всех сокетов, объявленных в одной строке. Эти
              многочисленные параметры зависят от операционной системы (OS) и параметров
              сборки; им посвящён отдельный раздел целиком. Подробности приведены в разделе
              5.

Можно указать разделённый запятыми список пар address:port. Фронтенд будет прослушивать все указанные адреса. Фиксированного ограничения на число адресов и портов, которые может прослушивать фронтенд, нет; число директив “bind” во фронтенде также не ограничено.

Пример:

listen http_proxy
    bind :80,:443
    bind 10.0.0.1:10080,10.0.0.1:10443
    bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy

listen http_https_proxy
    bind :80
    bind :443 ssl crt /etc/haproxy/site.pem

listen http_https_proxy_explicit
    bind ipv6@:80
    bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
    bind unix@ssl-frontend.sock user root mode 600 accept-proxy

listen external_bind_app1
    bind "fd@${FD_APP1}"

listen h3_quic_proxy
    bind quic4@10.0.0.1:8888 ssl crt /etc/mycrt

Примечание: для сокетов “abns” HAProxy в абстрактном пространстве имён Linux длина адреса равна полной длине sun_path. Некоторые другие программы, например socat, по умолчанию используют только длину строки. Чтобы определение абстрактного сокета в socat было совместимо с сокетами HAProxy, к нему нужно добавить параметр “,unix-tightsocklen=0”; другой вариант — использовать семейство сокетов “abnsz” HAProxy.

См. также: “source”, “option forwardfor”, “unix-bind” и документацию по протоколу PROXY, а также раздел 5 о параметрах bind.

capture cookie <name> len <length>

capture cookie <name> len <length>

Захватывает и записывает в журнал cookie из запроса и ответа.

Можно использовать в следующих контекстах: http

Можно использовать в секциях: defaults | frontend | listen | backend нет | да | да | нет

Аргументы:

<name>    — начало имени cookie, который нужно захватить. Для точного совпадения имени
          достаточно добавить в его конец знак равенства ('='). В журнал попадёт полное имя;
          это полезно для серверов приложений, которые изменяют и имя, и значение cookie
          (например, ASPSESSIONXXX).

<length>  — максимальное число символов, записываемых в журнал, включая имя cookie, знак
          равенства и значение в стандартной форме "name=value". Если длина строки превышает <length>,
          строка обрезается справа.

Захватывается только первый cookie. Отслеживаются как заголовки запроса “cookie”, так и заголовки ответа “set-cookie”. Это особенно полезно для выявления ошибок приложений, приводящих к смешиванию или краже сеансов между пользователями, поскольку обычно cookie пользователя могут меняться только на странице входа.

Если клиент не передал cookie, в соответствующем столбце журнала указывается “-”. Если в результате запроса сервер не назначает cookie, в столбце ответа указывается “-”.

Захват выполняется только во фронтенде: формат журнала для одного фронтенда должен оставаться одинаковым независимо от бэкендов. В дальнейшем это может измениться. Во фронтенде допускается только одна директива “capture cookie”. Максимальная длина захвата задаётся глобальным параметром “tune.http.cookielen” и по умолчанию составляет 63 символа. В секции “defaults” задавать захват нельзя.

Пример:

capture cookie ASPSESSION len 32

См. также: “capture request header”, “capture response header”, а также раздел 8 о ведении журнала.

capture request header <name> len <length>

capture request header <name> len <length>

Захватывает и записывает в журнал последнее вхождение указанного заголовка запроса.

Можно использовать в следующих контекстах: http

Можно использовать в секциях: defaults | frontend | listen | backend нет | да | да | нет

Аргументы:

<name>    — имя захватываемого заголовка. Регистр имён заголовков не учитывается, однако их
          принято писать так же, как в запросах, с заглавной первой буквой каждого слова. В
          журнал выводится только значение, без имени заголовка, но его позиция в журнале
          сохраняется.

<length>  — максимальное число символов, извлекаемых из значения и записываемых в журнал. Если
          длина строки превышает <length>, строка обрезается справа.

Захватывается полное значение последнего вхождения заголовка. Оно добавляется в журнал в фигурных скобках (’{}’). При захвате нескольких заголовков их значения разделяются вертикальной чертой (’|’) и выводятся в порядке объявления в конфигурации. Отсутствующие заголовки записываются как пустые строки. Обычно захватывают поле “Host” при виртуальном хостинге, “Content-length” при поддержке загрузки данных, “User-agent” для быстрого различения настоящих пользователей и роботов и “X-Forwarded-For” при работе через прокси, чтобы определить источник запроса.

При захвате заголовков, например “User-agent”, в журнал могут попадать пробелы, что усложняет его анализ. Поэтому следует осторожно выбирать записываемые данные, если известно, что используемый разборщик журналов не умеет определять границы по фигурным скобкам.

Число захватываемых заголовков запроса и их длина не ограничены, однако целесообразно поддерживать небольшие значения обоих параметров, чтобы ограничить расход памяти на поток. Для единого формата журнала в пределах одного фронтенда захват заголовков можно объявлять только во фронтенде. В секции “defaults” задавать захват нельзя.

Пример:

capture request header Host len 15
capture request header X-Forwarded-For len 15
capture request header Referer len 15

См. также: “capture cookie”, “capture response header”, а также раздел 8 о ведении журнала.

capture response header <name> len <length>

capture response header <name> len <length>

Захватывает и записывает в журнал последнее вхождение указанного заголовка ответа.

Можно использовать в следующих контекстах: http

Можно использовать в секциях: defaults | frontend | listen | backend нет | да | да | нет

Аргументы:

<name>    — имя захватываемого заголовка. Регистр имён заголовков не учитывается, однако их
          принято писать так же, как в ответе, с заглавной первой буквой каждого слова. В журнал
          выводится только значение, без имени заголовка, но его позиция в журнале сохраняется.

<length>  — максимальное число символов, извлекаемых из значения и записываемых в журнал. Если
          длина строки превышает <length>, строка обрезается справа.

Захватывается полное значение последнего вхождения заголовка. Результат добавляется в журнал в фигурных скобках (’{}’) после захваченных заголовков запроса. При захвате нескольких заголовков их значения разделяются вертикальной чертой (’|’) и выводятся в порядке объявления в конфигурации. Отсутствующие заголовки записываются как пустые строки. Обычно захватывают заголовок “Content-length”, указывающий ожидаемое число байтов в ответе, и “Location” для отслеживания перенаправлений.

Число захватываемых заголовков ответа и их длина не ограничены, однако целесообразно поддерживать небольшие значения обоих параметров, чтобы ограничить расход памяти на поток. Для единого формата журнала в пределах одного фронтенда захват заголовков можно объявлять только во фронтенде. В секции “defaults” задавать захват нельзя.

Пример:

capture response header Content-length len 9
capture response header Location len 15

См. также: “capture cookie”, “capture request header”, а также раздел 8 о ведении журнала.

clitcpka-cnt <count>

clitcpka-cnt <count>

Задаёт максимальное число проверочных пакетов для поддержания соединения, которые TCP должен отправить перед закрытием соединения на стороне клиента.

Можно использовать в следующих контекстах: tcp, http, log

Можно использовать в секциях: defaults | frontend | listen | backend да | да | да | нет

Аргументы:

<count>   — максимальное число проверочных пакетов для поддержания соединения.

Это ключевое слово соответствует параметру сокета TCP_KEEPCNT. Если оно не указано, используется общесистемный параметр TCP (tcp_keepalive_probes). Доступность этой настройки зависит от операционной системы. Известно, что она работает в Linux.

См. также: “option clitcpka”, “clitcpka-idle”, “clitcpka-intvl”.

clitcpka-idle <timeout>

clitcpka-idle <timeout>

Задаёт время простоя соединения, после которого TCP начинает отправлять проверочные пакеты для поддержания соединения, если отправка пакетов TCP для поддержания соединения на стороне клиента включена.

Можно использовать в следующих контекстах: tcp, http

Можно использовать в секциях: defaults | frontend | listen | backend да | да | да | нет

Аргументы:

<timeout> — время простоя соединения до начала отправки проверочных пакетов TCP для
          поддержания соединения. По умолчанию задаётся в секундах, но можно использовать любую
          другую единицу, добавив её обозначение после числа, как описано в начале документа.

Это ключевое слово соответствует параметру сокета TCP_KEEPIDLE. Если оно не указано, используется общесистемный параметр TCP (tcp_keepalive_time). Доступность этой настройки зависит от операционной системы. Известно, что она работает в Linux.

См. также: “option clitcpka”, “clitcpka-cnt”, “clitcpka-intvl”.

clitcpka-intvl <timeout>

clitcpka-intvl <timeout>

Задаёт интервал между отдельными проверочными пакетами для поддержания соединения на стороне клиента.

Можно использовать в следующих контекстах: tcp, http

Можно использовать в секциях: defaults | frontend | listen | backend да | да | да | нет

Аргументы:

<timeout> — интервал между отдельными проверочными пакетами для поддержания соединения. По
          умолчанию задаётся в секундах, но можно использовать любую другую единицу, добавив её
          обозначение после числа, как описано в начале документа.

Это ключевое слово соответствует параметру сокета TCP_KEEPINTVL. Если оно не указано, используется общесистемный параметр TCP (tcp_keepalive_intvl). Доступность этой настройки зависит от операционной системы. Известно, что она работает в Linux.

См. также: “option clitcpka”, “clitcpka-cnt”, “clitcpka-idle”.

compression algo <algorithm> ...

compression algo <algorithm> ...
compression algo-req <algorithm>
compression algo-res <algorithm>
compression type <mime type> ...

Включает сжатие HTTP.

Можно использовать в следующих контекстах: http

Можно использовать в секциях: defaults | frontend | listen | backend да | да | да | да

Аргументы:

algo     — за ним следует список поддерживаемых алгоритмов сжатия ответов (устаревшее ключевое
         слово).
algo-req — за ним следует алгоритм сжатия запроса (указывается только один).
algo-res — за ним следует список поддерживаемых алгоритмов сжатия ответов.
type     — за ним следует список типов MIME, для которых сжимаются ответы (устаревшее
         ключевое слово).
type-req — за ним следует список типов MIME, для которых сжимаются запросы.
type-res — за ним следует список типов MIME, для которых сжимаются ответы.

В настоящее время поддерживаются следующие алгоритмы:

identity     — в основном предназначен для отладки; был полезен при разработке функции сжатия.
             Этот алгоритм не изменяет данные.

gzip         — применяет сжатие gzip. Этот параметр доступен только в том случае, если при
             сборке была включена поддержка zlib или libslz.

deflate      — аналогичен "gzip", но использует алгоритм deflate и формат zlib. Поддержка этого
             алгоритма во многих браузерах неоднозначна, а в новых браузерах полностью
             отсутствует. Настоятельно рекомендуется не использовать его ни для чего, кроме
             экспериментов. Этот параметр доступен только в том случае, если при сборке была
             включена поддержка zlib или libslz.

raw-deflate  аналог "deflate" без оболочки zlib, используемый как альтернатива, когда браузер
             запрашивает "deflate". Его понимают все основные браузеры; несмотря на нарушение
             стандартов, известно, что он работает лучше "deflate", по крайней мере в MSIE и
             некоторых версиях Safari. Не следует использовать его совместно с "deflate": нужно
             выбрать один из этих алгоритмов, поскольку оба соответствуют одному токену
             Accept-Encoding. Эта настройка доступна только в сборках с поддержкой zlib или
             libslz.

Сжатие включается в зависимости от заголовка запроса Accept-Encoding. При identity этот заголовок не учитывается. Если серверы бэкенда поддерживают сжатие HTTP, эти директивы не оказывают действия: HAProxy обнаруживает сжатый ответ и не сжимает его повторно. Если серверы бэкенда не поддерживают сжатие HTTP, а запрос содержит заголовок Accept-Encoding, HAProxy сжимает соответствующий ответ.

Сжатие отключается, когда: * запрос не объявляет поддерживаемый алгоритм сжатия в заголовке “Accept-Encoding” * ответ использует версию ниже HTTP/1.1 * код состояния HTTP не равен 200, 201, 202 или 203 * ответ не содержит ни заголовка “Content-Length”, ни заголовка “Transfer-Encoding” с последним значением “chunked” * ответ содержит заголовок “Content-Type”, первое значение которого начинается с “multipart” * ответ содержит значение “no-transform” в заголовке “Cache-control” * User-Agent соответствует “Mozilla/4”, кроме MSIE 6 с XP SP2 и MSIE 7 или более поздних версий * ответ содержит заголовок “Content-Encoding”, указывающий, что ответ уже сжат (см. compression offload) * ответ содержит некорректный заголовок “ETag” или несколько заголовков ETag * размер полезной нагрузки меньше минимального (см. compression minsize-res)

Примечание: механизм сжатия не добавляет заголовок Warning.

Примеры:

compression algo gzip
compression type text/html text/plain

См. также: “compression offload”, “compression direction”, “compression minsize-req” и “compression minsize-res”

compression minsize-req <size>

compression minsize-req <size>
compression minsize-res <size>

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

Можно использовать в следующих контекстах: http

Можно использовать в секциях: defaults | frontend | listen | backend да | да | да | да

Полезная нагрузка меньше этого размера не сжимается, чтобы не тратить ресурсы CPU на данные, для которых сжатие не даёт существенного выигрыша. “minsize-req” применяется к запросам, а “minsize-res” — к ответам. Значение по умолчанию — 0.

compression offload

compression offload

Задаёт для HAProxy роль узла, полностью принимающего на себя сжатие.

Можно использовать в следующих контекстах: http

Можно использовать в секциях: defaults | frontend | listen | backend нет | да | да | да

Параметр “offload” заставляет HAProxy удалять заголовок Accept-Encoding, чтобы серверы бэкенда не сжимали ответы. Настоятельно рекомендуется этого не делать: вся работа по сжатию сосредоточится в одной точке, где находится HAProxy. Однако в некоторых схемах развёртывания HAProxy может находиться перед шлюзом с ошибочной реализацией сжатия HTTP, которую нельзя отключить. Тогда HAProxy может предотвратить отправку шлюзом некорректной полезной нагрузки. Простое удаление заголовка в конфигурации здесь не помогает: оно выполняется до разбора заголовка и лишает HAProxy возможности сжимать данные. В таких случаях следует использовать параметр “offload”.

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

См. также: “compression type”, “compression algo”, “compression direction”

compression direction <direction> (deprecated)

compression direction <direction> (deprecated)

Позволяет haproxy сжимать запросы и ответы. Допустимые значения: “request” — сжимать только запросы, “response” — только ответы, “both” — и запросы, и ответы. Значение по умолчанию — “response”.

Эта директива имеет значение только при включённом прежнем “filter compression”: с явными фильтрами comp-req и comp-res указание compression direction избыточно.

Можно использовать в следующих контекстах: http

См. также: “compression type”, “compression algo”, “compression offload”

cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]

cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
              [ postonly ] [ preserve ] [ httponly ] [ secure ]
              [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
              [ dynamic ] [ attr <value> ]*

Включает в бэкенде привязку сеанса на основе cookie.

Можно использовать в следующих контекстах: http

Можно использовать в секциях: defaults | frontend | listen | backend да | нет | да | да

Аргументы:

<name>    — имя cookie, который отслеживается, изменяется или вставляется для привязки сеанса.
          Этот cookie отправляется клиенту в заголовке "Set-Cookie" ответа и возвращается клиентом в
          заголовке "Cookie" всех запросов. Следует особенно внимательно выбирать имя, чтобы оно
          не конфликтовало с возможными cookie приложения. Если одни и те же клиенты могут
          использовать одни и те же бэкенды (например, HTTP/HTTPS), следует задавать разные
          имена cookie для всех бэкендов, если привязка между ними не нужна.

rewrite   Это ключевое слово указывает, что cookie предоставляет сервер, а HAProxy должен
          изменить его значение, поместив туда идентификатор сервера. Режим удобен, когда
          обработка сложных сочетаний заголовков "Set-cookie" и "Cache-control" возложена на приложение.
          Тогда приложение само решает, следует ли отправлять cookie привязки. Поскольку
          необходимо отслеживать все ответы, этот режим не работает в режиме туннеля HTTP.
          Если поведение приложения не отличается чрезмерной сложностью и/или ошибками, для
          новых развёртываний рекомендуется не начинать с этого режима. Это ключевое слово
          несовместимо с "insert" и "prefix".

insert    Это ключевое слово указывает, что HAProxy должен вставлять cookie привязки в ответы
          сервера, если у клиента ещё нет

          cookie, который позволил бы ему обращаться к этому серверу. Без параметра "preserve"
          cookie с таким же именем, отправленный сервером, удаляется до обработки. Поэтому этот
          режим позволяет обновлять существующие конфигурации, работающие в режиме "rewrite".
          Cookie будет только сеансовым и не будет сохраняться на диске клиента. По умолчанию
          сервер видит cookie, отправленные клиентом, если не добавлен параметр "indirect". Из-за
          влияния кеширования обычно целесообразно добавлять ключевые слова "nocache" или "postonly"
          (см. ниже). Ключевое слово "insert" несовместимо с "rewrite" и "prefix".

prefix    Это ключевое слово указывает, что вместо отдельного cookie привязки дополняется
          существующий cookie. Это может понадобиться в средах, где клиент поддерживает лишь
          один cookie, уже необходимый приложению. Тогда при каждом задании сервером cookie с
          именем <name> к его началу добавляются идентификатор сервера и разделитель. Префикс
          удаляется из всех клиентских запросов, чтобы сервер получал тот cookie, который он
          отправил. Поскольку изменяться могут все запросы и ответы, этот режим не работает в
          режиме туннеля. Ключевое слово "prefix" несовместимо с "rewrite" и "insert". Примечание:
          настоятельно рекомендуется не сочетать "indirect" с "prefix", иначе обновления cookie
          сервера не будут передаваться клиентам.

indirect  При этом параметре cookie не отправляется клиенту, у которого уже есть действительный
          cookie для сервера, обработавшего запрос. Если сервер сам задаёт такой cookie, он
          удаляется, кроме случаев, когда также указан "preserve". В режиме "insert" cookie
          дополнительно удаляются из запросов, передаваемых серверу, поэтому механизм привязки
          полностью прозрачен для приложения. Примечание: настоятельно рекомендуется не сочетать
          "indirect" с "prefix", иначе обновления cookie сервера не будут передаваться клиентам.

nocache   Этот параметр рекомендуется сочетать с режимом insert, если между клиентом и HAProxy
          находится кеш: кешируемый ответ помечается как некешируемый, если нужно вставить
          cookie. Это важно: если cookie привязки добавляются, например, в кешируемую главную
          страницу, все клиенты будут получать её из внешнего кеша с одним и тем же cookie
          привязки, и один сервер получит значительно больше трафика, чем остальные. См. также
          параметры "insert" и "postonly".

postonly  Этот параметр обеспечивает вставку cookie только в ответы на запросы POST. Это
          альтернатива "nocache": ответы POST не кешируются, поэтому cookie привязки никогда не
          попадёт в кеш. Большинству сайтов привязка не нужна до первого POST, обычно запроса
          входа в систему, поэтому это очень эффективный способ оптимизировать кеширование без
          риска сохранить cookie привязки в кеше. См. также параметры "insert" и "nocache".

preserve  Этот параметр можно использовать только с "insert" и/или "indirect". Он позволяет серверу
          самому отправлять cookie привязки. Тогда HAProxy оставляет найденный в ответе cookie
          без изменений. Это удобно, например, для прекращения привязки после запроса выхода из
          системы: серверу достаточно отправить cookie с недопустимым значением (например,
          пустым) или датой в прошлом. Вместе с параметром проверки "disable-on-404" этот механизм
          позволяет полностью плавно завершить обслуживание: после выхода из системы
          пользователи гарантированно покинут сервер.

httponly  Этот параметр указывает HAProxy добавлять атрибут "HttpOnly" при вставке cookie, чтобы
          пользовательский агент не передавал cookie компонентам, не использующим HTTP.
          Подробнее об этом атрибуте см. RFC6265.

secure    Этот параметр указывает HAProxy добавлять атрибут "Secure" при вставке cookie, чтобы
          пользовательский агент никогда не отправлял этот cookie по незащищённым каналам.
          Cookie с этим флагом передаётся только по соединениям SSL/TLS. Подробнее об
          этом атрибуте см. RFC6265.

domain    Этот параметр задаёт домен вставляемого cookie. Он требует ровно один параметр —
          действительное имя домена. Если домен начинается с точки, браузеру разрешено
          использовать cookie для любого хоста, имя которого оканчивается этим доменом. Параметр
          можно повторять, указывая несколько доменов. В некоторых браузерах число доменов
          ограничено небольшим значением, что нужно учитывать. Например, передача 10
          доменов в MSIE 6 или Firefox 2 работает ожидаемым образом.

maxidle   Этот параметр позволяет игнорировать вставленные cookie после определённого времени
          бездействия. Он работает только с cookie режима insert. При отправке cookie клиенту
          также передаётся дата его отправки. При последующих предъявлениях cookie он
          игнорируется, если его возраст превышает заданный параметром интервал в секундах.
          Иначе при отправке ответа клиенту cookie при необходимости обновляется. Это особенно
          полезно, чтобы пользователи, никогда не закрывающие браузер, не оставались слишком
          долго на одном сервере, например после изменения размера группы серверов. Если
          параметр задан, а у cookie нет даты, он всегда принимается, но обновляется в ответе;
          это сохраняет администраторам возможность доступа к своим сайтам. Cookie с датой более
          чем на 24 часа в будущем игнорируются. Такой подход позволяет исправлять проблемы
          часового пояса, не рискуя отключить пользователей от сайта.

maxlife   Этот параметр позволяет игнорировать вставленные cookie по истечении определённого
          срока жизни независимо от их использования. Он работает только с cookie режима insert.
          При первой отправке cookie клиенту также передаётся дата его отправки. При последующих
          предъявлениях cookie он игнорируется, если его возраст превышает заданный параметром
          интервал в секундах. Cookie запроса без даты принимается, и для него задаётся дата.
          Cookie с датой более чем на 24 часа в будущем игнорируются; это позволяет
          исправлять проблемы часового пояса, не рискуя отключить пользователей от сайта. В
          отличие от maxidle, значение не обновляется: учитывается только дата первого
          посещения. maxidle и maxlife можно использовать одновременно. Это особенно полезно,
          чтобы пользователи, никогда не закрывающие браузер, не оставались слишком долго на
          одном сервере, например после изменения размера группы серверов. Этот метод действует
          строже maxidle: по истечении фиксированного интервала он принудительно
          перераспределяет запросы.

dynamic   Включает динамические cookie. Для каждого сервера динамически создаётся сеансовый
          cookie на основе IP и порта сервера и секретного ключа из директивы бэкенда
          "dynamic-cookie-key". Cookie создаётся заново при каждом изменении адреса IP и формируется
          только для IPv4/IPv6.

attr      Этот параметр указывает HAProxy добавлять дополнительный атрибут при вставке cookie.
          Значение атрибута может содержать любые символы, кроме управляющих и ";". Параметр
          можно повторять.

У каждого бэкенда HTTP может быть только один cookie привязки; его можно объявить в секции defaults. Значением cookie будет значение, указанное после ключевого слова “cookie” в директиве “server”. Если для сервера cookie не объявлен, он не задаётся.

Примеры:

cookie JSESSIONID prefix
cookie SRV insert indirect nocache
cookie SRV insert postonly indirect
cookie SRV insert indirect nocache maxidle 30m maxlife 8h

См. также: “balance source”, “capture cookie”, “server” и “ignore-persist”.

declare capture [ request | response ] len <length>

declare capture [ request | response ] len <length>

Объявляет слот захвата.

Можно использовать в следующих контекстах: tcp, http

Можно использовать в секциях: defaults | frontend | listen | backend нет | да | да | нет

Аргументы:

<length> — это максимально допустимая длина захвата.

Объявление доступно только в секциях frontend и listen, но зарезервированный слот можно использовать в бэкендах. Ключевое слово “request” выделяет слот захвата для запроса, а “response” — для ответа.

См. также: “capture-req”, “capture-res” (преобразователи образцов), “capture.req.hdr”, “capture.res.hdr” (извлечения образцов), “http-request capture” и “http-response capture”.