• How PostgreSQL passwords are managed in Chef Infra Server
• Where the PostgreSQL credentials are stored
• How to rotate/change the db_superuser password
• Who can access those credentials
• How password management differs between embedded and external PostgreSQL deployments

Overview

Chef Infra Server ships with an embedded PostgreSQL instance that acts as the internal database for all Chef Server services - including Erchef, Bifrost, and OC-ID. This embedded PostgreSQL is fully managed by Chef Infra Server itself; it is installed, configured, started, and stopped entirely through the chef-server-ctl command-line tool.

Because the database is tightly integrated with the Chef Server lifecycle, credentials for the PostgreSQL superuser (db_superuser) are stored and managed internally rather than through a separate database administration process. Understanding where these credentials, how to rotate them, and who can access them is important for security compliance and incident response.

This article covers the following scenarios:

• Chef Infra Server using its embedded (local) PostgreSQL instance.
• Chef Infra Server configured against an external PostgreSQL database (e.g., AWS RDS).

How to Find Where the PostgreSQL Password Is Stored

Embedded PostgreSQL

When Chef Infra Server manages its own local PostgreSQL instance, all internal service secrets including the PostgreSQL superuser password  are stored in a single JSON file

/etc/opscode/private-chef-secrets.json

This file is auto-generated the first time chef-server-ctl reconfigure is run. It contains credentials for all embedded services (PostgreSQL, Redis, RabbitMQ, etc.) in plain text. The file is owned by root and readable only by root (chmod 600), which limits who can read it directly on the filesystem.

To inspect the PostgreSQL password without opening the file manually, use the built-in secrets management command:

chef-server-ctl show-secret postgresql db_superuser_password

This is safer than opening the JSON file directly because it reads the value through the chef-server-ctl interface rather than exposing the full secrets file.

External PostgreSQL (e.g., AWS RDS)

When Chef Infra Server is configured to use an external database, it does not generate or manage private-chef-secrets.json for PostgreSQL credentials. Instead, the database connection details including the superuser username are defined manually in the Chef Server configuration file:

/etc/opscode/chef-server.rb

A typical external database configuration looks like this:

postgresql['vip']          = 'your-rds-endpoint.xxxxxx.us-east-1.rds.amazonaws.com'
postgresql['port']         = 5432
postgresql['db_superuser'] = 'rds_master_username'
postgresql['username']     = 'rds_master_username'

In this setup, the password itself is not stored inside the Chef Server configuration. It is managed externally — either directly in the RDS instance or via a secrets manager such as AWS Secrets Manager or HashiCorp Vault.

How to Rotate the PostgreSQL Password

Embedded PostgreSQL

Chef Infra Server provides a built-in command to rotate the PostgreSQL superuser password. This command handles the full rotation process in one step. It updates both the secrets file and the actual PostgreSQL database simultaneously, so there is no risk of the two getting out of sync.

Step 1: Rotate the credentials

chef-server-ctl rotate-credentials postgresql

What happens internally:

• • A new random password is generated for the db_superuser account.
  • The new password is written to /etc/opscode/private-chef-secrets.json.
  • The password is also updated directly in the embedded PostgreSQL database using an ALTER ROLE statement.

At this point the secrets file and the database are consistent, but the running Chef Server services still hold the old password in memory.

Step 2: Apply the changes to all services

 chef-server-ctl reconfigure

What happens internally:

• • Chef Server reads the updated private-chef-secrets.json.
  • All service configuration files (e.g., Erchef, Bifrost) are re-rendered with the new password.
  • Services that depend on PostgreSQL are restarted to pick up the new credentials.

Important: Skipping reconfigure after rotating credentials will leave services using a stale password. This will cause authentication failures as services attempt to connect to PostgreSQL with the old credential.

External PostgreSQL (e.g., AWS RDS)

For external databases, the password is not managed by Chef. The rotation process has two parts: updating the password in the external database, and then telling Chef Server about the new password.

Step 1: Update the password in the external database

Change the password at the database level — either through the RDS console, the AWS CLI, or a direct psql command:

# Via psql
ALTER ROLE rds_master_username WITH PASSWORD 'new-secure-password';

Or via the AWS CLI:

 aws rds modify-db-instance \
  --db-instance-identifier your-db-instance \
  --master-user-password 'new-secure-password' \
  --apply-immediately

Step 2: Update Chef Server with the new password

Use the set-db-superuser-password command to store the new password in Chef Server's secrets:

chef-server-ctl set-db-superuser-password

This command will prompt you to enter the new password interactively. It stores the value securely so that Chef Server can use it when connecting to the external database.

Step 3: Apply the changes

chef-server-ctl reconfigure

This re-renders all service configurations with the updated password and restarts affected services.

Note: The order matters. Update the database password first, then update Chef Server. If you update Chef Server first and then change the database, there will be a window where Chef Server cannot connect to PostgreSQL.

How to Control Who Has Access to the PostgreSQL Password

Filesystem Access

The secrets file is protected by filesystem permissions:

 -rw------- 1 root root /etc/opscode/private-chef-secrets.json

Only the root user can read or write this file. Regular OS users — including the opscode user that runs Chef Server services — do not have direct read access to this file. Services receive their credentials through rendered configuration files, not by reading the secrets file directly.

Using the Secrets Management Interface

The chef-server-ctl secrets management commands provide a controlled interface for viewing and setting individual secrets without exposing the entire secrets file:

 # Read the current PostgreSQL superuser password (requires root)
chef-server-ctl show-secret postgresql db_superuser_password

# Set a specific secret manually (requires root)
chef-server-ctl set-secret postgresql db_superuser_password

Only users with root privileges (or sudo access to chef-server-ctl) can use these commands.

Reference: chef-server-ctl Secrets Management

Recommended Access Controls

Quick Reference

Always run chef-server-ctl reconfigure after any credential rotation to apply changes to all services.

References

• chef-server-ctl Secrets Management
• Chef Server PostgreSQL Optional Settings