chore: follow-ups to #406, #407 and #415 — locale cleanup, journal entry, pigz 1.1 and docs

This commit is contained in:
MacRimi
2026-10-01 23:06:49 +02:00
parent b7e053b88a
commit 96f3d82e15
29 changed files with 254 additions and 130 deletions
@@ -60,6 +60,7 @@
"title": "Prepare the system",
"body": "Behind a single confirmation, the script:",
"items": [
"Checks the repositories of the host before anything is removed or installed: a host with no active subscription and only the Enterprise repository is asked before switching to no-subscription, and the installation stops when the switch is declined.",
"Installs <code>pve-headers-$(uname -r)</code> (or <code>proxmox-headers-$(uname -r)</code>), <code>build-essential</code> and <code>dkms</code>.",
"Creates the ProxMenux-owned <code>/etc/modprobe.d/proxmenux-nouveau-blacklist.conf</code> with <code>blacklist nouveau</code> and <code>options nouveau modeset=0</code>, records whether it added the companion line to <code>blacklist.conf</code>, and tries to unload the module immediately.",
"Writes <code>/etc/modules-load.d/nvidia-vfio.conf</code> with <code>nvidia</code> and <code>nvidia_uvm</code> so the modules load early at boot."
@@ -400,7 +400,43 @@
"events": "<code>gpu_mode_switch</code>, <code>gpu_passthrough_blocked</code>, <code>pci_passthrough_conflict</code>, <code>ai_model_migrated</code>."
}
],
"burstNote": "A handful of <code>burst_*</code> aggregation types (<code>burst_auth_fail</code>, <code>burst_ip_block</code>, <code>burst_disk_io</code>, etc.) exist only in the dispatcher — they replace bursts of individual events with a single summary message and are not exposed as toggles in the UI. They inherit the on/off state of their parent event type."
"burstNote": "A handful of <code>burst_*</code> aggregation types (<code>burst_auth_fail</code>, <code>burst_ip_block</code>, <code>burst_disk_io</code>, etc.) exist only in the dispatcher — they replace bursts of individual events with a single summary message and are not exposed as toggles in the UI. They inherit the on/off state of their parent event type.",
"backupResults": {
"heading": "Backup results",
"intro": "A notification about a Proxmox backup job states how the job ended. The result is read from the report Proxmox sends, and it sets the title, the icon shown with <em>Rich messages</em> on, and the status row of the email.",
"headerIcon": "Icon",
"headerResult": "Result",
"headerWhen": "When",
"rows": [
{
"icon": "💾✅",
"result": "Backup complete",
"when": "Every guest of the job finished and the report carries no warnings."
},
{
"icon": "💾⚠️",
"result": "Backup completed with warnings",
"when": "Every guest finished and the report carries at least one warning line."
},
{
"icon": "💾❌",
"result": "Backup error reported",
"when": "A guest failed, or the job stopped with an error."
},
{
"icon": "💾❔",
"result": "Backup outcome unconfirmed",
"when": "The report is incomplete or does not state a result for every guest."
}
],
"items": [
"<strong>The title names what the job was about.</strong> It carries the storage and, for a job with a single guest, its type, name and ID. A failed job names the guest that failed.",
"<strong>The body lists each guest</strong> with its own result, size, duration and archive, followed by a line with the totals of the job.",
"<strong>Warnings and errors are listed once.</strong> Repeated lines are shown a single time with the main cause first; past eight lines, the rest is counted in a closing line and stays in the Proxmox task log.",
"<strong>A job that fails before its first guest</strong> shows the cause Proxmox gave, for example a storage that does not exist.",
"<strong>Summaries keep the result.</strong> A backup listed in the Quiet Hours summary or the Daily Digest carries the icon of its own result."
]
}
},
"history": {
"heading": "History",
@@ -21,12 +21,13 @@
"Sets <code>pigz: 1</code> in <code>/etc/vzdump.conf</code> so Proxmox's backup tool uses pigz natively.",
"Installs the <code>pigz</code> apt package if not already present.",
"Writes a wrapper script at <code>/bin/pigzwrapper</code> that forwards every argument to <code>/usr/bin/pigz</code>.",
"Moves the original <code>/bin/gzip</code> aside to <code>/bin/gzip.original</code> and replaces <code>/bin/gzip</code> with the wrapper. From now on, <em>anything</em> that calls <code>gzip</code> — logrotate, <code>tar czf</code>, scripts, vzdump — uses pigz transparently."
"Registers a dpkg diversion for the system's <code>gzip</code> binary (<code>/usr/bin/gzip</code> on Proxmox VE 9, <code>/bin/gzip</code> on Proxmox VE 8): the real binary is kept beside it as <code>gzip.distrib</code> and the wrapper takes its place. From now on, <em>anything</em> that calls <code>gzip</code> — logrotate, <code>tar czf</code>, scripts, vzdump — uses pigz transparently.",
"Checks that the file kept as <code>gzip.distrib</code> is a working gzip before the wrapper is put in place, and reinstalls the <code>gzip</code> package first when it is not. A host that still has the earlier <code>/bin/gzip.original</code> swap is moved to the diversion when the option is applied again."
],
"replacesTitle": "This replaces a system binary",
"replacesBody": "Replacing <code>/bin/gzip</code> with a wrapper is unusual. It is safe (the wrapper produces gzip-compatible output), but worth knowing: scripts that hardcode paths, run inside restrictive chroots, or verify binary hashes may behave differently. The original binary is preserved as <code>/bin/gzip.original</code> so you can always swap it back.",
"replacesBody": "Putting a wrapper in the place of <code>gzip</code> is unusual. It is safe (the wrapper produces gzip-compatible output), but worth knowing: scripts that hardcode paths, run inside restrictive chroots, or verify binary hashes may behave differently. The real binary is preserved as <code>gzip.distrib</code>, and because the replacement is a dpkg diversion, an update of the <code>gzip</code> package — or the upgrade from Proxmox VE 8 to 9 — updates that file and leaves the wrapper in place.",
"revertTitle": "Reversible from the Uninstall menu",
"revertBody": "This optimization is tracked. <link>Uninstall Optimizations</link> restores <code>/bin/gzip.original</code> back into place, removes the <code>pigzwrapper</code>, reverts the two lines added to <code>/etc/vzdump.conf</code>, and runs <code>apt purge pigz</code>. Manual equivalent:",
"revertBody": "This optimization is tracked. <link>Uninstall Optimizations</link> copies the real binary from <code>gzip.distrib</code> back over the wrapper, removes the diversion and the <code>pigzwrapper</code>, comments out the <code>pigz</code> line in <code>/etc/vzdump.conf</code>, and runs <code>apt purge pigz</code> once gzip is verified to work. Manual equivalent on Proxmox VE 9:",
"verifyTitle": "Verification",
"verifyBody": "After applying, <code>gzip --version</code> should mention pigz. A quick benchmark also shows the speed difference on a multi-core host:",
"whenTitle": "When this matters most",
@@ -205,7 +205,7 @@
},
{
"tool": "pigz (parallel gzip)",
"restores": "Puts /bin/gzip.original back in place, removes the /bin/pigzwrapper, reverts the pigz and bwlimit lines in /etc/vzdump.conf and apt purges pigz."
"restores": "Copies the real gzip back from gzip.distrib, removes the dpkg diversion and /bin/pigzwrapper, comments out the pigz line in /etc/vzdump.conf and apt purges pigz once gzip is verified."
},
{
"tool": "High Availability services",
+1 -1
View File
@@ -78,7 +78,7 @@
},
{
"title": "Proxmox System Update",
"description": "Repo hygiene + apt update + apt dist-upgrade with reboot prompt. Detects PVE major version (8 or 9) and routes to the matching worker. Switches to no-subscription, removes conflicting packages, runs autoremove.",
"description": "Repository check + apt update + apt dist-upgrade with reboot prompt. Detects the PVE major version (8 or 9), keeps the configured repositories and asks before switching a host without subscription to no-subscription, then runs autoremove.",
"href": "/docs/utils/system-update"
},
{
+14 -13
View File
@@ -7,7 +7,7 @@
},
"header": {
"title": "Proxmox System Update",
"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.",
"description": "Wrapper that delegates to a single safe worker (<code>update-pve-safe.sh</code>) which detects the running Proxmox major version by itself. The configured repositories are read through the Proxmox API and kept as they are; a host with no active subscription whose only Proxmox repository is Enterprise is asked before switching to no-subscription. 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": {
@@ -25,7 +25,7 @@
"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> 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>Keeps the configured repositories.</strong> <code>ensure_repositories</code> reads the repositories through the Proxmox repository API, together with the subscription status. A host with an active subscription, or one that already uses the no-subscription or test repository, is left unchanged. A host with no active subscription whose only Proxmox repository is Enterprise is asked whether to switch to no-subscription; declining stops the update with no source changed.",
"<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).",
@@ -63,10 +63,9 @@
"heading": "What the worker does",
"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>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>Sanity checks.</strong> Verifies at least ~1 GB free in <code>/var/cache/apt/archives</code>. Aborts early with a clear message when it fails, so the run doesn't die in the middle of an apt transaction.",
"<strong>Repository check.</strong> <code>ensure_repositories</code> reads the repositories and the subscription status. On a host with a usable Proxmox repository it changes nothing; on a host with no active subscription and only the Enterprise repository it asks before switching to no-subscription, and stops the update when the answer is no.",
"<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.",
@@ -96,14 +95,16 @@
"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": "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:",
"heading": "How the safe worker treats the Enterprise repository",
"intro": "Proxmox ships hosts with the Enterprise repository enabled by default. Without an active subscription, that repository returns 401 on <code>apt-get update</code>. The safe worker changes the repositories only in that case, only after asking, and through the Proxmox repository API — the same one behind <em>Node → Updates → Repositories</em>. What happens in each case:",
"items": [
"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."
"With an <strong>active subscription</strong>, the repositories are left unchanged and Enterprise drives the upgrade.",
"With the <strong>no-subscription or test repository already enabled</strong>, the repositories are left unchanged, whatever else is configured beside them.",
"With <strong>no active subscription and only the Enterprise repository</strong>, a dialog offers the switch. Accepting disables the Enterprise source, enables the no-subscription one and refreshes the package lists; the change is recorded in the <em>Changes</em> view of Audit & Report. Declining stops the update with no source changed.",
"<strong>Enterprise Ceph sources</strong>, when present, are disabled in the same switch without choosing another Ceph channel; a host that uses Ceph has its channel configured separately.",
"When the run has <strong>no terminal to ask in</strong>, no source is changed and the update stops with a message that points to <em>Node → Updates → Repositories</em>."
],
"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."
"outro": "The Debian sources and every other repository file are never edited by the update path. A source that mixes Enterprise with other components in the same entry is not switched: the update stops and asks for it to be split from the Proxmox repository view."
},
"cluster": {
"heading": "Cluster considerations",
@@ -124,7 +125,7 @@
"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."
"body": "The Enterprise repository is enabled and the host has no active subscription. The worker offers the switch to no-subscription before <code>apt-get update</code>; when it was declined, run the update again and accept it, or disable the Enterprise source in <em>Node → Updates → Repositories</em> and enable the no-subscription one."
},
{
"title": "dist-upgrade hangs at \"Configuring grub-pc\"",
@@ -142,7 +143,7 @@
},
"files": {
"heading": "Files involved",
"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"
"code": "scripts/utilities/proxmox_update.sh # this script (wrapper)\nscripts/global/update-pve-safe.sh # single safe worker (PVE 8 + PVE 9)\nscripts/global/repository-functions.sh # ensure_repositories\nscripts/global/repository_policy.py # reads and switches repositories through the Proxmox API\nscripts/global/utils-install-functions.sh # 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 # no-subscription source, written by Proxmox when the switch is accepted\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",
+4 -4
View File
@@ -12,7 +12,7 @@
},
"info": {
"title": "What this does",
"body": "Installs CLI tools from a curated list of 26 packages. Every installation goes through the same canonical flow: <code>ensure_repositories</code> sets up Proxmox + Debian repos for the running PVE major version, then <code>install_single_package</code> runs the install and verifies the resulting command is in PATH."
"body": "Installs CLI tools from a curated list of 26 packages. Every installation goes through the same canonical flow: <code>ensure_repositories</code> checks that the host has a usable Proxmox repository for the running PVE major version, then <code>install_single_package</code> runs the install and verifies the resulting command is in PATH."
},
"opening": {
"heading": "Opening the installer",
@@ -204,7 +204,7 @@
"howItWorks": {
"heading": "How a single package install works",
"items": [
"<code>ensure_repositories</code> detects PVE 8 or 9, writes Proxmox no-subscription + Debian sources files if missing, runs <code>apt-get update</code>.",
"<code>ensure_repositories</code> detects PVE 8 or 9 and reads the repositories through the Proxmox API. A host with a usable Proxmox repository is left unchanged; a host with no active subscription and only the Enterprise repository is asked before switching to no-subscription, and <code>apt-get update</code> runs after an accepted switch.",
"<code>install_single_package \"pkg\" \"verify_cmd\" \"description\"</code> runs <code>apt-get install -y \"$pkg\"</code> with feedback (<code>msg_info</code> / <code>msg_ok</code> / <code>msg_error</code>)."
],
"verifyIntro": "After install, the verify command is checked with <code>command -v \"$verify_cmd\"</code>. Three outcomes:",
@@ -224,7 +224,7 @@
"troubleshoot": {
"heading": "Troubleshooting",
"reposTitle": "\"Failed to configure repositories. Installation aborted.\"",
"reposBody": "The host can't reach the Proxmox or Debian repos, or doesn't have the expected base config. From a console: <code>cat /etc/apt/sources.list /etc/apt/sources.list.d/*.sources</code> and <code>apt-get update</code> manually to see the actual error.",
"reposBody": "The repository check did not pass: the switch to the no-subscription repository was declined, the subscription status could not be read, or a repository entry needs attention. The message printed above it states the cause. The repositories are listed in <em>Node → Updates → Repositories</em>, and <code>apt-get update</code> from a console shows the error apt reports.",
"warningsTitle": "A package is reported \"With warnings\" but the command works after I close the menu",
"warningsBody": "Expected. After <code>apt-get install</code>, the new binary is on disk but the current shell's PATH cache (<code>hash -t</code>) doesn't know yet. ProxMenux runs <code>hash -r</code> after each install, but in some shells the refresh only takes effect on the next prompt. Open a new shell and the command will work.",
"hangsTitle": "An apt install hangs",
@@ -232,7 +232,7 @@
},
"files": {
"heading": "Files involved",
"code": "scripts/utilities/system_utils.sh # this script\nscripts/global/utils-install-functions.sh # PROXMENUX_UTILS, ensure_repositories,\n # install_single_package\n/etc/apt/sources.list # may be touched by ensure_repositories\n/etc/apt/sources.list.d/proxmox.sources # created if missing (PVE 9)\n/etc/apt/sources.list.d/debian.sources # created if missing (PVE 9)\n/etc/apt/sources.list.d/pve-no-subscription.list # created if missing (PVE 8)"
"code": "scripts/utilities/system_utils.sh # this script\nscripts/global/utils-install-functions.sh # PROXMENUX_UTILS, install_single_package\nscripts/global/repository-functions.sh # ensure_repositories\nscripts/global/repository_policy.py # reads and switches repositories through the Proxmox API\n/etc/apt/sources.list.d/proxmox.sources # no-subscription source, written by Proxmox when the switch is accepted"
},
"related": {
"heading": "Related",