Mirrors/ProxMenux
1
0
Fork 0
mirror of https://github.com/MacRimi/ProxMenux.git synced 2026-08-02 13:56:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
MacRimi
2026-07-08 12:46:36 +02:00
parent 341681a3dc
commit a2a0fb4705
4 changed files with 29 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
web/messages/en/docs/backup-restore/destinations/pbs.json
+14 -14
View File
@@ -1,7 +1,7 @@
{
"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.",
"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 with optional passphrase-wrapped escrow, and the multi-source keyfile recovery on a fresh host.",
"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",
@@ -9,7 +9,7 @@
},
"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.",
"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 optional passphrase-wrapped keyfile escrow uploaded next to each backup.",
"section": "Backup & Restore"
},
"recommendedBadge": "Recommended destination",
@@ -50,28 +50,28 @@
},
"encryption": {
"heading": "Client-side encryption",
"glossaryHint": "This section uses the terms <em>keyfile</em>, <em>passphrase</em> and <em>recovery envelope</em>. If it ever gets hard to keep them apart, the <glosarioLink>glossary</glosarioLink> summarises the differences in one sentence per term.",
"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.",
"glossaryHint": "This section uses the terms <em>keyfile</em>, <em>passphrase</em> and <em>recovery envelope</em>. The <glosarioLink>glossary</glosarioLink> summarises the differences in one sentence per term.",
"intro": "PBS client-side keyfile encryption encrypts chunks on the source host before upload. In ProxMenux encryption is optional; when enabled, uploading a passphrase-wrapped copy of the keyfile to PBS as a recovery escrow is also optional. The keyfile itself always lives at one canonical path on the host — <code>/usr/local/share/proxmenux/pbs-key.conf</code> — and is reused silently by every subsequent encrypted backup.",
"keyfileTitle": "Setting up the keyfile",
"keyfileBody": "The encryption prompt runs at the first encrypted backup on the host. 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 — subsequent backups never re-ask. 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>. <em>Use an existing keyfile</em> auto-detects a PVE-managed keyfile: when the selected PBS repository is registered in Proxmox with an encryption key at <code>/etc/pve/priv/storage/&lt;NAME&gt;.enc</code>, that file is copied to the ProxMenux canonical path silently and the flow continues. When no PVE-managed keyfile matches the repository, an input prompts for the absolute path where the operator has already placed the keyfile on this host. Either way, the file lands at the canonical path with <code>chmod 600</code>.",
"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.",
"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. 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.",
"modesSharedBody": "One master keyfile generated once and installed on every host via the <em>Use an existing keyfile</em> option. Management is simpler: a single secret to safeguard, 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": "Upload key to PBS — the yes/no question",
"recoveryBody": "Right after the keyfile is chosen, ProxMenux asks a single question — <em>Upload key to PBS?</em> — with two answers. The default is <em>No, keep local only</em>: the keyfile stays only at the canonical local path and the operator handles the offsite copy themselves (the Monitor's <em>Download keyfile</em> button provides one on demand). Choosing <em>Yes, upload</em> prompts for a recovery passphrase — twice, with match validation — and ProxMenux wraps the keyfile with that passphrase using AES-256-CBC and PBKDF2 (600 000 iterations, random salt) to produce <code>pbs-key.recovery.enc</code>. Every subsequent encrypted backup uploads that envelope to PBS as a paired backup group. Neither the passphrase nor a plaintext copy of the keyfile ever leaves the host.",
"blobUploadTitle": "Paired backup group on PBS",
"blobUploadBody1": "After a backup that used the keyfile, ProxMenux uploads the recovery envelope to PBS as a second, paired backup group with the same name as the host group but ending in <code>-keyrecovery</code>. The two groups sit next to each other in the datastore listing — one for host backups, one for recovery envelopes. <strong>The envelope never leaves the host in plaintext</strong>: before upload, ProxMenux encrypts it on the host itself with AES-256-CBC, using a key derived from the recovery passphrase via PBKDF2 with 600 000 iterations and a random salt (<code>openssl enc -aes-256-cbc -pbkdf2 -iter 600000 -salt</code>). PBS receives only the already-encrypted envelope, and the upload happens only when the main backup was encrypted.",
"blobUploadBody1": "When the escrow mode is <em>Yes, upload</em>, ProxMenux uploads the recovery envelope to PBS after every encrypted backup as a second, paired backup group with the same name as the host group but ending in <code>-keyrecovery</code>. The two groups sit next to each other in the datastore listing — one for host backups, one for recovery envelopes. <strong>The envelope never leaves the host in plaintext</strong>: encryption happens on the host itself with AES-256-CBC and PBKDF2 before any bytes go on the wire (<code>openssl enc -aes-256-cbc -pbkdf2 -iter 600000 -salt</code>). PBS receives only the already-encrypted envelope.",
"envelopeSecurityTitle": "Is uploading the keyrecovery file to PBS a security risk?",
"envelopeSecurityBody": "The keyrecovery file is encrypted in transit and at rest. The recovery passphrase never leaves the host: encryption happens locally before the upload, and PBS only ever sees the already-encrypted result. A PBS administrator — or anyone with access to the datastore — can download the keyrecovery file, but without the recovery passphrase they cannot read the keyfile inside: it is opaque ciphertext. Reconstructing the keyfile requires both pieces at once, the keyrecovery file and the passphrase, and only the operator holds both.",
"blobUploadConstraintTitle": "Why two groups instead of a single encrypted one",
"blobUploadConstraintBody": "A single <code>proxmox-backup-client backup</code> invocation encrypts every one of its archives with the same keyfile, or none at all — there is no in-between. The host backup has to be encrypted with the host keyfile, but the recovery envelope cannot ride along in that same upload, because it would end up encrypted with the very keyfile it contains: on a freshly reinstalled host there would be no way to open it (you would need the keyfile to decrypt the keyfile). That is why the two artefacts are uploaded independently and appear as two separate groups: the host backup is encrypted by PBS with the keyfile, and the recovery envelope is encrypted by ProxMenux with the passphrase before upload. Two different encryption layers protecting two different assets.",
"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."
"blobUploadImageCaption": "PBS UI — the paired backup groups. The main group holds the host backups; the -keyrecovery group holds the passphrase-wrapped keyfile.",
"recoverTitle": "Recovery on a fresh host",
"recoverBody": "When the local keyfile is missing at the canonical path — on a freshly reinstalled host, or after an explicit removal — the restore flow tries three sources in order and stops at the first one that produces a usable keyfile. First, when the selected PBS repository has a matching PVE-managed keyfile at <code>/etc/pve/priv/storage/&lt;NAME&gt;.enc</code>, that file is copied to the canonical path silently. Second, when a <code>-keyrecovery</code> group is available on PBS, the newest snapshot is downloaded and the operator is asked for the recovery passphrase to decrypt it. Third, when neither of the above works or the operator declines them, an input prompts for the absolute path where the keyfile lives on this host and copies it to the canonical path. The Monitor exposes the same import flow inline in the backup detail modal — an amber panel appears at the top of the modal when Restore, Download or View contents would need a keyfile that is not installed."
},
"restoreAccess": {
"heading": "Retrieval on the restore side",
web/messages/en/docs/backup-restore/glossary.json
+1 -1
View File
@@ -38,7 +38,7 @@
{
"id": "sobre-recuperacion",
"term": "Recovery envelope",
"def": "The <a href=\"#clave-cifrado\">keyfile</a> wrapped in an extra layer: it is encrypted with the <a href=\"#passphrase-recuperacion\">recovery passphrase</a> using <a href=\"#aes-256-cbc\">AES-256-CBC</a> and <a href=\"#pbkdf2\">PBKDF2</a> before it ever leaves the host. It is what gets uploaded to PBS as the <code>-keyrecovery</code> group and what is also written to <code>/root/pbs-key.recovery-HOSTNAME-DATE.enc</code> as an offsite backup. Without the passphrase, the envelope is opaque: downloading it from PBS does not reveal the keyfile."
"def": "The <a href=\"#clave-cifrado\">keyfile</a> wrapped in an extra layer: it is encrypted with the <a href=\"#passphrase-recuperacion\">recovery passphrase</a> using <a href=\"#aes-256-cbc\">AES-256-CBC</a> and <a href=\"#pbkdf2\">PBKDF2</a> before it ever leaves the host. It is what gets uploaded to PBS as the <code>-keyrecovery</code> group. Without the passphrase, the envelope is opaque: downloading it from PBS does not reveal the keyfile."
},
{
"id": "cifrado-cliente",