"title":"Proxmox System Update | ProxMenux Documentation",
"description":"Runs the official Proxmox upgrade sequence (apt update + apt full-upgrade -y) and adds the repo hygiene, essential-package check, LVM sanity scan, autoremove/autoclean and reboot prompt that the upgrade guide also recommends. Detects the running major version automatically.",
"ogTitle":"Proxmox System Update | ProxMenux Documentation",
"ogDescription":"Official apt full-upgrade / dist-upgrade wrapped with repo hygiene, autoremove and a smart reboot prompt."
"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.",
"body":"Brings the host to the latest patch level of its current major version. Does <strong>not</strong> upgrade across major versions — for PVE 8 → PVE 9 see <link>Upgrade PVE 8 to PVE 9</link>."
},
"official":{
"heading":"The official Proxmox recommendation",
"intro":"Proxmox's own upgrade guidance for a running host (within the same major version) is to run:",
"code":"apt update && apt full-upgrade -y",
"outro":"That one line is the official command on any current Proxmox release. The hard part isn't the upgrade itself; it's making sure the repositories are clean, the right ones are enabled, and the host is in a sensible state afterwards."
},
"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, 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:",
"<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>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>."
"body":"Same upgrade Proxmox tells you to run, plus the repo cleanup, the essential-package check, the LVM sanity scan, the autoremove/autoclean afterwards, and a reboot prompt only when it matters."
},
"confirm":{
"heading":"Confirmation dialog",
"intro":"Selecting the option opens a summary of what the worker will do, requiring an explicit confirmation:",
"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:",
"<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."
"intro":"After the worker exits, the wrapper runs:",
"code":"apt-get autoremove -y # drop unused dependencies pulled in by old packages\napt-get autoclean # drop downloaded .deb files no longer in the index",
"afterCode":"Then it checks whether a reboot is needed. Two signals trigger the prompt:",
"items":[
"<code>/var/run/reboot-required</code> exists (created by the kernel package post-install hook)",
"The update log contains <code>linux-image</code> entries (kernel was actually upgraded)"
],
"outro":"If either is true, a whiptail dialog asks <em>\"Some changes require a reboot to take effect. Do you want to restart now?\"</em>. Decline to keep running on the old kernel until you choose to reboot manually (e.g. during a planned maintenance window)."
},
"end":{
"heading":"What you see at the end",
"intro":"When the worker finishes, the terminal shows the cleanup output and (if the kernel changed) the reboot prompt:",
"imageAlt":"Proxmox System Update completion summary with cleanup output and reboot prompt"
},
"calloutDeclineReboot":{
"title":"Decline reboot only if you know why",
"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."
"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:",
"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, 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."
"calloutTitle":"On clusters: update one node at a time",
"calloutBody":"On a Proxmox cluster, run this option on <strong>one node at a time</strong> and wait for the reboot to complete before moving to the next. Migrate guests off the node first to avoid cluster-wide service disruption. Mixed minor versions (e.g. 8.4.1 and 8.4.5) work fine for hours; mixed running kernels can produce unexpected behaviour for HA-managed guests."
},
"doesnt":{
"heading":"What it doesn't do",
"items":[
"<strong>Major-version upgrade.</strong> 8 → 9 is a separate operation — see <link>Upgrade PVE 8 to PVE 9</link>.",
"<strong>Backup.</strong> No snapshots, no rollback. Apt operations are not transactional. Combine with your normal backup discipline (PBS, vzdump, ZFS snapshots).",
"<strong>Container / VM updates.</strong> Only the host is upgraded; guests are left alone.",
"<strong>Firmware updates.</strong> CPU microcode, NIC firmware, BIOS — out of scope."
]
},
"troubleshooting":{
"heading":"Troubleshooting",
"items":[
{
"title":"apt update fails with 401 Unauthorized",
"body":"The enterprise repo is still enabled but you don't have a subscription. The worker should detect and switch automatically; if it didn't, comment the line in <code>/etc/apt/sources.list.d/pve-enterprise.list</code> (or set <code>Enabled: false</code> in the deb822 <code>pve-enterprise.sources</code>) and re-run."
},
{
"title":"dist-upgrade hangs at \"Configuring grub-pc\"",
"body":"A dpkg prompt is asking which device(s) to install GRUB to. The wrapper passes <code>--force-confold</code> for config files but boot-loader install is a separate prompt. Use <kbd>Tab</kbd> + <kbd>Space</kbd> to select all your boot disks, then OK. Best avoided by selecting the boot disks once with <code>dpkg-reconfigure grub-pc</code> beforehand."
},
{
"title":"Kernel upgraded but the new modules are missing for an out-of-tree driver",
"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",
"body":"Two signals must agree (<code>/var/run/reboot-required</code> and <code>linux-image</code> in the upgrade log). If the marker file was cleared but the log is being parsed wrong, reboot manually with <code>shutdown -r now</code>. To confirm a kernel upgrade happened: <code>grep linux-image /var/log/apt/history.log</code>."
