PG-1832 Document pg_tde's archive and restore commands

Author: jeltz

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

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'
+```

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"
+```

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