From a8829b543ea085e0b5c389e59bfd2541326e75e3 Mon Sep 17 00:00:00 2001 From: Andreas Karlsson Date: Mon, 11 Aug 2025 18:01:10 +0200 Subject: [PATCH] PG-1832 Document pg_tde's archive and restore commands Initial quick documentation for the two new CLI commands. We want to improve this futuer in the future plus add a proper guide for how to set up a complete solution. --- .../docs/command-line-tools/cli-tools.md | 15 ++++++++---- .../pg-tde-archive-decrypt.md | 23 +++++++++++++++++++ .../pg-tde-restore-encrypt.md | 21 +++++++++++++++++ contrib/pg_tde/documentation/mkdocs.yml | 4 +++- 4 files changed, 58 insertions(+), 5 deletions(-) create mode 100644 contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-archive-decrypt.md create mode 100644 contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-restore-encrypt.md diff --git a/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md b/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md index e0edeb4b5de32..7dba5ed41625d 100644 --- a/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md +++ b/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md @@ -1,7 +1,14 @@ # Overview of pg_tde CLI tools -The `pg_tde` extension introduces new command-line utilities and extends some existing PostgreSQL tools to support encrypted WAL and tables. These include: +The `pg_tde` extension introduces new command-line utilities and extends some existing PostgreSQL tools to support encrypted WAL and tables. -* [pg_tde_change_key_provider](../command-line-tools/pg-tde-change-key-provider.md): change encryption key provider for a database -* [pg_waldump](../command-line-tools/pg-waldump.md): inspect and decrypt WAL files -* [pg_checksums](../command-line-tools/pg-tde-checksums.md): verify data checksums (non-encrypted files only) +## New tools + +* [pg_tde_change_key_provider](./pg-tde-change-key-provider.md): change encryption key provider for a database +* [pg_tde_archive_decrypt](./pg-tde-archive-decrypt.md): custom archive command for archiving plaintext WAL +* [pg_tde_restore_encrypt](./pg-tde-restore-encrypt.md): custome restore command for making sure restored WAL is encrypted + +## Extended tools + +* [pg_checksums](./pg-tde-checksums.md): verify data checksums (non-encrypted files only) +* [pg_waldump](./pg-waldump.md): inspect and decrypt WAL files diff --git a/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-archive-decrypt.md b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-archive-decrypt.md new file mode 100644 index 0000000000000..bd26deb63db4b --- /dev/null +++ b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-archive-decrypt.md @@ -0,0 +1,23 @@ +# pg_tde_archive_decrypt + +Helper command to archive WAL segments in uncrypted form. This is necessary since the WAL encryption keys in the two-key hierarchy (see [Architecture](../architecture/architcture.md)) are specific to the host which generated them and may not be available at the machine which will replay the WAL. + +The command wraps your normal archive command and creates a temporary file on a RAM disk, `/dev/shm`, which is then fed as input to your archive command. + +This command is often use in conjunction with [pg_tde_restore_encrypt](./pg-tde-restore-encrypt.md). + +To use this safely make sure to encrypt the files stored in your WAL archive which is supported by e.g. PgBackRest. + +## Examples + +Simple example using `cp`: + +```ini +archive_command = '/lib/postgresql/17/bin/pg_tde_archive_decrypt %p cp %p /archive/%f' +``` + +With PgBackRest: + +```ini +archive_command = '/lib/postgresql/17/bin/pg_tde_archive_decrypt %p pgbackrest --stanza=tde archive-push %p' +``` diff --git a/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-restore-encrypt.md b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-restore-encrypt.md new file mode 100644 index 0000000000000..9300d8ca795b7 --- /dev/null +++ b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-restore-encrypt.md @@ -0,0 +1,21 @@ +# pg_tde_restore_encrypt + +Helper command to take unecrypted segments from the WAL archive and write them to disk in a format which `pg_tde` understands. + +The command wraps your normal restore command and has it write the file from the archive to a temporary file on a RAM disk, `/dev/shm` before copying it into PostgreSQL's data directory. + +This command is often use in conjunction with [pg_tde_archive_decrypt](./pg-tde-archive-decrypt.md). + +## Examples + +Simple example using `cp`: + +```ini +restore_command = '/lib/postgresql/17/bin/pg_tde_restore_enrypt %f %p cp /archive/%f %p' +``` + +With PgBackRest add something like the following to `/etc/pgbackrest.conf` or to the command line: + +```ini +recovery-option=restore_command=/lib/postgresql/17/bin/pg_tde_restore_encrypt %f %p pgbackrest --stanza=demo archive-get %f "%p" +``` diff --git a/contrib/pg_tde/documentation/mkdocs.yml b/contrib/pg_tde/documentation/mkdocs.yml index 43725bb5de5e6..bca17fb3742ad 100644 --- a/contrib/pg_tde/documentation/mkdocs.yml +++ b/contrib/pg_tde/documentation/mkdocs.yml @@ -196,8 +196,10 @@ nav: - "pg_tde CLI Tools": - "Overview": command-line-tools/cli-tools.md - "pg_tde_change_key_provider": command-line-tools/pg-tde-change-key-provider.md - - "pg_waldump": command-line-tools/pg-waldump.md + - "pg_tde_archive_decrypt": command-line-tools/pg-tde-archive-decrypt.md + - "pg_tde_restore_encrypt": command-line-tools/pg-tde-restore-encrypt.md - "pg_checksums": command-line-tools/pg-tde-checksums.md + - "pg_waldump": command-line-tools/pg-waldump.md - "Uninstall pg_tde": how-to/uninstall.md - "Configure Multi-tenancy": how-to/multi-tenant-setup.md - "Encryption Enforcement": how-to/enforcement.md