diff --git a/product_docs/docs/tde/15/enabling_tde.mdx b/product_docs/docs/tde/15/enabling_tde.mdx index 8674165472f..32177b2061f 100644 --- a/product_docs/docs/tde/15/enabling_tde.mdx +++ b/product_docs/docs/tde/15/enabling_tde.mdx @@ -1,5 +1,6 @@ --- -title: Enabling TDE +title: "Creating a database cluster with TDE enabled" +navTitle: Creating a cluster with TDE --- You enable transparent data encryption when you initialize a database cluster using [initdb](https://www.postgresql.org/docs/15/app-initdb.html). diff --git a/product_docs/docs/tde/15/enabling_tde_epas.mdx b/product_docs/docs/tde/15/enabling_tde_epas.mdx new file mode 100644 index 00000000000..7eef65b3f53 --- /dev/null +++ b/product_docs/docs/tde/15/enabling_tde_epas.mdx @@ -0,0 +1,159 @@ +--- +title: "Enabling TDE on an existing EDB Postgres Advanced Server cluster" +navTitle: Enabling TDE on an existing EDB Postgres Advanced Server cluster +deepToC: true +--- + +## Enabling TDE on an EDB Postgres Advanced Server cluster + +Create a new EDB Postgres Advanced Server cluster with TDE enabled +and use `pg_upgrade` to transfer data from the existing source cluster to the new encrypted cluster. + +- [Prepare your upgrade](#preparing-your-upgrade) by performing a backup of the existing instance. +- [Create a new database server](#creating-an-encrypted-server) + - Create an empty directory for the new server and ensure `enterprisedb` owns it. + - Set the environment variables to export the `wrap` and `unwrap` commands for encryption. + - Initialize a server with encryption enabled. + - Change the default port, so the new server is available at another port. + - Start the database server. + - Connect to the database server and ensure it is functioning. +- [Upgrade to the encrypted server](#upgrading-to-the-encrypted-server) + - Stop both the source and the new server. + - Use `pg_upgrade` with `--copy-by-block` option to copy data from the source server to the new server. Specify the source and target bin and data directories. + - Start the new encrypted databaser server. + - Connect to the encrypted database server and ensure the data was transfered. +- [Clean up and delete the source server](#cleaning-up-after-upgrade) + - Clean up the database and its statistics. + - Remove the source EDB Postgres Advanced Server cluster with the script provided by `pg_upgrade`. + +## Worked example + +### Preparing your upgrade + +Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [pgBackRest](/supported-open-source/pgbackrest/), or [Barman](/supported-open-source/barman/) to create a backup of your unencrypted source server. + +### Creating an encrypted server + +1. Create an empty directory for the new server: + + ``` + mkdir /var/lib/edb-as/16/TDE + ``` + +1. Ensure the `enterprisedb` user owns the directory: + + ``` + sudo chown enterprisedb /var/lib/edb-as/16/TDE + sudo chgrp /var/lib/edb-as/16/TDE + ``` + +1. Set environment variables to export the `wrap` and `unwrap` commands: + + ``` + export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pass pass:ok -out %p' + export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pass pass:ok -in %p' + ``` + + !!!note + Alternatively, use the `--key-unwrap-command=` and `--key-wrap-command=` arguments when initializing the encrypted server to include the `wrap` and `unwrap` commands. + + See [Using initdb TDE options](enabling_tde/#using-initdb-tde-options) for more information on possible configurations. + +1. Initialize the new server with encryption: + + ``` + /usr/lib/edb-as/16/bin/initdb --data-encryption -D /var/lib/edb-as/16/TDE + ``` + + This command initializes a CONFIG directory with all configuration files for the encrypted server. + +1. Modify the port number in the configuration file of the encrypted instance. Uncomment the line with `#port` and change the port number. For example: + + ``` + port 5590 + ``` + +1. Start the encrypted server: + + ``` + /usr/lib/edb-as/16/bin/pg_ctl -D /var/lib/edb-as/16/TDE -l logfile start + ``` + +1. Connect to the server: + + ``` + /usr/lib/edb-as/16/bin/psql -p 5590 edb + ``` + + !!!note + If you're using two different Postgres versions, use the psql utility of the encrypted server. Otherwise, the system will attempt to use psql from the previous instance. + +1. To ensure the new server is encrypted, [check for TDE presence](enabling_tde/#checking-for-tde-presence-using-sql). + +### Upgrading to the encrypted server + +1. Stop both servers: + + ``` + /usr/lib/edb-as/16/bin/pg_ctl -D /var/lib/edb-as/16/non-TDE stop + /usr/lib/edb-as/16/bin/pg_ctl -D /var/lib/edb-as/16/TDE stop + ``` + +1. To test for incompatibilities, run the `pg_upgrade` command in check mode. + + With `-b` and `-B`, specify the source and target BIN directories. With `-d` and `-D`, specify the source and target CONFIG directories. + Include the `--copy-by-block` option. + + ``` + /usr/lib/edb-as/16/bin/pg_upgrade -b /usr/lib/edb-as/16/bin -B /usr/lib/edb-as/16/bin -d /var/lib/edb-as/16/non-TDE -D /var/lib/edb-as/16/TDE --copy-by-block --check + ``` + + !!!note + The `--check` mode performs preliminary checks without executing the command. + +1. To copy data from the source server to the target server, run the `pg_upgrade` command in normal mode: + + ``` + /usr/lib/edb-as/16/bin/pg_upgrade -b /usr/lib/edb-as/16/bin -B /usr/lib/edb-as/16/bin -d /var/lib/edb-as/16/non-TDE -D /var/lib/edb-as/16/TDE --copy-by-block + ``` + +1. Restart the encrypted server: + + ``` + /usr/lib/edb-as/16/bin/pg_ctl -D /var/lib/edb-as/16/TDE start + ``` + +1. Connect to the encrypted database server: + + ``` + /usr/lib/edb-as/16/bin/psql -p 5590 edb + ``` + +1. Perform a spot check to ensure the databases, tables, schemas, and resources you had in the unencrypted server are available in the new server. For example, list all databases: + + ``` + \l + ``` + + Connect to a database, for example `hr`, and search for existing tables: + + ``` + \c hr + SELECT * FROM dept; + ``` + +### Cleaning up after upgrade + +After you verify that `pg_upgrade` encrypted the data successfully, perform a cleanup. + +1. Clean up the database and its statistics: + + ``` + /usr/lib/edb-as/16/bin/vacuumdb --all --analyze-in-stages + ``` + +1. Remove all data files of the unencrypted server with the script generated by `pg_upgrade`: + + ``` + ./delete_old_cluster.sh + ``` diff --git a/product_docs/docs/tde/15/index.mdx b/product_docs/docs/tde/15/index.mdx index 951760382dd..924e9721ce9 100644 --- a/product_docs/docs/tde/15/index.mdx +++ b/product_docs/docs/tde/15/index.mdx @@ -2,8 +2,10 @@ title: "Transparent Data Encryption" hideVersion: true navigation: +- "#Enabling" - key_stores - enabling_tde +- enabling_tde_epas - "#Differences from Postgres" - limitations - affected_commands @@ -11,7 +13,8 @@ navigation: - troubleshooting - backups - "#Upgrading" -- pg_upgrade +- upgrade_overview +- pg_upgrade_arguments - "#Testing" - single_user - regress_run diff --git a/product_docs/docs/tde/15/pg_upgrade.mdx b/product_docs/docs/tde/15/pg_upgrade_arguments.mdx similarity index 79% rename from product_docs/docs/tde/15/pg_upgrade.mdx rename to product_docs/docs/tde/15/pg_upgrade_arguments.mdx index c3adc3457a2..b20957fd6a6 100644 --- a/product_docs/docs/tde/15/pg_upgrade.mdx +++ b/product_docs/docs/tde/15/pg_upgrade_arguments.mdx @@ -1,10 +1,9 @@ --- -title: "Upgrading a TDE system" -navTitle: Upgrading encrypted clusters +title: "TDE upgrade arguments" +navTitle: TDE upgrade arguments --- - -These options to [pg_upgrade](https://www.postgresql.org/docs/15/pgupgrade.html) help with upgrading encrypted clusters. +These arguments to [pg_upgrade](https://www.postgresql.org/docs/latest/pgupgrade.html) help with upgrading encrypted clusters. ## `--copy-by-block` @@ -14,8 +13,10 @@ You must use this option when upgrading between clusters with different encrypti For added certainty, if the old cluster is encrypted and the new cluster was initialized as unencrypted, this option decrypts the data from the old cluster and copies it to the new cluster unencrypted. If the old cluster is unencrypted and the new cluster was initialized as encrypted, this option encrypts the data from the old cluster and places it into the new cluster encrypted. -See the description of the [initdb --copy-key-from=<file> option](/tde/latest/enabling_tde/#using-initdb-tde-options) for information on copying a key from an existing cluster when preparing a new cluster as a target for `pg_upgrade`. +See the description of the [initdb --copy-key-from=<file> option](enabling_tde/#using-initdb-tde-options) for information on copying a key from an existing cluster when preparing a new cluster as a target for `pg_upgrade`. +See [Tutorials](/upgrade_overview/#tutorials) for `--copy-by-block` usage examples. + ## `--key-unwrap-command=` Specifies a command to unwrap (decrypt) the data encryption key. The command must include a placeholder `%p` that specifies the file to read the wrapped key from. The command needs to write the unwrapped key to its standard output. If you don't specify this option, the environment variable `PGDATAKEYUNWRAPCMD` is used. diff --git a/product_docs/docs/tde/15/upgrade_overview.mdx b/product_docs/docs/tde/15/upgrade_overview.mdx new file mode 100644 index 00000000000..c921b1cb3fe --- /dev/null +++ b/product_docs/docs/tde/15/upgrade_overview.mdx @@ -0,0 +1,30 @@ +--- +title: "TDE pg_upgrade use cases" +navTitle: TDE pg_upgrade use cases +--- + +EDB supports using [pg_upgrade](pg_upgrade_arguments) to add encryption to unencrypted systems. +This table provides an overview of supported use cases. + +| Use case | Source unencrypted server | Target encrypted server | +|---------------------------------------------------------------|-----------------------------------------------|--------------------------------------------------------------------| +| Perform a minor upgrade and add encryption | Unencrypted EDB Postgres Extended Server 16.1 | Encrypted EDB Postgres Extended Server 16.2 | +| Change the Postgres distribution and add encryption | Unencrypted PostgreSQL 16 | Encrypted EDB Postgres Advanced Server 16 | +| Maintain the Postgres distribution and add encryption | Unencrypted EDB Postgres Advanced Server 15 | Encrypted EDB Postgres Advanced Server 15 | +| Maintain the Postgres distribution and rotate encryption keys | Encrypted EDB Postgres Advanced Server 15 | Encrypted EDB Postgres Advanced Server 15 with new encryption keys | + +!!! Important + Both source and target servers must be in the same Postgres major version. `pg_upgrade` only supports upgrades between minor versions. + +## Overview + +To enable encryption: + +1. Perform a backup of your system. +1. Install the target Postgres version. +1. Initialize a new server with TDE enabled. +1. Use `pg_upgrade` with the `--copy-by-block` option to upgrade to a TDE system. + +## Tutorials + +* [Enable TDE on an existing EDB Postgres Advanced Server database cluster](enabling_tde_epas). \ No newline at end of file