pgBackRest

Search Marketplace for pgBackRest, select the SecureAnyCloud publisher, and click Create.

Configure the Network Security Group to allow TCP 22 for administration only. Do not open TCP 5432. This image deliberately binds PostgreSQL to loopback, so nothing is listening on that port to reach.

The image declares a dedicated data disk for the backup repository. Azure provisions the disk and mounts it at /var/lib/pgbackrest automatically. Size it for your retention policy before you deploy.

RG="database-prod"; LOCATION="eastus"; VM_NAME="pgbackrest1" IMAGE_URN="sac1647283583153:pgbackrest-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:pgbackrest-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
# Open the administration port only. Do NOT open 5432 — PostgreSQL is loopback bound.
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1001

On first boot, the image runs through these steps:

• Asserts that the repository volume is mounted
• Generates the per-VM PostgreSQL password and repository passphrase
• Writes the per-machine pgbackrest.conf
• Starts PostgreSQL and creates the main stanza
• Runs pgbackrest check
• Takes an initial full backup and verifies the repository
• Enables the backup timers

This completes within a minute or two. SSH in as azureuser and read the credentials:

sudo cat /root/pgbackrest-credentials.txt

The file records the PostgreSQL superuser password, the repository encryption passphrase, the stanza name and the repository path. It is 0600 root:root, so only root can read it.

Back up the repository passphrase somewhere safe. The repository is encrypted with aes-256-cbc using a passphrase unique to this machine. Without the passphrase, your backups cannot be decrypted and therefore cannot be restored.

Confirm that PostgreSQL is running and that pgBackRest and PostgreSQL report the pinned versions. The listener list shows that the database is bound to loopback and that SSH is the only externally reachable port.

systemctl is-active postgresql@18-main.service pgbackrest version psql --version ss -tlnH | awk '{print $4}' | sort -u

Expected output:

active pgBackRest 2.58.0 psql (PostgreSQL) 18.4 0.0.0.0:22 127.0.0.1:5432 127.0.0.53%lo:53 127.0.0.54:53 [::]:22

127.0.0.1:5432 is PostgreSQL on loopback. 127.0.0.53 and 127.0.0.54 are the systemd resolver stub, also on loopback. Only port 22 is bound to a routable address.

The pgbackrest info command shows the state of your backup chain: the stanza, the cipher, the WAL archive range, and every backup with its size and timing. The initial full backup taken at first boot is already there.

sudo -u postgres pgbackrest --stanza=main info

Expected output:

stanza: main status: ok cipher: aes-256-cbc db (current) wal archive min/max (18): 000000010000000000000002/000000010000000000000003 full backup: 20260719-022052F timestamp start/stop: 2026-07-19 02:20:52+00 / 2026-07-19 02:20:57+00 wal start/stop: 000000010000000000000002 / 000000010000000000000003 database size: 22.5MB, database backup size: 22.5MB repo1: backup set size: 2.7MB, backup size: 2.7MB

status: ok means the stanza is healthy and WAL archiving is working. cipher: aes-256-cbc confirms that the repository is encrypted.

The pgBackRest workflow is four commands. The image has already run the first two for you. The last two are what you run day to day.

stanza-create defines a stanza, a named backup configuration for one PostgreSQL cluster. First boot created the main stanza. Run this command again only when you add a new cluster or repository.

check validates the configuration end to end. It confirms that pgBackRest can reach the cluster, that the repository is writable, and that WAL archiving actually delivers a segment into the repository. Run it after any configuration change.

sudo -u postgres pgbackrest --stanza=main check

backup takes a backup. --type=full copies everything. --type=diff copies what changed since the last full backup. --type=incr copies what changed since the last backup of any type.

sudo -u postgres pgbackrest --stanza=main --type=incr backup

verify re-reads the repository and checks every file against its stored checksum. It catches silent corruption before you need the backup, rather than during a restore.

sudo -u postgres pgbackrest --stanza=main verify

A backup you have never restored is a hypothesis. This is the restore path, and it is the same one the image proves on every self test.

restore writes the cluster back from the repository, so stop PostgreSQL first. The --delta option makes the restore incremental. pgBackRest compares checksums and copies only the files that differ, which is much faster than a full copy on a large cluster.

sudo systemctl stop postgresql@18-main.service
sudo -u postgres pgbackrest --stanza=main --delta --type=immediate --target-action=promote restore
sudo systemctl start postgresql@18-main.service

--type=immediate recovers to the earliest point at which the cluster is consistent, which is the end of the backup being restored. --target-action=promote brings the cluster out of recovery and makes it writable again once that point is reached.

Confirm that the cluster is back and out of recovery:

sudo -u postgres psql -tAc "SELECT pg_is_in_recovery();"

f means recovery has finished and the cluster is accepting writes.

Point-in-time recovery. Because WAL is archived continuously, you can restore to any moment covered by the archive, not only to a backup boundary. Replace --type=immediate with a timestamp target:

sudo systemctl stop postgresql@18-main.service
sudo -u postgres pgbackrest --stanza=main --delta \
  --type=time --target="2026-07-19 02:21:00+00" --target-action=promote restore
sudo systemctl start postgresql@18-main.service

The image ships /usr/local/sbin/pgbackrest-selftest.sh. It proves that the per-machine credentials authenticate, that wrong passwords are rejected, and that PostgreSQL is bound to loopback and the repository is encrypted. It then performs a complete round trip. It writes a known row, backs it up, verifies the repository, drops the table, restores from the repository, and asserts that the row came back intact.

This is the same check the image passes before it is published. It is destructive and self-healing, so run it on a machine whose current state you are willing to roll back to the backup it takes.

sudo /usr/local/sbin/pgbackrest-selftest.sh

Expected output ends with:

OK: RESTORED DATA MATCHES: sac-selftest-20260719022500-4211 SELFTEST_OK: per-VM credentials authenticate, wrong passwords rejected, listener loopback-only, repository encrypted, and a real backup/verify/restore round trip returned the known row intact.

systemd timers schedule backups for you, and they are enabled on first boot. Each runs as the postgres user with a low CPU and idle I/O priority, so scheduled backups never starve the database. Each also carries a randomized delay, so a fleet of machines does not stampede the repository.

• pgbackrest-full.timer: Sunday 01:00, full backup
• pgbackrest-diff.timer: Monday to Saturday 01:00, differential backup
• pgbackrest-incr.timer: hourly, at 30 minutes past, incremental backup
• pgbackrest-verify.timer: Sunday 03:00, repository verification

List the timers and their next run times:

systemctl list-timers 'pgbackrest-*' --all --no-pager

To change a schedule, edit the timer with sudo systemctl edit pgbackrest-incr.timer and set a new OnCalendar= value. Then run sudo systemctl daemon-reload.

Retention is set in /etc/pgbackrest/pgbackrest.conf. repo1-retention-full=2 keeps two full backups and everything that depends on them, and repo1-retention-diff=6 keeps six differentials. pgBackRest expires older backups automatically at the end of each backup run.

The same appliance can protect a PostgreSQL server running elsewhere. This is a configuration change only, with no reinstall. pgBackRest reaches the remote host over SSH as the postgres user.

On this backup host, generate a key for postgres and install it on the database server:

sudo -u postgres ssh-keygen -t ed25519 -N '' -f /var/lib/postgresql/.ssh/id_ed25519
sudo -u postgres cat /var/lib/postgresql/.ssh/id_ed25519.pub
# Append that public key to /var/lib/postgresql/.ssh/authorized_keys on the database server.

Then point the stanza at the remote cluster in /etc/pgbackrest/pgbackrest.conf:

[main] pg1-host=db1.internal.example.com pg1-host-user=postgres pg1-path=/var/lib/postgresql/18/main pg1-port=5432

Install pgBackRest on the database server too, give it the same repo1-cipher-pass, and set archive_command there to push to this host. Then re-run stanza-create and check. The check command is the gate: it does not pass until archiving from the remote cluster reaches this repository.

Storing the repository in object storage removes the local disk as a single point of failure and gives effectively unlimited retention. This is again a configuration-only change. Replace the repo1-path block in /etc/pgbackrest/pgbackrest.conf.

For Azure Blob Storage:

[global] repo1-type=azure repo1-azure-account=<storage-account-name> repo1-azure-container=<container-name> repo1-azure-key=<storage-account-key> repo1-path=/pgbackrest repo1-cipher-type=aes-256-cbc repo1-cipher-pass=<your-passphrase>

For S3-compatible storage:

[global] repo1-type=s3 repo1-s3-bucket=<bucket-name> repo1-s3-region=<region> repo1-s3-endpoint=s3.<region>.amazonaws.com repo1-s3-key=<access-key-id> repo1-s3-key-secret=<secret-access-key> repo1-path=/pgbackrest repo1-cipher-type=aes-256-cbc repo1-cipher-pass=<your-passphrase>

Keep repo1-cipher-type and repo1-cipher-pass set. With object storage, the repository leaves your machine, so client-side encryption is what keeps the contents private. After changing the repository, run stanza-create and then check against the new location before you rely on it.

pgBackRest also supports multiple repositories at once (repo2-*, repo3-*). You can keep fast local backups on the data volume and push a second copy to object storage for offsite retention.

The repository is encrypted with aes-256-cbc using repo1-cipher-pass, generated uniquely for this machine at first boot and recorded in /root/pgbackrest-credentials.txt.

Rotating the passphrase invalidates every existing backup. pgBackRest cannot decrypt objects written under a previous passphrase. Changing repo1-cipher-pass does not re-encrypt the repository. It makes everything already in the repository unreadable.

If you must rotate, create a new stanza or a new repository with the new passphrase and take a fresh full backup. Keep the old passphrase for as long as you need to restore from the old backups.

Treat the passphrase as you would the backups themselves. Store it in your secret manager and keep it recoverable independently of the machine, because a repository you cannot decrypt is a repository you do not have.

PostgreSQL is bound to loopback. Do administrative work on the machine as the postgres system user through peer authentication, which needs no password:

sudo -u postgres psql -tAc "SELECT version();"

To connect over TCP, use the per-machine superuser password from the credentials file:

PGPASSWORD='<the postgres.password value from /root/pgbackrest-credentials.txt>' \
  psql -h 127.0.0.1 -U postgres -c "SELECT current_user;"

To serve clients on your VNet, make three deliberate changes:

• Set listen_addresses in /etc/postgresql/18/main/conf.d/10-sac-pgbackrest.conf.
• Add a pg_hba.conf rule scoped to your subnet CIDR using scram-sha-256.
• Open TCP 5432 in the Network Security Group for that subnet only.

Never open 5432 to the internet.

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for pgBackRest. Select the SecureAnyCloud listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, and create or select a security group that allows inbound port 22 from your management network. Leave the root volume at the default size or larger. The pgBackRest repository volume is attached automatically from the image.

Select Launch instance. First-boot initialization runs once, after the instance state becomes Running and the status checks pass. It generates the per-instance secrets, creates the stanza, takes and verifies an initial full backup, and enables the scheduled timers. This takes a minute or two.

The following command launches an instance from the SecureAnyCloud pgBackRest Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing. Replace <key-name> with your EC2 key pair name and <subnet-id> with your subnet ID. Replace <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --metadata-options HttpTokens=required \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=pgbackrest}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name. You can find them in the EC2 console or with aws ec2 describe-instances.

Connect over SSH using your key pair and the login user for your operating system variant. For the Ubuntu 24.04 variant, the SSH login user is ubuntu.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands.

First boot generated the per-instance PostgreSQL superuser password and the repository encryption passphrase, and stored them in a root-only file. View them with the command below. Because the file contains secrets, this guide does not print its contents.

sudo cat /root/pgbackrest-credentials.txt

To confirm that the credentials file exists with the correct owner and 0600 permissions without revealing its contents, run:

sudo ls -l /root/pgbackrest-credentials.txt

pgBackRest and PostgreSQL are installed at pinned versions from the official PostgreSQL (PGDG) package repository. Confirm the pgBackRest version:

pgbackrest version

The output is pgBackRest 2.58.0.

PostgreSQL runs as a system service that is enabled and started on boot. Confirm that it is active:

systemctl is-active postgresql@18-main.service

The output is active.

Confirm that the listener is bound to loopback only, so the database is never exposed to the network:

ss -tlnH | grep ':5432'

The address is 127.0.0.1:5432, never 0.0.0.0.

pgbackrest check validates the configuration, the repository and WAL archiving end to end. It is safe to run at any time and makes no changes:

sudo -u postgres pgbackrest --stanza=main check

The output ends with check command end: completed successfully.

Now take an incremental backup. This adds a backup to the repository and is a normal, non-destructive operation:

sudo -u postgres pgbackrest --stanza=main --type=incr backup

The output ends with backup command end: completed successfully. You can take a full or differential backup the same way with --type=full or --type=diff.

All pgBackRest operations run as the postgres system user through sudo -u postgres. That user authenticates to PostgreSQL by peer authentication, so no password is needed for administration.

pgbackrest info shows the state of the repository: its encryption cipher, the WAL archive range, and every backup with its type, timestamp and size.

sudo -u postgres pgbackrest --stanza=main info

The output reports status: ok, cipher: aes-256-cbc, and the set of full, differential and incremental backups. Each incremental references the full backup it builds on. The repository is encrypted with the per-instance passphrase, so its contents are unreadable without it.

The image ships four systemd timers, enabled and ready. First boot starts them, and on a running instance they fire on their schedule:

• pgbackrest-full.timer: a full backup weekly (Sunday 01:00)
• pgbackrest-diff.timer: a differential backup daily (Monday to Saturday 01:00)
• pgbackrest-incr.timer: an incremental backup hourly (at :30)
• pgbackrest-verify.timer: repository verification weekly (Sunday 03:00)

Each timer carries a randomized delay, so a fleet of instances does not stampede. The backup services run at reduced I/O and CPU priority, so scheduled backups never starve the database. List the timers and their next run times:

systemctl list-timers 'pgbackrest-*' --all --no-pager

To match your recovery policy, adjust retention (repo1-retention-full, repo1-retention-diff) and the schedules in /etc/pgbackrest/pgbackrest.conf and the pgbackrest-*.timer units.

pgBackRest restores a cluster from the repository. A restore is destructive: it stops PostgreSQL and overwrites the data directory from the backup. Run it deliberately, on a host you intend to recover. The commands below are for reference, so do not run them casually on a production instance.

The image also ships a self-test that performs a complete backup, verify and restore round trip against a throwaway probe table. It proves that the whole chain works end to end on this instance. It stops and restarts PostgreSQL, so it is not part of the routine read-only checks above:

sudo /usr/local/sbin/pgbackrest-selftest.sh

A manual point-in-time restore follows this shape: stop PostgreSQL, restore, then start it again.

sudo systemctl stop postgresql@18-main.service
sudo -u postgres pgbackrest --stanza=main --delta --type=immediate --target-action=promote restore
sudo systemctl start postgresql@18-main.service

--delta restores only the files that differ, which is much faster than a full copy. To recover to a specific point in time, use --type=time --target="YYYY-MM-DD HH:MM:SS+00" instead of --type=immediate. Always rehearse restores on a separate instance before you need them in an emergency.

PostgreSQL listens on loopback only, and the security group opens port 22 only, so the database is not reachable from the network. To connect a local client such as psql, a BI tool or an application, open an SSH tunnel from your workstation. The tunnel forwards a local port to 127.0.0.1:5432 on the instance:

ssh -i <key-name>.pem -L 5432:127.0.0.1:5432 ubuntu@<public-ip>

With the tunnel open, point your local client at 127.0.0.1:5432, database postgres, user postgres, and the password from the credentials file. This keeps all database traffic inside the encrypted SSH channel.

Do not open port 5432 to the internet without TLS in front of it.

The pgBackRest repository lives on a dedicated EBS volume mounted at /var/lib/pgbackrest. The repository itself is under /var/lib/pgbackrest/repo. Confirm the mount:

df -h /var/lib/pgbackrest

To grow the volume, expand the EBS volume in the AWS console. Then grow the filesystem on the instance with sudo resize2fs on the underlying device.

For an additional off-instance copy of your backups, snapshot the volume. Alternatively, use the S3 repository option below to store backups off the instance entirely.

The same appliance can back up a remote PostgreSQL server or store its repository in Amazon S3. Both are config-only changes in /etc/pgbackrest/pgbackrest.conf.

To store the repository in S3 instead of the local volume, replace the repo1-path line with an S3 block that names a bucket, region and endpoint. Provide credentials through an EC2 instance role or repo1-s3-key settings:

[global] repo1-type=s3 repo1-s3-bucket=your-backup-bucket repo1-s3-region=us-east-1 repo1-s3-endpoint=s3.us-east-1.amazonaws.com repo1-path=/pgbackrest repo1-cipher-type=aes-256-cbc repo1-cipher-pass=<your-passphrase>

To back up a remote PostgreSQL host, point the stanza's pg1-path, pg1-host and pg1-host-user at that server, and install pgBackRest there too. See the pgBackRest user guide for the full remote and S3 configuration.