mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-06-14 04:17:00 +00:00
complete i18n migration to /[locale]/ with EN+ES content
Full rewrite of the docs site under app/[locale]/ with next-intl in localePrefix:"always" mode. Every page now exists at both /en/<path> and /es/<path>; the root / shows a meta-refresh + JS redirect to /<defaultLocale>/ so GitHub Pages serves something on the apex URL. Highlights: - 107 doc pages migrated to file-per-page JSON namespaces under messages/en/ and messages/es/. Spanish content is fully translated (no copy-of-English placeholders). - New documentation for the Active Suppressions section in the Settings tab and the per-event Dismiss dropdown in the Health Monitor modal. - New screenshots: dismiss-duration-dropdown.png and an updated health-suppression-settings.png. - Pagefind integrated for client-side search; index is built on every CI deploy (not committed). - RSS feeds: per-locale at /<locale>/rss.xml plus root /rss.xml for backward compat. - Removed the dead app/[locale]/guides/[slug]/ route — every guide now has its own static page and no markdown source remains. - Fixed orphan link /guides/nvidia -> /guides/nvidia-manual in docs/hardware/nvidia-host. - Removed obsolete components (footer2, calendar, drawer). Verified locally with `npm ci && npm run build`: 2804 files in out/, 231 pages indexed by pagefind, root redirect intact, both locale roots and the new Active Suppressions docs render OK.
This commit is contained in:
110
web/messages/en/docs/network/backup-restore.json
Normal file
110
web/messages/en/docs/network/backup-restore.json
Normal file
@@ -0,0 +1,110 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Interfaces Backup & Restart | ProxMenux Documentation",
|
||||
"description": "Manual snapshot, browse and restore /etc/network/interfaces backups stored under /var/backups/proxmenux/. Includes a network service restart with confirmation and a quick view of the live configuration.",
|
||||
"ogTitle": "Interfaces Backup & Restart | ProxMenux Documentation",
|
||||
"ogDescription": "Snapshot and restore Proxmox network configuration; restart the networking service with confirmation."
|
||||
},
|
||||
"header": {
|
||||
"title": "Interfaces backup & restart",
|
||||
"description": "Four utilities that revolve around /etc/network/interfaces: take a manual snapshot, view the live config, restore a previous backup with optional preview, and restart the networking service with explicit consent. Same backup directory used by the guided repair flows.",
|
||||
"section": "Network"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "Manages the same backup directory used by the guided repair flows (<code>/var/backups/proxmenux/</code>). Lets you take an extra snapshot before any manual change, browse all existing backups, and roll back to any of them — always with a fresh pre-restore backup taken automatically as a second safety net."
|
||||
},
|
||||
"shared": {
|
||||
"heading": "The shared backup directory",
|
||||
"intro": "Every backup taken anywhere in the Network menu lands in the same place:",
|
||||
"outro": "Filenames are timestamped, sorted by date, and never overwritten. The directory is created on first use."
|
||||
},
|
||||
"show": {
|
||||
"heading": "Show Network Config File",
|
||||
"body": "Prints <code>/etc/network/interfaces</code> verbatim to the terminal. Read-only. Useful as a sanity check before taking a backup or after a restore — there is no separate \"diff with previous backup\" tool, so eyeballing the live file is the easiest way to confirm what you have."
|
||||
},
|
||||
"create": {
|
||||
"heading": "Create Network Backup",
|
||||
"body": "Copies the current <code>/etc/network/interfaces</code> into the backup directory with a fresh timestamp. That's it — no analysis, no prompts, just a snapshot.",
|
||||
"whenTitle": "When to take a manual backup",
|
||||
"whenBody": "Before editing <code>/etc/network/interfaces</code> by hand, before installing a package that may touch the network stack (e.g. NetworkManager, Open vSwitch), or before any hardware change. The guided repairs already snapshot automatically — this option is for the <em>manual</em> moments."
|
||||
},
|
||||
"restore": {
|
||||
"heading": "Restore Network Backup",
|
||||
"intro": "Lists every backup in <code>/var/backups/proxmenux/</code> sorted from newest to oldest, and walks through a guarded restore:",
|
||||
"steps": [
|
||||
{
|
||||
"title": "1. Pick a backup",
|
||||
"body": "A menu lists each backup by its timestamp. If no backups exist, the flow exits with a clear message.",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "2. Optional preview",
|
||||
"body": "Offers to open the selected backup in a scrollable view before committing. Yes by default — do not skip it on a remote host.",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "3. Pre-restore backup",
|
||||
"body": "Before overwriting <code>/etc/network/interfaces</code>, takes <strong>another</strong> backup of the current state. Restoring a backup is itself a destructive action, so the new pre-restore snapshot lets you go back if the chosen backup turns out to be the wrong one.",
|
||||
"tone": "amber"
|
||||
},
|
||||
{
|
||||
"title": "4. Apply the restore",
|
||||
"body": "Copies the chosen backup over <code>/etc/network/interfaces</code>. The file change is on disk; the live kernel state still reflects the previous config.",
|
||||
"tone": "amber"
|
||||
},
|
||||
{
|
||||
"title": "5. Optional restart",
|
||||
"body": "Asks whether to run <code>systemctl restart networking</code> now. Decline to defer the change to the next reboot.",
|
||||
"tone": "emerald"
|
||||
}
|
||||
],
|
||||
"autoBackupTitle": "A restore takes its own backup automatically",
|
||||
"autoBackupBody": "Selecting <em>Restore Network Backup</em> always creates a fresh snapshot of the <em>current</em> config before overwriting it. If you restore to the wrong backup, the most recent file in <code>/var/backups/proxmenux/</code> is the state you came from."
|
||||
},
|
||||
"restart": {
|
||||
"heading": "Restart Network Service",
|
||||
"body": "Runs <code>systemctl restart networking</code> after a yes/no confirmation. Reports the result with <code>msg_ok</code> / <code>msg_error</code>. Most flows in this menu offer their own restart prompt at the end; this option is for restarting after a manual edit or after declining the in-flow restart earlier.",
|
||||
"warnTitle": "Brief disconnection guaranteed; permanent disconnection possible",
|
||||
"warnBody": "Restarting <code>networking</code> tears down and re-applies every interface declared in <code>/etc/network/interfaces</code>. SSH sessions hosted on those interfaces drop. If the new config is invalid, the network never comes back. Run this only when:",
|
||||
"warnItems": [
|
||||
"You have console / IPMI / iKVM access ready, <em>or</em>",
|
||||
"You are physically next to the machine, <em>or</em>",
|
||||
"You have just successfully rolled back to a known-good config and want to apply it."
|
||||
]
|
||||
},
|
||||
"manualRollback": {
|
||||
"heading": "Manual rollback from a console",
|
||||
"intro": "If you cannot reach the menu (no SSH, dialog crashing, …) but can reach a console, rollback is two commands:",
|
||||
"outro": "This is the <em>same</em> operation the menu performs, just typed by hand. If <code>networking</code> still fails to start, check <code>journalctl -u networking -b</code> for the underlying syntax / driver error."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"noneTitle": "\"No backups found\" in Restore",
|
||||
"noneBody": "The directory <code>/var/backups/proxmenux/</code> does not exist or contains no <code>interfaces_backup_*</code> files. Run <em>Create Network Backup</em> at least once, or run any guided repair (which auto-creates one). Confirm with <code>ls /var/backups/proxmenux/</code>.",
|
||||
"unreachTitle": "Restart networking succeeds but the host is still unreachable",
|
||||
"unreachBody": "Either the new config is wrong, or you restarted into a configuration that does not bind your management IP. Roll back from the console (see above). After rollback, use <bridgeLink>bridge analysis</bridgeLink> and <configLink>config analysis</configLink> to understand what was wrong before re-applying.",
|
||||
"emptyTitle": "Restore preview shows an empty file",
|
||||
"emptyBody": "The backup file is empty (0 bytes). This happens if a copy failed silently during a previous run. Pick an older backup, or re-run <em>Create Network Backup</em> right now if the live config is healthy."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"label": "Bridge analysis & guided repair",
|
||||
"href": "/docs/network/bridge-analysis",
|
||||
"tail": " — the most common reason a backup ends up here."
|
||||
},
|
||||
{
|
||||
"label": "Config analysis & guided cleanup",
|
||||
"href": "/docs/network/config-analysis",
|
||||
"tailRich": " — also writes to <code>/var/backups/proxmenux/</code> automatically."
|
||||
},
|
||||
{
|
||||
"label": "Diagnostics",
|
||||
"href": "/docs/network/diagnostics",
|
||||
"tail": " — verify the live state after a restore."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
132
web/messages/en/docs/network/bridge-analysis.json
Normal file
132
web/messages/en/docs/network/bridge-analysis.json
Normal file
@@ -0,0 +1,132 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Bridge Analysis & Guided Repair | ProxMenux Documentation",
|
||||
"description": "Detects vmbrX bridges with missing or invalid physical ports (typical after PCI re-enumeration), reports them with proposed shell commands, and offers a 5-step guided repair with mandatory backup.",
|
||||
"ogTitle": "Bridge Analysis & Guided Repair | ProxMenux Documentation",
|
||||
"ogDescription": "Audit and repair Proxmox bridge ports after hardware changes, with guided rollback-safe flow."
|
||||
},
|
||||
"header": {
|
||||
"title": "Bridge analysis & guided repair",
|
||||
"description": "Audits every vmbrX bridge declared in /etc/network/interfaces, verifies that its physical ports actually exist, and offers a step-by-step repair when they don't. The analysis is read-only; the repair is gated, previewed and backed up.",
|
||||
"section": "Network"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "Reads each bridge in <code>/etc/network/interfaces</code>, looks at its <code>bridge-ports</code> line and checks whether each declared port (e.g. <code>enp3s0</code>) actually exists on the host. If a port is missing, proposes a substitute and — with explicit consent — applies the change with a <strong>backup, preview, apply, verify</strong> flow."
|
||||
},
|
||||
"when": {
|
||||
"heading": "When you need this",
|
||||
"intro": "Linux assigns predictable interface names from PCI topology and slot order. Several events shuffle them and leave <code>/etc/network/interfaces</code> referring to names that no longer exist:",
|
||||
"items": [
|
||||
"Adding or removing a PCIe card (a NIC, a GPU, a HBA, an NVMe carrier).",
|
||||
"Moving an existing card to a different PCIe slot.",
|
||||
"BIOS / UEFI updates that re-enumerate PCI devices.",
|
||||
"Migrating the boot disk to different hardware."
|
||||
],
|
||||
"outro": "After the next boot, the bridge tries to attach to a port that no longer exists, fails to come up, and the host loses its network. <link>Persistent interface names</link> prevents this from happening again — but if you are already locked out, this page is the recovery path."
|
||||
},
|
||||
"bigPicture": {
|
||||
"heading": "The big picture",
|
||||
"diagram1": {
|
||||
"arrowLabel": "step 1",
|
||||
"nodes": {
|
||||
"sourceLabel": "/etc/network/interfaces",
|
||||
"sourceDetail": "auto vmbr0\niface vmbr0 inet static\n bridge-ports enp3s0",
|
||||
"bridgeLabel": "Analyze (read-only)",
|
||||
"bridgeDetail": "ip link show enp3s0\n→ does not exist",
|
||||
"targetLabel": "Report + suggestion",
|
||||
"targetDetail": "❌ enp3s0: NOT FOUND\nReplace with: eno1\n(no changes yet)"
|
||||
}
|
||||
},
|
||||
"diagram2": {
|
||||
"arrowLabel": "apply with backup",
|
||||
"nodes": {
|
||||
"sourceLabel": "Guided repair",
|
||||
"sourceDetail": "1. Backup\n2. Show current\n3. Preview changes\n4. Apply\n5. Verify",
|
||||
"targetLabel": "/etc/network/interfaces (new)",
|
||||
"targetDetail": "auto vmbr0\niface vmbr0 inet static\n bridge-ports eno1"
|
||||
}
|
||||
}
|
||||
},
|
||||
"step1": {
|
||||
"heading": "Step 1: analysis (read-only)",
|
||||
"intro": "Selecting <strong>Analyze Bridge Configuration</strong> aborts immediately if the host is not on the classic Debian/Proxmox stack. Otherwise it walks every bridge and reports:",
|
||||
"items": [
|
||||
"Bridge name, current status (UP / DOWN), assigned IP.",
|
||||
"Each declared port and whether it currently exists (<code>ip link show <port></code>).",
|
||||
"For each invalid port: a proposed replacement (the first available physical interface) plus the exact <code>sed</code> command to apply it manually.",
|
||||
"Bridges with no <code>bridge-ports</code> at all and orphan <code>auto</code> entries (no matching <code>iface</code> block)."
|
||||
],
|
||||
"readonlyTitle": "Read-only guarantee",
|
||||
"readonlyBody": "Up to this point the script has not run a single modifying command. You can leave the analysis open, copy the suggested <code>sed</code> commands and apply them manually if you prefer — or accept the next prompt to enter the guided repair."
|
||||
},
|
||||
"step2": {
|
||||
"heading": "Step 2: guided repair (5 steps)",
|
||||
"intro": "Only entered if you accept the prompt at the end of the analysis. Each step shows what will happen and asks for confirmation before continuing.",
|
||||
"steps": [
|
||||
{
|
||||
"title": "1. Safety backup",
|
||||
"body": "Copies <code>/etc/network/interfaces</code> to <code>/var/backups/proxmenux/interfaces_backup_<TIMESTAMP></code>. The exact backup path is shown before the copy and again after, with the rollback command.",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "2. Review current configuration",
|
||||
"body": "Opens the live <code>/etc/network/interfaces</code> in a scrollable dialog so you can see exactly what is about to be changed.",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "3. Preview proposed changes",
|
||||
"body": "Lists exactly which bridges will be touched and which port substitutions will happen. If the analysis decides nothing actually needs fixing (race condition: the port came back), the flow exits cleanly with <em>\"No changes needed.\"</em>",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "4. Apply changes",
|
||||
"body": "For each affected bridge, runs <code>sed -i \"/iface $bridge/,/bridge-ports/ s/bridge-ports.*/bridge-ports $new_ports/\"</code> against <code>/etc/network/interfaces</code>. If a bridge had no valid replacement available, the substitution is skipped and reported in step 5.",
|
||||
"tone": "amber"
|
||||
},
|
||||
{
|
||||
"title": "5. Verification",
|
||||
"body": "Re-reads the file and confirms each bridge's new port now exists. Prints the rollback command (<code>cp <backup> /etc/network/interfaces</code>). Finally offers a <strong>Restart networking</strong> prompt — accept only if you have console fallback.",
|
||||
"tone": "emerald"
|
||||
}
|
||||
],
|
||||
"restartTitle": "Restarting networking ≠ a free undo",
|
||||
"restartBody": "The repair is written to disk regardless of whether you restart the service. <code>systemctl restart networking</code> applies the change <em>now</em>, which can drop your SSH session if the new port is wrong. If you decline the restart, the change still takes effect on the next reboot — confirm the new config first or roll back from the printed command."
|
||||
},
|
||||
"edits": {
|
||||
"heading": "What gets edited (exactly)",
|
||||
"body": "Only the <code>bridge-ports</code> line of each affected bridge. Other directives (<code>address</code>, <code>netmask</code>, <code>gateway</code>, <code>bridge-stp</code>, …) are left untouched. The script never creates new <code>iface</code> blocks and never removes existing ones in this flow — that is the job of <link>Config analysis & cleanup</link>."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"unsupportedTitle": "Analysis aborts with \"Unsupported Network Stack\"",
|
||||
"unsupportedBody": "The host runs netplan, systemd-networkd or NetworkManager. The tool only supports <code>/etc/network/interfaces</code>. Switch the host to the classic stack first, or edit the configuration with the manager's native tooling (e.g. <code>netplan apply</code>).",
|
||||
"noSuggestTitle": "No suggestion is printed for an invalid port",
|
||||
"noSuggestBody": "The host has zero free physical interfaces (everything is either already in another bridge or doesn't exist). The analysis falls back to suggesting <code>bridge-ports none</code> so the bridge can at least come up without a port. Add a NIC or migrate ports between bridges manually before re-running.",
|
||||
"stillDownTitle": "The repair completes but the bridge is still DOWN",
|
||||
"stillDownBody": "<code>sed</code> updated the file but <code>systemctl restart networking</code> was declined. Run it manually once the new config is verified, or reboot. If the restart was accepted and the bridge is still DOWN, run <code>ip link show</code> to confirm the new port exists, then check <code>journalctl -u networking</code> for the actual error (cable unplugged, link not negotiated, port already a member of another bridge).",
|
||||
"lostSshTitle": "I lost SSH access right after restarting networking",
|
||||
"lostSshIntro": "Use console / IPMI / iKVM to reach the host. Restore the backup:",
|
||||
"lostSshOutro": "Then re-run the analysis from the console to figure out why the suggestion did not work (typically: the replacement port is not actually plugged in)."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"label": "Persistent interface names",
|
||||
"href": "/docs/network/persistent-names",
|
||||
"tail": " — pin names to MAC addresses so this scenario stops happening."
|
||||
},
|
||||
{
|
||||
"label": "Config analysis & guided cleanup",
|
||||
"href": "/docs/network/config-analysis",
|
||||
"tailRich": " — for orphaned <code>iface</code> blocks (the other half of the same problem)."
|
||||
},
|
||||
{
|
||||
"label": "Interfaces backup & restart",
|
||||
"href": "/docs/network/backup-restore",
|
||||
"tail": " — manual snapshots and the restore browser."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
122
web/messages/en/docs/network/config-analysis.json
Normal file
122
web/messages/en/docs/network/config-analysis.json
Normal file
@@ -0,0 +1,122 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Config Analysis & Guided Cleanup | ProxMenux Documentation",
|
||||
"description": "Detects iface blocks in /etc/network/interfaces that reference physical NICs no longer present on the host. Reports them and offers a 5-step guided removal with mandatory backup and per-block preview.",
|
||||
"ogTitle": "Config Analysis & Guided Cleanup | ProxMenux Documentation",
|
||||
"ogDescription": "Find and remove orphan interface blocks left behind by hardware changes, with full preview and rollback."
|
||||
},
|
||||
"header": {
|
||||
"title": "Config analysis & guided cleanup",
|
||||
"description": "Walks every iface block in /etc/network/interfaces and verifies that the underlying physical NIC still exists. Reports orphan blocks left behind by hardware changes and offers a guided removal with backup, preview and per-block confirmation.",
|
||||
"section": "Network"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "Identifies <code>iface</code> declarations whose backing NIC is no longer present on the host (typical after replacing or removing a network card). Then offers a guided cleanup that removes <em>only</em> the orphan blocks, with a backup, a per-section preview and an explicit final confirmation."
|
||||
},
|
||||
"differs": {
|
||||
"heading": "How it differs from bridge analysis",
|
||||
"headerAspect": "Aspect",
|
||||
"headerBridge": "Bridge analysis",
|
||||
"headerConfig": "Config analysis",
|
||||
"rows": [
|
||||
{
|
||||
"aspect": "Looks at",
|
||||
"bridge": "Bridges (<code>vmbrX</code>) and their <code>bridge-ports</code> line",
|
||||
"config": "Every <code>iface</code> block (excluding loopback, bridges, bonds)"
|
||||
},
|
||||
{
|
||||
"aspect": "Detects",
|
||||
"bridge": "Bridges referencing a non-existent port",
|
||||
"config": "Standalone interface blocks for NICs that don't exist"
|
||||
},
|
||||
{
|
||||
"aspect": "Repair action",
|
||||
"bridge": "Replaces the port name in <code>bridge-ports</code>",
|
||||
"config": "Removes the entire <code>iface</code> block"
|
||||
},
|
||||
{
|
||||
"aspect": "Excludes",
|
||||
"bridge": "Nothing — every bridge is analyzed",
|
||||
"config": "Bridges (<code>vmbrX</code>) and bonds (<code>bondX</code>) are always kept, since they are virtual and \"not existing\" would be normal during boot"
|
||||
}
|
||||
],
|
||||
"outro": "In practice you often run both, in this order: <strong>config analysis</strong> first to remove orphans, then <link>bridge analysis</link> to re-point any bridge that was relying on the now-removed interface."
|
||||
},
|
||||
"step1": {
|
||||
"heading": "Step 1: analysis (read-only)",
|
||||
"intro": "Aborts immediately if the host is not on the classic stack. Otherwise lists every configured non-loopback interface and reports its status:",
|
||||
"virtTitle": "Virtual interfaces are protected",
|
||||
"virtBody": "Bridges (<code>vmbrX</code>) and bonds (<code>bondX</code>) are virtual constructs. They may legitimately not exist at the moment of inspection (e.g. a bridge with no ports yet), so the analysis never proposes removing them — only physical NICs."
|
||||
},
|
||||
"step2": {
|
||||
"heading": "Step 2: guided cleanup (5 steps)",
|
||||
"intro": "Only entered if you accept the prompt at the end of the analysis. Each step requires confirmation; cancelling at any point exits without writing.",
|
||||
"steps": [
|
||||
{
|
||||
"title": "1. Safety backup",
|
||||
"body": "Copies <code>/etc/network/interfaces</code> to <code>/var/backups/proxmenux/interfaces_backup_<TIMESTAMP></code>. Path shown before and after.",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "2. Confirm the removal list",
|
||||
"body": "Lists exactly which physical interface blocks will be removed. If, between analysis and cleanup, the NICs reappeared (e.g. you re-seated a card), the flow exits with <em>\"No cleanup needed.\"</em>",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "3. Preview the exact block(s)",
|
||||
"body": "Opens a scrollable view of every <code>iface</code> block that would be deleted, verbatim from the file. This is the moment to spot e.g. an interesting <code>up</code> hook you want to preserve.",
|
||||
"tone": "blue"
|
||||
},
|
||||
{
|
||||
"title": "4. Apply removal",
|
||||
"body": "For each orphan interface, runs <code>sed -i \"/^iface $iface/,/^$/d\" /etc/network/interfaces</code>. That deletes from the matching <code>iface</code> line up to the next blank line.",
|
||||
"tone": "amber"
|
||||
},
|
||||
{
|
||||
"title": "5. Verification",
|
||||
"body": "Re-reads the file, lists what was removed, and re-checks the remaining interfaces. Prints the rollback command. Does <strong>not</strong> automatically restart networking — removing an unused block is safe to apply on the next reboot, and avoids touching the live state.",
|
||||
"tone": "emerald"
|
||||
}
|
||||
],
|
||||
"noRestartTitle": "Does not auto-restart networking",
|
||||
"noRestartBody": "Unlike bridge repair, the cleanup flow does not offer to restart the service. Removing an unused interface block has no immediate effect on the running config, so a restart is unnecessary and would be a needless connectivity risk. The change takes effect on the next manual <code>systemctl restart networking</code> or at the next reboot."
|
||||
},
|
||||
"caveats": {
|
||||
"heading": "Important caveats",
|
||||
"boundaryTitle": "The block boundary is the first blank line",
|
||||
"boundaryBody": "The <code>sed</code> pattern deletes from <code>iface <name></code> down to the next empty line. If your <code>/etc/network/interfaces</code> has no blank line separating blocks (rare, but possible if hand-edited), the deletion may consume the next block too. This is why <strong>step 3 is mandatory</strong>: review the preview before confirming.",
|
||||
"tandemTitle": "An orphan iface used by a bridge is detected here, not in bridge analysis",
|
||||
"tandemBody": "If <code>vmbr0</code> declares <code>bridge-ports enp3s0</code> and <code>enp3s0</code> also has its own <code>iface enp3s0 inet manual</code> block, removing <code>enp3s0</code> here will leave <code>vmbr0</code> with a dangling reference. After the cleanup, run <link>bridge analysis</link> to repoint or remove the bridge port. The two flows are designed to be used in tandem."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"notFoundTitle": "The analysis shows my new NIC as \"NOT FOUND\"",
|
||||
"notFoundBody": "The kernel sees the device under a different name than what is in the file. Run <code>ip link show</code> to get the actual name. This is exactly the case where <link>Persistent interface names</link> would prevent the issue going forward.",
|
||||
"tooMuchTitle": "The cleanup removed too much (a block I wanted to keep)",
|
||||
"tooMuchBody": "Restore from the backup printed in step 5:",
|
||||
"tooMuchOutro": "Edit the file by hand to add a clear blank line between blocks before re-running the cleanup, or remove the problematic block manually.",
|
||||
"bridgeBreakTitle": "A bridge stops working after the cleanup",
|
||||
"bridgeBreakBody": "The bridge was relying on a port whose <code>iface</code> block was just removed. Run <link>bridge analysis</link> and the suggestion will point the bridge at an existing physical interface."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"label": "Bridge analysis & guided repair",
|
||||
"href": "/docs/network/bridge-analysis",
|
||||
"tail": " — the natural follow-up after a cleanup."
|
||||
},
|
||||
{
|
||||
"label": "Persistent interface names",
|
||||
"href": "/docs/network/persistent-names",
|
||||
"tail": " — stops orphan blocks from accumulating after each hardware change."
|
||||
},
|
||||
{
|
||||
"label": "Interfaces backup & restart",
|
||||
"href": "/docs/network/backup-restore",
|
||||
"tail": " — manual snapshots and the restore browser."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
94
web/messages/en/docs/network/diagnostics.json
Normal file
94
web/messages/en/docs/network/diagnostics.json
Normal file
@@ -0,0 +1,94 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Diagnostics | ProxMenux Documentation",
|
||||
"description": "Three read-only one-shot diagnostic checks: Show Routing Table, Test Connectivity and Advanced Diagnostics. Pure inspection — never writes to /etc/network/interfaces and never runs a modifying command (one explicit, opt-in exception for purging NetworkManager when detected).",
|
||||
"ogTitle": "Diagnostics | ProxMenux Documentation",
|
||||
"ogDescription": "Read-only network diagnostics for the Proxmox host: routing, reachability, advanced statistics."
|
||||
},
|
||||
"header": {
|
||||
"title": "Diagnostics",
|
||||
"description": "Three one-shot read-only checks that inspect the live network state: routing table, connectivity test and advanced statistics. None of them write to /etc/network/interfaces — safe to use at any time, including over SSH. For interactive live monitoring, see Live monitoring tools.",
|
||||
"section": "Network"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "Reports on routing, reachability and aggregate statistics <strong>without modifying anything</strong>. Use it to confirm the network is healthy or identify duplicate IPs. For continuous traffic observation see <monitoringLink>Live monitoring tools</monitoringLink>; for viewing the raw config file see <backupLink>Interfaces backup & restart</backupLink>."
|
||||
},
|
||||
"routing": {
|
||||
"heading": "Show Routing Table",
|
||||
"body": "Lists every route the kernel currently uses (<code>ip route show</code>) and highlights the default gateway. Useful for confirming that traffic to the internet leaves through the expected interface and that no leftover routes are taking precedence."
|
||||
},
|
||||
"connectivity": {
|
||||
"heading": "Test Connectivity",
|
||||
"intro": "Sends two ICMP probes to three targets in sequence and reports each one. Then runs an <code>nslookup google.com</code> to verify DNS resolution independently of ICMP.",
|
||||
"headerTest": "Test",
|
||||
"headerTarget": "Target",
|
||||
"headerConfirms": "What it confirms",
|
||||
"rows": [
|
||||
{
|
||||
"test": "Google DNS",
|
||||
"target": "8.8.8.8",
|
||||
"confirms": "External reachability via well-known anycast IP"
|
||||
},
|
||||
{
|
||||
"test": "Cloudflare DNS",
|
||||
"target": "1.1.1.1",
|
||||
"confirms": "Independent second-opinion if Google blocks ICMP"
|
||||
},
|
||||
{
|
||||
"test": "Gateway",
|
||||
"target": "(default route)",
|
||||
"confirms": "L2 / L3 connectivity to the local router"
|
||||
},
|
||||
{
|
||||
"test": "DNS Resolution",
|
||||
"target": "google.com",
|
||||
"confirms": "DNS server is reachable and answering"
|
||||
}
|
||||
],
|
||||
"readingTitle": "Reading the result",
|
||||
"readingBody": "If the gateway test passes but the public DNS targets fail, you have local connectivity but no internet — check the gateway's upstream. If DNS resolution fails but pings to <code>8.8.8.8</code> succeed, the issue is the resolver, not the network: check <code>/etc/resolv.conf</code>."
|
||||
},
|
||||
"advanced": {
|
||||
"heading": "Advanced Diagnostics",
|
||||
"intro": "Aggregates network-wide statistics and runs a battery of common-issue checks. Reports active connection counts, listening ports, total interfaces and flags two anti-patterns explicitly:",
|
||||
"items": [
|
||||
"<strong>NetworkManager running on a Proxmox host.</strong> NetworkManager and Proxmox's <code>ifupdown</code> conflict — both try to manage interfaces, leading to bridges that flap or refuse to come up. If detected, the tool offers an interactive prompt to stop, disable and purge it (this is the <em>only</em> diagnostic that can modify the system, and only after explicit consent).",
|
||||
"<strong>Duplicate IP addresses on different interfaces.</strong> Two interfaces holding the same IPv4 cause intermittent connectivity that's extremely hard to debug from inside the VM. Detected via <code>ip -4 addr show | sort | uniq -d</code>."
|
||||
],
|
||||
"nmTitle": "The NetworkManager prompt is the only modifying action here",
|
||||
"nmBody": "Every other check in Advanced Diagnostics is read-only. NetworkManager removal is gated behind a yes/no dialog and runs <code>systemctl stop / disable</code> + <code>apt-get purge -y network-manager</code>. If you decline, nothing changes."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"gwTitle": "Test Connectivity reports the gateway as failed but the host has internet",
|
||||
"gwBody": "Some routers do not respond to ICMP from their internal interface even when they happily forward traffic. Test with <code>traceroute 8.8.8.8</code> from a console: if the second hop is your ISP and the public DNS test passed, the gateway is fine despite the failed ping.",
|
||||
"dupTitle": "Advanced Diagnostics keeps flagging duplicate IPs after I removed one",
|
||||
"dupBody": "The check looks at the live kernel state, not the config file. Run <code>ip -4 addr show</code> to confirm; if the duplicate is still present, an interface is still holding it. Use <code>ip addr del <IP>/<mask> dev <iface></code> to remove it from the live state, then edit <code>/etc/network/interfaces</code> if it is also persistent."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"label": "Live monitoring tools",
|
||||
"href": "/docs/network/monitoring",
|
||||
"tail": " — interactive iftop / iptraf-ng / iperf3 launchers."
|
||||
},
|
||||
{
|
||||
"label": "Bridge analysis & guided repair",
|
||||
"href": "/docs/network/bridge-analysis",
|
||||
"tail": " — when a vmbrX is missing its physical port."
|
||||
},
|
||||
{
|
||||
"label": "Config analysis & guided cleanup",
|
||||
"href": "/docs/network/config-analysis",
|
||||
"tail": " — when an old NIC is still declared but no longer present."
|
||||
},
|
||||
{
|
||||
"label": "Interfaces backup & restart",
|
||||
"href": "/docs/network/backup-restore",
|
||||
"tail": " — to snapshot the config before any change."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
107
web/messages/en/docs/network/index.json
Normal file
107
web/messages/en/docs/network/index.json
Normal file
@@ -0,0 +1,107 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Proxmox Network Management — Bridges, Bonds, Diagnostics, Repair | ProxMenux",
|
||||
"description": "Read-only diagnostics, analyze-then-suggest workflows and guided repairs for the Debian / Proxmox network stack (/etc/network/interfaces). Inspect bridges and bonds, run live monitoring tools, persist interface names, back up and safely restart networking — with mandatory backups and step-by-step previews.",
|
||||
"ogTitle": "Proxmox Network Management — Bridges, Bonds, Diagnostics, Repair",
|
||||
"ogDescription": "Diagnostics, analysis and guided repairs for the Proxmox network stack with mandatory backups and step-by-step previews.",
|
||||
"twitterTitle": "Proxmox Network Management | ProxMenux",
|
||||
"twitterDescription": "Bridges, bonds, diagnostics and guided repairs for the Proxmox network stack with mandatory backups."
|
||||
},
|
||||
"header": {
|
||||
"title": "Network Management",
|
||||
"description": "Read-only diagnostics, analyze-then-suggest reports and guided repairs for the classic Debian/Proxmox network stack. Every destructive flow takes a backup first and previews the exact changes before applying them.",
|
||||
"section": "Network"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this menu is for",
|
||||
"body": "Inspect, diagnose and (when needed) repair the Proxmox host network configuration without losing remote access. The tools are designed around one principle: <strong>read first, propose, then apply only with explicit consent and a safety backup</strong>. There is no \"auto-fix everything\" button."
|
||||
},
|
||||
"openingMenu": {
|
||||
"heading": "Opening the menu",
|
||||
"intro": "From ProxMenux's main menu, select <strong>Network</strong>. You will see this:",
|
||||
"imageAlt": "Network Management menu with diagnostics, monitoring, analysis, repair, persistent names and backup options"
|
||||
},
|
||||
"safety": {
|
||||
"heading": "The safety model",
|
||||
"body": "Editing network configuration on a remote Proxmox host is one of the easiest ways to lock yourself out. ProxMenux treats every action accordingly. The tools fall into three behavioural tiers — pick the card that matches your intent:"
|
||||
},
|
||||
"tiers": {
|
||||
"readOnly": {
|
||||
"title": "Read-only",
|
||||
"body": "Pure inspection. Cannot modify the system under any circumstance.",
|
||||
"items": [
|
||||
"Routing table, connectivity tests, advanced statistics",
|
||||
"Live traffic monitoring (iftop, iptraf-ng)",
|
||||
"Bandwidth test (iperf3)"
|
||||
]
|
||||
},
|
||||
"analyze": {
|
||||
"title": "Analyze, then suggest",
|
||||
"body": "Detects issues, prints a report with proposed shell commands, and stops. You decide whether to enter the guided repair afterwards.",
|
||||
"items": [
|
||||
"Bridge configuration analysis",
|
||||
"Network configuration analysis"
|
||||
]
|
||||
},
|
||||
"apply": {
|
||||
"title": "Apply with backup",
|
||||
"body": "Modifies the system. Always takes a timestamped backup of the affected file first and shows a preview before writing.",
|
||||
"items": [
|
||||
"Persistent interface names (.link files)",
|
||||
"Manual backup, restore and service restart"
|
||||
]
|
||||
}
|
||||
},
|
||||
"classicTitle": "Classic stack only",
|
||||
"classicBody": "Every analysis and repair function checks the active network manager before touching anything. If the host runs <strong>netplan</strong>, <strong>systemd-networkd</strong> or <strong>NetworkManager</strong>, the tool aborts immediately with a clear message — the menu only supports the classic Debian/Proxmox stack at <code>/etc/network/interfaces</code>. This is intentional: editing a netplan file with rules written for <code>ifupdown</code> would silently corrupt the configuration.",
|
||||
"backups": {
|
||||
"heading": "Where backups go",
|
||||
"intro": "Every guided repair, restore or manual backup writes a timestamped copy of <code>/etc/network/interfaces</code> to <code>/var/backups/proxmenux/</code>:",
|
||||
"rollbackIntro": "To roll back manually from a console:"
|
||||
},
|
||||
"readOnlySection": {
|
||||
"heading": "Read-only inspection",
|
||||
"body": "The starting point when something feels off. Pure inspection — never writes to <code>/etc/network/interfaces</code> and never runs a modifying command (with one explicit, opt-in exception for purging NetworkManager when detected). Safe to use over SSH at any time.",
|
||||
"options": [
|
||||
{
|
||||
"title": "Diagnostics",
|
||||
"description": "Three one-shot read-only checks: Show Routing Table, Test Connectivity and Advanced Diagnostics. Pure inspection — never writes to the system."
|
||||
},
|
||||
{
|
||||
"title": "Live monitoring tools",
|
||||
"description": "Three interactive launchers: iftop (real-time bandwidth per host pair), iptraf-ng (multi-mode traffic monitor) and iperf3 (bandwidth test, server / client mode)."
|
||||
}
|
||||
]
|
||||
},
|
||||
"analyzeSection": {
|
||||
"heading": "Analyze, then suggest",
|
||||
"body": "Used when an inspection (or a real outage) points at a configuration issue. Each tool walks the relevant part of <code>/etc/network/interfaces</code>, prints a detailed report with the exact shell command that would fix each finding, and <strong>stops</strong>. If you accept the optional guided repair afterwards, every change is backed up and previewed before being written.",
|
||||
"options": [
|
||||
{
|
||||
"title": "Bridge analysis & guided repair",
|
||||
"description": "Detects vmbrX bridges with missing or invalid ports (typical after PCI re-enumeration). Shows a report first; only repairs when you accept the 5-step guided flow."
|
||||
},
|
||||
{
|
||||
"title": "Config analysis & guided cleanup",
|
||||
"description": "Finds physical interfaces declared in /etc/network/interfaces that no longer exist (orphan configs left behind by hardware changes). Reports them and offers a guided removal."
|
||||
}
|
||||
]
|
||||
},
|
||||
"applySection": {
|
||||
"heading": "Apply with backup",
|
||||
"body": "Tools that write to disk by design. Each one takes a timestamped backup of the affected file before writing, and the destructive options (restore, restart) require an explicit yes/no confirmation. <em>Persistent interface names</em> takes effect at the next reboot, not immediately, so it is safe to schedule even on a remote host.",
|
||||
"options": [
|
||||
{
|
||||
"title": "Persistent interface names",
|
||||
"description": "Pins interface names (eno1, enp3s0, …) to MAC addresses via systemd .link files. Names survive PCI slot changes, kernel upgrades and adding / removing other NICs."
|
||||
},
|
||||
{
|
||||
"title": "Interfaces backup & restart",
|
||||
"description": "Manual snapshot of /etc/network/interfaces, browse and restore previous backups, view the live config, and restart the networking service when needed."
|
||||
}
|
||||
]
|
||||
},
|
||||
"consoleTitle": "Have console access ready",
|
||||
"consoleSubTitle": "Before any repair on a remote host",
|
||||
"consoleBody": "If you are connected over SSH and only have one path to the host, have a fallback before applying network changes: physical / IPMI / iKVM console, or another machine on the same LAN. The guided repairs are safe and always offer a roll-back command, but a misconfigured bridge or a dropped link can still leave you locked out until you can reach the console."
|
||||
}
|
||||
136
web/messages/en/docs/network/monitoring.json
Normal file
136
web/messages/en/docs/network/monitoring.json
Normal file
@@ -0,0 +1,136 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Live Monitoring Tools | ProxMenux Documentation",
|
||||
"description": "Three interactive network monitoring launchers: iftop (real-time bandwidth per host pair), iptraf-ng (multi-mode traffic monitor) and iperf3 (bandwidth test, server / client mode). Each is installed on first use.",
|
||||
"ogTitle": "Live Monitoring Tools | ProxMenux Documentation",
|
||||
"ogDescription": "Interactive network monitoring and bandwidth testing for the Proxmox host: iftop, iptraf-ng, iperf3."
|
||||
},
|
||||
"header": {
|
||||
"title": "Live monitoring tools",
|
||||
"description": "Three interactive launchers for real-time network observation and bandwidth measurement: iftop, iptraf-ng and iperf3. Each tool is auto-installed from apt on first use, runs in the foreground, and is exited with the documented keystroke. Read-only against the host configuration — they only observe traffic.",
|
||||
"section": "Network"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "Three interactive monitoring tools, each behind its own menu entry. The first time you launch one, the package is installed silently via <code>apt-get</code>. Subsequent launches start instantly. None of these tools modify the host network configuration."
|
||||
},
|
||||
"when": {
|
||||
"heading": "When to use which",
|
||||
"headerQuestion": "Question",
|
||||
"headerUse": "Use",
|
||||
"rows": [
|
||||
{
|
||||
"question": "Who is saturating the link <em>right now</em>?",
|
||||
"use": "iftop"
|
||||
},
|
||||
{
|
||||
"question": "What protocol breakdown / packet sizes / TCP flows are flowing?",
|
||||
"use": "iptraf-ng"
|
||||
},
|
||||
{
|
||||
"question": "How much bandwidth is actually available between two hosts?",
|
||||
"use": "iperf3"
|
||||
}
|
||||
]
|
||||
},
|
||||
"iftop": {
|
||||
"heading": "Real-time network usage (iftop)",
|
||||
"body": "Live bandwidth per host pair (source ↔ destination) — like <code>top</code> for traffic. Shows the heaviest flows at the top, with rolling 2/10/40-second averages. Best tool for the question <em>\"why is my uplink saturated?\"</em>.",
|
||||
"exit": "<strong>Exit:</strong> press <kbd>q</kbd>. ProxMenux shows a reminder dialog before launching.",
|
||||
"keysTitle": "Useful keys inside iftop",
|
||||
"keysBody": "<kbd>n</kbd> toggle DNS lookup, <kbd>p</kbd> show port numbers, <kbd>P</kbd> pause display, <kbd>t</kbd> toggle line direction (sent / received / both), <kbd>1</kbd>/<kbd>2</kbd>/<kbd>3</kbd> sort by 2s / 10s / 40s average. <code>man iftop</code> for the full set."
|
||||
},
|
||||
"iptraf": {
|
||||
"heading": "Network monitoring tool (iptraf-ng)",
|
||||
"intro": "A menu-driven multi-mode traffic monitor. Where iftop answers <em>\"who\"</em>, iptraf-ng answers <em>\"what\"</em>: per-protocol byte/packet counts, TCP connection state tracking, packet size histograms and per-station LAN activity.",
|
||||
"menuIntro": "On launch you get a five-option menu:",
|
||||
"headerMode": "Mode",
|
||||
"headerUseFor": "Use it for",
|
||||
"rows": [
|
||||
{
|
||||
"mode": "IP traffic monitor",
|
||||
"useFor": "Live TCP / UDP / ICMP / other-IP flow list with byte counters and connection state"
|
||||
},
|
||||
{
|
||||
"mode": "General interface stats",
|
||||
"useFor": "Aggregate IPv4 / IPv6 / TCP / UDP / ICMP / non-IP packet counts per NIC"
|
||||
},
|
||||
{
|
||||
"mode": "Detailed interface stats",
|
||||
"useFor": "Same as above but for one interface, with packet size and rate detail"
|
||||
},
|
||||
{
|
||||
"mode": "Statistical breakdowns",
|
||||
"useFor": "Packet size distribution histogram, by TCP / UDP port"
|
||||
},
|
||||
{
|
||||
"mode": "LAN station monitor",
|
||||
"useFor": "Per-MAC traffic stats for the local broadcast domain"
|
||||
}
|
||||
],
|
||||
"exit": "<strong>Exit:</strong> press <kbd>x</kbd> from any view (or <kbd>Q</kbd> from the main menu). ProxMenux shows a reminder dialog before launching.",
|
||||
"logTitle": "Logging captures to file",
|
||||
"logBody": "Each mode offers to log captured stats to <code>/var/log/iptraf-ng/</code>. Useful if you need a record of a traffic spike — leave it running, log to file, review the file afterwards instead of trying to read the live screen."
|
||||
},
|
||||
"iperf3": {
|
||||
"heading": "Bandwidth test (iperf3)",
|
||||
"intro1": "Measures actual TCP throughput between two hosts. Unlike iftop / iptraf-ng (which observe existing traffic), iperf3 generates synthetic traffic to stress-test the link. Indispensable for answering questions like <em>\"is my 10 GbE actually doing 10 GbE?\"</em> or <em>\"is the bottleneck the NIC, the switch, or the storage?\"</em>.",
|
||||
"intro2": "iperf3 is a <strong>two-host tool</strong>: one side runs as server (listens on TCP port 5201), the other runs as client (connects, sends data, prints the rate). The ProxMenux launcher asks which mode you want:",
|
||||
"headerMode": "Mode",
|
||||
"headerBehaviour": "Behaviour",
|
||||
"headerCli": "Equivalent CLI",
|
||||
"rows": [
|
||||
{
|
||||
"mode": "Server",
|
||||
"behaviour": "Listens on TCP 5201 and prints results for each incoming test. Stops on Ctrl+C.",
|
||||
"cli": "iperf3 -s"
|
||||
},
|
||||
{
|
||||
"mode": "Client",
|
||||
"behaviour": "Asks for the server IP / hostname, connects, runs a default 10-second test and prints the report.",
|
||||
"cli": "iperf3 -c <target>"
|
||||
}
|
||||
],
|
||||
"workflowIntro": "Typical workflow to test a 10 GbE link between two Proxmox hosts:",
|
||||
"workflow": [
|
||||
"On host A, open the Network menu → <em>Bandwidth test (iperf3)</em> → choose <strong>Server</strong>.",
|
||||
"On host B, open the same menu entry → choose <strong>Client</strong> → enter host A's IP.",
|
||||
"Wait 10 seconds. Compare the reported rate to the link's theoretical maximum."
|
||||
],
|
||||
"sample": "Sample client output:",
|
||||
"flagsTitle": "Useful manual flags (run from a shell)",
|
||||
"flagsBody": "<code>-t 60</code> longer test (60s instead of default 10s), <code>-P 4</code> 4 parallel streams (saturates faster), <code>-R</code> reverse direction (server → client), <code>-u -b 100M</code> UDP test at 100 Mbit/s (for jitter / packet loss measurements), <code>-p 5202</code> use a different port (multiple tests in parallel). <code>man iperf3</code> for the full set.",
|
||||
"firewallTitle": "Open the firewall port on the server",
|
||||
"firewallBody": "The server listens on TCP <strong>5201</strong> by default. If you run the server inside a Proxmox host with a strict firewall (datacenter or host level), allow inbound TCP 5201 from the client's IP for the duration of the test, then close it again. Same applies to <code>nftables</code> / <code>iptables</code> on bare hosts."
|
||||
},
|
||||
"install": {
|
||||
"heading": "First launch installs the package",
|
||||
"body": "All three launchers check for the binary and run <code>apt-get update -qq && apt-get install -y <pkg></code> if missing. The install is silent: the menu may appear frozen for 10–30 seconds the first time. Subsequent launches start instantly."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"hangTitle": "Install hangs forever on first launch",
|
||||
"hangBody": "The host has no internet or the apt repos are unreachable. Cancel with <kbd>Ctrl</kbd>+<kbd>C</kbd>, run <code>apt-get update</code> manually to see the actual error (DNS, repo signature, proxy …), then come back to the menu.",
|
||||
"refusedTitle": "iperf3 client: \"unable to connect to server: Connection refused\"",
|
||||
"refusedBody": "Either the server is not running, or its firewall blocks TCP 5201. Confirm on the server: <code>ss -tlnp | grep 5201</code> — should show iperf3 listening. If listening but client still fails, check the firewall path between the two hosts.",
|
||||
"slowTitle": "iperf3 reports way less than the expected link speed",
|
||||
"slowBody": "Common causes, in order of likelihood: (1) one of the hosts is bottlenecked on CPU — try <code>iperf3 -c <target> -P 4</code> to use multiple cores; (2) the path goes through a slower link (gigabit switch in the middle of two 10 GbE NICs); (3) MTU mismatch — check <code>ip link show</code> on both ends; (4) NIC offloading disabled — see the <em>Disable NIC Offloading</em> community script if you have an Intel e1000e card.",
|
||||
"noTrafficTitle": "iftop / iptraf-ng show no traffic for a busy host",
|
||||
"noTrafficBody": "Default capture is on the first detected interface. Specify the right one explicitly from the shell: <code>iftop -i vmbr0</code> or <code>iptraf-ng -i vmbr0</code>. The menu launcher uses the default; for non-default interfaces, run from a console."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"label": "Diagnostics",
|
||||
"href": "/docs/network/diagnostics",
|
||||
"tail": " — the read-only one-shot checks (routing, connectivity, advanced stats)."
|
||||
},
|
||||
{
|
||||
"label": "Bridge analysis & guided repair",
|
||||
"href": "/docs/network/bridge-analysis",
|
||||
"tail": " — when monitoring reveals an interface or bridge isn't doing what it should."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
130
web/messages/en/docs/network/persistent-names.json
Normal file
130
web/messages/en/docs/network/persistent-names.json
Normal file
@@ -0,0 +1,130 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Persistent Interface Names | ProxMenux Documentation",
|
||||
"description": "Pin Proxmox interface names (eno1, enp3s0, …) to MAC addresses via systemd .link files so names survive PCI re-enumeration, kernel upgrades and adding / removing other NICs.",
|
||||
"ogTitle": "Persistent Interface Names | ProxMenux Documentation",
|
||||
"ogDescription": "Stop Proxmox interface names from changing when you alter hardware. Uses systemd .link files keyed on MAC address."
|
||||
},
|
||||
"header": {
|
||||
"title": "Persistent interface names",
|
||||
"description": "Generates a systemd .link file per physical NIC that pins the kernel-assigned name to the card's MAC address. Once applied (after the next reboot), interface names stop drifting when you add, remove or move PCIe cards.",
|
||||
"section": "Network"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "For every physical NIC on the host, writes a small file under <code>/etc/systemd/network/10-<iface>.link</code> that says: <em>\"the device with this MAC must always be called this name\"</em>. systemd-udevd applies the rule at every boot, before <code>ifupdown</code> reads <code>/etc/network/interfaces</code>."
|
||||
},
|
||||
"problem": {
|
||||
"heading": "The problem this solves",
|
||||
"intro": "Linux derives default interface names from PCI topology — <code>eno1</code> = onboard, <code>enp3s0</code> = the card in PCI bus 3, slot 0, etc. The naming scheme is deterministic <em>given the same hardware layout</em>. Change the layout and names shift:",
|
||||
"items": [
|
||||
"Add a GPU in front of an existing NIC → the NIC bus number can change → name changes.",
|
||||
"Move a card to a different PCIe slot → name changes.",
|
||||
"BIOS / UEFI update that re-enumerates devices → names can change.",
|
||||
"Replace a faulty card with the same model in a different slot → name changes."
|
||||
],
|
||||
"outro": "After such a change, <code>/etc/network/interfaces</code> still references the <em>old</em> name; the bridge fails to come up; the host loses network. Setting up persistent names prevents this scenario from happening again."
|
||||
},
|
||||
"howWorks": {
|
||||
"heading": "How it works",
|
||||
"arrowLabel": "per NIC",
|
||||
"nodes": {
|
||||
"detectLabel": "Detect physical NICs",
|
||||
"detectDetail": "ls /sys/class/net/\nfilter out vmbr / bond /\ndocker / veth / wireguard …",
|
||||
"readLabel": "Read each MAC",
|
||||
"readDetail": "cat /sys/class/net/\n '<'iface'>'/address",
|
||||
"writeLabel": "Write .link file",
|
||||
"writeDetail": "/etc/systemd/network/\n 10-'<'iface'>'.link"
|
||||
},
|
||||
"minimalIntro": "Each generated file is intentionally minimal:",
|
||||
"minimalOutro": "At boot, systemd-udevd matches the device by MAC and assigns the requested name <em>before</em> any other component (ifupdown, kernel default naming) gets to it. The file prefix <code>10-</code> ensures these rules load early, ahead of the default <code>99-default.link</code>."
|
||||
},
|
||||
"scope": {
|
||||
"heading": "What gets written, what gets skipped",
|
||||
"headerType": "Type",
|
||||
"headerBehaviour": "Behaviour",
|
||||
"headerWhy": "Why",
|
||||
"rows": [
|
||||
{
|
||||
"type": "Onboard / PCIe NIC",
|
||||
"behaviour": "<code>.link</code> file written",
|
||||
"why": "Backed by a real PCI device — the case the tool is for"
|
||||
},
|
||||
{
|
||||
"type": "Wi-Fi (phy80211)",
|
||||
"behaviour": "<code>.link</code> file written",
|
||||
"why": "Has a real MAC and benefits from name stability"
|
||||
},
|
||||
{
|
||||
"type": "Bridges (vmbrX)",
|
||||
"behaviour": "Skipped",
|
||||
"why": "Virtual; name comes from <code>/etc/network/interfaces</code>"
|
||||
},
|
||||
{
|
||||
"type": "Bonds (bondX)",
|
||||
"behaviour": "Skipped",
|
||||
"why": "Virtual; bond name is set by ifupdown"
|
||||
},
|
||||
{
|
||||
"type": "veth / docker0 / br-XXXX",
|
||||
"behaviour": "Skipped",
|
||||
"why": "Created on demand by Docker / LXC — not persistent hardware"
|
||||
},
|
||||
{
|
||||
"type": "tap / fwpr / fwln",
|
||||
"behaviour": "Skipped",
|
||||
"why": "Created on demand by Proxmox per VM/CT"
|
||||
},
|
||||
{
|
||||
"type": "WireGuard / Cilium / Tailscale",
|
||||
"behaviour": "Skipped",
|
||||
"why": "Software interfaces managed by their own daemons"
|
||||
}
|
||||
]
|
||||
},
|
||||
"safety": {
|
||||
"heading": "Safety net: previous .link files are backed up",
|
||||
"intro": "If <code>/etc/systemd/network/</code> already contains <code>.link</code> files (from a previous run or other tooling), they are copied to a timestamped backup directory before the new ones are generated:",
|
||||
"outro": "To roll back: copy the files back from the backup directory and reboot.",
|
||||
"rebootTitle": "Takes effect on next reboot, not immediately",
|
||||
"rebootBody": "Changes to <code>.link</code> files only apply at boot, when udev re-enumerates devices. The tool reports <em>\"Changes will apply after reboot\"</em> for this reason. Renaming an interface live is risky and not attempted: an active <code>vmbr0</code> with members would have to be reconfigured atomically, which is why the operation is deferred to the next clean boot."
|
||||
},
|
||||
"afterReboot": {
|
||||
"heading": "After the reboot",
|
||||
"intro": "Once the names are pinned, the workflow for future hardware changes is simple:",
|
||||
"items": [
|
||||
"Power off, change hardware (add card, move slot, …), boot.",
|
||||
"Each NIC keeps its previous name because its MAC matches a <code>.link</code> file.",
|
||||
"If a NIC is replaced (different MAC), it gets a default kernel name (<code>enp<bus>s<slot></code>); re-run this menu to add a <code>.link</code> entry for the new card's MAC."
|
||||
]
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"emptyTitle": "\"No physical interfaces found\" after running the tool",
|
||||
"emptyBody": "The host has no PCI / phy80211-backed interfaces visible to the kernel. Confirm with <code>ls -l /sys/class/net/</code> — every entry should have either a <code>device</code> symlink (PCI) or a <code>phy80211</code> entry (Wi-Fi). If both are missing for what should be a real NIC, the driver is not loaded.",
|
||||
"noChangeTitle": "After the reboot, names did not change as expected",
|
||||
"noChangeBody": "Check that the file is present and well-formed: <code>cat /etc/systemd/network/10-<iface>.link</code>. Then check udev logs: <code>journalctl -u systemd-udevd -b | grep -i link</code>. A common cause is a stale <code>net.ifnames=0</code> kernel parameter that disables predictable naming entirely — remove it from <code>/etc/default/grub</code>, run <code>update-grub</code>, reboot.",
|
||||
"undoTitle": "I want to undo persistent naming",
|
||||
"undoBody": "Either delete the <code>.link</code> files (<code>rm /etc/systemd/network/10-*.link</code>) or restore from the backup directory generated on the previous run. Reboot to apply."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"label": "Bridge analysis & guided repair",
|
||||
"href": "/docs/network/bridge-analysis",
|
||||
"tailRich": " — the recovery path when names <em>have</em> already shifted."
|
||||
},
|
||||
{
|
||||
"label": "Config analysis & guided cleanup",
|
||||
"href": "/docs/network/config-analysis",
|
||||
"tail": " — to remove orphan blocks left behind by name shifts."
|
||||
},
|
||||
{
|
||||
"label": "Diagnostics",
|
||||
"href": "/docs/network/diagnostics",
|
||||
"tailRich": " — confirm the new names with <em>Show Routing Table</em> after reboot."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user