5. Параметры bind и server

Ключевые слова “bind”, “server” и “default-server” поддерживают ряд настроек, зависящих от параметров сборки и системы, в которой собран HAProxy. Обычно каждая настройка состоит из одного слова, иногда со значением, и записывается в той же строке “bind” или “server”. Все эти параметры описаны в этом разделе.

5.1. Параметры bind

Ключевое слово “bind” поддерживает ряд настроек, которые передаются аргументами в той же строке. Их порядок не имеет значения, если они указаны после адреса привязки. Все параметры необязательны. Некоторые состоят из одного слова (логические параметры), другие требуют значения. В последнем случае значение должно следовать непосредственно за именем настройки.

Ниже перечислены поддерживаемые настройки.

accept-netscaler-cip <magic number>

accept-netscaler-cip <magic number>

Требует использования протокола NetScaler Client IP insertion для любого соединения, принятого любым сокетом TCP, объявленным в той же строке. Протокол NetScaler Client IP insertion задаёт адреса уровня 3/4 входящего соединения, которые используются везде, где требуется адрес, за единственным исключением правил “tcp-request connection”: они видят только реальный адрес соединения. В журналах отражаются адреса, указанные в протоколе, если только он не нарушен; при нарушении используется реальный адрес. Это ключевое слово совместно с поддержкой внешних компонентов может эффективно и надёжно заменять механизм X-Forwarded-For, который не всегда надёжен и даже не всегда применим. Для более точного определения клиентов, которым разрешено использовать протокол, см. также “tcp-request connection expect-netscaler-cip”.

accept-proxy

accept-proxy

Требует использования протокола PROXY для любого соединения, принятого любым сокетом, объявленным в той же строке. Версии 1 и 2 протокола PROXY поддерживаются и корректно определяются. Протокол PROXY задаёт адреса уровня 3/4 входящего соединения, которые используются везде, где требуется адрес, за единственным исключением правил “tcp-request connection”: они видят только реальный адрес соединения. В журналах отражаются адреса, указанные в протоколе, если только он не нарушен; при нарушении используется реальный адрес. Эта директива совместно с поддержкой внешних компонентов может эффективно и надёжно заменять механизм X-Forwarded-For, который не всегда надёжен и даже не всегда применим. Для более точного определения клиентов, которым разрешено использовать протокол, см. также “tcp-request connection expect-proxy”.

allow-0rtt

allow-0rtt

Разрешает приём ранних данных при использовании TLSv1.3. По соображениям безопасности эта возможность по умолчанию отключена. Она уязвима к атакам повторного воспроизведения, поэтому её следует разрешать только для запросов, которые безопасно повторять, то есть идемпотентных запросов. Для любого запроса, небезопасного при использовании ранних данных, можно применять действие “wait-for-handshake”. Для QUIC режим 0rtt поддерживается с QuicTLS, OpenSSL >= 3.5.2 и AWS-LC. Для TCP/TLS режим 0rtt поддерживается только с OpenSSL и требует передачи ALPN клиентом; иначе ранние данные не рассматриваются до выполнения рукопожатия.

alpn <protocols>

alpn <protocols>

Включает расширение TLS ALPN и объявляет через него указанный список поддерживаемых протоколов. Имена протоколов разделяются запятыми, например “http/1.1,http/1.0” (без кавычек). Библиотека SSL должна быть собрана с поддержкой расширений TLS (проверяется командой haproxy -vv). Расширение ALPN заменяет первоначальное расширение NPN. На уровне протокола ALPN требуется для включения HTTP/2 на фронтенде HTTPS и HTTP/3 на фронтенде QUIC. Однако если на таком фронтенде не задан ни один из параметров “npn”, “alpn” и “no-alpn”, по умолчанию используется “h2,http/1.1” для обычного фронтенда HTTPS и “h3” для фронтенда QUIC. Версии OpenSSL до 1.0.2 не поддерживали ALPN и поддерживали лишь устаревшее теперь расширение NPN. На момент написания большинство браузеров всё ещё поддерживает и ALPN, и NPN для HTTP/2, поэтому переход на NPN может ещё некоторое время работать. Но ALPN необходимо использовать всякий раз, когда это возможно. Протоколы, отсутствующие в объявленном списке, не согласовываются. Например, так можно принимать только соединения HTTP/2:

bind :443 ssl crt pub.pem alpn h2  # explicitly disable HTTP/1.1

В качестве ALPN QUIC поддерживает только h3 и hq-interop. h3 предназначен для HTTP/3, а hq-interop — для http/0.9 и QUIC interop runner (см. https://interop.seemann.io ). Каждая директива “alpn” заменяет предыдущую. Для удаления списка служит “no-alpn”.

Некоторые старые браузеры, например Firefox 88, испытывали проблемы с WebSocket через H2. В такой конфигурации может потребоваться явно отключить HTTP/2 в строке “alpn”, задав “http/1.1” или “no-alpn”, либо глобально включить “h2-workaround-bogus-websocket-clients”.

backlog <backlog>

backlog <backlog>

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

ca-file <cafile>

ca-file <cafile>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт файл PEM с сертификатами CA для проверки сертификата клиента. Можно загрузить каталог с несколькими CA: HAProxy попытается загрузить все файлы с расширениями “.pem”, “.crt”, “.cer” и “.crl” в этом каталоге. Файлы, имена которых начинаются с точки, игнорируются.

Предупреждение: вместо cafile можно указать “@system-ca”, чтобы использовать доверенные CA системы, как в директиве server. Но этого нельзя делать, не понимая последствий. При такой настройке bind принимает любой сертификат клиента, выданный одним из CA системы, что крайне небезопасно.

ca-ignore-err [all|<errorID>,...]

ca-ignore-err [all|<errorID>,...]

Этот параметр доступен только при сборке с поддержкой OpenSSL. Задаёт через запятую список идентификаторов ошибок, которые игнорируются при проверке на глубине > 0. Можно использовать числовой идентификатор или имя константы (X509_V_ERR) из документации OpenSSL: https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get_error.html#ERROR-CODES Рекомендуется имя константы, поскольку числовое значение может измениться в новой версии OpenSSL. Значение ‘all’ позволяет игнорировать все ошибки. Если ошибка игнорируется, рукопожатие SSL не прерывается.

ca-sign-file <cafile>

ca-sign-file <cafile>

Этот параметр доступен только тогда, когда в HAProxy включена поддержка OpenSSL. Он обозначает файл PEM, содержащий как сертификат доверенного центра (CA), так и приватный ключ этого центра, используемый для создания и подписи сертификатов серверов. Этот параметр является обязательным при включении динамической генерации сертификатов. См. ‘generate-certificates’ для подробностей.

ca-sign-pass <passphrase>

ca-sign-pass <passphrase>

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Это пароль от приватного ключа CA. Параметр является необязательным и используется только при включении динамической генерации сертификатов. См. ‘generate-certificates’ для подробностей.

ca-verify-file <cafile>

ca-verify-file <cafile>

Этот параметр задаёт файл PEM с сертификатами CA для проверки сертификата клиента. Имена этих CA не должны включаться в список имён CA, отправляемый в сообщении server hello. Обычно в “ca-file” необходимо указать промежуточные сертификаты, а в “ca-verify-file” — сертификаты, завершающие цепочку, например корневого CA.

cc <algo>

cc <algo>

Этот параметр доступен только на системах, которые определяют TCP_CONGESTION, и был протестирован на Linux и FreeBSD. Он принимает имя алгоритма управления перегрузкой TCP и настраивает слушатель на использование этого алгоритма для всех соединений, принимаемых через данный слушатель. Типичные имена включают “reno”, “cubic” и зависят от операционной системы. На некоторых системах для настройки определённых алгоритмов могут потребоваться специальные разрешения. На Linux список доступных алгоритмов можно найти в sysctl “net.ipv4.tcp_available_congestion_control”, а список разрешённых без привилегий — в “net.ipv4.tcp_allowed_congestion_control”. Для доступа к алгоритмам, требующим дополнительных разрешений, может потребоваться capability “cap_net_admin” (см. “setcap” в глобальной секции). В случае неудачи при настройке конкретного алгоритма управления перегрузкой используется значение по умолчанию, и выводится предупреждение, сообщающее об ошибке. См. также: ключевое слово сервера “cc” (раздел 5.2 ). Пример:

frontend public
    bind :443 cc bbr   # use the BBR algorithm for high bandwidths

ciphers <ciphers>

ciphers <ciphers>

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он задаёт строку, описывающую список наборов шифров (“cipher suite”), согласуемых при рукопожатии SSL/TLS вплоть до TLSv1.2. Формат строки определён в документации “man 1 ciphers” от OpenSSL. Для дополнительной информации и рекомендаций см. например, (https://wiki.mozilla.org/Security/Server_Side_TLS ) и (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Для настройки алгоритмов шифрования в TLSv1.3, см. ключевое слово “ciphersuites”.

ciphersuites <ciphersuites>

ciphersuites <ciphersuites>

Этот параметр доступен только при сборке HAProxy с поддержкой OpenSSL версии 1.1.1 или новее. Он задаёт строку со списком наборов шифров (“cipher suite”), согласуемых при рукопожатии TLSv1.3. Формат строки описан в разделе “ciphersuites” страницы “man 1 ciphers” руководства OpenSSL. Для настройки шифров TLSv1.2 и более ранних версий служит ключевое слово “ciphers”. Этот параметр может принимать и наборы шифров TLSv1.2, однако такое поведение не документировано и не рекомендуется, поскольку может быть непоследовательным или содержать ошибки. По умолчанию в OpenSSL используются наборы шифров TLSv1.3: “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

Пример:

ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

client-sigalgs <sigalgs>

client-sigalgs <sigalgs>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт строку со списком согласуемых алгоритмов подписи для аутентификации клиента. Формат строки описан на странице “man 3 SSL_CTX_set1_client_sigalgs” руководства OpenSSL. Не рекомендуется использовать параметр без конкретной необходимости.

crl-file <crlfile>

crl-file <crlfile>

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

crt <cert>

crt <cert>

Этот параметр доступен только при сборке с поддержкой OpenSSL.

HAProxy использует кеш: файлы загружаются в хранилище сертификатов только один раз, а каждое последующее ключевое слово “crt” использует кешированную версию. Если сертификат объявлен в “crt-store”, хранилище заполняется оттуда, без попыток загрузить дополнительные файлы по их расширениям.

Задаёт файл PEM с необходимыми сертификатами и связанными с ними закрытыми ключами. Его можно создать, объединив несколько файлов PEM (например, cat cert.pem key.pem > combined.pem). Если CA требует промежуточный сертификат, его также можно добавить в этот файл. Промежуточный сертификат можно предоставить для совместного использования из каталога с помощью директивы “issuers-chain-path”.

Если файл не содержит приватного ключа, HAProxy попытается загрузить ключ по тому же пути, дополненному суффиксом “.key”.

Если в используемом OpenSSL поддерживается Diffie-Hellman, параметры, присутствующие в этом файле, загружаются.

Если вместо файла PEM используется имя каталога, то все файлы, найденные в этом каталоге, будут загружены в алфавитном порядке, за исключением тех, названия которых заканчиваются на ‘.key’, ‘.issuer’, ‘.ocsp’ или ‘.sctl’ (зарезервированные расширения). Файлы, начинающиеся с точки, также игнорируются. Данная директива может быть указана несколько раз для загрузки сертификатов из нескольких файлов или каталогов. Сертификаты будут представлены клиентам, предоставляющим действительное поле TLS Server Name Indication, соответствующее одному из их CN или альтернативных имён субъекта. Поддерживаются шаблоны, где символ ‘*’ используется вместо первого компонента имени хоста (например, *.example.org соответствует www.example.org , но не www.sub.example.org ). Если используется пустой каталог, HAProxy не запустится, если не используется ключевое слово “strict-sni”.

Если клиент не передал SNI, библиотека SSL не поддерживает расширения TLS или имя узла в SNI не соответствует ни одному сертификату, предоставляется первый загруженный сертификат. Поэтому при загрузке из каталога настоятельно рекомендуется сначала загрузить сертификат по умолчанию как отдельный файл либо обеспечить его первое место в каталоге. Для выбора нескольких сертификатов по умолчанию (1 rsa и 1 ecdsa) есть 3 варианта:

• Многосертификатный пакет может быть настроен как первый сертификат (crt foobar.pem в конфигурации, где существующие файлы являются foobar.pem.ecdsa и foobar.pem.rsa).
• Или фильтр ‘*’ для каждого сертификата в строке crt-list.
• Можно использовать ключевое слово ‘default-crt’.

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

Некоторые CA (например, GoDaddy) предлагают выпадающий список типов серверов, в котором HAProxy не включён при получении сертификата. Если такое происходит, убедитесь, что выбран тип веб-сервера, который по мнению CA требует промежуточного CA (для GoDaddy выбор Apache Tomcat обеспечит правильный пакет, в то время как многие другие, например nginx, приводят к неправильному пакету, который не будет работать для некоторых клиентов).

Для каждого файла PEM HAProxy проверяет наличие файла по тому же пути, дополняемого суффиксом “.ocsp”. Если такой файл найден, поддержка расширения запроса статуса сертификата TLS (также известного как «OCSP stapling») включается автоматически. Содержимое этого файла является необязательным. Если оно не пустое, оно должно содержать действительный ответ OCSP в формате DER. Для того чтобы ответ OCSP был действительным, он должен соответствовать следующим правилам: он должен указывать хороший статус, должен быть единственным ответом на сертификат файла PEM и должен быть действительным в момент добавления. Если эти правила не соблюдены, ответ OCSP игнорируется и выдается предупреждение. Для определения того, к какому сертификату относится ответ OCSP, необходим сертификат издателя. Если сертификат издателя не найден в файле PEM, он будет загружен из файла по тому же пути, что и файл PEM, дополняемого суффиксом “.issuer”, если такой файл существует, иначе будет выдано сообщение об ошибке.

Для каждого файла PEM HAProxy также проверяет наличие файла по тому же пути, дополняемого суффиксом “.sctl”. Если такой файл найден, поддержка расширения прозрачности сертификатов (RFC6962) TLS включается. Файл должен содержать действительный список подписанных временных меток сертификата, как описано в RFC. Файл анализируется для проверки базовой синтаксической корректности, но подписи не проверяются.

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

Для этого требуется OpenSSL 1.1.1. Такое поведение можно настроить, указав по одной записи crt на каждый тип сертификата либо настроив «пакет сертификатов», как требовалось до HAProxy 1.8. См. “ssl-load-extra-files”.

crt-ignore-err <errors>

crt-ignore-err <errors>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Задаёт через запятую список идентификаторов ошибок, которые игнорируются при проверке на глубине == 0. Можно использовать числовой идентификатор или имя константы (X509_V_ERR) из документации OpenSSL: https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get_error.html#ERROR-CODES Рекомендуется имя константы, поскольку числовое значение может измениться в новой версии OpenSSL. Значение ‘all’ позволяет игнорировать все ошибки. Если ошибка игнорируется, рукопожатие SSL не прерывается.

crt-list <file>

crt-list <file>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт список файлов PEM, для каждого сертификата в котором можно указать конфигурацию ssl и фильтр SNI. Каждая строка имеет следующий формат:

<crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]

Пустые строки, а также строки, начинающиеся с символа решётки (’#’), будут игнорироваться.

crt-list можно изменять динамически через сокет статистики. (См. “add ssl crt-list”, “del ssl crt-list”, “show ssl crt-list” в руководстве по управлению).

Обычно crt-list — отдельный файл, однако каталог, загруженный директивой “crt”, также представляется внутри как crt-list. Директива “ssl-f-use” во фронтенде тоже объявляет связанный с ним crt-list.

crtfile:

Имя файла сертификата либо идентификатор, если сертификат уже объявлен
в другом месте (например, через CLI или в crt-store с псевдонимом).

Один и тот же <crtfile> можно использовать в нескольких строках
с разными параметрами и фильтрами.

crt-list поддерживает пакеты из нескольких сертификатов
(см. "ssl-load-extra-files"), если в <crtfile> указано только базовое
имя. При загрузке файла HAProxy дублирует строку crt-list внутри,
добавляя расширение алгоритма (.rsa, .ecdsa, .dsa).

sslbindconf:

 <sslbindconf> поддерживает следующие ключевые слова строки bind
 (см. раздел 5.1. Параметры bind):

 - allow-0rtt
 - alpn
 - ca-file
 - ca-verify-file
 - ciphers
 - ciphersuites
 - client-sigalgs
 - crl-file
 - curves
 - ecdhe
 - no-alpn
 - no-ca-names
 - npn
 - sigalgs
 - ssl-min-ver
 - ssl-max-ver
 - verify

 <sslbindconf> также поддерживает следующие ключевые слова директивы
 load в crt-store (см. раздел 12.7.1. Параметры load):

 - crt
 - key
 - ocsp
 - issuer
 - sctl
 - ocsp-update

В <sslbindconf> наследуются параметры строки bind. Если они не заданы,
наследуются параметры по умолчанию. Параметры, указанные
в <sslbindconf>, переопределяют унаследованные настройки.

snifilter:

Если в строке crt-list указан <snifilter>, при рукопожатии сертификат
из этой строки выбирается по <snifilter>, а CN и SAN не используются.

<snifilter> — список записей, разделённых пробелами. Записи могут быть
доменами или шаблонами DNS с подстановочным знаком: одной звёздочкой
в начале. Домен можно исключить из шаблона отрицательным фильтром,
указав '!' перед отдельным доменом. Знак ! перед * игнорируется.
Отрицательные фильтры без шаблона в той же строке также не поддерживаются.
Специальная запись '*' задаёт сертификаты по умолчанию, используемые,
если ни один домен не совпал.

Сертификаты предоставляются клиентам с действительным полем TLS
Server Name Indication, которое совпало с одним из фильтров SNI либо
с CN и SAN сертификата <crtfile>. Алгоритм сначала ищет положительную
запись домена в списке, затем, если она не найдена, — шаблон.
При совпадении с шаблоном HAProxy проверяет отрицательный фильтр
в той же строке и при необходимости отменяет совпадение. При наличии
нескольких алгоритмов ключей (RSA,ECDSA,DSA) HAProxy пытается найти
по одному сертификату каждого типа и выбирает подходящий в зависимости
от возможностей клиента.

Если клиент не передал SNI или ни один сертификат не совпал, используется
один из сертификатов по умолчанию. Запретить такой переход можно
параметром 'strict-sni'. Если сертификатов по умолчанию несколько,
HAProxy выбирает подходящий ECDSA или RSA по возможностям клиента.

Первый сертификат строки bind, заданный через crt или crt-list,
используется по умолчанию.
Можно также указать фильтр '*', добавляющий сертификат в список
сертификатов по умолчанию. Для ясности конфигурации их можно явно
задать (фильтром '*') в начале списка, чтобы перед ними не добавился
неявный сертификат по умолчанию.
Поскольку пакеты из нескольких сертификатов дублируются в crt-list
для каждого алгоритма, первую строку crt-list занимает один алгоритм,
и только он считается вариантом по умолчанию. Следует либо назначить
весь пакет вариантом по умолчанию с фильтром '*', либо задать его
в строке bind.

Для отладки конфигурации можно использовать команду "show ssl sni"
через сокет статистики (см. "show ssl sni" в руководстве по управлению).

Пример:

# comment
default.pem.rsa *
default.pem.ecdsa *
cert2.pem [alpn h2,http/1.1]
certW.pem *.domain.tld !secure.domain.tld
certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
foo.crt [key bar.pem ocsp foo.ocsp ocsp-update on] foo.bar.com

default-crt <cert>

default-crt <cert>

Этот параметр работает так же, как “crt”, но указанный сертификат используется и как сертификат по умолчанию. Можно добавить несколько сертификатов по умолчанию, чтобы иметь ECDSA и RSA; большее число вряд ли полезно.

Параметр не отключает неявно выбранные сертификаты по умолчанию: если сертификат ‘crt’ объявлен первым, до любого ‘default-crt’ или другого ‘crt’, он по-прежнему будет сертификатом по умолчанию.

Сертификат по умолчанию используется, если в строке bind нет параметра “strict-sni”. Он предоставляется, когда клиент не использует расширение servername или имя servername не соответствует ни одному настроенному сертификату.

Пример:

# this bind line has 2 default certificates
bind *:443 default-crt foobar.pem.rsa default-crt foobar.pem.ecdsa crt website.pem.rsa

# this bind line has 3 default certificates
bind *:443 crt website.pem.rsa default-crt foobar.pem.rsa default-crt foobar.pem.ecdsa

См. также ключевое слово “crt”.

curves <curves>

curves <curves>

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он задаёт строку, описывающую список алгоритмов эллиптических кривых (“набор кривых”), которые согласовываются при рукопожатии SSL/TLS с ECDHE. Формат строки — это список названий кривых, разделённых двоеточием. Пример: “X25519:P-256” (без кавычек). При задании “curves” параметр “ecdhe” игнорируется.

defer-accept

defer-accept

Необязательное ключевое слово, поддерживаемое лишь некоторыми ядрами Linux. Оно задаёт приём соединения только после поступления данных или, в худшем случае, после первой повторной передачи. Его следует использовать только с протоколами, в которых первым передаёт данные клиент, например HTTP. Производительность может немного повыситься, поскольку к моменту приёма соединения большая часть запроса уже доступна. С другой стороны, соединения, по которым не передаются данные, обнаружить не удастся. Во всех ядрах до 2.6.31 включительно этот параметр работает некорректно: соединение вообще не принимается, пока клиент не передаст данные. Это может вызвать проблемы с межсетевыми экранами перед прокси: они видят установленное соединение, тогда как прокси видит его лишь в SYN_RECV. Параметр поддерживается только для сокетов TCPv4/TCPv6 и игнорируется для остальных.

ecdhe <named curve>

ecdhe <named curve>

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он задаёт имя кривой (RFC 4492), используемой для генерации временных ключей ECDH. По умолчанию используется кривая prime256v1.

ech <dir> [ EXPERIMENTAL ]

ech <dir> [ EXPERIMENTAL ]

Применяет все ключи ECH из <dir> к строке привязки. Файлы должны иметь расширение .ech и должны использовать формат файла PEM для ECH. ( https://datatracker.ietf.org/doc/draft-farrell-tls-pemesni/ )

Это ключевое слово включает ECH в совместном режиме: HAProxy выступает конечной точкой и TLS, и ECH. См. https://datatracker.ietf.org/doc/draft-ietf-tls-esni/

Это экспериментальная функция, которая требует опции “expose-experimental-directives” в секции global. Она также требует версии OpenSSL, поддерживающей ECH (https://github.com/openssl/openssl/tree/feature/ech ), и HAProxy должен быть скомпилирован с USE_ECH=1. API ECH в AWS-LC не поддерживается.

Пример:

$ openssl ech -public_name foobar.com -out /etc/haproxy/echkeydir/foobar.com.ech

$ cat haproxy.cfg
[...]
bind :443 ech /etc/haproxy/echkeydir/ ssl crt example.com.pem

// Use the ECHCONFIG section of your .ech file
$ openssl s_client -tls1_3 -connect example.com:443 -servername example.com \
-ech_config_list AD3+DQA5cwAgACB6ybtgtFYoM5r8nJSotus4c7K0EG..9vYmFyLmNvbQAA

expose-fd listeners

expose-fd listeners

Этот параметр применим только к сокету статистики. Он предоставляет сокету статистики возможность передавать файловые описатели слушателей в другой процесс HAProxy. В режиме master-worker этот параметр уже не требуется: файловые дескрипторы слушателей передаются через внутренние сокет-пары между мастером и рабочими процессами. См. также “-x” в руководстве по управлению.

force-sslv3

force-sslv3

Этот параметр обеспечивает использование только SSLv3 для соединений SSL, созданных из этого слушателя. SSLv3 в целом менее затратен, чем соответствующие варианты TLS, при высокой интенсивности соединений. Данный параметр также доступен в глобальной директиве “ssl-default-bind-options”. См. также “ssl-min-ver” и “ssl-max-ver”.

force-tlsv10

force-tlsv10

Этот параметр обеспечивает использование только TLSv1.0 на соединениях SSL, созданных из этого слушателя. Данный параметр также доступен в глобальной директиве “ssl-default-bind-options”. См. также “ssl-min-ver” и “ssl-max-ver”.

force-tlsv11

force-tlsv11

Этот параметр обеспечивает использование только TLSv1.1 на соединениях SSL, созданных из этого слушателя. Данный параметр также доступен в глобальной директиве “ssl-default-bind-options”. См. также “ssl-min-ver” и “ssl-max-ver”.

force-tlsv12

force-tlsv12

Этот параметр обеспечивает использование только TLSv1.2 на соединениях SSL, созданных из этого слушателя. Данный параметр также доступен в глобальной директиве “ssl-default-bind-options”. См. также “ssl-min-ver” и “ssl-max-ver”.

force-tlsv13

force-tlsv13

Этот параметр обеспечивает использование только TLSv1.3 на соединениях SSL, созданных из этого слушателя. Данный параметр также доступен в глобальной директиве “ssl-default-bind-options”. См. также “ssl-min-ver” и “ssl-max-ver”.

generate-certificates

generate-certificates

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он включает динамическое создание сертификатов SSL. Необходимы сертификат CA и его закрытый ключ (см. ‘ca-sign-file’). Когда HAProxy настроен как прозрачный прямой прокси, запросы SSL вызывают ошибки из-за несовпадения общего имени в сертификате, предоставленном клиенту. При включении параметра HAProxy пытается сформировать сертификат с именем узла SNI, указанным клиентом. Это происходит только в том случае, если ни один сертификат не соответствует имени SNI (см. ‘crt-list’).

При ошибке создания сертификата для соединения используется сертификат по умолчанию. При использовании ‘strict-sni’ сертификат по умолчанию не применяется и рукопожатие завершается неудачей.

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

Создание SSL сертификата — дорогостоящая операция, поэтому используется LRU кэш для хранения сгенерированных сертификатов (см. ’tune.ssl.ssl-ctx-cache-size’). Это увеличивает потребление памяти HAProxy с целью сокращения задержки при многократном использовании одного сертификата.

gid <gid>

gid <gid>

Задаёт группу сокетов UNIX по системному идентификатору gid. Значение по умолчанию можно также задать директивой “unix-bind” в секции global. Некоторые платформы просто игнорируют этот параметр. Он эквивалентен “group”, но использует идентификатор группы вместо имени. Для сокетов, отличных от UNIX, параметр игнорируется.

group <group>

group <group>

Задаёт группу сокетов UNIX по имени системной группы. Значение по умолчанию можно также задать директивой “unix-bind” в секции global. Некоторые платформы просто игнорируют этот параметр. Он эквивалентен “gid”, но использует имя группы вместо gid. Для сокетов, отличных от UNIX, параметр игнорируется.

guid-prefix <string>

guid-prefix <string>

Генерирует глобально уникальные идентификаторы с учётом регистра для каждого слушающего сокета, созданного этой строкой bind. Префикс соединяется с порядковым индексом слушателя в текущей строке bind через символ ‘-’. Подробнее о формате см. описание ключевого слова “guid” прокси. См. также “shm-stats-file”.

id <id>

id <id>

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

idle-ping <delay>

idle-ping <delay>

Может использоваться в следующих контекстах: tcp, http, log

Задаёт интервал периодической проверки работоспособности простаивающих соединений фронтенда. Если другая сторона не отвечает до следующей запланированной проверки, соединение закрывается. Иначе тайм-аут клиента обновляется, а соединение сохраняется. Учтите: таймеры http-request/http-keep-alive работают параллельно и не обновляются через idle-ping.

Для этой возможности требуется поддержка нижележащего протокола. Пока она реализована только в мультиплексоре H2. Остальные протоколы просто игнорируют idle-ping.

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

interface <interface>

interface <interface>

Ограничивает работу сокета указанным интерфейсом. При указании сокет обрабатывает только пакеты, полученные с указанного интерфейса. Данный функционал доступен только на Linux. Интерфейс должен быть первичным системным интерфейсом, а не алиасированным интерфейсом. Возможна привязка нескольких фронтендов к одному адресу, если они привязаны к разным интерфейсам. Примечание: привязка к сетевому интерфейсу требует прав root. Данный параметр совместим только с сокетами TCPv4/TCPv6. При указании, выходной трафик использует тот же интерфейс, что и входной трафик, и соответствующую таблицу маршрутизации, даже если настроены явные маршруты через другие интерфейсы. Это может быть полезно для устранения проблем асимметричной маршрутизации, когда одинаковые IP-адреса клиентов должны быть способны доставлять запросы к фронтендам, размещённым на разных интерфейсах.

ktls <on|off> [ EXPERIMENTAL ]

ktls <on|off> [ EXPERIMENTAL ]

Включает или отключает ktls для соответствующих сокетов. При включении kTLS будет использоваться, если ядро поддерживает kTLS и используемый шифр совместим. Доступно только для ядра Linux 4.17 и выше. Примечание: некоторые сетевые драйверы и/или TLS стеки могут ограничивать использование kTLS только для TLS v1.2. См. также “force-tlsv12”.

label <label>

label <label>

Задаёт необязательную метку сокетов. По ней можно группировать сокеты независимо от места объявления строк bind.

level <level>

level <level>

Этот параметр используется только с сокетами статистики для ограничения характера команд, которые можно отправить по сокету. Он игнорируется другими сокетами. <level> может принимать одно из следующих значений:

• “user” — наименее привилегированный уровень; допускается только чтение статистики без конфиденциальных данных; изменения запрещены. Подходит для систем, где ограничение доступа к сокету затруднено.
• “operator” — уровень по умолчанию, подходящий для большинства распространённых случаев. Допускается чтение всех данных, разрешены только изменения, не затрагивающие критичные данные (например, сброс максимальных значений счётчиков).
• “admin” следует использовать с осторожностью, так как разрешены все действия (например, очистка всех счётчиков).

maxconn <maxconn>

maxconn <maxconn>

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

mode <mode>

mode <mode>

Задаёт права доступа к сокету UNIX в восьмеричном виде. Значение по умолчанию можно также задать директивой “unix-bind” секции global. Некоторые платформы просто игнорируют этот параметр. Для сокетов, отличных от UNIX, он игнорируется.

mss <maxseg>

mss <maxseg>

Задаёт значение максимального размера сегмента (MSS) для TCP, которое будет объявляться при входящих соединениях. Это может использоваться для принудительного установления меньшего MSS для определённых портов, например, при соединениях, проходящих через VPN. Обратите внимание, что эта функция зависит от функции ядра, которая теоретически поддерживается в Linux, но была нестабильной во всех версиях до 2.6.28. Она может не работать на других операционных системах. Также возможно, что значение не изменится, но изменится эффективный размер исходящих сегментов. Обычно объявляемое значение TCPv4 в сетях Ethernet составляет 1460 = 1500(MTU) - 40(IP+TCP). Если это значение положительное, оно будет использоваться как объявляемое MSS. Если отрицательное — оно указывает, на сколько следует уменьшить объявляемое MSS входящего соединения для исходящих сегментов. Этот параметр совместим только с сокетами TCP v4/v6.

name <name>

name <name>

Устанавливает опциональное имя для этих сокетов, которое будет отображаться на странице статистики.

namespace <name>

namespace <name>

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

nbconn <nbconn> [ EXPERIMENTAL ]

nbconn <nbconn> [ EXPERIMENTAL ]

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

Обратный HTTP в настоящее время всё ещё находится на стадии активного развития. Механизм конфигурации может измениться в будущем. Поэтому он внутренне помечен как экспериментальный, что означает, что “expose-experimental-directives” должен быть указан в строке перед этой директивой.

nice <nice>

nice <nice>

Устанавливает «дружелюбность» соединений, инициируемых из сокета. Значение должно находиться в диапазоне -1024..1024 включительно и по умолчанию равно нулю. Положительные значения означают, что такие соединения более дружелюбны к другим и легко предоставляют место в планировщике. Напротив, отрицательные значения означают, что соединения хотят работать с более высоким приоритетом по сравнению с другими. Разница проявляется только при высоких нагрузках, когда система приближается к насыщению. Отрицательные значения подходят для служб с низкой задержкой или администрирования, а высокие значения в целом рекомендуются для CPU интенсивных задач, таких как SSL обработка или массовые передачи, которые менее чувствительны к задержке. Например, может быть оправдано использование положительного значения для сокета SMTP и отрицательного значения для сокета RDP.

no-alpn

no-alpn

Отключает обработку ALPN: технически строка ALPN становится пустой и не объявляется. Позволяет отменить предыдущее указание “alpn” и отключить согласование протокола приложения. Также может запрещать слушателю HTTPS или QUIC согласовывать ALPN с клиентом; по умолчанию слушатели HTTPS объявляют “h2,http/1.1”, а QUIC — “h3”. См. также “alpn” выше. При использовании “crt-list” сертификат может переопределить “alpn” и снова включить обработку ALPN.

no-ca-names

no-ca-names

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он предотвращает отправку имён CA в сообщении server hello при использовании ca-file. Используйте “ca-verify-file” вместо “ca-file” с “no-ca-names”.

no-sslv3

no-sslv3

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он отключает поддержку SSLv3 на любых сокетах, создаваемых из слушателя, при наличии SSL. Примечание: поддержка SSLv2 принудительно отключена в коде и не может быть включена с помощью настроек конфигурации. Этот параметр также доступен в глобальной директиве “ssl-default-bind-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

no-strict-sni

no-strict-sni

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он отменяет строгое применение SNI, заданное предыдущей директивой “strict-sni”. Это может потребоваться, чтобы выборочно отключить strict-sni в строке “bind”, если режим уже включён глобально через “ssl-default-bind-options”. См. также параметр bind “strict-sni”.

no-tls-tickets

no-tls-tickets

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он отключает возобновление сеансов без хранения состояния (расширение TLS Ticket, RFC 5077) и принудительно включает возобновление с хранением состояния. Возобновление без хранения состояния требует больше ресурсов CPU. Параметр также доступен в глобальной директиве “ssl-default-bind-options”. Механизм билетов TLS используется только до TLS 1.2 включительно. При использовании билетов TLS прямая секретность нарушается, если их ключи не заменяются регулярно (через перезагрузку конфигурации или с помощью “tls-ticket-keys”).

no-tlsv10

no-tlsv10

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он отключает поддержку TLSv1.0 на любых сокетах, создаваемых из слушателя, при наличии поддержки SSL. Примечание: SSLv2 выключена в коде и не может быть включена с помощью любого параметра конфигурации. Этот параметр также доступен в глобальной директиве “ssl-default-bind-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

no-tlsv11

no-tlsv11

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он отключает поддержку TLSv1.1 на любых сокетах, создаваемых из слушателя, при наличии поддержки SSL. Примечание: SSLv2 принудительно отключена в коде и не может быть включена с помощью любого параметра конфигурации. Этот параметр также доступен в глобальной директиве “ssl-default-bind-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

no-tlsv12

no-tlsv12

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он отключает поддержку TLSv1.2 на любых сокетах, создаваемых из слушателя, при наличии поддержки SSL. Примечание: SSLv2 выключена в коде и не может быть включена с помощью любого параметра конфигурации. Этот параметр также доступен в глобальной директиве “ssl-default-bind-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

no-tlsv13

no-tlsv13

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он отключает поддержку TLSv1.3 на любых сокетах, создаваемых из слушателя, при наличии поддержки SSL. Примечание: SSLv2 принудительно отключена в коде и не может быть включена с помощью любого параметра конфигурации. Этот параметр также доступен в глобальной директиве “ssl-default-bind-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

npn <protocols>

npn <protocols>

Включает расширение TLS NPN и объявляет через него указанный список поддерживаемых протоколов. Имена протоколов разделяются запятыми, например “http/1.1,http/1.0” (без кавычек). Библиотека SSL должна быть собрана с поддержкой расширений TLS (проверяется командой haproxy -vv). Расширение NPN заменено расширением ALPN (см. “alpn”), но последнее доступно лишь начиная с OpenSSL 1.0.2. Если HTTP/2 требуется с более старой версией OpenSSL, можно по-прежнему использовать NPN, поскольку на момент написания его поддерживает большинство клиентов. Можно включить NPN и ALPN одновременно, хотя за пределами тестирования это, вероятно, не имеет смысла.

prefer-client-ciphers

prefer-client-ciphers

При выборе набора шифров использует предпочтения клиента; по умолчанию действуют предпочтения сервера. Параметр также доступен в глобальной директиве “ssl-default-bind-options”.

Примечание: при использовании OpenSSL >= 1.1.1 ChaCha20-Poly1305 автоматически приоритизируется (без настройки данного параметра), если шифр ChaCha20-Poly1305 находится на вершине списка шифров клиента.

При использовании настройки с двумя алгоритмами (RSA + ECDSA) алгоритм выбора будет выбирать между RSA и ECDSA и всегда будет приоритизировать ECDSA. После выбора правильного сертификата, библиотека SSL будет приоритизировать шифры, кривые и т.д. Следовательно, данный параметр не может быть использован для приоритизации сертификата RSA над сертификатом ECDSA.

proto <name>

proto <name>

Принудительно задаёт протокол мультиплексора для входящих соединений. Протокол должен быть совместим с режимом фронтенда (TCP или HTTP) и пригоден для использования на стороне фронтенда. Список доступных протоколов выводит haproxy -vv. Для них указываются режим (TCP/HTTP), сторона (FE/BE), имя мультиплексора и его флаги.

Некоторые протоколы подвержены блокировке начала очереди на стороне сервера (flag=HOL_RISK). Некоторые не поддерживают смену протокола в существующем соединении (flag=NO_UPG). Также указывается совместимость с HTX (flag=HTX).

Вот протоколы, которые могут использоваться в качестве аргумента директивы “proto” на строке bind:

quic: mode=HTTP  side=FE|BE  mux=QUIC  flags=HTX|NO_UPG|FRAMED
 qmux: mode=HTTP  side=FE|BE  mux=QMUX  flags=HTX|NO_UPG
 h2  : mode=HTTP  side=FE|BE  mux=H2    flags=HTX|HOL_RISK|NO_UPG
 h1  : mode=HTTP  side=FE|BE  mux=H1    flags=HTX|NO_UPG
 none: mode=TCP   side=FE|BE  mux=PASS  flags=NO_UPG

Параметр позволяет обойти выбор наиболее подходящего протокола мультиплексора для всех соединений, принятых этим слушающим сокетом. Например, можно принудительно использовать http/2 поверх незашифрованного TCP, указав “proto h2” в строке bind.

Если настроены ALPN или NPN, указанные в них протоколы следует согласовать с протоколом мультиплексора, чтобы избежать проблем. Например, при “proto h1” не следует задавать ALPN “h2”.

QMux — подмножество QUIC, работающее над TCP. Оно соответствует следующему черновому протоколу https://www.ietf.org/archive/id/draft-ietf-quic-qmux-01.html . На данный момент оно считается экспериментальным в HAProxy.

quic-cc-algo { cubic | newreno | bbr | nocc }[(<args,...>)]

quic-cc-algo { cubic | newreno | bbr | nocc }[(<args,...>)]

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

В дополнение к алгоритму управления перегрузкой включено равномерное распределение отправки пакетов во времени (pacing), которое снижает потери и повышает пропускную способность. Его можно отключить глобальным ключевым словом “tune.quic.fe.tx.pacing”. В большинстве случаев pacing следует оставлять включённым, особенно при использовании BBR, поскольку для корректной работы этот алгоритм зависит от pacing. Использование BBR без pacing может вызвать замедления или высокую долю потерь при передаче.

Значение по умолчанию: cubic

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

• максимальный размер окна в байтах. Он должен быть больше 10k и меньше 4g. По умолчанию используется значение “tune.quic.fe.cc.max-win-size”.

Пример:

# newreno congestion control algorithm
quic-cc-algo newreno
# cubic congestion control algorithm with one megabytes as window
quic-cc-algo cubic(1m)

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

quic-force-retry

quic-force-retry

Специальный параметр QUIC, принудительно включающий QUIC Retry для всех попыток подключения к настроенным слушателям QUIC. Он проверяет, способны ли удалённые узлы получать пакеты по транспортному адресу, с которого они начали новое соединение: им отправляется пакет Retry с токеном. Токен должен быть возвращён отправителю Retry, поскольку только тот может проверить его. Учтите, что QUIC Retry будет использоваться всегда, даже если задан порог Retry (см. “tune.quic.fe.sec.retry-threshold”).

Для этого параметра должен быть задан секрет кластера, иначе при запуске будет выдана ошибка (см. “cluster-secret”).

Дополнительные сведения о QUIC retry см. в https://www.rfc-editor.org/rfc/rfc9000.html#section-8.1.2 .

quic-socket [ connection | listener ]

quic-socket [ connection | listener ]

Специальный параметр QUIC, задающий способ выделения сокетов для конкретных слушателей. Полное описание преимуществ и недостатков каждого режима приведено в “tune.quic.fe.sock-per-conn”.

Параметр применяется совместно с глобальным “tune.quic.fe.sock-per-conn”. Если глобально включён режим “default-on” (значение по умолчанию), каждое соединение QUIC использует собственный сокет, кроме слушателей с “quic-socket listener”. Однако при глобальном режиме “force-off” настройки отдельных слушателей игнорируются.

severity-output <format>

severity-output <format>

Этот параметр применяется только к сокетам статистики и настраивает вывод уровня важности перед информационными сообщениями обратной связи. Уровень может принимать значения от 0 до 7 согласно syslog rfc5424. Перед результатами корректных и успешных команд запроса данных, например “show map” или “get acl foo”, уровень не выводится никогда. Для остальных сокетов параметр игнорируется. <format> принимает одно из значений:

• “none” (по умолчанию) к сообщениям не добавляется уровень важности.
• “number” уровень важности добавляется как число.
• “string” уровень важности добавляется как строка согласно rfc5424.

shards { <number> | by-thread | by-group }

shards { <number> | by-thread | by-group }

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

Если количество шардов превышает количество доступных потоков, оно автоматически будет сокращено до количества потоков (то есть один шард на поток). Специальное значение «by-thread» также создаёт столько шардов, сколько потоков на строке “bind”. Поскольку система равномерно распределяет входящий трафик между всеми этими шардами, важно, чтобы это число было целым делителем количества потоков. Альтернативно, другое специальное значение «by-group» создаёт один шард на группу потоков. Это может быть полезно при работе с большим количеством потоков и желании избежать создания слишком большого числа сокетов. Распределение нагрузки будет немного менее оптимальным, но конкуренция (особенно в системе) всё ещё будет ниже, чем при использовании одного сокета.

На операционных системах, не поддерживающих несколько сокетов, привязанных к одному адресу, «by-thread» и «by-group» автоматически переходят к одному шарду. Для «by-group» это делается без предупреждения, поскольку это не меняет ничего в случае одной группы, и сокеты всё равно будут дублироваться для каждой группы. Однако для «by-thread» при этом будет выдано диагностическое предупреждение, поскольку итоговое количество слушателей не будет соответствовать ожидаемому.

sigalgs <sigalgs>

sigalgs <sigalgs>

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он задаёт строку, описывающую список алгоритмов подписи, согласуемых при рукопожатии TLSv1.2 и TLSv1.3. Формат строки определён в «man 3 SSL_CTX_set1_sigalgs» из справочной документации OpenSSL. Использование этого параметра не рекомендуется, если не требуется совместимость с промежуточным устройством.

ssl

ssl

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Он включает расшифровку SSL на соединениях, создаваемых из этого слушателя. Необходим сертификат (см. “crt” выше). Все содержимое в буферах будет отображаться в открытом виде, поэтому ACL и обработка HTTP будут иметь доступ только к расшифрованному содержимому. Поддержка SSLv3 отключена по умолчанию; для включения используйте “ssl-min-ver SSLv3”.

ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

Этот параметр обеспечивает использование <version> или ниже на соединениях SSL, создаваемых из этого слушателя. Использование этого параметра без “ssl-min-ver” может быть неоднозначным, поскольку значение по умолчанию ssl-min-ver может измениться в будущих версиях HAProxy. Этот параметр также доступен в глобальной директиве “ssl-default-bind-options”. См. также “ssl-min-ver”.

ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

Этот параметр обеспечивает использование <version> или выше на соединениях SSL, создаваемых из этого слушателя. Значение по умолчанию — “TLSv1.2”. Этот параметр также доступен в глобальной директиве “ssl-default-bind-options”. См. также “ssl-max-ver”.

strict-sni

strict-sni

Этот параметр доступен только при сборке с поддержкой OpenSSL. Согласование SSL/TLS разрешено лишь в том случае, если клиент передал SNI, соответствующий сертификату. Сертификат по умолчанию не используется. Параметр также позволяет запускаться без сертификатов в строке bind: можно указать пустой каталог и позже заполнить его через сокет статистики. Он доступен и в глобальной директиве “ssl-default-bind-options”, а выборочно отключить его в строке “bind” можно с помощью “no-strict-sni”. Подробнее см. “crt” и команду “add ssl crt-list” в руководстве по управлению.

tcp-md5sig <password>

tcp-md5sig <password>

Включает подпись TCP MD5 (RFC 2385 Защита сессий BGP через опцию подписи TCP MD5) для всех входящих соединений, инициированных из этого прослушиваемого сокета. Эта опция доступна только на Linux. При включении используется строка <password> для подписи каждого сегмента TCP с помощью 16-байтового MD5 хэша. Это обеспечивает защиту соединения TCP от подделки. Основное применение этой опции — защита BGP от введения фальшивых сегментов TCP в поток соединения. Однако она может быть полезна для любых очень долговременных соединений TCP.

tcp-ss <mode>

tcp-ss <mode>

Задаёт параметр TCP Save SYN для всех входящих соединений, создаваемых этим прослушивающим сокетом. Он доступен в Linux начиная с версии 4.3 и предписывает ядру попытаться сохранить копию входящего пакета IP с флагом TCP SYN для последующего анализа через функцию извлечения образцов “fc_saved_syn”. Поддерживаются 3 режима: 0 — сохранение пакета SYN отключено, это значение по умолчанию; 1 — сохранение пакета SYN включено, сохраняются заголовки IP и TCP; 2 — сохранение пакета SYN включено, сохраняются заголовки ETH, IP и TCP.

Это работает только для обычных соединений TCP и игнорируется для других протоколов (например, UNIX сокетов). См. также “fc_saved_syn”.

tcp-ut <delay>

tcp-ut <delay>

Устанавливает тайм-аут пользователя TCP для всех входящих соединений, создаваемых из этого слушающего сокета. Опция доступна на Linux с версии 2.6.37. Позволяет HAProxy настроить тайм-аут для сокетов, содержащих данные, не получающие подтверждения в течение заданного периода. Особенно полезна в случае долговременных соединений с длительными периодами бездействия, таких как удалённые терминалы или пулы соединений с базами данных, где тайм-ауты клиента и сервера должны быть высокими, чтобы допускать длительный период бездействия, но при этом важно обнаруживать исчезновение клиента для освобождения всех ресурсов, связанных с его соединением (и сессией сервера). Аргумент — задержка, выраженная в миллисекундах по умолчанию. Работает только для обычных TCP соединений и игнорируется для других протоколов.

tfo

tfo

Необязательное ключевое слово, поддерживаемое только в ядрах Linux >= 3.7. Включает TCP Fast Open на слушающем сокете. Начиная со второго соединения, клиенты с такой поддержкой могут отправить запрос и получить ответ в ходе 3-этапного рукопожатия, экономя один цикл обмена по сравнению с первым соединением. Это имеет смысл только для протоколов с высокой частотой соединений, где важен каждый цикл обмена. Возможны проблемы со многими межсетевыми экранами, которые не принимают данные в пакетах SYN, поэтому параметр следует включать только после тщательного тестирования. Он поддерживается только для сокетов TCPv4/TCPv6 и игнорируется для остальных. Если libc не определяет TCP_FASTOPEN, может потребоваться сборка HAProxy с USE_TFO=1.

thread [<thread-group>/]<thread-set>[,...]

thread [<thread-group>/]<thread-set>[,...]

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

Существуют две схемы нумерации. По умолчанию номера потоков являются абсолютными в процессе и варьируются от 1 до значения, указанного в global.nbthread. Также возможно указать номер потока с помощью его относительного номера внутри группы потоков, указав сначала номер группы потоков, затем слэш (’/’) и относительный номер потока(ов). В этом случае номера потоков также начинаются с 1 и заканчиваются на 32 или 64 в зависимости от платформы. При указании абсолютных номеров потоков они автоматически переводятся в относительные номера после того, как известны группы потоков. Обычно для простых конфигураций предпочтительны абсолютные номера, а для сложных конфигураций, где размещение на CPU имеет значение для производительности, — относительные.

После необязательного номера группы потоков спецификация “thread-set” должна иметь следующий формат:

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

Как следует из названий, “all” выбирает все потоки набора: все потоки указанной группы либо все потоки процесса. “odd” выбирает нечётные потоки (каждый второй, начиная с 1), а “even” — чётные (каждый второй, начиная с 2), также для процесса или группы. Если указаны диапазоны номеров, выбираются все потоки от первого до последнего номера включительно. Номера относительны к группе или абсолютны в зависимости от наличия номера группы потоков. Если первый номер пропущен, используется “1” — первый поток группы либо процесса. Если последний номер пропущен, используется последний номер потока группы (32 или 64) либо процесса (global.nbthread).

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

Важно понимать, что каждый слушатель, описанный строкой “bind”, создаёт как минимум один сокет, представленный как минимум одним файловым описателем. Поскольку файловые описатели не могут охватывать несколько групп потоков, если строка “bind” указывает диапазон потоков, охватывающий более одной группы, автоматически создаются несколько файловых описателей, чтобы для каждой группы был хотя бы один. Технически все они ссылаются на один и тот же сокет в ядре, но они получат отдельный идентификатор в HAProxy и даже будут иметь отдельную запись в статистике, если используется “option socket-stats”.

Основная цель — иметь несколько строк bind, использующих одинаковый IP:порт, но разные потоки в слушателе, чтобы система могла распределять входящие соединения по нескольким очередям, обходя внутреннюю балансировку нагрузки очередей HAProxy. В настоящее время поддержка такой конфигурации известна для Linux 3.9 и выше. См. также ключевое слово “shards”, описанное выше, которое автоматически дублирует строки “bind” и присваивает их нескольким группам потоков.

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

tls-tickets

tls-tickets

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он включает возобновление сеансов без хранения состояния (расширение TLS Ticket, RFC 5077). Это поведение по умолчанию, но параметр может потребоваться, чтобы выборочно включить его в строке “bind”, если оно отключено глобально через “no-tls-tickets” в “ssl-default-bind-options”. См. также ключевое слово bind “no-tls-tickets”.

tls-ticket-keys <keyfile>

tls-ticket-keys <keyfile>

Задаёт файл, из которого загружаются ключи билетов TLS. Длина ключа должна составлять 48 или 80 байт в зависимости от использования aes128 или aes256. Ключи кодируются в base64, по одному в строке (например, openssl rand 80 | openssl base64 -A | xargs echo). Первый ключ определяет длину последующих: смешивать ключи aes128 и aes256 нельзя. Число ключей задаётся параметром сборки TLS_TICKETS_NO (по умолчанию 3), и файл должен содержать не меньше этого числа ключей. Последние TLS_TICKETS_NO ключей используются для расшифрования, а предпоследний — для шифрования. Это позволяет легко заменять ключи: достаточно добавить новый ключ в конец файла и перезагрузить процесс. Ключи необходимо регулярно менять (например, каждые 12h), иначе нарушается совершенная прямая секретность. Также рекомендуется не хранить ключи на постоянных носителях, например жёстких дисках: можно использовать tmpfs и исключить вытеснение этих файлов в swap. Подсказку о сроке действия можно изменить через tune.ssl.timeout.

transparent

transparent

Является опциональным ключевым словом, поддерживающимся только на определённых версиях ядра Linux. Оно указывает на то, что адреса будут привязаны даже в случае, если они не принадлежат локальной машине, и пакеты, направляемые к этим адресам, будут перехвачены так же, как если бы эти адреса были настроены локально. Обычно требуется включение пересылки IP-пакетов. Внимание! не используйте это в сочетании с стандартным адресом ‘*’, иначе произойдёт перенаправление всего трафика на указанном порту. Это ключевое слово доступно только при сборке HAProxy с USE_LINUX_TPROXY=1. Этот параметр совместим только с сокетами TCPv4 и TCPv6, в зависимости от версии ядра. Некоторые дистрибутивы ядер включают бэкпорт данной функции, поэтому проверьте поддержку у поставщика.

uid <uid>

uid <uid>

Задаёт владельца сокетов UNIX по системному идентификатору uid. Значение по умолчанию можно также задать директивой “unix-bind” секции global. Некоторые платформы просто игнорируют параметр. Он эквивалентен “user”, но использует числовой идентификатор пользователя вместо имени. Для сокетов, отличных от UNIX, параметр игнорируется.

user <user>

user <user>

Задаёт владельца сокетов UNIX по имени системного пользователя. Значение по умолчанию можно также задать директивой “unix-bind” секции global. Некоторые платформы просто игнорируют параметр. Он эквивалентен “uid”, но использует имя пользователя вместо uid. Для сокетов, отличных от UNIX, параметр игнорируется.

v4v6

v4v6

Является опциональным ключевым словом, поддерживающимся только на наиболее новых системах, включая ядра Linux >= 2.4.21. Используется для привязки сокета как к IPv4, так и к IPv6 при использовании стандартного адреса. Такая настройка иногда необходима на системах, которые по умолчанию привязываются только к IPv6. Не оказывает влияния на сокеты, не относящиеся к IPv6, и подавляется опцией “v6only”.

v6only

v6only

Является опциональным ключевым словом, поддерживающимся только на последних системах, включая ядра Linux >= 2.4.21. Используется для привязки сокета только к IPv6, когда используется адрес по умолчанию. Такое действие иногда предпочтительнее выполнения системно в целом, поскольку оно действует на уровне слушателя. Не влияет на сокеты, не относящиеся к IPv6, и имеет приоритет перед опцией “v4v6”.

verify [none|optional|required]

verify [none|optional|required]

Этот параметр доступен только при сборке с поддержкой OpenSSL. При значении ’none’ сертификат клиента не запрашивается. Это значение по умолчанию. В остальных случаях сертификат запрашивается. Если клиент не предоставил его после запроса, рукопожатие прерывается при ‘verify required’, но завершается успешно при ‘verify optional’. Предоставленный сертификат всегда проверяется с помощью CA из ‘ca-file’ и необязательных списков отзыва CRL из ‘crl-file’. При неудачной проверке рукопожатие прерывается независимо от значения ‘verify’, кроме случаев точного совпадения кода ошибки с одним из перечисленных в ‘ca-ignore-err’ или ‘crt-ignore-err’.

5.2. Параметры server и default-server

Ключевые слова “server” и “default-server” поддерживают ряд настроек, передаваемых аргументами в строке сервера. Порядок аргументов не имеет значения; все они необязательны. Некоторые настройки состоят из одного слова (логические параметры), другие требуют одного или нескольких значений. Значения должны следовать непосредственно за именем настройки. Кроме случая “default-server”, все используемые настройки должны указываться после адреса сервера:

server <name> <address>[:port] [settings ...]
default-server [settings ...]

Примечание: все эти настройки поддерживаются как для “server”, так и для “default-server”, за исключением “id”, который поддерживается только для “server”.

На данный момент поддерживаются следующие настройки.

addr <ipv4|ipv6>

addr <ipv4|ipv6>

Допустимые контексты: tcp, http, log

Параметр “addr” позволяет направлять проверки работоспособности или проверки агента на другой IP-адрес. На некоторых серверах может быть полезно выделить адрес отдельному компоненту, способному выполнять сложные тесты и лучше подходящему для проверок, чем само приложение. Параметр игнорируется, если не задан “check”. См. также “port”.

agent-check

agent-check

Допустимые контексты: tcp, http, log

Включает дополнительную проверку через агента, выполняемую независимо от обычной проверки работоспособности. Проверка работоспособности агента осуществляется путём установления соединения TCP на порт, заданный параметром “agent-port”, и чтения строки ASCII, завершающейся первым вхождением ‘\r’ или ‘\n’. Строка состоит из ряда слов, разделённых пробелами, табуляциями или запятыми в любом порядке, каждое из которых состоит из:

• Представление ASCII положительного целого процента, например, “75%”. Значения в этом формате будут устанавливать вес пропорционально начальному весу сервера, заданному при запуске HAProxy. Примечание: нулевой вес отображается на странице статистики как “DRAIN”, поскольку он оказывает одинаковое влияние на сервер (сервер удаляется из группы балансировки). Это устаревший способ установки веса сервера. Рекомендуется использовать установку с префиксом “weight:”.

• Строка “weight:” за которой следует положительное целое число или положительное целое число в процентах, без пробела. Если значение заканчивается знаком ‘%’, то новый вес будет пропорционален первоначальному весу сервера. В противном случае значение считается абсолютным весом и должно находиться в диапазоне 0 до 256. Серверы, входящие в ферму, работающую по статическому алгоритму балансировки нагрузки, имеют более жесткие ограничения, поскольку вес не может изменяться после установки. Таким образом, для этих серверов допускаются только значения 0 и 100% (или 0 и первоначальный вес). Изменения вступают в силу немедленно, хотя некоторые алгоритмы балансировки нагрузки требуют определённого количества запросов, чтобы учесть изменения. Примечание: нулевой вес отображается на странице статистики как “DRAIN”, поскольку он оказывает такое же влияние на сервер (сервер удаляется из фермы балансировки нагрузки).

• Строка “maxconn:” за которой следует целое число (без пробела). Значения в таком формате устанавливают параметр maxconn сервера. Максимальное количество соединений, объявленное в этом параметре, должно быть умножено на количество балансировщиков нагрузки и различных бэкендов, использующих эту проверку работоспособности, чтобы получить общее количество соединений, которое может получить сервер. Пример: maxconn:30

• Слово “ready”. Это изменит административное состояние сервера на режим READY, тем самым отменяя любые состояния DRAIN или MAINT

• Слово “drain”. Это изменит административное состояние сервера на режим DRAIN, тем самым он не будет принимать новые соединения, кроме соединений, направленных на него механизмом привязки сеансов.

• Слово “maint”. Это установит административное состояние сервера в режиме MAINT, таким образом, он не будет принимать никакие новые соединения, и проверки работоспособности будут остановлены.

• Слова “down”, “fail” или “stopped”, опционально сопровождаемые описательной строкой после знака решетки (’#’). Все эти слова указывают на состояние работы сервера как DOWN, но поскольку само слово отображается на странице статистики, различие позволяет администратору понять, было ли это ожидаемым или нет: сервис может быть намеренно остановлен, может быть в состоянии “up”, но не проходить некоторые проверки работоспособности, или может быть отмечен как “down” (например, отсутствует процесс, или порт не отвечает).

• Слово “up” устанавливает состояние работы сервера как UP, если проверки работоспособности также сообщают, что сервис доступен.

Параметры, которые не объявляются агентом, не изменяются. Например, агент может быть спроектирован для мониторинга CPU и передачи только относительного веса, не взаимодействуя с состоянием работы. Аналогично, агент может быть спроектирован как интерфейс для конечного пользователя с 3 переключателями, позволяющими администратору изменять только административное состояние. Однако важно учитывать, что только сам агент может отменить свои действия, поэтому если сервер установлен в режим DRAIN или в состояние DOWN с помощью агента, то агент должен реализовать другие эквивалентные действия для возврата сервиса в рабочее состояние.

Невозможность подключения к агенту не считается ошибкой, поскольку подключение проверяется через регулярную проверку работоспособности, включаемую с помощью параметра “check”. Предупреждение: не рекомендуется останавливать агент после того, как он сообщает «down», поскольку только агент, сообщивший “up”, сможет включить сервер. Примечание: CLI на Unix-сокете статистики также может принудительно установить результат агента для обхода ошибочного агента, если это необходимо.

Требуется установить параметр “agent-port”. См. также параметры “agent-inter” и “no-agent-check”.

agent-send <string>

agent-send <string>

Допустимые контексты: tcp, http, log

Если параметр задан, после подключения HAProxy отправляет указанную строку агенту без изменений. Например, в неё можно включить имя бэкенда, чтобы агент выдавал разные ответы в зависимости от бэкенда. Для завершения запроса переводом строки необходимо включить в него ‘\n’.

agent-inter <delay>

agent-inter <delay>

Допустимые контексты: tcp, http, log

Параметр “agent-inter” задаёт интервал между двумя проверками агента в <delay> миллисекунд. Если параметр не указан, задержка по умолчанию равна 2000 ms.

Так же, как и для любого другого параметра, зависящего от времени, значение может быть указано в любой из явных единиц: { us, ms, s, m, h, d }. Параметр “agent-inter” также служит тайм-аутом для проверок работоспособности агента, если “timeout check” не задан. Чтобы снизить эффекты «резонанса» при размещении нескольких серверов на одном оборудовании, запуск проверок через агента и обычных проверок работоспособности всех серверов производится с небольшим временным сдвигом между ними. Также возможно добавить некоторое случайное отклонение в интервалы проверок через агента и обычных проверок работоспособности с помощью глобального параметра “spread-checks”. Это имеет смысл, например, когда большое количество бэкендов использует одни и те же серверы.

См. также параметры “agent-check” и “agent-port”.

agent-addr <addr>

agent-addr <addr>

Допустимые контексты: tcp, http, log

Параметр “agent-addr” задаёт адрес проверки агента.

Проверку agent-check можно перенести на другой узел, централизовав управление состоянием и весами серверов, определённых в HAProxy, если сами сервисы не могут отслеживать своё состояние и управлять им. Можно указать IP-адрес или имя узла; для имени будет выполнено разрешение.

agent-port <port>

agent-port <port>

Допустимые контексты: tcp, http, log

Параметр “agent-port” задаёт порт TCP, используемый для проверок агента.

См. также параметры “agent-check” и “agent-inter”.

allow-0rtt

allow-0rtt

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

Разрешает отправку ранних данных серверу при использовании TLS 1.3. Примечание: ранние данные будут отправлены только если клиент использовал ранние данные, или если бэкенд использует “retry-on” с ключевым словом “0rtt-rejected”. С QUIC, 0rtt поддерживается с QuicTLS, OpenSSL >= 3.5.2 и AWS-LC. С TCP/TLS, 0rtt поддерживается только с OpenSSL.

alpn <protocols>

alpn <protocols>

Допустимые контексты: tcp, http

Включает расширение TLS ALPN и объявляет через него указанный список поддерживаемых протоколов. Имена протоколов разделяются запятыми, например “http/1.1,http/1.0” (без кавычек). Библиотека SSL должна быть собрана с поддержкой расширений TLS (проверяется командой haproxy -vv). ALPN заменяет первоначальное расширение NPN. ALPN требуется для подключения к серверам HTTP/2, а также для использования HTTP/3 через сервер QUIC. Для серверов QUIC без “alpn” по умолчанию используется “h3”. Версии OpenSSL до 1.0.2 не поддерживали ALPN и поддерживали только устаревшее теперь расширение NPN. Если предполагается поддержка и HTTP/2, и HTTP/1.1, можно объявить обе версии в порядке предпочтения, как ниже:

server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1

См. также “ws” для использования альтернативного ALPN для потоков WebSocket.

backup

backup

Допустимые контексты: tcp, http, log

При наличии “backup” в строке сервера он участвует в балансировке нагрузки только тогда, когда недоступны все остальные нерезервные серверы. Однако запросы с cookie привязки сеанса, указывающим на этот сервер, обслуживаются всегда. По умолчанию используется только первый работоспособный резервный сервер, если в бэкенде не задан параметр “allbackups”. См. также “no-backup” и “allbackups”.

ca-file <cafile>

ca-file <cafile>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только тогда, когда в HAProxy включена поддержка OpenSSL. Он указывает на файл PEM из которого загружаются сертификаты CA, используемые для проверки сертификата сервера. Возможна загрузка каталога, содержащего несколько CA, в этом случае HAProxy попытается загрузить каждый “.pem”, “.crt”, “.cer” и .crl, доступный в каталоге, файлы, начинающиеся с точки, игнорируются.

Чтобы использовать доверенные CA вашей системы, параметр “@system-ca” может быть использован вместо cafile. Путь к этому каталогу может быть перезаписан с помощью установки переменной среды SSL_CERT_DIR.

cc <algo>

cc <algo>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только на системах, которые определяют TCP_CONGESTION, и был протестирован на Linux и FreeBSD. Он принимает имя алгоритма управления перегрузкой TCP и настраивает исходящие соединения на использование этого алгоритма. Типичные имена включают “reno” или “cubic” и зависят от операционной системы. На некоторых системах для настройки определённых алгоритмов могут потребоваться специальные разрешения. На Linux доступные алгоритмы перечислены в sysctl “net.ipv4.tcp_available_congestion_control”, а разрешённые без привилегий — в “net.ipv4.tcp_allowed_congestion_control”. Для доступа к алгоритмам, требующим дополнительных разрешений, может потребоваться capability “cap_net_admin” (см. “setcap” в глобальной секции). В случае неудачи при настройке конкретного алгоритма управления перегрузкой используется алгоритм по умолчанию. См. также: ключевое слово bind “cc” (раздел 5.1 ).

check

check

Допустимые контексты: tcp, http, log

Этот параметр включает проверки работоспособности сервера: — если он не задан, проверки не выполняются и сервер всегда считается доступным. — Если он задан и другие методы проверки не настроены, сервер считается доступным, когда удалось установить соединение на самом верхнем из настроенных транспортных уровней. По умолчанию это TCP, а при “ssl” или “check-ssl” — SSL/TLS. В обоих случаях возможны префиксы соединения, например заголовок протокола PROXY при “send-proxy” или “check-send-proxy”. Для динамических серверов поведение немного отличается; подробности приведены ниже. — Если параметр задан и определена проверка на уровне приложения, обмены на этом уровне выполняются поверх настроенного транспорта. Сервер считается доступным, если все обмены успешны.

По умолчанию проверки выполняются по адресу и порту сервера с теми же параметрами инкапсуляции (SSL/TLS, заголовок протокола PROXY и т. д.). Адрес назначения можно изменить через “addr”, а порт — через “port”. В таком случае предполагается, что проверяется не порт сервиса, поэтому настроенные параметры инкапсуляции не используются повторно. Для отправки заголовков соединения необходимо явно задать “check-send-proxy”, а для использования SSL/TLS — “check-ssl”.

Примечание: не выполняется неявная настройка ssl и протокола PROXY для динамических серверов. В этом случае требуется явно использовать “check-ssl” и “check-send-proxy” при необходимости, даже если порт проверки не переопределён.

Когда “sni” или “alpn” заданы на строке сервера, их значение не используется для проверки работоспособности и необходимо использовать “check-sni” или “check-alpn”.

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

Интервал между проверками можно задать с помощью ключевого слова “inter”, а ключевые слова “rise” и “fall” могут быть использованы для определения количества успешных или неудачных проверок работоспособности, необходимых для обозначения сервера как доступного или недоступного.

Опциональные проверки работоспособности на уровне приложения могут быть настроены с помощью “option httpchk”, “option mysql-check” “option smtpchk”, “option pgsql-check”, “option ldap-check”, или “option redis-check”.

Пример:

# simple tcp check
backend foo
  server s1 192.168.0.1:80 check
# this does a tcp connect + tls handshake
backend foo
  server s1 192.168.0.1:443 ssl check
# simple tcp check is enough for check success
backend foo
  option tcp-check
  tcp-check connect
  server s1 192.168.0.1:443 ssl check

check-reuse-pool

check-reuse-pool

Допустимые контексты: tcp, http

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

Для упрощения конфигурации этот параметр игнорируется без уведомления, если определён какой-либо конкретный параметр подключения проверки, либо на строке сервера, либо в собственном правиле tcp-check connect.

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

См. также: “check-pool-conn-name”

check-send-proxy

check-send-proxy

Допустимые контексты: tcp, http

Этот параметр заставляет генерировать строку протокола PROXY при исходящих проверках работоспособности, независимо от того, использует ли сервер send-proxy для обычного трафика. По умолчанию, протокол PROXY включается для проверок работоспособности, если он уже включен для обычного трафика, и если отсутствуют директивы “port” и “addr”. Однако, если такие директивы присутствуют, для принудительного использования протокола необходимо использовать параметр “check-send-proxy”. Дополнительную информацию см. в отношении параметра “send-proxy”.

check-alpn <protocols>

check-alpn <protocols>

Допустимые контексты: tcp, http

Задаёт протоколы, объявляемые через ALPN. Имена разделяются запятыми, например “http/1.1,http/1.0” (без кавычек). Если параметр не задан, используется ALPN сервера.

check-pool-conn-name <name>

check-pool-conn-name <name>

Допустимые контексты: tcp, http

При повторном использовании соединений для проверок заданное <name> служит идентификатором для поиска соответствующего соединения в пуле. Это аналог параметра сервера “pool-conn-name”. Если текущий параметр не задан, запасным значением служит “check-sni”.

См. также: “check-reuse-pool”

check-proto <name>

check-proto <name>

Допустимые контексты: tcp, http

Принудительно задаёт протокол мультиплексора для соединений проверки работоспособности сервера. Протокол должен быть совместим с типом проверки (TCP или HTTP) и пригоден для использования на стороне бэкенда. Список доступных протоколов выводит haproxy -vv. Для них указываются режим (TCP/HTTP), сторона (FE/BE), имя мультиплексора и его флаги.

Некоторые протоколы подвержены блокировке начала очереди на стороне сервера (flag=HOL_RISK). Некоторые не поддерживают смену протокола в существующем соединении (flag=NO_UPG). Также указывается совместимость с HTX (flag=HTX).

Здесь приведены протоколы, которые могут быть использованы в качестве аргумента директивы “check-proto” на строке сервера:

h2  : mode=HTTP  side=FE|BE  mux=H2    flags=HTX|HOL_RISK|NO_UPG
fcgi: mode=HTTP  side=BE     mux=FCGI  flags=HTX|HOL_RISK|NO_UPG
h1  : mode=HTTP  side=FE|BE  mux=H1    flags=HTX|NO_UPG
none: mode=TCP   side=FE|BE  mux=PASS  flags=NO_UPG
quic: mode=HTTP  side=FE|BE  mux=QUIC  flags=HTX|NO_UPG|FRAMED
spop: mode=SPOP  side=BE     mux=SPOP  flags=HOL_RISK|NO_UPG

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

Если настроены ALPN или NPN, указанные в них протоколы следует согласовать с протоколом мультиплексора, чтобы избежать проблем. Например, при “proto h1” не следует задавать ALPN “h2”.

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

check-sni-auto

check-sni-auto

Допустимые контексты: tcp, http, log

Этот параметр включает автоматический выбор SNI при проверке работоспособности серверов через SSL, если значение не было задано ранее. Параметр включён по умолчанию, но может быть использован как “server” для сброса любого значения “no-check-sni-auto”, наследуемого из директивы “default-server” как значение по умолчанию. Он также может быть использован как “default-server” для сброса любого предыдущего значения “default-server” “no-check-sni-auto”.

Для соединений HTTPS SNI выбирается автоматически только при отсутствии правила “http-check connect”. Выбор основан на значении заголовка host, заданном директивой “option httpchk” или правилом “http-check send”. В правилах “http-check connect” автоматический выбор не выполняется. Для других протоколов параметр игнорируется.

Если используется автоматическое определение SNI для проверки работоспособности, то значение присваивается имени соединения, если задан параметр “check-reuse-pool”, за исключением случая, когда оно перекрывается ключевым словом сервера “check-pool-conn-name”.

См. опцию “sni-auto” для включения автоматического выбора SNI для прокси-трафика.

check-sni <sni>

check-sni <sni>

Допустимые контексты: tcp, http, log

Этот параметр позволяет указать SNI, используемый при проверке работоспособности через SSL. Возможна только строка для задания <sni>. Если необходимо задать SNI для проксированных потоков, см. “sni”.

check-ssl

check-ssl

Допустимые контексты: tcp, http, log

Этот параметр обеспечивает шифрование всех проверок работоспособности через SSL, независимо от того, использует ли сервер SSL для обычного трафика. Обычно этот параметр применяется тогда, когда указано явное “port” или “addr”, а проверки работоспособности через SSL не наследуются. Важно понимать, что данный параметр вставляет слой SSL на транспортном уровне ниже проверок, таким образом, простая проверка TCP соединения превращается в проверку SSL соединения, которая заменяет старую проверку ssl-hello-chk. Наиболее распространённый случай — отправка проверок HTTPS путём объединения проверок “httpchk” и SSL. Все настройки SSL распространяются на проверки работоспособности и трафик (например, шифры). См. параметр “ssl” для дополнительной информации и “no-check-ssl” для отключения этого параметра.

check-via-socks4

check-via-socks4

Допустимые контексты: tcp, http, log

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

ciphers <ciphers>

ciphers <ciphers>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только при сборке с поддержкой OpenSSL. Этот параметр задаёт строку, описывающую список алгоритмов шифрования, согласуемых при рукопожатии SSL/TLS с сервером. Формат строки определён в документации “man 1 ciphers” от OpenSSL. Для дополнительной информации и рекомендаций см. например, (https://wiki.mozilla.org/Security/Server_Side_TLS ) и (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). Для настройки шифрования TLSv1.3 см. параметр “ciphersuites”.

ciphersuites <ciphersuites>

ciphersuites <ciphersuites>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только при сборке с поддержкой OpenSSL и использовании OpenSSL 1.1.1 или более поздней версии для сборки HAProxy. Этот параметр задаёт строку, описывающую список алгоритмов шифрования, согласуемых во время TLS 1.3 рукопожатия с сервером. Формат строки определён в разделе “ciphersuites” документации OpenSSL, доступной по команде “man 1 ciphers”. Для настройки шифров TLSv1.2 и ранее обратитесь к ключевому слову “ciphers”.

client-sigalgs <sigalgs>

client-sigalgs <sigalgs>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только при сборке с поддержкой OpenSSL. Устанавливает строку, описывающую список алгоритмов подписи, связанных с аутентификацией клиента, которые согласовываются. Формат строки определён в “man 3 SSL_CTX_set1_client_sigalgs” из страниц справки OpenSSL. Не рекомендуется использовать этот параметр, если не определён конкретный сценарий использования.

cookie <value>

cookie <value>

Допустимые контексты: http

Параметр “cookie” устанавливает значение куки, присваиваемое серверу, в <value>. Это значение будет проверяться в входящих запросах, и первый рабочий сервер, обладающий таким же значением, будет выбран. В ответ, в режимах вставки или переписывания куки, это значение будет присваиваться куки, отправляемой клиенту. Нет ничего неправильного в том, чтобы несколько серверов делили одно и то же значение куки, и это, в действительности, довольно распространено между обычными и резервными серверами. См. также ключевое слово “cookie” в секции бэкенда.

crl-file <crlfile>

crl-file <crlfile>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

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

crt <cert>

crt <cert>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

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

Если файл не содержит приватного ключа, HAProxy попытается загрузить ключ по тому же пути, но с суффиксом “.key” (при условии, что опция “ssl-load-extra-files” установлена соответствующим образом).

curves <curves>

curves <curves>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только при сборке с поддержкой OpenSSL. Устанавливает строку, описывающую список алгоритмов эллиптических кривых (“набор кривых”), которые согласовываются при рукопожатии SSL/TLS с ECDHE. Формат строки — это список названий кривых, разделённых двоеточием. Пример: “X25519:P-256” (без кавычек)

disabled

disabled

Допустимые контексты: tcp, http, log

Ключевое слово “disabled” запускает сервер в состоянии “disabled”. Это означает, что сервер отмечен как выключенный в режиме технического обслуживания, и никакое соединение, кроме тех, которые разрешены режимом persist, не достигнет его. Оно очень хорошо подходит для настройки новых серверов, поскольку обычный трафик никогда не достигнет их, при этом возможно тестирование сервиса с использованием механизма force-persist. См. также настройку “enabled”.

enabled

enabled

Допустимые контексты: tcp, http, log

В строке ‘server’ этот параметр позволяет сбросить настройку ‘disabled’, унаследованную из директивы ‘default-server’ как значение по умолчанию. В директиве ‘default-server’ он также может сбросить предыдущую настройку ‘default-server’ ‘disabled’.

error-limit <count>

error-limit <count>

Допустимые контексты: tcp, http, log

Если включено наблюдение за работоспособностью, параметр “error-limit” задаёт число последовательных ошибок, вызывающее событие, выбранное параметром “on-error”. По умолчанию — 10 последовательных ошибок.

См. также “check”, “error-limit” и “on-error”.

fall <count>

fall <count>

Допустимые контексты: tcp, http, log

Параметр “fall” устанавливает, что сервер считается неисправным после <count> последовательных неудачных проверок работоспособности. Значение по умолчанию для этого параметра равно 3, если параметр не указан. См. также параметры “check”, “inter” и “rise”.

force-sslv3

force-sslv3

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр обеспечивает использование только SSLv3 при SSL для связи с сервером. SSLv3 в целом менее затратен, чем соответствующие TLS при высокой интенсивности соединений. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. См. также “ssl-min-ver” и ssl-max-ver.

force-tlsv10

force-tlsv10

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр обеспечивает использование только TLSv1.0 при использовании SSL для связи с сервером. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. См. также “ssl-min-ver” и ssl-max-ver.

force-tlsv11

force-tlsv11

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр обеспечивает использование только TLSv1.1 при использовании SSL для связи с сервером. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. См. также “ssl-min-ver” и ssl-max-ver.

force-tlsv12

force-tlsv12

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр обеспечивает использование только TLSv1.2 при использовании SSL для связи с сервером. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. См. также “ssl-min-ver” и ssl-max-ver.

force-tlsv13

force-tlsv13

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр обеспечивает использование только TLSv1.3 при использовании SSL для связи с сервером. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. См. также “ssl-min-ver” и ssl-max-ver.

guid <string>

guid <string>

Допустимые контексты: tcp, http, log

Задаёт глобально уникальный идентификатор с учётом регистра для этого сервера. Этот идентификатор должен быть уникальным во всей конфигурации HAProxy на всех типах объектов. См. описание ключевого слова “guid” прокси для получения дополнительной информации о его формате. См. также “shm-stats-file”.

hash-key <key>

hash-key <key>

Допустимые контексты: tcp, http, log

Задаёт способ вычисления ключей узлов для “hash-type consistent”

Аргументы:

<key>   <key> может принимать одно из следующих значений:

  id         Ключи узлов вычисляются из числового идентификатора сервера,
             заданного через "id" или по умолчанию равного его позиции
             в списке серверов. Это значение по умолчанию. Используются
             только 20 младших битов ID (то есть (id % 1048576)),
             поэтому во избежание пересечений лучше задавать значения
             от 1 до этого числа.

  id32       Ключи узлов вычисляются из числового идентификатора сервера,
             заданного через "id" или по умолчанию равного его позиции
             в списке серверов. Используются все 32 бита ID, чтобы
             исключить коллизии. В отличие от "id", значение
             не масштабируется, поэтому рекомендуется всегда применять
             его с хеш-функцией (см. "hash-key") либо с явно заданными
             ID, равномерно распределёнными по 32-битному пространству.

  guid       Ключи узлов вычисляются из guid сервера, если он есть;
             иначе используется "id". Преимущество — полная независимость
             от порядка: используется только внутренний стабильный
             идентификатор, который можно повторить на множестве
             балансировщиков нагрузки.

  addr       Ключи узлов вычисляются из адреса сервера, если он есть;
             иначе используется "id".

  addr-port  Ключи узлов вычисляются из адреса и порта сервера,
             если они доступны; иначе используется "id".

Опции “addr” и “addr-port” могут быть полезны в сценариях, когда несколько процессов HAProxy распределяют трафик между одним и тем же набором серверов. Если порядок серверов в каждом процессе отличается (например, из-за того, что DNS записи были разрешены в различных порядках), то это позволит независимым процессам HAProxy согласовывать решения по маршрутизации. Примечание: “balance random” также использует “hash-type consistent”, и качество распределения будет зависеть от качества ключей.

healthcheck <name>

healthcheck <name>

Допустимые контексты: tcp, http

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

Аргумент:

<name>    — имя секции healthcheck.

Параметр позволяет использовать отдельную конфигурацию проверки работоспособности для сервера вместо конфигурации прокси. См. также раздел о секции “healthcheck”.

id <value>

id <value>

Допустимые контексты: tcp, http, log

Установите постоянный идентификатор для сервера. Этот идентификатор должен быть положительным 32-битным числом и уникальным для прокси. Если идентификатор не задан, будет автоматически назначено свободное значение. Первое назначаемое значение будет 1. Этот идентификатор в настоящее время возвращается только в статистике и используется для размещения узлов балансировки нагрузки при использовании алгоритмов консистентного хэша, когда “hash-key” установлен в “id” (по умолчанию). В этом случае используются только 20 младших битов значения (то есть (id % 1048576)), поэтому лучше использовать значения, включенные в диапазон от 1 до этого значения, чтобы избежать пересечения.

idle-ping <delay>

idle-ping <delay>

Допустимые контексты: tcp, http, log

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

Для этой возможности требуется поддержка нижележащего протокола. Пока она реализована только в мультиплексоре H2. Остальные протоколы просто игнорируют idle-ping.

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

init-addr {last | libc | none | <ip>},[...]*

init-addr {last | libc | none | <ip>},[...]*

Допустимые контексты: tcp, http, log

Укажите порядок разрешения адреса сервера при запуске, если он использует FQDN. При попытке разрешения адреса применяются по очереди все методы, перечисленные в списке, разделённом запятыми. Первый метод, который успешно работает, используется. Если конец списка достигнут без нахождения рабочего метода, генерируется ошибка. Метод “last” означает выбор адреса, присутствующего в файле состояния (см. “server-state-file”). Метод “libc” использует внутренний разрешитель libc (gethostbyname() или getaddrinfo() в зависимости от операционной системы и опций сборки). Метод “none” явно указывает на то, что сервер должен запускаться без действительного IP-адреса в состоянии down. Это может быть полезно для игнорирования некоторых DNS проблем при запуске, ожидая, пока ситуация будет исправлена позже. Наконец, может быть указан IP-адрес (IPv4 или IPv6). Он может быть текущим известным адресом сервера (например, заполненным конфигурационным генератором) или адресом виртуального сервера, используемого для перехвата старых сессий и предоставления при этом уместного сообщения об ошибке. При использовании алгоритма балансировки нагрузки “first” такой IP-адрес может указывать на фейковый сервер, используемый для запуска новых экземпляров на лету. Эта опция по умолчанию равна “last,libc”, что означает, что сначала используется предыдущий адрес из файла состояния (если он есть), иначе используется разрешитель libc. Это обеспечивает совместимость с историческим поведением. При использовании внутренних разрешителей рекомендуется либо отключать разрешение на основе libc, либо делать это явно (см. раздел 5.3 для дополнительной информации).

Пример 1:

defaults
    # never fail on address resolution
    default-server init-addr last,libc,none

Пример 2:

defaults
    # disable libc resolution in combination with resolvers
    default-server init-addr last,none

inter <delay>

inter <delay>
fastinter <delay>
downinter <delay>

Допустимые контексты: tcp, http, log

Параметр “inter” устанавливает интервал между двумя последовательными проверками работоспособности в <delay> миллисекунд. Если не указан, задержка по умолчанию равна 2000 ms. Также возможно использовать «fastinter» и «downinter» для оптимизации задержек между проверками в зависимости от состояния сервера:

    Состояние сервера                                       | Используемый интервал
    --------------------------------------------------------+------------------------------
    UP 100% (устойчивое состояние)                          | "inter"
    --------------------------------------------------------+------------------------------
    Переходное UP (в сторону отказа, "fall"),               | "fastinter", если задан,
    переходное DOWN (в сторону восстановления, "rise"),     | иначе "inter".
    либо ещё не проверен.                                   |
    --------------------------------------------------------+------------------------------
    DOWN 100% (устойчивое состояние)                        | "downinter", если задан,
                                                            | иначе "inter".
    --------------------------------------------------------+------------------------------

Так же, как и для всех других параметров, зависящих от времени, они могут быть указаны в любой из явных единиц: { us, ms, s, m, h, d }. Параметр “inter” также служит тайм-аутом для проверок работоспособности, отправляемых серверам, если “timeout check” не задан. Чтобы снизить эффект “резонанса” при размещении нескольких серверов на одном оборудовании, запуск проверок через агента и обычных проверок работоспособности всех серверов производится с небольшим временным смещением между ними. Также возможно добавить некоторое случайное отклонение в интервалы проверок через агента и обычных проверок работоспособности с помощью глобального параметра “spread-checks”. Это имеет смысл, например, когда большое количество бэкендов использует одни и те же серверы. Глобальный параметр “tune.max-checks-per-thread”, если задан с ненулевым значением, ограничивает количество одновременно выполняемых проверок на любом из потоков. Для достижения этого HAProxy помещает в очередь проверки, которые планировались начать на потоке, достигшем этого предела, до тех пор, пока не завершится другая проверка. Это приведёт к увеличению эффективного интервала проверок. В таком случае сокращение параметра “inter” будет иметь очень ограниченное влияние, поскольку не сможет сократить время, затрачиваемое на ожидание в очереди.

init-state { fully-up | up | down | fully-down | none }

init-state { fully-up | up | down | fully-down | none }

Допустимые контексты: tcp, http

Допустимые секции: defaults | frontend | listen | backend нет | нет | да | да

Опция “init-state” устанавливает начальное состояние сервера: - при значении ‘fully-up’ сервер считается немедленно доступным и, если включены проверки работоспособности для этого сервера, он будет переключен в состояние DOWN при неудаче всех проверок работоспособности. - при значении ‘up’ сервер считается немедленно доступным и, если включены проверки работоспособности для этого сервера, он будет немедленно переключен в состояние DOWN при неудаче следующей проверки работоспособности. - при значении ‘down’ сервер считается изначально недоступным и, если включены проверки работоспособности для этого сервера, он может быть переключен в состояние UP при успешной следующей проверке работоспособности. - при значении ‘fully-down’ сервер считается изначально недоступным и, если включены проверки работоспособности для этого сервера, он будет переключен в состояние UP при успешности всех проверок работоспособности. - при значении ’none’ (по умолчанию), управление init-state отключено. Оно может использоваться для восстановления стандартного поведения, когда этот параметр наследовался от директивы ‘default-server’.

Когда HAProxy-экземпляр запускается (перезапускается), обнаруживается новый сервер (например, через обнаружение сервисов / разрешение имён DNS), динамический сервер включается, сервер выходит из режима технического обслуживания и т.д., используется директива сервера init-state. Эта директива не может использоваться, когда сервер отслеживает другой сервер.

Примеры:

# pass client traffic ONLY to Redis "master" node
backend redis-master
  mode tcp
  balance first
  option tcp-check
  tcp-check send role\r\n
  tcp-check expect string master
  server-template redis 3 _redis._tcp.redis-headless-service.sandbox.svc.cluster.local:6379 check ... init-state down

# pass traffic to the server only after 3 successful health checks
backend google-backend
  mode http
  server srv1 google.com:80 check init-state fully-down rise 3
  server srv2 google.com:80 check init-state fully-down rise 3

См. также: “option tcp-check”, “option httpchk”

ktls <on|off> [ EXPERIMENTAL ]

ktls <on|off> [ EXPERIMENTAL ]

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Включает или отключает ktls для этих сокетов. При включении kTLS будет использоваться, если ядро поддерживает kTLS и используемый шифр совместим. Доступно только на Linux 4.17 и выше. Примечание: некоторые сетевые драйверы и/или TLS стеки могут ограничивать использование kTLS только для TLS v1.2. См. также “force-tlsv12”.

log-bufsize <bufsize>

log-bufsize <bufsize>

Допустимые контексты: log

“log-bufsize” задаёт размер буфера неявного кольца, которое связывается с сервером журналов в бэкенде log. По умолчанию используется BUFSIZE. Большее значение увеличивает расход памяти, но может предотвратить потерю сообщений при медленных серверах, поскольку буфер вмещает больше ожидающих отправки сообщений. Ключевое слово допустимо только в секциях backend для журналов (с “mode log”).

log-proto <logproto>

log-proto <logproto>

Допустимые контексты: log, ring

“log-proto” задаёт протокол передачи сообщений о событиях серверу, настроенному в секции log или ring. Допустимы “legacy” и “octet-count”, соответствующие методам «непрозрачного разделения кадров» и «подсчёта октетов» в rfc6587. По умолчанию — “legacy”.

maxconn <maxconn>

maxconn <maxconn>

Допустимые контексты: tcp, http

Параметр “maxconn” указывает на максимальное количество одновременных соединений, которые будут отправлены на этот сервер. Если количество входящих одновременных соединений превышает указанное значение, они будут помещены в очередь и ожидать освобождения слота. Этот параметр очень важен, поскольку может предотвратить выход слабых серверов из строя под экстремальными нагрузками. Если указан параметр “minconn”, ограничение становится динамическим. Значение по умолчанию — “0”, что означает неограниченное количество. См. также параметры “minconn” и “maxqueue”, а также ключевое слово “fullconn” бэкенда.

В режиме HTTP этот параметр ограничивает количество одновременных запросов, а не количество соединений. Множественные запросы могут быть мультиплексированы через одно соединение TCP к серверу. Например, если вы укажете значение maxconn в виде 50, вы можете наблюдать от 1 до 50 фактических соединений с сервером, но не более чем 50 одновременных запросов.

maxqueue <maxqueue>

maxqueue <maxqueue>

Допустимые контексты: tcp, http

Параметр “maxqueue” задаёт максимальное количество соединений, которые будут ждать в очереди для этого сервера. Если это ограничение достигнуто, последующие запросы будут перенаправлены на другие серверы вместо бесконечного ожидания обслуживания. Это нарушит привязку сеанса, но может позволить пользователям быстро повторно войти, если сервер, к которому они пытаются подключиться, выходит из строя. Некоторые алгоритмы балансировки нагрузки, такие как leastconn, учитывают это и допускают добавление запросов в очередь сервера до указанного значения, если оно явно установлено в значение, превышающее ноль, что часто позволяет лучше сгладить нагрузку при работе с однозначными значениями maxconn. Значение по умолчанию — “0”, что означает отсутствие ограничения на очередь. См. также параметры “maxconn” и “minconn” и “balance leastconn”.

max-reuse <count>

max-reuse <count>

Может использоваться в следующих контекстах: http, ring

При использовании в контексте http:

Аргумент “max-reuse” указывает обработчикам соединений HTTP не использовать соединение с сервером повторно для новых запросов больше заданного числа раз. Допустимы -1 (по умолчанию), отключающее ограничение, и любое положительное значение. Ноль фактически отключает keep-alive. Параметр служит только для обхода ошибок серверов, приводящих к постепенной утечке ресурсов. Нижележащие уровни не обязательно соблюдают его из-за технических ограничений. По крайней мере соединения HTTP/2 с серверами это ограничение соблюдают.

При использовании в контексте ring:

Аргумент “max-reuse” указывает обработчикам соединений TCP приёмника не использовать соединение с сервером повторно для отправки сообщений больше заданного числа раз. Соединение принудительно закрывается после обработки в нём не менее “max-reuse + 1” сообщений, затем создаётся заново автоматически. При большом числе сообщений и многопоточной работе это помогает равномернее распределять нагрузку кольца между потоками. Каждое соединение привязано к одному потоку CPU на всё время существования: в отличие от HTTP, в syslog нет транзакций, поэтому соединение может жить неограниченно долго, пока сервер его не закроет или не произойдёт сетевая ошибка. Периодическое закрытие даёт другим потокам возможность по очереди обрабатывать сообщения. Это также может помочь плавно сменять серверы журналов, когда между ними и HAProxy есть дополнительный уровень балансировки нагрузки. Однако после каждого пересоздания соединения исходящий порт остаётся в TIME_WAIT и на современных ОС около минуты недоступен для повторного использования. Поэтому нельзя задавать слишком малые значения, чтобы быстро не исчерпать исходящие порты. Как правило, следует закрывать соединения не чаще нескольких раз в секунду, а лучше значительно реже. Допустимы -1 (по умолчанию), отключающее ограничение, и любое положительное значение. В отличие от HTTP, для серверов-приёмников “max-reuse” соблюдается по мере возможности: сообщения кольца обрабатываются пакетами, и ограничение проверяется между пакетами.

minconn <minconn>

minconn <minconn>

Допустимые контексты: tcp, http

При заданном “minconn” ограничение maxconn становится динамическим и зависит от нагрузки бэкенда. Сервер всегда допускает не менее <minconn> соединений и не более <maxconn>. Если в бэкенде меньше <fullconn> одновременных соединений, предел плавно растёт между этими значениями. Это ограничивает нагрузку на сервер в обычном режиме и позволяет повысить её при большой нагрузке, не перегружая сервер при исключительных пиках. См. также “maxconn”, “maxqueue” и ключевое слово бэкенда “fullconn”.

namespace <name>

namespace <name>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

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

no-agent-check

no-agent-check

Допустимые контексты: tcp, http, log

В строке “server” этот параметр позволяет сбросить настройку “agent-check”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “agent-check”.

no-backup

no-backup

Допустимые контексты: tcp, http, log

В строке “server” этот параметр позволяет сбросить настройку “backup”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “backup”.

no-check

no-check

Допустимые контексты: tcp, http, log

В строке “server” этот параметр позволяет сбросить настройку “check”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “check”.

no-check-reuse-pool

no-check-reuse-pool

Допустимые контексты: tcp, http

Отменяет ранее заданный “check-reuse-pool”, в том числе унаследованный из “default-server”. Каждая проверка выполняется через отдельное соединение.

no-check-sni-auto

no-check-sni-auto

Допустимые контексты: tcp, http, log

В строке “server” этот параметр позволяет отключить автоматический выбор SNI для проверок работоспособности через SSL. По умолчанию автоматический выбор включён.

См. опцию “no-sni-auto” для отключения автоматического выбора SNI для прокси-трафика.

no-check-ssl

no-check-ssl

Допустимые контексты: tcp, http, log

В строке “server” этот параметр позволяет сбросить настройку “check-ssl”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “check-ssl”.

no-renegotiate

no-renegotiate

Допустимые контексты: tcp, http, log

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он отключает механизмы повторного согласования SSL для указанного бэкенда: и устаревший небезопасный, и более новый безопасный (расширение TLS Renegotiation Indication, RFC 5746). Параметр также доступен в глобальной директиве “ssl-default-server-options”. В TLS 1.3 повторное согласование уже невозможно. Если не указан ни “renegotiate”, ни “no-renegotiate”, сохраняется поведение библиотеки SSL по умолчанию. Например, OpenSSL по умолчанию включает безопасное повторное согласование, а AWS-LC отключает. См. также “renegotiate”.

no-send-proxy

no-send-proxy

Допустимые контексты: tcp, http

В строке “server” этот параметр позволяет сбросить настройку “send-proxy”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “send-proxy”.

no-send-proxy-v2

no-send-proxy-v2

Допустимые контексты: tcp, http

В строке “server” этот параметр позволяет сбросить настройку “send-proxy-v2”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “send-proxy-v2”.

no-send-proxy-v2-ssl

no-send-proxy-v2-ssl

Допустимые контексты: tcp, http

В строке “server” этот параметр позволяет сбросить настройку “send-proxy-v2-ssl”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “send-proxy-v2-ssl”.

no-send-proxy-v2-ssl-cn

no-send-proxy-v2-ssl-cn

Допустимые контексты: tcp, http

В строке “server” этот параметр позволяет сбросить настройку “send-proxy-v2-ssl-cn”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “send-proxy-v2-ssl-cn”.

no-sni-auto

no-sni-auto

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

Этот параметр может быть использован как “server” настройка для отключения автоматического выбора SNI, включенного по умолчанию.

См. параметр “no-check-sni-auto” для отключения автоматического выбора SNI для проверки работоспособности SSL.

no-ssl

no-ssl

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

В строке “server” этот параметр позволяет сбросить настройку “ssl”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “ssl”.

Примечание: использование default-server ssl настройки и no-ssl на сервере инициализирует SSL соединение, поэтому его можно включить позже через runtime API: см. команды set server в документации по управлению.

no-ssl-reuse

no-ssl-reuse

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

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

no-sslv3

no-sslv3

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр отключает поддержку SSLv3 при использовании SSL для связи с сервером. Примечание, что SSLv2 отключён в коде и не может быть включён с помощью любого параметра конфигурации. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

Доступен в default-server: Нет

no-tls-tickets

no-tls-tickets

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только при сборке с поддержкой OpenSSL. Он отключает возобновление сеансов без хранения состояния (расширение TLS Ticket, RFC 5077) и принудительно включает возобновление с хранением состояния. Возобновление без хранения состояния требует больше ресурсов CPU на серверах. Параметр также доступен в глобальной директиве “ssl-default-server-options”. Механизм билетов TLS используется только до TLS 1.2 включительно. При использовании билетов TLS прямая секретность нарушается, если их ключи не заменяются регулярно (через перезагрузку конфигурации или с помощью “tls-ticket-keys”). См. также “tls-tickets”.

no-tlsv10

no-tlsv10

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр отключает поддержку TLSv1.0 при использовании SSL для связи с сервером. Примечание, что SSLv2 отключён в коде и не может быть включён с помощью любого параметра конфигурации. TLSv1 дороже, чем SSLv3, поэтому часто имеет смысл отключать его при связи с локальными серверами. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

Доступен в default-server: Нет

no-tlsv11

no-tlsv11

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр отключает поддержку TLSv1.1 при использовании SSL для связи с сервером. Примечание, что SSLv2 отключён в коде и не может быть включён с помощью любого параметра конфигурации. TLSv1 дороже, чем SSLv3, поэтому часто имеет смысл отключать его при связи с локальными серверами. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

Доступен в default-server: Нет

no-tlsv12

no-tlsv12

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр отключает поддержку TLSv1.2 при использовании SSL для связи с сервером. Примечание, что SSLv2 отключён в коде и не может быть включён с помощью любого параметра конфигурации. TLSv1 дороже, чем SSLv3, поэтому часто имеет смысл отключать его при связи с локальными серверами. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

Доступен в default-server: Нет

no-tlsv13

no-tlsv13

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр отключает поддержку TLSv1.3 при использовании SSL для связи с сервером. Примечание, что SSLv2 отключён в коде и не может быть включён с помощью любого параметра конфигурации. TLSv1 дороже, чем SSLv3, поэтому часто имеет смысл отключать его при связи с локальными серверами. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. Используйте “ssl-min-ver” и “ssl-max-ver” вместо этого.

Доступен в default-server: Нет

no-verifyhost

no-verifyhost

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

В строке “server” этот параметр позволяет сбросить настройку “verifyhost”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “verifyhost”.

no-tfo

no-tfo

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

В строке “server” этот параметр позволяет сбросить настройку “tfo”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “tfo”.

non-stick

non-stick

Допустимые контексты: tcp, http

Никогда не добавляет соединения, назначенные этому серверу, в stick-table. Может использоваться вместе с backup, чтобы отключить привязку сеансов по stick-table для резервных серверов.

npn <protocols>

npn <protocols>

Допустимые контексты: tcp, http

Включает расширение TLS NPN и объявляет через него указанный список поддерживаемых протоколов. Имена протоколов разделяются запятыми, например “http/1.1,http/1.0” (без кавычек). Библиотека SSL должна быть собрана с поддержкой расширений TLS (проверяется командой haproxy -vv). Расширение NPN заменено расширением ALPN (см. “alpn”), но последнее доступно только начиная с OpenSSL 1.0.2.

observe <mode>

observe <mode>

Допустимые контексты: tcp, http

Этот параметр включает корректировку состояния работоспособности по результатам наблюдения за обменом с сервером. По умолчанию данная функция отключена и для её включения необходимо также включить проверку работоспособности. Поддерживаются два режима: “layer4” и “layer7”. В режиме “layer4” значимы только успешные и неуспешные TCP-соединения. В режиме “layer7”, который допускается только для HTTP-прокси, проверяются ответы, получаемые от сервера, например, корректные/ошибочные HTTP-коды, заголовки, которые невозможно разобрать, тайм-аут и т.д. Корректные коды состояний включают 100 до 499, 501 и 505.

См. также “check”, “on-error” и “error-limit”.

on-error <mode>

on-error <mode>

Допустимые контексты: tcp, http, log

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

• fastinter: принудительно включить fastinter
• fail-check: имитировать неудачную проверку работоспособности, также принудительно включает fastinter (по умолчанию)
• sudden-death: имитировать неудачную проверку работоспособности перед критическим сбоем, один дополнительный неудачный результат проверки помечает сервер как выключенный, принудительно включает fastinter
• mark-down: немедленно помечает сервер как выключенный и принудительно включает fastinter

См. также “check”, “observe” и “error-limit”.

on-marked-down <action>

on-marked-down <action>

Допустимые контексты: tcp, http, log

Задаёт действие при переходе сервера в состояние недоступности. В настоящее время доступно одно действие:

• shutdown-sessions: Завершение потоков однорангового узла. При включении этого параметра все соединения с сервером немедленно прекращаются при выходе сервера из строя. Этот параметр может быть использован, если проверка работоспособности выявляет более сложные случаи, чем простое состояние соединения, и длительные тайм-ауты приводят к тому, что сервис остаётся неотвечаемым слишком долго. Например, проверка работоспособности может обнаружить, что база данных застряла, и уже невозможно использовать существующие соединения. Соединения, завершённые таким образом, логируются с кодом завершения ‘D’ (для “Down”).

Действия отключены по умолчанию

on-marked-up <action>

on-marked-up <action>

Допустимые контексты: tcp, http, log

Задаёт действие при переходе сервера в состояние доступности. В настоящее время доступно одно действие:

• shutdown-backup-sessions: Завершение потоков на всех резервных серверах. Это выполняется только если сервер не является резервным и не отключён (его эффективный вес > 0). Такое действие может быть использовано в некоторых случаях для принудительного возврата всего трафика на активный сервер после восстановления при работе с длительными сессиями (например, LDAP, SQL, …). Использование этой функции может привести к большему количеству проблем, чем оно решает (например, незавершённые транзакции), поэтому эта функция должна использоваться с крайней осторожностью. Потоки, завершённые из-за восстановления доступности сервера, логируются с кодом завершения ‘U’ (для “Up”).

Действия отключены по умолчанию

pool-conn-name <expr>

pool-conn-name <expr>

Допустимые контексты: http

При установке соединения с бэкендом это выражение вычисляется для формирования имени соединения. Имя — одно из ключевых свойств соединения в пуле простаивающих соединений с серверами. См. “http-reuse”. Когда для запроса ищется существующее простаивающее соединение, выражение вычисляется для поиска совпадения.

Если для соединения с бэкендом используется SSL SNI, имени соединения автоматически присваивается результат выражения “sni”. Это подходит для большинства случаев. Для более сложных конфигураций значение можно переопределить через “pool-conn-name”.

См. также: “http-reuse”, “sni”

pool-low-conn <max>

pool-low-conn <max>

Допустимые контексты: http

Задаёт нижний порог числа простаивающих соединений с сервером, ниже которого поток не пытается забрать соединение у другого потока. Это может улучшить использование CPU при работе со множеством очень быстрых серверов: каждый поток постоянно сохраняет несколько свободных соединений, вместо того чтобы они накапливались в одном потоке и перемещались между потоками. Типичное значение, равное удвоенному числу потоков, по-видимому, уже показывает очень хорошую производительность при времени ответа менее миллисекунды. По умолчанию используется ноль: любое простаивающее соединение можно использовать в любой момент. Это рекомендуемая настройка для обычной работы. Параметр относится только к соединениям, допускающим совместное использование по тем же принципам, что и “http-reuse”. Если совместное использование соединений между потоками отключено через “tune.idle-pool.shared”, параметр может быть особенно важен для сохранения нескольких соединений в каждом потоке. Иначе доля повторно используемых соединений снижается с ростом числа потоков.

pool-max-conn <max>

pool-max-conn <max>

Допустимые контексты: http

Задаёт максимальное число простаивающих соединений с сервером. -1 означает отсутствие ограничения, 0 — отсутствие таких соединений. По умолчанию — -1. Если простаивающие соединения разрешены, соединения, больше не принадлежащие ни одному клиентскому сеансу, перемещаются в отдельный пул для использования будущими клиентами. Это относится только к соединениям, допускающим совместное использование по тем же принципам, что и “http-reuse”.

pool-purge-delay <delay>

pool-purge-delay <delay>

Допустимые контексты: http

Задаёт задержку перед началом очистки простаивающих соединений. Через каждый интервал <delay> закрывается половина таких соединений. 0 означает, что простаивающие соединения не сохраняются. По умолчанию — 5s.

port <port>

port <port>

Допустимые контексты: tcp, http, log

Используя параметр “port”, становится возможным отправлять проверки работоспособности через другой порт или проводить пробы на agent-check. На некоторых серверах может быть желательно выделить порт для конкретного компонента, способного выполнять сложные тесты, более подходящие для проверок работоспособности, чем приложение. Обычно для этого запускают простой скрипт в inetd. Параметр игнорируется, если не задан параметр “check”. См. также параметр “addr”.

proto <name>

proto <name>

Допустимые контексты: tcp, http

Принудительно задаёт протокол мультиплексора для исходящих соединений с этим сервером. Протокол должен быть совместим с режимом бэкенда (TCP или HTTP) и пригоден для использования на стороне бэкенда. Список доступных протоколов выводит haproxy -vv. Для них указываются режим (TCP/HTTP), сторона (FE/BE), имя мультиплексора и его флаги.

Некоторые протоколы подвержены блокировке начала очереди на стороне сервера (flag=HOL_RISK). Некоторые не поддерживают смену протокола в существующем соединении (flag=NO_UPG). Также указывается совместимость с HTX (flag=HTX).

Здесь приведены протоколы, которые могут быть использованы в качестве аргумента директивы “proto” на строке сервера:

quic: mode=HTTP  side=FE|BE  mux=QUIC  flags=HTX|NO_UPG|FRAMED
qmux: mode=HTTP  side=FE|BE  mux=QMUX  flags=HTX|NO_UPG
h2  : mode=HTTP  side=FE|BE  mux=H2    flags=HTX|HOL_RISK|NO_UPG
fcgi: mode=HTTP  side=BE     mux=FCGI  flags=HTX|HOL_RISK|NO_UPG
h1  : mode=HTTP  side=FE|BE  mux=H1    flags=HTX|NO_UPG
none: mode=TCP   side=FE|BE  mux=PASS  flags=NO_UPG
spop: mode=SPOP  side=BE     mux=SPOP  flags=HOL_RISK|NO_UPG

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

Если настроены ALPN или NPN, указанные в них протоколы следует согласовать с протоколом мультиплексора, чтобы избежать проблем. Например, при “proto h1” не следует задавать ALPN “h2”.

См. также “ws” для использования альтернативного протокола для потоков WebSocket.

QMux — это подмножество QUIC, работающее над TCP. Оно соответствует следующему черновому протоколу https://www.ietf.org/archive/id/draft-ietf-quic-qmux-01.html . На данный момент считается экспериментальным в HAProxy.

quic-cc-algo { cubic | newreno | bbr | nocc }[(<args,...>)]

quic-cc-algo { cubic | newreno | bbr | nocc }[(<args,...>)]

Специальный параметр QUIC для выбора алгоритма управления перегрузкой для всех соединений с этим сервером. Эти алгоритмы аналогичны используемым в TCP. Полное описание настроек приведено у одноимённого параметра bind.

Значение по умолчанию: cubic

См. также: “tune.quic.be.tx.pacing” и “tune.quic.be.cc.max-win-size”

redir <prefix>

redir <prefix>

Допустимые контексты: http

Параметр “redir” включает режим перенаправления для всех запросов GET и HEAD, адресующих данный сервер. Это означает, что вместо того чтобы передавать запрос серверу, HAProxy отправляет ответ «HTTP 302» с заголовком «Location», состоящим из этого префикса, сразу за которым следует запрошенный URI начиная с ведущего ‘/’ компонента пути. Это означает, что после <prefix> не должен использоваться завершающий слэш. Все невалидные запросы будут отклонены, а все запросы, кроме GET и HEAD, будут нормально обрабатываться сервером. Примечание: поскольку ответ полностью синтезирован, в ответе невозможно изменять заголовки или вставлять куки. Однако куки в запросах всё ещё анализируются, что делает это решение полностью применимым для направления пользователей к удалённому месту в случае локальной катастрофы. Основное применение заключается в увеличении пропускной способности статических серверов за счёт прямого подключения клиентов к ним. Примечание: никогда не используйте относительный путь здесь, иначе возникнет цикл между клиентом и HAProxy!

Пример: server srv1 192.168.1.1:80 redir http://image1.mydomain.com check

renegotiate

renegotiate

Допустимые контексты: tcp, http, log

Этот параметр включает механизм безопасного повторного согласования (RFC 5746 TLS Расширение указания повторного согласования) для заданного бэкенда SSL. Это не означает, что клиент SSL будет отправлять запросы на повторное согласование, он лишь разрешает бэкендам проводить повторное согласование при запросе серверов. Требуется, чтобы лежащая в основе библиотека SSL фактически поддерживала повторное согласование. Этот параметр также доступен на глобальном уровне в операторе “ssl-default-server-options”. Повторное согласование больше невозможно в TLS 1.3. Если ни “renegotiate”, ни “no-renegotiate” не указаны, сохраняется поведение по умолчанию библиотеки SSL. Обратите внимание, что, например, библиотека OpenSSL включает безопасное повторное согласование по умолчанию, в то время как AWS-LC отключает его.

rise <count>

rise <count>

Допустимые контексты: tcp, http, log

Параметр “rise” указывает, что сервер будет считаться работоспособным после <count> успешных последовательных проверок работоспособности. Значение по умолчанию равно 2, если параметр не указан. См. также параметры “check”, “inter” и “fall”.

resolve-opts <option>,<option>,… Может быть использован в следующих контекстах: tcp, http, log

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

Доступные варианты:

• allow-dup-ip По умолчанию HAProxy запрещает дублирование адресов IP в бэкенде при выполнении разрешения DNS в режиме работы. Однако в некоторых случаях оправдано, чтобы два сервера (в одном бэкенде, разрешаемые одним FQDN) имели один и тот же адрес IP. В таком случае включите эту опцию. Это противоположность prevent-dup-ip.

• ignore-weight Игнорировать любое значение веса, установленное в записи SRV. Это полезно тогда, когда вы хотите управлять весами с помощью альтернативного метода, например, с помощью “agent-check” или через API времени выполнения.

• prevent-dup-ip Обеспечить соблюдение стандартного поведения HAProxy на сервере: предотвратить повторное использование адреса IP, уже присвоенного серверу в одном бэкенде и имеющего одинаковое полное имя домена. Это противоположность allow-dup-ip.

Пример:

backend b_myapp
  default-server init-addr none resolvers dns
  server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
  server s2 myapp.example.com:81 check resolve-opts allow-dup-ip

С опцией allow-dup-ip:

• если сервер имён возвращает один IP-адрес, тогда оба сервера будут использовать его
• Если сервер имён возвращает 2 IP-адреса, тогда каждый сервер будет использовать разный адрес

По умолчанию: не задано

resolve-prefer <family>

resolve-prefer <family>

Допустимые контексты: tcp, http, log

Когда включено разрешение DNS для сервера и возвращаются несколько адресов IP из разных семейств, HAProxy будет предпочтительно использовать адрес из семейства, указанного в параметре “resolve-prefer”. См. также глобальный параметр “dns-accept-family” для принудительного использования конкретного семейства. Доступные семейства: “ipv4” и “ipv6”.

Значение по умолчанию: ipv6

Пример:

server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6

resolve-net <network>[,<network[,...]]

resolve-net <network>[,<network[,...]]

Допустимые контексты: tcp, http, log

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

Пример:

server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8

resolvers <id>

resolvers <id>

Допустимые контексты: tcp, http, log

Указывает на существующую секцию “resolvers” для разрешения имени хоста текущего сервера. Часто рекомендуется отключать разрешение на основе libc при использовании разрешителей, хотя существуют исключения (см. раздел 5.3.1 ). В любом случае рекомендуется явно указывать “init-addr” при использовании разрешителей, чтобы не упустить этот элемент.

Пример:

server s1 app1.domain.com:80 init-addr last,none check resolvers mydns

См. также раздел 5.3 для деталей реализации и ловушек, на которые следует обратить внимание.

send-proxy

send-proxy

Допустимые контексты: tcp, http

Параметр “send-proxy” обеспечивает использование протокола PROXY при любом соединении, установленном с этим сервером. Протокол PROXY сообщает другой стороне об адресах уровня 3/4 входящего соединения, чтобы она могла узнать адрес клиента или публичный адрес, к которому он подключился, независимо от протокола верхнего уровня. Для соединений, принятых слушателем “accept-proxy” или “accept-netscaler-cip”, будет использоваться объявленный адрес. Поддерживаются только семейства адресов TCPv4 и TCPv6. Другие семейства, такие как Unix-сокеты, будут отображать семейство UNKNOWN. Серверы, использующие этот параметр, могут полностью быть связаны с другим экземпляром HAProxy, настроенным с параметром “accept-proxy”. Этот параметр не должен использоваться, если сервер не осведомлен о протоколе. При отправке проверок работоспособности на сервер, при наличии этого параметра, автоматически используется протокол PROXY, за исключением явного указания директивы “port” или “addr”, в случае чего потребуется также явная директива “check-send-proxy” для использования протокола PROXY. См. также параметр “no-send-proxy” данной секции и параметры “accept-proxy” и “accept-netscaler-cip” ключевого слова “bind”.

send-proxy-v2

send-proxy-v2

Допустимые контексты: tcp, http

Параметр “send-proxy-v2” обеспечивает использование версии протокола PROXY 2 при любом соединении, установленном с этим сервером. Протокол PROXY сообщает другой стороне об адресах уровня 3/4 входящего соединения, чтобы она могла узнать адрес клиента или публичный адрес, к которому он подключился, независимо от протокола верхнего слоя. Он также передаёт сведения об ALPN, если ALPN был согласован. Этот параметр не должен использоваться, если сервер не осведомлён об этой версии протокола. См. также опцию “no-send-proxy-v2” этой секции и опцию send-proxy ключевого слова “bind”.

set-proxy-v2-tlv-fmt(<id>) <fmt>

set-proxy-v2-tlv-fmt(<id>) <fmt>

Допустимые контексты: tcp, http

Параметр “set-proxy-v2-tlv-fmt” служит для отправки произвольных TLV протокола PROXY версии 2. Диапазоны определённых типов TLV (<id>) описаны в разделе 2.2.8 спецификации протокола PROXY. Значение можно выбирать свободно, если его длина не превышает 65,535 байт. Параметр также позволяет пересылать TLV: функция извлечения “fc_pp_tlv” получает TLV, принятый фронтендом. Параметр допустим в server и default-server. Для фактической отправки TLV PPv2 его необходимо сочетать с send-proxy-v2.

Пример: server srv1 192.168.1.1:80 send-proxy-v2 set-proxy-v2-tlv-fmt(0x20) %[fc_pp_tlv(0x20)]

В этом случае мы получаем TLV с типом 0x20 как строку и устанавливаем его в значение нового TLV, который также имеет тип 0x20.

proxy-v2-options <option>[,<option>]*

proxy-v2-options <option>[,<option>]*

Допустимые контексты: tcp, http

Параметр “proxy-v2-options” добавляет опции отправки в версии протокола PROXY 2 при использовании “send-proxy-v2”. Доступные опции:

• ssl : См. также “send-proxy-v2-ssl”.
• cert-cn : См. также “send-proxy-v2-ssl-cn”.
• ssl-cipher: Название используемого шифра.
• cert-sig : Алгоритм подписи используемого сертификата.
• cert-key : Алгоритм ключа используемого сертификата
• authority: Значение имени хоста, переданное клиентом (поддерживаются только SNI из соединения TLS).
• crc32c : Контрольная сумма заголовка PROXYv2.
• unique-id: Передача уникального идентификатора, сгенерированного с помощью “unique-id-format” фронтенда в заголовке PROXYv2. Уникальный идентификатор в первую очередь предназначен для “mode tcp”. Он может привести к непредвиденным результатам в “mode http”, поскольку сгенерированный уникальный идентификатор также используется для первого запроса HTTP в соединении Keep-Alive.

send-proxy-v2-ssl

send-proxy-v2-ssl

Допустимые контексты: tcp, http

Параметр “send-proxy-v2-ssl” обеспечивает использование версии протокола PROXY 2 при любом соединении, установленном с этим сервером. Протокол PROXY сообщает другой стороне об адресах уровня 3/4 входящего соединения, чтобы она могла узнать адрес клиента или публичный адрес, к которому он подключился, независимо от протокола верхнего слоя. Кроме того, в заголовок протокола PROXY добавляется расширение информации SSL протокола PROXY. Этот параметр нельзя использовать, если сервер не осведомлён об этой версии протокола. См. также опцию “no-send-proxy-v2-ssl” этой секции и опцию “send-proxy-v2” ключевого слова “bind”.

send-proxy-v2-ssl-cn

send-proxy-v2-ssl-cn

Допустимые контексты: tcp, http

Параметр “send-proxy-v2-ssl” обеспечивает использование версии протокола PROXY 2 при любом соединении, установленном с этим сервером. Протокол PROXY сообщает другой стороне об адресах уровня 3/4 входящего соединения, чтобы она могла узнать адрес клиента или публичный адрес, к которому он обращался, независимо от протокола верхнего слоя. Кроме того, расширение информации SSL протокола PROXY, а также общее имя (Common Name) из субъекта сертификата клиента (если имеется), добавляется в заголовок протокола PROXY. Этот параметр нельзя использовать, если сервер не осведомлён об этой версии протокола. См. также опцию “no-send-proxy-v2-ssl-cn” этой секции и опцию “send-proxy-v2” ключевого слова “bind”.

shard <shard>

shard <shard>

Допустимые контексты: peers

Параметр используется только при синхронизации stick-table по протоколу peers. “shard” определяет узлы, получающие все обновления stick-table для ключей, чей хеш распределения соответствует этому шарду. Допустимы значения от 0 до значения “shards” в секции “peers”. По умолчанию используется 0: узел получает обновления всех ключей. Значения больше “shards” игнорируются, как и любые значения, заданные локальному узлу.

Пример:

peers mypeers
     shards 3
     peer A 127.0.0.1:40001 # local peer without shard value (0 internally)
     peer B 127.0.0.1:40002 shard 1
     peer C 127.0.0.1:40003 shard 2
     peer D 127.0.0.1:40004 shard 3

sigalgs <sigalgs>

sigalgs <sigalgs>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только тогда, когда поддержка OpenSSL была включена. Устанавливает строку, описывающую список алгоритмов подписи, согласовываемых во время рукопожатия TLSv1.2 и TLSv1.3. Формат строки определён в “man 3 SSL_CTX_set1_sigalgs” из справочной документации OpenSSL. Не рекомендуется использовать этот параметр, если не требуется совместимость с промежуточным устройством.

slowstart <start_time_in_ms>

slowstart <start_time_in_ms>

Допустимые контексты: tcp, http

Параметр “slowstart” для сервера принимает значение в миллисекундах, указывающее, через какое время сервер, только что вернувшийся в работу, начнёт функционировать на полной скорости. Как и для любого другого параметра, зависящего от времени, его можно указать в любой другой явной единице измерения: { us, ms, s, m, h, d }. Скорость увеличивается линейно от 0 до 100% в течение этого времени. Ограничение применяется к двум параметрам:

• maxconn: количество принятых сервером соединений будет расти от 1 до 100% обычного динамического предела, определенного выражением (minconn,maxconn,fullconn).

• weight: при использовании бэкендом динамического алгоритма с весом, вес растёт линейно от 1 до 100%. В этом случае вес обновляется при каждой проверке работоспособности. Поэтому важно, чтобы параметр “inter” был меньше чем “slowstart”, чтобы максимизировать количество шагов.

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

sni <expression>

sni <expression>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Параметр “sni” вычисляет выражение извлечения данных, преобразует результат в строку и использует её как имя узла, отправляемое серверу в расширении TLS SNI. Типичный случай — передать SNI клиента при работе HAProxy мостом TCP/SSL, используя в выражении функцию “ssl_fc_sni”. ЭТО НЕЛЬЗЯ ИСПОЛЬЗОВАТЬ ДЛЯ HTTPS: вместо этого следует использовать req.hdr(host), поскольку в HTTPS SNI обязательно должно совпадать с полем Host, а клиентам разрешено использовать разные имена узлов в одном соединении. Если задано “verify required” (рекомендуемая настройка), полученное имя также проверяется на соответствие именам в сертификате сервера. Подробнее см. “verify”. Для задания SNI проверок работоспособности служит “check-sni”.

По умолчанию, SNI присваивается имени соединения для “http-reuse”, если не переопределено директивой “pool-conn-name” сервера.

sni-auto

sni-auto

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Параметр “sni-auto” включает автоматический выбор SNI, если значение ещё не задано. Он задаёт выражение “sni” как “req.hdr(host),field(1,:)”, то есть передаёт в SNI имя Host запроса, отправляемого серверу, без номера порта. Автоматический выбор включён по умолчанию, но параметр в строке “server” позволяет сбросить “no-sni-auto”, унаследованный из “default-server”. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “no-sni-auto”.

Для HTTPS соединений выбранный SNI определяется на основе значения заголовка host запроса, если он присутствует. В противном случае он остаётся неустановленным. Для других протоколов опция игнорируется.

Если используется автоматическое определение SNI, то значение присваивается имени соединения для “http-reuse”, за исключением случая, когда это перекрывается ключевым словом “pool-conn-name” сервера.

См. опцию “check-sni-auto” для включения автоматического выбора SNI при проверке работоспособности для SSL.

source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]

source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
source <addr>[:<pl>[-<ph>]] [interface <name>] ...

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

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

Кроме того, утверждение “source” на строке сервера позволяет указать диапазон исходных портов, задавая нижнюю и верхнюю границы, разделённые дефисом (’-’). Некоторые операционные системы могут требовать действительный IP-адрес при указании диапазона исходных портов. Разрешено указывать один и тот же IP/диапазон для нескольких серверов. Это позволяет обойти ограничение в 64 тыс. одновременных соединений. Ограничение в этом случае достигнет 64 тыс. соединений на каждый сервер.

Начиная с Linux 4.2/libc 2.23, для соединений с заданным исходным адресом без портов устанавливается IP_BIND_ADDRESS_NO_PORT.

ssl

ssl

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Эта опция включает SSL шифрование на исходящих соединениях к серверу. Критически важно проверять сертификаты сервера с помощью “verify” при использовании SSL для подключения к серверам, иначе обмен уязвим к простым атакам «человек посередине», что делает SSL бесполезным. При использовании этой опции проверки работоспособности автоматически отправляются в SSL, если нет директивы “port” или “addr”, указывающей на то, что проверка должна быть направлена в другое место. См. “no-ssl” для отключения опции “ssl” и опцию “check-ssl” для принудительной отправки проверок работоспособности в SSL.

ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр обеспечивает использование <version> или ниже при использовании SSL для связи с сервером. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. См. также “ssl-min-ver”.

ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр обеспечивает использование <version> или выше при использовании SSL для связи с сервером. Этот параметр также доступен в глобальной директиве “ssl-default-server-options”. См. также “ssl-max-ver”.

ssl-reuse

ssl-reuse

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

В строке “server” этот параметр позволяет сбросить настройку “no-ssl-reuse”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “no-ssl-reuse”.

stick

stick

Допустимые контексты: tcp, http

В строке “server” этот параметр позволяет сбросить настройку “non-stick”, унаследованную из директивы “default-server” как значение по умолчанию. В директиве “default-server” он также может сбросить предыдущую настройку “default-server” “non-stick”.

strict-maxconn

strict-maxconn

Допустимые контексты: tcp, http

Название maxconn для серверов не вполне точно: параметр задаёт максимальное число отправляемых серверу запросов, но с учётом простаивающих соединений общее число соединений может быть больше. Если требуется строгий предел числа соединений с сервером, можно добавить strict-maxconn. Тогда HAProxy никогда не устанавливает больше maxconn соединений с сервером и при необходимости пытается повторно использовать или закрывать соединения. Однако запросы могут завершаться ошибкой, если новое соединение установить нельзя, а простаивающего нет. Это возможно при «частных» соединениях, закреплённых за одним сеансом после аутентификации.

socks4 <addr>:<port>

socks4 <addr>:<port>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр включает туннели socks4 для исходящих соединений с сервером. Использование данного параметра не будет по умолчанию заставлять проверку работоспособности проходить через socks4. Для включения функции необходимо использовать ключевое слово “check-via-socks4”.

tcp-md5sig <password>

tcp-md5sig <password>

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

Включает подпись TCP MD5 (RFC 2385 Защита BGP Сессий через опцию подписи TCP MD5) для всех исходящих соединений с этим сервером. Эта опция доступна только на Linux. При включении, строка <password> используется для подписи каждого TCP сегмента с помощью 16-байтового MD5 хэша. Это обеспечивает защиту TCP соединения от подделки. Основное применение этой опции — защита BGP от введения фальшивых TCP сегментов в поток соединения. Однако она может быть полезна для любых очень длительных TCP соединений.

tcp-ut <delay>

tcp-ut <delay>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Устанавливает тайм-аут пользователя TCP для всех исходящих соединений с этим сервером. Этот параметр доступен в Linux начиная с версии 2.6.37. Он позволяет HAProxy настроить тайм-аут для сокетов, содержащих данные, не получающие подтверждения в течение заданного промежутка времени. Это особенно полезно для долговременных соединений с длительными периодами бездействия, таких как удалённые терминалы или пулы соединений с базами данных, где тайм-ауты клиента и сервера должны быть высокими для обеспечения длительного периода бездействия, но при этом важно обнаруживать исчезновение сервера с целью освобождения всех ресурсов, связанных с его соединением (и сессией клиента). Один из типичных сценариев использования — принудительное завершение соединений с недоступным сервером при слишком медленных проверках работоспособности или во время плавной перезагрузки, поскольку при этом проверки работоспособности отключаются. Аргумент — задержка, выраженная в миллисекундах по умолчанию. Работает только для обычных TCP соединений и игнорируется для других протоколов.

tfo

tfo

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр включает использование TCP fast open при подключении к серверам на системах, поддерживающих его (на данный момент — только ядро Linux >= 4.11). Дополнительную информацию о TCP fast open см. в опции “tfo” bind. Обратите внимание, что при использовании tfo следует также использовать ключевые слова “conn-failure”, “empty-response” и “response-timeout” для “retry-on”, иначе HAProxy не сможет повторно подключаться при сбое. См. также “no-tfo”.

track [<backend>/]<server>

track [<backend>/]<server>

Допустимые контексты: tcp, http, log

Этот параметр позволяет устанавливать текущее состояние сервера путём отслеживания другого сервера. Можно отслеживать сервер, который сам отслеживает другой сервер, при условии, что в конце цепочки сервер имеет включённые проверки работоспособности. Если <backend> не указан, используется текущий бэкенд. Если используется disable-on-404, то этот параметр должен быть включён на обоих прокси.

Пример:

backend A
server a1 1.1.1.1:80 track B/b1
server a2 1.1.1.2:80 track B/b1

backend B
server b1 2.2.2.2:80 check

tls-tickets

tls-tickets

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

В строке “server” этот параметр позволяет сбросить “no-tls-tickets”, унаследованный из “default-server” как значение по умолчанию. Механизм билетов TLS используется только до TLS 1.2 включительно. При использовании билетов TLS прямая секретность нарушается, если ключи билетов не заменяются регулярно (через перезагрузку конфигурации или с помощью “tls-ticket-keys”). В директиве “default-server” параметр также может сбросить предыдущую настройку “default-server” “no-tls-tickets”.

verify [none|required]

verify [none|required]

Может быть использован в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только при сборке с поддержкой OpenSSL. При значении ’none’ сертификат сервера не проверяется. В противном случае сначала проверяется, соответствуют ли имена в атрибутах subject и subjectAlternateNames сертификата имени из “sni” либо, при его отсутствии, статическому имени из “verifyhost”. Затем сертификат проверяется с помощью CA из ‘ca-file’ и необязательных списков отзыва CRL из ‘crl-file’. Если имя для проверки не задано, имена сертификата игнорируются. Поэтому без SNI важно использовать “verifyhost”. При неудаче проверки рукопожатие прерывается. При подключении к серверам через SSL критически важно проверять их сертификаты: иначе обмен уязвим к простым атакам «человек посередине», что делает SSL совершенно бесполезным. Если в секции global не указан “ssl_server_verify”, по умолчанию “verify” имеет значение “required”.

verifyhost <hostname>

verifyhost <hostname>

Может использоваться в следующих контекстах: tcp, http, log, peers, ring

Этот параметр доступен только при сборке с поддержкой OpenSSL и действует лишь при ‘verify required’. Он задаёт статическое имя узла по умолчанию для проверки сертификата сервера, если при подключении не использовался SNI. Без SNI это единственный способ включить проверку имени узла. Заданное статическое имя используется и для проверок работоспособности, если они не передают значение SNI. Если ни одно имя в сертификате не совпадает с указанным, рукопожатие прерывается. Имена в сертификате сервера могут содержать подстановочные знаки. См. также “verify”, “sni” и “no-verifyhost”.

weight <weight>

weight <weight>

Допустимые контексты: tcp, http

Параметр “weight” используется для настройки веса сервера по сравнению с другими серверами. Все серверы получают нагрузку пропорционально их весу относительно суммы всех весов, поэтому чем выше вес, тем выше нагрузка. По умолчанию вес равен 1, а максимальное значение — 256. Значение 0 означает, что сервер не участвует в балансировке нагрузки, но по-прежнему принимает соединения, направленные на него механизмом привязки сеансов. Если этот параметр используется для распределения нагрузки в соответствии с возможностями сервера, рекомендуется начинать с значений, которые могут как увеличиваться, так и уменьшаться, например, в диапазоне от 10 до 100, чтобы оставить достаточный запас как сверху, так и снизу для последующих корректировок.

ws { auto | h1 | h2 }

ws { auto | h1 | h2 }

Допустимые контексты: http

Этот параметр позволяет настроить протокол, используемый при пересылке потоков WebSocket. Это особенно полезно при использовании бэкенда HTTP/2 без поддержки WebSocket H2 через RFC8441.

По умолчанию используется “auto”: применяется тот же протокол, что и для основного трафика. Исключение — ALPN: для потоков WebSocket возможна попытка перейти на “http/1.1”, если этот протокол есть в настроенном списке ALPN сервера.

Значение “h1” используется для принудительного задания HTTP/1.1 для потоков WebSocket, через ALPN если SSL ALPN включено для сервера. Аналогично, “h2” может быть использован для принудительного задания HTTP/2.0 WebSocket. Используйте это значение с осторожностью: сервер должен поддерживать RFC8441 или при пересылке WebSocket HAProxy выдаст ошибку.

Примечание, что NPN не учитывается, так как его использование было отменено в пользу расширения ALPN

См. также “alpn” и “proto”.

5.3. Определение IP-адреса сервера через DNS

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

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

Независимо от того, включено ли разрешение имени сервера в режиме работы, по умолчанию HAProxy выполняет первое разрешение при запуске во время парсинга конфигурации через libc, если не отключено параметром “init-addr”.

5.3.1. Общий обзор

Как показано во введении, разрешение имени в HAProxy происходит на двух разных этапах жизненного цикла процесса:

1. При запуске HAProxy разбирает строку определения сервера и обнаруживает
   имя узла. Для его разрешения используются функции libc. Такое разрешение
   опирается на файл /etc/resolv.conf.

2. Во время работы HAProxy периодически разрешает имена серверов,
   которым требуется разрешение DNS.

Несколько других событий могут инициировать разрешение имени в режиме работы:

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

При использовании резолверов имя сервера может быть либо именем хоста, либо меткой SRV. HAProxy считает всё, что начинается с подчёркивания, меткой SRV. Если указана метка SRV, то соответствующие записи SRV будут получены с сервера DNS, а указанные имена хостов будут использоваться. Метка SRV будет проверяться периодически, и при добавлении или удалении серверов HAProxy автоматически выполнит аналогичные действия.

Несколько важных моментов, на которые следует обратить внимание:

• все серверы имён опрашиваются одновременно. HAProxy обрабатывает первый валидный ответ.

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

• Клиент DNS, реализованный в HAProxy, является очень простым и не сможет понять большое количество опций и сложных настроек, которые может обрабатывать резолвер операционной системы. Следовательно, за исключением действительно простых конфигураций, в которых сервер, известный только по своему FQDN, имеет ровно один IP-адрес в любой момент времени и может периодически обновлять его (например, после перезагрузки), настоятельно рекомендуется избегать смешивания разрешения имён на этапе инициализации, основанного на библиотеке libc, с разрешением во время выполнения, основанным на DNS. Такие конфигурации известны своей склонностью к сбоям при обновлении адресов. В заключение, если вы не уверены в том, что делаете, всегда следует исключать “libc” из “init-addr” при использовании “resolvers” в строке сервера.

5.3.2. Секция resolvers

В этой секции хранится информация, связанная с разрешением имён в HAProxy. Секций resolvers может быть столько, сколько необходимо; каждая может содержать несколько серверов имён.

При запуске HAProxy пытается сгенерировать секцию resolvers, названную “default”, если в конфигурации нет секции с таким названием. Эта секция по умолчанию используется httpclient и использует ключевое слово parse-resolv-conf. Если HAProxy не может автоматически сгенерировать эту секцию, не выдается ни ошибки, ни предупреждения.

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

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

1. HAProxy повторяет тот же запрос DNS с другим типом: A меняется
   на AAAA и наоборот. Это не относится к запросам SRV и ошибкам
   тайм-аута.

2. После переключения типа запроса (или если оно неприменимо) HAProxy
   повторяет исходный запрос DNS с предпочтительным типом.

3. HAProxy повторяет предыдущие шаги <resolve_retries> раз. Если после
   этого действительный ответ не получен, разрешение DNS прекращается
   и сообщается об ошибке.

Например, при настройке 2 серверов в секции resolvers, возможны следующие сценарии:

• Первый ответ является действительным и применяется немедленно, второй ответ игнорируется

• Первый ответ является недействительным, второй — действительным, затем применяется второй ответ

• Первый ответ — NX домен, второй — обрезанный ответ, затем HAProxy повторяет запрос с новым типом

• Первый ответ — NX домен, второй — тайм-аут, затем HAProxy повторяет запрос с новым типом

• Запрос истек по тайм-ауту для обоих серверов, затем HAProxy повторяет запрос с тем же типом запроса

Поскольку DNS сервер может не отвечать на все IP в одном DNS запросе, HAProxy хранит кэш предыдущих ответов, ответ считается устаревшим после <hold obsolete> секунд без возврата IP.

resolvers <resolvers id>

resolvers <resolvers id>

Создаёт список серверов имён с меткой <resolvers id>. Как указано выше, специальное имя “default” существует всегда: секция создаётся автоматически, если не объявлена явно. Именно на неё опираются внутренние службы, например httpclient. Объявление “default” влияет на разрешение имён этими службами.

Секция resolvers принимает следующие параметры:

accepted_payload_size <nb>

accepted_payload_size <nb>

Определяет максимальный размер полезной нагрузки, который принимается HAProxy и объявляется всем серверам имен, настроенным в этой секции разрешителей. <nb> измеряется в байтах. Если не задано, HAProxy объявляет 512. (минимальное значение, определённое RFC 6891)

Примечание: максимально допустимое значение — 65535. Рекомендуемое значение для UDP — 4096, и не рекомендуется превышать 8192, за исключением случаев, когда вы уверены, что ваша система и сеть способны справиться с этим (значение, превышающее 65507, не имеет смысла, поскольку это максимальный размер полезной нагрузки UDP). Если вы используете только TCP серверы имен для обработки больших DNS ответов, следует установить это значение на максимум: 65535.

nameserver <name> <address>[:port] [param*]

nameserver <name> <address>[:port] [param*]

Используется для настройки сервера имён. Имя <name> сервера имён должно быть уникальным. По умолчанию <address> считается типом датаграммы. Это означает, что при настройке IPv4 или IPv6 без специальных префиксов адресов (параграф 11) будет использоваться протокол UDP. Если используется префикс адреса потокового протокола, сервер имён будет считаться потоковым сервером (TCP, например), и параметры “server”, указанные в параграфе 5.2, которые относятся к разрешению DNS, будут учитываться.

Примечание: в настоящее время в режиме TCP 4 запроса отправляются конвейером по одному соединению. Каждые 5 секунд закрывается группа простаивающих соединений. Параметр “maxconn” можно настроить для ограничения количества одновременных соединений. Также должна быть возможность использовать TLS, если сервер его поддерживает.

parse-resolv-conf

parse-resolv-conf

Добавляет все серверы имён из /etc/resolv.conf в список серверов этой секции resolvers. Порядок такой, как если бы каждый сервер из /etc/resolv.conf был отдельно указан на месте этой директивы.

hold <status> <period>

hold <status> <period>

После получения ответа DNS со статусом <status> определяет, нужно ли перевести сервер из UP в DOWN. Для этого проверяет, приходил ли действительный ответ за последние <period>, который позволил бы проигнорировать только что полученный недействительный статус.

`<status>`: последний статус разрешения имени.
       nx        После NXDOMAIN проверяется, был ли действительный
                 ответ за прошедший заданный период.

       refused   После REFUSED проверяется, был ли действительный
                 ответ за прошедший заданный период.

       timeout   После истечения "timeout retry" проверяется, был ли
                 действительный ответ за прошедший заданный период.

       other     После любого другого недействительного статуса
                 проверяется, был ли действительный ответ
                 за прошедший заданный период.

       valid     Применяется только к действиям "http-request do-resolve"
                 и "tcp-request content do-resolve". Задаёт время хранения
                 действительного ответа сервером до нового разрешения.
                 Не влияет на динамическое разрешение имён серверов.

       obsolete  Задаёт время ожидания перед удалением устаревших записей
                 DNS после получения обновлённой записи ответа.
                 Применяется к записям SRV.

`<period>`: прошедший период, за который должен быть получен действительный
           ответ. Используется формат времени HAProxy; по умолчанию
           значение указывается в миллисекундах.

Если сервер определяет свой IP-адрес через динамическое разрешение DNS, недействительный ответ, например NXDOMAIN, приводит к переходу из UP в DOWN. Директивы hold задают, насколько далеко в прошлое искать действительный ответ. Если такой ответ получен в течение <period>, только что полученный недействительный статус игнорируется.

Если за прошедший заданный период действительный ответ не получен, сервер помечается DOWN. Например, при “hold nx 30s” и последнем ответе NXDOMAIN сервер перейдёт в DOWN, если за последние 30 секунд не было действительного ответа.

Сервер в состоянии DOWN будет немедленно помечен как UP при получении допустимого статуса от сервера DNS.

Существует отдельное поведение для “hold valid” и “hold obsolete”.

По умолчанию для “valid” используется 10s, для “obsolete” — 0s, для остальных — 30s.

resolve_retries <nb>

resolve_retries <nb>

Определяет количество <nb> запросов, которые необходимо отправить для разрешения имени сервера, прежде чем отказаться. Значение по умолчанию: 3

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

timeout <event> <time>

timeout <event> <time>

Определяет тайм-ауты, связанные с разрешением имен <event>: событие, на котором применяется период тайм-аута <time>. Доступные события: - resolve: время, при котором запускается разрешение имен, если не применяется другое время. Значение по умолчанию: 1s - retry : время между двумя DNS запросами, если не получены действительные ответы. Значение по умолчанию: 1s <time>: время, связанное с событием. Оно следует формату времени HAProxy. <time> выражено в миллисекундах.

Пример:

resolvers mydns
  nameserver dns1 10.0.0.1:53
  nameserver dns2 10.0.0.2:53
  nameserver dns3 tcp@10.0.0.3:53
  parse-resolv-conf
  resolve_retries       3
  timeout resolve       1s
  timeout retry         1s
  hold other           30s
  hold refused         30s
  hold nx              30s
  hold timeout         30s
  hold valid           10s
  hold obsolete        30s