Note: To keep this guide clear and easy to follow, I’ve divided it into two parts. The first part covers the overall process and goals—the 'why' behind each step. The second part, found at the end of this article, is a Command Reference Guide with all the commands used in the video. This way, we can focus on the big picture first, then quickly reference the practical commands when it’s time to build. Keep in mind that specific commands and configurations may vary depending on your operating system, its version, and your environment.
What's up, guys? Welcome back to the channel. In the last blog, we set up Proxmox Backup Server and even covered how to back up our VMs and containers. However, when it comes to backups, most people focus on protecting their VMs and containers — and that makes sense. But what about the Proxmox host itself? The host holds your network setup, user accounts, and all the configuration files that define how your environment runs. If you ever lose that, rebuilding from scratch can be painful.
In this post, we’ll walk through the full process of backing up and restoring your Proxmox host configuration using Proxmox Backup Server (PBS). The idea is simple: all of your important config files get automatically backed up to PBS, so if your host ever fails, you can rebuild it quickly and get back up and running.
Two Ways to Back Up a Proxmox Host
When it comes to backing up your Proxmox host, you have two main approaches:
Option 1 – Manual Configuration Backup: This method focuses on backing up only the important configuration files — things like your network setup, user accounts, and VM definitions. You’re not backing up the actual VM data, just the configuration that tells Proxmox how everything is connected.
Option 2 – Full System (Bare-Metal) Backup: This option creates a full system image, which includes everything: operating system, configuration, and all data. It’s easier to restore since it brings back your entire system as-is, but it takes up more space and can sometimes create compatibility issues if you’re restoring to different hardware.
In this walkthrough, we’ll focus on Option 1, the configuration-level backup, since it’s lightweight, easy to automate, and covers 90% of what you’d need to recover your environment quickly. Also, if you have been following along, you should have created a back of your VMs and Container from our previous blog (Setting Up Proxmox Backup Server (PBS) with Proxmox VE Integration). Ideally, you should combine both approaches: use configuration-level backups weekly, and a full bare-metal backup monthly. That way, you’ll always have a fast restore option and a full image for disaster recovery.
How This Works
Proxmox does not yet include a built-in “host backup” out of the box for PBS. But because Proxmox is just Linux under the hood, we can use a command-line tool called "Proxmox Backup Client" to send important files directly to PBS.
So here’s the plan:
- Create a PBS user and API token for authentication.
- Use the Proxmox Backup Client to send key configuration folders to PBS.
- Automate the process with a simple shell script and a scheduled cron job.
- Test the restore process by pulling those files back and applying them to a new host.
By the end, you’ll have an automated backup routine that keeps all your host configs safe and easily restorable.
What to Back Up
You can technically back up any config file you want, but for most setups, the following folders are critical:
- /etc/pve/ – Contains Proxmox configuration files: VM definitions, cluster info, and storage settings.
- /etc/network/ – Holds all your network configuration details: bridges, bonds, IPs, and VLANs.
If you have these two directories backed up, you can rebuild your Proxmox host and restore its structure.
Testing the Backup
Once you’ve created your PBS user and API key, you can use the Proxmox Backup Client to push your host config files to PBS. The idea is to confirm that the authentication works and that PBS is receiving your data correctly.
You’ll see a snapshot appear in your PBS datastore — this is where your host configuration now lives, alongside your VM and container backups. If you open that snapshot, you’ll see files like:
- host-config.pxar
- network-config.pxar
Those are your host backups, safely stored and ready to restore.
Automating the Process
Manual backups are fine for testing, but automation is where this really shines. The best way to do this is by writing a simple shell script that:
- Defines the PBS repository, datastore, and API credentials.
- Specifies which folders to back up.
- Adds a date to the filename for clarity.
- Runs automatically at a set time via cron.
Once set up, your Proxmox host will quietly send updated configuration backups to PBS on schedule — no manual steps required. You can choose to run the job nightly, weekly, or even every few hours depending on how frequently you make changes. For most environments, once per day or once per week is more than enough.
Restoring Your Host
Now for the part most people forget to test — restoration. Before restoring, it’s important to understand what’s actually being replaced. When you pull back your old configs, you’re overwriting your current system files. If your new host uses different hardware, NIC names, or storage layouts, restoring everything blindly can break the setup.
Here’s how to do it safely:
- Create a temporary restore directory (for example, /mnt/pbs-restore).
- Restore your backup files into that directory using the Proxmox Backup Client.
- Review the files — check network interfaces, hostnames, and storage entries.
- Once you’ve verified and made any adjustments, copy the configs into /etc/pve/ and /etc/network/.
This “staging folder” approach lets you safely inspect everything before you overwrite system files.
Rebuilding from the Backup
Once your configs are verified and applied, Proxmox will pick up your network, storage, VM, and container definitions almost instantly.
A few tips before hitting “restore” on anything major:
- Storage first. Recreate your old storage pools (ZFS, LVM, Directory, etc.) with the same names before restoring configs.
- Match NIC names. Rename network interfaces on the new host to match your old config or update the config before applying it.
- Be selective. Don’t restore every file — just the ones relevant to your new setup.
- Verify before overwrite. Always open the restored configs and check their contents before copying them into /etc/pve/.
Once your skeleton is in place, you can restore your VM and container data from PBS. As long as the VM IDs and datastore names match, PBS will automatically detect and restore the right data.
After restoring both your host and VM data, you’ll see your entire environment back online — network bridges, storage pools, and all. The best part? Everything now lives in one centralized location — Proxmox Backup Server — making it easy to manage, schedule, and even replicate to the cloud or offsite for disaster recovery. This method gives you both peace of mind and flexibility. Even if your Proxmox host fails completely, you can rebuild it from scratch.
Command Reference Guide
Below is a simplified command guide that walks you through the core steps from setup to restoration. You can copy and paste these commands into your environment and adjust as needed.
Define PBS Repository and API Key
- export PBS_REPOSITORY='user@pbs!api-token@pbs-server-ip:datastore-name'
- export PBS_PASSWORD='your-api-secret'
Run a Test Backup
proxmox-backup-client backup \
host-configs.pxar:/etc/pve \
network-config.pxar:/etc/network \
--backup-id proxmox-host-configs
Create Backup Script:
- nano /root/backup-proxmox-configs.sh
Script:
#!/bin/bash
#
# === Settings ===
export PBS_REPOSITORY='user@pbs!api-token@pbs-server-ip:datastore-name'
export PBS_PASSWORD='your-api-secret'
# === Timestamp ===
DATE=$(date +%F)
# === Run backup ===
proxmox-backup-client backup \
etc-pve-${DATE}.pxar:/etc/pve \
etc-network-${DATE}.pxar:/etc/network \
--repository ${PBS_REPOSITORY} \
--backup-id proxmox-host-configs
Make it executable:
- chmod +x /root/backup-proxmox-config.sh
Schedule It with Cron
- crontab -e
- Add this line (you can change as you see fit):
- 0 23 * * * /root/backup-proxmox-config.sh >> /var/log/proxmox-config-backup.log 2>&1
- Add this line (you can change as you see fit):
Restore Configuration Files
Before starting the restoration process, you’ll need to list the available backups on your PBS server. Once you have that information, you can use it to select and restore the desired backup.
- List your backups
- proxmox-backup-client snapshots --repository 'user@pbs!api-token@pbs-server-ip:datastore-name'
- Create a restore directory and pull files from PBS:
- mkdir -p /mnt/pbs-restore
- cd /mnt/pbs-restore
- proxmox-backup-client restore host/proxmox-host/2025-10-03T21:33:01Z etc-pve-2025-10-03.pxar /mnt/pbs-restore/etc-pve
- proxmox-backup-client restore host/proxmox-host/2025-10-03T21:33:01Z etc-network-2025-10-03.pxar /mnt/pbs-restore/etc-network
Review your configs: Make sure to review all configuration files you’re migrating to your new host. In the example below, we’re reviewing the storage and network interface configurations.
- cat /mnt/pbs-restore/etc/pve/storage.cfg
- cat /mnt/pbs-restore/etc/network/interfaces
When satisfied, copy them into new host: After you’ve verified the configurations, copy only what you need into your new host. Warning: this will overwrite the configs on your new host, so double-check before you proceed.
In the example below, we copy VM configs, container configs, and the storage config. Avoid copying the entire /etc/pve directory—doing so can introduce node/cluster mismatches and other issues. Be selective.
- Storage: cp -a /mnt/pbs-restore/etc/pve/storage.cfg /etc/pve/
- Network: cp -a /mnt/pbs-restore/etc/network/* /etc/network/
- LXC: cp -a /mnt/pbs-restore/etc/pve/lxc/* /etc/pve/lxc/
- VMs: cp -a /mnt/pbs-restore/etc/pve/qemu-server/* /etc/pve/qemu-server/
Once your Proxmox host and storage pools are recreated, you can how connect to you PBS server and restore VM and container data from.
Final Thoughts
And that’s it — you now have a complete, repeatable backup and restore system for your Proxmox host. By keeping your configuration files safely backed up to PBS, you can rebuild your environment quickly after any failure. Combine that with regular VM and container backups, and you’ve got yourself a full-stack recovery plan with very little overhead.
It takes some setup the first time, but once automated, it just works — quietly protecting the backbone of your environment every day. As always — stay geeking, stay curious, and keep building.
