mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-08-02 13:56:23 +00:00
update documentation
This commit is contained in:
MacRimi
@@ -50,6 +50,7 @@
|
||||
},
|
||||
"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.",
|
||||
@@ -62,9 +63,11 @@
|
||||
"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.",
|
||||
"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.",
|
||||
"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",
|
||||
|
||||
@@ -0,0 +1,230 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Glossary — Backup & Restore | ProxMenux",
|
||||
"description": "Glossary of terms and definitions for the ProxMenux backup & restore stack: encryption, keyfile, passphrase, recovery envelope, PBS, chunks, rootfs, manifest, runner and cross-kernel hydration.",
|
||||
"ogTitle": "Backup & Restore glossary | ProxMenux",
|
||||
"ogDescription": "Clear definitions for the vocabulary used across the ProxMenux backup & restore documentation.",
|
||||
"twitterTitle": "Backup & Restore glossary | ProxMenux",
|
||||
"twitterDescription": "Passphrase, keyfile, recovery envelope, rootfs, manifest, PBS, chunks — all defined in one place."
|
||||
},
|
||||
"header": {
|
||||
"title": "Glossary",
|
||||
"description": "Terms used across the backup & restore documentation, with their definition.",
|
||||
"section": "Backup & Restore"
|
||||
},
|
||||
"intro": {
|
||||
"body": "Terms are grouped by theme. Every entry gives the term and a short definition."
|
||||
},
|
||||
"groups": [
|
||||
{
|
||||
"title": "Encryption and key recovery",
|
||||
"intro": "Vocabulary for the PBS encryption block. It involves two distinct secrets: a binary keyfile and a written passphrase.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "passphrase-recuperacion",
|
||||
"term": "Recovery passphrase",
|
||||
"def": "Text password the operator picks to protect the <a href=\"#sobre-recuperacion\">recovery envelope</a>. 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. <strong>It is not the passphrase that unlocks the keyfile itself</strong>, and it is never sent to PBS. During a normal backup it never leaves the host."
|
||||
},
|
||||
{
|
||||
"id": "clave-cifrado",
|
||||
"term": "Keyfile (encryption key)",
|
||||
"def": "Binary file that Proxmox Backup Server uses to encrypt the <a href=\"#chunk\">chunks</a> of each backup before uploading them. Without this file, no encrypted backup can be read. ProxMenux stores it at <code>/usr/local/share/proxmenux/pbs-key.conf</code> with mode <code>600</code>. This is the asset that has to be protected; the <a href=\"#sobre-recuperacion\">recovery envelope</a> exists precisely so that this file can be rescued if it is lost."
|
||||
},
|
||||
{
|
||||
"id": "contrasena-keyfile",
|
||||
"term": "Keyfile passphrase (KDF passphrase)",
|
||||
"def": "Optional passphrase that the keyfile itself may carry, distinct from the <a href=\"#passphrase-recuperacion\">recovery passphrase</a>. It only exists when the keyfile was created with <code>--kdf scrypt</code> (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."
|
||||
},
|
||||
{
|
||||
"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."
|
||||
},
|
||||
{
|
||||
"id": "cifrado-cliente",
|
||||
"term": "Client-side encryption",
|
||||
"def": "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 <a href=\"#sobre-recuperacion\">recovery envelope</a> on top."
|
||||
},
|
||||
{
|
||||
"id": "kdf-none",
|
||||
"term": "--kdf none",
|
||||
"def": "Option to <code>proxmox-backup-client key create</code> 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."
|
||||
},
|
||||
{
|
||||
"id": "kdf-scrypt",
|
||||
"term": "--kdf scrypt",
|
||||
"def": "Option to <code>proxmox-backup-client key create</code> that produces a keyfile protected by a <a href=\"#contrasena-keyfile\">keyfile passphrase</a>. 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."
|
||||
},
|
||||
{
|
||||
"id": "aes-256-cbc",
|
||||
"term": "AES-256-CBC",
|
||||
"def": "Standard symmetric cipher. ProxMenux uses it (via <code>openssl enc -aes-256-cbc</code>) to wrap the <a href=\"#clave-cifrado\">keyfile</a> with the <a href=\"#passphrase-recuperacion\">recovery passphrase</a> and produce the <a href=\"#sobre-recuperacion\">envelope</a>."
|
||||
},
|
||||
{
|
||||
"id": "pbkdf2",
|
||||
"term": "PBKDF2",
|
||||
"def": "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."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Backup structure",
|
||||
"intro": "Terms describing what lives inside a backup, regardless of destination.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "rootfs",
|
||||
"term": "rootfs / root filesystem",
|
||||
"def": "A flat copy of the source host's filesystem, produced by <code>rsync</code> over the <a href=\"#perfil-defecto\">default profile</a> plus any <a href=\"#rutas-personalizadas\">custom paths</a>. It is not a whole-disk image: only paths that contain configuration or state Proxmox cannot regenerate on its own are copied."
|
||||
},
|
||||
{
|
||||
"id": "manifiesto",
|
||||
"term": "Manifest (manifest.json)",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "staging",
|
||||
"term": "Staging directory",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "perfil-defecto",
|
||||
"term": "Default profile",
|
||||
"def": "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 <em>How it works</em> page."
|
||||
},
|
||||
{
|
||||
"id": "rutas-personalizadas",
|
||||
"term": "Custom paths",
|
||||
"def": "Extra paths the user adds on top of the <a href=\"#perfil-defecto\">default profile</a>. Either persistent (stored in <code>backup-extra-paths.txt</code>) or per-run (picked in Custom mode)."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Destinations and storage",
|
||||
"intro": "Terms tied to where the backup lands — PBS server, local archive or Borg repository — and how PBS organises the data.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "repositorio-pbs",
|
||||
"term": "PBS repository",
|
||||
"def": "Combination of Proxmox Backup Server + <a href=\"#datastore\">datastore</a> + user that receives the backup. Identified by the string <code>user@realm@host:datastore</code>. A single PBS server can host several repositories."
|
||||
},
|
||||
{
|
||||
"id": "datastore",
|
||||
"term": "Datastore",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "chunk",
|
||||
"term": "Chunk / chunk deduplication",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "fingerprint",
|
||||
"term": "Fingerprint",
|
||||
"def": "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 <code>proxmox-backup-client</code> via the <code>PBS_FINGERPRINT</code> environment variable."
|
||||
},
|
||||
{
|
||||
"id": "grupo-copia",
|
||||
"term": "Backup group",
|
||||
"def": "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 <code>-keyrecovery</code> suffix for the <a href=\"#sobre-recuperacion\">recovery envelope</a>."
|
||||
},
|
||||
{
|
||||
"id": "backup-id",
|
||||
"term": "Backup ID",
|
||||
"def": "Name of the <a href=\"#grupo-copia\">backup group</a>. ProxMenux defaults to <code>hostcfg-HOSTNAME</code> and lets the operator edit it before upload; unsupported characters are stripped automatically."
|
||||
},
|
||||
{
|
||||
"id": "pxar",
|
||||
"term": ".pxar",
|
||||
"def": "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."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Execution and scheduling",
|
||||
"intro": "Terms used by the ProxMenux scheduled-jobs system.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "runner",
|
||||
"term": "Runner",
|
||||
"def": "The <code>run_scheduled_backup.sh</code> 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."
|
||||
},
|
||||
{
|
||||
"id": "trabajo-programado",
|
||||
"term": "Scheduled job",
|
||||
"def": "Persisted configuration of a recurring backup. Holds destination, credentials, encryption, schedule and retention. Lives at <code>/var/lib/proxmenux/backup-jobs/<id>.env</code>."
|
||||
},
|
||||
{
|
||||
"id": "modo-adjunto",
|
||||
"term": "Attach mode",
|
||||
"def": "Scheduled job with no schedule of its own; it fires automatically whenever an existing PVE <code>vzdump</code> task runs. It inherits the schedule and retention from that parent task. Supported for Local and PBS destinations only."
|
||||
},
|
||||
{
|
||||
"id": "timer-systemd",
|
||||
"term": "Systemd timer",
|
||||
"def": "Standard systemd mechanism that fires a command on a calendar. ProxMenux creates one timer per <em>independent</em> scheduled job; <a href=\"#modo-adjunto\">attach-mode</a> jobs use no timer, they run via the PVE script-hook."
|
||||
},
|
||||
{
|
||||
"id": "retencion",
|
||||
"term": "Retention (keep-last, keep-daily…)",
|
||||
"def": "Policy that decides which older backups to keep and which to prune. Defined per job with parameters like <code>keep-last</code>, <code>keep-daily</code>, <code>keep-weekly</code>, <code>keep-monthly</code>. Applied by the runner after each successful backup."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Restore",
|
||||
"intro": "Terms from the restore flow.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "restauracion-universal",
|
||||
"term": "Universal restore",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "hidratacion",
|
||||
"term": "Hydration (cross-kernel)",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "cross-kernel",
|
||||
"term": "Cross-kernel restore",
|
||||
"def": "Restore where the target's kernel differs from (usually is newer than) the source's. Requires the <a href=\"#hidratacion\">hydration</a> pass to avoid dragging along files incompatible with the target's kernel."
|
||||
},
|
||||
{
|
||||
"id": "instalador-postboot",
|
||||
"term": "Post-boot installer",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "compatibility-check",
|
||||
"term": "Compatibility check",
|
||||
"def": "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."
|
||||
},
|
||||
{
|
||||
"id": "equipo-recien-instalado",
|
||||
"term": "Fresh install",
|
||||
"def": "Host just reinstalled from scratch, with no local <a href=\"#clave-cifrado\">keyfile</a>. Restoring an encrypted backup requires first recovering the keyfile from the <a href=\"#sobre-recuperacion\">envelope</a> stored on PBS, using the <a href=\"#passphrase-recuperacion\">recovery passphrase</a>."
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"whereNext": {
|
||||
"heading": "Where next",
|
||||
"items": [
|
||||
{
|
||||
"label": "How it works",
|
||||
"href": "/docs/backup-restore/how-it-works",
|
||||
"tail": " — where the rootfs, manifest and application inventory fit inside a backup."
|
||||
},
|
||||
{
|
||||
"label": "Proxmox Backup Server destination",
|
||||
"href": "/docs/backup-restore/destinations/pbs",
|
||||
"tail": " — where client-side encryption, keyfile, recovery passphrase and envelope are documented in depth."
|
||||
},
|
||||
{
|
||||
"label": "Restoring",
|
||||
"href": "/docs/backup-restore/restoring",
|
||||
"tail": " — the restore flow and manifest usage."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -24,6 +24,10 @@
|
||||
"title": "Attach mode — recommended when a PVE vzdump task already exists",
|
||||
"body": "When a PVE vzdump backup task is already configured for the VMs and LXCs on this node, attaching the host backup to that task guarantees the host configuration is captured in the <strong>same window</strong> as the guests. On restore, the guest configs come from the host backup (they live under <code>/etc/pve</code>), and the guest disks come from the vzdump backup taken alongside — both sets are consistent with each other, so a full-node recovery can reproduce the host and re-attach every guest without version drift."
|
||||
},
|
||||
"frequencyBadge": {
|
||||
"title": "Recommended frequency",
|
||||
"body": "To maximise compatibility between a host backup and its future restore, run host backups frequently. The closer the backup is to the current state of the host, the less configuration, package and component drift the restore has to reconcile."
|
||||
},
|
||||
"modes": {
|
||||
"heading": "The two modes",
|
||||
"rows": [
|
||||
|
||||
Reference in New Issue
Block a user