pitrery.1

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH PITRERY 1 "February 3, 2021"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pitrery \- Manage point-in-time recovery for PostgreSQL

.SH SYNOPSIS
.B pitrery
.RI [ options ]
.I action
.RI [ args ]

The command needs to be written in a specific order: pitrery options should be
stated first, and the action options should be stated after the action
keywords. This is important since some switches are the same in both lists of
options, but with different meanings.

.SH DESCRIPTION
The purpose of \fBpitrery\fP is to make it easy to manage the archiving of
PostgreSQL WAL segments and automate the tasks of taking base backups and
preparing a point in time recovery operation if or when that is needed.

The \fBpitrery\fP script itself provides six archive maintenance actions,
.BR backup ", " restore ", " purge ", " list ", " check ", and " configure ,
which create a new base backup, prepare the necessary files for
initiating a recovery, clean up old base backup and WAL segments that
are no longer wanted, display the available base backups, and check
and create the configuration, respectively. It is designed to be run
on the same machine as the PostgreSQL cluster, but the base backups
and WAL segments that it operates on can be archived either locally or
on a remote server using an SSH connection.

The \fBpitrery\fP package also provides two helper scripts,
\fBarchive_wal\fP(1) and \fBrestore_wal\fP(1), which can help with the
task of managing the WAL segments that accumulate between base backups,
allowing them to be compressed and/or stored on remote host away from the
database server. It is not required to use these two scripts to use
\fBpitrery\fP, but similar functionality to copy WAL segments to an archive
space and retrieve them on demand, will need to be provided by some other
means if they are not. They can also be called from other scripts if you
require additional functionality that they don't provide. The main advantage
they offer is keeping all needed configuration for backup and restore tasks
coherently in a single location.


.SH OPTIONS
The following options are available:

.TP
.BI "\-f, \-c " conf
Use option settings from the specified configuration file instead of the
default \fIpitrery.conf\fP file. This may be a full path to the file to use,
or the name of a configuration file in \fI/etc/pitrery\fP.

.TP
.B \-l
List available configuration files in the default directory.

.TP
.B \-V
Display the \fBpitrery\fP version and exit.

.TP
.B \-?
Output the brief help summarising the above options.


.SH ACTIONS
Each of the actions also has its own individual set of options, which must
be passed after the action name.


.SS list
The \fBlist\fP action is used to obtain information about the available base
backups which can be used to begin a recovery operation.

.TP 4
.B SYNOPSIS
.B pitrery
.RI [ options ]
.B list
.RI [ list-options ]
.RI [ [[user@]host:]/path/to/backups ]

.TP 4
.B LIST-OPTIONS
The following options are available for the \fBlist\fP action:

.RS

.TP
.B \-j
Display verbose details in \fBJSON\fP format.

.TP
.B \-v
Display verbose details about the listed base backups.

.TP
.B \-?
Output the brief help summarising the \fBlist\fP options.

.TP
.I [[user@]host:]/path/to/backups
The path to the directory storing the backups. If a host name is
provided, it is used to login to a remote archive with
\fBssh\fP(1). When the host is not given, the lookup is local.

.RE


.SS backup
The \fBbackup\fP action is used to create a new base backup of the present
state of a PostgreSQL cluster. This provides a starting point which WAL
segments can be replayed on top of, so that point in time recovery may be done
for any time after the base backup was completed and for which there is a
sequence of archived WAL segment files up to the desired recovery time.

This must be run on the same machine as the cluster that is to be backed up,
though the base backup may be pushed to a remote machine for storage.

.TP 4
.B SYNOPSIS
.B pitrery
.RI [ options ]
.B backup
.RI [ backup-options ]
.RI [ hostname ]

.TP 4
.B BACKUP-OPTIONS
The following options are available for the \fBbackup\fP action:

.RS

.TP
.BI "\-D " dir
The \fBPGDATA\fP path of the cluster to back up on the local machine. This
will override the \fBPGDATA\fP option from the configuration file.

.TP
.BI "\-s " mode
The storage mode to use for the base backup. The \fImode\fP may be \fBtar\fP
or \fBrsync\fP. This will override the \fBSTORAGE\fP option from the
configuration file.

Using \fBrsync\fP will attempt to hardlink any files that have not changed
since the last base backup was taken. Whether this will actually use less
disk space than a compressed tarball will depend on the size of your cluster
and its pattern of use. It will only try to do this to the most recent base
backup, so it will be equivalent to a plain copy of the \fBPGDATA\fP directory
if the previous backup was not also taken with the rsync method.

.TP
.BI "\-c " compress_bin
The command to use for compressing a base backup taken with the \fBtar\fP
mode. This will override the \fBBACKUP_COMPRESS_BIN\fP option from the
configuration file.

.TP
.BI "\-e " compress_suffix
The suffix to add to a compressed base backup taken with the \fBtar\fP
mode. This will override the \fBBACKUP_COMPRESS_SUFFIX\fP option from the
configuration file.

.TP
.B \-E
Encrypt the file using GnuPG. The list of recipients must given using
the \fB-r\fP option. When this option is used, \fBtar\fP storage method
must be used. This will override the \fBBACKUP_ENCRYPT\fP option from the
configuration file.

.TP
.BI "\-r " keys:...
List of public keys for GPG encryption, it is a colon separeted list
of USER-ID recognized by the \fB--recipient\fP option of \fBgpg\fP(1).
This will override the \fBGPG_ENCRYPT_KEYS\fP option from the
configuration file.

.TP
.B \-t
When naming the backup directory from the stop time of the backup, use
ISO 8601 format. This will override the \fBUSE_ISO8601_TIMESTAMPS\fP
option from the configuration file.

.TP
.B \-T
Timestamp the log messages. This will override the \fBLOG_TIMESTAMP\fP option
from the configuration file (forcing it to be "yes").

.TP
.BI "\-P " psql
The \fBpsql\fP(1) command to use to run SQL statements on the database cluster.
This will override the \fBPGPSQL\fP option from the configuration file.

You should avoid using this to pass extra options to \fBpsql\fP (and instead
use the options below for that). It is mostly for overriding the default
\fBpsql\fP(1) that would otherwise be found in the system \fBPATH\fP.

.TP
.BI "\-h " host
The host address to use to query the database cluster. This may be an IP
address for TCP connection or the path to a unix socket directory for a
local peer connection. It is passed as the \fB\-\-host\fP option to
\fBpsql\fP(1). This will override the \fBPGHOST\fP option from the
configuration file.

.TP
.BI "\-p " port
The port to use to query the database cluster. It is passed as the
\fB\-\-port\fP option to \fBpsql\fP(1). This will override the \fBPGPORT\fP
option from the configuration file.

.TP
.BI "\-U " name
The user name to use to query the database cluster. It is passed as
the \fB\-\-username\fP option to \fBpsql\fP(1). This will override
the \fBPGUSER\fP option from the configuration file. This role must
be a superuser or have the replication attribute to execute
\fBpg_start_backup\fP() on the cluster.

.TP
.BI "\-d " database
The database to use when querying the cluster. It is passed as the
\fB\-\-dbname\fP option to \fBpsql\fP(1). This will override the
\fBPGDATABASE\fP option from the configuration file. Note that this does not
influence what is included in the base backup, point in time recovery is
always for the entire cluster.

.TP
.B \-?
Output the brief help summarising the \fBbackup\fP options.

.TP
.I [[user@]host:]/path/to/backups
The path to the directory storing the backups. If a host name is
provided, it is used to login to a remote archive with
\fBssh\fP(1). When the host is not given, the lookup is local.

.RE


.SS restore
The \fBrestore\fP action is used to select and retrieve the files needed to
begin recovery of a cluster to a particular state, either to the most recently
archived state or a point in time between the oldest base backup and the most
recent WAL segment that is available to be replayed.

It will create a new \fBPGDATA\fP tree from the archived data with a minimal
\fIrecovery.conf\fP ready to begin recovery operations. It may also place a
copy of the \fBpostgres\fP configuration files from the time that the base
backup was made in \fIPGDATA/restored_config_files\fP if they did not exist in
the \fBPGDATA\fP directory at that time.

It will create a new \fBPGDATA\fP tree from the archived data with a minimal set
of recovery configuration keys in \fIpostgresql.conf\fP with a "*.signal" file
(PG>=12) or a minimal \fIrecovery.conf\fP (PG<=11) ready to begin
recovery operations.
It may also place a copy of the \fBpostgres\fP configuration files from the time
that the base backup was made in  \fIPGDATA/restored_config_files\fP if they did
not exist in the \fBPGDATA\fP directory at that time.


.TP 4
.B SYNOPSIS
.B pitrery
.RI [ options ]
.B restore
.RI [ restore-options ]
.RI [ [[user@]host:]/path/to/backups ]

.TP 4
.B RESTORE-OPTIONS
The following options are available for the \fBrestore\fP action:

.RS

.TP
.BI "\-D " dir
The \fBPGDATA\fP path of the cluster on the local machine, that is to be
repopulated ready for recovery. This directory will be created if it does not
already exist, but must be empty if it does (unless the \fB\-R\fP option is
used to force overwriting it). This will override the \fBPGDATA\fP option
from the configuration file.

.TP
.BI "\-x " dir
The directory where WAL segment files will be placed if you wish to
keep those outside of the \fBPGDATA\fP tree. If specified this will
create \fIPGDATA/pg_wal\fP (or \fIPGDATA/pg_xlog\fP as of PostgreSQL
9.6 or less) as a symlink to \fIdir\fP rather than as a directory in
its own right. This will override the \fBPGWAL\fP option from the
configuration file.

.TP
.BI "\-d " date
The initial \fIrecovery_target_time\fP to place in
\fIpostgresql.conf\fP (PG>=12) or in \fIrecovery.conf\fP (PG<=11) which is
the first point in time that replaying the WAL segment files will pause at.
The canonical form of the \fIdate\fP string is:

.nh
.nf
  \fIYYYY\-MM\-DD HH:MM:SS\fP [\fI(+|\-)XXXX\fP]
.fi
.hy

where \fIXXXX\fP is the optional timezone offset, however the \fIdate\fP may be
specified here in any form that \fBdate\fP(1) on your system will recognise,
including the relative date strings such as '1\ hour\ ago' which GNU \fBdate\fP
accepts.

This cannot be earlier than the oldest archived base backup, and can only be
restored to if all the WAL segment files from the nearest base backup to that
time are available and uncorrupted.

.TP
.BI "\-O " user
The user which should be set as the owner of the restored files if
\fBpitrery\fP is run as root. This will override the \fBPGOWNER\fP option
from the configuration file.

.TP
.BI "\-t " tblspc:dir
Change the target directory of tablespace \fItblspc\fP to \fIdir\fP. This
option may be used as many times as required if multiple tablespaces need to
to relocated.

.TP
.B \-n
Do a dry run of the restore, showing information about what it would do but
stopping before actually making any changes to \fBPGDATA\fP.

.TP
.B \-R
Overwrite destination directories. By default the \fBrecovery\fP action will
refuse to proceed if any of the destination directories are not empty. Even
with this option it will still refuse to proceed if a \fIpostmaster.pid\fP
file is present, since attempting a restore into directory that a running
\fBpostgres\fP instance is using is likely to Go Very Badly.

.TP
.BI "\-c " uncompress_bin
The command to use for uncompressing a base backup taken with the \fBtar\fP
mode. This will override \fBBACKUP_UNCOMPRESS_BIN\fP option from the
configuration file.

.TP
.BI "\-e " compress_suffix
The file suffix to expect (e.g., gz, bz2, xz) for a compressed base backup
taken with the \fBtar\fP mode. This will override the
\fBBACKUP_COMPRESS_SUFFIX\fP option from the configuration file.

.TP
.BI "\-m " restore_mode
Restore either in \fBstandby\fP or \fBrecovery\fP mode, which will create
respectivily a \fIstandby.signal\fP or \fPrecovery.signal\fP file. This will
override the \fBRESTORE_MODE\fP option from the configuration file.

.TP
.BI "\-r " command
The command line to use in the \fIrestore_command\fP option written in the
\fIpostgresql.conf\fP file (PG>=12) or of the generated \fIrecovery.conf\fP
file (PG<=11). This will override the \fBRESTORE_COMMAND\fP option from the
configuration file. The default is to use \fBrestore_wal\fP(1).

.TP
.BI "\-C " config
The configuration file to use for \fBrestore_wal\fP(1) if
\fBRESTORE_COMMAND\fP was not explicitly specified on either the command line
or in the configuration file.

.TP
.BI "\-y " command
The command to use to set the \fIrecover_end_command\fP option written in the
\fIpostgresql.conf\fP file (PG>=12) or of the generated \fIrecovery.conf\fP
file (PG<=11). This will override the \fBRECOVERY_END_COMMAND\fP option from
the configuration file.

.TP
.B \-T
Timestamp the log messages. This will override the \fBLOG_TIMESTAMP\fP option
from the configuration file (forcing it to be "yes").

.TP
.B \-?
Output the brief help summarising the \fBrestore\fP options.

.TP
.I [[user@]host:]/path/to/backups
The path to the directory storing the backups. If a host name is
provided, it is used to login to a remote archive with
\fBssh\fP(1). When the host is not given, the lookup is local.

.RE


.SS purge
The \fBpurge\fP action is used to perform an orderly expiry of old archived
data that you no longer wish to retain. It will remove both base backups and
any archived WAL segment files that would no longer be usable with just the
base backups that remain. (It will not remove any archived WAL segment files
if there are no base backups at all though).

Expiry of backups can be based on the maximum number of them that you wish to
keep, the maximum age of them that you wish to keep, or a combination of both
where they will only be removed if they exceed both the age limit and the
limit on the number of backups to retain. This can avoid accidentally removing
all the existing backups if all of them are older than the maximum age.

.TP 4
.B SYNOPSIS
.B pitrery
.RI [ options ]
.B purge
.RI [ purge-options ]
.RI [ [[user@]host:]/path/to/backups ]

.TP 4
.B PURGE-OPTIONS
The following options are available for the \fBpurge\fP action:

.RS

.TP
.BI "\-a " [[user@]host:]/dir
The directory on the (local or remote) host where WAL segment files will be
stored. This will override the \fBARCHIVE_DIR\fP option from the
configuration file. When the host name is omited, the archiving is local.

.TP
.BI "\-m " count
Keep (at least) this number of base backups. The \fBpurge\fP action will
never reduce the number of backups to less than this count, regardless of
their age. This will override the \fBPURGE_KEEP_COUNT\fP option from the
configuration file.

.TP
.BI "\-d " days
Keep all base backups dating back to (at least) this number of days. The
\fBpurge\fP action will never remove backups that are more recent than this,
regardless of the number of them which remain. This will override the
\fBPURGE_OLDER_THAN\fP option from the configuration file.

.TP
.B \-N
Do a dry run of the purge, showing information about what it would remove but
stopping before actually making any changes to the archived files.

.TP
.B \-T
Timestamp the log messages. This will override the \fBLOG_TIMESTAMP\fP option
from the configuration file (forcing it to be "yes").

.TP
.B \-?
Output the brief help summarising the \fBpurge\fP options.

.TP
.I [[user@]host:]/path/to/backups
The path to the directory storing the backups. If a host name is
provided, it is used to login to a remote archive with
\fBssh\fP(1). When the host is not given, the lookup is local.

.RE

.SS configure

The \fBconfigure\fP action creates a configuration file. It needs a
destination of the form \fB[[user@]host:]/path\fP to know where backups
shall be stored. If a host is not provided, the backup is considered
local.

.TP 4
.B SYNOPSIS
.B pitrery
.RI [ options ]
.B configure
.RI [ configure-options ]
.RI destination

.TP 4
.B CONFIGURE-OPTIONS
The following options are available for the \fBconfigure\fP action:

.RS

.TP
.BI "\-o " config_file
The configuration file to create. If it is not a path, the file is
created in the default configuration directory.

.TP
.B \-C
Do not connect to check the configuration of PostgreSQL and output the
parameters to modify in postgresql.conf for WAL archiving.

.TP
.B \-f
If the output configuration file already exists, overwrite it.

.TP
.BI "\-s " mode
The storage mode to use for the base backup. The \fImode\fP may be
\fBtar\fP or \fBrsync\fP. This will configure the \fBSTORAGE\fP
option in the configuration file.

.TP
.BI "\-m " count
Keep (at least) this number of base backups. The \fBpurge\fP action
will never reduce the number of backups to less than this count,
regardless of their age. This will configure the
\fBPURGE_KEEP_COUNT\fP option in the configuration file. Defaults to
2.

.TP
.BI "\-g " days
Keep all base backups dating back to (at least) this number of days. The
\fBpurge\fP action will never remove backups that are more recent than this,
regardless of the number of them which remain. This will configure the
\fBPURGE_OLDER_THAN\fP option in the configuration file.

.TP
.BI "\-D " dir
The \fBPGDATA\fP path of the cluster to back up on the local machine.
This will configure the \fBPGDATA\fP option from the configuration
file. When \-c is given, the configure action gets the the PGDATA
from the \fBdata_directory\fP setting of the cluster, \-D overrides
this, and it is mandatory when not checking the cluster. This will
configure the \fBPGDATA\fP option in the configuration file.

.TP
.BI "\-a " [[user@]host:]/dir
Place to store WAL files, used by \fBarchive_wal\fP(1) and
\fBrestore_wal\fP(1). This will configure \fBARCHIVE_USER\fP,
\fBARCHIVE_HOST\fP and \fBARCHIVE_DIR\fP. When a host is missing,
archiving is considered local. When not used, the configuration falls
back to the destination provided for backups, and \fBARCHIVE_DIR\fP is
configured to "$BACKUP_DIR/archived_wal"

.TP
.B \-E
Encrypt the backup's files and the archived WAL files using GnuPG. The list of
recipients must given using the \fB-r\fP option. When this option is used,
\fBtar\fP storage method must be used for base backups. This will override the
\fBBACKUP_ENCRYPT\fP and \fBARCHIVE_ENCRYPT\fP options from the
configuration file.

.TP
.BI "\-r " keys:...
List of public keys for GPG encryption, it is a colon separeted list
of USER-ID recognized by the \fB--recipient\fP option of \fBgpg\fP(1).
This will override the \fBGPG_ENCRYPT_KEYS\fP option from the
configuration file.

.TP
.BI "\-P " psql
The \fBpsql\fP(1) command to use to run SQL statements on the database cluster.
This will configure the \fBPGPSQL\fP option in the configuration file.

You should avoid using this to pass extra options to \fBpsql\fP (and instead
use the options below for that). It is mostly for overriding the default
\fBpsql\fP(1) that would otherwise be found in the system \fBPATH\fP.

.TP
.BI "\-h " host
The host address to use to query the database cluster. This may be an IP
address for TCP connection or the path to a unix socket directory for a
local peer connection. It is passed as the \fB\-\-host\fP option to
\fBpsql\fP(1). This will configure the \fBPGHOST\fP option in the
configuration file.

.TP
.BI "\-p " port
The port to use to query the database cluster. It is passed as the
\fB\-\-port\fP option to \fBpsql\fP(1). This will configure the \fBPGPORT\fP
option in the configuration file.

.TP
.BI "\-U " name
The user name to use to query the database cluster. It is passed as
the \fB\-\-username\fP option to \fBpsql\fP(1). This will configure
the \fBPGUSER\fP option in the configuration file. This role must
be a superuser or have the replication attribute to execute
\fBpg_start_backup\fP() on the cluster.

.TP
.BI "\-d " database
The database to use when querying the cluster. It is passed as the
\fB\-\-dbname\fP option to \fBpsql\fP(1). This will configure the
\fBPGDATABASE\fP option in the configuration file. Note that this does not
influence what is included in the base backup, point in time recovery is
always for the entire cluster.

.TP
.B \-?
Output the brief help summarising the \fBconfigure\fP options.

.TP
.I [[user@]host:]/path/to/backups
Place where to store the backups. When host is given, backup is done
over SSH, otherwise it is considered local. This will configure the
\fBBACKUP_USER\fP, \fBBACKUP_HOST\fP and \fBBACKUP_DIR\fP options in
the configuration file.

.RE

.SS check
The \fBcheck\fP action is used to check if a configuration file is
correct or backup policy and archived WAL files. The action tests if
the backup directory is reachable, if WAL archiving can be done with
\fBarchive_wal\fP(1), if PostgreSQL is up and properly configured for
PITR and if the current user can actually backup the files.

.TP 4
.B SYNOPSIS
.B pitrery
.RI [ options ]
.B check
.RI [ check-options ]
.RI [ [[user@]host:]/path/to/backups ]

.TP 4
.B CHECK-OPTIONS
The following options are available for the \fBcheck\fP action:

.RS

.TP
.BI "\-C " config_file
The configuration file to check. It can also be provided using the \-c
option of \fBpitrery\fP.

.TP
.B \-B
Check backups instead of the configuration.

.TP
.BI "\-m " count
When checking backups, fail when the number of backups is less than
count. If not set, fallback to the value of \fBPURGE_KEEP_COUNT\fP.

.TP
.BI "\-g " age
When checking backups, Fail when the newest backup is older than age
in days. A time unit can specified: the supported units are "s"
(seconds), "min" (minutes), "h" (hours) and "d" (days). If not set,
fallback to the value of \fBPURGE_OLDER_THAN\fP.

.TP
.B \-A
Check archived WAL files instead of the configuration.

.TP
.BI "\-c " uncompress_bin
The command to use for uncompressing WAL segment files. This will override
\fBARCHIVE_UNCOMPRESS_BIN\fP option from the configuration file.

.TP
.BI "\-a " [[user@]host:]/dir
Place where WAL files are stored.

.TP
.B \-n
When checking backups, behave like a Nagios plugin.

.TP
.B \-?
Output the brief help summarising the \fBcheck\fP options.

.TP
.I [[user@]host:]/path/to/backups
The path to the directory storing the backups. If a host name is
provided, it is used to login to a remote archive with
\fBssh\fP(1). When the host is not given, the lookup is local.

.RE

.SH CONFIGURATION
The following options may be configured persistently in one or more
configuration files. The configuration file will be sourced as a
\fBbash\fP(1) shell snippet, so it must contain only valid shell syntax,
though it should usually only contain assignments to the following variables:

.SS Cluster configuration
These variables specify the location and manner of accessing the PostgreSQL
cluster for \fBbackup\fP and \fBrestore\fP operations.

.TP
.B PGDATA
The path to the PostgreSQL cluster data directory. This must be set (or
passed on the command line) for \fBbackup\fP and \fBrestore\fP operations.

.TP
.B PGPSQL
The \fBpsql\fP(1) program to use when querying the database for \fBbackup\fP
operations. If not set, then the \fBpsql\fP binary found in the system
\fBPATH\fP will be used.

You should avoid using this to pass extra options to \fBpsql\fP (and instead
use the options below for that). It is mostly for overriding the default
\fBpsql\fP(1) that would otherwise be found in the system \fBPATH\fP.

.TP
.B PGHOST
The host address to use to query the database cluster. This may be an IP
address for TCP connection or the path to a unix socket directory for a
local peer connection. It is passed as the \fB\-\-host\fP option to
\fBpsql\fP(1) for \fBbackup\fP operations. If not set the \fBpsql\fP default
will be used.

.TP
.B PGPORT
The port to use to query the database cluster. It is passed as the
\fB\-\-port\fP option to \fBpsql\fP(1) for \fBbackup\fP operations.
If not set the \fBpsql\fP default will be used.

.TP
.B PGUSER
The username to use when querying the database. It is passed as the
\fB\-\-username\fP option to \fBpsql\fP(1) for \fBbackup\fP operations.
This must be a superuser with permission to execute \fBpg_start_backup\fP()
on the cluster. If not set the \fBpsql\fP default will be used.

.TP
.B PGDATABASE
The database to use when querying the cluster. It is passed as the
\fB\-\-dbname\fP option to \fBpsql\fP(1) for \fBbackup\fP operations.
Note that this does not influence what is included in the base backup,
point in time recovery is always for the entire cluster.
If not set the \fBpsql\fP default will be used.

.TP
.B PGOWNER
The user which should be set as the owner of the restored files if
\fBpitrery\ restore\fP is run as root.

.TP
.B PGWAL
The directory where WAL segment files will be placed if you wish to
keep those outside of the \fBPGDATA\fP tree when a \fBrestore\fP
operation is performed. If set this will create \fIPGDATA/pg_wal\fP
(or \fIPGDATA/pg_xlog\fP as of PostgreSQL 9.6 or less) as a symlink
to the specified path rather than as a directory in its own right.


.SS Base backup configuration
These variables specify the location and manner of accessing the base backup
archive for all operations.

.TP
.B BACKUP_DIR
The directory on the (local or remote) host where base backups are stored.
Each backup will have its own subdirectory under this, named with the timestamp
of when the \fBbackup\fP operation completed.

.TP
.B BACKUP_HOST
The target host where remote backups will be stored. The user running
\fBpitrery\fP must be able to \fBssh\fP(1) to this host and run commands in
the remote shell. Typically this means that either a passwordless \fBssh\fP
key must be available, or an agent must be active to permit this access.
If left empty, backups are local.

.TP
.B BACKUP_USER
The username to use for \fBssh\fP(1) access to the remote backup storage.
If not set, the \fBssh\fP default will be used (either taking the user from
the \fBssh\fP configuration for the target host, or the user that is running
the command).

.TP
.B STORAGE
The base backup storage method to use. The \fBtar\fP method creates one
compressed tarball for \fBPGDATA\fP and each tablespace. The \fBrsync\fP
method will attempt to optimise the amount of data transferred and the amount
of disk space used by doing a differential backup, hardlinking files that have
not changed to the copies from the previous backup (which must also have been
done with the rsync method for this to work). The disk space used by a highly
compressed tarball may still be less than what is saved by the hardlinks
(depending on the size of your cluster and its use patterns), but rsync is
likely to be able to complete the backup faster with less data transferred.

.TP
.B PRE_BACKUP_COMMAND
An optional user defined command which may be run before a \fBbackup\fP
operation begins. See the \fBBACKUP\ HOOKS\fP section below for more
details.

.TP
.B POST_BACKUP_COMMAND
An optional user defined command which may be run after a \fBbackup\fP
operation us completed. See the \fBBACKUP\ HOOKS\fP section below for more
details.


.SS WAL archiving configuration
These variables are used by the \fBarchive_wal\fP(1) and
\fBrestore_wal\fP(1) scripts and by the \fBpurge\fP action when managing
archived WAL segment files.

.TP
.B ARCHIVE_HOST
The host name for \fBssh\fP(1) login to a remote WAL archive. Leave
it empty to archive on the local host.

.TP
.B ARCHIVE_USER
The user name for \fBssh\fP(1) login to a remote WAL archive.
If not set, the PostgreSQL server process owner is used for
\fBarchive_wal\fP(1) and \fBrestore_wal\fP(1) operations and the
user that run pitrery is used during \fBpurge\fP operations.

.TP
.B ARCHIVE_DIR
The directory where archived WAL segment files will be kept on the (local
or remote) host. If they are kept on the same machine as the \fBBACKUP_HOST\fP
they can be stored near the base backups by setting this to something like:

.nh
.nf
  ARCHIVE_DIR="$BACKUP_DIR/archived_wal"
.fi
.hy

.TP
.B ARCHIVE_OVERWRITE
If set to "yes", overwrite destination files if they exist. Since
preventing overwrite adds a performance penalty over SSH, it is set to
"yes" by default.

.TP
.B ARCHIVE_CHECK
If set set to "yes", check the md5 of the archived
file to the md5 of the original WAL file. It is useful when the
storage and the network is not reliable. If overwriting is disabled,
the md5 check enabled and the archive already exists, the archiving
returns success if the md5 check is successful. This option does not
apply on local archiving.

.TP
.B ARCHIVE_FLUSH
If set to "yes", force an immediate flush of the archived file to disk
before returning success. It may slow down the archiving process but
ensure archives are not corrupted in case of a power loss on the
destination.

.TP
.B ARCHIVE_FILE_CHMOD
Configures the permission of the archived file. The value must be in
octal form as understood by \fBchmod\fP(1). It can help with uid/gid
issues on NFS shares used by different hosts, and should not be
necessary in most of the cases.


.SS Compression configuration
These variables are used to configure the compression of the archived WAL
segment files and base backups which use the \fBtar\fP \fBSTORAGE\fP mode.

.TP
.B ARCHIVE_COMPRESS
If set to "yes", compress the archived WAL segment files with
.BR ARCHIVE_COMPRESS_BIN.

.TP
.B ARCHIVE_COMPRESS_BIN
The command line to use to compress archived WAL segment files.
The program used here must support a \fB\-c\fP option to send output to
\fIstdout\fP and read input from \fIstdin\fP (such as
.BR gzip (1),
.BR pigz (1),
.BR bzip2 (1),
.BR pbzip2 (1),
.BR xz (1)
). If not set, the default is to use "gzip \-4".

.TP
.B ARCHIVE_COMPRESS_SUFFIX
The suffix to use for files compressed by \fBARCHIVE_COMPRESS_BIN\fP.
If not set the default is to use "gz".

.TP
.B ARCHIVE_UNCOMPRESS_BIN
The command line to use to decompress archived WAL segment files.
It must take the file to process as its first parameter. If not set, the
default is to use
.BR gunzip (1).

.TP
.B BACKUP_COMPRESS_BIN
The command to use for compressing a base backup taken with the \fBtar\fP
\fBSTORAGE\fP mode. It must be able to take input piped to \fIstdin\fP
and send its output to \fIstdout\fP (such as
.BR gzip (1),
.BR pigz (1),
.BR bzip2 (1),
.BR pbzip2 (1),
.BR xz (1)
). If not set, the default is to use "gzip \-4".

.TP
.B BACKUP_COMPRESS_SUFFIX
The suffix to add to a compressed base backup taken with the \fBtar\fP
\fBSTORAGE\fP mode. If not set the default is to use "gz".

.TP
.B BACKUP_UNCOMPRESS_BIN
The command to use for uncompressing a base backup taken with the \fBtar\fP
\fBSTORAGE\fP mode. It must be able to take the file to process as its first
parameter or input piped to \fIstdin\fP, and support a \fB\-c\fP option to
send output to \fIstdout\fP. If not set, the default is to use
.BR gunzip (1).

.TP
.B USE_ISO8601_TIMESTAMPS
When naming the backup directory from the stop time of the backup, use
ISO 8601 format. Defaults to "no" to keep the backward compatibility,
as mixing formats of backup names would break the sorting of backups on
restore.

.SS Encryption configuration
This variables are used to configure the encryption with GnuPG for the
base backups and the archived WAL files.

.TP
.B BACKUP_ENCRYPT
When set to "yes", use GPG to encrypt the backups.
This only applies to the \fBtar\fP storage, as ciphered files would not be
synchronized by rsync. Note that compression options do not apply when
encrypting files as GPG already compresses the output file using
\fBzlib\fP(3) by default.

.TP
.B ARCHIVE_ENCRYPT
When set to "yes", use GPG to encrypt the archived WAL files.

.TP
.B GPG_ENCRYPT_KEYS
When GPG encryption is enabled, specifies the recipients to encrypt
data to. It can be a colon separated list of recipients. All public
keys must be available in the keyring of the user running the
PostgreSQL cluster and the user who runs pitrery for base backups if
different.

.SS Transfer configuration
This variables are used to configure the behavior of rsync when used
for the base backups.

.TP
.B RSYNC_WHOLEFILE
When set to "yes", disable the rsync on the fly comparison algorithm
by adding --whole-file to the \fBrsync\fP(1) commandline. This may improve
performance over NFS. Default is "no".

.TP
.B RSYNC_BWLIMIT
Limit the bandwidth usage for rsync. This is the value of --bwlimit of
\fBrsync\fP(1). With no unit, it is in kB/s. Leave empty for no limit,
there is no limit by default.

.SS Restore configuration
These variables are used to configure the \fBrestore\fP action operation.

.TP
.B RESTORE_COMMAND
The command line to use in the \fIrestore_command\fP option of the
\fIpostgresql.conf\fP file (PG>=12) or of \fIrecovery.conf\fP file (PG<=11)
that is generated by the \fBrestore\fP action.
This is the command that PostgreSQL will use to attempt to retrieve archived
WAL segment files needed during recovery.
If not set, the default is to use \fBrestore_wal\fP(1).

.TP
.B RESTORE_MODE
Which mode to use when the cluster starts after its restore, "recovery" or
"standby" are the two choices. If not set, the default is to use
\fBrecovery\fP mode.

.TP
.B RECOVERY_END_COMMAND
The command to use to set the \fIrecover_end_command\fP option written in the
\fIpostgresql.conf\fP file (PG>=12) or of the generated \fIrecovery.conf\fP
file (PG<=11) that is generated by the \fBrestore\fP action.
This parameter specifies, in PostgreSQL version 8.4 and greater, a shell
command that will be executed once only at the end of recovery. Any %r is
replaced by the name of the file containing the last valid restart point, like
in \fIarchive_cleanup_command\fP.


.SS Purge configuration
These variables are used to configure the \fBpurge\fP action operation.

.TP
.B PURGE_KEEP_COUNT
Keep (at least) this number of base backups. The \fBpurge\fP action will
never reduce the number of backups to less than this count, regardless of
their age.

.TP
.B PURGE_OLDER_THAN
Keep all base backups dating back to (at least) this number of days. The
\fBpurge\fP action will never remove backups that are more recent than this,
regardless of the number of them which remain.


.SS Logging configuration
These variables are used to configure the logging output of \fBpitrery\fP
actions.

.TP
.B LOG_TIMESTAMP
Timestamp the warning and error messages that may be output when \fBpitrery\fP
actions are performed.

.TP
.B SYSLOG
If set to "yes", then messages output by \fBarchive_wal\fP(1) and
\fBrestore_wal\fP(1) will be written to the \fBsyslog\fP(3) instead of to
the \fBstdio\fP(3) streams. This should be coordinated with the configuration
used in \fIpostgresql.conf\fP, in particular whether the logging collector is
being used to capture the \fBstdio\fP streams. When logging to \fBsyslog\fP,
messages sent to \fIstdout\fP will be logged with \fBLOG_INFO\fP priority,
while messages to \fIstderr\fP will be logged with \fBLOG_ERR\fP priority.

.TP
.B SYSLOG_FACILITY
Specify the syslog facility to use. If not set, the default is to use
\fBlocal0\fP. See \fBlogger\fP(1) for details of the valid facility strings
that can be used here.

.TP
.B SYSLOG_IDENT
An identifier to prefix \fBsyslog\fP output with. If not set, the default is
to use the string "postgres".


.SH BACKUP HOOKS
When the \fBbackup\fP operation is performed, user defined commands may be run
before the backup starts and after it is completed to perform any additional
actions that you might require.

The \fBPRE_BACKUP_COMMAND\fP is run before the backup is started.

The \fBPOST_BACKUP_COMMAND\fP is run after the backup is finished.
This command is run even if the backup fails, but not if the backup fails
because of the \fBPRE_BACKUP_COMMAND\fP or earlier (i.e. the sequence of
"pre\ command"\ ->\ "base\ backup"\ ->\ "post\ command" execution is ensured).

The following environment variables are available to the hook commands, to
access the PostgreSQL cluster or the current backup:

.TP
.B PITRERY_HOOK
Contains the name of the hook that is being run, either \fIpre_backup\fP or
\fIpost_backup\fP (so that the same command may be used to perform actions
before and after the backup runs).

.TP
.B PITRERY_PSQL
Contains the \fBpsql\fP(1) command line needed to run SQL statements on the
saved PostgreSQL cluster.

.TP
.B PITRERY_DATABASE
Contains the name of the database used for \fBpsql\fP(1) connections.

.TP
.B PITRERY_BACKUP_DIR
Contains the full path to the directory used for the base backup.

.TP
.B PITRERY_BACKUP_LOCAL
Will contain "yes" if base backups are being stored on the local machine
(and so can be used to know if \fBssh\fP(1) is required to access the backup
directory).

.TP
.B PITRERY_SSH_TARGET
Contains the \fIuser@host\fP part needed to access the backup server.

.TP
.B PITRERY_EXIT_CODE
Contains the exit code of the \fBbackup\fP operation when the
\fBPOST_BACKUP_COMMAND\fP is run so it can know if there was a problem.
Will be 0 for success, 1 for failure.


.SH REPLICATION SLOTS
For PostgreSQL >= 9.4. If the primary server that is being backed up
has streaming replication slots defined for hot standby servers, they
will not be included directly in the base backup. Even in the cases
where you do want them to be recreated when restoring from a backup,
the state information captured at the time of the backup will almost
certainly be out of date, and the WAL segments required to recover
from that state will almost certainly no longer be present in the
normal \fIpg_wal\fP cache, even if they have been kept in a separate
archive elsewhere. So the best solution is normally to create them
again freshly when rebuilding a cluster, whatever the reason for
needing to rebuild it from a backup might be.

To assist with that, the \fBbackup\fP action will create a record of
the physical replication slots that existed at the time of the base
backup, and the \fBrestore\fP action will create a SQL script that can
be used to recreate them again if that is desired. Note that any
change to the list of replication slots which took place after the
base backup was taken will not be preserved, so you should probably
create a new base backup shortly after any 'permanent' change adding
or removing them, but that should be a fairly infrequent operation in
most cases.

To recreate the replication slots which were defined at the time of the base
backup, then after a \fBrestore\fP you can run something like:

 psql\ \-f $PGDATA/restore_replication_slots.sql



.SH FILES
.TP
.I /etc/pitrery/pitrery.conf
The default \fBpitrery\fP configuration file if not explicitly specified.

.TP
.I $PGDATA/postgresql.conf
For a PostgreSQL instance \fBv.12 or higher\fP, the file to which the
recovery configuration keys are written by \fBpitrery\ restore\fP, which allows
\fBrestore_wal\fP to be used to recover any WAL segment files needed during
database recovery.

.TP
.I $PGDATA/recovery.signal
For a PostgreSQL instance \fBv.12 or higher\fP, this file is used to start the
server in targeted \fBrecovery\fP mode.

.TP
.I $PGDATA/standby.signal
For a PostgreSQL instance \fBv.12 or higher\fP, this file is used to start the
server in targeted \fBstandby\fP mode.

.TP
.I $PGDATA/recovery.conf
For a PostgreSQL instance \fBv.11 or lower\fP, the file created in the
\fBPGDATA\fP directory by \fBpitrery\ restore\fP which configures if and/or
how to use \fBrestore_wal\fP to retrieve any needed WAL segment files
during database recovery.


.SH NOTES
.B Project :
https://dalibo.github.io/pitrery

.B Installation :
https://dalibo.github.io/pitrery/install.html

.B Source Code :
https://github.com/dalibo/pitrery

.B Bugs :
https://github.com/dalibo/pitrery/labels/bug


.SH SEE ALSO
.BR archive_wal(1),
.BR restore_wal(1).


.SH AUTHOR
.B pitrery
was written by Nicolas Thauvin <nicolas.thauvin@dalibo.com>.
This man page was written by Ron <ron@debian.org>.