pg_keytool

pg_keytool — generate cluster encryption key and/or send it to the PostgreSQL server

Synopsis

pg_keysetup [option...]

Description

pg_keytool reads either an encryption key or a password from standard input. If it receives a password, it runs the key derivation function (KDF) on it in order to derive the key.

The encryption key is written either to standard output (the default behavior) or, if both host name and port number are specified, sent via a frontend/backend protocol to the PostgreSQL server during start up.

One common use case is that pg_keytool is used within the encryption key command, see the examples in Chapter 32. In this case it sends the encryption key to standard output.

The other use case is that PostgreSQL is started in another way than using pg_ctl, typically using systemd or a custom script. In this case, pg_keytool can be used to send the key to the server. (pg_keytool should connect to the same port or Unix-domain socket to which applications will eventually connect.)

If in the latter case you provide pg_keytool with an encryption key (as opposed to with a password), the utility only ensures transmission of the key to the database server.

Options

-D directory

Specifies the directory where the database cluster is stored. In particular, pg_keytool looks for the kdf_params file here. This file contains parameters of the key derivation function and is needed to derive the encryption key from a password. Thus, a different data directory generally means that a different key will be derived from the same password.

If this option is not passed, pg_keytool tries to get the data directory from the PGDATA environment variable.

-h hostname
--host=hostname

Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix-domain socket.

-p port

Specifies the TCP port or the local Unix-domain socket file extension on which the server is listening for connections. If it is not set, it will be allocated to the port specified at compile time, usually 5432.

-s

Send the key to the PostgreSQL server rather than to standard output. This option does not have to be specified explicitly if the --host or --port option is passed.

-w

Expect the password rather than the encryption key on standard input.