Glossary

Backup & Restore~8 min

Terms used across the backup & restore documentation, with their definition.

Terms are grouped by theme. Every entry gives the term and a short definition.

Encryption and key recovery

Vocabulary for the PBS encryption block. It involves two distinct secrets: a binary keyfile and a written passphrase.

Recovery passphrase: Text password the operator picks to protect the recovery envelope. It is prompted twice with a match check, and is only used to encrypt the envelope and to decrypt it if the keyfile ever needs to be recovered. It is not the passphrase that unlocks the keyfile itself, and it is never sent to PBS. During a normal backup it never leaves the host.
Keyfile (encryption key): Binary file that Proxmox Backup Server uses to encrypt the chunks of each backup before uploading them. Without this file, no encrypted backup can be read. ProxMenux stores it at /usr/local/share/proxmenux/pbs-key.conf with mode 600. This is the asset that has to be protected; the recovery envelope exists precisely so that this file can be rescued if it is lost.
Keyfile passphrase (KDF passphrase): Optional passphrase that the keyfile itself may carry, distinct from the recovery passphrase. It only exists when the keyfile was created with --kdf scrypt (typically an imported keyfile). Without it, the keyfile cannot be unlocked for use. ProxMenux persists it in encrypted form on the host so that scheduled backups can run without an interactive prompt.
Recovery envelope: The keyfile wrapped in an extra layer: it is encrypted with the recovery passphrase using AES-256-CBC and PBKDF2 before it ever leaves the host. It is what gets uploaded to PBS as the -keyrecovery group. Without the passphrase, the envelope is opaque: downloading it from PBS does not reveal the keyfile.
Client-side encryption: Encryption model in which data is encrypted on the source host before being uploaded. PBS only ever receives and stores ciphertext; not even a PBS administrator with datastore access can read it without the keyfile. ProxMenux builds on this model and adds the recovery envelope on top.
--kdf none: Option to proxmox-backup-client key create that produces a keyfile with no attached passphrase. The keyfile can be used directly without a prompt, which is essential for scheduled jobs running unattended. This is what ProxMenux uses by default when generating a new keyfile.
--kdf scrypt: Option to proxmox-backup-client key create that produces a keyfile protected by a keyfile passphrase. Each use of the keyfile requires unlocking it with that passphrase. ProxMenux accepts this style of keyfile on import and stores the passphrase encrypted so scheduled backups can still run unattended.
AES-256-CBC: Standard symmetric cipher. ProxMenux uses it (via openssl enc -aes-256-cbc) to wrap the keyfile with the recovery passphrase and produce the envelope.
PBKDF2: Cryptographic function that turns a human-typed passphrase into a binary key suitable for encryption. It slows down brute-force attempts by applying many iterations. ProxMenux uses it with 600 000 iterations and a random salt when encrypting the recovery envelope.

Backup structure

Terms describing what lives inside a backup, regardless of destination.

rootfs / root filesystem: A flat copy of the source host's filesystem, produced by rsync over the default profile plus any custom paths. It is not a whole-disk image: only paths that contain configuration or state Proxmox cannot regenerate on its own are copied.
Manifest (manifest.json): Structured JSON document describing the source host at backup time: hardware, storage, kernel, ProxMenux-installed components and inventory of VMs and LXCs. It is produced by six independent collectors. The restore flow uses it to compare source and target.
Staging directory: Temporary directory where ProxMenux assembles the three blocks (rootfs, metadata and manifest) before packing them and uploading to the destination. It is removed automatically when the backup finishes, even on abort.
Default profile: Curated set of paths that ProxMenux copies by default in every backup. Covers PVE config, network, SSH, kernel, apt, ProxMenux tools and more. It is defined in code and documented on the How it works page.
Custom paths: Extra paths the user adds on top of the default profile. Either persistent (stored in backup-extra-paths.txt) or per-run (picked in Custom mode).

Destinations and storage

Terms tied to where the backup lands — PBS server, local archive or Borg repository — and how PBS organises the data.

PBS repository: Combination of Proxmox Backup Server + datastore + user that receives the backup. Identified by the string user@realm@host:datastore. A single PBS server can host several repositories.
Datastore: Concrete store inside a PBS server where backups and their chunks live. Each datastore sits on a filesystem of the PBS server and has its own permissions and policies.
Chunk / chunk deduplication: PBS splits every backup into variable-size chunks, identifies each chunk by its hash and stores each chunk only once, even if it appears in many different backups. This means successive backups of the same host — or across similar hosts — take very little additional space.
Fingerprint: Cryptographic fingerprint of the PBS server's TLS certificate. It lets the client verify it is talking to the intended server without relying on a public certificate authority. ProxMenux passes it to proxmox-backup-client via the PBS_FINGERPRINT environment variable.
Backup group: Logical container inside PBS under which successive backups of the same asset accumulate. Each new backup shares deduplication with earlier ones in the same group. ProxMenux uses two groups per host when encryption is enabled: one for the host backup and one with a -keyrecovery suffix for the recovery envelope.
Backup ID: Name of the backup group. ProxMenux defaults to hostcfg-HOSTNAME and lets the operator edit it before upload; unsupported characters are stripped automatically.
.pxar: PBS-native archive format for directories. It behaves like a tar optimised for chunk deduplication: rather than storing an opaque file, PBS breaks its contents into reusable chunks.

Execution and scheduling

Terms used by the ProxMenux scheduled-jobs system.

Runner: The run_scheduled_backup.sh script that executes a scheduled backup. It reads the job config, launches the matching backend (Local, PBS or Borg), applies retention on success and sends the configured notifications.
Scheduled job: Persisted configuration of a recurring backup. Holds destination, credentials, encryption, schedule and retention. Lives at /var/lib/proxmenux/backup-jobs/<id>.env.
Attach mode: Scheduled job with no schedule of its own; it fires automatically whenever an existing PVE vzdump task runs. It inherits the schedule and retention from that parent task. Supported for Local and PBS destinations only.
Systemd timer: Standard systemd mechanism that fires a command on a calendar. ProxMenux creates one timer per independent scheduled job; attach-mode jobs use no timer, they run via the PVE script-hook.
Retention (keep-last, keep-daily…): Policy that decides which older backups to keep and which to prune. Defined per job with parameters like keep-last, keep-daily, keep-weekly, keep-monthly. Applied by the runner after each successful backup.

Restore

Terms from the restore flow.

Universal restore: The ProxMenux restore flow does not just extract the filesystem: it reads the manifest to spot differences between source and target, reproduces the system configuration and re-runs the installers for the ProxMenux-managed components. The goal is to reproduce the source host, not merely the archive.
Hydration (cross-kernel): Restore pass that merges the user's own configuration from the source (IOMMU tokens, VFIO device IDs, custom quirks, GRUB keys) on top of the target's fresh boot configuration, without copying the source's kernel-tied files verbatim. Runs when the target kernel is newer than the backup's.
Cross-kernel restore: Restore where the target's kernel differs from (usually is newer than) the source's. Requires the hydration pass to avoid dragging along files incompatible with the target's kernel.
Post-boot installer: Components reinstalled after the first boot of the restored host (NVIDIA drivers, Coral TPU drivers, AMD GPU tools, Intel GPU tools). Each installer runs against the target's kernel, so the restored host does not depend on the source's kernel being present.
Compatibility check: Comparison between the source manifest and the target's state that ProxMenux performs at the start of the restore. It decides which parts are copied verbatim, which need hydration and which are recreated by an installer.
Fresh install: Host just reinstalled from scratch, with no local keyfile. Restoring an encrypted backup requires first recovering the keyfile from the envelope stored on PBS, using the recovery passphrase.

Where next

How it works — where the rootfs, manifest and application inventory fit inside a backup.
Proxmox Backup Server destination — where client-side encryption, keyfile, recovery passphrase and envelope are documented in depth.
Restoring — the restore flow and manifest usage.

Backup & Restore: Previous

Cross-kernel restore

Commands Reference: Next

Overview