Skip to content

SSL and Domains Updated 2026-05-27

SSL/TLS for PostgreSQL

The Stack Harbor PaaS SSL/TLS encryption-in-transit add-on for PostgreSQL — installation, certificate locations, Pgpool-II configuration, and connecting from a client over SSL.

PostgreSQL environments on the Stack Harbor PaaS support a built-in SSL/TLS add-on that turns on encryption in transit between client and database. After installation, data is encrypted before it leaves the client, the connection endpoints authenticate each other, and the database verifies the integrity of every payload on arrival — without any code changes on your side.

The add-on installs on PostgreSQL nodes and, in clustered topologies, on Pgpool-II load balancer nodes.

Install the add-on

  1. In the dashboard, open the PostgreSQL layer.
  2. Go to Add-Ons.
  3. Click Install on the SSL/TLS Encryption card.
  4. Select the target environment and the node groups. For clusters with Pgpool-II, select both the PostgreSQL layer and the Pgpool-II layer.
  5. Click Install.

The reconfiguration takes about a minute. PostgreSQL is restarted with the new TLS configuration once.

Where certificates live

  • Certificates are generated by the /usr/local/sbin/selfcertgen utility.
  • They are self-signed, issued per node hostname. When you authenticate, use the certificates of the node you connect to.
  • Server and client certificates are stored under /var/lib/stackharbor/keys/SSL-TLS/, with two subdirectories:
    • server/ — server certificates for TLS termination on PostgreSQL
    • client/ — downloadable client certificates for mutual TLS (PostgreSQL nodes only — Pgpool-II does not expose client certificates)

The keys shortcut in the file manager points to the same place.

PostgreSQL configuration changes

Installing the add-on triggers a handful of changes to PostgreSQL configuration:

  • The authentication algorithm is moved from md5 to scram-sha-256 — the PostgreSQL project’s recommended default and a requirement for SSL with Pgpool-II clusters.
  • If md5 was the global default before, it is replaced everywhere in postgresql.conf.
  • postgresql.conf is appended with the TLS paths:
ssl_cert_file = '/var/lib/stackharbor/keys/SSL-TLS/server/server.crt'
ssl_ca_file   = '/var/lib/stackharbor/keys/SSL-TLS/server/root.crt'
ssl_key_file  = '/var/lib/stackharbor/keys/SSL-TLS/server/server.key'
ssl           = on
  • Existing user passwords need to be re-hashed under the new algorithm. The default webadmin user is reset automatically to the same password as before. Custom users must reset their password manually with ALTER ROLE.
  • pg_hba.conf is updated to use hostssl instead of host:
hostssl all all 0.0.0.0/0 scram-sha-256
  • To enable client-certificate authentication on top of password auth, change the auth method in pg_hba.conf to cert.

Pgpool-II configuration changes

In clustered topologies with Pgpool-II, the add-on enables SSL in /etc/pgpool-II/pgpool.conf:

ssl = on
enable_pool_hba = on
ssl_key = '/var/lib/stackharbor/keys/SSL-TLS/server/server.key'
ssl_cert = '/var/lib/stackharbor/keys/SSL-TLS/server/server.crt'
pool_passwd = 'pool_passwd'

hostssl is used in /etc/pgpool-II/pool_hba.conf:

hostssl all all 0.0.0.0/0 scram-sha-256

The default webadmin and pgpool entries are added automatically to /etc/pgpool-II/pool_passwd. For custom users, add entries with the pg_enc utility:

pg_enc -m -f /etc/pgpool-II/pgpool.conf -u $USERNAME $PASSWORD

Re-issue and uninstall

The add-on adds two actions under the Add-Ons tab of the affected layer:

  • Re-issue certificates — regenerates SSL certificates (use after a suspected compromise or accidental deletion).
  • Configuration Tutorial — links to the in-platform reference for establishing SSL connections to PostgreSQL.

Uninstall in the add-on’s overflow menu removes the add-on, the custom configuration, and the generated certificates from the layer.

Connect from a client over SSL

Server-side encryption is active immediately after install. Connect from psql (or any libpq client) with the credentials from your provisioning email:

psql -U <user> <dbname> -h <host> -p <port> -W

To upgrade to mutual TLS, download the client certificates from /var/lib/stackharbor/keys/SSL-TLS/client/ on the PostgreSQL node and pass them via libpq parameters or environment variables (PGSSLCERT, PGSSLKEY, PGSSLROOTCERT).

See also