Настройка

Конфигурирование 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 представлены в разделе далее.

Для применения изменений конфигурации компонента Pangolin 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. Внимание! Установка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, на которого следует перейти после запуска. Работает, только если Pangolin Pooler запущен от имени root или если он уже запущен от имени указанного пользователя	Не задано
pool_mode	Определяет, когда соединение с сервером может быть повторно использовано другими клиентами: session – соединение возвращается в пул после отключения клиента; transaction – соединение возвращается в пул после завершения транзакции; statement – соединение освобождается обратно в пул после завершения запроса. Транзакции, охватывающие несколько операторов, в этом режиме запрещены Предупреждение! Режимpool_mode = session несовместим с параметром СУБД shared_prepared_statements = on. Такая комбинация может привести к блокировкам (LWLock ClientSessionsSharedAccess) и недоступности экземпляра БД под нагрузкой. Используйте shared_prepared_statements = off при pool_mode = session.	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	Определяет принцип соединения с сервером. По умолчанию Pangolin Pooler использует принцип LIFO (last-in, first-out), так что наибольшая нагрузка распределяется по небольшому количеству соединений. Это обеспечивает наилучшую производительность, если есть только один сервер, обслуживающий базу данных. Но если за адресом базы данных стоит система round-robin (TCP, DNS или список хостов), то рекомендуется включать круговую балансировку, чтобы равномерно распределять нагрузку между всеми доступными серверами	0
track_extra_parameters	Список дополнительных параметров, которые должны отслеживаться пулером и применяться индивидуально для каждого клиента. По умолчанию Pangolin Pooler отслеживает параметры client_encoding, datestyle, timezone, standard_conforming_strings и application_name для каждого клиента. Для отслеживания других параметров, их можно указать здесь, чтобы пулер учитывал, что они должны сохраняться в кеше клиентских переменных и восстанавливаться на сервере всякий раз, когда клиент становится активным. Если нужно указать несколько значений, используется список, разделенный запятыми (например, default_transaction_readonly, IntervalStyle)	IntervalStyle
ignore_startup_parameters	Перечень дополнительных параметров, принимаемых пулером при старте соединения. По умолчанию Pangolin Pooler разрешает использовать в стартовых пакетах только те параметры, которые он может отслеживать: client_encoding, datestyle, timezone и standard_conforming_strings. Все остальные параметры приведут к ошибке. Чтобы разрешить другие параметры, их можно указать в ignore_startup_parameters, чтобы компонент Pangolin Pooler учитывал, что они обрабатываются администратором, и мог их игнорировать. Если нужно указать несколько значений, используется список, разделенный запятыми (например: options, extra_float_digits)	extra_float_digits
peer_id	Идентификатор пира, используемый для распознавания данного процесса pangolin-pooler в группе запущенных вместе процессов. Значение peer_id должно быть уникальным в группе запущенных вместе процессов pangolin-pooler. При значении 0 пиринг Pangolin 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, Pangolin Pooler не будет изменять его снова	0
conffile	Показывает расположение текущего файла конфигурации. Изменение этого параметра заставит Pangolin Pooler использовать другой файл конфигурации для следующего RELOAD/SIGHUP	Файл из командной строки
stats_period	Устанавливает, как часто обновляются средние значения, отображаемые в различных командах SHOW, и как часто агрегированная статистика записывается в журнал (подробнее смотрите log_stats)	60 (в секундах)
max_prepared_statements	Количество подготовленных запросов, поддерживаемых активными на одном серверном соединении. Если значение параметра равно 0, поддержка подготовленных запросов для транзакций и пула запросов отключена. Чтобы добиться максимальной производительности, необходимо, чтобы этот параметр был больше, чем количество часто используемых подготовленных запросов в приложении. Внимание! При использовании функциональности«Поддержка подготовленных запросов» Pangolin Pooler оставьте значение max_prepared_statements = 0. Значение max_prepared_statements больше 0 включает механизм обработки подготовленных запросов, унаследованный от PgBouncer. Одновременное использование этого механизма и функциональности Pangolin Pooler не поддерживается и может привести к некорректной обработке подготовленных запросов. Более подробное описание параметра представлено в исходной документации ядра компонента PgBouncer. Рекомендуется ознакомиться с разделом «Поддержка подготовленных запросов»	0
ndc_suspending_timeout	Содержит значение момента времени старта приложения или получения последней команды NDC_KEEPALIVE. Это значение в основном цикле обработки событий сравнивается с текущим моментом времени и, если разница превышает заданное в конфигурационном файле значение ndc_suspending_timeout, то Pangolin Pooler прерывает все существующие соединения к базам данных и все клиентские соединения, кроме соединений с административной консолью, и переходит в режим NDC_DISALLOWED (поведение аналогичное получению команды NDC_SUSPEND). Рекомендуется ознакомиться с разделом «Поддержка топологии 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 Внимание! Запрос выполняется внутри целевой базы данных. Поэтому, если используется функция, ее необходимо установить в каждую базу данных.	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 (по умолчанию) указывает на то, что нужно ждать завершения клиентской сессии. Значение 1 указывает на то, что нужно закрыть сразу или после текущей транзакции (при этом сеанс клиента тоже разрывается). В режимах transaction-pooling и statement-pooling параметр не используется.	0
server_lifetime	Время жизни неиспользуемого серверного соединения (не привязанного к клиенту), заданное в секундах. Если задано 0, то каждое соединение используется только один раз и сразу закрывается.	3600.0 (секунды)
server_idle_timeout	Тайм-аут, по истечению которого простаивающее соединение с сервером будет закрыто. Значение 0 означает, что тайм-аут отключен	600.0 (секунды)
server_connect_timeout	Максимальное время (в секундах), отведенное на установление соединения с сервером и успешный вход в систему. Если указанные операции не будут выполнены за указанный период, соединение закрывается принудительно	15.0 (секунды)
server_login_retry	Интервал ожидания (в секундах) перед повторной попыткой входа на сервер в случае неуспешного подключения или ошибки аутентификации. В течение интервала ожидания новые запросы на подключение к этому серверу получают ошибку без повторной попытки подключения	15.0 (секунды)
client_login_timeout	Время (в секундах), в течение которого клиент обязан успешно завершить процедуру входа в систему после установки соединения. По истечении указанного срока сессия прерывается, предотвращая остановку SUSPEND и перезапуск в режиме ONLINE	60.0 (секунды)
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	Период проверки изменения серийного номера зоны. Pangolin 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, чтобы задать ключ и сертификат, которые пулер использует для приема клиентских соединений. Наиболее распространенный формат файла сертификата — 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	Максимальный размер пакетов СУБД, которые пропускает пулер. Один пакет — это либо один запрос, либо одна строка набора результатов. Полный набор результатов может быть больше	2147483647 (не ограничено)
listen_backlog	Аргумент backlog для listen(2). Определяет, сколько новых попыток соединения, не получивших ответа, будет храниться в очереди. Когда очередь переполнена, новые соединения отбрасываются	128
sbuf_loopcnt	Максимальное количество циклов обработки данных на одном соединении перед возобновлением работы. Предотвращает длительное торможение Pangolin Pooler из-за соединений с большим набором результатов. Один цикл обрабатывает один pkt_buf данных. Значение 0 означает отсутствие ограничения	5
so_reuseport	Указывает, устанавливать ли параметр сокета SO_REUSEPORT для сокетов, прослушивающих TCP. В некоторых операционных системах это позволяет запустить несколько экземпляров пулера на одном хосте, прослушивающих один и тот же порт, и заставить ядро автоматически распределять соединения. Эта опция — способ заставить Pangolin Pooler использовать больше ядер процессора (Pangolin Pooler является однопоточным и использует одно ядро процессора на экземпляр)	0
tcp_defer_accept	Устанавливает опцию сокета TCP_DEFER_ACCEPT. Это булева опция: 1 означает включено. Фактическое значение, установленное при включении, в настоящее время закодировано строго на 45 секунд	1
tcp_socket_buffer	Размер буферов TCP-сокета для приема и передачи	Не задано
tcp_keepalive	Включает базовый keepalive с настройками ОС по умолчанию	1
tcp_keepcnt	Количество keepalive-проб до разрыва соединения	Не задано
tcp_keepidle	Время простоя (секунды), после которого начинаются keepalive-пробы	Не задано
tcp_keepintvl	Интервал (секунды) между keepalive-пробами	Не задано
tcp_user_timeout	Устанавливает параметр сокета TCP_USER_TIMEOUT. Задает максимальное время в миллисекундах, в течение которого переданные данные могут оставаться непризнанными, прежде чем TCP-соединение будет принудительно закрыто. Если установлено значение 0, то используется значение по умолчанию операционной системы	0

Раздел [databases]

Раздел [databases] определяет имена баз данных, к которым могут подключаться клиенты Pangolin 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 возвращает несколько результатов, они используются поочередно. Внимание! В списке все хосты должны быть доступны в любое время: нет никаких механизмов для пропуска недоступных хостов или для выбора только доступных хостов из списка. Также это влияет только на то, как выбираются места назначения новых соединений. Изучите параметрserver_round_robin для определения того, как клиенты назначаются на уже установленные серверные соединения.	По умолчанию: не задано, что означает использование сокета Unix. Если значение начинается с /, то используется сокет Unix в пространстве имен файловой системы. Если значение начинается с @, то используется сокет Unix в абстрактном пространстве имен. Можно указать список имен или адресов хостов, разделенных запятыми. В этом случае соединения устанавливаются поочередно.
port	Порт подключения	По умолчанию: 5433
user	Если установлено значение user=, все соединения с базой данных назначения будут осуществляться с указанным пользователем, что означает, что для этой базы данных будет существовать только один пул. В противном случае Pangolin 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 не установлен, пулер будет имитировать, что пользователь существует, не сможет вернуть клиенту сообщения «такого пользователя нет», но и не будет принимать указанный пароль.

Внимание!

Сквозная аутентификация не работает для пользователей, которые указаны в секции[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.