Skip to main content
DCHost / Practical guide

Back up and restore an Ubuntu/Linux server with Proxmox Backup Client

An Ubuntu server running outside Proxmox VE can send backups directly to an existing Proxmox Backup Server. proxmox-backup-client runs on Ubuntu, reads the source data and uploads it to a PBS datastore. The source can be a physical server or a virtual machine on another platform.

In this guide, you will create an encrypted directory backup, restore it into a different directory, compare its contents and Linux permissions, and schedule daily runs with systemd. You will also restore a small test block device from .img, then back up the root filesystem and separate boot files and extract them into other directories.

Example environment: Ubuntu 24.04.5 LTS, x86-64, Linux 6.8.0-147-generic; official static client package 4.2.8-1 (version: 4.2.8); existing PBS 4.2.8-1. Directory and system-file restores, byte-for-byte image recovery and an automatic timer trigger were verified.

For this walkthrough, we used an isolated Ubuntu VM hosted on PVE and ran the standalone backup client inside Ubuntu. The same client can also back up compatible physical Linux servers and Linux VMs on other platforms.

Ubuntu Server · SSHCheck the Ubuntu client
Isolated Ubuntu client; actual SSH session.
Actual SSH terminal showing Ubuntu 24.04.5 LTS, x86_64 and available root filesystem space.
A closer look
Release and architecture — detail from the screenshot above

Step 1: Release and architecture

  1. Release and architecture

    This test client runs Ubuntu 24.04.5 LTS on x86_64.

  2. Inspect available space

    Read the Avail column in df; plan additional space for backup sources and the restore destination.

This screen shows client prerequisites only; no backup has run yet.

Which backup type covers your data?​

RequirementMethodCoverage
/etc, website files, user or application directoriesdata.pxar:/source/directoryFiles and supported Linux filesystem metadata
Operating system filesroot.pxar:/ plus other required filesystemsPartitioning and bootloader recovery require a separate plan
Contents of a block devicedisk.img:/dev/DEVICERaw bytes from the selected device; the source must be consistent
Running databaseEngine-supported backup first, then PBSCopying its live data directory alone is insufficient

Proxmox's regular client packages target Debian. Its official static client is provided for modern x86-64 Linux systems; this guide uses Ubuntu 24.04. We do not add a current Debian repository to Ubuntu. Do not assume native Windows, macOS or ARM support from this package.

1. Give this server limited access to PBS​

PBS must already have a datastore, and Ubuntu must be able to reach its HTTPS port, 8007. If you still need to set up PBS, complete the Proxmox Backup Server installation guide first.

In the PBS management interface:

  1. Create the ubuntu-client namespace inside the datastore you will use.
  2. Open Configuration → Access Control → User Management and add ubuntu-backup@pbs.
  3. Under API Tokens, create the ubuntu24 token for this user. Save the displayed token secret securely; the same value will not be displayed again.
  4. Under Permissions, assign DatastoreBackup on /datastore/DATASTORE/ubuntu-client to both the user ubuntu-backup@pbs and the token ubuntu-backup@pbs!ubuntu24. Replace DATASTORE with your existing datastore name.

A token's effective privileges are the intersection of its own permissions and its user's permissions. That is why both entries are needed. DatastoreBackup can create and restore its own backups; the source server does not need administrator or backup deletion privileges. A namespace groups data within a datastore; it does not create a separate physical disk or quota.

Proxmox Backup ServerCreate a namespace for Ubuntu
Actual administration screen in a PBS 4.2.8 lab.
PBS Create Namespace form with ubuntu-client beneath Root.
A closer look
Parent namespace — detail from the screenshot above

Step 1: Parent namespace

  1. Parent namespace

    Root selects the datastore root. This example groups Ubuntu backups in a separate namespace.

  2. Namespace name

    Namespace Name is ubuntu-client. Grant the user and token permissions on this exact namespace path.

Create has not yet been submitted; this screen shows the selected parent and name.

Proxmox Backup ServerPrepare the PBS backup user
Actual administration screen in a PBS 4.2.8 lab.
PBS Add User form with the ubuntu-backup user and Proxmox Backup authentication realm.
A closer look
Dedicated PBS user — detail from the screenshot above

Step 1: Dedicated PBS user

  1. Dedicated PBS user

    Enter ubuntu-backup in User name and select Proxmox Backup auth; the identity becomes ubuntu-backup@pbs.

  2. Keep the user enabled

    Keep Enabled selected. Do not publish password values; the client will use a separate API token.

The form has not yet been submitted with Add; saved permissions appear in the following screens.

Proxmox Backup ServerPrepare a dedicated API token
Actual administration screen in a PBS 4.2.8 lab.
PBS Add API token form for ubuntu-backup@pbs with token name ubuntu24.
A closer look
User and token name — detail from the screenshot above

Step 1: User and token name

  1. User and token name

    User is ubuntu-backup@pbs and Token Name is ubuntu24; the API identity becomes ubuntu-backup@pbs!ubuntu24.

No token secret exists in this preparation screen. Store the secret shown after creation in a private file.

Proxmox Backup ServerNamespace permission for the user
Actual administration screen in a PBS 4.2.8 lab.
PBS permission form with the user, ubuntu-client namespace path and DatastoreBackup role.
A closer look
Exact namespace path — detail from the screenshot above

Step 1: Exact namespace path

  1. Exact namespace path

    Path is /datastore/dchost-demo/ubuntu-client; avoid a broader grant on the datastore root.

  2. DatastoreBackup role

    The role is DatastoreBackup. Add a separate permission for the API token on the same namespace.

Add has not yet been submitted. Save the user and token permissions separately.

Proxmox Backup ServerNamespace permission for the API token
Actual administration screen in a PBS 4.2.8 lab.
PBS permission form with the API token, ubuntu-client namespace path and DatastoreBackup role.
A closer look
Exact namespace path — detail from the screenshot above

Step 1: Exact namespace path

  1. Exact namespace path

    Path is /datastore/dchost-demo/ubuntu-client; avoid a broader grant on the datastore root.

  2. DatastoreBackup role

    The role is DatastoreBackup. Token permissions are also limited by the linked user’s effective permissions.

Add has not yet been submitted. Save the user and token permissions separately.

Proxmox Backup ServerConfirm the two saved namespace grants
Actual saved permissions in a PBS 4.2.8 lab.
PBS permissions table with saved DatastoreBackup grants for the user and API token on the ubuntu-client namespace path.
A closer look
The same exact namespace path — detail from the screenshot above

Step 1: The same exact namespace path

  1. The same exact namespace path

    The last two rows use /datastore/dchost-demo/ubuntu-client, limiting this client’s grant to the selected namespace.

  2. Separate user and token rows

    Both ubuntu-backup@pbs and ubuntu-backup@pbs!ubuntu24 have a saved DatastoreBackup role.

Unrelated existing backup identities are masked; their permissions were not changed.

Obtain the PBS certificate fingerprint through your trusted PBS administration session. We will use it when connecting with a self-signed certificate. If PBS has a valid certificate issued by a CA trusted by the client, you can omit the PBS_FINGERPRINT setting.

2. Place the official static client on Ubuntu​

Check the architecture first:

uname -m
cat /etc/os-release

This example expects x86_64. Install the supporting tools from Ubuntu's own repositories:

sudo apt update
sudo apt install --no-install-recommends ca-certificates curl gpgv python3 acl

The guide's downloadable, readable helper script downloads the official 4.2.8-1 static client package. It verifies the published Proxmox key hash, repository signature and package hashes, then extracts the package into a working directory. It does not add an APT repository, install a Debian package or execute the downloaded program.

curl --fail --show-error --location \
--output fetch-pbs-client.py 'https://docs.dchost.com/downloads/pbc-fetch-client.py' &&
python3 fetch-pbs-client.py &&
sudo install -o root -g root -m 0755 \
pbs-client-4.2.8-1/extracted/usr/bin/proxmox-backup-client \
/usr/local/bin/proxmox-backup-client &&
/usr/local/bin/proxmox-backup-client version

Stop if a signature or hash check fails. The helper pins the version verified for this guide. A copied client is not updated automatically by APT; authenticate the official package again and repeat backup and restore checks when upgrading. The static client does not use custom libc/NSS name resolution modules; confirm that it resolves your PBS address in a connection test.

Ubuntu Server · SSHAuthenticate the official static client
Isolated Ubuntu client; actual SSH session.
Actual SSH terminal showing the official repository signature, verified static client and SHA-256 output.
A closer look
Authentication completed — detail from the screenshot above

Step 1: Authentication completed

  1. Authentication completed

    Verified official static client identifies the authenticated file. Verify the hash chain from signed repository metadata before running the binary.

This capture runs a prepared authentication helper; no package was installed at this stage. The visible release key and hash are public verification metadata.

Ubuntu Server · SSHCheck the client version
Isolated Ubuntu client; actual SSH session.
SSH terminal showing proxmox-backup-client version and the result client version 4.2.8.
A closer look
Working client — detail from the screenshot above

Step 1: Working client

  1. Working client

    The client version: 4.2.8 result shows that the installed client runs in this Ubuntu session.

The version command ran after the actual installation; this check does not yet prove PBS connectivity or a backup.

Step-by-step videoVerify and install the static client

In a real Ubuntu SSH session, the previously uploaded fetch-pbs-client.py helper verifies the official repository metadata signature and the hash chain leading to the static client. The extracted binary is installed with sudo install and reports version 4.2.8. Preparing the helper is outside this recording.

Client installation transcript​

00:00 — The prepared verification helper runs.

00:03 — The official static client is verified and extracted.

00:07 — The installed client reports version 4.2.8.

This real Ubuntu SSH session invokes the previously uploaded fetch-pbs-client.py helper; preparing that helper is outside the recording. Verification of the official repository metadata signature and hash chain is followed by extraction of the verified static client. The line saying that no packages or system configuration changed describes this first phase. The actual sudo install command then runs, and the version query returns client version: 4.2.8. This clip shows no backup or restore result.

cd ~; python3 fetch-pbs-client.py --output pbs-client-4.2.8-1
sudo install -m 0755 pbs-client-4.2.8-1/extracted/usr/bin/proxmox-backup-client /usr/local/bin/proxmox-backup-client
proxmox-backup-client version

3. Prepare connection and encryption credentials​

Run the remaining Ubuntu commands in a root shell. This permits ownership and permissions to be restored:

sudo -i
umask 077
install -d -m 0700 /etc/proxmox-backup

Edit /etc/proxmox-backup/client.env. Replace the server, datastore and fingerprint with your values; do not place the token secret in this file:

PBS_REPOSITORY='ubuntu-backup@pbs!ubuntu24@pbs.example.com:DATASTORE'
PBS_FINGERPRINT='VERIFIED_SHA256_FINGERPRINT_OF_THE_PBS_CERTIFICATE'

Save the token secret separately without displaying it:

systemd-ask-password 'PBS token secret:' > /etc/proxmox-backup/pbs-api-token
chmod 0600 /etc/proxmox-backup/client.env /etc/proxmox-backup/pbs-api-token
set -a
. /etc/proxmox-backup/client.env
set +a
export PBS_PASSWORD_FILE=/etc/proxmox-backup/pbs-api-token

Create the encryption key. Enter a new key passphrase at the first prompt, then enter the same passphrase in the second command:

proxmox-backup-client key create /etc/proxmox-backup/encryption-key.json
systemd-ask-password 'Backup key passphrase:' > /etc/proxmox-backup/pbs-key-password
chmod 0600 /etc/proxmox-backup/encryption-key.json /etc/proxmox-backup/pbs-key-password
export PBS_ENCRYPTION_PASSWORD_FILE=/etc/proxmox-backup/pbs-key-password

The PBS access token, backup encryption key and key passphrase are separate credentials. Keep an accessible recovery copy of the key and its passphrase in a secure location separate from the source server. If the only copy is inside the encrypted backup that needs that key, losing the source server can also make the backup inaccessible. Do not record token or passphrase entry.

Ubuntu Server · SSHCheck credential-file permissions
Actual SSH session on the isolated Ubuntu client.
SSH terminal showing directory mode 700, mode 600 on four configuration/key files and root:root ownership.
A closer look
Directory 700, files 600 — detail from the screenshot above

Step 1: Directory 700, files 600

  1. Directory 700, files 600

    /etc/proxmox-backup is mode 700; its environment, token, encrypted key and key-password files show mode 600 and root:root ownership.

stat shows only filenames, modes and ownership; token, password and key contents were not opened.

4. Back up a directory and restore it elsewhere​

This example uses /srv/pbs-demo. Create a test file; this example also grants a read ACL to UID 1000. For real use, select the source directory and ACL user for your environment:

set -euo pipefail
install -d -m 0750 /srv/pbs-demo
printf 'PBS file restore test\n' > /srv/pbs-demo/restore-check.txt
chmod 0640 /srv/pbs-demo/restore-check.txt
setfacl -m u:1000:r-- /srv/pbs-demo/restore-check.txt
proxmox-backup-client backup data.pxar:/srv/pbs-demo \
--backup-type host --backup-id ubuntu24-lab --ns ubuntu-client \
--keyfile /etc/proxmox-backup/encryption-key.json
proxmox-backup-client snapshot list --ns ubuntu-client

In the datastore's Content view on PBS, select the ubuntu-client namespace. Check the host/ubuntu24-lab group, completed task and encrypted data.pxar archive. Use the same identity, namespace and source archive plan for subsequent backups of that group.

Ubuntu Server · SSHResult of the first encrypted directory backup
Actual SSH session on the isolated Ubuntu client.
SSH terminal showing upload, catalog, duration and end-time output for the data.pxar backup.
A closer look
Command completed — detail from the screenshot above

Step 1: Command completed

  1. Command completed

    The catalog uploaded, Duration and End Time were printed, and the shell prompt returned. Inspect the actual snapshot and archive next.

The encryption-key fingerprint is permanently masked. Timing for this tiny test directory is not a production-performance benchmark.

The file-backup video shows an actual repeated run using the same test data. It reported 0 B of new archive data and 304 B reused; these values are not a measurement of total network traffic.

Proxmox Backup ServerInspect the encrypted archive in PBS
Actual snapshot content in the PBS 4.2.8 lab.
Actual snapshot, data.pxar.didx archive index and Encrypted status in the PBS ubuntu-client namespace.
A closer look
Snapshot and archive — detail from the screenshot above

Step 1: Snapshot and archive

  1. Snapshot and archive

    The expanded snapshot contains data.pxar.didx. The client restore command uses data.pxar as the archive name.

  2. Encrypted and Signed

    The data/catalog archives show Encrypted, while index.json.blob shows Signed. Store the encryption key separately and securely.

Verify State is still None. Encrypted storage alone does not show that verification or a restore test passed.

Ubuntu Server · SSHSee data reuse on a repeated backup
Actual SSH session on the isolated Ubuntu client.
SSH terminal showing the previous manifest download and 0 B of 304 B newly backed up for data.pxar.
A closer look
0 B new data, completed command — detail from the screenshot above

Step 1: 0 B new data, completed command

  1. 0 B new data, completed command

    The data.pxar row shows 0 B newly sent for 304 B of content. Catalog, duration and end-time output are followed by the shell prompt.

This is not the first backup. The real repeated run reuses data from the unchanged tiny test directory. The encryption fingerprint is masked.

Step-by-step videoRepeat the same directory backup

In a real Ubuntu SSH session, the same sample directory is backed up again as an encrypted data.pxar archive. The client uses the previous manifest, reuses the unchanged 304 B and reports 0 B of new file data. This is a repeated backup; it shows no restore.

Repeated directory backup transcript​

00:00 — The same directory is backed up again.

00:02 — 304 B reused; new data: 0 B.

The recording begins in a cleared, real Ubuntu SSH terminal. The command below repeats an encrypted backup of the sample /srv/pbs-demo directory as data.pxar in the ubuntu-client namespace. Playback is at real speed: this tiny sample finishes in about 0.46 seconds, with the result held for about five seconds. Downloading previous manifest shows that the client uses the earlier backup. The result data.pxar: had to backup 0 B of 304 B means that the unchanged 304 B of file data is reused. Uploaded backup catalog (62 B), the duration, end time and returned shell prompt are also visible; 0 B does not mean zero network traffic. This clip proves neither the first backup nor a restore. The key fingerprint is masked; the key file contents are never displayed.

proxmox-backup-client backup data.pxar:/srv/pbs-demo \
--backup-type host --backup-id ubuntu24-lab --ns ubuntu-client \
--keyfile /etc/proxmox-backup/encryption-key.json
Ubuntu Server · SSHRead the snapshot list in the namespace
Actual SSH session on the isolated Ubuntu client.
SSH terminal showing the snapshot list and data.pxar archive in the ubuntu-client namespace.
A closer look
The data.pxar archive — detail from the screenshot above

Step 1: The data.pxar archive

  1. The data.pxar archive

    The files column shows catalog.pcat1, data.pxar and index.json. Use data.pxar as the archive name when restoring.

  2. Complete snapshot identity

    Use the full snapshot identity beginning with host/ubuntu24-lab and keep the namespace option in the command.

The list shows that a backup exists; restoration is tested in the next step.

Copy the real snapshot path from the list. Replace the date in this example with your output. Choose a different, unused destination directory:

SNAPSHOT='host/ubuntu24-lab/2026-10-31T00:06:40Z'
proxmox-backup-client restore "$SNAPSHOT" data.pxar /srv/pbs-restore-check \
--ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json
cmp /srv/pbs-demo/restore-check.txt /srv/pbs-restore-check/restore-check.txt
stat -c '%u:%g %a %n' \
/srv/pbs-demo/restore-check.txt /srv/pbs-restore-check/restore-check.txt

cmp prints nothing when it succeeds. Both files should have the same numeric user/group and mode. If you use ACLs, install Ubuntu's acl package and compare getfacl -cp FILE output for the source and destination too. In the example, source and restored file SHA-256 hashes matched; UID:GID 0:0, mode 0640 and the r-- ACL entry for UID 1000 were preserved.

Ubuntu Server · SSHRestore to a separate directory and verify the file
Actual SSH session on the isolated Ubuntu client.
SSH terminal showing the separate restore destination, File contents match, ownership 0:0, mode 640 and source/destination POSIX ACL lists.
A closer look
Contents and metadata match — detail from the screenshot above

Step 1: Contents and metadata match

  1. Contents and metadata match

    cmp is followed by File contents match. Both files show 0:0 / 640; both ACL outputs have the same entries, including user:1000:r--.

This test verifies file contents and the displayed metadata; it does not prove boot, whole-machine or live-database recovery. The encryption fingerprint is masked.

Step-by-step videoRestore files into a separate directory

In a real Ubuntu SSH session, data.pxar is restored into a separate directory. File contents, numeric ownership, mode 640 and POSIX ACL output are compared. The final ACL result is visible briefly at the end; pause or read the transcript.

File restore transcript​

00:00 — Restore into a separate directory.

00:02 — Compare contents and permissions.

The first approximately 0.15 seconds retain the preceding successful backup and snapshot listing; the terminal then clears. The selected data.pxar archive is restored into /srv/pbs-restore-check, separate from the source /srv/pbs-demo directory. The client reports restore complete. cmp succeeds and prints File contents match. Both files report numeric owner/group 0:0 and mode 640. The two getfacl -ncp outputs contain the same ACL entries: user::rw-, user:1000:r--, group::r--, mask::r--, other::---. The restored file’s final ACL output appears only in the last approximately 0.2 seconds; pause the recording to inspect it. The encryption-key fingerprint is permanently masked. This proves recovery of the sample file contents and shown permission metadata; it is not an application, database or bootable system recovery test.

SNAPSHOT='host/ubuntu24-lab/2026-10-31T00:06:40Z'
proxmox-backup-client restore "$SNAPSHOT" data.pxar /srv/pbs-restore-check \
--ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json
cmp /srv/pbs-demo/restore-check.txt /srv/pbs-restore-check/restore-check.txt && printf 'File contents match\n'
stat -c '%u:%g %a %n' /srv/pbs-demo/restore-check.txt /srv/pbs-restore-check/restore-check.txt
getfacl -ncp /srv/pbs-demo/restore-check.txt
getfacl -ncp /srv/pbs-restore-check/restore-check.txt

5. Schedule daily backups with systemd​

Scheduling runs on Ubuntu. Create /etc/systemd/system/pbs-client-backup.service:

[Unit]
Description=Back up Ubuntu files to Proxmox Backup Server
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
User=root
EnvironmentFile=/etc/proxmox-backup/client.env
LoadCredential=pbs-api-token:/etc/proxmox-backup/pbs-api-token
LoadCredential=pbs-key-password:/etc/proxmox-backup/pbs-key-password
Environment=PBS_PASSWORD_FILE=%d/pbs-api-token
Environment=PBS_ENCRYPTION_PASSWORD_FILE=%d/pbs-key-password
ExecStart=/usr/local/bin/proxmox-backup-client backup data.pxar:/srv/pbs-demo --backup-type host --backup-id ubuntu24-lab --ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json

Create /etc/systemd/system/pbs-client-backup.timer:

[Unit]
Description=Daily Proxmox Backup Client backup

[Timer]
OnCalendar=*-*-* 02:30:00
RandomizedDelaySec=15m
Persistent=true
Unit=pbs-client-backup.service

[Install]
WantedBy=timers.target

Run the service manually and check its result before enabling the timer:

systemd-analyze verify /etc/systemd/system/pbs-client-backup.service /etc/systemd/system/pbs-client-backup.timer
systemctl daemon-reload
systemctl start pbs-client-backup.service
systemctl show pbs-client-backup.service --property=Result --property=ExecMainStatus
journalctl -u pbs-client-backup.service --no-pager -n 30
systemctl enable --now pbs-client-backup.timer
timedatectl
systemctl list-timers --all pbs-client-backup.timer

A successful first run should report Result=success and ExecMainStatus=0; PBS should also show a new snapshot. A finished oneshot service normally becomes inactive (dead). The timer runs around 02:30 in the server's local timezone, with up to 15 minutes of randomized delay plus systemd's scheduling tolerance; read the actual next trigger in the NEXT column. The timer does not restart the same service while it is still active. Persistent=true can catch a missed calendar run when the timer becomes active again; this example does not configure automatic failure notifications or retries.

The lab's actual automatic trigger completed at 03:10:14 on 31 October 2026 (Europe/Istanbul), using a temporary OnActiveSec=35s test setting. It reported success with exit code 0. The temporary setting was removed, leaving the daily 02:30 schedule and 15-minute randomized delay shown above enabled.

Ubuntu Server · SSHInspect the backup service
Actual SSH session on the isolated Ubuntu client.
Actual systemd oneshot service with LoadCredential, an environment file and the data.pxar backup command.
A closer look
Load credentials from files — detail from the screenshot above

Step 1: Load credentials from files

  1. Load credentials from files

    The two LoadCredential entries bind the API token and key password to systemd credentials. Type=oneshot and ExecStart are visible in the same actual service definition.

This service backs up /srv/pbs-demo files. LoadCredential shows file paths; secret values are not displayed.

Ubuntu Server · SSHCheck the final daily timer
Actual SSH session on the isolated Ubuntu client.
systemd output showing OnCalendar 02:30, a 15-minute randomized delay, Persistent=true and the next run.
A closer look
02:30 with up to 15 minutes of delay — detail from the screenshot above

Step 1: 02:30 with up to 15 minutes of delay

  1. 02:30 with up to 15 minutes of delay

    OnCalendar is saved as daily 02:30. RandomizedDelaySec=15m and Persistent=true are visible in the same definition.

  2. The actual next trigger time

    NEXT in list-timers shows 1 November 2026 at 02:35:46 +03, the next run calculated from the daily calendar and randomized delay.

The visible LAST value comes from the earlier short test timer. The first nightly run of this final daily schedule has not yet been observed.

Ubuntu Server · SSHRead the automatic test-trigger result
Actual SSH session on the isolated Ubuntu client.
LastTriggerUSec and journal output from the actual successful backup service started by the short test timer.
A closer look
The service finished — detail from the screenshot above

Step 1: The service finished

  1. The service finished

    The journal shows the service deactivated successfully and the Finished line. LastTriggerUSec records the 31 October 03:10:14 +03 trigger.

This result belongs to the temporary 35-second test timer. The daily 02:30 calendar was restored afterward; this screen does not prove its first nightly run.

6. Back up a block device as .img​

This section uses only a newly created 64 MiB test image. Never pass a production or root disk to the mkfs command. Run these commands in the same root Bash session. set -euo pipefail prevents a file write after a failed mount. Prepare the test file and loop device:

set -euo pipefail
PBS_IMAGE_WORK=$(mktemp -d /var/tmp/pbs-image-demo.XXXXXX)
truncate -s 64M "${PBS_IMAGE_WORK:?}/source.img"
mkfs.ext4 -F "${PBS_IMAGE_WORK:?}/source.img"
PBS_DEMO_LOOP=$(losetup --find --show "${PBS_IMAGE_WORK:?}/source.img")
install -d "${PBS_IMAGE_WORK:?}/source-mount"
mount "${PBS_DEMO_LOOP:?}" "${PBS_IMAGE_WORK:?}/source-mount"
printf 'PBS block image test\n' > "${PBS_IMAGE_WORK:?}/source-mount/image-check.txt"
umount "${PBS_IMAGE_WORK:?}/source-mount"
if findmnt -rn -S "$PBS_DEMO_LOOP"; then
printf 'ERROR: test device is still mounted.\n' >&2
exit 1
fi

The final check stops the procedure if the device is still mounted. Keep this device free of writes throughout the backup. A .img operation does not create a snapshot or stop applications.

sha256sum "$PBS_DEMO_LOOP"
proxmox-backup-client backup demo.img:"$PBS_DEMO_LOOP" \
--backup-type host --backup-id ubuntu24-lab-image --ns ubuntu-client \
--keyfile /etc/proxmox-backup/encryption-key.json
proxmox-backup-client snapshot list --ns ubuntu-client

We use ubuntu24-lab-image as a separate group from the scheduled directory job. Select its snapshot and restore the image to a new regular file:

IMAGE_SNAPSHOT='host/ubuntu24-lab-image/2026-10-31T00:12:04Z'
proxmox-backup-client restore "$IMAGE_SNAPSHOT" demo.img "${PBS_IMAGE_WORK:?}/restored.img" \
--ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json
sha256sum "$PBS_DEMO_LOOP" "${PBS_IMAGE_WORK:?}/restored.img"
cmp "$PBS_DEMO_LOOP" "${PBS_IMAGE_WORK:?}/restored.img"

The two SHA256 hashes must match. In the lab, the SHA-256 hashes of the 64 MiB source device and restored image matched; cmp also verified every byte. To check the file inside, mount the restored ext4 image read-only with journal replay disabled:

install -d "${PBS_IMAGE_WORK:?}/restore-mount"
mount -o loop,ro,noload "${PBS_IMAGE_WORK:?}/restored.img" "${PBS_IMAGE_WORK:?}/restore-mount"
cat "${PBS_IMAGE_WORK:?}/restore-mount/image-check.txt"
umount "${PBS_IMAGE_WORK:?}/restore-mount"
losetup -d "$PBS_DEMO_LOOP"

This proves that the selected block device's bytes were recovered. It does not prove that an operating system boots or that a live database recovers. An image of one partition or LVM logical volume does not include the disk's other partitions or its complete disk layout.

Ubuntu Server · SSHConfirm the 64 MiB image is unmounted
Actual SSH session on the isolated Ubuntu client.
blockdev returns 67108864 bytes; the findmnt check reports Source is unmounted.
A closer look
The source is unmounted — detail from the screenshot above

Step 1: The source is unmounted

  1. The source is unmounted

    The visible check reports Source is unmounted. The 67108864-byte value above confirms the 64 MiB size.

This example uses a 64 MiB loop device. It is not an operating-system disk or a boot-recovery test.

Ubuntu Server · SSHRead the repeated image-backup result
Actual SSH session on the isolated Ubuntu client.
Actual demo.img backup output reports reuse of all 64 MiB and completion.
A closer look
64 MiB was reused — detail from the screenshot above

Step 1: 64 MiB was reused

  1. 64 MiB was reused

    The demo.img line reports reused 64 MiB (100.0%). The output also records 0 B transferred and completion in 0.95 seconds.

This is not the first image backup. The actual repeat run shows reuse of the unchanged 64 MiB contents.

Ubuntu Server · SSHRead a file from the restored image
Actual SSH session on the isolated Ubuntu client.
After matching SHA-256 values, the restored image is mounted with ro,noload and its PBS block image test text is read.
A closer look
The test file inside the image was read — detail from the screenshot above

Step 1: The test file inside the image was read

  1. The test file inside the image was read

    cat reads PBS block image test from the restored image. The preceding mount command visibly uses loop,ro,noload.

The image was mounted read-only. This file read and byte comparison are not an operating-system boot test.

Ubuntu Server · SSHCompare the source and restored image
Actual SSH session on the isolated Ubuntu client.
source.img and restored.img have the same SHA-256 value; cmp finishes with Image bytes match.
A closer look
The image bytes match — detail from the screenshot above

Step 1: The image bytes match

  1. The image bytes match

    Image bytes match after cmp confirms byte equality. The same SHA-256 value is visible above for source.img and restored.img.

This independent check compares the two regular image files. Equality applies to the bytes of the 64 MiB example.

Step-by-step videoBack up and restore a 64 MiB test image

In a real Ubuntu SSH session, the image backup of an unmounted 64 MiB test block device is repeated; demo.img is restored to a separate file. The source and restored image have matching SHA-256 values, and the marker file is read from a read-only mount. This test does not demonstrate OS boot or whole-machine recovery.

Test image backup and restore transcript​

00:00 — 64 MiB test image; source is unmounted.

00:04 — 64 MiB reused; new image data: 0 B.

00:09 — The image is restored to a separate file.

00:12 — The SHA-256 values are compared.

00:15 — Read-only mount; the marker file is read.

The recording runs continuously at real speed. Its first approximately 0.135 seconds retain the previous successful preparation and first image-backup output, followed by an actual terminal clear. blockdev --getsize64 reports 67108864 bytes (64 MiB); the findmnt check returns Source is unmounted. The backup executed in this clip is a repeat: the client downloads the previous manifest, reuses all 64 MiB and reports 0 B of new image data. Backup duration is 0.95 seconds. restore complete confirms that 64 MiB was restored to the separate restored.img file.

After a second actual clear, the source loop device and restored file show the same SHA-256 value. The restored image is mounted read-only with loop,ro,noload; image-check.txt is read as PBS block image test. The mount is then removed and the source loop device detached. cmp is not run in this clip; it appears in the separate clean checksum screenshot. Key fingerprints are covered by opaque masks; key-file contents are never displayed. These commands belong to this prepared, unmounted test device; they do not prove a consistent image of a running root disk, bootability or whole-machine recovery.

blockdev --getsize64 "$PBS_DEMO_LOOP"
if findmnt -rn -S "$PBS_DEMO_LOOP"; then
echo "STOP: device is mounted"
else
echo "Source is unmounted"
fi
proxmox-backup-client backup demo.img:"$PBS_DEMO_LOOP" \
--backup-type host --backup-id ubuntu24-lab-image --ns ubuntu-client \
--keyfile /etc/proxmox-backup/encryption-key.json
IMAGE_SNAPSHOT='host/ubuntu24-lab-image/2026-10-31T00:12:04Z'
proxmox-backup-client restore "$IMAGE_SNAPSHOT" demo.img "${PBS_IMAGE_WORK:?}/restored.img" \
--ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json
sha256sum "$PBS_DEMO_LOOP" "${PBS_IMAGE_WORK:?}/restored.img"
install -d "${PBS_IMAGE_WORK:?}/restore-mount"
mount -o loop,ro,noload "${PBS_IMAGE_WORK:?}/restored.img" "${PBS_IMAGE_WORK:?}/restore-mount"
cat "${PBS_IMAGE_WORK:?}/restore-mount/image-check.txt"
umount "${PBS_IMAGE_WORK:?}/restore-mount" && losetup -d "$PBS_DEMO_LOOP"

7. Back up operating system files and restore them elsewhere​

This example backs up selected files from the root filesystem as root.pxar. It also creates separate archives for /boot and /boot/efi if they are separate mounts. Recovery goes into a new directory under /var/tmp, leaving the running operating system in place. Files on the live root filesystem can change while being read; this operation does not create a coordinated application snapshot.

Check the disk layout and space available for the restore:

findmnt -R /
lsblk -f
df -h /var/tmp

root.pxar:/ skips mountpoints on other devices by default. Plan separate coverage if /home, /var or application data uses another filesystem. Extracted files consume space on Ubuntu; compression and deduplication on PBS do not remove that local space requirement.

Ubuntu Server · SSHCheck filesystems and working space
Actual SSH session on the isolated Ubuntu client.
Terminal showing the actual root ext4, /boot ext4 and /boot/efi vfat mounts and 4.7G of available space.
A closer look
Available space for the restore — detail from the screenshot above

Step 1: Available space for the restore

  1. Available space for the restore

    df reports 4.7G available for /var/tmp. The findmnt result above lists the root, /boot and /boot/efi filesystems separately.

The separate mounts prevent assuming that one root-directory archive automatically contains all these files. This capacity belongs only to the shown lab.

The exclusions below belong to this example environment. Temporary files, caches, logs, swap files and the restore staging area are left out. /etc/proxmox-backup and the root user's client configuration/cache directories are excluded too; do not expect to recover the token or encryption key from this archive. They require their own recovery copy. The earlier file restore destination /srv/pbs-restore-check and this lab's client download directory /home/demo/pbs-client-4.2.8-1 are also excluded; use the actual paths for your environment.

For root.pxar:/, --exclude=/etc/proxmox-backup excludes that directory and its descendants; no trailing /** is needed. The leading / anchors a pattern to the archive root. Existing .pxarexclude files can change selection, so inspect existing rules first:

find / -xdev -name .pxarexclude -print

No additional rule files are expected in this clean Ubuntu example. If any appear, review their interaction with your exclusions before proceeding. Run these commands in the same root Bash session; set -euo pipefail prevents later steps from continuing after a failed command:

set -euo pipefail
PBS_SYSTEM_ARCHIVES=(root.pxar:/)
if mountpoint -q /boot; then
PBS_SYSTEM_ARCHIVES+=(boot.pxar:/boot)
fi
if mountpoint -q /boot/efi; then
PBS_SYSTEM_ARCHIVES+=(efi.pxar:/boot/efi)
fi
proxmox-backup-client backup "${PBS_SYSTEM_ARCHIVES[@]}" \
--backup-type host --backup-id ubuntu24-lab-system --ns ubuntu-client \
--keyfile /etc/proxmox-backup/encryption-key.json \
--exclude=/proc --exclude=/sys --exclude=/dev --exclude=/run \
--exclude=/tmp --exclude=/var/tmp --exclude=/mnt --exclude=/media \
--exclude=/swap.img --exclude=/swapfile --exclude=/lost+found \
--exclude=/etc/proxmox-backup --exclude=/root/.config/proxmox-backup \
--exclude=/root/.cache --exclude=/var/cache/apt/archives --exclude=/var/log \
--exclude=/srv/pbs-restore-check --exclude=/home/demo/pbs-client-4.2.8-1
proxmox-backup-client snapshot list --ns ubuntu-client
Ubuntu Server · SSHThe selected system-file backup completed
Actual SSH session on the isolated Ubuntu client.
The actual script backs up root, boot and efi archives; System-files backup completed appears after 48.55 seconds.
A closer look
The three-archive operation completed — detail from the screenshot above

Step 1: The three-archive operation completed

  1. The three-archive operation completed

    System-files backup completed follows the root.pxar, boot.pxar and efi.pxar operations. The same result records Duration: 48.55s.

These are three file archives. This does not prove running-application consistency, a whole-machine image or bootable recovery.

Step-by-step videoBack up root, boot and EFI files

In the real Ubuntu session, the prepared script backs up /, /boot and /boot/efi into separate root.pxar, boot.pxar and efi.pxar archives. The first selected system-file backup completes in 48.55 seconds and lists all three encrypted archives. The recording runs at real speed; it does not establish application consistency or whole-machine recovery.

System-file backup transcript​

00:00 — Check separate filesystems and available space.

00:04 — The prepared script backs up three archives.

00:10 — Root files are uploading. Playback is at real speed.

00:49 — Boot and EFI files upload to separate archives.

00:53 — System-file backup completed in 48.55 s.

00:57 — The three encrypted archives are listed.

The initial terminal briefly retains the preceding block-image test output, followed by the real clear command. findmnt shows ext4 for / and /boot, and vfat for /boot/efi. After checking space in /var/tmp, the previously prepared bash /var/tmp/pbc-system-backup.sh script runs; writing that script is outside the recording. It backs up / as root.pxar, separate /boot as boot.pxar, and separate /boot/efi as efi.pxar. The root archive skips the separate boot mount; the boot archive skips the separate EFI mount. This first selected system backup has no previous manifest, although existing chunks supply 1.5% of the root data. The output reports 48.55 seconds and completion. Then proxmox-backup-client snapshot files "$SYSTEM_SNAPSHOT" --ns ubuntu-client lists all three archives in encrypt mode. A permanent opaque mask hides the encryption-key fingerprint. This is a system-file backup; it does not establish point-in-time consistency of running applications or recovery of a bootable whole machine.

This job writes to ubuntu24-lab-system, separately from the directory timer. Copy the completed snapshot path from the list and inspect which archives were created:

PBS_SYSTEM_SNAPSHOT='host/ubuntu24-lab-system/2026-10-31T00:13:03Z'
proxmox-backup-client snapshot files "$PBS_SYSTEM_SNAPSHOT" --ns ubuntu-client
PBS_SYSTEM_RESTORE=$(mktemp -d /var/tmp/pbs-system-restore.XXXXXX)
proxmox-backup-client restore "$PBS_SYSTEM_SNAPSHOT" root.pxar \
"${PBS_SYSTEM_RESTORE:?}/root" \
--ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json
Ubuntu Server · SSHList the three system archives
Actual SSH session on the isolated Ubuntu client.
snapshot files output shows encrypt for boot.pxar.didx, efi.pxar.didx and root.pxar.didx.
A closer look
All three data archives are encrypted — detail from the screenshot above

Step 1: All three data archives are encrypted

  1. All three data archives are encrypted

    boot.pxar.didx, efi.pxar.didx and root.pxar.didx each show encrypt. index.json.blob separately shows sign-only.

The list shows archive presence and encryption mode. Restore evidence comes from the separate operation that follows.

If the snapshot contains boot.pxar or efi.pxar, run only the following commands for archives that actually exist. They also restore into separate test directories:

proxmox-backup-client restore "$PBS_SYSTEM_SNAPSHOT" boot.pxar \
"${PBS_SYSTEM_RESTORE:?}/boot" \
--ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json
proxmox-backup-client restore "$PBS_SYSTEM_SNAPSHOT" efi.pxar \
"${PBS_SYSTEM_RESTORE:?}/efi" \
--ns ubuntu-client --keyfile /etc/proxmox-backup/encryption-key.json

Compare system files and the test file created earlier. If source files changed after the backup, compare against hashes recorded before backup instead:

cmp /usr/lib/os-release "${PBS_SYSTEM_RESTORE:?}/root/usr/lib/os-release"
cmp /etc/fstab "${PBS_SYSTEM_RESTORE:?}/root/etc/fstab"
cmp /srv/pbs-demo/restore-check.txt \
"${PBS_SYSTEM_RESTORE:?}/root/srv/pbs-demo/restore-check.txt"
stat -c '%u:%g %a %n' /srv/pbs-demo/restore-check.txt \
"${PBS_SYSTEM_RESTORE:?}/root/srv/pbs-demo/restore-check.txt"
getfacl -ncp /srv/pbs-demo/restore-check.txt > "${PBS_SYSTEM_RESTORE:?}/source.acl"
getfacl -ncp "${PBS_SYSTEM_RESTORE:?}/root/srv/pbs-demo/restore-check.txt" \
> "${PBS_SYSTEM_RESTORE:?}/restored.acl"
cmp "${PBS_SYSTEM_RESTORE:?}/source.acl" "${PBS_SYSTEM_RESTORE:?}/restored.acl"
for PBS_EXCLUDED_PATH in etc/proxmox-backup root/.config/proxmox-backup root/.cache var/tmp srv/pbs-restore-check home/demo/pbs-client-4.2.8-1; do
test ! -e "${PBS_SYSTEM_RESTORE:?}/root/$PBS_EXCLUDED_PATH"
test ! -L "${PBS_SYSTEM_RESTORE:?}/root/$PBS_EXCLUDED_PATH"
done
printf 'System files match; PBS credentials and staging paths are absent.\n'

The lab used ext4 /dev/sda1 for /, ext4 /dev/sda16 for /boot, and vfat /dev/sda15 for /boot/efi. root.pxar, boot.pxar and efi.pxar were extracted into new directories, using approximately 2 GiB. System/test files, ownership, mode and ACL matched; the vmlinuz kernel file and BOOTX64.EFI also passed byte comparisons. Credential, temporary, previous-restore and client-download directories were confirmed absent. The restore did not replace the running root filesystem.

Ubuntu Server · SSHRestore system files to a separate directory
Actual SSH session on the isolated Ubuntu client.
Actual root, boot and efi restores show file and metadata equality, exclusions, and matching kernel/EFI files.
A closer look
The kernel and EFI files match — detail from the screenshot above

Step 1: The kernel and EFI files match

  1. The kernel and EFI files match

    The final check reports matching kernel and EFI boot-file contents. Above it, the output confirms system-file and metadata equality and exclusion of credential and staging paths.

Files were restored into a new directory. Partitioning, bootloader installation and machine boot were not tested.

Step-by-step videoRestore three system-file archives to a separate directory

In the real Ubuntu session, the prepared script restores the root, boot and EFI archives into a fresh directory under /var/tmp. File content, ownership/mode, exclusion and kernel/EFI file comparisons pass. The recording runs at real speed; it shows no repartitioning, bootloader installation or boot test.

System-file restore transcript​

00:00 — The prepared restore script runs.

00:06 — Root files are restoring. Playback is at real speed.

00:32 — Root file and permission checks pass.

00:34 — Boot and EFI files are also restored.

00:35 — File comparisons pass. No boot test is performed.

The preceding system-backup archive listing remains briefly at the start, followed by the real clear command. The previously prepared bash /var/tmp/pbc-system-restore.sh script runs; writing it is outside the recording. It restores the root, boot and EFI archives into separate targets under the fresh /var/tmp/pbs-system-restore.x0Cil7 directory. Root files complete in 30.8 seconds. Source and restored check files both show owner/group 0:0 and mode 640; the script confirms file/metadata equality and absence of PBS credentials and staging paths. Boot and EFI restores also finish, followed by passing kernel and EFI file-content comparisons. The output shows about 2.0G of restored data and remaining space. Permanent opaque masks hide encryption-key fingerprints. This proves system-file restoration into a separate directory. It does not recreate partitions, install a bootloader or test booting the restored operating system.

What this recovery proves​

The tested operation here restores selected operating system files and required separate boot archives into other directories. A new disk can still require partition/LVM/encryption setup, UUID and /etc/fstab alignment, initramfs, GRUB/UEFI and network configuration. Full-machine recovery is complete only after preparing that layout on the new target and checking that the machine boots and its applications work. This guide does not claim that boot test.

Databases, retention and recurring checks​

Proxmox Backup Client does not automatically stop a database or create a consistent snapshot while reading files. Copying a running PostgreSQL/MySQL/MariaDB data directory can produce an unusable database backup even when the PBS task succeeds. First produce consistent output using the engine's supported logical/physical backup or coordinated snapshot method, send the completed output to PBS, and restore it into a separate database. Plan WAL/binlog retention and point-in-time recovery separately when production requirements call for them.

On PBS, manage retention, prune, garbage collection and verification jobs that cover this namespace. A keep-daily policy selects recovery points by day; it does not retain every snapshot taken on the same day. Before restoring, list the snapshots again and choose one that is still available. The source token does not need additional deletion privileges. During recurring restore tests, check file contents, ownership/permissions, access to the encryption key and application behavior. For 403 errors, check both user and token namespace permissions. For missing snapshots, check the namespace and complete snapshot path. For ownership errors, check which identity originally created the group.

In the PBS datastore's Content tab, select the ubuntu-client namespace and use Verify All to verify that scope. In this lab, the task checked seven snapshots across three backup groups and finished with TASK OK and no errors. The final view showed all three groups as encrypted and All OK. This server-side check verifies stored backup integrity; the actual restores above separately verified that the encryption key could be used and the files could be recovered.

Proxmox Backup Server 4.2.8Scope PBS verification to the namespace
Actual web interface of the separate PBS lab.
Actual PBS Verify dialog with the ubuntu-client namespace and Verify button.
A closer look
The ubuntu-client namespace is selected — detail from the screenshot above

Step 1: The ubuntu-client namespace is selected

  1. The ubuntu-client namespace is selected

    The Verify dialog is scoped to the ubuntu-client namespace. This view shows the selection before verification starts.

  2. Start verification

    Verify starts the server-side integrity check of stored backups. Check completion in the separate task output.

This ready dialog is not completion evidence. Server verification does not replace a plaintext file-restore test.

Proxmox Backup Server 4.2.8Read the completed PBS verification task
Actual task output of the separate PBS lab, scrolled to the end of the log.
End of the actual PBS task log showing 0 errors results, 100.00% (3/3 groups) and TASK OK.
A closer look
3/3 groups and TASK OK — detail from the screenshot above

Step 1: 3/3 groups and TASK OK

  1. 3/3 groups and TASK OK

    The final lines show 100.00% (3/3 groups) and TASK OK. The visible final root, boot and efi archive checks report 0 errors.

This is the server-side integrity check of stored backups. Plaintext restores and file comparisons were tested in separate operations.

Proxmox Backup Server 4.2.8Check verification status on all three groups
Actual Content view of the separate PBS lab.
Three backup groups in the ubuntu-client namespace show Encrypted and All OK, with snapshot counts 4, 2 and 1.
A closer look
All OK on all three groups — detail from the screenshot above

Step 1: All OK on all three groups

  1. All OK on all three groups

    The file, image and system-file groups show Encrypted and All OK. Their counts are 4, 2 and 1, for seven snapshots in total.

All OK is the server-side verification status of stored backups. File and image restores were tested separately.

Official references​