mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-08-04 23:06:23 +00:00
new beta 1.2.4.1
This commit is contained in:
MacRimi
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Creating backups — interactive backup flow | ProxMenux",
|
||||
"description": "The interactive backup flow in ProxMenux. Two entry points (Scripts TUI menu and Monitor Web UI), three destinations, two profile modes, one staging step, and one confirmation dialog. Documents the six-option matrix, the default and custom profiles, and what the operator sees between selecting a backup and the archive landing on the destination.",
|
||||
"description": "The interactive backup flow in ProxMenux. Two entry points (Scripts TUI menu and Monitor Web UI), three destinations, two profile modes, one staging step, and one confirmation dialog. Documents the six-option matrix, the default and custom profiles, and what the user sees between selecting a backup and the archive landing on the destination.",
|
||||
"ogTitle": "ProxMenux Backup — creating backups",
|
||||
"ogDescription": "The interactive backup flow with three destinations, two profiles and a common staging step.",
|
||||
"twitterTitle": "Creating backups | ProxMenux",
|
||||
@@ -25,7 +25,7 @@
|
||||
},
|
||||
"modes": {
|
||||
"heading": "Manual vs scheduled backups",
|
||||
"body": "Backups can be produced in two modes: <strong>manual</strong> (the interactive flow this page documents — the operator picks a destination and a profile from a menu and watches the archive land) or <strong>scheduled</strong> (an unattended job that runs on a cron-style timer and applies the retention configured on the job). Both modes support the same three destinations and the same two profiles, and both are available from both entry points — the Scripts TUI menu and the Monitor Backups tab. Scheduled jobs use the same backend functions as the manual flow through <code>run_scheduled_backup.sh</code>; the archives produced are indistinguishable.",
|
||||
"body": "Backups can be produced in two modes: <strong>manual</strong> (the interactive flow this page documents — the user picks a destination and a profile from a menu and watches the archive land) or <strong>scheduled</strong> (an unattended job that runs on a cron-style timer and applies the retention configured on the job). Both modes support the same three destinations and the same two profiles, and both are available from both entry points — the Scripts TUI menu and the Monitor Backups tab. Scheduled jobs use the same backend functions as the manual flow through <code>run_scheduled_backup.sh</code>; the archives produced are indistinguishable.",
|
||||
"seeAlso": "The scheduled-jobs page covers the full flow, including how to create a job, attach it to an existing PVE vzdump timer, and configure the retention values.",
|
||||
"monitorAlt": "ProxMenux Monitor Backups tab showing the New scheduled backup dialog with destination, profile, schedule and retention fields.",
|
||||
"monitorCaption": "Scheduled backup — ProxMenux Monitor. The same wizard-style dialog that creates a manual backup carries the schedule and retention fields at the bottom for the unattended path."
|
||||
@@ -37,7 +37,7 @@
|
||||
{ "combo": "1", "destination": "PBS", "profile": "Default", "action": "Uploads the default profile plus persistent extras to a configured PBS repository." },
|
||||
{ "combo": "2", "destination": "Borg", "profile": "Default", "action": "Creates an archive with the default profile plus persistent extras in the selected Borg repository." },
|
||||
{ "combo": "3", "destination": "Local", "profile": "Default", "action": "Writes a <code>.tar.zst</code> archive with the default profile plus persistent extras to the configured local target." },
|
||||
{ "combo": "4", "destination": "PBS", "profile": "Custom", "action": "Opens the path picker before the PBS upload; the operator ticks paths and can add new ones." },
|
||||
{ "combo": "4", "destination": "PBS", "profile": "Custom", "action": "Opens the path picker before the PBS upload; the user ticks paths and can add new ones." },
|
||||
{ "combo": "5", "destination": "Borg", "profile": "Custom", "action": "Opens the path picker before the Borg archive create." },
|
||||
{ "combo": "6", "destination": "Local", "profile": "Custom", "action": "Opens the path picker before writing the local <code>.tar.zst</code>." }
|
||||
]
|
||||
@@ -45,11 +45,11 @@
|
||||
"profiles": {
|
||||
"heading": "Default vs Custom profile",
|
||||
"defaultTitle": "Default profile",
|
||||
"defaultBody": "The default profile is the curated list from <code>hb_default_profile_paths</code> (documented in <em>How it works</em> under <em>Path categories</em>) plus every entry in the persistent extras file <code>/usr/local/share/proxmenux/backup-extra-paths.txt</code>. The operator confirms the destination and encryption options and the backup proceeds without further path selection.",
|
||||
"defaultBody": "The default profile is the curated list from <code>hb_default_profile_paths</code> (documented in <em>How it works</em> under <em>Path categories</em>) plus every entry in the persistent extras file <code>/usr/local/share/proxmenux/backup-extra-paths.txt</code>. The user confirms the destination and encryption options and the backup proceeds without further path selection.",
|
||||
"customTitle": "Custom profile",
|
||||
"customBody": "The custom profile opens a checklist showing every path in the default profile (unchecked) and every persistent extra (pre-checked, prefixed with <code>[+]</code>). The operator ticks the set for this run and can press <em>Add custom path</em> to append a new absolute path. Any path added inline is persisted to <code>backup-extra-paths.txt</code> so future backups pick it up automatically without re-adding it. Removing a persistent extra unticks it for this run but does not delete it from the file — deletion is a separate <em>Manage custom paths</em> action outside the backup flow.",
|
||||
"customBody": "The custom profile opens a checklist showing every path in the default profile (unchecked) and every persistent extra (pre-checked, prefixed with <code>[+]</code>). The user ticks the set for this run and can press <em>Add custom path</em> to append a new absolute path. Any path added inline is persisted to <code>backup-extra-paths.txt</code> so future backups pick it up automatically without re-adding it. Removing a persistent extra unticks it for this run but does not delete it from the file — deletion is a separate <em>Manage custom paths</em> action outside the backup flow.",
|
||||
"customPickerAlt": "Custom profile checklist showing the default-profile paths (unchecked) and persistent extras (pre-checked with a [+] prefix), plus buttons to add a new path or confirm the selection.",
|
||||
"customPickerCaption": "Custom profile — the path picker. Default-profile paths are unchecked; persistent extras appear pre-checked with a [+] prefix. The operator ticks the set for this run.",
|
||||
"customPickerCaption": "Custom profile — the path picker. Default-profile paths are unchecked; persistent extras appear pre-checked with a [+] prefix. The user ticks the set for this run.",
|
||||
"manageCustomAlt": "Manage custom paths menu showing the list of persistent extras and options to add, remove or edit them.",
|
||||
"manageCustomCaption": "Manage custom paths — the entry point where persistent extras are added or removed. Every path listed here is included automatically in Default-mode backups without needing to open the Custom picker."
|
||||
},
|
||||
@@ -57,11 +57,11 @@
|
||||
"heading": "What runs regardless of destination",
|
||||
"intro": "After the profile is resolved, every backend runs the same staging pipeline before diverging into its own upload path. <code>hb_prepare_staging</code> assembles the archive tree in <code>/tmp/proxmenux-DESTINATION-stage.XXXXXX</code> and populates each of the three payloads.",
|
||||
"steps": [
|
||||
{ "step": "1", "name": "rootfs assembly", "detail": "Runs <code>rsync -a</code> for each selected path into <code>staging_root/rootfs/</code>. Excludes volatile subpaths (bash history, caches, trash) from <code>/root/</code>. Paths absent from the source are recorded in <code>metadata/missing_paths.txt</code> without stopping the backup." },
|
||||
{ "step": "1", "name": "rootfs assembly", "detail": "Runs <code>rsync -a</code> for each selected path into <code>staging_root/rootfs/</code>. The pmxcfs database at <code>/var/lib/pve-cluster/config.db</code> is captured separately via <code>sqlite3 .backup</code> to produce a consistent snapshot without stopping the cluster, and the <code>.db-wal</code> / <code>.db-shm</code> sidecars are excluded from the rsync; when <code>sqlite3</code> is not available a <code>config.db.raw-fallback</code> is dropped instead, and the restore promotes it on import. Volatile subpaths (bash history, caches, trash) are excluded from <code>/root/</code>. Paths absent from the source are recorded in <code>metadata/missing_paths.txt</code> without stopping the backup." },
|
||||
{ "step": "2", "name": "Manifest generation", "detail": "<code>build_manifest.sh</code> orchestrates the six collectors and writes <code>manifest.json</code> at the top of staging. On collector failure, the affected section falls back to a documented empty default; the manifest is still valid." },
|
||||
{ "step": "3", "name": "Package inventory", "detail": "<code>apt-mark showmanual</code> is captured verbatim into <code>metadata/packages.manual.list</code>. Component state is already inside the restored rootfs (<code>components_status.json</code>) because <code>/usr/local/share/proxmenux/</code> is part of the default profile." },
|
||||
{ "step": "4", "name": "Run info", "detail": "<code>metadata/run_info.env</code> records the backup run identity — hostname, timestamp, kernel version — used by the restore's compatibility check to determine the cross-kernel direction." },
|
||||
{ "step": "5", "name": "Notification (start)", "detail": "<code>hb_notify_lifecycle \"start\"</code> fires. If notifications are configured in the Monitor, an operator-facing <em>Host backup started</em> event is emitted. Silent if no channels are configured." }
|
||||
{ "step": "5", "name": "Notification (start)", "detail": "<code>hb_notify_lifecycle \"start\"</code> fires. If notifications are configured in the Monitor, an user-facing <em>Host backup started</em> event is emitted. Silent if no channels are configured." }
|
||||
]
|
||||
},
|
||||
"included": {
|
||||
@@ -75,7 +75,7 @@
|
||||
"<code>*.log</code> — log files."
|
||||
],
|
||||
"rootTitle": "<code>/root/</code> exclusions",
|
||||
"rootBody": "<code>/root/</code> is part of the default profile so operator scripts and config land in the archive. Volatile subpaths are dropped:",
|
||||
"rootBody": "<code>/root/</code> is part of the default profile so user scripts and config land in the archive. Volatile subpaths are dropped:",
|
||||
"rootItems": [
|
||||
"<code>.bash_history</code>",
|
||||
"<code>.cache/</code>",
|
||||
@@ -107,7 +107,7 @@
|
||||
"archiveStructure": {
|
||||
"heading": "Archive structure",
|
||||
"intro": "The staging directory produced by every backend follows the same layout regardless of destination. The tarball, PBS <code>.pxar</code> or Borg archive stores this tree verbatim.",
|
||||
"tree": "backup-[timestamp]/\n├── manifest.json # structured host state (kernel_params, hardware, storage, guests, components, source_host)\n├── metadata/\n│ ├── packages.manual.list # output of apt-mark showmanual\n│ ├── run_info.env # hostname, timestamp, kernel version\n│ ├── paths_archived.txt # exact list of paths that reached rootfs/\n│ └── missing_paths.txt # paths from the profile absent on source\n└── rootfs/\n ├── etc/ # /etc/pve, /etc/network, /etc/ssh, /etc/apt, ...\n ├── root/ # /root without volatile subpaths\n ├── usr/local/ # /usr/local/bin, /usr/local/sbin, /usr/local/share/proxmenux (state only)\n └── var/ # /var/lib/pve-cluster, /var/spool/cron/crontabs"
|
||||
"tree": "backup-[timestamp]/\n├── manifest.json # structured host state (kernel_params, hardware, storage, guests, components, source_host)\n├── metadata/\n│ ├── packages.manual.list # output of apt-mark showmanual\n│ ├── run_info.env # hostname, timestamp, kernel version, pmxcfs method\n│ ├── paths_archived.txt # exact list of paths that reached rootfs/\n│ └── missing_paths.txt # paths from the profile absent on source\n└── rootfs/\n ├── etc/ # /etc/pve, /etc/network, /etc/systemd/network, /etc/ssh, /etc/apt, ...\n ├── root/ # /root without volatile subpaths\n ├── usr/local/ # /usr/local/bin, /usr/local/sbin, /usr/local/share/proxmenux (state only)\n └── var/ # /var/lib/pve-cluster (config.db via sqlite3 .backup), /var/spool/cron/crontabs"
|
||||
},
|
||||
"confirmation": {
|
||||
"heading": "Confirmation summary",
|
||||
@@ -115,7 +115,7 @@
|
||||
},
|
||||
"writing": {
|
||||
"heading": "Writing to the destination",
|
||||
"intro": "Once the operator confirms, each backend runs its own write step. The mechanics are covered in the destination pages; the shared surface is the log, the sidecar and the completion notification.",
|
||||
"intro": "Once the user confirms, each backend runs its own write step. The mechanics are covered in the destination pages; the shared surface is the log, the sidecar and the completion notification.",
|
||||
"rows": [
|
||||
{ "topic": "Log file", "detail": "Every backend writes its full output to <code>/tmp/proxmenux-DESTINATION-backup-YYYYMMDD_HHMMSS.log</code> and, on failure, offers to open it in a scrollable dialog. The log path is printed in the completion summary only when the file has content." },
|
||||
{ "topic": "Sidecar (local only)", "detail": "<code>hb_write_archive_sidecar</code> drops a <code>*.proxmenux.json</code> next to the local archive so the Monitor identifies it as a ProxMenux host backup even after moves or renames." },
|
||||
|
||||
@@ -46,14 +46,14 @@
|
||||
"intro": "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 <code>GRUB_TIMEOUT</code>, 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).",
|
||||
"phaseRows": [
|
||||
{ "phase": "1a — GRUB path", "detail": "For hosts using GRUB (ext4/lvm installs). <code>_rs_hyd_grub</code> merges every token from the backup's <code>manifest.kernel_params.cmdline_extra</code> into the target's live <code>GRUB_CMDLINE_LINUX_DEFAULT</code>, skipping tokens whose key the target already carries. Then merges whitelisted <code>GRUB_*</code> keys (<code>GRUB_TIMEOUT</code>, <code>GRUB_TIMEOUT_STYLE</code>, <code>GRUB_DEFAULT</code>, <code>GRUB_TERMINAL</code>, <code>GRUB_DISABLE_OS_PROBER</code>, <code>GRUB_SERIAL_COMMAND</code>, <code>GRUB_GFXMODE</code>, <code>GRUB_GFXPAYLOAD_LINUX</code>) from the backup's <code>/etc/default/grub</code> if they differ from the target's." },
|
||||
{ "phase": "1b — systemd-boot / ZFS path", "detail": "For hosts using systemd-boot (typically ZFS-on-root). <code>_rs_hyd_kernel_cmdline</code> merges operator tokens from <code>cmdline_extra</code> into the target's <code>/etc/kernel/cmdline</code>, keeping the target's own <code>root=</code>, <code>boot=</code> and <code>rootflags=</code> boilerplate intact." },
|
||||
{ "phase": "1b — systemd-boot / ZFS path", "detail": "For hosts using systemd-boot (typically ZFS-on-root). <code>_rs_hyd_kernel_cmdline</code> merges user tokens from <code>cmdline_extra</code> into the target's <code>/etc/kernel/cmdline</code>, keeping the target's own <code>root=</code>, <code>boot=</code> and <code>rootflags=</code> boilerplate intact." },
|
||||
{ "phase": "2 — /etc/modules merge", "detail": "<code>_rs_hyd_modules</code> appends modules from <code>manifest.kernel_params.modules_loaded_at_boot</code> that are in the whitelist (<code>vfio</code>, <code>vfio_pci</code>, <code>vfio_iommu_type1</code>, <code>vfio_virqfd</code>, <code>kvm</code>, <code>kvm_intel</code>, <code>kvm_amd</code>, <code>nvidia</code>, <code>nvidia_drm</code>, <code>nvidia_modeset</code>, <code>nvidia_uvm</code>, <code>i915</code>, <code>xe</code>) AND not already present in the target's <code>/etc/modules</code>." },
|
||||
{ "phase": "3 — Whitelisted files copy", "detail": "<code>_rs_hyd_files</code> copies operator-authored files from the staging rootfs to the live target when the content differs. Whitelist covers VFIO/nvidia/blacklist files under <code>/etc/modprobe.d</code>, <code>/etc/modules-load.d</code>, and the ProxMenux VFIO bind rule + nvidia udev rules under <code>/etc/udev/rules.d</code>. Distro-owned files (<code>pve-blacklist.conf</code>, <code>mdadm.conf</code>, <code>nvme.conf</code>) are intentionally excluded — their contents evolve between releases." },
|
||||
{ "phase": "3 — Whitelisted files copy", "detail": "<code>_rs_hyd_files</code> copies user-authored files from the staging rootfs to the live target when the content differs. Whitelist covers VFIO/nvidia/blacklist files under <code>/etc/modprobe.d</code>, <code>/etc/modules-load.d</code>, and the ProxMenux VFIO bind rule + nvidia udev rules under <code>/etc/udev/rules.d</code>. Distro-owned files (<code>pve-blacklist.conf</code>, <code>mdadm.conf</code>, <code>nvme.conf</code>) are intentionally excluded — their contents evolve between releases." },
|
||||
{ "phase": "4 — Force post-boot reflows", "detail": "The four phases write directly to the live target OUTSIDE the normal restore pipeline. To make the merged tokens/modules/files take effect on the next boot, <code>HB_HYDRATION_APPLIED=1</code> propagates through <code>plan.env</code> to <code>apply_pending_restore.sh</code>, which forces <code>NEEDS_INITRAMFS=1</code> and <code>NEEDS_GRUB=1</code> regardless of what was in the apply list. The post-boot dispatcher then regenerates initramfs and refreshes the bootloader." }
|
||||
]
|
||||
},
|
||||
"planCommit": {
|
||||
"heading": "Plan vs commit — the operator sees a preview first",
|
||||
"heading": "Plan vs commit — the user sees a preview first",
|
||||
"body": "The hydration runs in two modes. Before the confirmation dialog, ProxMenux runs <code>_rs_apply_bk_older_hydration</code> in <code>plan</code> mode: it computes exactly what would be merged, populates <code>RS_HYDRATION_SUMMARY</code> 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 <code>commit</code> mode — same phases, same logic, but this time each phase writes to the live target. Cancelling the confirmation dialog leaves the target untouched."
|
||||
},
|
||||
"flowDiagram": {
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
{
|
||||
"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."
|
||||
"def": "Text password the user 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",
|
||||
@@ -130,7 +130,7 @@
|
||||
{
|
||||
"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."
|
||||
"def": "Name of the <a href=\"#grupo-copia\">backup group</a>. ProxMenux defaults to <code>hostcfg-HOSTNAME</code> and lets the user edit it before upload; unsupported characters are stripped automatically."
|
||||
},
|
||||
{
|
||||
"id": "pxar",
|
||||
|
||||
@@ -20,11 +20,11 @@
|
||||
"heading": "Archive layout",
|
||||
"intro": "Every archive follows the same tree layout regardless of destination. The <code>metadata/</code> subdirectory holds the structured payloads; the <code>rootfs/</code> subdirectory holds the filesystem copy.",
|
||||
"treeCaption": "The staging directory laid out during a backup. Every destination receives the same tree (adapted to its native format: tar for local, PBS chunks for PBS, borg segments for Borg).",
|
||||
"tree": "backup-[timestamp]/\n├── manifest.json # structured host state\n├── metadata/\n│ ├── packages.manual.list # apt-mark showmanual\n│ ├── run_info.env # backup run identity + kernel version\n│ ├── paths_archived.txt # exact list of paths that reached rootfs/\n│ └── missing_paths.txt # paths from the profile absent on source\n└── rootfs/\n ├── etc/ # /etc/pve, /etc/network, /etc/ssh, …\n ├── root/ # /root (with volatile subdirs excluded)\n ├── usr/local/ # /usr/local/bin, /usr/local/share/proxmenux, …\n └── var/ # /var/lib/pve-cluster, /var/spool/cron/…"
|
||||
"tree": "backup-[timestamp]/\n├── manifest.json # structured host state\n├── metadata/\n│ ├── packages.manual.list # apt-mark showmanual\n│ ├── run_info.env # backup run identity + kernel version + pmxcfs method\n│ ├── paths_archived.txt # exact list of paths that reached rootfs/\n│ └── missing_paths.txt # paths from the profile absent on source\n└── rootfs/\n ├── etc/ # /etc/pve, /etc/network, /etc/systemd/network, /etc/ssh, …\n ├── root/ # /root (with volatile subdirs excluded)\n ├── usr/local/ # /usr/local/bin, /usr/local/share/proxmenux, …\n └── var/ # /var/lib/pve-cluster (config.db via sqlite3 .backup), /var/spool/cron/…"
|
||||
},
|
||||
"rootfs": {
|
||||
"heading": "The rootfs payload",
|
||||
"intro": "The <code>rootfs/</code> tree is a <strong>plain filesystem copy</strong> produced by <code>rsync</code> from the source host. It contains a curated <strong>default profile</strong> of paths that matter for a Proxmox restore, plus any <strong>custom paths</strong> added by the operator to the backup job or interactive session. The set is deliberately narrow: only paths that either <em>hold configuration</em> or <em>hold state that Proxmox cannot regenerate on its own</em>.",
|
||||
"intro": "The <code>rootfs/</code> tree is a <strong>plain filesystem copy</strong> produced by <code>rsync</code> from the source host. It contains a curated <strong>default profile</strong> of paths that matter for a Proxmox restore, plus any <strong>custom paths</strong> added by the user to the backup job or interactive session. The set is deliberately narrow: only paths that either <em>hold configuration</em> or <em>hold state that Proxmox cannot regenerate on its own</em>.",
|
||||
"defaultProfileTitle": "The default profile",
|
||||
"defaultProfileBody": "The default profile is defined by <code>hb_default_profile_paths</code> in <code>lib_host_backup_common.sh</code>. It covers eight categories that together describe a working Proxmox host:",
|
||||
"categoriesTitle": "Path categories",
|
||||
@@ -32,17 +32,17 @@
|
||||
{
|
||||
"category": "PVE core",
|
||||
"paths": "/etc/pve, /var/lib/pve-cluster, /etc/vzdump.conf",
|
||||
"why": "Cluster filesystem contents, cluster live data, vzdump defaults."
|
||||
"why": "Cluster filesystem contents and vzdump defaults. The pmxcfs database (<code>config.db</code>) is captured as a consistent snapshot via <code>sqlite3 .backup</code> without stopping the cluster, and the <code>.db-wal</code> / <code>.db-shm</code> sidecars are excluded from the rsync. When <code>sqlite3</code> is not available, a <code>config.db.raw-fallback</code> is dropped instead, which the restore promotes automatically."
|
||||
},
|
||||
{
|
||||
"category": "Host identity & network",
|
||||
"paths": "/etc/hostname, /etc/hosts, /etc/timezone, /etc/resolv.conf, /etc/network",
|
||||
"why": "Everything the host needs to come up on the network with the same identity."
|
||||
"paths": "/etc/hostname, /etc/hosts, /etc/timezone, /etc/resolv.conf, /etc/network, /etc/systemd/network",
|
||||
"why": "Everything the host needs to come up on the network with the same identity. The <code>.link</code> files under <code>/etc/systemd/network</code> pin NIC names to their MAC, so reinstalls and hardware changes do not rename interfaces."
|
||||
},
|
||||
{
|
||||
"category": "Access & auth",
|
||||
"paths": "/etc/ssh, /etc/sudoers, /etc/sudoers.d, /etc/pam.d, /etc/security",
|
||||
"why": "SSH keys, sudo rules and PAM configuration. Losing these locks the operator out of the restored host."
|
||||
"why": "SSH keys, sudo rules and PAM configuration. Losing these locks the user out of the restored host."
|
||||
},
|
||||
{
|
||||
"category": "Kernel & boot",
|
||||
@@ -57,7 +57,7 @@
|
||||
{
|
||||
"category": "Packaging & cron",
|
||||
"paths": "/etc/apt, /etc/cron.d, /etc/cron.{daily,hourly,weekly,monthly}, /etc/cron.allow, /etc/cron.deny, /var/spool/cron/crontabs",
|
||||
"why": "APT sources for consistent package resolution, scheduled tasks defined by the operator."
|
||||
"why": "APT sources for consistent package resolution, scheduled tasks defined by the user."
|
||||
},
|
||||
{
|
||||
"category": "ProxMenux state & tools",
|
||||
@@ -78,11 +78,11 @@
|
||||
"customTitle": "Extending the profile with custom paths",
|
||||
"customBody": "Beyond the default profile, ProxMenux offers two ways to include additional paths in a backup. They compose without conflict and both apply to interactive backups and scheduled jobs.",
|
||||
"customExtrasTitle": "1. Persistent extras (per-host file)",
|
||||
"customExtrasBody": "A text file at <code>/usr/local/share/proxmenux/backup-extra-paths.txt</code> holds a list of absolute paths the operator has marked as \"always include\" on this host. When a backup runs in <strong>Default</strong> mode, ProxMenux appends these paths to the default profile automatically without asking. The file is edited from the interface — no manual editing needed — and persists across reboots and updates. One absolute path per line; <code>#</code> comments are allowed.",
|
||||
"customExtrasBody": "A text file at <code>/usr/local/share/proxmenux/backup-extra-paths.txt</code> holds a list of absolute paths the user has marked as \"always include\" on this host. When a backup runs in <strong>Default</strong> mode, ProxMenux appends these paths to the default profile automatically without asking. The file is edited from the interface — no manual editing needed — and persists across reboots and updates. One absolute path per line; <code>#</code> comments are allowed.",
|
||||
"customModeTitle": "2. Custom mode (per-run)",
|
||||
"customModeBody": "Launching a backup in <strong>Custom</strong> mode replaces the automatic application of the default profile with a checklist showing every path: the default-profile entries and the persistent extras (prefixed with <code>[+]</code> and pre-checked). The operator ticks or unticks entries for that specific run, and can also press <em>Add custom path</em> to enter a new path — which is then persisted to the extras file for future backups.",
|
||||
"customModeBody": "Launching a backup in <strong>Custom</strong> mode replaces the automatic application of the default profile with a checklist showing every path: the default-profile entries and the persistent extras (prefixed with <code>[+]</code> and pre-checked). The user ticks or unticks entries for that specific run, and can also press <em>Add custom path</em> to enter a new path — which is then persisted to the extras file for future backups.",
|
||||
"customMissingTitle": "Paths absent from the source",
|
||||
"customMissingBody": "Any path from the profile (default or added) that does not exist on the source host is recorded in <code>metadata/missing_paths.txt</code> inside the archive. The backup neither fails nor stops — the operator sees a summary of archived paths and missing paths at the end. In practice this happens for optional tooling paths like <code>/etc/wireguard</code> or <code>/etc/prometheus</code> when those tools are not installed."
|
||||
"customMissingBody": "Any path from the profile (default or added) that does not exist on the source host is recorded in <code>metadata/missing_paths.txt</code> inside the archive. The backup neither fails nor stops — the user sees a summary of archived paths and missing paths at the end. In practice this happens for optional tooling paths like <code>/etc/wireguard</code> or <code>/etc/prometheus</code> when those tools are not installed."
|
||||
},
|
||||
"manifest": {
|
||||
"heading": "The manifest payload",
|
||||
@@ -102,7 +102,7 @@
|
||||
{
|
||||
"collector": "collect_storage.sh",
|
||||
"produces": "storage_inventory",
|
||||
"content": "ZFS pools (with pool type + member disks resolved to <code>/dev/disk/by-id/*</code> for portability), LVM volume groups + thin pools, physical disks with SMART capability, PVE <code>storage.cfg</code> entries, external mounts."
|
||||
"content": "ZFS pools (with pool type + member disks resolved to <code>/dev/disk/by-id/*</code>, <code>/dev/disk/by-partuuid/*</code> or raw <code>/dev/sdX</code> paths depending on how each pool was originally created), LVM volume groups + thin pools, physical disks with SMART capability, PVE <code>storage.cfg</code> entries, external mounts."
|
||||
},
|
||||
{
|
||||
"collector": "collect_kernel.sh",
|
||||
@@ -157,8 +157,8 @@
|
||||
},
|
||||
"restoreFlow": {
|
||||
"heading": "How the restore consumes the three payloads",
|
||||
"intro": "The restore is a five-stage pipeline. Each stage reads a specific subset of the archive and updates the target host. No stage requires the source host to be reachable — the archive is fully self-contained.",
|
||||
"stagesCaption": "Stage 1 uses the manifest to decide what to touch. Stage 2 copies rootfs paths that are safe to apply on a running system. Stage 3 stages the risky paths for the next boot. Stage 4 handles packages. Stage 5 runs after the reboot and reinstalls components against the target's kernel.",
|
||||
"intro": "The restore is a six-stage pipeline. Each stage reads a specific subset of the archive and updates the target host. No stage requires the source host to be reachable — the archive is fully self-contained.",
|
||||
"stagesCaption": "Stage 1 uses the manifest to decide what to touch. Stage 2 copies rootfs paths that are safe to apply on a running system. Stage 3 stages the risky paths for the next boot. Stage 3b imports non-root ZFS data pools whose disks are all present. Stage 4 handles packages. Stage 5 runs after the reboot and reinstalls components against the target's kernel.",
|
||||
"stageRows": [
|
||||
{
|
||||
"stage": "1",
|
||||
@@ -178,6 +178,12 @@
|
||||
"reads": "rootfs/ (reboot + dangerous paths)",
|
||||
"action": "<code>_rs_prepare_pending_restore</code> stages risky paths under <code>/var/lib/proxmenux/pending-restore/</code>, writes <code>plan.env</code>, <code>apply-on-boot.list</code> and <code>rs-skip-paths.txt</code>, and enables <code>proxmenux-restore-onboot.service</code> to fire on the next boot."
|
||||
},
|
||||
{
|
||||
"stage": "3b",
|
||||
"name": "Data-pool import",
|
||||
"reads": "manifest.storage_inventory + target ZFS state",
|
||||
"action": "<code>_rs_import_data_pools</code> imports every non-root ZFS pool whose full set of disks is present on the target. Pools carrying a foreign hostid are retried with <code>zpool import -f</code>. Pools missing any disk are skipped with a warning. The per-pool outcome is recorded in <code>/var/log/proxmenux/restore-datapools-<timestamp>.log</code>."
|
||||
},
|
||||
{
|
||||
"stage": "4",
|
||||
"name": "Package install",
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
"intro": "A ProxMenux archive is structured around three self-contained payloads. The restore uses all three together to reproduce the source host on a target that may not even have the same kernel installed.",
|
||||
"diagramCaption": "Every backup ships the same three payloads regardless of destination. The restore consumes all three: rootfs to lay down files, manifest to detect drift and cross-kernel differences, and application inventory to re-install packages and components against the target's own kernel.",
|
||||
"pillar1Label": "Filesystem",
|
||||
"pillar1Detail": "rootfs/\n(rsync of\n/etc, /root,\n/var/lib/pve-cluster,\n+ optional paths)",
|
||||
"pillar1Detail": "rootfs/\n(rsync of /etc,\n/etc/systemd/network,\n/root, plus a\nsqlite3 snapshot\nof /var/lib/pve-cluster,\n+ optional paths)",
|
||||
"pillar2Label": "Manifest",
|
||||
"pillar2Detail": "manifest.json\n(hardware, kernel\nparams, network,\nZFS, users, cron,\nZFS pools, storage)",
|
||||
"pillar3Label": "Applications",
|
||||
@@ -44,7 +44,7 @@
|
||||
},
|
||||
"restoreIsUniversal": {
|
||||
"heading": "The restore reproduces the source host, not the archive",
|
||||
"body": "Restoring a ProxMenux backup does not just extract the filesystem. The restore flow reads the manifest to detect drift between the source and the target (hardware differences, NIC renames, kernel version, ZFS pool identity), replays the filesystem, then triggers the correct component installer for every service that was installed on the source (NVIDIA driver, Coral TPU, AMD GPU tools, Intel GPU tools). Each installer runs against the <strong>target's current kernel</strong>, so the restored host does not depend on the source's kernel being present. When the target's kernel is newer than the backup's, a kernel-agnostic <strong>hydration</strong> pass merges the operator's own tuning (IOMMU tokens, VFIO device IDs, custom quirks, GRUB keys) into the target's fresh boot configuration without copying kernel-tied files verbatim."
|
||||
"body": "Restoring a ProxMenux backup does not just extract the filesystem. The restore flow reads the manifest to detect drift between the source and the target (hardware differences, NIC renames, kernel version, ZFS pool identity), replays the filesystem, then triggers the correct component installer for every service that was installed on the source (NVIDIA driver, Coral TPU, AMD GPU tools, Intel GPU tools). Each installer runs against the <strong>target's current kernel</strong>, so the restored host does not depend on the source's kernel being present. When the target's kernel is newer than the backup's, a kernel-agnostic <strong>hydration</strong> pass merges the user's own tuning (IOMMU tokens, VFIO device IDs, custom quirks, GRUB keys) into the target's fresh boot configuration without copying kernel-tied files verbatim."
|
||||
},
|
||||
"twoInterfaces": {
|
||||
"heading": "Two interfaces, one backend",
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -39,7 +39,7 @@
|
||||
"heading": "How attach mode works",
|
||||
"intro": "PVE writes <code>vzdump</code> tasks to <code>/etc/pve/jobs.cfg</code> — one stanza per task, each pointing at a storage where the VM and LXC dumps land. Attach mode requires that storage to be a backend ProxMenux understands (Local or PBS); when the task fires, ProxMenux runs alongside it.",
|
||||
"steps": [
|
||||
{ "step": "1", "detail": "During job creation, ProxMenux lists compatible parent PVE tasks via <code>hb_pve_list_vzdump_jobs_for_backend</code>. The operator picks one." },
|
||||
{ "step": "1", "detail": "During job creation, ProxMenux lists compatible parent PVE tasks via <code>hb_pve_list_vzdump_jobs_for_backend</code>. The user picks one." },
|
||||
{ "step": "2", "detail": "The job's <code>.env</code> is written with <code>PVE_PARENT_JOB</code>, <code>PVE_STORAGE</code> and the inherited <code>KEEP_*</code> values; no systemd timer is created." },
|
||||
{ "step": "3", "detail": "<code>hb_install_vzdump_hook</code> registers a script-hook in <code>/etc/vzdump.conf</code>. When PVE runs any vzdump task, the hook script fires; if the <code>$STOREID</code> passed to it matches an attached job's <code>PVE_STORAGE</code>, the runner is invoked for that job." },
|
||||
{ "step": "4", "detail": "The archive lands in the same storage the vzdump dumps just wrote to: <code>path/dump/</code> for Local, or the PBS repository configured on the PVE storage entry." }
|
||||
@@ -78,7 +78,7 @@
|
||||
},
|
||||
"notifications": {
|
||||
"heading": "Notifications",
|
||||
"body": "Every scheduled run fires the same <code>hb_notify_lifecycle</code> events as the interactive flow (<code>start</code>, <code>complete</code>, <code>fail</code>). If notification channels are configured in the Monitor, unattended jobs surface their results the same way manual backups do — an operator does not need to check the log to know whether a job succeeded."
|
||||
"body": "Every scheduled run fires the same <code>hb_notify_lifecycle</code> events as the interactive flow (<code>start</code>, <code>complete</code>, <code>fail</code>). If notification channels are configured in the Monitor, unattended jobs surface their results the same way manual backups do — an user does not need to check the log to know whether a job succeeded."
|
||||
},
|
||||
"whereNext": {
|
||||
"heading": "Where to go next",
|
||||
|
||||
@@ -153,7 +153,7 @@
|
||||
{
|
||||
"href": "/docs/utils/system-update",
|
||||
"label": "Proxmox System Update (interactive)",
|
||||
"tail": " — wrapper that does all of this with a confirmation dialog and reboot prompt."
|
||||
"tail": " — wrapper that does all of this with a confirmation dialog, an automatic DKMS rebuild of ProxMenux-managed drivers when a new kernel is installed, and a reboot prompt. Also launchable from the Update Now button of the ProxMenux Monitor dashboard."
|
||||
},
|
||||
{
|
||||
"href": "/docs/utils/upgrade-pve8-pve9",
|
||||
|
||||
@@ -57,7 +57,7 @@
|
||||
},
|
||||
"updating": {
|
||||
"heading": "Updating",
|
||||
"body": "ProxMenux self-updates. When a new version is available, you're prompted on the next <code>menu</code> launch and accepting replaces utility files and configurations in place. No manual download needed. Stable users get stable releases; beta users get beta releases (and the auto-switch prompt above when a stable cuts over)."
|
||||
"body": "ProxMenux self-updates. When a new version is available, the next <code>menu</code> launch offers the update; accepting replaces utility files and configurations in place. No manual download needed. Stable users get stable releases; beta users get beta releases (and the auto-switch prompt above when a stable cuts over). The prompt shape depends on where <code>menu</code> runs: over SSH or the Proxmox console it is a classic yes / no dialog, and accepting applies the update immediately. Inside the WebSocket terminal of ProxMenux Monitor it is replaced by an informational msgbox — that terminal cannot survive a self-update mid-flight, so the msgbox shows the canonical one-line installer (<code>bash -c \"$(wget -qLO - https://raw.githubusercontent.com/MacRimi/ProxMenux/main/install_proxmenux.sh)\"</code> for stable, or the equivalent <code>install_proxmenux_beta.sh</code> URL for beta) to run from SSH or console."
|
||||
},
|
||||
"uninstall": {
|
||||
"heading": "Uninstalling",
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
},
|
||||
"intro": {
|
||||
"title": "A real PTY in the browser",
|
||||
"body": "The terminal allocates a server-side PTY through <code>flask_terminal_routes</code>, pipes it over a WebSocket to <code>xterm.js</code> in the browser, and runs as <code>root</code> (the systemd unit's user). Anything you can do in <code>ssh root@<host></code> works here — including <code>vim</code>, <code>tmux</code>, ncurses tools and Proxmox CLIs (<code>qm</code>, <code>pct</code>, <code>pvesh</code>, <code>pvecm</code>)."
|
||||
"body": "The terminal allocates a server-side PTY through <code>flask_terminal_routes</code>, pipes it over a WebSocket to <code>xterm.js</code> in the browser, and runs as <code>root</code> (the systemd unit's user). Anything you can do in <code>ssh root@<host></code> works here — including <code>vim</code>, <code>tmux</code>, ncurses tools and Proxmox CLIs (<code>qm</code>, <code>pct</code>, <code>pvesh</code>, <code>pvecm</code>). Every PTY started from this tab exports the environment variable <code>PROXMENUX_TERMINAL=monitor</code>, which is inherited by every child <code>bash</code> process — including a subsequent <code>menu</code> launch — so ProxMenux flows can tell when they are running inside the Monitor's browser terminal."
|
||||
},
|
||||
"singleAlt": "ProxMenux Monitor Terminal tab — single terminal session showing Fastfetch system summary on login",
|
||||
"singleCaption": "One host terminal open — the toolbar above shows the count (<em>1 / 4 terminals</em>), <em>+ New</em>, <em>Search</em>, <em>Clear</em> and <em>Close</em>. The mobile keyboard helpers appear under the terminal on touch devices.",
|
||||
@@ -19,6 +19,11 @@
|
||||
"body1": "The Terminal tab opens a shell on the <strong>Proxmox host itself</strong> — the same login you would get over SSH. Each tab opens a brand-new host terminal.",
|
||||
"body2": "To reach an <strong>LXC container</strong> from the browser, use the dedicated <em>Console</em> button on every running CT card in the <link>VMs & LXCs tab</link>. It opens a modal that runs <code>pct enter <vmid></code> and reuses the same mobile-friendly toolbar described below."
|
||||
},
|
||||
"menuGuard": {
|
||||
"heading": "Self-update guard when menu runs inside this terminal",
|
||||
"body1": "ProxMenux's <code>menu</code> self-updates in place: accepting the prompt replaces its own script tree and reloads. That works cleanly over SSH or the Proxmox console, but the browser terminal cannot survive it — the update tears down the very PTY the shell is running in, and the WebSocket drops mid-flight. To avoid stranding the session, the internal handlers <code>check_updates_stable</code>, <code>check_updates_beta</code> and <code>apply_release_channel</code> read <code>PROXMENUX_TERMINAL</code> and detect the Monitor context.",
|
||||
"body2": "When they detect it, the classic yes / no dialog is replaced by an informational msgbox with the canonical one-line installer — <code>bash -c \"$(wget -qLO - https://raw.githubusercontent.com/MacRimi/ProxMenux/main/install_proxmenux.sh)\"</code> for stable, and the equivalent <code>install_proxmenux_beta.sh</code> URL for beta. The update itself is deferred to an SSH session or the Proxmox host console; the browser terminal is used only to acknowledge and read the command."
|
||||
},
|
||||
"fourTerminals": {
|
||||
"heading": "Up to four terminals at once",
|
||||
"intro": "The tab lets you open up to four host terminals simultaneously. Each one gets its own PTY and its own WebSocket — they are fully independent sessions. Two layouts switch with the icons next to the \"New\" button:",
|
||||
|
||||
@@ -98,7 +98,7 @@
|
||||
{
|
||||
"category": "System Updates",
|
||||
"checks": "Pending updates, security updates, kernel / PVE version, system age",
|
||||
"events": "Security updates available; pinned kernel several minor versions behind; host uptime > 90 days."
|
||||
"events": "Security updates available; pinned kernel several minor versions behind; host uptime > 90 days. When updates are pending, the Overview header shows an <em>Update Now</em> button that runs the full ProxMenux update flow inline; on close it re-hits the health endpoint with <code>?refresh=1</code> so the badge count reflects the new state without waiting for the next 5-min cycle."
|
||||
},
|
||||
{
|
||||
"category": "Security & Certificates",
|
||||
@@ -151,11 +151,14 @@
|
||||
"<strong>Dismissed</strong> — items previously acknowledged by the user that are still inside their suppression window. Each row shows how much of the suppression remains and the configured duration. When the window expires, the item disappears from this list; if the underlying condition is still present and the category supports re-firing, it re-appears in <em>Active</em>."
|
||||
],
|
||||
"pillTitle": "The pill mirrors the worst category",
|
||||
"pillBody": "The dashboard header colour is the highest severity across the ten categories: any CRITICAL → red, else any WARNING → yellow, else any INFO → blue, else green. The same logic drives the favicon dot and the PWA badge."
|
||||
"pillBody": "The dashboard header colour is the highest severity across the ten categories: any CRITICAL → red, else any WARNING → yellow, else any INFO → blue, else green. The same logic drives the favicon dot and the PWA badge.",
|
||||
"updateNowTitle": "Update Now button in the Overview header",
|
||||
"updateNowBody1": "When the <em>System Updates</em> category reports one or more pending updates, the Overview header renders an <strong>Update Now</strong> button next to the health pill. The button opens a modal that runs the same host-side flow as <em>ProxMenux → Settings post-install Proxmox → Proxmox System Update</em>: repo hygiene, <code>apt full-upgrade</code> via the safe worker <code>update-pve-safe.sh</code>, automatic DKMS rebuild of ProxMenux-managed drivers when a new kernel lands, autoremove / autoclean and a reboot prompt if the kernel changed. Progress lines stream in the modal as the worker prints them.",
|
||||
"updateNowBody2": "When the run finishes, closing the modal calls <code>GET /api/health/details?refresh=1</code>, which invalidates the health-endpoint cache before serving. The pending-updates row and the pill severity are recomputed from the new package state on the spot, so the badge disappears without waiting for the next five-minute cycle. When the host is already up to date, the button is hidden — no visual noise on a healthy system."
|
||||
},
|
||||
"dismiss": {
|
||||
"heading": "Dismissing alerts and the Suppression Duration",
|
||||
"intro": "Some events are noisy by nature — a <em>System Updates: pending updates available</em> stays true until you patch the host, and you don't want a notification every five minutes for a week. The Health Monitor solves this with two coupled mechanisms:",
|
||||
"intro": "Some events are noisy by nature — a <em>System Updates: pending updates available</em> stays true until you patch the host, and you don't want a notification every five minutes for a week. The <em>Update Now</em> button in the Overview header is the direct shortcut to resolve that specific case in place; for everything else, or when patching is deferred, the Health Monitor also offers two coupled silencing mechanisms:",
|
||||
"step1": "<strong>Per-event Dismiss action</strong> in the modal. The Dismiss button opens a small dropdown with three options — <strong>24 hours</strong>, <strong>7 days</strong> or <strong>Permanently</strong> — letting you choose how long this specific alert stays silenced regardless of the category's default. Picking one calls <code>POST /api/health/acknowledge</code> with the <code>error_key</code> and the chosen <code>suppression_hours</code> (<code>-1</code> for permanent). The event moves to the Dismissed list with a timestamped <code>acknowledged_at</code>.",
|
||||
"dropdownImageAlt": "Dismiss dropdown on a Health Monitor alert — 24 hours, 7 days or Permanently",
|
||||
"dropdownImageCaption": "Per-event Dismiss dropdown. The chosen window applies to this single alert; if no per-event window is selected the category's default is used. Permanent dismisses are tagged with a distinct amber <em>Permanent</em> badge in the Dismissed list and never re-fire.",
|
||||
|
||||
@@ -67,7 +67,7 @@
|
||||
},
|
||||
{
|
||||
"tool": "Network stack tuning",
|
||||
"what": "TCP buffer sizing, IPv4 hardening (redirects off, rp_filter=2, martian log off), local port range 1024-65535, TCP MTU probing, RFC 1337, plus a oneshot systemd unit to normalise virtual firewall bridges.",
|
||||
"what": "TCP buffer sizing, IPv4 hardening (redirects off, rp_filter=2, martian log off), local port range 1024-65535, TCP MTU probing, RFC 1337, plus a helper at /usr/local/sbin/proxmenux-fwbr-tune wired to a oneshot systemd unit and a udev rule, so rp_filter=0 / log_martians=0 are re-applied to fwbr*/fwln*/fwpr*/tap* interfaces every time Proxmox recreates them at VM start/stop, reboot or live migration.",
|
||||
"category": "Network",
|
||||
"categorySlug": "network"
|
||||
},
|
||||
@@ -103,7 +103,7 @@
|
||||
},
|
||||
{
|
||||
"tool": "Persistent interface names",
|
||||
"what": "Writes /etc/systemd/network/10-*.link files matching each physical NIC by MAC so eth0 / enp… names stay stable across reboots and new NIC additions.",
|
||||
"what": "Writes one /etc/systemd/network/10-proxmenux-<iface>.link per physical NIC (each starting with a 'Managed by ProxMenux' header) that pins the MAC to the current name, so eth0 / enp… names stay stable across reboots and new NIC additions.",
|
||||
"category": "Network",
|
||||
"categorySlug": "network"
|
||||
}
|
||||
|
||||
@@ -54,6 +54,8 @@
|
||||
}
|
||||
],
|
||||
"sourceOutro": "It also adds <code>source /etc/network/interfaces.d/*</code> to <code>/etc/network/interfaces</code> if not already present — standard practice so you can drop modular interface snippets without editing the main file.",
|
||||
"fwbrTitle": "Automatic tuning of virtual firewall bridges",
|
||||
"fwbrBody": "Alongside the sysctl profile, ProxMenux installs a helper at <code>/usr/local/sbin/proxmenux-fwbr-tune</code> that applies <code>rp_filter=0</code> and <code>log_martians=0</code> to the <code>fwbr*</code> / <code>fwln*</code> / <code>fwpr*</code> / <code>tap*</code> interfaces Proxmox creates around VMs and containers. The helper is invoked by the <code>proxmenux-fwbr-tune.service</code> one-shot unit at boot, and by the <code>/etc/udev/rules.d/99-proxmenux-fwbr-tune.rules</code> rule on every <code>net add</code> event matching those prefixes — covering interfaces that Proxmox recreates on VM start/stop, reboot and live migration.",
|
||||
"rpFilterTitle": "Why rp_filter=2 (loose) instead of 1 (strict)",
|
||||
"rpFilterBody": "Strict reverse-path filtering drops packets whose source would be routed out a <em>different</em> interface. That's the right default on a client machine, but breaks badly on a Proxmox host where VM traffic often arrives on a bridge and leaves on an uplink with asymmetric routes. <code>rp_filter=2</code> (loose) only drops packets with truly unroutable sources. It's a pragmatic trade-off — slight reduction in local-IP-spoof detection in exchange for not breaking your VM network."
|
||||
},
|
||||
@@ -84,14 +86,14 @@
|
||||
"LXC containers with <code>hotplug</code> NICs and bonded links can race on boot and end up named inconsistently. Pinning fixes that."
|
||||
],
|
||||
"writtenTitle": "What gets written",
|
||||
"writtenIntro": "One file per physical NIC, at <code>/etc/systemd/network/10-<iface>.link</code>:",
|
||||
"writtenOutro": "Any pre-existing <code>.link</code> files in that directory are copied to <code>/etc/systemd/network/backup-<timestamp>/</code> before touching anything.",
|
||||
"writtenIntro": "One file per physical NIC, at <code>/etc/systemd/network/10-proxmenux-<iface>.link</code>. Each file starts with the header <code># Managed by ProxMenux — do not edit</code> so ProxMenux can distinguish its own files from user- or package-provided <code>.link</code> files.",
|
||||
"writtenOutro": "<code>.link</code> files from other packages or hand-written by the user are left in place — only files carrying the ProxMenux header are managed. On re-run, the function reconciles its own set: it re-reads <code>MACAddress=</code> from every <code>10-proxmenux-*.link</code> and drops any whose MAC no longer appears under <code>/sys/class/net/</code>. Files written by an earlier ProxMenux release in the old <code>10-<iface>.link</code> format are migrated automatically the first time.",
|
||||
"pveTitle": "PVE 9 vs PVE 8",
|
||||
"pveBody": "On Proxmox VE 9 (<code>systemd-networkd</code> native), the script reloads udev rules after writing the <code>.link</code> files so new hotplug NICs pick up the correct name without a reboot. On PVE 8 (<code>ifupdown2</code>), interface naming is resolved at boot anyway — a reboot is required for the changes to take effect. The script sets the reboot flag either way so Customizable prompts you.",
|
||||
"reviewTitle": "Review existing /etc/network/interfaces first",
|
||||
"reviewBody": "If your host has legacy configuration in <code>/etc/network/interfaces</code> that references NIC names generated by the kernel's default scheme, pinning <em>today's</em> names is exactly what you want. But if you've already manually customised the config around specific names, double-check the pinning matches what the interfaces file expects before rebooting.",
|
||||
"revertTitle": "Reversible from the Uninstall menu",
|
||||
"revertBody": "<link>Uninstall Optimizations</link> deletes every <code>.link</code> file from <code>/etc/systemd/network/</code>, restoring the kernel's default naming on next reboot. The timestamped backup of the original files stays behind in case you need to restore specific ones manually."
|
||||
"revertBody": "<link>Uninstall Optimizations</link> deletes only the <code>10-proxmenux-*.link</code> files carrying the ProxMenux header from <code>/etc/systemd/network/</code>. Any <code>.link</code> file added by the user or by another package is preserved. Interface names return to systemd's default behaviour on next reboot."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
|
||||
@@ -145,10 +145,11 @@
|
||||
"doesLabel": "What ProxMenux does:",
|
||||
"doesItems": [
|
||||
"Detects whether the root disk is SSD/NVMe by reading <code>/sys/block/<dev>/queue/rotational</code>. On a rotational disk the Automated flow asks first before installing.",
|
||||
"Clones the upstream repository (<code>azlux/log2ram</code>) into <code>/tmp/log2ram</code> and runs its <code>install.sh</code>, then enables the <code>log2ram</code> systemd unit.",
|
||||
"Clones the upstream repository (<code>azlux/log2ram</code>) into <code>/tmp/log2ram</code> and patches its <code>install.sh</code>, replacing <code>rsync -aAXv</code> with <code>rsync -aXv --no-acls</code>. That adjustment avoids the <em>set_acl: Operation not supported</em> exit 23 failure that the vanilla script triggers when moving /var/log on filesystems without ACL support. The <code>log2ram</code> systemd unit is enabled after install.",
|
||||
"Sizes the ramdisk based on host RAM: <code>≤ 8 GB → 128M</code>, <code>≤ 16 GB → 256M</code>, <code>> 16 GB → 512M</code>. Writes the value to <code>SIZE=</code> in <code>/etc/log2ram.conf</code>.",
|
||||
"Schedules a periodic disk sync via <code>/etc/cron.d/log2ram</code>: every 1h / 3h / 6h according to the same RAM tier.",
|
||||
"Installs an auto-sync guard at <code>/usr/local/bin/log2ram-check.sh</code>, wired to <code>/etc/cron.d/log2ram-auto-sync</code> to run every 10 minutes. When <code>/var/log</code> reaches 80% of the ramdisk size the guard vacuums journald; at 92% it also truncates <code>pveproxy access/error</code> and <code>pveam.log</code> before syncing — the plain <code>log2ram write</code> command copies tmpfs to disk but does NOT shrink the tmpfs, so this guard prevents PVE from crashing with <em>No space left on device</em> when logs grow uncontrolled.",
|
||||
"Installs an auto-sync guard at <code>/usr/local/bin/log2ram-check.sh</code>, wired to <code>/etc/cron.d/log2ram-auto-sync</code> to run every 10 minutes. When <code>/var/log</code> reaches 80% of the ramdisk size the guard vacuums journald; at 92% it first runs <code>logrotate -f /etc/logrotate.d/proxmox-backup-api</code> when that file exists (forcing rotation of the PBS API logs, typically the largest consumer on a host running PBS) and then truncates <code>pveproxy access/error</code> and <code>pveam.log</code> before syncing. The plain <code>log2ram write</code> command copies tmpfs to disk but does NOT shrink the tmpfs, so this guard prevents PVE from crashing with <em>No space left on device</em> when logs grow uncontrolled.",
|
||||
"Detects whether <code>proxmox-backup-server</code> runs as a service on the host. When present, drops <code>/etc/logrotate.d/proxmox-backup-api</code> (20 MB × 3 rotation) and <code>/etc/cron.hourly/proxmox-backup-logrotate</code>, so the PBS API logs — the usual source of growth on a PBS host — stay bounded even between Log2RAM's periodic syncs. On hosts without PBS this step is a no-op.",
|
||||
"Adjusts systemd-journald limits (<code>SystemMaxUse</code>, <code>RuntimeMaxUse</code>) to fit within the ramdisk so a single burst cannot fill it.",
|
||||
"Registers itself in <code>installed_tools.json</code> so it can be reverted from Uninstall Optimizations."
|
||||
],
|
||||
|
||||
@@ -18,30 +18,26 @@
|
||||
"intro": "The <strong>Adaptive Replacement Cache (ARC)</strong> is ZFS's in-memory read cache. Without explicit tuning, ZFS happily grabs up to half the host RAM for itself, which is excessive on a Proxmox host that also needs memory for VMs and LXCs. This option caps ARC to a sane fraction of total RAM based on the size of the machine.",
|
||||
"sizingTitle": "Sizing rules",
|
||||
"headerRam": "Host RAM",
|
||||
"headerMin": "ARC min",
|
||||
"headerMax": "ARC max",
|
||||
"headerMax": "ARC cap",
|
||||
"rows": [
|
||||
{
|
||||
"ram": "≤ 16 GB",
|
||||
"min": "512 MB",
|
||||
"max": "512 MB"
|
||||
"max": "512 MiB"
|
||||
},
|
||||
{
|
||||
"ram": "17 – 32 GB",
|
||||
"min": "1 GB",
|
||||
"max": "1 GB"
|
||||
"max": "1 GiB"
|
||||
},
|
||||
{
|
||||
"ram": "> 32 GB",
|
||||
"min": "RAM / 16",
|
||||
"max": "RAM / 8"
|
||||
"max": "RAM / 8 (floor 512 MiB)"
|
||||
}
|
||||
],
|
||||
"after": "On a 64 GB host, that means 4 GB min / 8 GB max for ARC. The config is written to <code>/etc/modprobe.d/99-zfsarc.conf</code> and enables a few extra ZFS tunables (L2ARC prefetch on, L2ARC write max at 500 MB, longer TXG timeout).",
|
||||
"after": "On a 64 GB host, that means an 8 GB cap for ARC. The file <code>/etc/modprobe.d/99-zfsarc.conf</code> contains a single directive — <code>options zfs zfs_arc_max=…</code>. Every other ZFS module parameter (<code>zfs_arc_min</code>, L2ARC prefetch/write throttle, TXG timeout) is left at its OpenZFS default. After writing the file, ProxMenux runs <code>update-initramfs -u -k all</code> and, when applicable, <code>proxmox-boot-tool refresh</code>, so the cap also lands in the initramfs used by ZFS-on-root setups.",
|
||||
"rebootTitle": "Requires a reboot to take effect",
|
||||
"rebootBody": "ARC settings are read when the <code>zfs</code> kernel module loads. They do <strong>not</strong> apply on a live system — you'll need to reboot the host for the cap to kick in. The script sets the \"reboot required\" flag automatically.",
|
||||
"rebootBody": "ARC settings are read when the <code>zfs</code> kernel module loads. To make the cap take effect on ZFS-on-root hosts, ProxMenux regenerates the initramfs with <code>update-initramfs -u -k all</code> and, when applicable, refreshes the boot loader with <code>proxmox-boot-tool refresh</code>. A reboot is still required to pick up the new module parameter; the \"reboot required\" flag is set automatically.",
|
||||
"safeTitle": "Safe on non-ZFS hosts",
|
||||
"safeBody": "The function checks for the <code>zfs</code> command before touching anything. On ext4 / LVM-only Proxmox hosts, ticking this option is a no-op — nothing gets written.",
|
||||
"safeBody": "The function only writes the config when <code>zpool list</code> reports at least one imported ZFS pool. On ext4 / LVM-only Proxmox hosts, or on machines with the ZFS tools installed but no pool imported, ticking this option is a no-op — nothing gets written.",
|
||||
"verifyTitle": "Verification and manual rollback"
|
||||
},
|
||||
"autoSnap": {
|
||||
|
||||
@@ -88,11 +88,11 @@
|
||||
"items": [
|
||||
{
|
||||
"tool": "Network Optimizations",
|
||||
"restores": "Removes /etc/sysctl.d/99-network.conf and the proxmenux-fwbr-tune.service unit. Reloads sysctl and systemd."
|
||||
"restores": "Removes /etc/sysctl.d/99-network.conf together with the proxmenux-fwbr-tune.service unit, the /usr/local/sbin/proxmenux-fwbr-tune helper and the /etc/udev/rules.d/99-proxmenux-fwbr-tune.rules udev rule. Reloads sysctl, systemd and the udev ruleset."
|
||||
},
|
||||
{
|
||||
"tool": "Persistent Interface Names",
|
||||
"restores": "Removes every .link file from /etc/systemd/network/. Interface names return to systemd's default behaviour on next reboot."
|
||||
"restores": "Removes only the 10-proxmenux-*.link files carrying the ProxMenux header from /etc/systemd/network/. Any .link file provided by another package or written by the user is left in place. Interface names return to systemd's default behaviour on next reboot."
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -171,7 +171,7 @@
|
||||
"packageTitle": "Package reinstall touches live Proxmox packages",
|
||||
"packageBody": "Reverting <strong>Subscription Banner Removal</strong> reinstalls <code>pve-manager</code>, <code>proxmox-widget-toolkit</code>, <code>libjs-extjs</code> and <code>libpve-http-server-perl</code> with <code>--force-confnew</code>. This is generally safe but does touch the running web UI — refresh your browser afterwards, and expect a few seconds of reconnection. Don't run this in the middle of a migration or clone operation.",
|
||||
"rebootTitle": "Persistent names and VFIO need a reboot",
|
||||
"rebootBody": "Removing the <code>.link</code> files (<em>Persistent Interface Names</em>) and reverting <em>IOMMU/VFIO</em> do not affect the running system — they only matter after a reboot. ProxMenux sets the reboot flag automatically for these.",
|
||||
"rebootBody": "Removing ProxMenux's <code>10-proxmenux-*.link</code> files (<em>Persistent Interface Names</em>) and reverting <em>IOMMU/VFIO</em> do not affect the running system — they only matter after a reboot. ProxMenux sets the reboot flag automatically for these.",
|
||||
"perItemTitle": "You can revert one thing and keep the rest",
|
||||
"perItemBody": "The uninstaller operates per-item. If you only want to remove Log2RAM but keep the network tuning and bashrc changes, tick only <em>Log2RAM</em>. Nothing else is touched, and the registry is updated accordingly."
|
||||
},
|
||||
|
||||
@@ -53,7 +53,8 @@
|
||||
"Your existing config, ProxMenux Monitor login (<code>auth.json</code>), notification channels, post-install registry, custom thresholds — none of those are touched. The channel switch only swaps the script tree and the binary AppImage.",
|
||||
"A Monitor that was active before the switch stays active after; one that was deactivated stays deactivated.",
|
||||
"ProxMenux Monitor <code>auth.json</code>, API tokens and the JWT secret are preserved across channel changes. Sessions don't get logged out.",
|
||||
"You can flip channels as many times as you like — the dialog will accept it every time and rerun the installer. No restart of Proxmox is required."
|
||||
"You can flip channels as many times as you like — the dialog will accept it every time and rerun the installer. No restart of Proxmox is required.",
|
||||
"The channel switch installer replaces ProxMenux's own script tree, so it cannot run inside the Monitor's browser terminal (that PTY would be torn down mid-update and leave the dialog stranded). If you launch the option from there, the confirmation is replaced by an informational msgbox showing the canonical one-line installer for the target channel; run that command from an SSH session or the Proxmox host console."
|
||||
]
|
||||
},
|
||||
"feedback": {
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
},
|
||||
"header": {
|
||||
"title": "Proxmox System Update",
|
||||
"description": "Wrapper that detects the running Proxmox major version and delegates to the matching worker (PVE 8 or PVE 9). Repos are cleaned up, the no-subscription source is enabled, all packages are upgraded, conflicting packages are removed, and the system is cleaned up afterwards. A reboot prompt fires only when the kernel was actually updated.",
|
||||
"description": "Wrapper that delegates to a single safe worker (<code>update-pve-safe.sh</code>) which detects the running Proxmox major version by itself. Repositories are cleaned up when they overlap with the base Proxmox / Debian sources, all packages are upgraded, ProxMenux-managed DKMS drivers are rebuilt if a new kernel landed, and the reboot prompt fires only when the kernel actually changed. Also launchable from the <em>Update Now</em> button in the ProxMenux Monitor dashboard header when pending updates are detected.",
|
||||
"section": "Utilities"
|
||||
},
|
||||
"calloutWhat": {
|
||||
@@ -22,15 +22,15 @@
|
||||
},
|
||||
"onTop": {
|
||||
"heading": "What ProxMenux runs on top — verified against the script",
|
||||
"intro": "This option runs <strong>exactly</strong> the apt command above, wrapped with the repo hygiene and post-upgrade cleanup the official upgrade guide also recommends. The list below maps 1:1 to <code>scripts/utilities/proxmox_update.sh</code> and the per-version worker scripts — nothing implied, every step is in the code:",
|
||||
"intro": "This option runs <strong>exactly</strong> the apt command above, wrapped with the repo hygiene, DKMS rebuild for ProxMenux-managed drivers and post-upgrade cleanup the official upgrade guide also recommends. Everything below maps 1:1 to <code>scripts/utilities/proxmox_update.sh</code> and the single safe worker <code>scripts/global/update-pve-safe.sh</code> — nothing implied, every step is in the code:",
|
||||
"items": [
|
||||
"<strong>Detects the PVE major version</strong> (<code>pveversion | grep -oP ''pve-manager/\\K[0-9]+''</code>) and dispatches to <code>update-pve8.sh</code> or <code>update-pve9_2.sh</code> so the right codename and repo URLs are used.",
|
||||
"<strong>Cleans up repositories</strong> before touching apt: disables the enterprise source (which 401s without a subscription), removes legacy repo files, and writes a clean no-subscription source for the host's codename.",
|
||||
"<strong>Runs the upgrade non-interactively</strong> with <code>DEBIAN_FRONTEND=noninteractive</code> and <code>--force-confdef --force-confold</code> — meaning if a configuration file you already modified also changed upstream, your version stays in place. No silent overwrites of custom configs.",
|
||||
"<strong>Installs essential Proxmox packages</strong> if any are missing (<code>zfsutils-linux</code>, <code>proxmox-backup-restore-image</code>, <code>chrony</code>).",
|
||||
"<strong>Detects the PVE major version</strong> from inside the worker (<code>pveversion | grep -oP ''pve-manager/\\K[0-9]+''</code>) and adapts the base Proxmox / Debian repo URLs (bookworm on PVE 8, trixie on PVE 9). There is no fan-out to per-version worker scripts — a single safe worker handles both.",
|
||||
"<strong>Cleans up repositories in a conservative way.</strong> <code>ensure_repositories</code> runs first but only when the base Proxmox / Debian sources are missing — a bare host gets them written, a configured host is a no-op. <code>cleanup_duplicate_repos</code> then removes exact URL + Suite + Component duplicates only against <code>proxmox.sources</code> / <code>debian.sources</code>; user-authored files (enterprise, Ceph, alternative NTP mirrors, custom <code>download.proxmox.com/*</code> entries or hand-written <code>pve-*.list</code>) are left untouched, and every file is backed up before being edited.",
|
||||
"<strong>Runs the upgrade non-interactively</strong> with <code>DEBIAN_FRONTEND=noninteractive</code> and <code>--force-confdef --force-confold</code> — if a configuration file you already modified also changed upstream, your version stays in place. No silent overwrites of custom configs.",
|
||||
"<strong>Skips forcing optional utilities.</strong> The safe worker does not push <code>zfsutils-linux</code>, <code>chrony</code>, <code>ifupdown2</code> or similar packages onto the host — a Proxmox install that opted out of any of them keeps its choice. Missing packages are surfaced by the higher-level installer flows, not by the update path.",
|
||||
"<strong>LVM metadata sanity check</strong> against stray PV headers from passthrough disks (warn-only, no automatic fix).",
|
||||
"<strong>Cleans up afterwards:</strong> <code>apt-get autoremove -y</code> + <code>apt-get autoclean -y</code>.",
|
||||
"<strong>Reboot prompt</strong> only if the kernel actually changed (<code>/var/run/reboot-required</code> present or <code>linux-image</code> in the upgrade log)."
|
||||
"<strong>DKMS rebuild before the reboot prompt.</strong> When the upgrade staged a new kernel, the wrapper calls <code>pmx_rebuild_dkms_after_kernel</code> to rebuild every driver that ProxMenux installed via DKMS against the incoming kernel version — so the modules are ready before the box comes back up. Reboot detection uses <code>/var/run/reboot-required</code> when <code>needrestart</code> is present, and falls back to a <code>dpkg-query</code> comparison between the running kernel and the newest installed <code>proxmox-kernel-*-pve-signed</code> / <code>pve-kernel-*-pve</code> package when it isn't — a signal that survives the many Proxmox hosts that ship without <code>needrestart</code>."
|
||||
]
|
||||
},
|
||||
"calloutOneSentence": {
|
||||
@@ -50,8 +50,8 @@
|
||||
"detail": "pveversion |\ngrep -oP ''pve-manager/\\K[0-9]+''"
|
||||
},
|
||||
"bridge": {
|
||||
"label": "Worker selection",
|
||||
"detail": "PVE 8 → update-pve8.sh\nPVE 9 → update-pve9_2.sh"
|
||||
"label": "Single safe worker",
|
||||
"detail": "update-pve-safe.sh\n(detects PVE 8 / 9\ninternally)"
|
||||
},
|
||||
"target": {
|
||||
"label": "Post-update",
|
||||
@@ -61,13 +61,18 @@
|
||||
},
|
||||
"worker": {
|
||||
"heading": "What the worker does",
|
||||
"intro": "Both workers (<code>scripts/global/update-pve8.sh</code> for PVE 8 and <code>scripts/global/update-pve9_2.sh</code> for PVE 9) follow the same outline, with version-appropriate repo URLs and package names:",
|
||||
"intro": "A single worker (<code>scripts/global/update-pve-safe.sh</code>) handles both PVE 8 and PVE 9. It detects the major version internally and uses the version-appropriate codename (<code>bookworm</code> or <code>trixie</code>) for its base sources. The stages are:",
|
||||
"items": [
|
||||
"<strong>Repo hygiene.</strong> Removes duplicate entries from <code>/etc/apt/sources.list</code> and <code>/etc/apt/sources.list.d/</code>. Comments out the enterprise repo if the host has no subscription and writes / enables the no-subscription source.",
|
||||
"<strong>Apt update + full-upgrade.</strong> Pulls the latest package lists and applies all available upgrades for the current major version, running with <code>DEBIAN_FRONTEND=noninteractive</code> and <code>--force-confdef --force-confold</code> so any configuration file you customised keeps its current contents when upstream also changed it.",
|
||||
"<strong>Essential packages check.</strong> Installs <code>zfsutils-linux</code>, <code>chrony</code>, <code>ifupdown2</code> and a few others if the host is missing them.",
|
||||
"<strong>LVM / storage sanity check.</strong> Repairs missing PV headers if detected.",
|
||||
"<strong>Conflicting package removal.</strong> Drops packages known to clash on Proxmox (e.g. some time-sync daemons that fight chrony)."
|
||||
"<strong>Sanity checks.</strong> Verifies at least ~1 GB free in <code>/var/cache/apt/archives</code> and pings <code>download.proxmox.com</code>. Aborts early with a clear message when either fails, so the run doesn't die in the middle of an apt transaction.",
|
||||
"<strong>Repo bootstrap.</strong> <code>ensure_repositories</code> writes the base Proxmox / Debian sources only when they are missing (a fresh or hand-cleaned host); on a configured host it does nothing.",
|
||||
"<strong>Apt update with GPG auto-recovery.</strong> On <code>NO_PUBKEY</code> for any repo (yours or a third-party one) the worker imports the missing key and retries automatically before failing.",
|
||||
"<strong>Conservative duplicate cleanup.</strong> <code>cleanup_duplicate_repos</code> only removes exact URL + Suite + Component matches against <code>proxmox.sources</code> / <code>debian.sources</code>. User-authored files — enterprise, Ceph, alternative NTP mirrors, custom <code>download.proxmox.com/*</code> entries, hand-written <code>pve-*.list</code> — are left intact. Every file is backed up before modification.",
|
||||
"<strong>Pending upgrades + security count.</strong> Reports how many packages will change and how many of those come from the security suite, so the confirmation dialog has real numbers to show.",
|
||||
"<strong>Confirmation dialog.</strong> The wrapper asks for an explicit yes before touching apt.",
|
||||
"<strong>apt full-upgrade.</strong> Runs with <code>DEBIAN_FRONTEND=noninteractive</code> and <code>--force-confdef --force-confold</code> so any configuration file you customised keeps its current contents when upstream also changed it. Never overwrites operator-edited configs silently.",
|
||||
"<strong>LVM sanity check.</strong> <code>lvm_repair_check</code> refreshes VG metadata when disks passed through to guest VMs (DSM, TrueNAS, storage appliances) come back with old PV headers.",
|
||||
"<strong>DKMS rebuild for ProxMenux-managed drivers.</strong> When the upgrade staged a new kernel, <code>pmx_rebuild_dkms_after_kernel</code> reads <code>components_status.json</code> for the drivers ProxMenux installed (currently <code>nvidia_driver</code> → module <code>nvidia</code>, <code>coral_driver</code> → module <code>gasket</code>), installs the matching kernel headers (<code>proxmox-headers-<newkver></code> when available, else <code>pve-headers-<newkver></code>) and runs <code>dkms autoinstall -k <newkver></code>. If <code>dkms status</code> then doesn't show the modules built against the new kernel, the worker falls back to re-running each installer with <code>--auto-reinstall</code>. Any failure is logged but does not abort the update — you land on the reboot prompt in every case.",
|
||||
"<strong>Post-cleanup.</strong> <code>apt-get autoremove</code> + <code>apt-get autoclean</code> before returning control to the wrapper."
|
||||
]
|
||||
},
|
||||
"post": {
|
||||
@@ -91,14 +96,14 @@
|
||||
"body": "Running on an old kernel after upgrading <code>linux-image-*</code> means you're on a half-upgraded system: userspace is new, kernel is old. Most of the time things work, but ZFS modules, IOMMU groups, KSMBD and any out-of-tree drivers will only match the kernel they were built for — a mismatch produces obscure failures. Reboot at the earliest sensible moment."
|
||||
},
|
||||
"noSub": {
|
||||
"heading": "When the no-subscription switch happens",
|
||||
"intro": "Proxmox ships hosts with the enterprise repo enabled by default. Without a paid subscription, that repo returns 401 on <code>apt-get update</code>. The worker detects this and:",
|
||||
"heading": "How the safe worker treats the enterprise repo",
|
||||
"intro": "Proxmox ships hosts with the enterprise repo enabled by default. Without a paid subscription, that repo returns 401 on <code>apt-get update</code>. The safe worker deliberately does <strong>not</strong> touch enterprise or Ceph repositories — a host running with a real subscription must not have its config silently rewritten. What happens instead:",
|
||||
"items": [
|
||||
"Comments out (or disables) <code>/etc/apt/sources.list.d/pve-enterprise.list</code> (or the deb822 equivalent)",
|
||||
"Writes <code>/etc/apt/sources.list.d/pve-no-subscription.list</code> (or the deb822 <code>proxmox.sources</code> for PVE 9) with the matching codename (<code>bookworm</code> for PVE 8, <code>trixie</code> for PVE 9)",
|
||||
"Re-runs <code>apt-get update</code>"
|
||||
"On a <strong>bare host</strong> with no base Proxmox / Debian sources at all, <code>ensure_repositories</code> writes the no-subscription source in the deb822 format (<code>proxmox.sources</code>) with the codename matching the detected major version (<code>bookworm</code> for PVE 8, <code>trixie</code> for PVE 9) and the matching Debian sources.",
|
||||
"On a <strong>configured host</strong>, <code>ensure_repositories</code> is a no-op — whatever the operator chose (no-subscription, enterprise, or a mix) is preserved.",
|
||||
"The enterprise <code>pve-enterprise.sources</code> / <code>ceph.sources</code> files are never modified by the update path. The removal of the enterprise repo when it's unwanted is handled elsewhere in ProxMenux (the Automated post-install script), not here."
|
||||
],
|
||||
"outro": "If you have a paid subscription, comment out the no-subscription source and uncomment the enterprise one before running this option."
|
||||
"outro": "If you have a paid subscription, keep <code>pve-enterprise.sources</code> enabled and the safe worker will let it drive the upgrade unchanged. If you don't, either run the Automated post-install first (it does the switch and records it) or comment the enterprise source out manually — the update path will not do it for you."
|
||||
},
|
||||
"cluster": {
|
||||
"heading": "Cluster considerations",
|
||||
@@ -127,7 +132,7 @@
|
||||
},
|
||||
{
|
||||
"title": "Kernel upgraded but the new modules are missing for an out-of-tree driver",
|
||||
"body": "Out-of-tree modules (NVIDIA, ZFS via DKMS, custom NIC drivers) need to be rebuilt against the new kernel. Most are handled automatically by DKMS during the upgrade — confirm with <code>dkms status</code>. If something is missing: <code>dkms autoinstall</code>."
|
||||
"body": "The drivers ProxMenux installed via DKMS (currently <code>nvidia_driver</code> and <code>coral_driver</code>) are rebuilt automatically at the end of the upgrade against the incoming kernel version, using <code>dkms autoinstall -k <newkver></code> and, when needed, a fallback to each installer with <code>--auto-reinstall</code>. Confirm with <code>dkms status</code>. Third-party out-of-tree modules that aren't in ProxMenux's <code>components_status.json</code> registry (custom NIC drivers, hand-installed DKMS packages, …) still need a manual <code>dkms autoinstall</code> — the safe worker only touches what it originally installed."
|
||||
},
|
||||
{
|
||||
"title": "The reboot prompt didn't appear but I'm sure the kernel changed",
|
||||
@@ -137,7 +142,7 @@
|
||||
},
|
||||
"files": {
|
||||
"heading": "Files involved",
|
||||
"code": "scripts/utilities/proxmox_update.sh # this script (wrapper)\nscripts/global/update-pve8.sh # worker for PVE 8 hosts\nscripts/global/update-pve9_2.sh # worker for PVE 9 hosts\nscripts/global/common-functions.sh # cleanup_duplicate_repos used by workers\n/etc/apt/sources.list # may be edited\n/etc/apt/sources.list.d/* # may be edited / created\n/var/run/reboot-required # read to decide on reboot prompt\n/var/log/apt/history.log # read to detect kernel changes"
|
||||
"code": "scripts/utilities/proxmox_update.sh # this script (wrapper)\nscripts/global/update-pve-safe.sh # single safe worker (PVE 8 + PVE 9)\nscripts/global/common-functions.sh # cleanup_duplicate_repos used by the worker\nscripts/global/utils-install-functions.sh # ensure_repositories + pmx_rebuild_dkms_after_kernel\n/usr/local/share/proxmenux/components_status.json # ProxMenux-managed DKMS driver registry\n/etc/apt/sources.list.d/proxmox.sources # deb822 no-subscription source (bare-host bootstrap)\n/etc/apt/sources.list.d/debian.sources # deb822 Debian sources (bare-host bootstrap)\n/var/run/reboot-required # read to decide on reboot prompt\n# Reboot fallback when needrestart isn't installed:\n# dpkg-query -W 'proxmox-kernel-*-pve-signed' 'pve-kernel-*-pve' vs. uname -r"
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
|
||||
Reference in New Issue
Block a user