Proxmox Backup Server 3 to 4 In-Place Upgrade: Homelab Guide

If your homelab matters, your backups matter more. Proxmox Backup Server (PBS) 4 runs on Debian 13 “Trixie”. PBS 4.0 (August 2025) shipped the Linux 6.14 kernel and ZFS 2.3.3; the current point release, 4.2 (April 2026), defaults to kernel 7.0 and ZFS 2.4.1, and an in-place upgrade today lands you on the latest 4.x. Headline upgrades in 4.x include S3-compatible object storage as a datastore backend (a technology preview in 4.0, fully supported since 4.2), live RAIDZ expansion, and automatic sync on mount for removable datastores. Below is a straightforward, no-subscription in-place upgrade from PBS 3.4 to 4.x, with homelab-friendly notes.On this page:

Why upgrade?

Before you start

• Step 1 — Run the checklist
• Step 2 — Maintenance mode (optional)
• Step 3 — Switch to Trixie & add no-subscription repo
• Step 4 — Upgrade
• Step 5 — Reboot & verify
• Step 6 — Tidy up
• Gotchas & homelab notes
• New features to try next
• FAQ

#!/usr/bin/env bash
# proxmox-upgrade-preflight.sh - ReadTheManual.co.uk
# Pre-flight checks before an in-place Proxmox VE or PBS major upgrade.
# READ THE FULL UPGRADE GUIDE FIRST. This script only checks; it changes nothing.
# Run as root on the node you plan to upgrade:  bash proxmox-upgrade-preflight.sh
set -u
pass=0; warn=0; fail=0
ok(){   echo "  [PASS] $1"; pass=$((pass+1)); }
wrn(){  echo "  [WARN] $1"; warn=$((warn+1)); }
bad(){  echo "  [FAIL] $1"; fail=$((fail+1)); }

echo "== Proxmox upgrade pre-flight (checks only, no changes) =="

# 1. root?
[ "$(id -u)" = "0" ] && ok "running as root" || bad "not root - run with sudo/root"

# 2. which product + version
if command -v pveversion >/dev/null 2>&1; then
  v=$(pveversion | head -1); ok "Proxmox VE detected: $v"
elif command -v proxmox-backup-manager >/dev/null 2>&1; then
  v=$(proxmox-backup-manager version 2>/dev/null | head -1); ok "PBS detected: $v"
else
  bad "neither pveversion nor proxmox-backup-manager found - is this a Proxmox node?"
fi

# 3. disk space (need comfortable headroom for a dist-upgrade)
for m in / /var; do
  availk=$(df -Pk "$m" 2>/dev/null | awk 'NR==2{print $4}')
  if [ -n "${availk:-}" ]; then
    availg=$((availk/1024/1024))
    if [ "$availk" -ge $((5*1024*1024)) ]; then ok "$m has ${availg}G free"; 
    elif [ "$availk" -ge $((2*1024*1024)) ]; then wrn "$m has only ${availg}G free - 5G+ recommended";
    else bad "$m has ${availg}G free - clear space before upgrading"; fi
  fi
done

# 4. repo sanity: enterprise repo without a subscription will 401 mid-upgrade
if grep -rqs "enterprise.proxmox.com" /etc/apt/sources.list /etc/apt/sources.list.d/ 2>/dev/null; then
  wrn "enterprise repo configured - fine WITH a subscription; otherwise switch to no-subscription first"
else
  ok "no enterprise repo configured (no-subscription path)"
fi

# 5. pending updates on the CURRENT release first (uses the cached index: run apt update first)
if apt-get -s dist-upgrade 2>/dev/null | grep -q "^Inst"; then
  wrn "pending updates on current release - fully update BEFORE the major upgrade"
else
  ok "current release fully updated"
fi

# 6. running guests (VE only) - plan a window
if command -v qm >/dev/null 2>&1; then
  running=$(qm list 2>/dev/null | awk 'NR>1 && $3=="running"' | wc -l)
  ct=$(pct list 2>/dev/null | awk 'NR>1 && $2=="running"' | wc -l)
  [ "$((running+ct))" -gt 0 ] && wrn "$((running+ct)) guest(s) running - schedule a window or migrate first" || ok "no running guests"
fi

# 7. cluster quorum (VE clusters)
if command -v pvecm >/dev/null 2>&1 && pvecm status >/dev/null 2>&1; then
  pvecm status | grep -qi "quorate.*yes" && ok "cluster is quorate" || bad "cluster NOT quorate - do not upgrade"
fi

# 8. recent backup evidence (VE only: vzdump logs exist on PVE nodes, not on PBS)
if command -v vzdump >/dev/null 2>&1; then
  newest=$(find /var/log/vzdump -type f -mtime -7 2>/dev/null | head -1)
  if [ -n "${newest:-}" ]; then ok "vzdump activity within 7 days"; else wrn "no vzdump logs in the last 7 days - take/verify backups first"; fi
fi

# 9. PBS only: datastores and ZFS pools healthy
if command -v proxmox-backup-manager >/dev/null 2>&1 && ! command -v pveversion >/dev/null 2>&1; then
  ds=$(proxmox-backup-manager datastore list --output-format json 2>/dev/null | grep -o '"name"' | wc -l)
  [ "$ds" -gt 0 ] && ok "$ds datastore(s) configured" || wrn "no datastores listed - check proxmox-backup-manager datastore list"
  if command -v zpool >/dev/null 2>&1; then
    zpool status -x 2>/dev/null | grep -q "all pools are healthy\|no pools available" && ok "zpool status -x clean" || bad "a ZFS pool is not healthy - fix before upgrading"
  fi
fi

# 10. the official checker for this product (read its output in full)
if command -v pve8to9 >/dev/null 2>&1; then
  echo ""; echo "== pve8to9 --full =="; pve8to9 --full
elif command -v pbs3to4 >/dev/null 2>&1; then
  echo ""; echo "== pbs3to4 --full =="; pbs3to4 --full
else
  wrn "official checker (pve8to9 / pbs3to4) not found - update to the latest 8.4 / 3.4 first"
fi

echo ""
echo "== Result: $pass pass, $warn warn, $fail fail =="
[ "$fail" -gt 0 ] && echo "Fix every FAIL before upgrading. Read the guide for each WARN." || echo "No hard failures. Read the WARNs, take a fresh backup, then follow the guide."

Why upgrade?

• Modern base (Debian 13 “Trixie”) + newer kernel (6.14 at 4.0, 7.0 since 4.2): better hardware support, performance, and security on mixed homelab gear.
• ZFS 2.3+ with live RAIDZ expansion: grow existing RAIDZ vdevs with minimal downtime.
• S3-compatible object storage: point a datastore at public or private S3-API storage; a local cache reduces API calls and cost. A technology preview in 4.0, officially supported from 4.2.
• Automatic sync on mount — run sync jobs whenever a removable datastore is mounted; great for USB/offsite copies.

Before you start (quick checks)

Tip: Use SSH with tmux or screen. Don’t rely on the web console during the upgrade.

1. Be on PBS 3.4 latest (Bookworm repos still in place): apt update && apt dist-upgrade, then proxmox-backup-manager versions, which should show 3.4.2-1 or newer.
2. Back up your config tar czf ~/pbs3-etc-backup-$(date -I).tar.gz -C /etc proxmox-backup
3. Free space: aim for ≥ 10 GB free on /. df -h /
4. If PBS and PVE live on the same box, review the PVE 8 to 9 upgrade and switch both repos in sync.

Step 1 — Run the checklist

Fix what it flags, then re-run until clean. It’s advisory (no changes made) but catches common issues.

pbs3to4 --full

Step 2 — (Optional) Enable maintenance mode

Stop new backups starting mid-upgrade while keeping existing ones readable:

proxmox-backup-manager datastore update <DATASTORE-ID> --maintenance-mode read-only

Step 3 — Point APT at Trixie and the no-subscription PBS repo

No-subscription users: This adds the correct PBS 4 pbs-no-subscription repository in the modern deb822 format.

1) Flip Debian to Trixie

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list
grep -rn bookworm /etc/apt/sources.list /etc/apt/sources.list.d/

The grep lists any Bookworm entries left under /etc/apt/sources.list.d/. Comment each one out with #; the next two steps replace the Proxmox ones.

2) Disable the enterprise repo

Without a subscription, enterprise.proxmox.com returns 401 Unauthorized and apt update fails. Remove the old enterprise file:

rm -f /etc/apt/sources.list.d/pbs-enterprise.list

If a pbs-enterprise.sources file exists, add the line Enabled: no to it instead.

3) Add the PBS 4 no-subscription repo (deb822 format)

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

apt update && apt policy   # ensure only Trixie repos are active

Then remove the old PBS 3 no-subscription line from /etc/apt/sources.list, /etc/apt/sources.list.d/pbs-install-repo.list or wherever you added it, and run apt update and apt policy again. apt update must finish without errors and apt policy should show only Debian trixie and pbs-no-subscription.

Step 4 — Upgrade

apt dist-upgrade

Expect prompts about service restarts and some config diffs (e.g., /etc/ssh/sshd_config, /etc/default/grub). If unsure, defaults are fine — you’ll reboot anyway.

Step 5 — Reboot and verify

pbs3to4 --full   # re-run; act on anything it flags (e.g. removing the systemd-boot meta-package)
systemctl reboot
# after boot:
systemctl status proxmox-backup.service proxmox-backup-proxy.service

Force-reload the web UI after the upgrade (Ctrl+Shift+R on Windows/Linux or ⌘+Alt+R on macOS).

Step 6 — Tidy up

• Turn off maintenance mode if you enabled it: proxmox-backup-manager datastore update <DATASTORE-ID> --delete maintenance-mode
• (Optional) Modernise APT sources to deb822: apt modernize-sources # Answer "n" to preview changes, then run again and "Y" to apply

Gotchas & homelab notes

Heads-up: Keep iKVM/IPMI or physical access handy during any major OS upgrade.

• NIC names may change with the newer kernel; check your network config if links don’t come up as expected. Consider installing the proxmox-network-interface-pinning package, whose CLI tool pins interface names and updates the network config.
• Older hardware: the newer kernel brings changes; test on similar kit if you’re running decade-old controllers.
• Bootloader: systems installed from the PBS 3.0 to 3.4 ISOs carry the systemd-boot meta-package. When pbs3to4 suggests it, remove it (Proxmox manages boot via proxmox-boot-tool); keep it only if you set up systemd-boot yourself.

New features worth trying next

• S3-compatible datastores for budget-friendly offsite copies with caching to reduce API calls.
• Live RAIDZ expansion to grow your pool gradually without a rebuild.
• USB/offsite drive workflows using run-on-mount sync jobs for an easy 3-2-1 backup strategy.

FAQ

Written for homelab & hobbyist users. As always, make sure you’ve got verified backups before any major upgrade.

Read more at the official pages

Proxmox Backup Server 4.0 available

Before you upgrade anything else in the lab, the RTM Toolbox has the pre-flight script, checklists and calculators we use ourselves – all free, no email required.

Related Guides

If you found this useful, these guides continue the journey:

• Proxmox Installation Guide — getting started with Proxmox VE
• Proxmox VE 9 Upgrade Guide — upgrading the hypervisor itself
• Build Your First Homelab — the hardware foundation

Eric Lonsdale

ReadTheManual is run, written and curated by Eric Lonsdale.

Eric has over 20 years of professional experience in IT infrastructure, cloud architecture, and  cybersecurity, but started with PCs long before that.

He built his first machine from parts bought off tables at the local college campus, hoping they worked. He learned on BBC Micros and Atari units in the early 90s, and has built almost every PC he’s used between 1995 and now.

From helpdesk to infrastructure architect, Eric has worked across enterprise datacentres, Azure environments, and security operations. He’s managed teams, trained engineers, and spent two decades solving the problems this site teaches you to solve.

ReadTheManual exists because Eric believes the best way to learn IT is to build things, break things, and actually read the manual. Every guide on this site runs on infrastructure he owns and maintains.

Enjoyed this guide?

New articles on Linux, homelab, cloud, and automation every 2 days. No spam, unsubscribe anytime.

Get new guides straight to your inbox:

New articles every 2 days. No spam, unsubscribe anytime.