PostgreSQL Remote Access on Gentoo Linux: pg_hba.conf and postgresql.conf
Just a quick note from experience: I once configured network access to a PostgreSQL database running on a waiter POS terminal under Gentoo Linux. After setting it up, I forgot about it, and when I needed to tweak the access rules later, I had to track down where the config lived and recall the exact rule format.
PostgreSQL: configuring local network access
Client authentication and IP filtering in PostgreSQL are controlled by pg_hba.conf, while the network interfaces the server listens on are configured via listen_addresses in postgresql.conf. Below is a complete reference covering where to find these files on Gentoo, how each field in the rules works, and how to reload the configuration without dropping active connections.
Where pg_hba.conf Lives on Gentoo Linux
In a standard non-slotted Gentoo installation, the access control file is typically located in PostgreSQL’s data directory at /var/lib/postgresql/data/pg_hba.conf.
If your system uses slotted Gentoo PostgreSQL packages (multiple versions side by side), configs are usually stored under /etc/postgresql-<version>/pg_hba.conf or /var/lib/postgresql/<version>/data/pg_hba.conf. Instead of searching the filesystem manually, you can ask PostgreSQL directly from psql:
SHOW hba_file; SHOW config_file;
The first query prints the exact path to pg_hba.conf, and the second shows the location of postgresql.conf.
pg_hba.conf Rule Syntax
Authorization rule structure in pg_hba.conf
Each active line in pg_hba.conf defines one authentication rule using five fields (the address field is omitted for local Unix-socket rules):
# TYPE DATABASE USER ADDRESS METHOD
In older PostgreSQL releases, the fourth column header was CIDR-ADDRESS instead of ADDRESS, though the format is identical.
- TYPE – connection type:
localfor local Unix-domain sockets,hostfor TCP/IP (both plain and encrypted),hostsslfor SSL/TLS only, andhostnosslfor unencrypted TCP/IP only. - DATABASE – target database name:
all(any database), a specific database (such aspos_db), or a comma-separated list. - USER – PostgreSQL role/username:
all, a specific role likewaiter, or a group role prefixed with+. - ADDRESS / CIDR – client IP address or subnet in CIDR notation for
hostrules. A single IPv4 host uses a/32mask (e.g.,192.168.0.1/32), while an entire LAN subnet uses/24(192.168.0.0/24). IPv6 addresses follow the same CIDR style, such as::1/128. - METHOD – authentication method used to verify the client.
Choosing an Auth Method: trust vs md5 / scram-sha-256
The authentication method determines whether a password is required and how securely credentials are verified:
- trust – allows anyone matching the rule to connect with no password at all. In the POS terminal setup,
trustis only acceptable for localhost (127.0.0.1/32) or a single dedicated host on an isolated LAN (192.168.0.1/32). Never usetrustfor an entire subnet – any machine on the network would be able to log in as thepostgressuperuser without a password. - md5 – classic challenge-response password authentication using MD5 hashing. Useful when older PostgreSQL servers or legacy POS client libraries do not support newer methods.
- scram-sha-256 – modern, stronger password authentication introduced in PostgreSQL 10 and used by default in current releases. Prefer
scram-sha-256overmd5whenever both server and client support it. - reject – explicitly denies matching connections; handy for blacklisting specific hosts before a broader allow rule.
Here is a practical example where localhost and one trusted terminal connect without a password, while the rest of the 192.168.0.0/24 subnet must authenticate with a password to access a specific database:
# TYPE DATABASE USER ADDRESS METHOD local all all trust host all all 127.0.0.1/32 trust host all all 192.168.0.1/32 trust host pos_db waiter 192.168.0.0/24 scram-sha-256
Rule order matters: PostgreSQL evaluates pg_hba.conf from top to bottom and stops at the first matching record. If a broader rule for 192.168.0.0/24 with reject or md5 appears above a specific rule for 192.168.0.1/32, the lower rule is never reached. Likewise, if authentication fails on a matched line, PostgreSQL does not fall through to subsequent lines.
Configuring listen_addresses in postgresql.conf
Even with a valid rule in pg_hba.conf, remote clients will still get a Connection refused error if PostgreSQL is only bound to the loopback interface. By default, postgresql.conf sets listen_addresses = 'localhost'.
To accept connections over the LAN, edit postgresql.conf and either listen on all interfaces:
listen_addresses = '*'
or bind specifically to localhost and the server’s LAN IP so port 5432 is not exposed on an external interface:
listen_addresses = 'localhost, 192.168.0.10'
Also verify that your local firewall (iptables or nftables) allows incoming TCP traffic on port 5432 from your LAN subnet. You can confirm which addresses PostgreSQL is listening on with:
ss -tlnp | grep 5432
Reloading Configuration Without Downtime
When you only modify pg_hba.conf, there is no need to restart PostgreSQL or interrupt active terminal sessions. A configuration reload applies the updated rules immediately.
On Gentoo using the classic init script:
/etc/init.d/postgresql reload
Or via OpenRC’s rc-service (include the slot suffix if your service is versioned, e.g., postgresql-16):
rc-service postgresql reload
For a distribution-independent reload directly inside psql, run:
SELECT pg_reload_conf();
Keep in mind that changing listen_addresses (or port) in postgresql.conf does require a full service restart rather than a reload:
rc-service postgresql restart
P.S. I wrote this down because I configured it once long ago, forgot the file path, and had to hunt it down all over again. If a client still fails to connect after reloading, check the PostgreSQL log – it records the exact reason, whether a missing pg_hba.conf entry or a password mismatch.