Backups with Proxmox Backup Server

NexoVirt covers two kinds of backups:

• Guest backups on Proxmox Backup Server (PBS) or any other Proxmox backup storage: backup jobs, per-guest backups, browsing, restore, prune and encryption.
• Panel backups of NexoVirt itself (database and uploaded files), under Storage & Backups → Backups.

All backup pages live in the Storage & Backups sidebar menu: Backup servers, Backups and Backup browser.

Servers and datastores

Storage & Backups → Backup servers lists each Proxmox Backup Server once, with its datastores underneath (expand a server row to see them).

• A server is one PBS instance: name, address, port (default 8007), optional API token and the pinned TLS certificate fingerprint.
• A datastore row is a datastore plus an optional namespace on that server. Attachments to nodes, prune policies and encryption keys belong to the datastore row, so two namespaces on the same server are managed separately.

Each datastore row shows the nodes it is attached to (as node / cluster · storage ID), an Encrypted badge when client-side encryption is on, and how the panel reaches it (see below).

Automatic discovery

You usually do not need to add anything by hand. On every inventory run, NexoVirt reads each host’s Proxmox storage configuration and creates a server and datastore entry for every pbs storage it finds. These entries carry a Discovered badge and no API token.

• A datastore whose storage disappears from a node is detached automatically.
• A discovered server that is no longer used anywhere, and that you never edited, is removed.
• Servers you entered yourself are reused and never overwritten by discovery.
• If a storage read fails, nothing is changed.

Adding a server manually

1. Open Storage & Backups → Backup servers and click Add PBS.
2. Enter a Name, the Server address (for example pbs.example.com), the Port and a Token ID (user@realm!tokenname) with its Token secret.
3. Click Test & Discover. The panel connects to PBS, fills in the Fingerprint and lists the available datastores and namespaces.
4. Pick a Datastore and, optionally, a Namespace. Turn on Encrypt backups if new backups should be encrypted client-side (see Encryption).
5. Save. Use Add datastore on the server row to add further datastores of the same server.

Import existing lists pbs storages already configured on your nodes that the panel does not manage yet, and adopts one with an optional token secret.

The token secret and the encryption key are stored encrypted. Edit on a server row changes the address or token (leave the secret blank to keep the stored one). A server can be deleted only when it has no datastores left; a datastore can be Removed only after it is detached from every node.

Attach and detach

Attach on a datastore row creates a pbs storage on the selected node or cluster, using the pinned fingerprint and, if set, the encryption key. Detach a node with the × on its badge in the datastore row.

How the panel reaches a datastore

The Access column shows how NexoVirt talks to each datastore:

Access	Meaning
via node	Through a node where the storage is attached and active. No PBS token needed. Preferred whenever available.
API token	Directly through the PBS API with the stored token.
Unreachable	Neither works: the datastore is not attached to any node, or the storage is inactive on every node (check that PBS is running and port 8007 is open).

Most actions work through a node. Garbage collect and Verify always need a PBS API token; without one the buttons are disabled and the page says so. Add a token with Edit on the server row.

The datastore page

Click Manage on a datastore row. The header says how the datastore is reached and offers Verify, Garbage collect, Prune, Enable encryption or Rotate key. When a server has several datastores, Switch datastore jumps between them.

• Datastore usage: total, used and available space, plus the dedup factor when PBS reports it.
• Snapshots: a searchable table of backups with type, ID / VMID, backup time, size, notes, verification state and protection.
• Prune policies and, for encrypted datastores, Key history.

Backup actions

When the datastore is reached via a node, each snapshot row has an actions menu:

• Restore… restores a VM or container backup as a new guest on that node. The dialog checks a free VMID live (the original VMID when it is free, otherwise the next free one) and offers only target storages that can hold the guest’s disks. A restore here never overwrites an existing guest. The restore runs as a normal provisioning job.
• File restore… browses the files inside a backup and downloads single files. The first look can take up to a minute while the node mounts the backup.
• Show configuration shows the guest configuration stored in the backup.
• Edit notes… sets the backup’s notes.
• Protect / Remove protection. Prune and delete skip protected backups.
• Delete… removes the backup from the datastore. Not offered while the backup is protected.

Prune

Prune opens a dialog with the standard retention rules: Keep last, Keep daily, Keep weekly, Keep monthly, Keep yearly. Preview (dry-run) lists which snapshots would be kept or removed; Prune now applies the rules. Prune is applied per backup group.

Scheduled prune policies

Under Prune policies, Add policy stores the same keep rules with an Interval (hours) and an Enabled switch. When reached with an API token you can also limit a policy to a namespace.

Note

php spark pbs:prune --once evaluates due policies. The installer’s cron setup runs it every hour.

Garbage collection and verify

Garbage collect reclaims space from deleted backups; Verify runs a full verification of the datastore. Both start a PBS task and need a PBS API token.

Encryption and key rotation

Client-side encryption is set per datastore:

• Turn on Encrypt backups when adding the datastore, or click Enable encryption on its page. A key is generated, applied to the attached nodes and shown once. Store it somewhere safe: encrypted backups cannot be restored without it.
• Rotate key generates a new key, archives the old one and re-keys the attached node storages (best effort; failures are listed as warnings). The new key is shown once.
• Key history lists archived keys by fingerprint and date only. Key material is never shown again.

Caution

Key rotation is a newer part of the integration. Keep your own copy of every key the panel shows you, and test a restore of an encrypted backup before you rely on it for disaster recovery.

Backup jobs

Scheduled guest backups are Proxmox datacenter backup jobs. Open them from a node page with Backup jobs. The page lists the jobs of that host (node or cluster) and New job creates one:

• Schedule: Proxmox calendar syntax such as sun 03:00, or a cron expression like 0 2 * * *.
• Target storage: a storage that accepts backup content (a PBS datastore or another backup storage).
• Guest selection: All, a Pool, or specific VMIDs.
• Backup mode: Snapshot, Suspend or Stop.
• Keep last, Enabled and an optional Comment.

Jobs can be edited, enabled or disabled, and deleted from the table.

Backups of a single guest

The Backups tab on a guest’s page lists that guest’s backups across the host’s backup storages. Pick a storage and click Back up now to start a backup. From the table you can restore a backup over the guest (this overwrites its current data; you confirm by typing the VMID) or delete it.

Backup browser

Storage & Backups → Backup browser (also Browse backups on a node page) lists all backups of a host, filterable by storage and node, with Restore, Delete and Verify (Verify only for PBS backups). Restore here restores over the existing guest with the same VMID.

Tip

To get a backup back next to the running guest instead of over it, use Restore… on the datastore page under Backup servers, which always creates a new guest.

Backups of the panel itself

Storage & Backups → Backups backs up NexoVirt’s own data. An archive contains a dump of the panel database, writable/uploads and the uploaded images (OS template group images and the brand logo).

• Enable scheduled backups turns on the daily run (02:30 via the cron jobs set up by the installer).
• Destination: Local (writable/backups), FTP or SFTP. Remote destinations take a server, port, user, remote path and password; SFTP can use a private key instead. Credentials are stored encrypted.
• Keep (retention): the number of backups to keep per destination; older ones are pruned.
• Test connection checks the remote destination, Run backup now starts a backup immediately, and Backup history lists every run with size, status and a download.

The .env file is not in the archive

The .env file holds the encryption key that protects stored host passwords, tokens and keys. It is excluded on purpose. Keep a separate, secure copy of it: a database restored without the matching key cannot decrypt those secrets.

Restoring the panel

1. Download a backup from Backup history and copy it to the server.
2. Extract it: tar -xzf nexovirt-backup-*.tar.gz.
3. Import the database: mysql <db> < db.sql.
4. Copy uploads/ back to writable/uploads and the contents of images/ back to public/assets/.
5. Make sure the .env with the original encryption key is in place.

Backup alerts

The alerting engine has two backup alert types:

• Backup failed: a guest backup failed recently.
• Backup stale: a guest’s last successful backup is older than the rule’s threshold (in hours). Guests that were never backed up are not flagged.

Next steps

• Failover restores guests of a failed host from these PBS backups.
• Alerts & webhooks for backup alerts in context.
• CLI & daemons for pbs:prune and backup:run.