From b3b7beb240ce4df746731da99a071197a7f3bff1 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Wed, 3 Apr 2024 20:33:27 +0200 Subject: [PATCH] Doc: Added install from packages instructions --- documentation/docs/apt.md | 66 +++++++++++++++++++++++ documentation/docs/css/design.css | 27 ++++++++-- documentation/docs/external-parameters.md | 34 ++++++++++++ documentation/docs/functions.md | 45 +++------------- documentation/docs/index.md | 6 +-- documentation/docs/install.md | 33 ++++++------ documentation/docs/setup.md | 45 +--------------- documentation/docs/yum.md | 62 +++++++++++++++++++++ documentation/mkdocs.yml | 27 +++++----- 9 files changed, 227 insertions(+), 118 deletions(-) create mode 100644 documentation/docs/apt.md create mode 100644 documentation/docs/external-parameters.md create mode 100644 documentation/docs/yum.md diff --git a/documentation/docs/apt.md b/documentation/docs/apt.md new file mode 100644 index 00000000..436465d4 --- /dev/null +++ b/documentation/docs/apt.md @@ -0,0 +1,66 @@ +# Install `pg_tde` on Debian or Ubuntu + +In version Aplha1, `pg_tde` packages are available in the testing repository for Percona Distribution for PostgreSQL 16.2. Check the [list of supported platforms](install.md#__tabbed_1_2). + +This tutorial shows how to install `pg_tde` with [Percona Distribution for PostgreSQL](https://docs.percona.com/postgresql/latest/index.html). + +## Preconditions + +You need the `percona-release` repository management tool that enables the desired Percona repository for you. + +1. You need the following dependencies to install `percona-release`: + + - `wget` + - `gnupg2` + - `curl` + - `lsb-release` + + Install them with the following command: + + ```bash + sudo apt-get install -y wget gnupg2 curl lsb-release + ``` + +2. Fetch the `percona-release` package + + ```bash + sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb + ``` + +3. Install `percona-release` + + ```bash + sudo dpkg -i percona-release_latest.generic_all.deb + ``` + +4. Enable the Percona Distribution for PostgreSQL repository + + ```bash + sudo percona-release enable-only ppg-16.2 testing + ``` + +5. Update the local cache + + ```bash + sudo apt-get update + ``` + +## Install Percona Distribution for PostgreSQL + +To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command: + +```bash +sudo apt-get install -y percona-postgresql-16 percona-postgresql-contrib percona-postgresql-server-dev-all +``` + +## Install `pg_tde` packages + +To install `pg_tde` packages, run the following command: + +```bash +sudo apt-get install percona-postgresql-16-pg-tde +``` + +## Next step + +[Setup](setup.md){.md-button} \ No newline at end of file diff --git a/documentation/docs/css/design.css b/documentation/docs/css/design.css index a93b4fea..51e6aee9 100644 --- a/documentation/docs/css/design.css +++ b/documentation/docs/css/design.css @@ -81,7 +81,6 @@ font-weight: bold; } .md-typeset h1 { - font-weight: normal; color: inherit; } .md-typeset h1 { @@ -149,16 +148,20 @@ .md-content .md-button { margin: 0 0.25em 0.5em 0; } -.md-typeset .tabbed-labels>label { +.md-typeset .tabbed-labels > label { font-size: 0.75rem; padding: 0.75em 1em; } .js .md-typeset .tabbed-labels:before { height: 4px; + background-color: var(--md-accent-fg-color); } .md-typeset [class*="moji"] { vertical-align: -0.25em; } +.md-typeset .tabbed-set>input:first-child:checked~.tabbed-labels>:first-child, .md-typeset .tabbed-set>input:nth-child(10):checked~.tabbed-labels>:nth-child(10), .md-typeset .tabbed-set>input:nth-child(11):checked~.tabbed-labels>:nth-child(11), .md-typeset .tabbed-set>input:nth-child(12):checked~.tabbed-labels>:nth-child(12), .md-typeset .tabbed-set>input:nth-child(13):checked~.tabbed-labels>:nth-child(13), .md-typeset .tabbed-set>input:nth-child(14):checked~.tabbed-labels>:nth-child(14), .md-typeset .tabbed-set>input:nth-child(15):checked~.tabbed-labels>:nth-child(15), .md-typeset .tabbed-set>input:nth-child(16):checked~.tabbed-labels>:nth-child(16), .md-typeset .tabbed-set>input:nth-child(17):checked~.tabbed-labels>:nth-child(17), .md-typeset .tabbed-set>input:nth-child(18):checked~.tabbed-labels>:nth-child(18), .md-typeset .tabbed-set>input:nth-child(19):checked~.tabbed-labels>:nth-child(19), .md-typeset .tabbed-set>input:nth-child(2):checked~.tabbed-labels>:nth-child(2), .md-typeset .tabbed-set>input:nth-child(20):checked~.tabbed-labels>:nth-child(20), .md-typeset .tabbed-set>input:nth-child(3):checked~.tabbed-labels>:nth-child(3), .md-typeset .tabbed-set>input:nth-child(4):checked~.tabbed-labels>:nth-child(4), .md-typeset .tabbed-set>input:nth-child(5):checked~.tabbed-labels>:nth-child(5), .md-typeset .tabbed-set>input:nth-child(6):checked~.tabbed-labels>:nth-child(6), .md-typeset .tabbed-set>input:nth-child(7):checked~.tabbed-labels>:nth-child(7), .md-typeset .tabbed-set>input:nth-child(8):checked~.tabbed-labels>:nth-child(8), .md-typeset .tabbed-set>input:nth-child(9):checked~.tabbed-labels>:nth-child(9) { + color: var(--md-accent-fg-color); +} .md-typeset .md-button [class*="moji"], .md-typeset .tabbed-set [class*="moji"] { height: 1.3333em; @@ -175,11 +178,21 @@ color: var(--md-default-fg-color--lighter); } .md-typeset hr { + margin: 3em 0; border-color: var(--md-default-fg-color--lighter) } .md-typeset .tabbed-labels { box-shadow: 0 -0.05rem var(--md-default-fg-color--lighter) inset; } +.md-typeset .tabbed-button { + width: 1.25rem; + height: 1.25rem; + margin-top: 0.0625rem; +} +.md-typeset .tabbed-control { + width: 2.25rem; + height: 2.25rem; +} /* Content re-styling */ .md-typeset [type=checkbox]:checked + .task-list-indicator:before { @@ -199,8 +212,8 @@ .md-tabs__link { font-size: 0.67rem; } -.md-tabs__link--active, -.md-tabs__link--active a { +.md-tabs__item--active .md-tabs__link, +.md-tabs__item--active .md-tabs__link a { font-weight: bold; border-bottom: 0.15em solid currentColor; } @@ -241,6 +254,12 @@ [data-banner] a [class*="moji"] svg { width: 1.3333em; } +[data-banner="logo"] > p:first-child { + margin-top: 0; +} +[data-banner="logo"] > p:first-child [class*="moji"] { + font-size: 4em; +} [data-grid] { display: flex; flex-wrap: wrap; diff --git a/documentation/docs/external-parameters.md b/documentation/docs/external-parameters.md new file mode 100644 index 00000000..66824e2c --- /dev/null +++ b/documentation/docs/external-parameters.md @@ -0,0 +1,34 @@ +# Use external reference to parameters + +To allow storing secrets or any other parameters in a more secure, external location, `pg_tde` +allows users to specify an external reference instead of hardcoded parameters. + +In Alpha1 version, `pg_tde` supports the following external storage methods: + +* `file`, which just stores the data in a simple file specified by a `path`. The file should be +readable to the postgres process. +* `remote`, which uses a HTTP request to retrieve the parameter from the specified `url`. + +## Examples + +To use the file provider with a file location specified by the `remote` method, +use the following command: + +```sql +SELECT pg_tde_add_key_provider_file( + 'file-provider', + json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/hello' ) + );" +``` + +Or to use the `file` method, use the following command: + +```sql +SELECT pg_tde_add_key_provider_file( + 'file-provider', + json_object( 'type' VALUE 'remote', 'path' VALUE '/tmp/datafile-location' ) + );" +``` + +Any parameter specified to the `add_key_provider` function can be a `json_object` instead of the string, +similar to the above examples. \ No newline at end of file diff --git a/documentation/docs/functions.md b/documentation/docs/functions.md index 027e343f..b3089a19 100644 --- a/documentation/docs/functions.md +++ b/documentation/docs/functions.md @@ -12,7 +12,7 @@ This function is intended for development, and stores the keys unencrypted in th SELECT pg_tde_add_key_provider_file('provider-name','/path/to/the/keyring/data.file'); ``` -All parameters can be either strings, or JSON objects referencing remote parameters. +All parameters can be either strings, or JSON objects [referencing remote parameters](external-parameters.md). ## pg_tde_add_key_provider_vault_v2 @@ -31,7 +31,7 @@ where: * `secret_token` is an access token with read and write access to the above mount point * [optional] `ca_path` is the path of the CA file used for SSL verification -All parameters can be either strings, or JSON objects referencing remote parameters. +All parameters can be either strings, or JSON objects [referencing remote parameters](external-parameters.md). ## pg_tde_set_master_key @@ -47,23 +47,22 @@ SELECT pg_tde_set_master_key('name-of-the-master-key', 'provider-name'); ## pg_tde_rotate_key -Creates a new version of the specified master key, and updates the database so that it uses the new master key version. +Creates a new version of the specified master key and updates the database so that it uses the new master key version. -It can be used without any parameters, which will just create a new version of the current database +When used without any parameters, the function will just create a new version of the current database master key, using the same provider: ```sql SELECT pg_tde_rotate_key(); ``` -Or alternatively it can be used with two parameters, specifying both a new key name and a new provider -name: +Alternatively, you can pass two parameters to the function, specifying both a new key name and a new provider name: ```sql SELECT pg_tde_rotate_key('name-of-the-new-master-key', 'name-of-the-new-provider'); ``` -In this case, both parameters support the `NULL` value, which means that parameter won't be changed: +Both parameters support the `NULL` value, which means that the parameter won't be changed: ```sql -- creates new master key on the same provider as before @@ -82,35 +81,3 @@ SELECT pg_tde_is_encrypted('table_name'); ``` -# JSON objects as remote parameters - -To allow storing secrets, or any other parameters in a more secure, external location, `pg_tde` -allows users to specify an external reference instead of hardcoded parameters. - -Currently `pg_tde` supports two external storage methods: - -* `file`, which just stores the data in a simple file specified by a `path`. The file should be -readable to the postgres process. -* `remote`, which uses a HTTP request to retrieve the parameter from the specified `url`. - -As an example, to use the file provider with a file location specified by the `remote` method, -use the following command: - -```sql -SELECT pg_tde_add_key_provider_file( - 'file-provider', - json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/hello' ) - );" -``` - -Or to use the `file` method, use the following command: - -```sql -SELECT pg_tde_add_key_provider_file( - 'file-provider', - json_object( 'type' VALUE 'remote', 'path' VALUE '/tmp/datafile-location' ) - );" -``` - -Any parameter specified to the `add_key_provider` functions can be a json_object instead of the string, -similar to the above examples. diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 41d25f92..34113aa7 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -1,12 +1,10 @@ -# `pg_tde` documentation [Tech preview] +# `pg_tde` documentation [Aplha1] `pg_tde` is the extension that brings in [Transparent Data Encryption (TDE)](tde.md) to PostgreSQL and enables users to keep sensitive data safe and secure. It enables users to configure encryption differently for each database, encrypting specific tables in some databases with different encryption keys, while keeping others non encrypted. !!! important - This is the tech preview version of the extension and is not meant for production use yet. - -[What's new](release-notes/tech-preview.md){.md-button} + This is the Alpha1 version of the extension and is not meant for production use yet. ## What's encrypted diff --git a/documentation/docs/install.md b/documentation/docs/install.md index 0cb5a96d..89f3a2f6 100644 --- a/documentation/docs/install.md +++ b/documentation/docs/install.md @@ -16,6 +16,23 @@ You can use the following options to manage encryption keys: Install `pg_tde` using one of available installation methods: + +=== "Package manager" + + Starting with Aplha1 version, you can install the extension as package from Percona repositories using the `percona-release` tool. The packages are available for the following operating systems: + + - Red Hat Enterprise Linux and CentOS 7 + - Red Hat Enterprise Linux 8 and compatible derivatives + - Red Hat Enterprise Linux 9 and compatible derivatives + - Ubuntu 20.04 (Focal Fossa) + - Ubuntu 22.04 (Jammy Jellyfish) + - Debian 10 (Buster) + - Debian 11 (Bullseye) + - Debian 12 (Bookworm) + + [Install on Debian or Ubuntu](apt.md){.md-button} + [Install on RHEL or derivatives](yum.md){.md-button} + === "Build from source" 1. To build `pg_tde` from source code, you require the following on Ubuntu/Debian: @@ -43,22 +60,6 @@ Install `pg_tde` using one of available installation methods: sudo make USE_PGXS=1 install ``` -=== "Package manager" - - Currently only DEB packages for Ubuntu 22.04 are available. If you are running RPM-based operating system, consider [building the extension from source](#build-from-source) or [running it in Docker](#run-in-docker) - - 1. Download the latest [release package](https://github.com/Percona-Lab/pg_tde/releases) - - ``` sh - wget https://github.com/Percona-Lab/pg_tde/releases/download/latest/pgtde-pgdg16.deb - ``` - - 2. Install the package - - ``` sh - sudo dpkg -i pgtde-pgdg16.deb - ``` - === "Run in Docker" You can find Docker images built from the current main branch on [Docker Hub](https://hub.docker.com/r/perconalab/pg_tde). Images are built on top of [postgres:16](https://hub.docker.com/_/postgres) official image. diff --git a/documentation/docs/setup.md b/documentation/docs/setup.md index d3f5d068..daf39f40 100644 --- a/documentation/docs/setup.md +++ b/documentation/docs/setup.md @@ -68,53 +68,12 @@ Load the `pg_tde` at the start time. The extension requires additional shared me ```sql SELECT pg_tde_set_master_key('name-of-the-master-key', 'provider-name'); ``` -## Optional: use external parameters -When configuring `pg_tde` with the steps described above, the provider configuration specified in -step 4 is stored in the database catalog, in an unencrypted table. This is not secure to store -sensitive parameters, such as vault secrets. + :material-information: Info: The key provider configuration is stored in the database catalog in an unencrypted table. See [how to use external reference to parameters](external-parameters.md) to add an extra security layer to your setup. -To allow storing secrets, or any other parameters in a more secure, external location, `pg_tde` -allows users to specify an external reference instead of hardcoded parameters. -Currently `pg_tde` supports two external storage methods: - -* `file`, which just stores the data in a simple file specified by a `path`. The file should be -readable to the postgres process. -* `remote`, which uses a HTTP request to retrieve the parameter from the specified `url`. - -As an example, to use the file provider with a file location specified by the `remote` method, -use the following command: - -```sql -SELECT pg_tde_add_key_provider_file( - 'file-provider', - json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/hello' ) - );" -``` - -Or to use the `file` method, use the following command: - -```sql -SELECT pg_tde_add_key_provider_file( - 'file-provider', - json_object( 'type' VALUE 'remote', 'path' VALUE '/tmp/datafile-location' ) - );" -``` - -Any parameter specified to the `add_key_provider` functions can be a json_object instead of the string, -similar to the above examples. - -6. You are all set to create encrypted tables. For that, specify `USING pg_tde` in the `CREATE TABLE` statement. -**For example**: -```sql -CREATE TABLE albums ( - album_id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY, - artist_id INTEGER, - title TEXT NOT NULL, - released DATE NOT NULL -) USING pg_tde; ## Next steps [Test TDE](test.md){.md-button} + \ No newline at end of file diff --git a/documentation/docs/yum.md b/documentation/docs/yum.md new file mode 100644 index 00000000..de7b6ae0 --- /dev/null +++ b/documentation/docs/yum.md @@ -0,0 +1,62 @@ +# Install `pg_tde` on Red Hat Enterprise Linux and derivatives + +In version Aplha1, `pg_tde` packages are available in the testing repository for Percona Distribution for PostgreSQL 16.2. Check the [list of supported platforms](install.md#__tabbed_1_2). + +This tutorial shows how to install `pg_tde` with [Percona Distribution for PostgreSQL](https://docs.percona.com/postgresql/latest/index.html). + +## Preconditions + +### Enable / disable modules + +=== "CentOS 7" + + Install the `epel-release` package: + + ```bash + sudo yum -y install epel-release + sudo yum repolist + ``` + +=== "RHEL8/Oracle Linux 8/Rocky Linux 8" + + Disable the ``postgresql`` and ``llvm-toolset``modules: + + ```bash + sudo dnf module disable postgresql llvm-toolset + ``` + +### Install `percona-release` + +You need the `percona-release` repository management tool that enables the desired Percona repository for you. + +1. Install `percona-release`: + + ```bash + sudo yum -y install https://repo.percona.com/yum/percona-release-latest.noarch.rpm + ``` + +2. Enable the repository + + ```bash + sudo percona-release enable-only ppg-16.2 testing + ``` + +## Install Percona Distribution for PostgreSQL + +To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command: + +```bash +sudo yum -y install percona-postgresql-client-common percona-postgresql-common percona-postgresql-server-dev-all percona-postgresql16 percona-postgresql16-contrib percona-postgresql16-devel percona-postgresql16-libs +``` + +## Install `pg_tde` + +To install `pg_tde` packages, run the following command: + +```bash +sudo yum install percona-pg_tde_16 +``` + +## Next steps + +[Setup](setup.md){.md-button} \ No newline at end of file diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 9f39584e..4ba6105e 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -51,6 +51,7 @@ theme: - navigation.tracking + extra_css: - https://unicons.iconscout.com/release/v3.0.3/css/line.css - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css @@ -73,27 +74,27 @@ markdown_extensions: - def_list # https://michelf.ca/projects/php-markdown/extra/#def-list - meta - smarty: - smart_angled_quotes: true + smart_angled_quotes: true - pymdownx.mark - pymdownx.smartsymbols - pymdownx.tilde - pymdownx.superfences - pymdownx.tabbed: - alternate_style: true + alternate_style: true - pymdownx.tilde - pymdownx.details - pymdownx.highlight: - linenums: false + linenums: false - pymdownx.snippets: - base_path: ["snippets"] - auto_append: - - services-banner.md + base_path: ["snippets"] + auto_append: + - services-banner.md - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg - options: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + options: custom_icons: - - _resource/.icons + - _resource/.icons plugins: @@ -142,11 +143,13 @@ nav: - tde.md - Get started: - "Install": "install.md" + - "Via apt": apt.md + - "Via yum": yum.md - "Set up": "setup.md" - - Test TDE: "test.md" + - "Test TDE": "test.md" - functions.md - How to: - - Configure streaming replication: replication.md + - Use reference to external parameters: external-parameters.md - Release notes: - "pg_tde tech preview": release-notes/release-notes.md - uninstall.md