Introduction

Operating a Proxmox VE cluster effectively means planning for hardware issues, configuration mistakes and handling unexpected events. Backing up /etc, which houses all vital system and cluster settings, ensures you can restore service swiftly and maintain uptime. There is no need to backup any other directories like anything under /var, /root or otherwise.

Backup Scenarios

Failure scenarios can be broadly seen as the following:

Node Failure: If a Proxmox VE node completely fails due to hardware malfunction or corruption, reinstalling Proxmox VE and restoring configuration files from backup will greatly reduce downtime.
Accidental File Deletion: Administrators or automated scripts can sometimes mistakenly alter or delete essential files. A proper backup ensures rapid restoration of these files without extensive troubleshooting or manual configuration.
Catastrophic Event: Events such as fires, floods or complete data center losses require rebuilding the entire cluster from scratch. A complete backup of configurations simplifies reconstruction.

Essential Files and Directories to Back Up

Critical configuration files for Proxmox VE reside primarily within the /etc directory:

/etc/network: This has the interfaces file which defines network configurations. It also includes the interfaces.d directory which contains Proxmox’s SDN configuration.
/etc/hostname and /etc/hosts: These files define the identity of the node within the cluster and resolve hostnames to IP addresses.
/etc/pve: The Proxmox VE-specific directory includes all cluster-related and guest configurations.

When an entire node is lost and has to be rebuilt, /etc/pve directory is automatically synced from the other nodes when the replacement rejoins the cluster.

Backing up the entire /etc directory thus covers all necessary configurations comprehensively.

Backup Procedure

Make sure you test your backups regularly by restoring them to a temporary directory.

To regularly back up /etc, utilize the Proxmox Backup Client (proxmox-backup-client). A reference on how to use the proxmox-backup-client CLI can be found here. Ensure the Proxmox Backup Server (pbs) and datastore (datastore) configuration is already set up:


root@pve01:~# proxmox-backup-client backup etc.pxar:/etc --repository <proxmox-backup-server-host>:<datastore-name> --backup-type host
Starting backup: [hosts]:host/pve01/2025-05-14T12:56:57Z    
Client name: pve01    
Starting backup protocol: Wed May 14 14:56:57 2025    
Downloading previous manifest (Wed May 14 13:53:32 2025)    
Upload directory '/etc' to 'pbs:datastore' as etc.pxar.didx    
skipping mount point: "pve"
etc.pxar: had to backup 0 B of 2.259 MiB (compressed 0 B) in 0.03 s (average 0 B/s)
etc.pxar: backup was done incrementally, reused 2.259 MiB (100.0%)
Uploaded backup catalog (27.317 KiB)
Duration: 3.37s    
End Time: Wed May 14 14:57:00 2025

If you’d like to use a namespace, simply add a --ns <namespace> flag to the command like so. Make sure the namespace actually exists on the Proxmox Backup Server host before specifying it here.

root@pve01:~# proxmox-backup-client backup etc.pxar:/etc --repository <proxmox-backup-server-host>:<datastore-name> --ns <namespace> --backup-type host

Automating Backups

Automation with systemd Timers

The use of systemd-timers here instead of cron is because:

systemd timers prevent tasks from overlapping, ensuring only one instance runs at a time, unlike cron.
They offer integrated logging via journalctl and simplified task management with systemctlcommands.
Timers provide more flexible scheduling with granular timing, event-based triggers, and robust dependency management.

Create two files: a systemd service unit and a systemd timer unit.

Create the service unit, /etc/systemd/system/proxmox-backup.service:

[Unit]
Description=Proxmox Host Backup
[Service]
Type=simple
EnvironmentFile=/etc/default/proxmox-backup
ExecStart=/usr/bin/proxmox-backup-client backup etc.pxar:/etc --repository ${PBS_REPOSITORY} --backup-type host --keyfile /etc/proxmox/backup.key
StandardOutput=journal
StandardError=journal

Create the timer at/etc/systemd/system/proxmox-backup.timer:

[Unit]
Description=Daily Backup
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target

Enable the timer:

systemctl daemon-reload
systemctl enable --now proxmox-backup.timer

Define the backup server details in /etc/default/proxmox-backup:

PBS_REPOSITORY=root@pam@your-pbs-server:your-datastore
PBS_PASSWORD="your-pbs-password"
PBS_FINGERPRINT="your-server-fingerprint"
PBS_ENCRYPTION_PASSWORD="your-backup-key-password"

Encryption Key Creation

For additional security, you may create a client-side encryption key:

root@pve01:~# mkdir /etc/proxmox
root@pve01:~# proxmox-backup-client key create /etc/proxmox/backup.key
Encryption Key Password: ********
Verify Password: ********
root@pve01:~# chmod 600 /etc/proxmox/backup.key

Include the key in the backup command with --keyfile /etc/proxmox/backup.key.

Restoration

Single File:

If a single file is deleted, use the proxmox-backup-client to restore the file. In this example, we assume it’s /etc/network/interfaces.

First list all the backups:

root@pve01:~# proxmox-backup-client list --repository pbs:datastore 
┌────────────┬─────────────────────────────────┬──────────────┬───────────────────────────────────┐
│ group      │ last snapshot                   │ backup-count │ files                             │
╞════════════╪═════════════════════════════════╪══════════════╪═══════════════════════════════════╡
│ host/pve01 │ host/pve01/2025-05-14T12:56:57Z │            2 │ catalog.pcat1 etc.pxar index.json │
└────────────┴─────────────────────────────────┴──────────────┴───────────────────────────────────┘

The list presented will likely have multiple backups / snapshots. Pick the latest snapshot and then use the --pattern argument with the restore subcommand of proxmox-backup-client to retrieve a single file from the backup.

root@pve01:~# proxmox-backup-client restore host/pve01/2025-05-14T12:56:57Z etc.pxar /tmp/ --repository pbs:datastore --pattern 'network/interfaces'
root@pve01:~# tree /tmp
/tmp
└── network
    └── interfaces
2 directories, 1 file

Complete Node:

If a complete node is lost, follow these steps:

Reinstall the node with the original hostname.

Restore only the files needed as a reference, for example/etc/network/interfaces or /etc/hosts that might have specific configurations that are time-consuming to reimplement and are easier to copy and paste.

root@pve01:~# proxmox-backup-client list --repository pbs:datastore
┌────────────┬─────────────────────────────────┬──────────────┬───────────────────────────────────┐
│ group      │ last snapshot                   │ backup-count │ files                             │
╞════════════╪═════════════════════════════════╪══════════════╪═══════════════════════════════════╡
│ host/pve01 │ host/pve01/2025-05-14T12:56:57Z │            2 │ catalog.pcat1 etc.pxar index.json │
└────────────┴─────────────────────────────────┴──────────────┴───────────────────────────────────┘
root@pve01:~# proxmox-backup-client restore host/pve01/2025-05-14T12:56:57Z etc.pxar /tmp/pbs --repository pbs:datastore --pattern 'interfaces'

- It’s not recommended to restore the whole /etc directory as several of the node’s attributes may have changed (eg. new hardware). If blindly restored, it might end up breaking the entire node or the cluster.
- The cluster configuration (stored in /etc/pve) will automatically be synchronised when the node rejoins the cluster.
- Restore only the files that are needed from /etc to speed up the process by using the --pattern argument. If multiple files need to be restored, --pattern can be used multiple times.
Reboot the node once all the configuration is in place.
Rejoin the node to the cluster.

Cluster Loss:

Rebuild the cluster from scratch while referring to the backups for any special configuration like networks or storage. It is not recommended to restore any of the previously backed up files as it will be a completely new cluster. It is best to use the backups as a handy reference.

Conclusion

This guide walks you through backing up the full /etc directory using proxmox-backup-client, optionally setting up encryption with a client-wide key, and automating daily backups via systemd timers. We cover how to restore individual files and deal with the loss of an entire node or even an entire cluster. Along with the above, remember that testing backups regularly makes sure the backups actually work when you need them.

Backing up a Proxmox Node in a Proxmox VE Cluster using Proxmox Backup Client

24/7 premium support