TLS

pg_doorman терминирует TLS на клиентской стороне (клиенты → pg_doorman) и инициирует TLS на серверной стороне (pg_doorman → PostgreSQL). Стороны настраиваются независимо.

Клиентский TLS

Шифрование соединений между клиентскими приложениями и pg_doorman.

Режимы

РежимПоведение
disableНе анонсировать TLS. Клиенты, отправляющие SSLRequest, получают 'N' (отказ).
allowАнонсировать TLS, но принимать и обычный TCP.
requireТребовать TLS. Обычные соединения разрываются после неудачного SSLRequest.
verify-fullТребовать TLS и валидный клиентский сертификат. Используется для mTLS.

verify-full — это mTLS: сервер проверяет сертификат клиента. Подготовьте набор клиентских CA через tls_ca_cert.

Конфигурация

general:
  tls_mode: "require"
  tls_certificate: "/etc/pg_doorman/tls/server.crt"
  tls_private_key: "/etc/pg_doorman/tls/server.key"
  tls_ca_cert: "/etc/pg_doorman/tls/client_ca.pem"   # только для verify-full
  tls_rate_limit_per_second: 100                       # необязательное ограничение скорости handshake

Для разработки сертификат может быть самоподписанным; в промышленной эксплуатации обычно используют Let's Encrypt или внутренний CA.

Перезагрузка (клиентская сторона)

Клиентские сертификаты загружаются при старте. Их смена требует рестарта процесса. Для клиентского TLS перезагрузки по SIGHUP нет.

Горячая замена процесса может загрузить новый сертификат и ключ для новых входящих TLS-подключений, но это не бесшовная ротация для уже открытых TLS-сессий. Для переноса TLS-сессий оба процесса должны использовать те же tls_certificate и tls_private_key, а сборка должна быть Linux + tls-migration; при смене этих файлов TLS-клиенты дренируются и переподключаются.

Политика шифров

Минимум TLS 1.2 применяется на этапе handshake. PgDoorman не задаёт явный список шифров — эффективные шифры берутся из системной сборки OpenSSL. Если нужен жёсткий список, настройте его системно (/etc/ssl/openssl.cnf) или соберите OpenSSL с нужной политикой.

Direct TLS handshake (PostgreSQL 17, без SSLRequest) не поддерживается. Для управления шифрами TLS 1.3 или direct TLS из PostgreSQL 17 используйте PgBouncer 1.25+.

Серверный TLS

Шифрование соединений между pg_doorman и PostgreSQL. Появилось в 3.6.0.

Режимы

РежимПоведение
disableОбычный TCP.
allow (по умолчанию)Сначала пробовать обычный TCP; если сервер отказывает, повторить попытку на новом сокете с TLS. Соответствует libpq sslmode=allow.
preferОтправить SSLRequest; если сервер отвечает 'N', откатиться к обычному TCP.
requireТребовать TLS. Падать, если сервер его не поддерживает.
verify-caТребовать TLS и проверять серверный сертификат против настроенного CA.
verify-fullТребовать TLS, проверять CA и проверять hostname сервера против сертификата.

allow — режим по умолчанию ради обратной совместимости: существующие развёртывания, где у PostgreSQL настроен TLS, автоматически переходят на TLS без изменения конфигурации. Для новых развёртываний, которым нужны явные гарантии, выбирайте require или verify-full.

Конфигурация

general:
  server_tls_mode: "verify-full"
  server_tls_ca_cert: "/etc/pg_doorman/tls/pg_ca_bundle.pem"

# Необязательно: клиентский сертификат для mTLS к PostgreSQL
  server_tls_certificate: "/etc/pg_doorman/tls/pg_client.crt"
  server_tls_private_key: "/etc/pg_doorman/tls/pg_client.key"

server_tls_ca_cert принимает PEM-bundle (несколько CA-сертификатов, склеенных подряд). Загружаются все.

Горячая перезагрузка

По SIGHUP серверные сертификаты перечитываются с диска. Существующие соединения продолжают пользоваться исходным TLS-контекстом; новые соединения используют перезагруженные сертификаты. Перезагрузка не берёт блокировку на горячем пути (Arc<ArcSwap<...>>): без обрыва соединений и без задержек на handshake.

kill -HUP $(pidof pg_doorman)

Это единственный путь перезагрузки TLS. Клиентские сертификаты по SIGHUP не перезагружаются.

mTLS к PostgreSQL

Задайте server_tls_certificate и server_tls_private_key. PostgreSQL должен быть настроен с ssl_ca_file, соответствующим подписанту клиентского сертификата, а у роли в pg_hba.conf со стороны PostgreSQL должно быть clientcert=verify-ca (или verify-full).

Мониторинг

Серверный TLS покрывают три серии Prometheus:

МетрикаТипНазначение
pg_doorman_server_tls_connectionsgauge на пулЧисло активных TLS-соединений к PostgreSQL.
pg_doorman_server_tls_handshake_duration_secondshistogram на пулБакеты продолжительности handshake.
pg_doorman_server_tls_handshake_errors_totalcounter на пулНеудавшиеся handshake. Алерт при ненулевой скорости.

Смотрите Справочник Prometheus.

Известные ограничения

  • Протокол COPY поверх серверного TLS не покрыт BDD-тестами. Поведение должно работать, но не верифицировано.
  • Cancel-запросы к PostgreSQL минуют серверный TLS — они идут по свежему обычному TCP-соединению. Это совпадает с дизайном протокола PostgreSQL (cancel отправляется по отдельному сокету).
  • Direct TLS handshake (быстрый handshake PostgreSQL 17 без SSLRequest) не поддерживается ни на одной из сторон.

Куда дальше