ProxMenux/web/messages/en/docs/backup-restore/destinations/pbs.json

{
  "meta": {
    "title": "Proxmox Backup Server destination — repository, encryption, recovery | ProxMenux",
    "description": "The PBS destination writes ProxMenux host backups as PBS backups. Documents repository auto-discovery from /etc/pve/storage.cfg, manual PBS configuration, the .pxar upload command, the client-side keyfile encryption model, the recovery passphrase escrow blob, and the fresh-install keyfile recovery from PBS.",
    "ogTitle": "ProxMenux Backup — Proxmox Backup Server destination",
    "ogDescription": "How ProxMenux writes host backups to Proxmox Backup Server with client-side keyfile encryption and recovery escrow.",
    "twitterTitle": "PBS backup destination | ProxMenux",
    "twitterDescription": "Proxmox Backup Server destination with keyfile encryption and recovery passphrase escrow."
  },
  "header": {
    "title": "Proxmox Backup Server",
    "description": "The PBS destination uploads the staging root as a single .pxar backup to a Proxmox Backup Server datastore, with optional client-side keyfile encryption and an automatic recovery passphrase escrow for fresh-install disaster recovery.",
    "section": "Backup & Restore"
  },
  "recommendedBadge": "Recommended destination",
  "aboutPbs": {
    "heading": "What Proxmox Backup Server is",
    "body": "Proxmox Backup Server (PBS) is Proxmox's own backup server product, developed and maintained by the same team that authors Proxmox VE. It is a dedicated backup server designed to receive backups from Proxmox VE hosts (VMs, LXCs and — via <code>proxmox-backup-client</code> — arbitrary host directories) with chunk-based deduplication, client-side encryption, and retention policies applied server-side. ProxMenux uses PBS as one of the three destinations for host backups; every PBS-specific mechanism described on this page (backup groups, <code>.pxar</code> archives, <code>--backup-id</code>, keyfile encryption) is standard PBS behaviour."
  },
  "intro": {
    "title": "One backup per run, chunk-level dedup",
    "body": "A PBS backup produces a single backup entry in the datastore, grouped under the backup ID <code>host/hostcfg-HOSTNAME/BACKUP-TIME</code>. The payload is a <code>.pxar</code> archive containing the same three-block layout described in <em>How it works</em>. PBS deduplicates at the chunk level across all backups in the datastore, so subsequent backups of the same host transfer and store only the chunks that changed. Retention is applied by ProxMenux itself for scheduled jobs — <code>run_scheduled_backup.sh</code> runs <code>proxmox-backup-client prune</code> with <code>--keep-last</code> / <code>--keep-daily</code> / <code>--keep-weekly</code> after each successful run using the values configured on the job."
  },
  "repoSelection": {
    "heading": "Repository selection",
    "intro": "ProxMenux discovers PBS repositories from two sources on every backup. The operator picks one from a unified menu; the choice determines <code>HB_PBS_REPOSITORY</code>, <code>HB_PBS_SECRET</code> and <code>HB_PBS_FINGERPRINT</code> for the run.",
    "sourceRows": [
      {
        "source": "Proxmox storage.cfg (auto-discovered)",
        "path": "/etc/pve/storage.cfg + /etc/pve/priv/storage/NAME.pw",
        "content": "Any <code>pbs:</code> stanza in Proxmox's own storage config is picked up automatically. Server, datastore, username and fingerprint come from the stanza. The password is read from Proxmox's own credentials directory. No re-entry needed on the ProxMenux side — the repository is available as soon as it is configured in Proxmox."
      },
      {
        "source": "ProxMenux manual config",
        "path": "/usr/local/share/proxmenux/pbs-manual-configs.txt + pbs-pass-NAME.txt + pbs-fingerprint-NAME.txt",
        "content": "Added from <em>Configure backup destinations → PBS destinations → Add PBS</em>. Prompts for a name, username (<code>root@pam</code> or <code>user@pbs!token</code>), host or IP, datastore and password. The password re-prompts on empty input — an empty save would otherwise persist silently and every subsequent backup would fail with an opaque authentication error. This path is used when the target PBS is not registered as Proxmox storage."
      }
    ],
    "menuTitle": "Selection menu",
    "menuBody": "Both sources are shown in a single menu, each row tagged with its origin (<code>[proxmox]</code> or <code>[manual]</code>). Entries whose password could not be resolved are tagged with a <code>⚠ no password</code> warning — selecting one triggers a password re-entry before the backup starts. The fingerprint is passed to <code>proxmox-backup-client</code> via the <code>PBS_FINGERPRINT</code> environment variable; when absent, the client asks the operator to accept the server certificate interactively on the first backup."
  },
  "backupCommand": {
    "heading": "The backup command",
    "intro": "The upload is a single invocation of <code>proxmox-backup-client backup</code>. ProxMenux runs it inside an <code>env</code> wrapper so credentials never appear in the process argument list.",
    "cmd": "env \\\n    PBS_PASSWORD=\"$HB_PBS_SECRET\" \\\n    PBS_ENCRYPTION_PASSWORD=\"$HB_PBS_ENC_PASS\" \\\n    PBS_FINGERPRINT=\"$HB_PBS_FINGERPRINT\" \\\n    proxmox-backup-client backup \\\n        hostcfg.pxar:$staging_root \\\n        --repository USER@REALM@HOST:DATASTORE \\\n        --backup-type host \\\n        --backup-id  hostcfg-HOSTNAME \\\n        --backup-time BACKUP-EPOCH \\\n        [--keyfile /usr/local/share/proxmenux/pbs-key.conf]",
    "backupIdTitle": "Backup ID naming",
    "backupIdBody": "The default backup ID is <code>hostcfg-HOSTNAME</code>. The operator is asked to confirm or edit it before the upload; any characters outside <code>[A-Za-z0-9_-]</code> are stripped and trailing dashes are trimmed. Reusing the same ID across runs is intentional — PBS treats the ID as a <em>group</em>, and every subsequent backup appears as a new backup inside that group, sharing dedup with prior runs.",
    "pxarTitle": "Why the source is the full staging root",
    "pxarBody": "The <code>.pxar</code> source is the entire <code>staging_root</code> — <code>rootfs/</code>, <code>metadata/</code> and <code>manifest.json</code> together. Earlier versions passed <code>$staging_root/rootfs</code> as the source; that left <code>metadata/</code> out of the archive and the restore's compatibility check had nothing to read, degrading to cross-host warnings even on same-host restores. Old backups created with the rootfs-only source still restore correctly via <code>_rs_check_layout</code>'s case-3 branch, which wraps a flat <code>etc/var/root/usr</code> tree back into a <code>rootfs/</code> hierarchy."
  },
  "encryption": {
    "heading": "Client-side encryption",
    "intro": "PBS client-side keyfile encryption encrypts chunks on the source host before upload. ProxMenux enables the feature with one added constraint: a recovery passphrase is mandatory when encryption is enabled. The passphrase does not protect the local keyfile; it protects the escrow copy of the keyfile that ProxMenux uploads to PBS for disaster recovery.",
    "keyfileTitle": "Keyfile",
    "keyfileBody": "The encryption prompt is a two-step yes/no. Step one asks whether to encrypt the backup: <em>No</em> continues without encryption; <em>Yes</em> moves to step two. Step two depends on whether a keyfile is already installed at <code>/usr/local/share/proxmenux/pbs-key.conf</code>. If it is, the installed keyfile is reused silently and the backup proceeds. If it is not, a two-option menu asks how to set one up. <em>Generate a new keyfile</em> runs <code>proxmox-backup-client key create --kdf none</code> — the resulting keyfile has no passphrase, so the scheduled runner can use it under systemd without any interactive prompt. <em>Import an existing keyfile</em> takes a path the operator supplies and copies it into place with <code>chmod 600</code>; ProxMenux does not inspect the contents (any keyfile the operator accepts as valid on their PBS is accepted here, including scrypt-encoded keyfiles that could not be validated non-interactively). When importing, the flow also asks for the keyfile's own passphrase — the one that <code>proxmox-backup-client key create --kdf scrypt</code> asked for at creation. That passphrase is persisted at <code>/usr/local/share/proxmenux/pbs-key.pass</code> (chmod 600) and reused by every encrypted job on this host as <code>PBS_ENCRYPTION_PASSWORD</code>. Leaving it blank means the keyfile is <code>--kdf none</code> (no passphrase). Both branches run only after the recovery passphrase has been confirmed — cancelling any dialog before that point leaves the disk unchanged.",
    "modesTitle": "Per-host or shared keyfile",
    "modesIntro": "Both operating models are supported and neither is enforced — the choice belongs to the operator based on how their fleet is organised.",
    "modesPerHostTitle": "Per-host keyfile (default)",
    "modesPerHostBody": "Each host generates its own keyfile the first time it enables PBS encryption. Isolation is maximum: compromising the keyfile of one host does not expose the backups of any other. Each host has its own paired recovery blob on PBS, restorable with the recovery passphrase of that host. Recommended for production fleets and for environments where hosts have different owners or compliance boundaries.",
    "modesSharedTitle": "Shared keyfile (import on every host)",
    "modesSharedBody": "One master keyfile generated once and installed on every host via the <em>Import</em> option. Management is simpler: a single secret to safeguard, a single recovery blob works for every host, and any host can decrypt the archives of any other (useful for consolidation, cross-host restore drills, or centralised backup verification). The trade-off is that a leak of the shared keyfile exposes every host at once. Recommended for homelabs and for fleets where all hosts have the same owner and trust boundary.",
    "recoveryTitle": "Recovery passphrase and escrow blob",
    "recoveryBody": "The recovery passphrase is asked BEFORE any keyfile is written to disk. ProxMenux prompts twice with match validation; then, only if the operator confirms, the keyfile is created (or imported) and <code>openssl</code> produces <code>pbs-key.recovery.enc</code> — the keyfile encrypted with the passphrase. A copy is written to <code>/root/pbs-key.recovery-HOSTNAME-YYYYMMDD.enc</code> for offsite storage. Cancelling the passphrase dialog leaves the disk untouched — no keyfile is created and no cleanup is needed.",
    "blobUploadTitle": "Paired backup group on PBS",
    "blobUploadBody1": "After a PBS backup that used the keyfile, the escrow blob is uploaded as a second backup group: <code>host/hostcfg-HOSTNAME-keyrecovery/BACKUP-TIME</code>. The shared <code>hostcfg-HOSTNAME</code> prefix places both groups adjacent in the PBS UI; the <code>-keyrecovery</code> suffix labels the relationship. The upload runs without <code>--keyfile</code> (the blob is already passphrase-protected by openssl) and only when the current backup used the keyfile.",
    "blobUploadConstraintTitle": "Why two groups",
    "blobUploadConstraintBody": "<code>--keyfile</code> is a per-invocation flag in <code>proxmox-backup-client backup</code>: all archives in a single invocation are encrypted with the keyfile or none are. <code>hostcfg.pxar</code> requires encryption; <code>keyrecovery.conf</code> cannot be encrypted with the same keyfile (fresh-install recovery would then require the keyfile it is meant to recover). Two invocations, two backup IDs.",
    "blobUploadImageAlt": "PBS UI showing the hostcfg-HOSTNAME and hostcfg-HOSTNAME-keyrecovery backup groups adjacent in the datastore listing.",
    "blobUploadImageCaption": "PBS UI — the paired backup groups. The main group holds the host backups; the -keyrecovery group holds the escrow blob.",
    "recoverTitle": "Fresh-install recovery",
    "recoverBody": "On a host without a local keyfile, the restore flow calls <code>hb_pbs_try_keyfile_recovery</code>. The function lists keyrecovery groups on the configured PBS, downloads the newest and prompts for the passphrase. On success, <code>pbs-key.conf</code> is written to the ProxMenux state directory and the encrypted backup can be restored. Without both the keyfile and the passphrase, the encrypted backup is not recoverable."
  },
  "restoreAccess": {
    "heading": "Retrieval on the restore side",
    "body": "The restore flow discovers ProxMenux host backups on PBS by listing backup groups under the configured repository and filtering by backup ID pattern. The Monitor's Backups tab renders the same list. Selecting a backup triggers <code>proxmox-backup-client restore</code> with the same repository + password + fingerprint (and <code>--keyfile</code> when the backup was encrypted), extracting the <code>.pxar</code> into a staging directory that <code>_rs_check_layout</code> then feeds to the standard restore pipeline. For manual retrieval outside ProxMenux, the same command extracts the archive to any path — the resulting tree can be inspected or fed to a hand-driven restore."
  },
  "references": {
    "heading": "References",
    "intro": "Official Proxmox Backup Server documentation for the components ProxMenux relies on.",
    "items": [
      {
        "label": "Proxmox Backup Server documentation",
        "href": "https://pbs.proxmox.com/docs/",
        "tail": " — main entry point covering installation, administration, storage, users and roles."
      },
      {
        "label": "proxmox-backup-client",
        "href": "https://pbs.proxmox.com/docs/backup-client.html",
        "tail": " — the command-line tool ProxMenux invokes for every backup and restore. Covers backup IDs, backup types, archives, repository syntax and environment variables."
      },
      {
        "label": "Client-side encryption",
        "href": "https://pbs.proxmox.com/docs/backup-client.html#encryption",
        "tail": " — keyfile creation, --kdf modes, the encryption model that ProxMenux extends with a passphrase escrow."
      },
      {
        "label": "Datastore management",
        "href": "https://pbs.proxmox.com/docs/storage.html",
        "tail": " — creating and managing the datastores that receive host backups, including chunk-store layout and permissions."
      },
      {
        "label": "Pruning and garbage collection",
        "href": "https://pbs.proxmox.com/docs/maintenance.html#pruning",
        "tail": " — the retention model behind --keep-last / --keep-daily / --keep-weekly that ProxMenux applies per scheduled job, plus how PBS reclaims chunks after prune."
      }
    ]
  }
}