Cross-kernel restore

The direction check

During the compatibility check, hb_compat_check compares the kernel recorded in the backup's manifest against the target's current kernel (uname -r) and classifies the restore into one of three cases, stored in the internal variable HB_COMPAT_KERNEL_DIRECTION:

Why a backup with a newer kernel than the target restores unchanged

When the restore runs against a target with an older kernel than the one recorded in the backup, every mechanism the restore depends on is independent of the kernel version. GPU driver installers and other PCI-device installers detect the running kernel with uname -r and compile DKMS against whatever the target has. The APT package install pulls binaries built for the target's distribution. IOMMU cmdline tokens like intel_iommu=on are stable across major kernel versions. The backup carries paths written under a newer kernel, but those paths (module blacklists, GRUB defaults, initramfs config) are still valid syntax on the older one — kernels ignore tokens they do not recognise instead of failing. This case is equivalent in practice to a same-kernel restore, and ProxMenux treats it as such.

The safe-subset filter (only when the target kernel is newer)

When the target kernel is newer than the backup's, the compatibility check adds 16 boot-critical paths from hb_unsafe_paths_cross_version to RS_SKIP_PATHS. These paths are excluded from the restore because writing a version of them from an older kernel over a target running a newer one has caused kernel panics in bench tests. The paths cover four categories:

The filter runs BEFORE the confirmation dialog so the user sees the exact list of paths that will be skipped, categorised by reason. The restore still proceeds — everything else (VMs, LXCs, network, /etc/pve, users, cron, ProxMenux state, packages, drivers, /root) is restored normally.

Kernel-agnostic hydration

The safe-subset filter alone would leave the target without the tuning the user had inside those boot-critical files: IOMMU cmdline for GPU passthrough, VFIO device IDs, custom GRUB_TIMEOUT, nvidia blacklists. The hydration pass re-applies those bits kernel-agnostically. Four phases run when the target kernel is newer than the backup's, each additive (never overwrites a value the target already carries) and idempotent (running twice is a no-op).

Plan vs commit — the operator sees a preview first

The hydration runs in two modes. Before the confirmation dialog, ProxMenux runs _rs_apply_bk_older_hydration in plan mode: it computes exactly what would be merged, populates RS_HYDRATION_SUMMARY with a green block listing each action, and returns without writing. The confirmation dialog shows that green block alongside the amber safe-subset skip list, so the user sees UPFRONT what will be re-applied automatically. After the user confirms, ProxMenux re-runs the same helper in commit mode — same phases, same logic, but this time each phase writes to the live target. Cancelling the confirmation dialog leaves the target untouched.

The flow when the target kernel is newer than the backup's

The steps added when the target kernel is newer sit inside the normal restore flow. Everything else — hot apply, pending prepare, package install, post-boot dispatcher — runs identically to a same-kernel restore.

  ┌────────────────────────────────────────────────────────────┐
  │ hb_compat_check                                             │
  │   HB_COMPAT_KERNEL_DIRECTION = bk_older                     │
  └───────────────────────────┬────────────────────────────────┘
                              │
                              ▼
  ┌────────────────────────────────────────────────────────────┐
  │ Add 16 boot-critical paths to RS_SKIP_PATHS                 │
  │   /etc/default/grub, /etc/kernel, /etc/modules-load.d, ...  │
  └───────────────────────────┬────────────────────────────────┘
                              │
                              ▼
  ┌────────────────────────────────────────────────────────────┐
  │ _rs_apply_bk_older_hydration "plan"                         │
  │   Compute what would be merged                              │
  │   Populate RS_HYDRATION_SUMMARY (green block)               │
  │   No writes                                                 │
  └───────────────────────────┬────────────────────────────────┘
                              │
                              ▼
  ┌────────────────────────────────────────────────────────────┐
  │ Confirmation dialog                                         │
  │   Amber: paths skipped by safe-subset filter                │
  │   Green: tokens/files reapplied by hydration                │
  │   User accepts or cancels                                   │
  └───────────────────────────┬────────────────────────────────┘
                              │ (accepted)
                              ▼
  ┌────────────────────────────────────────────────────────────┐
  │ _rs_apply_bk_older_hydration "commit"                       │
  │   Phase 1a/1b: merge cmdline tokens + GRUB keys             │
  │   Phase 2: append modules to /etc/modules                   │
  │   Phase 3: copy whitelisted vfio/nvidia files               │
  │   Set HB_HYDRATION_APPLIED=1                                │
  └───────────────────────────┬────────────────────────────────┘
                              │
                              ▼
  ┌────────────────────────────────────────────────────────────┐
  │ Rest of the restore runs normally                           │
  │   _rs_apply hot (skips RS_SKIP_PATHS)                       │
  │   _rs_prepare_pending_restore (writes plan.env with         │
  │     HB_HYDRATION_APPLIED=1)                                 │
  │   packages.manual.list install                              │
  │   Reboot                                                    │
  │   apply_pending_restore.sh (forces NEEDS_INITRAMFS=1,       │
  │     NEEDS_GRUB=1 because of the hydration flag)             │
  │   apply_cluster_postboot.sh                                 │
  │     update-initramfs -u -k all                              │
  │     update-grub / proxmox-boot-tool refresh                 │
  │     component --auto-reinstall                              │
  └────────────────────────────────────────────────────────────┘

Concrete examples

The hydration pass is not abstract — it produces observable, correct outcomes for common scenarios. Two examples that hydration handles automatically:

Where the mechanisms live

For developers looking to trace or extend the cross-kernel behaviour:

Where to go next

• Restoring — the full restore pipeline this page's mechanisms plug into.
• How it works — the manifest and collectors that produce the <code>kernel_params</code> block hydration reads from.