Upgrading Proxmox Backup Server 3 to version 4

In August 2025, with the release of Debian Trixie (13), Proxmox Backup Server (PBS) moves up to its fourth major version.

Just like with Proxmox VE (article on j.hommet.net ), a dedicated command (pbs3to4) lets you prepare the upgrade of your PBS. Before updating your machine, it’s important to follow a few best practices. As always, here is my procedure:

• Back up the data and prepare the PBS server
• Read the changelogs
• Update version N-1 (PBS 3)
• Update to version N (PBS 4)
• Functional testing

If possible, run a test upgrade on a dedicated machine that is non-critical and disposable. Also, perform the following steps with the root account rather than an account that has sudo rights. The root user has full control over the entire system, which is necessary for this kind of operation.

Back up the data and prepare the PBS server#

Backing up the data of a backup server is a concept that will always make me smile. It’s also not the simplest thing to do, given the amount of data and all the constraints that come with it.

With PBS 3, you can replicate the backup server’s data to another PBS. This procedure is easy to set up and is recommended (if you can afford it).

Don’t forget to document the procedure and to keep a log of the restore tests you carry out, recording both the successes and the failures, along with a detailed description (especially for the failures, which will give you a technical edge if the problem comes back or if you need to share your experience).

Also, on a Proxmox Backup Server, it’s useful to back up the files in the “/etc/pbs/” folder. Inside you’ll find the public/private keys, the certificates, the local user accounts, and so on, using the command tar -czvf "/etc/pbs/pbs_backup_$(date +'%Y%m%d').tar.gz" /etc/pbs.

In addition, take the time to check your machines’ backups. In the datastore, select “content”, browse to the “namespace” where the backups are stored, and make sure all the files are validated, with the “OK” status. This result comes from a “verify job” which is, in principle, run periodically and has already done the work.

Read the changelogs#

You’ll find all the changes on the official Proxmox Backup Server wiki, at this address .

Roadmap - Proxmox Backup ServerProxmox Backup ServerIt’s always fascinating to follow these developments, especially when they involve storage tools. With PBS 4.0, OpenZFS has been updated to version 2.3.3, which sparked a lot of discussion in early 2025 because of the many fixes integrated into the Linux kernel. The big news for ZFS is the ability to expand a RAIDZ array without having to recreate it.

Another important new feature is support for S3-type storage, now allowing you to store your VM backups and snapshots on an S3 target.

Update version N-1 (PBS 3)#

When you use PBS in a Proxmox environment, it’s strongly recommended to disable all the backup jobs for your VMs in PVE. Indeed, the upgrade will require a reboot of the machine, blocking access to the PBS storage. Without that access, the VMs cannot be backed up. There’s no point leaving these jobs running in the background, because they will fail and generate unnecessary network traffic.

A maintenance mode can be enabled on demand, by entering the command proxmox-backup-manager datastore update <nom_datastore> --maintenance-mode read-only. To find the name of the datastores, you can enter proxmox-backup-manager datastore list. For my part, here is what I entered:

$ proxmox-backup-manager datastore list
┌───────────┬──────────────────────────┬─────────┐
│ name      │ path                     │ comment │
╞═══════════╪══════════════════════════╪═════════╡
│ pbs-disk1 │ /mnt/datastore/pbs-disk1 │         │
└───────────┴──────────────────────────┴─────────┘
$
$ proxmox-backup-manager datastore update pbs-disk1 --maintenance-mode read-only
$
$ proxmox-backup-manager datastore show pbs-disk1
┌───────────────────┬──────────────────────────┐
│ Name              │ Value                    │
╞═══════════════════╪══════════════════════════╡
│ name              │ pbs-disk1                │
├───────────────────┼──────────────────────────┤
│ path              │ /mnt/datastore/pbs-disk1 │
├───────────────────┼──────────────────────────┤
│ gc-schedule       │ 2:00                     │
├───────────────────┼──────────────────────────┤
│ maintenance-mode  │ read-only                │
├───────────────────┼──────────────────────────┤
│ notification-mode │ notification-system      │
└───────────────────┴──────────────────────────┘

Before moving to a higher version, make sure all the latest updates of the current version are installed. This step is crucial, because it brings your machines up to date and ensures you have the prerequisites needed for a smooth transition to the higher version.

Often, a kernel update is pushed, so a reboot of the machine is then required before performing the upgrade to another version of PBS.

Update to version N (PBS 4)#

The pbs3to4 command is a tool that lets you validate the prerequisites for moving from one major version to another.

Make sure you have at least 10 GB of free space for downloading and decompressing the new packages. You must be on version “3.4.2-1” to move to PBS 4. The PBS server I use in my lab is a virtual machine. Here is the output of the pbs3to4 command:

root@durango:~# pbs3to4
= CHECKING VERSION INFORMATION FOR PBS PACKAGES =

INFO: Checking for package updates..
PASS: all packages up-to-date
INFO: Checking proxmox backup server package version..
PASS: 'proxmox-backup' has version >= 3.4.0
INFO: Check running kernel version..
PASS: running kernel '6.8.12-12-pve' is considered suitable for upgrade.

= MISCELLANEOUS CHECKS =

INFO: Checking PBS daemon services..
PASS: systemd unit 'proxmox-backup.service' is in state 'active'
PASS: systemd unit 'proxmox-backup-proxy.service' is in state 'active'
INFO: Checking for supported & active NTP service..
PASS: Detected active time synchronisation unit
INFO: Checking for package repository suite mismatches..
PASS: found no suite mismatch
INFO: Checking bootloader configuration...
FAIL: systemd-boot meta-package installed. This will cause problems on upgrades of other boot-related packages.
Remove the 'systemd-boot' package.
See https://pbs.proxmox.com/wiki/Upgrade_from_3_to_4#sd-boot-warning for more information.
SKIP: could not get dkms status

= SUMMARY =

TOTAL:     9
PASSED:    7
SKIPPED:   1
NOTICE:    0
FAILURES:  1

ATTENTION: Please check the output for detailed information!
Try to solve the problems one at a time and rerun this checklist tool again.

The most obvious problem concerns the systemd-boot package:

FAIL: systemd-boot meta-package installed. This will cause problems on upgrades of other boot-related packages.
Remove the 'systemd-boot' package.

A quick apt remove systemd-boot and the job is done. Now the server seems ready:

# pbs3to4
= CHECKING VERSION INFORMATION FOR PBS PACKAGES =

INFO: Checking for package updates..
PASS: all packages up-to-date
INFO: Checking proxmox backup server package version..
PASS: 'proxmox-backup' has version >= 3.4.0
INFO: Check running kernel version..
PASS: running kernel '6.8.12-12-pve' is considered suitable for upgrade.

= MISCELLANEOUS CHECKS =

INFO: Checking PBS daemon services..
PASS: systemd unit 'proxmox-backup.service' is in state 'active'
PASS: systemd unit 'proxmox-backup-proxy.service' is in state 'active'
INFO: Checking for supported & active NTP service..
PASS: Detected active time synchronisation unit
INFO: Checking for package repository suite mismatches..
PASS: found no suite mismatch
INFO: Checking bootloader configuration...
PASS: bootloader packages installed correctly
SKIP: could not get dkms status

= SUMMARY =

TOTAL:     9
PASSED:    8
SKIPPED:   1
NOTICE:    0

Using the sed command, we’ll change the name of the Debian release: sed -i 's/bookworm/trixie/g' /etc/apt/sources.list. As of 2025-08-12, the apt modernize-sources command isn’t available yet. You’ll be able to upgrade the sources file afterwards.

# apt update
Get:1 http://ftp.fr.debian.org/debian trixie InRelease [138 kB]
Get:2 http://security.debian.org trixie-security InRelease [43.4 kB]
Get:3 http://download.proxmox.com/debian/pbs trixie InRelease [2,785 B]
Get:4 http://ftp.fr.debian.org/debian trixie-updates InRelease [47.1 kB]
Get:5 http://download.proxmox.com/debian/pbs trixie/pbs-no-subscription amd64 Packages [71.7 kB]
Get:6 http://security.debian.org trixie-security/main amd64 Packages [5,304 B]
Get:7 http://security.debian.org trixie-security/main Translation-en [6,724 B]
Get:8 http://ftp.fr.debian.org/debian trixie/main amd64 Packages [9,668 kB]
Get:9 http://ftp.fr.debian.org/debian trixie/main Translation-en [6,484 kB]
Get:10 http://ftp.fr.debian.org/debian trixie/contrib amd64 Packages [53.8 kB]
Get:11 http://ftp.fr.debian.org/debian trixie/contrib Translation-en [49.6 kB]
Get:12 http://ftp.fr.debian.org/debian trixie-updates/main amd64 Packages [2,432 B]
Get:13 http://ftp.fr.debian.org/debian trixie-updates/main Translation-en [396 B]
Fetched 16.6 MB in 2s (9,658 kB/s)
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
357 packages can be upgraded. Run 'apt list --upgradable' to see them.

The apt dist-upgrade command will perform the package updates. The operation will take around twenty minutes, depending on your hardware. During the update, questions will be asked about which services to restart automatically; I advise you to answer “No”. Indeed, there’s no point restarting the services live during the PBS update, since we’ll have to reboot the server in any case. Other questions will be asked about updating files such as /etc/issue or even /etc/ssh/sshd_config (watch out for your customizations).

Functional testing#

Once you’ve rebooted your machine, try to access your PBS server. That’s the first test: did the server reboot and is it up and running?

Server rebooted, accessible, all that’s left is to restart the backups.

What now?#

Over SSH, run the apt autoremove command to remove the leftovers (in particular the obsolete kernels).

ZFS-type storage#

If your datastores are ZFS-type, moving from PBS 3 to 4 updates zfs to 2.3.3. This version brings its share of improvements as well as new features. When you’re connected to the PBS web interface, select the ZFS storage and click the “Details” button - you’ll see that an action is pending on the pool, to update it.

So, connect over SSH to that PBS, list the ZFS storages, then run the command zpool upgrade <nom_pool_zfs> (replacing the name with your own, of course). The operation doesn’t appear to be destructive (tested on six different PBS hosts, with ZFS storages of every size, on mechanical and flash disks); several features are added to optimize the storage, especially “fast_dedup”.

Additional notes#

With Debian 13, APT moves to version 3 and gets a new format for the sources.list files (Thanks L.G. for the tip!). Debian has a page explaining the changes:

SourcesList - Debian WikiDebian WikiI ran the apt modernize-sources command and the files were updated:

# apt modernize-sources
The following files need modernizing:
  - /etc/apt/sources.list
  - /etc/apt/sources.list.d/pbs-enterprise.list

Modernizing will replace .list files with the new .sources format,
add Signed-By values where they can be determined automatically,
and save the old files into .list.bak files.

This command supports the 'signed-by' and 'trusted' options. If you
have specified other options inside [] brackets, please transfer them
manually to the output files; see sources.list(5) for a mapping.

For a simulation, respond N in the following prompt.
Rewrite 2 sources? [Y/n]
Modernizing /etc/apt/sources.list...
- Writing /etc/apt/sources.list.d/debian.sources
- Writing /etc/apt/sources.list.d/proxmox.sources

Modernizing /etc/apt/sources.list.d/pbs-enterprise.list...

# cat /etc/apt/sources.list.d/proxmox.sources
# Modernized from /etc/apt/sources.list
Types: deb
URIs: http://download.proxmox.com/debian/pbs/
Suites: trixie
Components: pbs-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

If you don’t use Proxmox Backup Server’s enterprise repositories, disable them from the web interface, or by moving/renaming the file “/etc/apt/sources.list.d/pbs-enterprise.sources” to “/etc/apt/sources.list.d/pbs-enterprise.sources.bak”, followed by the apt update command to take the changes into account.

Don’t forget to disable maintenance mode, using the command proxmox-backup-manager datastore update <nom_datastore> --delete maintenance-mode, and/or to re-enable the backup jobs from your Proxmox servers.

Source