Настройка pg_hba.conf в PostgreSQL: сетевой доступ и методы аутентификации | AdminWiki

Настройка pg_hba.conf в PostgreSQL: сетевой доступ и методы аутентификации

20 ноября 2026 12 мин. чтения
Содержание статьи

Что такое 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: типы подключений и поля правила

Правило состоит из пяти полей, разделённых пробелами или табуляцией:

  1. тип подключения: local, host, hostssl, hostnossl;
  2. база данных;
  3. роль (пользователь);
  4. адрес клиента, только для сетевых типов;
  5. метод аутентификации и его параметры.
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), а снимать её как решение проблемы не нужно.

  1. Сделайте копии обоих файлов с датой в имени. Номер версии в пути подставьте свой.

    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
  2. В postgresql.conf перечислите конкретные адреса вместо звёздочки: listen_addresses = 'localhost,10.0.0.5'. Параметр применяется только при старте, поэтому нужен перезапуск. На проде это короткий простой, планируйте его заранее.

  3. Добавьте правило host в pg_hba.conf выше общих строк.

    host    appdb   app_user   10.0.1.0/24   scram-sha-256
  4. Закройте порт 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 разрешён и вы не отрежете себя от машины.

  5. Примените правило без перезапуска.

    SELECT pg_reload_conf();

    Эквиваленты из шелла: pg_ctl reload с указанием каталога данных, для Debian и Ubuntu — pg_ctlcluster 16 main reload или systemctl reload postgresql.

  6. Проверьте подключение с хоста в разрешённой подсети и отказ с хоста вне её.

    psql -h 10.0.0.5 -U app_user -d appdb

pg_hba.conf не заменяет файрвол. Правило в файле разрешает подключение, но не скрывает порт: сканирование увидит открытый 5432, если его не закрыть на уровне ОС или сети.

Методы аутентификации PostgreSQL: сравнение scram-sha-256, md5, peer и cert

МетодГде работаетЧто проверяетКогда выбирать
scram-sha-256local, host, hostsslпароль по протоколу SCRAM, в каталоге хранятся соль и хешпо умолчанию для всех подключений по паролю
md5local, host, hostsslустаревший хеш паролятолько для совместимости со старым клиентом, для новых установок не выбирать
peerтолько localимя пользователя ОС совпадает с именем ролиадминистрирование через sudo -u postgres psql
certhostsslклиентский 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 раньше, чем пароль роли, вход сломается с ошибкой аутентификации. Безопасный порядок такой:

  1. Включите scram для новых паролей и перечитайте конфиг: ALTER SYSTEM SET password_encryption = 'scram-sha-256'; SELECT pg_reload_conf();

  2. Задайте пароли заново для каждой роли, которая ходит по паролю.

    ALTER ROLE app_user PASSWORD 'CHANGE_ME_strong_password';
  3. Проверьте тип хеша в системном каталоге.

    SELECT rolname, left(rolpassword, 13) FROM pg_authid WHERE rolname = 'app_user';

    Ожидаемый результат: SCRAM-SHA-256. Значение с префиксом md5 означает, что пароль не перевыпущен. Запрос требует прав суперпользователя.

  4. Убедитесь, что клиентские драйверы и пулер соединений поддерживают SCRAM. Старые версии библиотек без этой поддержки перестанут подключаться: обновите их до правки pg_hba.conf. Нюансы аутентификации при пулинге разобраны в гайде по PgBouncer.

  5. И только теперь замените 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 не роняет сервер, но закрывает новые подключения, включая ваше следующее. Существующие сессии продолжают работать, и это главная страховка. Порядок действий:

  1. Скопируйте pg_hba.conf в файл с датой в имени.
  2. Держите открытой вторую сессию с правами суперпользователя. Если новая сессия не проходит, вы откатите изменения из старой.
  3. Применяйте правки через reload, не через restart: перезапуск рвёт все подключения и на проде означает простой.
  4. Сразу после reload посмотрите pg_hba_file_rules на ошибки разбора.
  5. Проверьте новое правило из отдельной сессии с удалённого хоста, а не только локально.
  6. Если доступа нет, верните файл из копии и снова выполните 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 refusedlisten_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 и требуют сверки с документацией вашей версии и особенностями дистрибутива: пути к файлам и способ перезагрузки кластера там отличаются.

Поделиться: