Что такое pg_hba.conf и как PostgreSQL принимает решение о подключении
pg_hba.conf — файл управления доступом на основе хоста. На каждое входящее подключение PostgreSQL смотрит в него и решает две вещи: пускать клиента и каким способом проверять его личность. Сервер читает файл при старте и по сигналу SIGHUP, поэтому правки применяются через reload, без перезапуска и обрыва текущих сессий.
Путь зависит от дистрибутива. В Debian и Ubuntu с пакетами PostgreSQL файл лежит внутри каталога данных, но не в стандартном $PGDATA: типичный путь — /etc/postgresql/НОМЕР_ВЕРСИИ/main/pg_hba.conf. В RHEL, Rocky Linux, AlmaLinux и при сборке из исходников файл находится в каталоге данных, то есть $PGDATA/pg_hba.conf. Не угадывайте, спросите сервер:
SHOW hba_file;
Параметры postgresql.conf, которые понадобятся ниже, включая listen_addresses, разобраны в гайде по установке и базовой настройке PostgreSQL.
Чем pg_hba.conf отличается от listen_addresses
listen_addresses в postgresql.conf отвечает на вопрос, на каких интерфейсах сервер слушает TCP. pg_hba.conf отвечает на вопрос, кого с этих адресов пускать и как проверять. Условия нужны одновременно: при listen_addresses = 'localhost' подключение с 10.0.1.5 не установится вообще, и правило host для подсети 10.0.1.0/24 просто не к чему применить.
Значение по умолчанию в большинстве дистрибутивных сборок — 'localhost'. Проверка:
SHOW listen_addresses;
Ожидаемый вывод для типовой установки: localhost. Смена этого параметра требует перезапуска сервера, reload здесь не поможет. Разница в поведении и становится частой причиной путаницы: pg_hba.conf перечитывается по reload, listen_addresses только при старте.
Порядок правил: срабатывает первая совпавшая строка
PostgreSQL читает файл сверху вниз и останавливается на первом правиле, совпавшем по типу подключения, базе, роли и адресу. Дальше по файлу он не идёт, даже если ниже есть более точная строка. Отсюда правило: узкие разрешения ставьте выше широких.
host all all 0.0.0.0/0 scram-sha-256 host appdb app_user 10.0.1.0/24 scram-sha-256
Вторая строка недостижима: подключение с 10.0.1.5 совпадёт с первой. Поменяйте строки местами, и app_user из подсети 10.0.1.0/24 получит своё правило, а остальные адреса пойдут по общей строке. Комментарии с # и пустые строки игнорируются, но порядок значимых строк — часть логики, а не оформление файла.
Структура строки pg_hba.conf: типы подключений и поля правила
Правило состоит из пяти полей, разделённых пробелами или табуляцией:
- тип подключения: local, host, hostssl, hostnossl;
- база данных;
- роль (пользователь);
- адрес клиента, только для сетевых типов;
- метод аутентификации и его параметры.
hostssl appdb,reportdb app_user,analyst 10.0.1.0/24 scram-sha-256
В поле базы работают спецзначения all (все базы), sameuser (база с именем, совпадающим с ролью), samerole; для потока физической репликации указывают отдельное ключевое слово replication. Несколько баз или ролей перечисляют через запятую без пробелов. Перед именем роли можно поставить +, тогда правило сработает для всех членов этой роли.
Если ролей ещё нет, создайте их заранее: команды и разграничение прав собраны в руководстве по пользователям и привилегиям. Правило доступа к несуществующей роли бессмысленно, а опечатка в её имени даёт отказ на входе.
local, host, hostssl и hostnossl: что выбирать
local описывает подключение через Unix-сокет, поле адреса в такой строке отсутствует. host покрывает TCP: и loopback, и внешние адреса, и TLS, если клиент его запросил. hostssl принимает только подключения с установленным TLS, остальные отклоняет. hostnossl, наоборот, только без TLS; нужен редко, например при отладке драйвера.
hostssl сам по себе шифрование не включает. Нужны ssl = on, ssl_cert_file и ssl_key_file в postgresql.conf. Если задача шире, чем аутентификация, смотрите разбор шифрования данных в базах.
Как задавать адрес и подсеть
Адрес задаётся в CIDR: 192.0.2.10/32 для одного хоста, 192.0.2.0/24 для подсети, ::1/128 и 2001:db8::/32 для IPv6. Ключевые слова сокращают запись: all означает любой адрес, samehost покрывает адреса самого сервера, samenet покрывает подсети, к которым он подключён напрямую. Имена хостов допустимы, но требуют обратного DNS-разрешения при каждом подключении, поэтому зависят от состояния DNS и менее предсказуемы.
Два правила под типовую схему: приложение ходит из своей подсети, администратор с одного фиксированного адреса.
host appdb app_user 10.0.1.0/24 scram-sha-256 host all dba_user 203.0.113.7/32 scram-sha-256
0.0.0.0/0 и ::/0 означают любой адрес. Выбирать их осмысленно только при дополнительной защите на уровне сети или файрвола.
Как открыть доступ к PostgreSQL по сети только для нужных подсетей
Разберём типовой случай: PostgreSQL на 10.0.0.5, приложение на хостах в приватной сети 10.0.1.0/24. Выполняйте шаги по порядку и после каждого проверяйте результат.
Почему не стоит ставить 0.0.0.0/0 и listen_addresses = '*'
С такой парой сервер принимает подключения с любого адреса, и вся защита сводится к паролю роли. Один слабый или переиспользованный пароль в конфиге приложения превращается в компрометацию базы. Порт 5432 сканируют постоянно, скрыть его от перебора не получится.
Альтернативы прямому выставлению порта: SSH-туннель до сервера, VPN между сетями, размещение приложения на том же хосте с подключением через localhost, ограничение на уровне security group облака. Ни один из этих способов не требует отключать файрвол или SELinux. При нестандартном порте или каталоге данных проверьте политику SELinux (например, список semanage port -l | grep postgresql), а снимать её как решение проблемы не нужно.
Сделайте копии обоих файлов с датой в имени. Номер версии в пути подставьте свой.
cp /etc/postgresql/16/main/pg_hba.conf /etc/postgresql/16/main/pg_hba.conf.bak-2026-11-20 cp /etc/postgresql/16/main/postgresql.conf /etc/postgresql/16/main/postgresql.conf.bak-2026-11-20
В postgresql.conf перечислите конкретные адреса вместо звёздочки: listen_addresses = 'localhost,10.0.0.5'. Параметр применяется только при старте, поэтому нужен перезапуск. На проде это короткий простой, планируйте его заранее.
Добавьте правило host в pg_hba.conf выше общих строк.
host appdb app_user 10.0.1.0/24 scram-sha-256
Закройте порт 5432 файрволом для всех, кроме подсети приложений. Пример для ufw:
ufw allow from 10.0.1.0/24 to any port 5432 proto tcp ufw status numbered
Пример для firewalld:
firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=10.0.1.0/24 port port=5432 protocol=tcp accept' firewall-cmd --reload firewall-cmd --list-rich-rules
Для nftables добавьте аналогичное правило в цепочку input вашей таблицы: имена таблиц и цепочек зависят от текущей конфигурации. Перед правкой файрвола на удалённом сервере проверьте, что доступ по SSH разрешён и вы не отрежете себя от машины.
Примените правило без перезапуска.
SELECT pg_reload_conf();
Эквиваленты из шелла: pg_ctl reload с указанием каталога данных, для Debian и Ubuntu — pg_ctlcluster 16 main reload или systemctl reload postgresql.
Проверьте подключение с хоста в разрешённой подсети и отказ с хоста вне её.
psql -h 10.0.0.5 -U app_user -d appdb
pg_hba.conf не заменяет файрвол. Правило в файле разрешает подключение, но не скрывает порт: сканирование увидит открытый 5432, если его не закрыть на уровне ОС или сети.
Методы аутентификации PostgreSQL: сравнение scram-sha-256, md5, peer и cert
| Метод | Где работает | Что проверяет | Когда выбирать |
|---|---|---|---|
| scram-sha-256 | local, host, hostssl | пароль по протоколу SCRAM, в каталоге хранятся соль и хеш | по умолчанию для всех подключений по паролю |
| md5 | local, host, hostssl | устаревший хеш пароля | только для совместимости со старым клиентом, для новых установок не выбирать |
| peer | только local | имя пользователя ОС совпадает с именем роли | администрирование через sudo -u postgres psql |
| cert | hostssl | клиентский TLS-сертификат | когда есть PKI и пароли в конфигах приложений нежелательны |
| trust | любой | ничего, пускает без проверки | не использовать на адресах, доступных по сети |
| reject | любой | ничего, отклоняет подключение | явный запрет для группы адресов или ролей |
Для новых установок и для действующих парольных правил выбирайте scram-sha-256. Задайте password_encryption = 'scram-sha-256' в postgresql.conf, чтобы новые пароли сразу хешировались по SCRAM, и переведите роли на новые хеши до правки pg_hba.conf.
Почему md5 устарел и что делать со старыми паролями
md5 хранит пароль в виде хеша по старой схеме и не даёт той же стойкости к перехвату и офлайн-подбору, что SCRAM. Поддержку SCRAM-SHA-256 добавили в PostgreSQL 10: она обеспечивает лучшую безопасность при согласовании и хранении паролей, чем прежний метод md5 (Release Notes PostgreSQL 10.0). Поведение новых мажорных веток сверяйте с документацией вашей версии: требования к старым методам там постепенно ужесточают.
Главная ловушка перехода: хеш, посчитанный по md5, для SCRAM не подходит. Если поменять метод в pg_hba.conf раньше, чем пароль роли, вход сломается с ошибкой аутентификации. Безопасный порядок такой:
Включите scram для новых паролей и перечитайте конфиг: ALTER SYSTEM SET password_encryption = 'scram-sha-256'; SELECT pg_reload_conf();
Задайте пароли заново для каждой роли, которая ходит по паролю.
ALTER ROLE app_user PASSWORD 'CHANGE_ME_strong_password';
Проверьте тип хеша в системном каталоге.
SELECT rolname, left(rolpassword, 13) FROM pg_authid WHERE rolname = 'app_user';
Ожидаемый результат: SCRAM-SHA-256. Значение с префиксом md5 означает, что пароль не перевыпущен. Запрос требует прав суперпользователя.
Убедитесь, что клиентские драйверы и пулер соединений поддерживают SCRAM. Старые версии библиотек без этой поддержки перестанут подключаться: обновите их до правки pg_hba.conf. Нюансы аутентификации при пулинге разобраны в гайде по PgBouncer.
И только теперь замените md5 на scram-sha-256 в pg_hba.conf и выполните reload.
peer-аутентификация для локальных подключений
peer сравнивает имя пользователя ОС, от которого запущен клиент, с именем роли в PostgreSQL. Работает только для строк local, то есть для Unix-сокета. Типовая строка выглядит так:
local all postgres peer
Она позволяет администратору заходить без пароля командой sudo -u postgres psql. Для сетевых подключений peer не подходит: у клиента с другого хоста нет локального пользователя ОС на сервере. Приложению, которое ходит по TCP, нужен scram-sha-256 или cert.
Метод cert использует клиентские SSL-сертификаты и поэтому доступен только для SSL-соединений. Атрибут CN сертификата сравнивается с запрошенным именем пользователя БД, и при совпадении вход разрешается (Certificate Authentication). Удобен там, где есть PKI и выдача сертификатов автоматизирована: пароли в конфигах приложений тогда не хранят.
Безопасное тестирование изменений: как не потерять доступ к серверу
Ошибка в pg_hba.conf не роняет сервер, но закрывает новые подключения, включая ваше следующее. Существующие сессии продолжают работать, и это главная страховка. Порядок действий:
- Скопируйте pg_hba.conf в файл с датой в имени.
- Держите открытой вторую сессию с правами суперпользователя. Если новая сессия не проходит, вы откатите изменения из старой.
- Применяйте правки через reload, не через restart: перезапуск рвёт все подключения и на проде означает простой.
- Сразу после reload посмотрите pg_hba_file_rules на ошибки разбора.
- Проверьте новое правило из отдельной сессии с удалённого хоста, а не только локально.
- Если доступа нет, верните файл из копии и снова выполните reload.
На продакшене сначала прогоните конфиг на тестовом стенде с той же мажорной версией PostgreSQL и тем же способом подключения. Разница в версии меняет и доступные методы, и поведение представления с разбором правил.
Проверка правил через pg_hba_file_rules
Представление показывает, как сервер разобрал файл: номер строки, список баз, список пользователей и групп, адрес хоста или IP, маску, опции метода и текст ошибки, объясняющий, почему строку не удалось обработать. Строка появляется для каждой непустой некомментированной строки файла (pg_hba_file_rules).
SELECT line_number, database, user_name, address, auth_method, error FROM pg_hba_file_rules ORDER BY line_number;
Непустое поле error означает, что строку не удалось разобрать и правило не работает. Пустой error подтверждает синтаксис, но не прохождение подключения: финальная проверка — реальный вход через psql. Представление доступно только суперпользователям и отражает текущее содержимое файла, а не то, что сервер загрузил последним, поэтому после правок сначала выполните reload.
Чек-лист: проверка подключения с удалённого хоста
- SHOW listen_addresses; показывает ожидаемые адреса, включая тот, на который вы подключаетесь.
- pg_hba_file_rules не содержит строк с заполненным error.
- С хоста в разрешённой подсети проходит psql -h 10.0.0.5 -U app_user -d appdb. Пароль вводится интерактивно: не передавайте его флагом в командной строке, он останется в истории.
- С хоста вне разрешённой подсети подключение отклоняется: либо сообщением об отсутствии записи в pg_hba.conf, либо таймаутом, если порт закрыт файрволом.
- Порт 5432 не отвечает с внешнего адреса. Проверяйте из другой сети, а не с того же сервера.
- В журнале PostgreSQL видны записи об успешных и отклонённых подключениях, если включены log_connections и log_disconnections.
Регулярную проверку привилегий и защиты соединений удобно вести по чек-листу аудита безопасности баз данных: правила pg_hba.conf стоит перечитывать при каждом изменении схемы сети.
Типичные ошибки в pg_hba.conf и как их распознать
| Симптом | Причина | Как проверить |
|---|---|---|
| no pg_hba.conf entry for host ... | нет подходящего правила: не совпали база, роль или адрес, либо выше сработало более широкое | pg_hba_file_rules, затем журнал сервера |
| connection refused | listen_addresses не включает нужный адрес или порт закрыт файрволом | SHOW listen_addresses; ss -lntp | grep 5432 |
| password authentication failed при верном пароле | роль хранит md5-хеш, а в правиле указан scram-sha-256 | префикс rolpassword в pg_authid |
| ошибка про неподдерживаемый метод у клиента | драйвер или пулер не умеет SCRAM | версия драйвера, журнал приложения |
| правило добавлено, поведение прежнее | не выполнен reload | повторить SELECT pg_reload_conf(); и проверить pg_hba_file_rules |
| подсеть не пускает | неверная маска, например /32 вместо /24 | сверить адрес клиента в журнале с полем address |
| клиент с TLS отклонён или, наоборот, пущен без TLS | в правиле hostssl, а клиент без TLS, либо host, который принимает оба варианта | параметры SSL в строке подключения клиента |
Журнал остаётся главным источником: в строке об отказе PostgreSQL указывает, какое правило сработало или что не совпало ни одно. Включите log_connections и log_disconnections в postgresql.conf, если их ещё нет.
Что делать, если доступ уже потерян
Сначала попробуйте открытую ранее сессию с правами суперпользователя: верните pg_hba.conf из копии и выполните SELECT pg_reload_conf();. Если локальный peer-доступ сохранился, заходите через sudo -u postgres psql и правьте файл оттуда.
Когда не осталось ни одной рабочей сессии, остановите сервер и приведите файл в порядок с диска. Крайний вариант — запуск в однопользовательском режиме, порядок описан в документации вашей версии. Остановка сервера означает простой для приложений: принимайте решение осознанно и перед остановкой проверьте, что резервная копия файла на месте.
Короткая шпаргалка: готовые правила и команды проверки
Базовый набор правил: локальное администрирование по peer, приложение из подсети по паролю, TLS-доступ для отдельной группы.
local all postgres peer local all all peer host appdb app_user 10.0.1.0/24 scram-sha-256 hostssl appdb analyst 10.0.2.0/24 scram-sha-256 host all all 0.0.0.0/0 reject
Строка reject в конце отсекает всё, что не совпало выше. Она сработает только при отсутствии более широкого разрешения, поэтому проверяйте порядок строк.
Команды проверки и применения:
SHOW hba_file; SHOW listen_addresses; SELECT pg_reload_conf(); SELECT line_number, database, user_name, address, auth_method, error FROM pg_hba_file_rules ORDER BY line_number; psql -h 10.0.0.5 -U app_user -d appdb
Перед правкой — копия файла, после правки — reload и проверка представления, затем реальное подключение с удалённого хоста. Перезапуск нужен только при смене listen_addresses и других параметров уровня postmaster.
Примеры приведены для актуальных поддерживаемых веток PostgreSQL и требуют сверки с документацией вашей версии и особенностями дистрибутива: пути к файлам и способ перезагрузки кластера там отличаются.