- {t.rich("encryption.keyfileBody", { code })} + {t.rich("encryption.keyfileBody", { code, em })} +
+ ++ {t.rich("encryption.modesIntro", { em })} +
+ ++ {t.rich("encryption.modesPerHostBody", { code, em })} +
+ ++ {t.rich("encryption.modesSharedBody", { code, em })}
+ {t.rich("liveProgress.body", { code })} +
+ +| Card element | +Detail | +
|---|---|
| {row.name} | +{t.rich(`liveProgress.fields.${idx}.detail`, { code, em })} | +
+ {t.rich("liveProgress.dismissBody", { code, em })} +
+ +proxmox-backup-client key create --kdf none generates the keyfile at /usr/local/share/proxmenux/pbs-key.conf (chmod 600). Subsequent backups reuse it after a single confirmation dialog. If key creation fails, the backup is cancelled and the tool's error output is shown in a dialog.",
+ "keyfileBody": "The encryption prompt is a two-step yes/no. Step one asks whether to encrypt the backup: No continues without encryption; Yes moves to step two. Step two depends on whether a keyfile is already installed at /usr/local/share/proxmenux/pbs-key.conf. 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: Generate a new keyfile runs proxmox-backup-client key create --kdf none, or Import an existing keyfile takes a path the operator supplies, validates it with proxmox-backup-client key info and installs it at the canonical path. 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 Import 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": "After the keyfile is created, ProxMenux prompts twice for a recovery passphrase (with match validation) and runs openssl to produce pbs-key.recovery.enc — the keyfile encrypted with the passphrase. A copy is written to /root/pbs-key.recovery-HOSTNAME-YYYYMMDD.enc for offsite storage. Cancelling the passphrase dialog wipes the freshly-created keyfile.",
+ "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 openssl produces pbs-key.recovery.enc — the keyfile encrypted with the passphrase. A copy is written to /root/pbs-key.recovery-HOSTNAME-YYYYMMDD.enc 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: host/hostcfg-HOSTNAME-keyrecovery/BACKUP-TIME. The shared hostcfg-HOSTNAME prefix places both groups adjacent in the PBS UI; the -keyrecovery suffix labels the relationship. The upload runs without --keyfile (the blob is already passphrase-protected by openssl) and only when the current backup used the keyfile.",
"blobUploadConstraintTitle": "Why two groups",
diff --git a/web/messages/en/docs/backup-restore/how-it-works.json b/web/messages/en/docs/backup-restore/how-it-works.json
index 1064896e..dee5eb9b 100644
--- a/web/messages/en/docs/backup-restore/how-it-works.json
+++ b/web/messages/en/docs/backup-restore/how-it-works.json
@@ -193,7 +193,7 @@
]
},
"whyItWorks": {
- "heading": "Why the three-payload split is the right one",
+ "heading": "Why the three-payload split is the one used",
"body": "The split is not a filesystem decision — it is a lifecycle decision. Filesystem content moves with rsync: fast, transparent, atomic per file. Configuration state that a restore has to interpret before touching the target moves as structured JSON: readable independently, versionable through a schema, machine-diffable against the target's own state. Software that has to be re-installed against the target's environment moves as an inventory: names and versions only, letting the target's package manager and ProxMenux's own installers decide the actual binaries. Each payload optimises for what it needs to do, and the three combine into a restore that is atomic in intent but fault-tolerant in practice: a corrupt manifest still leaves the rootfs restorable, a missing package still leaves the components installable, a component installer failing on one entry does not stop the next."
}
}
diff --git a/web/messages/en/docs/backup-restore/restoring.json b/web/messages/en/docs/backup-restore/restoring.json
index f3630b3a..76621a6e 100644
--- a/web/messages/en/docs/backup-restore/restoring.json
+++ b/web/messages/en/docs/backup-restore/restoring.json
@@ -20,19 +20,40 @@
"heading": "Three actions on a backup",
"intro": "Selecting a backup from the list opens a menu with three actions.",
"actionRows": [
- { "action": "View", "detail": "Opens a read-only view of the archive: manifest.json contents (source hostname, PVE version, kernel, hardware, installed components), the list of paths inside rootfs/, and a diff of what would change on the current host if the backup were applied." },
- { "action": "Download", "detail": "Exports the archive as a portable .tar.zst file (tar compressed with zstd). It can be extracted on any Linux system with tar --zstd -xf FILE.tar.zst, or on macOS/Windows with any tool that supports zstd (7-Zip, PeaZip, Keka…). The extracted tree contains manifest.json, metadata/ and rootfs/ — exactly the same layout the restore consumes. Useful for offline inspection or for restoring on a host without access to the original destination (PBS, Borg)." },
- { "action": "Restore", "detail": "The write path. Extracts the archive into a staging directory, runs the compatibility check, and presents the mode picker (Full or Custom)." }
+ {
+ "action": "View",
+ "detail": "Opens a read-only view of the archive: manifest.json contents (source hostname, PVE version, kernel, hardware, installed components), the list of paths inside rootfs/, and a diff of what would change on the current host if the backup were applied."
+ },
+ {
+ "action": "Download",
+ "detail": "Exports the archive as a portable .tar.zst file (tar compressed with zstd). It can be extracted on any Linux system with tar --zstd -xf FILE.tar.zst, or on macOS/Windows with any tool that supports zstd (7-Zip, PeaZip, Keka…). The extracted tree contains manifest.json, metadata/ and rootfs/ — exactly the same layout the restore consumes. Useful for offline inspection or for restoring on a host without access to the original destination (PBS, Borg)."
+ },
+ {
+ "action": "Restore",
+ "detail": "The write path. Extracts the archive into a staging directory, runs the compatibility check, and presents the mode picker (Full or Custom)."
+ }
]
},
"compatibilityCheck": {
"heading": "The compatibility check",
"intro": "Before any file is written, hb_compat_check compares the state described in the manifest against the target host. The check runs read-only and produces four independent outputs that drive the rest of the restore.",
"outputRows": [
- { "output": "Direction flag", "detail": "HB_COMPAT_KERNEL_DIRECTION — one of same, bk_newer or bk_older. Compares the backup's major kernel version against the target's. Drives the cross-kernel safe-subset filter (only fires on bk_older) and the hydration pass documented on the cross-kernel page." },
- { "output": "Skip-paths list", "detail": "RS_SKIP_PATHS — every path the restore must NOT apply. Populated by two mechanisms: hardware drift (missing NIC, missing storage ID, foreign ZFS pool) and — when the direction is bk_older — the cross-kernel unsafe-paths list." },
- { "output": "NIC remap plan", "detail": "When a NIC on the target has the same MAC as one on the source but a different name (typical after a motherboard swap), the compatibility check registers a rename plan (HB_NIC_REMAP) that will rewrite /etc/network/interfaces during the restore." },
- { "output": "Rollback plan", "detail": "Computed by compute_rollback_plan.sh. Lists VMs, LXCs and components present on the target but not in the backup. The operator opts in during the confirmation dialog to have these removed as part of the restore, so the target ends up matching the backup exactly." }
+ {
+ "output": "Direction flag",
+ "detail": "HB_COMPAT_KERNEL_DIRECTION — one of same, bk_newer or bk_older. Compares the backup's major kernel version against the target's. Drives the cross-kernel safe-subset filter (only fires on bk_older) and the hydration pass documented on the cross-kernel page."
+ },
+ {
+ "output": "Skip-paths list",
+ "detail": "RS_SKIP_PATHS — every path the restore must NOT apply. Populated by two mechanisms: hardware drift (missing NIC, missing storage ID, foreign ZFS pool) and — when the direction is bk_older — the cross-kernel unsafe-paths list."
+ },
+ {
+ "output": "NIC remap plan",
+ "detail": "When a NIC on the target has the same MAC as one on the source but a different name (typical after a motherboard swap), the compatibility check registers a rename plan (HB_NIC_REMAP) that will rewrite /etc/network/interfaces during the restore."
+ },
+ {
+ "output": "Rollback plan",
+ "detail": "Computed by compute_rollback_plan.sh. Lists VMs, LXCs and components present on the target but not in the backup. The operator opts in during the confirmation dialog to have these removed as part of the restore, so the target ends up matching the backup exactly."
+ }
],
"reportBody": "The check also emits a structured report (HB_COMPAT_RESULTS) categorised as PASS / INFO / WARN / FAIL. WARN and FAIL entries surface in the pre-restore panel; the restore refuses to proceed only when a FAIL is present that the operator cannot resolve by clicking Continue."
},
@@ -40,17 +61,32 @@
"heading": "Full restore vs Custom restore",
"intro": "Once the compatibility check is complete, the restore mode menu appears. The choice determines what is applied, not how — both modes share the same underlying pipeline.",
"modeRows": [
- { "mode": "Full restore", "detail": "Applies every path in the archive that survives the drift and cross-kernel filters. Also runs the package install and the component auto-reinstall pass. This is the default and the recommended choice — the goal is to reproduce the source, not pick pieces." },
- { "mode": "Custom restore", "detail": "Opens a checklist showing every path the archive carries. The operator ticks a subset. Paths blocked by the cross-kernel filter appear greyed out and cannot be selected. Package install and component auto-reinstall are skipped by default in Custom mode — the operator is signalling that they want partial application, not a full reproduction." }
+ {
+ "mode": "Full restore",
+ "detail": "Applies every path in the archive that survives the drift and cross-kernel filters. Also runs the package install and the component auto-reinstall pass. This is the default and the recommended choice — the goal is to reproduce the source, not pick pieces."
+ },
+ {
+ "mode": "Custom restore",
+ "detail": "Opens a checklist showing every path the archive carries. The operator ticks a subset. Paths blocked by the cross-kernel filter appear greyed out and cannot be selected. Package install and component auto-reinstall are skipped by default in Custom mode — the operator is signalling that they want partial application, not a full reproduction."
+ }
]
},
"pathClassification": {
"heading": "How paths are classified",
"intro": "Every path selected for the restore is classified by hb_classify_path into one of three categories. The category determines when the path is applied to the system and why.",
"rows": [
- { "class": "hot", "detail": "Paths applied immediately to the running system. The service that consumes them picks up the change on its own or at the next reload — no reboot required. These are the bulk of a backup: /etc/ssh, /etc/apt, /etc/cron.*, /root, /usr/local/bin, general service configuration files, etc." },
- { "class": "reboot", "detail": "Paths applied immediately as well, but whose actual effect only kicks in on the next boot: the kernel only reads /etc/default/grub when the bootloader starts, /etc/fstab when filesystems are mounted at boot, /etc/modules when modules are loaded, etc. The file is in place the moment it is applied but the system has to reboot to consume it. Examples: /etc/default/grub, /etc/kernel, /etc/modules, /etc/fstab, /etc/zfs, /etc/initramfs-tools." },
- { "class": "dangerous", "detail": "Paths that are NOT applied on the running system — a live write could corrupt state or drop the active connection. These are staged in the pending set and written by the post-boot dispatcher after the reboot, when the cluster is up but the system is not yet fully in use. Examples: /etc/pve (pmxcfs is a live FUSE mount; writing directly to it bypasses it), /var/lib/pve-cluster (live cluster data), /etc/network (could reconfigure the very interface the user is connected on over SSH and drop the session)." }
+ {
+ "class": "hot",
+ "detail": "Paths applied immediately to the running system. The service that consumes them picks up the change on its own or at the next reload — no reboot required. These are the bulk of a backup: /etc/ssh, /etc/apt, /etc/cron.*, /root, /usr/local/bin, general service configuration files, etc."
+ },
+ {
+ "class": "reboot",
+ "detail": "Paths applied immediately as well, but whose actual effect only kicks in on the next boot: the kernel only reads /etc/default/grub when the bootloader starts, /etc/fstab when filesystems are mounted at boot, /etc/modules when modules are loaded, etc. The file is in place the moment it is applied but the system has to reboot to consume it. Examples: /etc/default/grub, /etc/kernel, /etc/modules, /etc/fstab, /etc/zfs, /etc/initramfs-tools."
+ },
+ {
+ "class": "dangerous",
+ "detail": "Paths that are NOT applied on the running system — a live write could corrupt state or drop the active connection. These are staged in the pending set and written by the post-boot dispatcher after the reboot, when the cluster is up but the system is not yet fully in use. Examples: /etc/pve (pmxcfs is a live FUSE mount; writing directly to it bypasses it), /var/lib/pve-cluster (live cluster data), /etc/network (could reconfigure the very interface the user is connected on over SSH and drop the session)."
+ }
]
},
"fullFlow": {
@@ -62,10 +98,22 @@
"heading": "The pending-restore machinery",
"intro": "Paths classified as reboot or dangerous, and hydration writes, are staged for the next boot instead of being applied live. This is done through a small, self-contained set of files under /var/lib/proxmenux/pending-restore/:",
"rows": [
- { "file": "apply-on-boot.list", "content": "One relative path per line — the exact set of paths apply_pending_restore.sh will apply from the staged rootfs. Reading this file tells the operator exactly what will change on the next boot." },
- { "file": "plan.env", "content": "Environment variables sourced by the on-boot script: restore ID, compatibility flags (HB_COMPAT_CROSS_VERSION, HB_COMPAT_KERNEL_DIRECTION, HB_HYDRATION_APPLIED), rollback opt-in flag, cluster options." },
- { "file": "rs-skip-paths.txt", "content": "The final RS_SKIP_PATHS list, persisted so apply_pending_restore.sh applies the same exclusions after reboot that were computed during the interactive step. Prevents drift-affected or cross-kernel-unsafe paths from being restored at boot time." },
- { "file": "rootfs/", "content": "The staged files themselves — the exact bytes that will be laid down. Kept on the same filesystem as / so the on-boot rsync is fast and does not depend on external storage still being reachable at boot." }
+ {
+ "file": "apply-on-boot.list",
+ "content": "One relative path per line — the exact set of paths apply_pending_restore.sh will apply from the staged rootfs. Reading this file tells the operator exactly what will change on the next boot."
+ },
+ {
+ "file": "plan.env",
+ "content": "Environment variables sourced by the on-boot script: restore ID, compatibility flags (HB_COMPAT_CROSS_VERSION, HB_COMPAT_KERNEL_DIRECTION, HB_HYDRATION_APPLIED), rollback opt-in flag, cluster options."
+ },
+ {
+ "file": "rs-skip-paths.txt",
+ "content": "The final RS_SKIP_PATHS list, persisted so apply_pending_restore.sh applies the same exclusions after reboot that were computed during the interactive step. Prevents drift-affected or cross-kernel-unsafe paths from being restored at boot time."
+ },
+ {
+ "file": "rootfs/",
+ "content": "The staged files themselves — the exact bytes that will be laid down. Kept on the same filesystem as / so the on-boot rsync is fast and does not depend on external storage still being reachable at boot."
+ }
],
"unitBody": "The proxmenux-restore-onboot.service systemd unit is enabled at the end of the interactive step. It is a one-shot service that fires early on the next boot, calls apply_pending_restore.sh, then disables itself. The unit is gated by ConditionPathExists=/var/lib/proxmenux/pending-restore/state, so on any boot without a pending restore it is a no-op."
},
@@ -73,13 +121,63 @@
"heading": "The post-boot dispatcher — apply_cluster_postboot.sh",
"intro": "Where the interactive step ends and where the actual host reproduction happens. apply_cluster_postboot.sh is installed as a second one-shot systemd unit (proxmenux-apply-cluster-postboot.service) whose After=/Wants= targets ensure it runs only after pve-cluster and network-online are up. This is where the host-visible restore actions land.",
"tasks": [
- { "task": "Apply /etc/pve", "detail": "/etc/pve is a live pmxcfs FUSE mount — it cannot be written to on early boot. The dispatcher copies files from the pending rootfs to the live /etc/pve once the cluster filesystem is up, one file at a time, without restarting pve-cluster." },
- { "task": "Rebuild initramfs and bootloader", "detail": "Runs update-initramfs -u -k all across every installed kernel, then either update-grub (GRUB installs) or proxmox-boot-tool refresh (systemd-boot / ZFS installs). Skipped if the interactive step determined nothing changed in the paths that affect these tools." },
- { "task": "Component auto-reinstall", "detail": "Reads the restored components_status.json and iterates over the registered installers (nvidia_driver, coral_driver, amdgpu_top, intel_gpu_tools). Each installer runs in --auto-reinstall mode, reads its previously-recorded version from the state file, and rebuilds against the target's current kernel. The interactive flow does not do this — reinstalling drivers against a kernel that has not yet booted is meaningless." },
- { "task": "Boot sanity check", "detail": "Before firing the completion notification, verifies that proxmox-boot-tool status shows a configured ESP, every /boot/vmlinuz-* has a matching /lib/modules/<ver> directory, and /vmlinuz resolves. Any inconsistency is surfaced in the notification instead of being hidden." },
- { "task": "Completion notification", "detail": "Sends the Host restore finished event through hb_notify_lifecycle. Includes total duration, applied path count, sanity-check warnings if any, and a link to the log at /var/log/proxmenux/proxmenux-cluster-postboot-*.log. If notifications are not configured, the event is silent — the log still records everything." }
+ {
+ "task": "Apply /etc/pve",
+ "detail": "/etc/pve is a live pmxcfs FUSE mount — it cannot be written to on early boot. The dispatcher copies files from the pending rootfs to the live /etc/pve once the cluster filesystem is up, one file at a time, without restarting pve-cluster."
+ },
+ {
+ "task": "Rebuild initramfs and bootloader",
+ "detail": "Runs update-initramfs -u -k all across every installed kernel, then either update-grub (GRUB installs) or proxmox-boot-tool refresh (systemd-boot / ZFS installs). Skipped if the interactive step determined nothing changed in the paths that affect these tools."
+ },
+ {
+ "task": "Component auto-reinstall",
+ "detail": "Reads the restored components_status.json and iterates over the registered installers (nvidia_driver, coral_driver, amdgpu_top, intel_gpu_tools). Each installer runs in --auto-reinstall mode, reads its previously-recorded version from the state file, and rebuilds against the target's current kernel. The interactive flow does not do this — reinstalling drivers against a kernel that has not yet booted is meaningless."
+ },
+ {
+ "task": "Boot sanity check",
+ "detail": "Before firing the completion notification, verifies that proxmox-boot-tool status shows a configured ESP, every /boot/vmlinuz-* has a matching /lib/modules/<ver> directory, and /vmlinuz resolves. Any inconsistency is surfaced in the notification instead of being hidden."
+ },
+ {
+ "task": "Completion notification",
+ "detail": "Sends the Host restore finished event through hb_notify_lifecycle. Includes total duration, applied path count, sanity-check warnings if any, and a link to the log at /var/log/proxmenux/proxmenux-cluster-postboot-*.log. If notifications are not configured, the event is silent — the log still records everything."
+ }
]
},
+ "liveProgress": {
+ "heading": "Live progress in the Monitor's Backups tab",
+ "body": "After the reboot the Backups tab of ProxMenux Monitor renders a live post-restore card that reflects the state of apply_cluster_postboot.service as it runs. The card is driven by /var/lib/proxmenux/restore-state.json, which the dispatcher updates at every milestone (apply cluster config, rebuild initramfs, update bootloader, per-component reinstall, boot sanity check, finalize).",
+ "fields": [
+ {
+ "name": "Status badge",
+ "detail": "One of Restore in progress, Restore complete or Restore failed. The card polls the state file every 2 seconds while running and every 30 seconds after finish."
+ },
+ {
+ "name": "Progress bar + step counter",
+ "detail": "Shows N/M steps with the label of the current step. While the restore is running an estimated time is derived from steps completed and elapsed time."
+ },
+ {
+ "name": "Component list",
+ "detail": "One row per driver being reinstalled (NVIDIA, Intel GPU tools, AMD tools, Coral TPU) with installing / ok / failed plus a link to the per-component log at /var/log/proxmenux/component-*.log."
+ },
+ {
+ "name": "Boot sanity warnings",
+ "detail": "The dispatcher checks for missing /lib/modules/<kernel>, absent ESP configuration and dangling /vmlinuz symlinks. Any warning surfaces here as a coloured banner."
+ },
+ {
+ "name": "Rollback delta",
+ "detail": "Lists VMs, LXCs and components that exist on the target but were not in the restored backup — the same entries surfaced in the pre-restore destructive rollback dialog. Each row carries the manual cleanup command."
+ },
+ {
+ "name": "Log tail",
+ "detail": "The last 600 lines of proxmenux-cluster-postboot-<ts>.log, with an Issues only filter that keeps just lines matching error, warning, failed, ✗ or traceback."
+ }
+ ],
+ "dismissBody": "Once the restore is complete or failed, a Dismiss button collapses the card. The state file is preserved and the History button re-opens it plus any prior restore (the last 20 runs are archived under /var/lib/proxmenux/restore-history/).",
+ "imageAlt": "ProxMenux Monitor Backups tab showing the post-restore progress card after a completed restore, with the green Restore complete badge, full progress bar, run duration and summary tiles (guests, bind-mount stubs, stale nodes cleaned, components).",
+ "imageCaption": "The Backups tab card after the post-boot dispatcher has finished — status badge, 100% progress bar, run duration and per-component summary tiles.",
+ "detailsImageAlt": "Post-restore Details modal opened on the same completed restore, showing the finalised progress bar at 6/6 steps, the Rollback delta section reporting no drift, and the full log tail with the Full / Issues only toggle.",
+ "detailsImageCaption": "The Details modal for a completed restore, exposing the full run log, the boot sanity result and the rollback delta computed against the backup."
+ },
"postbootExample": {
"heading": "What the post-boot looks like on the console",
"body": "On the host's physical console, a successful dispatcher run ends with a [ OK ] Finished proxmenux-apply-cluster-postboot.service line. When that line appears — usually alongside the OKs for multi-user.target and graphical.target — the restore is completely finished: components reinstalled, boot artifacts regenerated, cluster reconciled.",
@@ -90,13 +188,41 @@
"heading": "Why the last ten minutes matter",
"intro": "The reboot itself takes seconds, but the post-boot dispatcher spends around ten minutes finishing the restore. During this window the host is reachable and login works, but some services (mainly GPU-driver-dependent ones) are not yet available. Time breakdown for a typical Proxmox host with NVIDIA + Coral installed:",
"rows": [
- { "stage": "Boot + pve-cluster ready", "time": "~30 s", "detail": "Standard Proxmox boot. SSH, web UI and login are available at the end of this stage." },
- { "stage": "Apply /etc/pve to pmxcfs", "time": "~10 s", "detail": "Fast — small config files copied one by one to the live cluster filesystem." },
- { "stage": "Rebuild initramfs across kernels", "time": "3–5 min", "detail": "update-initramfs -u -k all rebuilds one initramfs image per installed kernel. Bulk of the wait." },
- { "stage": "Rebuild bootloader config", "time": "10–30 s", "detail": "update-grub or proxmox-boot-tool refresh. Fast even on ZFS." },
- { "stage": "NVIDIA driver reinstall (if applicable)", "time": "5–10 min", "detail": "Downloads the recorded driver version, compiles the DKMS modules against the current kernel, applies the ProxMenux patch if the source had it. Longest single task." },
- { "stage": "Coral / other component reinstalls", "time": "3–5 min", "detail": "DKMS compiles for Coral, apt install for intel-gpu-tools, .deb download + install for amdgpu_top." },
- { "stage": "Sanity check + notification", "time": "~2 s", "detail": "Cheap. The operator learns the run completed the moment the notification fires." }
+ {
+ "stage": "Boot + pve-cluster ready",
+ "time": "~30 s",
+ "detail": "Standard Proxmox boot. SSH, web UI and login are available at the end of this stage."
+ },
+ {
+ "stage": "Apply /etc/pve to pmxcfs",
+ "time": "~10 s",
+ "detail": "Fast — small config files copied one by one to the live cluster filesystem."
+ },
+ {
+ "stage": "Rebuild initramfs across kernels",
+ "time": "3–5 min",
+ "detail": "update-initramfs -u -k all rebuilds one initramfs image per installed kernel. Bulk of the wait."
+ },
+ {
+ "stage": "Rebuild bootloader config",
+ "time": "10–30 s",
+ "detail": "update-grub or proxmox-boot-tool refresh. Fast even on ZFS."
+ },
+ {
+ "stage": "NVIDIA driver reinstall (if applicable)",
+ "time": "5–10 min",
+ "detail": "Downloads the recorded driver version, compiles the DKMS modules against the current kernel, applies the ProxMenux patch if the source had it. Longest single task."
+ },
+ {
+ "stage": "Coral / other component reinstalls",
+ "time": "3–5 min",
+ "detail": "DKMS compiles for Coral, apt install for intel-gpu-tools, .deb download + install for amdgpu_top."
+ },
+ {
+ "stage": "Sanity check + notification",
+ "time": "~2 s",
+ "detail": "Cheap. The operator learns the run completed the moment the notification fires."
+ }
],
"outroBody": "The window matters because the operator can log in during this time and see missing tools (nvidia-smi not found, coral not detected). This is expected — the reinstall is still running in the background. The completion notification signals when everything is ready."
},
@@ -107,18 +233,42 @@
"logs": {
"heading": "Where the logs live",
"rows": [
- { "log": "/var/log/proxmenux/restore-YYYYMMDD_HHMMSS.log", "detail": "Written by the interactive step. Contains: compatibility results, drift filter, hydration plan, apply hot output, prepare pending output, package install." },
- { "log": "/var/log/proxmenux/apply-pending-YYYYMMDD_HHMMSS.log", "detail": "Written by apply_pending_restore.sh on early boot. Contains: sourced plan.env, apply-on-boot iteration, skip-paths filtering." },
- { "log": "/var/log/proxmenux/proxmenux-cluster-postboot-YYYYMMDD_HHMMSS.log", "detail": "Written by apply_cluster_postboot.sh. Contains: pve-cluster apply, initramfs and bootloader output, per-component installer output, sanity check, notification payload." },
- { "log": "/var/log/proxmenux/component-apply_pending_restore.sh on early boot. Contains: sourced plan.env, apply-on-boot iteration, skip-paths filtering."
+ },
+ {
+ "log": "/var/log/proxmenux/proxmenux-cluster-postboot-YYYYMMDD_HHMMSS.log",
+ "detail": "Written by apply_cluster_postboot.sh. Contains: pve-cluster apply, initramfs and bootloader output, per-component installer output, sanity check, notification payload."
+ },
+ {
+ "log": "/var/log/proxmenux/component-proxmox-backup-client key create --kdf none genera el keyfile en /usr/local/share/proxmenux/pbs-key.conf (chmod 600). Las copias posteriores lo reutilizan tras un único diálogo de confirmación. Si la creación del keyfile falla, la copia se cancela y la salida de error de la herramienta se muestra en un diálogo.",
+ "keyfileBody": "El diálogo de cifrado sigue un flujo yes/no en dos pasos. El primer paso pregunta si se desea cifrar el backup: No continúa sin cifrado; Yes pasa al segundo paso. El segundo paso depende de si ya hay un keyfile instalado en /usr/local/share/proxmenux/pbs-key.conf. Si lo hay, se reutiliza silenciosamente y el backup continúa. Si no lo hay, aparece un menú de dos opciones: Generate a new keyfile, que ejecuta proxmox-backup-client key create --kdf none, o Import an existing keyfile, que toma una ruta indicada por el operador, la valida con proxmox-backup-client key info y la instala en la ruta canónica. Ambas ramas se ejecutan solo tras confirmar la passphrase de recuperación — cancelar cualquier diálogo antes de ese punto deja el disco intacto.",
+ "modesTitle": "Keyfile por host o compartido",
+ "modesIntro": "Ambos modelos operativos están soportados y ninguno se impone — la decisión pertenece al usuario según cómo esté organizada su flota.",
+ "modesPerHostTitle": "Keyfile por host (por defecto)",
+ "modesPerHostBody": "Cada host genera su propio keyfile la primera vez que activa el cifrado PBS. El aislamiento es máximo: comprometer el keyfile de un host no expone las copias de ningún otro. Cada host tiene su propio blob de recuperación emparejado en PBS, restaurable con la passphrase de recuperación de ese host. Recomendado para flotas de producción y para entornos donde los hosts tienen propietarios o límites de compliance distintos.",
+ "modesSharedTitle": "Keyfile compartido (importar en cada host)",
+ "modesSharedBody": "Un keyfile maestro generado una vez e instalado en cada host mediante la opción Importar. La gestión es más simple: un único secreto que proteger, un único blob de recuperación sirve para todos los hosts, y cualquier host puede desencriptar los archives de cualquier otro (útil para consolidación, simulacros de restore cruzado o verificación centralizada de backups). El trade-off es que una filtración del keyfile compartido expone todos los hosts a la vez. Recomendado para homelabs y para flotas donde todos los hosts tienen el mismo propietario y límite de confianza.",
"recoveryTitle": "Passphrase de recuperación y blob de escrow",
- "recoveryBody": "Tras crear el keyfile, ProxMenux pregunta dos veces por una passphrase de recuperación (con validación de coincidencia) y ejecuta openssl para producir pbs-key.recovery.enc — el keyfile cifrado con la passphrase. Se escribe una copia en /root/pbs-key.recovery-HOSTNAME-YYYYMMDD.enc para almacenamiento offsite. Cancelar el diálogo de la passphrase borra el keyfile recién creado.",
+ "recoveryBody": "La passphrase de recuperación se solicita ANTES de escribir ningún keyfile en disco. ProxMenux la pide dos veces con validación de coincidencia; solo cuando el operador la confirma, se crea (o importa) el keyfile y openssl produce pbs-key.recovery.enc — el keyfile cifrado con la passphrase. Se escribe una copia en /root/pbs-key.recovery-HOSTNAME-YYYYMMDD.enc como respaldo offsite. Cancelar el diálogo de la passphrase deja el disco intacto — no se crea ningún keyfile y no hay nada que limpiar.",
"blobUploadTitle": "Grupo emparejado en PBS",
"blobUploadBody1": "Tras una copia PBS que usó el keyfile, el blob de escrow se sube como un segundo grupo de copia: host/hostcfg-HOSTNAME-keyrecovery/BACKUP-TIME. El prefijo compartido hostcfg-HOSTNAME coloca ambos grupos adyacentes en la interfaz de PBS; el sufijo -keyrecovery etiqueta la relación. La subida se ejecuta sin --keyfile (el blob ya está protegido con passphrase por openssl) y sólo cuando la copia actual usó el keyfile.",
"blobUploadConstraintTitle": "Por qué dos grupos",
diff --git a/web/messages/es/docs/backup-restore/how-it-works.json b/web/messages/es/docs/backup-restore/how-it-works.json
index c46d33c2..ed39ebb3 100644
--- a/web/messages/es/docs/backup-restore/how-it-works.json
+++ b/web/messages/es/docs/backup-restore/how-it-works.json
@@ -193,7 +193,7 @@
]
},
"whyItWorks": {
- "heading": "Por qué la separación en tres bloques es la correcta",
+ "heading": "Por qué la separación en tres bloques es la usada",
"body": "La separación no responde a una decisión de sistema de ficheros — responde a una decisión de ciclo de vida. El contenido del sistema de ficheros se mueve con rsync: rápido, transparente, atómico por fichero. El estado de configuración que la restauración tiene que interpretar antes de tocar el destino se mueve como JSON estructurado: legible de forma independiente, versionable mediante un esquema, diff-eable contra el estado propio del destino. El software que se tiene que reinstalar contra el entorno del destino se mueve como inventario: sólo nombres y versiones, dejando que el gestor de paquetes del destino y los instaladores propios de ProxMenux decidan los binarios reales. Cada bloque se optimiza para lo que tiene que hacer, y los tres combinan en una restauración que es atómica en la intención pero tolerante a fallos en la práctica: un manifiesto corrupto sigue dejando el rootfs restaurable, un paquete perdido sigue dejando los componentes instalables, un instalador que falla en una entrada no detiene la siguiente."
}
}
diff --git a/web/messages/es/docs/backup-restore/restoring.json b/web/messages/es/docs/backup-restore/restoring.json
index f09e2924..c633bd13 100644
--- a/web/messages/es/docs/backup-restore/restoring.json
+++ b/web/messages/es/docs/backup-restore/restoring.json
@@ -143,6 +143,41 @@
}
]
},
+ "liveProgress": {
+ "heading": "Progreso en vivo en la pestaña Backups del Monitor",
+ "body": "Tras el reboot, la pestaña Backups del Monitor de ProxMenux muestra una tarjeta de progreso en vivo que refleja el estado de apply_cluster_postboot.service a medida que avanza. La tarjeta lee /var/lib/proxmenux/restore-state.json, que el dispatcher actualiza en cada hito (aplicar configuración del cluster, reconstruir initramfs, actualizar bootloader, reinstalación por componente, verificación de arranque, finalización).",
+ "fields": [
+ {
+ "name": "Insignia de estado",
+ "detail": "Una de estas tres: Restauración en curso, Restauración completa o Restauración fallida. Mientras se ejecuta, la tarjeta consulta el fichero de estado cada 2 segundos; una vez terminada, cada 30 segundos."
+ },
+ {
+ "name": "Barra de progreso + contador de pasos",
+ "detail": "Muestra N/M steps con la etiqueta del paso actual. Durante la ejecución se calcula un tiempo estimado restante a partir de los pasos completados y el tiempo transcurrido."
+ },
+ {
+ "name": "Lista de componentes",
+ "detail": "Una fila por cada driver reinstalado (NVIDIA, Intel GPU tools, AMD tools, Coral TPU) con estado installing / ok / failed y un enlace al log por componente en /var/log/proxmenux/component-*.log."
+ },
+ {
+ "name": "Avisos de arranque",
+ "detail": "El dispatcher verifica si falta /lib/modules/<kernel>, si no hay ESP configurada y si hay un symlink /vmlinuz colgado. Cualquier aviso aparece aquí en un banner coloreado."
+ },
+ {
+ "name": "Delta de rollback",
+ "detail": "Lista VMs, LXCs y componentes que existen en el destino pero no estaban en el backup restaurado — las mismas entradas que aparecen en el diálogo de rollback destructivo pre-restore. Cada fila incluye el comando de limpieza manual."
+ },
+ {
+ "name": "Tail del log",
+ "detail": "Las últimas 600 líneas de proxmenux-cluster-postboot-<ts>.log, con un filtro Issues only que deja solo las líneas con error, warning, failed, ✗ o traceback."
+ }
+ ],
+ "dismissBody": "Cuando la restauración termina como complete o failed, el botón Dismiss colapsa la tarjeta. El fichero de estado se conserva y el botón History la reabre junto con cualquier restauración anterior (se archivan las últimas 20 en /var/lib/proxmenux/restore-history/).",
+ "imageAlt": "Pestaña Backups del Monitor de ProxMenux mostrando la tarjeta de progreso post-restauración tras una restauración completada, con la insignia verde \"Restore complete\", la barra de progreso llena, la duración del proceso y los recuadros de resumen (guests, bind-mount stubs, stale nodes cleaned, components).",
+ "imageCaption": "La tarjeta de la pestaña Backups tras finalizar el post-boot dispatcher — insignia de estado, barra al 100%, duración total y recuadros de resumen por componente.",
+ "detailsImageAlt": "Modal Details post-restauración abierto sobre la misma restauración completada, mostrando la barra final en 6/6 pasos, la sección Rollback delta indicando que no hay entradas nuevas y el tail del log completo con el conmutador Full / Issues only.",
+ "detailsImageCaption": "El modal Details de una restauración completada, con el log completo, el resultado de la verificación de arranque y el delta de rollback calculado contra el backup."
+ },
"postbootExample": {
"heading": "Cómo se ve el post-boot en la consola",
"body": "En la consola física del host la ejecución exitosa del dispatcher termina con una línea [ OK ] Finished proxmenux-apply-cluster-postboot.service. Cuando esa línea aparece — normalmente acompañada de los OK del multi-user.target y del graphical.target — la restauración ha terminado por completo: componentes reinstalados, boot artifacts regenerados, cluster reconciliado.",
diff --git a/web/public/images/docs/backup-restore/monitor-restore-progress-card.png b/web/public/images/docs/backup-restore/monitor-restore-progress-card.png
new file mode 100644
index 00000000..0392e78c
Binary files /dev/null and b/web/public/images/docs/backup-restore/monitor-restore-progress-card.png differ
diff --git a/web/public/images/docs/backup-restore/monitor-restore-progress-details.png b/web/public/images/docs/backup-restore/monitor-restore-progress-details.png
new file mode 100644
index 00000000..0738328f
Binary files /dev/null and b/web/public/images/docs/backup-restore/monitor-restore-progress-details.png differ