12. Другие секции

Секции, описанные ниже, реже используются и обычно поддерживают лишь несколько параметров. Между ними нет неявной связи. Они все начинаются с одного ключевого слова. Ни одна из них не допускается до секции “global”. Поддержка некоторых из них может зависеть от опций сборки (например, что касается SSL).

12.1. Трассировка

Для отладки можно включить трассировку подсистемы HAProxy. При этом выводятся отладочные сообщения об определённой подсистеме. Это мощное средство диагностики проблем. Трассировку можно динамически настраивать через CLI. Некоторые параметры также можно заранее задать в файле конфигурации, в отдельных секциях “traces”. Подробнее о трассировке см. руководство по управлению. Это инструмент разработчика для сложных сеансов отладки. Он выводит много сообщений и требует дополнительных ресурсов, поэтому используйте его осторожно. Поскольку это инструмент разработчика, обратная совместимость этой секции не гарантируется.

traces

traces

Начинает новую секцию traces. Одна или несколько секций “traces” могут быть использованы. Все директивы оцениваются в порядке объявления, последующие перекрывают предыдущие.

trace <source> <args...>

trace <source> <args...>

Настраивает подсистему “trace”. Каждая из них может быть найдена в руководстве по управлению и соответствует идентичной синтаксису. Любое выведение, которое бы произвело команда “trace”, будет выведено во время этапа парсинга секции. Чаще всего это будут ошибки и предупреждения, но некоторые неполные команды могут перечислить допустимые варианты. Эта команда не предназначена для обычного использования, она будет рекомендована разработчикам только в ходе сложных сессий отладки. Важно помнить, что в зависимости от уровня трассировки и детализации, включение трассировок может серьёзно снизить глобальную производительность. См. руководство по управлению для синтаксиса команд.

Пример:

ring buf1
  size 10485760 # 10MB
  format timed
  backing-file /tmp/h1.traces

ring buf2
  size 10485760 # 10MB
  format timed
  backing-file /tmp/h2.traces

traces
  trace h1 sink buf1 level developer verbosity complete start now
  trace h2 sink buf1 level developer verbosity complete start now

12.2. Списки пользователей

Возможно, контролировать доступ к frontend/backend/listen секциям или к статистике HTTP, разрешая только авторизованным и авторизованным пользователям. Для этого необходимо создать хотя бы один пользовательский список и определить пользователей.

userlist <listname>

userlist <listname>

Создаёт новый пользовательский список с именем <listname>. Множество независимых пользовательских списков может быть использовано для хранения данных аутентификации и авторизации для независимых клиентов.

group <groupname> [users <user>,<user>,(...)]

group <groupname> [users <user>,<user>,(...)]

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

user <username> [password|insecure-password <password>]

user <username> [password|insecure-password <password>]
                [groups <group>,<group>,(...)]

Добавляет пользователя <username> в текущий список пользователей. Можно использовать как зашифрованные (зашифрованные), так и незашифрованные (нешифрованные) пароли. Зашифрованные пароли оцениваются с помощью функции crypt(3), поэтому в зависимости от возможностей системы могут поддерживаться различные алгоритмы. Например, современные системы Linux на базе Glibc поддерживают MD5, SHA-256, SHA-512 и, конечно, классический метод шифрования паролей на основе DES.

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

Чтобы снизить высокое использование хэш-функций CPU, одним из подходов является уменьшение числа итераций хэш-функции (алгоритмы SHA) или сокращение «стоимости» функции, если это возможно.

Как примечание, реализации musl (например, Alpine Linux) известны тем, что при расчёте хэшей они медленнее, чем их аналоги на glibc, поэтому стоит также учитывать этот аспект.

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

Пример:

userlist L1
  group G1 users tiger,scott
  group G2 users xdb,scott

  user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
  user scott insecure-password 'elgato'
  user xdb insecure-password 'hello'

userlist L2
  group G1
  group G2

  user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
  user scott insecure-password 'elgato' groups G1,G2
  user xdb insecure-password 'hello' groups G2

Примечание, что оба списка функционально идентичны.

12.3. Почтовые серверы

Возможно, отправлять электронные письма при изменении состояния серверов. Если настроены электронные уведомления, они отправляются каждому получателю, указанному в секции mailers. Электронные письма отправляются получателям через Lua (см. examples/lua/mailers.lua).

mailers <mailersect>

mailers <mailersect>

Создаёт новый список рассылки с именем <mailersect>. Это независимая секция, которая ссылается на один или более прокси.

mailer <mailername> <ip>:<port>

mailer <mailername> <ip>:<port>

Определяет почтового отправителя внутри секции почтовых отправителей.

Пример:

global
    # mailers.lua file as provided in the git repository
    # adjust path as needed
    lua-load examples/lua/mailers.lua

mailers mymailers
    mailer smtp1 192.168.0.1:587
    mailer smtp2 192.168.0.2:587

backend mybackend
    mode tcp
    balance roundrobin

    email-alert mailers mymailers
    email-alert from test1@horms.org
    email-alert to test2@horms.org

    server srv1 192.168.0.30:80
    server srv2 192.168.0.31:80

timeout mail <time>

timeout mail <time>

Определяет время, доступное для установления соединения и передачи письма на сервер. Если не определено, значение по умолчанию — 10 секунд. Для обеспечения передачи как минимум двух SYN-ACK пакетов в ходе инициализации TCP рукопожатия рекомендуется сохранять это значение выше 4 секунд.

Пример:

mailers mymailers
    timeout mail 20s
    mailer smtp1 192.168.0.1:587

12.4. Ошибки HTTP

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

http-errors <name>

http-errors <name>

Создайте новую группу http-errors с именем <name>. Это независимая секция, которая может быть
использована одним или несколькими прокси с помощью её имени.

errorfile <code> <file>

errorfile <code> <file>

Привязать содержимое файла к коду ошибки HTTP

Аргументы:

<code>    is the HTTP status code. Currently, HAProxy is capable of
          generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
          425, 429, 500, 501, 502, 503, and 504.

<file>    designates a file containing the full HTTP response. It is
          recommended to follow the common practice of appending ".http" to
          the filename so that people do not confuse the response with HTML
          error pages, and to use absolute paths, since files are read
          before any chroot is performed.

Пожалуйста, обратитесь к ключевому слову “errorfile” в секции 4 для подробностей.

Пример:

http-errors website-1
    errorfile 400 /etc/haproxy/errorfiles/site1/400.http
    errorfile 404 /etc/haproxy/errorfiles/site1/404.http
    errorfile 408 /dev/null  # work around Chrome pre-connect bug

http-errors website-2
    errorfile 400 /etc/haproxy/errorfiles/site2/400.http
    errorfile 404 /etc/haproxy/errorfiles/site2/404.http
    errorfile 408 /dev/null  # work around Chrome pre-connect bug

12.5. Кольцевые буферы

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

ring <ringname>

ring <ringname>

Создаёт новый кольцевой буфер с именем <ringname>.

backing-file <path>

backing-file <path>

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

При использовании этой опции общая объём памяти уменьшается на размер структуры “struct ring”, начинающейся в начале области, необходимой для восстановления содержимого области. Файл будет создан с правами владельца пользователя, который его запустил, с режимом 0600 и размером, заданным директивой “size”. При парсинге директивы (включая проверку конфигурации) любой существующий не пустой файл будет сначала переименован с дополнительным суффиксом “.bak”, а любой ранее существовавший файл с суффиксом “.bak” будет удалён. Это обеспечивает, что мгновенная перезагрузка или перезапуск процесса не приведёт к потере важной информации для отладки, и даёт администратору время заметить новый файл “.bak” и архивировать его при необходимости. Таким образом, после сбоя файл, обозначенный <path>, будет содержать самую свежую информацию, а при перезапуске сервиса сам файл “<path>.bak” будет содержать эту информацию. Это означает, что общий объём памяти, необходимый для хранения, будет вдвое превышать размер кольца. Ошибки при перезаписи файла игнорируются, поэтому размещение файла в каталоге без прав на запись будет достаточным для избежания резервной копии, если это не требуется.

ПРЕДУПРЕЖДЕНИЕ: использование этой функции имеет последствия с точки зрения стабильности и безопасности. Во-первых, запись в кольцо на медленное устройство (например, физический жесткий диск) может привести к заметному замедлению при доступах, и в случае слишком большого количества потоков, конкурирующих за доступ, может даже вызвать сбой. Во-вторых, внешний процесс, изменяющий указанную область, может привести к сбою процесса HAProxy или к перезаписи его собственной памяти с отпечатками. В-третьих, если файловая система заполняется до того, как заполнится кольцо, записи в кольцо могут привести к сбою процесса.

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

description <text>

description <text>

Описание — это необязательная строка описания кольца. Оно будет отображаться на CLI. По умолчанию, <name> используется для заполнения этого поля.

format <format>

format <format>

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

Аргументы:

<format> is the log format used when generating syslog messages. It may be
         one of the following:

  iso     A message containing only the ISO date, followed by the text.
          The PID, process name and system name are omitted. This is
          designed to be used with a local log server.

  local   Analog to rfc3164 syslog message format except that hostname
          field is stripped. This is the default.
          Note: option "log-send-hostname" switches the default to
          rfc3164.

  raw     A message containing only the text. The level, PID, date, time,
          process name and system name are omitted. This is designed to be
          used in containers or during development, where the severity
          only depends on the file descriptor used (stdout/stderr). This
          is the default.

  rfc3164 The RFC3164 syslog message format.
          (https://tools.ietf.org/html/rfc3164)

  rfc5424 The RFC5424 syslog message format.
          (https://tools.ietf.org/html/rfc5424)

  short   A message containing only a level between angle brackets such as
          '<3>', followed by the text. The PID, date, time, process name
          and system name are omitted. This is designed to be used with a
          local log server. This format is compatible with what the systemd
          logger consumes.

 priority A message containing only a level plus syslog facility between angle
          brackets such as '<63>', followed by the text. The PID, date, time,
          process name and system name are omitted. This is designed to be used
          with a local log server.

  timed   A message containing only a level between angle brackets such as
          '<3>', followed by ISO date and by the text. The PID, process
          name and system name are omitted. This is designed to be
          used with a local log server.

maxlen <length>

maxlen <length>

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

server <name> <address> [param*]

server <name> <address> [param*]

Настраивает сервер syslog по tcp для пересылки сообщений из кольцевого буфера. Поддерживаются все параметры “server” из пункта 5.2. Некоторые из них не имеют смысла для секций “ring”. Важный момент: добавлять в кольцевой буфер несколько серверов почти бессмысленно, поскольку каждый из них получает одну и ту же копию его содержимого, и буфер продвигается со скоростью самого медленного сервера. Если один сервер не отвечает, старые сообщения нельзя будет удалять, что может заблокировать добавление новых. Для отправки сообщений нескольким серверам следует использовать отдельный кольцевой буфер для каждого сервера журналирования, а не привязывать несколько серверов к одному буферу. Специальная директива сервера “log-proto” задаёт протокол отправки сообщений.

size <size>

size <size>

Это опциональный размер кольцевой буферной памяти в байтах. Значение по умолчанию установлено на BUFSIZE.

timeout connect <timeout>

timeout connect <timeout>

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

Аргументы:

<timeout> is the timeout value specified in milliseconds by default, but
          can be in any other unit if the number is suffixed by the unit,
          as explained at the top of this document.

timeout server <timeout>

timeout server <timeout>

Установите максимальное время пребывания ожидающих данных в буфер вывода.

Аргументы:

<timeout> is the timeout value specified in milliseconds by default, but
          can be in any other unit if the number is suffixed by the unit,
          as explained at the top of this document.

Пример:

global
    log ring@myring local7

ring myring
    description "My local buffer"
    format rfc5424
    maxlen 1200
    size 32764
    timeout connect 5s
    timeout server 10s
    server mysyslogsrv 127.0.0.1:6514 log-proto octet-count

12.6. Пересылка журналов

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

log-forward <name>

log-forward <name>

Создаёт новый прокси-пересылатель логов, идентифицированный как <name>.

backlog <conns>

backlog <conns>

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

bind <addr> [param*]

bind <addr> [param*]

Используется для настройки слушателя потокового журнала для получения сообщений для пересылки. Поддерживаются параметры “bind”, описанные в разделе 5.1, включая параметры ssl, однако некоторые утверждения, такие как “alpn”, могут быть нерелевантны для протокола syslog через TCP. Такие слушатели поддерживают как режим «Подсчет октетов», так и режим «Непрозрачное формирование кадров», как определено в rfc-6587.

dgram-bind <addr> [param*]

dgram-bind <addr> [param*]

Используется для настройки слушателя датаграмм логов, предназначенного для получения сообщений и их передачи. Адреса должны быть в формате IPv4 или IPv6, за которым следует порт. Поддерживается часть параметров “bind”, описанных в разделе 5.1, включая “interface”, “namespace” или “transparent”; остальные параметры игнорируются безусловно, так как не относятся к случаю UDP/syslog.

log global

log global
log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
    <facility> [<level> [<minlevel>]]

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

Пример:

global
   log stderr format iso local7

ring myring
    description "My local buffer"
    format rfc5424
    maxlen 1200
    size 32764
    timeout connect 5s
    timeout server 10s
    # syslog tcp server
    server mysyslogsrv 127.0.0.1:514 log-proto octet-count

log-forward sylog-loadb
    dgram-bind 127.0.0.1:1514
    bind 127.0.0.1:1514
    # all messages on stderr
    log global
    # all messages on local tcp syslog server
    log ring@myring local0
    # load balance messages on 4 udp syslog servers
    log 127.0.0.1:10001 sample 1:4 local0
    log 127.0.0.1:10002 sample 2:4 local0
    log 127.0.0.1:10003 sample 3:4 local0
    log 127.0.0.1:10004 sample 4:4 local0

maxconn <conns>

maxconn <conns>

Исправьте максимальное количество одновременных соединений на лог-форвардере. 10 — значение по умолчанию.

timeout client <timeout>

timeout client <timeout>

Установите максимальное время неактивности с клиента.

option assume-rfc6587-ntf

option assume-rfc6587-ntf

Приказывает HAProxy рассматривать поступающие TCP потоки логов всегда как использующие непрозрачную оболочку. Этот параметр упрощает логику оболочки и обеспечивает единообразное обработку сообщений, особенно при работе с некорректно сформированными начальными символами.

option dont-parse-log

option dont-parse-log

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

option host { replace | fill | keep | append }

option host { replace | fill | keep | append }

Задаёт стратегию обработки поля hostname в секции log-forward для исходящих сообщений syslog в форматах rfc3164 или rfc5424.

  replace If input message already contains a value for the hostname field,
          we replace it by the source IP address from the sender.
          If input message doesn't contain a value for the hostname field
          (ie: '-' as input rfc5424 message or non compliant rfc3164 or
          rfc5424 message), we use the source IP address from the sender as
          hostname field.

  fill    If input message already contains a value for the hostname field,
          we keep it.
          If input message doesn't contain a value for the hostname field
          (ie: '-' as input rfc5424 message or non compliant rfc3164 or
          rfc5424 message), we use the source IP address from the sender as
          hostname field.
          (This is the default)

  keep    Если входное сообщение уже содержит значение поля hostname,  
          мы сохраняем его.  
          Если входное сообщение не содержит значения поля hostname,  
          мы устанавливаем его в 'localhost' (rfc3164) или '-' (rfc5424).

  append  Если входное сообщение уже содержит значение поля hostname,  
          мы добавляем запятую, за которой следует IP-адрес отправителя.  
          Если входное сообщение не содержит значения поля hostname,  
          мы используем IP-адрес отправителя.

Для всех перечисленных опций, если адрес исходного IP-адреса от отправителя недоступен (то есть: UNIX/ABNS socket), то получаемая стратегия будет “keep”.

Примечание: данное опция актуально только для формата логов rfc3164 или rfc5424. В противном случае настройка не окажет видимого эффекта.

12.7. Хранилище сертификатов

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

crt-store [<name>]

Секция “crt-store” может принимать необязательное имя в качестве аргумента. Если имя указано, каждый сертификат этого хранилища должен ссылаться с помощью “@<name>/<crt>” или “@<name>/<alias>”.

Файлы в хранилище сертификатов также могут обновляться динамически с помощью CLI. См. “set ssl cert” в секции в руководстве по управлению 9.3 .

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

• crt-base
• key-base
• load

crt-base <dir>

crt-base <dir>

Присваивает стандартную директорию для получения сертификатов SSL при использовании относительного пути с директивами “crt”. Абсолютные пути, указанные явно, имеют приоритет и игнорируют “crt-base”. При использовании в хранилище сертификатов игнорируется crt-base секции глобальной конфигурации.

key-base <dir>

key-base <dir>

Присваивает стандартную директорию для получения приватных ключей SSL при использовании относительного пути с директивами “key”. Абсолютные пути, указанные явно, имеют приоритет и игнорируют “key-base”. При использовании в crt-store игнорируется key-base секции глобального раздела.

load [crt <filename>] [param*]

load [crt <filename>] [param*]

Загружайте файлы SSL в хранилище сертификатов. Для списка параметров см. секцию “12.7.1. Опции загрузки”

Пример:

crt-store
    load crt "site1.crt" key "site1.key" ocsp "site1.ocsp" alias "site1"
    load crt "site2.crt" key "site2.key"

frontend in2
    bind *:443 ssl crt "@/site1" crt "site2.crt"

crt-store web
    crt-base /etc/ssl/certs/
    key-base /etc/ssl/private/
    load crt "site3.crt" alias "site3"
    load crt "site4.crt" key "site4.key"

frontend in2
    bind *:443 ssl crt "@/site1" crt "site2.crt"  crt "@web/site3" crt "@web/site4.crt"

12.7.1. Параметры загрузки

Загрузите файлы SSL в хранилище сертификатов. Слово load может принимать несколько параметров, перечисленных ниже. Эти ключевые слова также могут использоваться в crt-list.

crt <filename>

crt <filename>

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

acme <string>

acme <string>

Этот параметр позволяет настроить протокол ACME для заданного сертификата. Это экспериментальная функция, требующая ключевого слова “expose-experimental-directives” в секции глобального уровня.

При использовании ключевого слова “acme” в crt-store возможно запускать без существующего сертификата на диске. Вместо этого будет использоваться временная пара ключей до генерации сертификата ACME. Это поведение является исключительным для crt-stores, ни строка crt-list, ни строка ssl-f-use не могут достичь такого результата без предварительного объявления crt-store.

См. также секцию 12.8 (“ACME”) и “domains” в этой секции.

alias <string>

alias <string>

Вариантный аргумент. Позволяет присвоить сертификату имя, чтобы он мог быть ссылаться на него в конфигурации. Имя должно предваряться символом ‘@/’ при использовании в других частях конфигурации.

domains <string>

domains <string>

Настройте список доменов, которые будут использоваться для ACME сертификатов. Первый домен в списке используется как CN. Домены разделяются запятыми в списке.

См. также секцию 12.8 (“ACME”) и “acme” в этой секции.

Пример:

load crt "example.com.pem" acme LE domains "bar.example.com,foo.example.com"

ips <string>

ips <string>

Настройте список IP-адресов, которые будут включены как IP SAN в сертификате ACME. IP-адреса в списке разделяются запятыми.

Создание сертификата с IP-адресами может потребовать использования профиля “shortlived”.

См. также секцию 12.8 (“ACME”), “acme” и “domains” в этой секции.

Пример:

load crt "server.pem" acme LE ips "192.0.2.1,2001:db8::1"

key <filename>

key <filename>

Этот аргумент является необязательным. Загрузите приватный ключ в формате PEM. Если приватный ключ уже был определён в “crt”, он заменит его.

ocsp <filename>

ocsp <filename>

Этот аргумент является необязательным, он загружает ответ в формате OCSP в DER. Он может быть обновлён с помощью CLI.

issuer <filename>

issuer <filename>

Этот аргумент является необязательным. Загрузите издателя OCSP в формате PEM. Для идентификации того, к какому сертификату относится ответ OCSP, необходим сертификат издателя. Если сертификат издателя не найден в файле “crt”, его можно загрузить из файла с помощью этого аргумента.

sctl <filename>

sctl <filename>

Этот аргумент является необязательным. Поддержка расширения Certificate Transparency (RFC6962) TLS включена.
Файл должен содержать действительный список подписанного времени сертификации, как описано в RFC. Файл анализируется для проверки базовой синтаксической корректности, но подписи не проверяются.

ocsp-update [ off | on ]

ocsp-update [ off | on ]

Включите автоматическое обновление ответа OCSP при значении ‘on’, отключите в противном случае. Значение по умолчанию — ‘off’. Чтобы включить автоматическое обновление OCSP на строке bind, можно использовать этот параметр в crt-store или global-опцию “tune.ocsp-update.mode”. Если сертификат используется в нескольких crt-lists с разными значениями параметра ‘ocsp-update’, будет выдана ошибка. Аналогично, если сертификат наследует global-опцию на строке bind и имеет несовместимо заданный явный параметр ‘ocsp-update’ в crt-list, будет выдана та же ошибка.

Примеры:

Вот пример конфигурации, включающей его с помощью crt-list:

haproxy.cfg:

frontend fe
    bind:443 ssl crt-list haproxy.list

haproxy.list:

server_cert.pem [ocsp-update on] foo.bar

Вот пример конфигурации, включающей его с использованием crt-store:

haproxy.cfg:

crt-store
  load crt foobar.pem ocsp-update on

frontend fe
    bind:443 ssl crt foobar.pem

Когда опция устанавливается в ‘on’, мы попытаемся получить ответ OCSP каждый раз, когда в сертификате фронтенда найден URI OCSP. Единственным ограничением этого режима является необходимость того, чтобы издатель сертификата был известен для построения идентификатора сертификата OCSP. Каждый ответ OCSP будет обновляться как минимум раз в час, и ещё чаще, если срок действия конкретного ответа OCSP истекает раньше этого часового лимита. Останется минимальный интервал обновления в 5 минут, чтобы избежать слишком частых обновлений ответов, срок действия которых очень короток или вообще отсутствует. Из-за этого жёсткого ограничения, следует отметить, что при включении автоматического обновления в ‘on’, любые ответы OCSP, загруженные при инициализации, не будут обновляться до тех пор, пока не пройдёт как минимум 5 минут, даже если их срок действия истекает до текущего времени плюс 5 минут. Это не должно быть слишком большим препятствием, поскольку ответ OCSP должен быть действительным при загрузке во время инициализации (срок действия должен быть в будущем), и, следовательно, маловероятно, что такой ответ истечёт так быстро после инициализации. С другой стороны, если сертификат имеет указанную URI OCSP и отсутствует ответ OCSP, установка этой опции в ‘on’ для данного сертификата обеспечит автоматическое получение ответа OCSP сразу после инициализации. Значения минимального и максимального задержек (5 минут и 1 часа соответственно) могут быть настроены с помощью глобальных опций “ocsp-update.maxdelay” и “ocsp-update.mindelay”.

Каждый раз, когда обновляется ответ OCSP автоматической задачей обновления или в результате вызова команды “update ssl ocsp-response” CLI, генерируется отдельная строка лога. Она следует специфическому формату, содержащему следующий заголовок “<OCSP-UPDATE>” и последующую информацию, связанную с OCSP: — путь к соответствующему сертификату фронтенда — числовое состояние обновления — текстовое состояние обновления — количество сбоев обновления для данного ответа — количество успешных обновлений для данного ответа. См. команду “show ssl ocsp-updates” CLI для полного списка кодов ошибок и сообщений об ошибках. Эта строка генерируется независимо от успешности или неуспешности обновления ответа OCSP. Запрос/ответ OCSP передаётся и получается через экземпляр http_client, у которого установлено опция dontlog-normal и который использует стандартный формат лога HTTP в случае ошибки (например, недоступный ответчик OCSP). Если возникает такая ошибка, дополнительно генерируется строка лога, содержащая информацию, связанную с HTTP, и одновременно с «обычной» строкой OCSP (в которой, скорее всего, будет указано «ошибка HTTP»). Однако, если возникает чистая ошибка HTTP (например, недоступный ответчик OCSP), дополнительно генерируется строка лога, следующая за стандартным форматом HTTP log-format. Ниже приведены два примера таких строк лога: сначала пример строки лога успешного обновления OCSP, затем пример ошибки HTTP с двумя разными строками (строки были выведены, а URL было сокращено для удобства чтения):

<133>Mar  6 11:16:53 haproxy[14872]: <OCSP-UPDATE> /path_to_cert/foo.pem 1 \
        "Update successful" 0 1

<133>Mar  6 11:18:55 haproxy[14872]: <OCSP-UPDATE> /path_to_cert/bar.pem 2 \
        "HTTP error" 1 0
<133>Mar  6 11:18:55 haproxy[14872]: -:- [06/Mar/2023:11:18:52.200] \
        <OCSP-UPDATE> -/- 2/0/-1/-1/3009 503 217 - - SC-- 0/0/0/0/3 0/0 {} \
        "GET http://127.0.0.1:12345/MEMwQT HTTP/1.1"

Устранение неполадок: Частой ошибкой, которая может возникнуть при использовании сертификатов Let’s Encrypt, является то, что разрешение DNS предоставляет адрес IPv6, а в вашей системе отсутствует действительный исходящий маршрут IPv6. В таком случае вы можете либо создать соответствующий маршрут, либо установить опцию “httpclient.resolvers.prefer ipv4” в секции глобального настройки. В случае ошибки “проверка ответа OCSP неудачна” рекомендуется проверить, является ли предоставленный сертификат издателя действительным. Более точное сообщение об ошибке может быть отображено в скобках после общего сообщения об ошибке. Ошибка может возникать при “проверка ответа OCSP неудачна” или при ошибке “ошибка при вставке”.

jwt [ off | on ]

jwt [ off | on ]

Разрешить использование этого сертификата для проверки JWT или дешифровки через преобразователь “jwt_verify_cert”, “jwt_decrypt_cert” или “jwt_decrypt” при установке значения ‘on’. Значение по умолчанию — ‘off’.

При установке значения ‘on’ для заданного сертификата команда CLI “del ssl cert” не будет работать. Для удаления сертификата он должен не использоваться ни для проверки SSL, ни для проверки JWT.

Эту опцию можно изменить в режиме работы с помощью команд “add ssl jwt” и “del ssl jwt” CLI. См. также команду “show ssl jwt” CLI.

generate-dummy [ off | on ]

generate-dummy [ off | on ]

Разрешает генерацию приватного ключа и его самоподписанных сертификата в момент парсинга при установке в
‘on’. Это может быть полезно, если в ходе тестирования нет доступного сертификата, например. В этом случае, “keytype”, “bits” и “curves” могут быть использованы для настройки приватного ключа.
При отсутствии использования, значение по умолчанию — ‘off’. (см. также “keytype”, “bits” и “curves”).

keytype [ RSA | ECDSA ]

keytype [ RSA | ECDSA ]

Разрешает выбор типа приватного ключа, используемого для генерации самоподписанных сертификатов при парсинге. В случае, если “generate-dummy” установлен в ‘on’ для этого сертификата, применяется такой режим. При отсутствии указания значение по умолчанию — ‘RSA’. (см. также “generate-dummy”).

bits <number>

bits <number>

Настройте количество бит, необходимое для генерации сертификата со знаком RSA при том, что “generate-dummy” установлен в ‘on’ для этого сертификата со знаком и “keytype” установлен в ‘RSA’. При отсутствии использования значение по умолчанию — 2048. (см. также “generate-dummy”).

curves <string>

curves <string>

Настройте кривые при том, что “generate-dummy” установлен в ‘on’ и “keytype” установлен в ‘ECDSA’ для этого самоподписного сертификата. По умолчанию — ‘P-384’.

12.8. ACME

acme <name>

Протокол ACME может быть настроен с помощью секции “acme”. Секция принимает аргумент “<name>”, который используется для привязки сертификата к секции.

Секция ACME позволяет настроить HAProxy как клиента ACMEv2. Эта функция является экспериментальной, что означает, что “expose-experimental-directives” должен быть указан в глобальной секции, чтобы можно было использовать эту функцию.

Руководство доступно на HAProxy wiki https://github.com/haproxy/wiki/wiki/ACME:--native-haproxy

Текущие ограничения:

- The feature is limited to the http-01, dns-01 or dns-persist-01 challenges

- The feature is limited to the http-01, dns-01 or dns-persist-01 challenges

на данный момент. http-01 полностью обрабатывается HAProxy, но dns-01 и dns-persist-01 требуют либо API датаплэйна, либо другого 3 стороннего инструмента для взаимодействия с поставщиком DNS API. dns-persist-01 требует только установки записи TXT один раз, поэтому она может быть настроена вручную без использования инструмента.

- It is possible to start without an existing certificate on the disk. To do

- It is possible to start without an existing certificate on the disk. To do

таким образом, сертификат должен быть настроен в хранилище crt. При использовании ключевого слова “acme” в хранилище crt будет использован временный пароль ключей до генерации сертификата ACME.

- The current HAProxy architecture is a non-blocking model, access to the disk

- The current HAProxy architecture is a non-blocking model, access to the disk

не должен выполняться после загрузки конфигурации, поскольку это может заблокировать цикл событий, блокируя трафик на том же потоке. Означает, что сертификаты и ключи, сгенерированные в HAProxy, должны быть экспортированы снаружи HAProxy с помощью “dump ssl cert” на сокете статуса. Экспорт сертификатов можно автоматизировать с помощью API планировщика или скрипта HAProxy-dump-certs, предоставленного в директории admin/cli/.

Планировщик ACME запускается при старте HAProxy, он проходит по сертификатам и запускает задачу ACME обновления при прохождении времени notAfter + (notAfter - notBefore) / 12, или 7 дней, если notBefore не определён. Планировщик затем спит и пробуждается через 12 часов. Возможность ручного запуска задачи обновления осуществляется с помощью команды “acme renew”. См. также “acme status” в руководстве по управлению.

Следующие ключевые слова доступны в секции ACME:

account-key <filename>

account-key <filename>

Настройте путь к ключу учетной записи. Ключ должен быть сгенерирован до запуска HAProxy. Если не используется ключ учетной записи, секция acme попытается загрузить файл по имени секции “<name>.account.key”. Если файл не существует, HAProxy сгенерирует его, используя параметры из секции acme.

Также можно сгенерировать вручную ключ RSA приватного ключа с помощью OpenSSL:

openssl genrsa -out account.key 2048

Или ecdsa один:

openssl ecparam -name secp384r1 -genkey -noout -out account.key

acme-vars <string>

acme-vars <string>

Передавайте произвольные переменные внешнему инструменту DNS для настройки (например, dataplaneAPI) через синтаксис “dpapi”. Семантика зависит от конкретного инструмента; см. документацию вашего инструмента DNS для настройки.

Этот ключ имеет смысл только в случае, когда тип вызова равен “dns-01” или “dns-persist-01”.

См. также: “challenge”, “provider-name”

bits <number>

bits <number>

Настройте количество бит, необходимое для генерации сертификата RSA. По умолчанию — 2048. Установка слишком высокого значения может вызвать предупреждение, если ваша машина не имеет достаточной производительности. (Это может быть настроено с помощью “warn-blocked-traffic-after”, однако блокировка трафика слишком долго может сработать с watchdog.)

challenge <string>

challenge <string>

Принимает тип вызова в качестве параметра, этот параметр должен быть http-01, dns-01 или dns-persist-01. При отсутствии использования данного параметра по умолчанию выбирается http-01.

dns-persist-01 реализует draft-ietf-acme-dns-persist. В отличие от dns-01, он использует статическую запись TXT в “_validation-persist.<domain>”, которая устанавливается один раз и не изменяется между перезагрузками. Запись должна содержать идентификатор аккаунта URI и опциональную политику. Тип вызова dns-persist-DNS не требует прав на запись в провайдере API при каждом обновлении.

challenge-ready <value>[,<value>]*

challenge-ready <value>[,<value>]*

Настройте условия, которые должны быть выполнены перед уведомлением сервера ACME о готовности днс-01 вызова для проверки. Допустимые значения:

cli  - wait for an operator to signal readiness via the CLI command
       "acme challenge_ready <crt> domain <domain>" on the master CLI or
       the stats socket. This allows an external DNS provisioning tool to
       confirm that the TXT record has been set before HAProxy proceeds.

dns  - perform a DNS pre-check by resolving the TXT record for
       "_acme-challenge.<domain>" using the configured "default" resolvers
       section, not the authoritative name servers. The challenge is not
       submitted until the TXT record matches the expected token. Results
       may therefore be affected by DNS caching at the resolver level. The
       delay between resolution attempts is controlled by "dns-delay". This
       option is independent of the CLI command, so no human intervention
       is required.

       For dns-01, the TXT record at "_acme-challenge.<domain>" is
       resolved and must match the expected token. For dns-persist-01,
       the TXT record at "_validation-persist.<domain>" is resolved and
       only its presence is checked.

delay - apply an initial wait of "dns-delay" before proceeding. Without
        "dns", the challenge is submitted after the delay expires. When
        combined with "dns", the initial wait is applied before starting
        the DNS pre-checks.

none - no readiness condition; the challenge is submitted to the ACME
       server immediately without waiting for any external confirmation.
       This option cannot be combined with others.

Множественные значения могут быть объединены запятой. При указании нескольких условий HAProxy обрабатывает их в следующем порядке: сначала ожидает подтверждения CLI (“cli”), затем применяет начальный задержку (“delay”), затем выполняет DNS проверки (“dns”).

Этот параметр совместим только с типами вызова dns-01 и dns-persist-01.

Когда “challenge” установлен в “dns-01” и этот параметр не настроен, значение по умолчанию — “cli”.

Когда “challenge” установлен в “dns-persist-01” и этот параметр не настроен, значение по умолчанию равно
“dns,delay”.

Когда “challenge” установлен в “dns-persist-01”, всегда выполняется инициальный опциональный DNS проверка до оценки challenge-ready условий. Поскольку запись “_validation-persist.<domain>” TXT устанавливается один раз и не изменяется между перезагрузками, HAProxy проверяет в момент перезагрузки, присутствует ли запись. Если проверка успешно проходит для всех доменов, вызов проверки немедленно выполняется без прохождения challenge-ready этапов (cli, delay, dns). Если проверка не проходит, HAProxy переходит к обычному challenge-ready потоку.

Пример:

# Wait for CLI confirmation, then verify DNS propagation
challenge-ready cli,dns

contact <string>

contact <string>

Электронная почта для связи, которая будет привязана к ключу учетной записи в CA.

curves <string>

curves <string>

При использовании типа ключа ECDSA настройте кривые. По умолчанию — P-384.

directory <string>

directory <string>

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

Пример:

directory https://acme-staging-v02.api.letsencrypt.org/directory

dns-delay <time>

dns-delay <time>

Настройте задержку, используемую условиями “challenge-ready” «delay» и «dns». Значение — время, выраженное в формате времени HAProxy (например, «5m», «300s»). По умолчанию — 30 секунд.

Её роль зависит от используемых условий “challenge-ready”:

delay     - the challenge is submitted after this delay expires, without
            any DNS pre-check.

dns       - the delay between two consecutive DNS resolution attempts.
            The first probe fires immediately without any initial wait.

dns+delay - the initial wait before the first DNS resolution attempt, and
            the delay between subsequent retries.

Примечание: разрешение проходит через настроенный раздел “default” резолверов, а не через авторитетные серверы имен. Результаты могут поэтому все еще быть подвержены кэшированию DNS на уровне резолвера.

dns-timeout <time>

dns-timeout <time>

Когда “challenge-ready” содержит “dns”, настройте максимальное время, разрешающееся для успешного разрешения записи TXT перед отменой вызова. Значение — время, выраженное в формате времени HAProxy (например, “10m”, “600s”). По умолчанию — 600 секунд.

Таймер начинается с момента первого запуска попытки разрешения DNS (после первичного “dns-delay”). Если следующая попытка разрешения была бы запущена после истечения тайм-аута, вызов отменяется с ошибкой. Это предотвращает бесконечный цикл повторных попыток при сбое распространения DNS.

См. также: “dns-delay”

keytype <string>

keytype <string>

Настройте тип ключа, который будет сгенерирован. Значение может быть либо “RSA”, либо “ECDSA”. Вы также можете настроить “curves” для ECDSA и количество “bits” для RSA. По умолчанию генерируются ключи EC384.

map <map>

map <map>

Настройте карту, которая будет использоваться для хранения токена (ключ) и отпечатка (значение), что позволяет отвечать на вызов при использовании нескольких аккаунтов. Задача acme добавит записи до проверки вызова и удалит их в конце выполнения задачи.

profile <string>

profile <string>

Запросите конкретный профиль сертификата у Центра сертификации, включив поле “profile” в запрос нового заказа. Это реализует draft-ietf-acme-profiles.

Имена профилей — это краткие идентификаторы, специфичные для каждого CA (например, “classic”, “shortlived”). При задании профиля имя профиля передаётся без изменений в полезную нагрузку нового заказа JSON. CA может игнорировать запрос или возвращать ошибку, если профиль не поддерживается. При отсутствии задания профиля поле профиля не включается, и CA использует свою стандартную политику выдачи.

См. https://letsencrypt.org/docs/profiles/ для профилей Let’s Encrypt.

Пример:

# Request short-lived certificates
profile shortlived

provider-name <string>

provider-name <string>

Задайте имя провайдера DNS, передаваемое внешнему инструменту DNS управления (например, dataplaneAPI) через приемник “dpapi”. Допустимые значения зависят от инструмента; обратитесь к документации вашего инструмента управления DNS.

Этот ключ имеет смысл только в случае, когда тип вызова равен “dns-01” или “dns-persist-01”.

См. также: “challenge”, “acme-vars”

reuse-key { on | off }

reuse-key { on | off }

Если установлено “on”, HAProxy не генерирует новый приватный ключ и сохраняет предыдущий. Ротация приватных ключей рекомендуется; при включении этой опции рекомендуется регулярно вручную пересоздавать ключи.

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

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

Предварительное значение — “off”.

Пример:

global
    expose-experimental-directives
    httpclient.resolvers.prefer ipv4

frontend in
    bind *:80
    bind *:443 ssl
    http-request return status 200 content-type text/plain lf-string "%[path,field(-1,/)].%[path,field(-1,/),map(virt@acme)]\n" if { path_beg '/.well-known/acme-challenge/' }
    ssl-f-use crt "foo.example.com.pem.rsa"   acme LE1 domains "foo.example.com.pem,bar.example.com"
    ssl-f-use crt "foo.example.com.pem.ecdsa" acme LE2 domains "foo.example.com.pem,bar.example.com"

acme LE1
    directory https://acme-staging-v02.api.letsencrypt.org/directory
    account-key /etc/haproxy/letsencrypt.account.key
    contact john.doe@example.com
    challenge http-01
    keytype RSA
    bits 2048
    map virt@acme

acme LE2
    directory https://acme-staging-v02.api.letsencrypt.org/directory
    account-key /etc/haproxy/letsencrypt.account.key
    contact john.doe@example.com
    challenge http-01
    keytype ECDSA
    curves P-384
    map virt@acme

eab-key-id <filename>

eab-key-id <filename>

Укажите путь к файлу идентификатора ключа EAB. Средство аутентификации предоставляется Центром сертификации и должно быть размещено на указанном пути до запуска HAProxy. Оно используется только при создании аккаунта.

Файл должен содержать простую строку ASCII.

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

См. также: “eab-mac-key”, “eab-mac-alg”

eab-mac-key <filename>

eab-mac-key <filename>

Настройте путь к файлу ключа EAB MAC. Ключ предоставляется CA и должен быть размещён по указанному пути до запуска HAProxy. Используется только при создании учётной записи.

Файл должен содержать закодированный в формате base64url ключ MAC.

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

См. также: “eab-key-id”, “eab-mac-alg”

eab-mac-alg { HS256 | HS384 | HS512 }

eab-mac-alg { HS256 | HS384 | HS512 }

Настройте алгоритм MAC, используемый для подписи EAB. По умолчанию — HS256. Ключ EAB MAC должен быть достаточно велик, чтобы поддерживать заданный алгоритм MAC. Не все Центры сертификации поддерживают алгоритмы, кроме HS256.

См. также: “eab-key-id”, “eab-mac-key”

12.9. Проверки работоспособности

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

healthcheck <name>

healthcheck <name>

Создан новый проверка работоспособности с именем <name>. Это имя должно быть уникальным. Оно следует использовать в строке сервера для ссылки на конкретную секцию проверки работоспособности.

type <type>

type <type>

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

* tcp-check
* httpchk
* ssl-hello-chk
* smtpchk
* pgsql-check
* redis-check
* mysql-check
* ldap-check
* spop-check

Каждый тип использует те же параметры, что и соответствующий опции прокси. Например, параметры метода, URI… могут быть указаны для типа “httpchk”:

Примеры:

   healthcheck my-http-check
type httpchk GET /health HTTP/1.1 %[srv_name]

См. также: “option tcp-check”, “option httpchk”, “option ssl-hello-chk”, “option smtpchk”, “option mysql-check”, “option pgsql-check”, “option redis-check”, “опция ldap-check” и “опция spop-check”

http-check comment <string>

http-check comment <string>
http-check connect [default] [port <expr>] [addr <ip>] [send-proxy]
                   [via-socks4] [ssl] [sni <sni>] [alpn <alpn>] [linger]
                   [proto <name>] [comment <msg>]
http-check disable-on-404
http-check expect [min-recv <int>] [comment <msg>]
                  [ok-status <st>] [error-status <st>] [tout-status <st>]
                  [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
                  [!] <match> <pattern>
http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>]
                [hdr <name> <fmt>]* [{ body <string> | body-lf <fmt> }]
                [comment <msg>]
http-check send-state
http-check set-var(<var-name>[,<cond>...]) <expr>
http-check set-var-fmt(<var-name>[,<cond>...]) <fmt>
http-check unset-var(<var-name>)

Добавьте конкретное правило http-check для проверки здоровья “httpchk”. Используется та же синтаксис, что и в соответствующих директивы прокси. См. соответствующую документацию по прокси для подробностей.

tcp-check comment <string>

tcp-check comment <string>
tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4]
                  [ssl] [sni <sni>] [alpn <alpn>] [linger]
                  [proto <name>] [comment <msg>]
tcp-check expect [min-recv <int>] [comment <msg>]
                 [ok-status <st>] [error-status <st>] [tout-status <st>]
                 [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
                 [!] <match> <pattern>
tcp-check send <data> [comment <msg>]
tcp-check send-lf <fmt> [comment <msg>]
tcp-check send-binary <hexstring> [comment <msg>]
tcp-check send-binary-lf <hexfmt> [comment <msg>]
tcp-check set-var(<var-name>[,<cond>...]) <expr>
tcp-check set-var-fmt(<var-name>[,<cond>...]) <fmt>
tcp-check unset-var(<var-name>)

Добавьте конкретное правило tcp-check для проверки здоровья “tcp-check”. Используется та же синтаксис, что и в соответствующих директивы прокси. См. соответствующую документацию по прокси для подробностей.