Настройка

Конфигурирование Pangolin Pooler

Компонент Pangolin Pooler имеет основной конфигурационный файл – pangolin-pooler.ini (путь /etc/pangolin-pooler/).

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

sudo chown postgres:postgres /etc/pangolin-pooler/pangolin-pooler.ini
sudo chmod 0600              /etc/pangolin-pooler/pangolin-pooler.ini

У компонента Pangolin Pooler также доступна возможность использования файла аутентификации userlist.txt, который хранит список пользователей и паролей. Подробное описание и процесс конфигурирования userlist.txt представлены в разделе далее.

Для применения изменений конфигурации компонента Pooler необходимо выполнить команду перезагрузки конфигурации:

• через системную команду:

  sudo systemctl reload pangolin-pooler

  или

  systemctrl --user reload pangolin-pooler

• через команду управления RELOAD в административной БД pgbouncer:

  $ psql -p 6544 pgbouncer
  
  pgbouncer=# RELOAD;

Конфигурационные параметры

В разделе приведено описание параметров и разделов конфигурационного файла pangolin-pooler.ini компонента Pangolin Pooler.

Подсказка

Конфигурационный файл имеет формат .ini. Имена разделов находятся между [ и ]. Строки, начинающиеся с ; или #, воспринимаются как комментарии и игнорируются.

Общие настройки

В таблице ниже приведены общие настройки, которые определяются в разделе [pgbouncer] конфигурационного файла.

:

Параметр	Описание	Значение по умолчанию
logfile	Указывает имя файла журнала. Для работы в фоновом режиме (-d) необходимо указать либо этот параметр, либо syslog.

admonition :class: attention Установка logfile сама по себе не отключает ведение журнала в stderr. Для этого используйте опцию командной строки -q или -d.

::

• /pangolinlogs/pangolin-pooler/pangolin-pooler.log

• • pidfile
  • Указывает PID-файл. Если pidfile не задан, работа в фоновом режиме (-d) не разрешена
  • /var/run/user/{user_id}/pangolin-pooler/pangolin-pooler.pid
• • listen_addr
  • Указывает список адресов (разделенных запятыми), по которым следует прослушивать TCP-соединения. Можно также использовать *, что означает «слушать все адреса». Если значение не задано, принимаются только соединения с сокетами Unix. Адреса могут быть указаны численно (IPv4/IPv6) или по имени
  • localhost
• • listen_port
  • Определяет, какой порт прослушивать. Применяется как к TCP, так и к Unix-сокетам
  • 6544

• • unix_socket_dir

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

    Чтобы перезагрузка в режиме онлайн (-R) работала, необходимо сконфигурировать сокет Unix, который должен находиться в пространстве имен файловой системы

  • /tmp

• • unix_socket_mode
  • Режим файловой системы для сокета Unix. Игнорируется для сокетов в абстрактном пространстве имен
  • 0777
• • unix_socket_group
  • Имя группы, используемое для сокетов Unix. Игнорируется для сокетов в абстрактном пространстве имен
  • Не задано
• • user
  • Если установлено, указывает пользователя Unix, на которого следует перейти после запуска. Работает, только если Pooler запущен от имени root или если он уже запущен от имени указанного пользователя
  • Не задано

• • pool_mode

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

    • session – соединение возвращается в пул после отключения клиента;
    • transaction – соединение возвращается в пул после завершения транзакции;
    • statement – соединение освобождается обратно в пул после завершения запроса. Транзакции, охватывающие несколько операторов, в этом режиме запрещены

  • session

• • max_client_conn
  • Максимальное количество разрешенных клиентских соединений
  • 100
• • default_pool_size
  • Разрешенное количество соединений с сервером для пары пользователь/база данных. Может быть переопределено в конфигурации для каждой базы данных
  • 20

• • min_pool_size

  • Минимальное количество активных соединений с сервером.

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

  • 0 (отключено)

• • reserve_pool_size
  • Сколько дополнительных подключений разрешить к пулу (см. reserve_pool_timeout)
  • 0 (отключено)
• • reserve_pool_timeout
  • Время, за которое должен быть обслужен клиент. После указанного времени будут использованы дополнительные соединения из резервного пула. Значение 0 – отключает
  • 5.0 (секунды)

• • max_db_connections

  • Разрешенное количество соединений с сервером для каждой базы данных (независимо от пользователя). При этом учитывается база данных pgbouncer, к которой подключился клиент, а не база данных СУБД исходящего соединения.

    Этот параметр также можно задать для каждой базы данных в разделе [databases]

  • 0 (неограниченно)

• • max_user_connections

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

    Этот параметр также можно задать для каждого пользователя в разделе [users]

  • 0 (неограниченно)

• • max_user_client_connections

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

    Этот параметр также можно установить для каждого пользователя в разделе [users]

  • 0 (неограниченно)

• • server_round_robin
  • По умолчанию Pooler использует соединения с сервером по принципу LIFO (last-in, first-out), так что наибольшая нагрузка распределяется по небольшому количеству соединений. Это обеспечивает наилучшую производительность, если есть только один сервер, обслуживающий базу данных. Но если за адресом базы данных стоит система round-robin (TCP, DNS или список хостов), то будет лучше, если Pangolin Pooler также будет использовать соединения по такому принципу, добиваясь равномерной нагрузки
  • 0

• • track_extra_parameters

  • По умолчанию Pangolin Pooler отслеживает параметры client_encoding, datestyle, timezone, standard_conforming_strings и application_name для каждого клиента. Для отслеживания других параметров, их можно указать здесь, чтобы Pooler знал, что они должны сохраняться в кеше клиентских переменных и восстанавливаться на сервере всякий раз, когда клиент становится активным.

    Если нужно указать несколько значений, используется список, разделенный запятыми (например, default_transaction_readonly, IntervalStyle)

  • IntervalStyle

• • ignore_startup_parameters

  • По умолчанию Pooler разрешает использовать в стартовых пакетах только те параметры, которые он может отслеживать: client_encoding, datestyle, timezone и standard_conforming_strings. Все остальные параметры приведут к ошибке. Чтобы разрешить другие параметры, их можно указать в ignore_startup_parameters, чтобы Pooler знал, что они обрабатываются администратором, и мог их игнорировать.

    Если нужно указать несколько значений, используется список, разделенный запятыми (например: options, extra_float_digits)

  • extra_float_digits

• • peer_id

  • Идентификатор пира, используемый для идентификации данного процесса pangolin-pooler в группе запущенных вместе процессов. Значение peer_id должно быть уникальным в группе запущенных вместе процессов pangolin-pooler. При значении 0 пиринг Pooler отключен.

    Максимальное значение, которое может быть использовано для peer_id - 16383

  • 0

• • disable_pqexec
  • Отключение протокола Simple Query (PQexec). В отличие от протокола Extended Query, Simple Query допускает несколько запросов в одном пакете, что позволяет осуществлять некоторые классы атак с использованием «SQL-инъекций». Его отключение может повысить безопасность, потому что работать будут только те клиенты, которые используют исключительно протокол Extended Query
  • 0
• • application_name_add_host
  • Добавление адреса хоста и порта клиента в настройку имени приложения, устанавливаемую при запуске соединения. Помогает определить источник неправильных запросов. Эта логика применяется только при запуске соединения. Если application_name позже будет изменено с помощью SET, Pooler не будет изменять его снова
  • 0
• • conffile
  • Показывает расположение текущего файла конфигурации. Изменение этого параметра заставит Pangolin Pooler использовать другой файл конфигурации для следующего RELOAD/SIGHUP
  • Файл из командной строки
• • stats_period
  • Устанавливает, как часто обновляются средние значения, отображаемые в различных командах SHOW, и как часто агрегированная статистика записывается в журнал (см. log_stats)
  • 60 (в секундах)

• • max_prepared_statements

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

    Более подробное описание параметра представлено в исходной документации ядра компонента PgBouncer.

    Рекомендуется ознакомиться с разделом «Поддержка подготовленных запросов»

  • 0

• • ndc_suspending_timeout

  • Содержит значение момента времени старта приложения или получения последней команды NDC_KEEPALIVE. Это значение в основном цикле обработки событий сравнивается с текущим моментом времени и, если разница превышает заданное в конфигурационном файле значение ndc_suspending_timeout, то Pooler прерывает все существующие соединения к базам данных и все клиентские соединения, кроме соединений с административной консолью, и переходит в режим NDC_DISALLOWED (поведение аналогичное получению команды NDC_SUSPEND).

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

    Если примененное значение заменено на значение по умолчанию (0), то возобновляется прием и обработка клиентских соединений.

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

    Рекомендуется ознакомиться с разделом «Поддержка топологии N-ЦОД в Pangolin Pooler»

  • 0 (секунды)

    :::

Настройки аутентификации

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

:

Параметр	Описание	Значение по умолчанию
auth_type	Как аутентифицировать пользователей: - cert – клиент должен подключиться по TLS-соединению с действительным сертификатом клиента. Имя пользователя берется из поля CommonName сертификата. - md5 – использовать проверку паролей на основе MD5. Это метод аутентификации по умолчанию. auth_file может содержать как MD5-зашифрованные, так и обычные пароли. Если настроен md5, а у пользователя есть SCRAM-секрет, то вместо него автоматически используется SCRAM-аутентификация. - scram-sha-256 – использовать проверку паролей с помощью SCRAM-SHA-256. auth_file должен содержать секреты SCRAM или пароли в открытом виде. - plain – пароль передается в открытом виде. Метод более не актуален. - trust – аутентификация не выполняется. Имя пользователя должно существовать в auth_file. - any – аналогичен методу trust, но указанное имя пользователя игнорируется. Требуется, чтобы все базы данных были настроены на вход под определенным пользователем. Кроме того, консольная база данных позволяет любому пользователю входить в систему под именем администратора. - hba – фактический тип аутентификации загружается из файла auth_hba_file. Это позволяет использовать различные методы аутентификации для разных путей доступа, например: соединения через Unix сокет используют метод peer, соединения через TCP должны использовать TLS. - pam – для аутентификации пользователей используется PAM, auth_file игнорируется. Этот метод несовместим с базами данных, использующими параметр auth_user. Имя службы, передаваемое в PAM - pangolin-pooler. pam не поддерживается в файле конфигурации HBA.	md5
auth_hba_file	Файл конфигурации HBA для использования, когда параметр auth_type установлен в hba	Не задано
auth_ident_file	Файл карты идентификаторов для использования, когда параметр auth_type установлен в hba и будет определена карта пользователей	Не задано
auth_file	Имя файла, из которого будут загружаться имена пользователей и пароли. Подробнее описано в подразделе «Файл аутентификации» далее Большинство типов аутентификации требуют, чтобы были заданы либо auth_file, либо auth_user; в противном случае пользователи не будут определены	/etc/pangolin-pooler/userlist.txt
auth_user	Если задан auth_user, то любой пользователь, не указанный в auth_file, будет запрашиваться через запрос auth_query из pg_authid в базе данных, используя auth_user. Пароль auth_user будет взят из auth_file. Если auth_user не требует пароля, то его не нужно определять в auth_file. Прямой доступ к pg_authid требует прав администратора. Предпочтительнее использовать не суперпользователя, который вместо этого вызывает функцию SECURITY DEFINER	Не задано
auth_query	Запрос для загрузки пароля пользователя из базы данных. Прямой доступ к pg_authid требует прав администратора. Предпочтительнее использовать не суперпользователя, который вместо этого вызывает функцию SECURITY DEFINER

admonition

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

• SELECT rolname, CASE WHEN rolvaliduntil < pg_catalog.now() THEN NULL ELSE rolpassword END FROM pg_authid WHERE rolname=$1 AND rolcanlogin

• • auth_dbname
  • Имя базы данных в разделе [database] для использования в целях аутентификации. Этот параметр может быть как глобальным, так и переопределенным в строке подключения, если он указан

  • Не задано

    :::

Сквозная аутентификация

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

Параметр	Описание	Значение по умолчанию
auth_proxy	Регулирует активацию режима сквозной аутентификации	off
auth_failure_threshold	Задает максимальное число не аутентифицированного N раз подряд клиента с идентичными параметрами (тип соединения, адрес клиента, база данных и имя пользователя), при котором будет взведен таймер не активности аутентификации для этого клиента	0 (выключено)
auth_inactivity_period	Определяет время, в течение которого ранее не аутентифицированному более N раз подряд клиенту при подключении с идентичными параметрами (тип соединения, адрес клиента, база данных и имя пользователя), Pangolin Pooler откажет в обслуживании	0 (в секундах)
auth_last_size	Задает максимальное число кешируемых записей о последних аутентификациях пользователей. Информацию о последних аутентификациях пользователей можно получить с помощью команды SHOW LAST	10
log_audit	Включает или выключает аудит	off

Настройки журнала

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

Параметр	Описание	Значение по умолчанию
syslog	Включение и выключение syslog	0
syslog_ident	Под каким именем отправлять журналы в syslog	pangolin-pooler
syslog_facility	Под каким объектом отправлять журналы в syslog. Возможные варианты: auth, authpriv, daemon, user, local0-7	daemon
log_connections	Вести журнал успешных входов в систему	1
log_disconnections	Вести журнал отключений с указанием причин	1
log_pooler_errors	Вести журнал сообщений об ошибках, которые пулер отправляет клиентам	1
log_stats	Запись агрегированной статистики в журнал, каждый stats_period. Эту функцию можно отключить, если используются внешние инструменты мониторинга для получения тех же данных из команд SHOW	1
verbose	Повысить многословность. Аналогично переключателю -v в командной строке. Например, использование -v -v в командной строке равносильно verbose=2	0
show_period	Вывода результата команды SHOW POOLS в лог-файл компонента Pangolin Pooler (по умолчанию – pangolin-pooler.log). Подробнее в подразделе «Настройка вывода команды SHOW POOLS в лог Pangolin Pooler»	0

Управление доступом к консоли

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

Параметр	Описание	Значение по умолчанию
admin_users	Список пользователей базы данных, которым разрешено подключаться и выполнять все команды в консоли. Разделен запятыми. Игнорируется, если auth_type имеет значение any, в этом случае любое имя пользователя может быть допущено в качестве администратора	Пусто
stats_users	Список пользователей базы данных (разделен запятыми), которым разрешено подключаться и выполнять запросы в консоли только для чтения, а также все команды SHOW, кроме SHOW FDS	Пусто

Проверки целостности соединений, тайм-ауты

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

Параметр	Описание	Значение по умолчанию
server_reset_query	Запрос отправляется на сервер при разрыве соединения, прежде чем сделать его доступным для других клиентов. В этот момент ни одна транзакция не выполняется, поэтому значение не должно включать ABORT или ROLLBACK. Когда используется пул транзакций, server_reset_query не используется, потому что в этом режиме клиенты не должны использовать никакие функции, основанные на сеансах, поскольку каждая транзакция завершается в отдельном соединении и, следовательно, получает отдельное состояние сеанса	DISCARD ALL
server_reset_query_always	Определяет, должен ли server_reset_query выполняться во всех режимах пулов. Если этот параметр выключен (по умолчанию), запрос server_reset_query будет выполняться только в пулах, находящихся в режиме session-pooling. Соединения в режиме пула транзакций не должны нуждаться в запросе сброса	0
server_check_delay	Определяет, как долго держать освобожденные соединения доступными для немедленного повторного использования без выполнения server_check_query. Значение 0 означает, что проверка выполняется всегда	30.0
server_check_query	Простой запрос, не требующий никаких действий, для проверки того, имеется ли соединение с сервером. Если строка пустая, то проверка отключена	SELECT 1
server_fast_close	Отключить сервер в режиме пула сессий сразу или после завершения текущей транзакции, если он находится в режиме close_need (установленном с помощью RECONNECT, RELOAD, изменяющего настройки соединения, или изменения DNS), вместо того чтобы ждать окончания сессии. В режиме пула операторов или транзакций это не используется, так как там это поведение используется по умолчанию	0
server_lifetime	Пулер закроет неиспользуемое (не связанное в данный момент ни с одним клиентским соединением) серверное соединение, которое было подключено дольше, чем это значение. Установка значения 0 означает, что соединение будет использовано только один раз, а затем закрыто	3600.0 (секунды)
server_idle_timeout	Если соединение с сервером простаивает больше указанного количества секунд, оно будет закрыто. Значение 0 означает, что тайм-аут отключен	600.0 (секунды)
server_connect_timeout	Если соединение и вход в систему не завершатся за это время, соединение будет закрыто	15.0 (секунды)
server_login_retry	Если вход на сервер не удался из-за сбоя подключения или аутентификации, пулер ждет столько времени, сколько указано в server_login_retry, прежде чем повторить попытку подключения. В течение интервала ожидания, новые клиенты, пытающиеся подключиться к неудачному серверу, сразу получат ошибку без повторной попытки подключения	15.0 (секунды)
client_login_timeout	Если клиент подключается, но не успевает войти в систему за время client_login_timeout, он будет отключен. В основном это необходимо для того, чтобы не допустить остановки SUSPEND и, соответственно, перезапуска в режиме онлайн	60.0 (секунды)
autodb_idle_timeout	Если автоматически созданные (через *) пулы баз данных не использовались в течение autodb_idle_timeout секунд, они освобождаются	3600.0 (секунды)
dns_max_ttl	Продолжительность кеширования DNS-поисков. Фактическое значение DNS TTL игнорируется	15.0 (секунды)
dns_nxdomain_ttl	Как долго могут кешироваться ошибки DNS и поиск DNS NXDOMAIN	15.0 (секунды)
dns_zone_check_period	Период проверки изменения серийного номера зоны. Pooler может собирать DNS-зоны из имен хостов (все после первой точки), а затем периодически проверять, не изменилась ли последовательность зон. Если он замечает изменения, все имена хостов в этой зоне просматриваются заново. Если IP-адрес какого-либо хоста изменится, его соединения будут аннулированы. Работает только с бэкендом c-ares (опция конфигурации --with-cares)	0.0 (отключено, задается в секундах)
max_client_route_allowed	Определяет максимальное количество переходов состояний клиентских подключений (см. SHOW CLIENTS). Используется в диагностических целях	1024
resolv_conf	Расположение пользовательского файла resolv.conf. Параметр позволяет указывать пользовательские DNS-серверы и другие параметры разрешения имен независимо от глобальной конфигурации операционной системы. Разбор файла выполняется библиотекой бэкенда DNS, а не Pangolin Pooler, поэтому подробности о допустимом синтаксисе и директивах смотрите в документации к библиотеке	/etc/pangolin-pooler/resolv.conf

Настройки TLS

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

Параметр	Описание	Значение по умолчанию
client_tls_sslmode	По умолчанию TLS-соединения отключены. При включении необходимо также настроить client_tls_key_file и client_tls_cert_file, чтобы задать ключ и сертификат, которые Pooler использует для приема клиентских соединений. Наиболее распространенный формат файла сертификата — pem. Возможные значения: - disable — обычный TCP. Если клиент запрашивает TLS, игнорируется. Установлен по умолчанию; - allow — используется, если клиент запрашивает TLS, иначе используется обычный TCP. Если клиент предъявляет сертификат клиента, он не проверяется; - prefer — то же, что allow; - require — клиент должен использовать TLS. В противном случае клиентское соединение будет отклонено. Если клиент предъявляет сертификат клиента, он не проверяется; - verify-ca — сертификат клиента проверяется на валидность; - verify-full — то же, что и verify-ca.	disable
client_tls_key_file	Приватный ключ для Pangolin Pooler для приема клиентских соединений	Не задано
client_tls_cert_file	Сертификат для закрытого ключа. Клиенты могут подтвердить его	Не задано
client_tls_ca_file	Файл корневого сертификата для проверки клиентских сертификатов	Не задано
client_tls_protocols	Разрешенные версии протокола TLS. Минимальная версия – 1.2. Допустимые значения: tlsv1.2, tlsv1.3. Сокращения: secure (tlsv1.2, tlsv1.3)	secure
client_tls_ciphers	Разрешенные шифры TLS в синтаксисе OpenSSL. Сокращения: - default/secure/fast/normal (все они используют системные настройки OpenSSL по умолчанию); - all (включает все шифры, не рекомендуется). Затронуты только соединения, использующие TLS версии 1.2 и ниже. В настоящее время не существует настройки, контролирующей выбор шифров, используемых соединениями TLS версии 1.3	default
client_tls_ecdhcurve	Имя эллиптической кривой, используемой для обмена ключами ECDH. Допустимые значения: none (DH отключен), auto (256-битный ECDH), имя кривой	auto
client_tls_dheparams	Тип обмена ключами DHE. Допустимые значения: none (DH отключен), auto (2048-битный DH), legacy (1024-битный DH)	auto
server_tls_sslmode	Режим TLS, используемый для соединений с серверами СУБД. Возможные значения: - disable — обычный TCP. TLS даже не запрашивается у сервера; - allow — если сервер отклоняет обычную версию, попробовать использовать TLS; - prefer — TLS-соединение всегда запрашивается первым у СУБД. В случае отказа соединение будет установлено по классическому TCP. Сертификат сервера не проверяется. Используется по умолчанию; - require — соединение должно проходить по протоколу TLS. Если сервер отклоняет его, попытка обычного TCP не предпринимается. Сертификат сервера не проверяется; - verify-ca — соединение должно осуществляться по протоколу TLS, а сертификат сервера должен быть действителен в соответствии с файлом server_tls_ca_file. Имя хоста сервера не проверяется на соответствие сертификату; - verify-full — соединение должно осуществляться по протоколу TLS, а сертификат сервера должен быть действителен в соответствии с файлом server_tls_ca_file. Имя хоста сервера должно соответствовать информации сертификата.	prefer
server_tls_ca_file	Файл корневого сертификата для проверки сертификатов сервера	Не задано
server_tls_key_file	Закрытый ключ для аутентификации пулера на сервере	Не задано
server_tls_cert_file	Сертификат для закрытого ключа. Сервер может подтвердить его	Не задано
server_tls_protocols	Разрешенные версии протокола TLS. Допустимые значения: tlsv1.2, tlsv1.3. Сокращения: secure (tlsv1.2, tlsv1.3)	secure
server_tls_ciphers	Разрешенные шифры TLS в синтаксисе OpenSSL. Сокращения: - default/secure/fast/normal (все они используют системные настройки OpenSSL по умолчанию); - all (включает все шифры, не рекомендуется). Затронуты только соединения, использующие TLS версии 1.2 и ниже. В настоящее время не существует настройки, контролирующей выбор шифров, используемых соединениями TLS версии 1.3	default
ssl_legacy_provider	Параметр управляет активацией устаревших алгоритмов через подгрузку провайдера Legacy в OpenSSL 3.0.0+ (аналог Engine API в OpenSSL 1.+) при запуске компонента. Это необходимо для обеспечения обратной совместимости с компонентами, использующими OpenSSL 1.+	1

Опасные тайм-ауты

Внимание!

Установка тайм-аутов, указанных в таблице, может привести к непредвиденным ошибкам.

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

Параметр	Описание	Значение по умолчанию
query_timeout	Запросы, выполняющиеся дольше этого времени, отменяются. Следует использовать только при немного меньшем размере серверной части statement_timeout, чтобы применять только для сетевых проблем	0.0 (отключено, задается в секундах)
query_wait_timeout	Максимальное время, которое запросы могут провести в ожидании выполнения. Если за это время запрос не будет назначен серверу, клиент отключается. Значение 0 отключает параметр, что означает для клиентов неограниченное время ожидания в очереди. Настройка используется для предотвращения захвата соединений невосприимчивыми серверами, помогает, когда сервер не работает или отклоняет соединения по какой-либо причине	120.0 (секунды)
cancel_wait_timeout	Максимальное время, которое запросы на отмену могут провести в ожидании выполнения. Если за это время запрос на отмену не будет назначен серверу, клиент отключается. В случае значения параметра '0' запросы на отмену будут ставиться в очередь бесконечно. Эта настройка используется для предотвращения блокировки клиента, когда отмена не может быть переслана из-за нерабочего состояния сервера.	10.0 (секунды)
client_idle_timeout	Клиентские соединения, простаивающие дольше этого количества секунд, закрываются. Значение должно быть больше, чем настройки времени жизни соединения на стороне клиента, используется только при проблемах с сетью	0.0 (отключено, задается в секундах)
idle_transaction_timeout	Если клиент находится в состоянии «простоя в транзакции» дольше чем это значение, он будет отключен	0.0 (отключено, задается в секундах)
suspend_timeout	Сколько времени ждать очистки буфера при SUSPEND или перезагрузке (-R). Соединение будет разорвано, если очистка не удалась	10 (секунды)

Низкоуровневые сетевые настройки

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

Параметр	Описание	Значение по умолчанию
pkt_buf	Размер внутреннего буфера для пакетов. Влияет на размер отправляемых TCP-пакетов и общее использование памяти. Фактические пакеты libpq могут быть больше этого размера, поэтому нет необходимости устанавливать его большим	4096
max_packet_size	Максимальный размер пакетов СУБД, которые пропускает Pooler. Один пакет — это либо один запрос, либо одна строка набора результатов. Полный набор результатов может быть больше	2147483647 (не ограничено)
listen_backlog	Аргумент backlog для listen(2). Определяет, сколько новых попыток соединения, не получивших ответа, будет храниться в очереди. Когда очередь переполнена, новые соединения отбрасываются	128
sbuf_loopcnt	Сколько раз нужно обработать данные на одном соединении, прежде чем продолжить работу. Без этого ограничения одно соединение с большим набором результатов может надолго замедлить Pangolin Pooler. Один цикл обрабатывает один pkt_buf данных. Значение 0 означает отсутствие ограничения	5
so_reuseport	Указывает, устанавливать ли параметр сокета SO_REUSEPORT для сокетов, прослушивающих TCP. В некоторых операционных системах это позволяет запустить несколько экземпляров пулера на одном хосте, прослушивающих один и тот же порт, и заставить ядро автоматически распределять соединения. Эта опция — способ заставить Pangolin Pooler использовать больше ядер процессора (Pooler является однопоточным и использует одно ядро процессора на экземпляр)	0
tcp_defer_accept	Устанавливает опцию сокета TCP_DEFER_ACCEPT. Это булева опция: 1 означает включено. Фактическое значение, установленное при включении, в настоящее время закодировано строго на 45 секунд	1
tcp_socket_buffer	—	Не задано
tcp_keepalive	Включает базовый keepalive с настройками ОС по умолчанию	1
tcp_keepcnt	—	Не задано
tcp_keepidle	—	Не задано
tcp_keepintvl	—	Не задано
tcp_user_timeout	Устанавливает параметр сокета TCP_USER_TIMEOUT. Задает максимальное время в миллисекундах, в течение которого переданные данные могут оставаться непризнанными, прежде чем TCP-соединение будет принудительно закрыто. Если установлено значение 0, то используется значение по умолчанию операционной системы	0

Раздел [databases]

Раздел [databases] определяет имена баз данных, к которым могут подключаться клиенты Pooler, и указывает, куда будут направляться эти соединения. Раздел содержит строки типа ключ=значение:

dbname = connection string

Где в качестве ключа будет взято имя базы данных, а в качестве значения — строка подключения, состоящая из пар ключ=значение параметров подключения (представлены далее в таблице).

Имя базы данных может содержать символы _0-9A-Za-z без кавычек. Имена, содержащие другие символы, должны быть заключены в стандартные кавычки идентификатора SQL – двойные кавычки. При использовании внутри имени БД один экземпляр двойной кавычки ("), необходимо оформлять как двойные парные кавычки ("").

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

* = host=foo

Тогда подключение к Pangolin Pooler с указанием базы данных bar будет вести себя так, как если следующая запись существует (пользуясь тем, что по умолчанию dbname — это имя базы данных на стороне клиента):

bar = host=foo dbname=bar

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

:

Параметр	Описание	Значение
dbname	Имя базы данных назначения	По умолчанию: То же, что и имя базы данных на стороне клиента
host	Имя хоста или IP-адрес для подключения Имена хостов разрешаются во время соединения, результат кешируется в соответствии с параметром dns_max_ttl. При изменении разрешения имени хоста существующие серверные соединения автоматически закрываются при их освобождении (в соответствии с режимом пула), а новые серверные соединения сразу используют новое разрешение. Если DNS возвращает несколько результатов, они используются поочередно.

admonition :class: attention В списке все хосты должны быть доступны в любое время: нет никаких механизмов для пропуска недоступных хостов или для выбора только доступных хостов из списка. Также это влияет только на то, как выбираются места назначения новых соединений. Изучите параметр server_round_robin для определения того, как клиенты назначаются на уже установленные серверные соединения.

::

• По умолчанию: не задано, что означает использование сокета Unix.

  Если значение начинается с /, то используется сокет Unix в пространстве имен файловой системы. Если значение начинается с @, то используется сокет Unix в абстрактном пространстве имен.

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

• • port
  • –
  • По умолчанию: 5433

• • user

  • Если установлено значение user=, все соединения с базой данных назначения будут осуществляться с указанным пользователем, что означает, что для этой базы данных будет существовать только один пул.

    В противном случае Pooler входит в базу данных назначения с именем пользователя клиента, а значит на одного пользователя будет приходиться один пул
• • password
  • Если пароль здесь не указан, будет использован пароль из файла auth_file или auth_query

• • auth_port

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

    Ознакомьтесь с разделом «Cквозная аутентификация»

  • По умолчанию 5544

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

• • auth_pool_size

  • Параметр задает максимальное количество соединений для выполнения аутентификации пользователей.

    Ознакомьтесь с разделом «Cквозная аутентификация»

  • 1

• • pool_size
  • Устанавливает максимальный размер пулов для этой базы данных.
  • Если не задано, используется значение default_pool_size

• • min_pool_size

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

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

    • в этой записи в разделе [database] установлено значение для ключа user (он же системный пользователь подключений);
    • есть хотя бы один клиент, подключенный к пулу

  • Если не задан, используется глобальный min_pool_size

• • reserve_pool_size
  • Установка дополнительных соединений для этой базы данных. По соображениям обратной совместимости reserve_pool является псевдонимом для этого параметра
  • Если не задано, используется reserve_pool_size
• • connect_query
  • Запрос, выполняемый после установления соединения, но перед тем, как разрешить использовать соединение любым клиентам. Если запрос вызывает ошибки, они записываются в журнал, но в противном случае игнорируются
• • pool_mode
  • Устанавливает режим пула, характерный для этой базы данных
  • Если не задан, используется режим пула по умолчанию

• • load_balance_hosts

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

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

    Рекомендуется установить значение server_login_retry ниже, чем по умолчанию, чтобы обеспечить быструю повторную попытку при наличии нескольких хостов

  • round-robin

• • max_db_connections
  • Настраивает максимальное значение для всей базы данных, то есть все пулы в базе данных не будут иметь больше этого количества соединений с сервером
• • server_lifetime
  • Настраивает время жизни сервера для каждой базы данных
  • Если значение не задано, база данных будет использовать значение времени жизни сервера, настроенное для всего экземпляра
• • client_encoding
  • Запрашивает у сервера использование указанной клиентской кодировки (client_encoding)
• • datestyle
  • Запрашивает у сервера использование указанного стиля даты (datestyle)
• • timezone
  • Запрашивает у сервера использование указанного часового пояса (timezone)

::::

Раздел [users]

Этот раздел содержит строки с парами ключ=значение:

user1 = settings

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

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

Внимание!

При настройке auth_file, если пользователь указан в этом разделе, но не указан в auth_file (userlist.txt), Pangolin Pooler попытается использовать auth_query для поиска пароля для этого пользователя, если установлен auth_user. Если auth_user не установлен, Pooler будет имитировать, что пользователь существует, не сможет вернуть клиенту сообщения «такого пользователя нет», но и не будет принимать указанный пароль.

Внимание!

Сквозная аутентификация не работает для пользователей, которые указаны в секции [users].

Параметр	Описание	Значение
pool_size	Задайте максимальный размер пула для всех подключений от этого пользователя	Если значение не задано, используется база данных или default_pool_size
reserve_pool_size	Задайте количество дополнительных подключений к пулу для этого пользователя	Если значение не задано, используется конфигурация базы данных или глобальный параметр reserve_pool_size
pool_mode	Устанавливает режим пула, который будет использоваться для всех соединений от этого пользователя	Если он не задан, используется режим пула базы данных или режим пула по умолчанию
max_user_connections	Задает максимум для пользователя, то есть все пулы с этим пользователем не будут иметь больше этого количества подключений к серверу
query_timeout	Задает максимальное количество секунд, в течение которых может выполняться пользовательский запрос	Если этот тайм-аут установлен, он переопределяет значение на уровне сервера
idle_transaction_timeout	Задает максимальное количество секунд, в течение которых пользователь может держать транзакцию в режиме ожидания	Если этот тайм-аут установлен, он переопределяет значение на уровне сервера
client_idle_timeout	Задает максимальное время в секундах, в течение которого клиент может бездействовать при подключении к экземпляру компонента	Если этот тайм-аут установлен, он переопределяет значение на уровне сервера
max_user_client_connections	Настройте максимальное количество клиентских подключений для пользователя. Это пользовательский эквивалент параметра max_client_conn

Раздел [peers]

В разделе [peers] определяются пиры, которым Pangolin Pooler может пересылать запросы на отмену и куда эти запросы будут направляться.

Раздел содержит строки с парами ключ=значение:

peer_id = connection string

Параметр	Описание	Значение
host	Имя хоста или IP-адрес для подключения
port	–	По умолчанию: 5433
pool_size	Устанавливает максимальное количество запросов на отмену, которые могут одновременно поступать к пиру. Запросы на отмену обычно поступают пакетами, например, когда резервный сервер СУБД «медленный» или не работает. Поэтому важно, чтобы размер пула (pool_size) не был настолько мал, чтобы он не мог справиться с данными поступающими пакетами	Если значение не задано, то по умолчанию используется default_pool_size

Поддержка подготовленных запросов

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

Параметр	Описание	Значение по умолчанию
session_region_id	Идентификатор региона для клиентских сессий, генерируемый алгоритмом snowflakeID, 0-23	0
session_worker_id	Идентификатор обработчика для клиентских сессий, генерируемый алгоритмом snowflakeID, 0-1023	1

Примечание

Необходимость отдельного session_worker_id обусловлена возможностью запуска на одном узле нескольких процессов Pangolin Pooler. Для разделения множества идентификаторов между такими процессами используется параметр session_worker_id - свой для каждого процесса узла компонента Pangolin Pooler (session_region_id).

Необходимо учитывать что каждый узел кластера должен иметь свое значение параметра session_region_id.

Кеширования серверных и клиентских сертификатов

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

Параметр	Описание	Значение по умолчанию
client_tls_enable_vault_certificates_cache	Определяет необходимость кеширования клиентских сертификатов в Pangolin Pooler	0 (не используется)
server_tls_enable_vault_certificates_cache	Определяет необходимость кеширования серверных сертификатов в Pangolin Pooler	0 (не используется)

Поддержка CRL

В таблице ниже приведены конфигурационные параметры, отвечающие за поддержку CRL.

Параметр	Описание	Значение по умолчанию
client_tls_crl_file	Путь к файлу CRL	Не задано
client_tls_crl_path	Путь к директории с файлами CRL, по которым выполняется проверка аннулирования клиентских сертификатов	Не задано
server_tls_crl_file	Путь к файлу CRL	Не задано
server_tls_crl_path	Путь к директории с файлами CRL, по которым выполняется проверка аннулирования серверного сертификата Pangolin	Не задано

Управление сертификатами PKCS#12

В таблице ниже приведены конфигурационные параметры, отвечающие за функциональность «Использование и управление сертификатами PKCS#12».

Параметр	Описание	Значение по умолчанию
client_tls_pkcs12_config_path	Путь к конфигурационному файлу в JSON-формате, содержащему данные для генерации сертификата	Не задано
server_tls_pkcs12_config_path	Путь к конфигурационному файлу в JSON-формате, содержащему данные для генерации сертификата	Не задано

Файл аутентификации userlist.txt

Формат файла, заданного параметром auth_file - userlist.txt. Это текстовый файл в следующем формате:

"username2" "md5abcdef012342345" ...
"username2" "SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>"

Должно быть не менее двух полей, заключенных в двойные кавычки. Первое поле — имя пользователя, а второе — пароль в открытом виде, MD5-хеш или SCRAM-секрет. Pangolin Pooler игнорирует остальную часть строки. Двойные кавычки в значении поля можно экранировать, написав две двойные кавычки.

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

Конфигурирование userlist.txt

1. Измените файл userlist.txt (путь к файлу /etc/pangolin-pooler/userlist.txt) при помощи текстового редактора, добавив следующие строки:

   "<user>" "<password>"

   Пример файла userlist.txt:

   "user" "qwerty"

   Или в засекреченном виде:

   "user" "md5175c641eaed0b6c05ae8444b73d789f0"

2. Измените права и владельца файла:

   sudo chown postgres:postgres /etc/pangolin-pooler/userlist.txt
   sudo chmod 0600 /etc/pangolin-pooler/userlist.txt

Конфигурирование SSL-соединения

Pangolin Pooler позволяет устанавливать защищенное соединение по протоколу SSL (а именно TLS версии 1.2) между клиентами и Pangolin Pooler, и между СУБД и Pangolin Pooler. Для того, чтобы защищенное соединение работало, необходимо провести конфигурирование параметров в Pangolin Pooler и в СУБД Pangolin, а также иметь:

• сертификат x509 и закрытый ключ для каждого сервера БД;
• сертификат x509 удостоверяющего центра(УЦ);
• сертификат и закрытый ключ клиента;
• CRL-файлы удостоверяющих центров для проверки сертификатов по спискам отозванных сертификатов.

Настройка СУБД Pangolin

После выпуска сертификатов, в конфигурационном файле postgresql.conf необходимо указать пути к сертификату и закрытому ключу сервера, корневого сертификата и, при необходимости, список отозванных сертификатов. После, чтобы включить шифрование, нужно установить параметр в конфигурационном файле ssl = 'on' и перезагрузить сервер. После этого, с СУБД можно будет установить как зашифрованное, так и базовое соединение, в зависимости от того, какие способы разрешены в pg_hba.conf.

Для аутентификации клиента необходимо выпустить сертификат клиента, после чего передавать его при помощи драйвера (например jdbc, который использует параметры sslcert, sslkey, sslrootcert и sslmode). Этого достаточно, чтобы начать использовать TLS и mTLS в Pangolin.

Проверить, какое соединение было установлено можно SQL-запросом:

postgres=# CREATE EXTENSION sslinfo;

CREATE EXTENSION

postgres=# SELECT a.current_user, b.ssl_version FROM (SELECT current_user AS current_user) a,(SELECT ssl_version() AS ssl_version) b;

 current_user | ssl_version
--------------+-------------
 postgres     | TLSv1.2

Настройка Pangolin Pooler

В pangolin-pooler.ini добавьте секцию TLS-настроек и настройте параметры защищенного соединения.

примечание

Между Pangolin Pooler и СУБД Pangolin настраивается SSL-соединение, между Pangolin Pooler и клиентом — по требованию клиента. В обоих случаях минимальная версия TLS 1.2.