CaryvaneHelp
/
EN

Back up a Proxmox server

Proxmox VE backs up a virtual machine incrementally and deduplicated only when the backup goes to something that speaks the Proxmox Backup protocol. The Caryvane agent on a Proxmox node speaks it: Proxmox sees a backup server on the node itself, and every chunk it sends lands in the storage you chose, in exactly the layout a Proxmox Backup Server keeps. Backups are scheduled, run, browsed and restored from the Proxmox web interface, as they would be with a Proxmox Backup Server; Caryvane adds the storage, the catalogue, the alerts and a recovery key.

Compatible with Proxmox Backup Server

Caryvane is not a Proxmox product and does not contain Proxmox Backup Server. It implements the protocol Proxmox VE uses to talk to one, so Proxmox treats the agent as a backup server. Proxmox and Proxmox Backup Server are trademarks of Proxmox Server Solutions GmbH.

1. Install the agent on every node #

Proxmox runs a virtual machine's backup on the node the machine is on, and talks to the backup server at 127.0.0.1. So every node of the cluster needs the Caryvane Linux agent, enrolled for the customer who owns the cluster. It is the ordinary Linux agent; there is no separate Proxmox agent. On a Proxmox node it notices Proxmox by itself and reports the version, which is how Caryvane knows the machine can serve backups. Create the cluster in Caryvane from any one node. Once the cluster has a storage area, every other node whose agent is installed joins it by itself within a few minutes: it proves it belongs to the same Proxmox cluster with the storage token Proxmox shares between its nodes. Add node on the cluster's page still works for a node you want in straight away. If a machine you pick is on a node without the agent, the job dialog says so, and its backups show as failed runs naming the node rather than as completed.

  1. In Caryvane, create an enrollment token for the customer (Agents → Enroll Agent) and follow the Linux instructions on each node. The package is a .deb for Debian, which is what a Proxmox node runs.
  2. Wait for each node to show as online. A node on Proxmox shows its Proxmox version on its agent card; that is how the wizard knows it may host the datastore.

Each node is one agent, and is billed as one agent. There is no charge per virtual machine.

2. The cluster, its storage areas, and what to back up #

  1. Jobs → New job → Back up a Proxmox server. The first time, name the cluster and choose its first node. Add the other nodes from the Proxmox page afterwards; they need nothing else, because every node serves the same certificate.
  2. Back up machines: tick the VMs and containers (the list comes live from the cluster), or choose every machine, including ones created later, or every machine in a Proxmox pool. Choose the storage and a folder in it, when (daily, on chosen days, or every few hours) and how long to keep: a backup a day for N days, and optionally at least the last N.

For example: VM 146 kept 5 days in storage M, folder proxmox/vm146, and VM 170 kept 30 days in storage Y, are two jobs. Each storage and folder becomes its own storage in Proxmox, caryvane-name, with its own encryption key, registered by the agent within a few minutes. The same machine can be in two jobs to two storage areas, say nightly to the UK for a month and weekly to cheap storage for a year.

Caryvane writes each job into the cluster as a Proxmox backup job (Datacenter → Backup, marked caryvane-job in its comment) and keeps it in step: change it in Caryvane and the Proxmox job changes; delete it and the Proxmox job goes. Proxmox does the running, so its incremental backups, the guest-agent freeze and live migration all behave as normal. Do not edit those jobs in Proxmox; Caryvane puts them back. Backup jobs you make yourself in Proxmox to a Caryvane storage still work, and show on the Proxmox page as made in Proxmox.

Run now on a job starts its backups straight away. Every backup appears as a run of its job, with the size, what was sent and what was already stored. If no backup reaches a storage area within the interval you set, it is flagged as late.

For providers: backing up into a customer's own storage #

A provider's Proxmox server can back a customer's virtual machines up into the customer's storage, for example their own UK bucket. The customer allows it first: on their storage target, Storage → … → Allow my provider's Proxmox servers. Only storage of customers beneath the provider can be chosen, never another provider's or a sibling's, and the provider's own storage needs no tick.

3. The encryption key: back it up now #

The storage is created with an encryption key that Proxmox generates and keeps in /etc/pve/priv/storage/. Every chunk is encrypted on the node before it leaves; Caryvane and the storage only ever hold ciphertext. Proxmox shows the key once and asks you to back it up: do that, into a password manager or a printed copy kept away from the cluster. A cluster that is lost takes the key with it.

There is a second way back. The storage entry also carries a Caryvane master key, and Proxmox encrypts a copy of the data key to it inside every backup. Caryvane keeps the private half, encrypted, and a manager can download it from the job page as a recovery key. With the recovery key and the Proxmox tools, every backup is readable again even if the cluster and its key are gone. Download it once and keep it with the first one; the download is recorded in the audit trail.

Never run pvesm set … --encryption-key autogen on the Caryvane storage: it replaces the key silently, and every earlier backup then needs the recovery key.

4. What is backed up and how #

Every Proxmox backup appears in Caryvane as a run of the datastore's job, one per machine, with the size, the chunks sent and the bytes reused. The job page lists every snapshot of every machine.

5. Restoring #

Restores are done in the Proxmox web interface, exactly as from a Proxmox Backup Server. Caryvane serves the backups to Proxmox; there is no restore button in Caryvane for Proxmox machines. The cluster's page in Caryvane repeats these steps with its own storage names.

A whole machine #

  1. In Proxmox, under any node, click the Caryvane storage. Its name starts caryvane- (for example caryvane-test); the storage area's card in Caryvane shows it.
  2. Open Backups. Every backup of every machine on that storage area is listed, newest first.
  3. Pick the backup and click Restore.
  4. Choose where it goes. A new VM ID restores alongside the original, which is the safe choice when you only want to look. The machine's own VM ID replaces it; Proxmox asks you to stop the machine first and overwrites its disks.
  5. Pick the target storage for the disks (for example your Ceph pool) and start the restore. Progress shows in Proxmox's task log at the bottom of the screen.

From the command line, qmrestore caryvane-test:backup/vm/153/2026-10-18T17:40:45Z 9153 does the same (pct restore for a container). On our own cluster a 50 GiB machine restored from a cloud bucket in about half a minute and booted normally.

Single files and folders #

  1. Open the Caryvane storage and Backups as above, pick the backup and click File Restore.
  2. Proxmox starts a small temporary helper to read the backup. Open the disk (for example drive-scsi0), then the partition that holds the files; a swap partition cannot be opened.
  3. Browse to the file or folder and click Download. A folder downloads as a zip.

Nothing is written to the running machine; copy the file back yourself. The first browse of a backup takes a little longer while the helper starts.

If the cluster is lost #

The backups are safe in the storage, but each one is encrypted on the node with a key Proxmox kept on the cluster (/etc/pve/priv/storage/caryvane-<name>.enc). If you kept a copy of that file when Proxmox showed it, put it back on the new cluster and restore as normal. If not, the customer's recovery key in Caryvane recovers it:

  1. Install the Caryvane agent on a Proxmox node of the new cluster, add the node to a cluster in Caryvane, and add the same storage, bucket and folder as a storage area. The backups appear under the new caryvane- storage in Proxmox.
  2. On the cluster's page in Caryvane, click Recovery key next to the customer and save the key as master.pem on the node.
  3. Fetch the encrypted key that every backup carries, and unlock it with the recovery key:
    proxmox-backup-client restore vm/153/2026-10-18T17:40:45Z rsa-encrypted.key rsa-encrypted.key \
      --repository 'USER@127.0.0.1:8007:DATASTORE'
    proxmox-backup-client key import-with-master-key old.enc \
      --master-keyfile master.pem --encrypted-keyfile rsa-encrypted.key --kdf none
    USER and DATASTORE are the username and datastore lines of the storage in /etc/pve/storage.cfg; the password is in /etc/pve/priv/storage/caryvane-<name>.pw (give it as PBS_PASSWORD), and PBS_FINGERPRINT is the storage's fingerprint line. --kdf none leaves the recovered key without a password, which is what a Proxmox storage takes.
  4. In Proxmox, Datacenter → Storage, edit the Caryvane storage, Encryption, and upload old.enc as its key. The old backups now restore as normal.

Keep each customer's recovery key somewhere that survives losing the cluster. Downloading it is recorded in the audit trail.

Snapshots can be protected and annotated in Proxmox. Each job's retention prunes its own machines' backups; a storage area's never keep longer than, if set, removes older ones on top, never the newest of a machine and never a protected one. Proxmox's own tools work too: proxmox-backup-client pointed at 127.0.0.1:8007 on any node, with the storage's token.

Boot checks: testing that backups restore #

A backup that has never been restored is a hope. A boot check restores a machine's newest backup on the cluster as a throwaway copy, starts it, asks it who it is, takes a picture of its screen and deletes it again, on a schedule, without anyone watching. The Proxmox page then shows a badge beside each machine: Booted 2 days ago (green), Booted, no guest agent (amber), Boot check failed (red) or Not checked. Click a badge for the screenshot, the host name and operating system the machine gave, which backup was tested and the run log.

A green badge means the copy booted and answered through the QEMU guest agent. It does not test the applications inside, and it is not a promise that every file is intact; it is strong evidence that the backup is a working machine.

Setting it up #

  1. On the cluster's page in Caryvane, Boot checks → Set up boot checks.
  2. Tick the machines to check. Nothing is checked unless you tick it. Machines are checked one at a time, smallest first.
  3. Name the Proxmox storage the copies are restored to, for example local-lvm or a Ceph pool. It must exist on the node that runs the checks (shown on the card; it is the node that writes the cluster's backup jobs).
  4. Set the size cap (200 GB unless you change it), how long a machine has to boot (10 minutes) and the days and time. The default is Saturdays at 12:00 UTC, away from the nightly backups; if backups are running when it starts, it waits for them to finish.

Check now runs it straight away. Each check is also a run of the boot check job, with its log, in the jobs list.

What a check does to the cluster #

Without the QEMU guest agent inside the machine the badge can only say it booted, so it is amber: open the screenshot to see how far it got. Installing the guest agent in each machine also makes its backups application-consistent.

The cluster can also boot-check physical Windows machines: a whole-machine backup can be restored to a throwaway VM on a node on a schedule, with the same isolation, VM ID range and clean-up, and a whole-machine restore point can be restored to a lasting Proxmox VM.

The full screenshot is kept in the customer's own storage, next to the backups (verify/VMID/ in the storage area's folder); Caryvane keeps only a small thumbnail. Failed checks are emailed to the addresses in Settings → Notifications; switch off Boot check failed there if you do not want them.

6. Which storage, and what to expect #

Any Caryvane storage target works. The difference is speed:

If you cannot change the cluster yet #

Two routes work today without anything on the Proxmox nodes. Install the Caryvane agent inside each virtual machine, which gives file and application backup (including Hyper-V, SQL Server and Active Directory on Windows guests) but not whole-machine restore. Or schedule vzdump on a node into a local directory and back that directory up with an ordinary Caryvane file job; every night's archive is a full one, so this suits small machines.