From: dwsteele (@dwsteele) <noreply+dwsteele@github.com>
To: pgbackrest/pgbackrest <noreply+pgbackrest-pgbackrest@github.com>
Subject: [pgbackrest/pgbackrest] PR #2898: Add stanza-rekey command to change the repository passphrase.
Date: Wed, 04 Nov 2026 11:27:47 +0000
Message-ID: <gh-pgbackrest-pgbackrest-2898@github.com> (raw)
repo-cipher-pass encrypts only archive.info, backup.info, and their copies. Every other file is encrypted with a key stored in one of them, so changing the passphrase rewrites four small files and no backups or WAL.
To change the passphrase, set repo-cipher-pass to the new passphrase and the new repo-cipher-pass-old option to the old passphrase on every host where repo-cipher-pass is configured. Then run stanza-rekey, remove repo-cipher-pass-old from those hosts, and run check. A host with no encryption settings gets both options from the repository host.
While repo-cipher-pass-old is set, an info file that cannot be read with repo-cipher-pass is retried with the old passphrase so commands keep working until the rekey runs. The retry is logged at debug level. verify also retries and reports the file at detail level. repo-get reads an info file directly and does not fall back to the old passphrase.
An info file is saved with the passphrase that decrypted it and only stanza-rekey changes it. Backups and archiving can continue while hosts are updated, and a host that has not been updated can still read the stanza until the rekey runs. check warns while repo-cipher-pass-old is set and reports whether the stanza has been rekeyed.
stanza-rekey has these behaviors:
- It does not connect to PostgreSQL and locks like stanza-upgrade.
- It checks the new passphrase like stanza-create, and the new passphrase must differ from the old one.
- It saves each info file and its copy with the new passphrase, so running it again after a crash finishes the job.
- It rekeys at every format and skips unencrypted repositories. It errors when no repository is encrypted. --repo limits it to one repository.
stanza-rekey also rotates the archive key of each encrypted repository at format >= 6, even when repo-cipher-pass-old is not set. There is no option to skip this. Format 5 has a single archive key, so a run with nothing to rekey there only warns. A backup set gets a new key with its next full backup.
Rotation protects only data written afterwards. If the old passphrase and the repository were both exposed, existing keys and data must be considered exposed. A full backup taken before the rekey stores its key in backup.info while backup.info is still encrypted with the old passphrase, and the rekey does not replace that key. After an exposure, take a full backup after the rekey.
The command and repo-cipher-pass-old are internal until format 6 is released.
The integration test runs the fallback and the rekey from pg1, which has no encryption settings. Before the rekey it runs a backup and checks that both info files are still encrypted with the old passphrase. The remaining backup and restore tests then run against the rekeyed repository.