ProxMenux/web/messages/en/docs/utils/system-utils.json

{
  "meta": {
    "title": "System Utilities Installer | ProxMenux Documentation",
    "description": "CLI utility installer for Proxmox VE, with 25 packages in the canonical list (htop, btop, iperf3, tmux, ...). Custom selection, install-all and predefined groups (basic, development, compression, multiplexers, analysis, network). Groups can include additional packages. Uses ensure_repositories + install_single_package.",
    "ogTitle": "System Utilities Installer | ProxMenux Documentation",
    "ogDescription": "Install curated CLI tools on Proxmox VE with one click or custom selection."
  },
  "header": {
    "title": "System Utilities Installer",
    "description": "Picker for 25 CLI utilities in the canonical PROXMENUX_UTILS list. Offers custom selection, install-all, six predefined groups and an installation check. Groups can include tools outside the canonical list. Uses shared ensure_repositories() + install_single_package() helpers for consistent repository handling and per-package feedback.",
    "section": "Utilities"
  },
  "info": {
    "title": "What this does",
    "body": "Installs CLI tools from a list of 25 packages. Every installation uses the same 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> installs the package and checks that its command is in PATH."
  },
  "opening": {
    "heading": "Opening the installer",
    "intro": "From the Utilities menu, choose <strong>System Utilities Installer</strong>. The main menu offers nine options:",
    "imageAlt": "System Utilities Installer menu with custom selection, ALL, predefined groups and verify"
  },
  "actions": {
    "heading": "The 9 menu actions",
    "headerOption": "Option",
    "headerBehaviour": "Behaviour",
    "rows": [
      {
        "option": "1. Custom selection",
        "behaviourRich": "Checklist of all 25 packages. Use SPACE to toggle and ENTER to confirm; only the selected packages are installed."
      },
      {
        "option": "2. Install ALL utilities",
        "behaviourRich": "One-shot install of every package in <code>PROXMENUX_UTILS</code>. Use after a fresh Proxmox install."
      },
      {
        "option": "3. Basic",
        "behaviourRich": "<code>grc</code>, <code>htop</code>, <code>tree</code>, <code>curl</code>, <code>wget</code>"
      },
      {
        "option": "4. Development",
        "behaviourRich": "<code>git</code>, <code>vim</code>, <code>nano</code>"
      },
      {
        "option": "5. Compression",
        "behaviourRich": "<code>zip</code>, <code>unzip</code>, <code>rsync</code>"
      },
      {
        "option": "6. Terminal multiplexers",
        "behaviourRich": "<code>screen</code>, <code>tmux</code>"
      },
      {
        "option": "7. Analysis",
        "behaviourRich": "<code>jq</code>, <code>ncdu</code>, <code>iotop</code>"
      },
      {
        "option": "8. Network",
        "behaviourRich": "<code>iperf3</code>, <code>nethogs</code>, <code>nmap</code>, <code>tcpdump</code>, <code>lsof</code>"
      },
      {
        "option": "9. Verify installations",
        "behaviourRich": "Walks every entry in <code>PROXMENUX_UTILS</code>, checks if the verify command is in PATH, prints an Available / Missing summary."
      }
    ]
  },
  "packages": {
    "heading": "The 25 packages",
    "intro": "Defined in the shared <code>scripts/global/utils-install-functions.sh</code> as <code>PROXMENUX_UTILS</code> (format: <code>package:verify_command:description</code>). Other ProxMenux scripts (e.g. the network monitoring launchers for iftop / iptraf-ng / iperf3) reuse entries from this list so package + verify command stay in sync.",
    "headerPackage": "Package",
    "headerVerify": "Verify command",
    "headerDescription": "Description",
    "rows": [
      {
        "package": "axel",
        "verify": "axel",
        "description": "Download accelerator"
      },
      {
        "package": "aria2",
        "verify": "aria2c",
        "description": "Multi-source downloader"
      },
      {
        "package": "btop",
        "verify": "btop",
        "description": "Modern resource monitor"
      },
      {
        "package": "cabextract",
        "verify": "cabextract",
        "description": "Extract CAB files"
      },
      {
        "package": "chntpw",
        "verify": "chntpw",
        "description": "Edit Windows registry / passwords"
      },
      {
        "package": "dos2unix",
        "verify": "dos2unix",
        "description": "Convert DOS / Unix text files"
      },
      {
        "package": "genisoimage",
        "verify": "genisoimage",
        "description": "Create ISO images"
      },
      {
        "package": "grc",
        "verify": "grc",
        "description": "Generic log colorizer"
      },
      {
        "package": "htop",
        "verify": "htop",
        "description": "Interactive process viewer"
      },
      {
        "package": "iftop",
        "verify": "iftop",
        "description": "Real-time network usage"
      },
      {
        "package": "intel-gpu-tools",
        "verify": "intel_gpu_top",
        "description": "Intel GPU tools"
      },
      {
        "package": "iotop",
        "verify": "iotop",
        "description": "Monitor disk I/O usage"
      },
      {
        "package": "iperf3",
        "verify": "iperf3",
        "description": "Network bandwidth testing"
      },
      {
        "package": "ipset",
        "verify": "ipset",
        "description": "Manage IP sets"
      },
      {
        "package": "iptraf-ng",
        "verify": "iptraf-ng",
        "description": "Network monitoring tool"
      },
      {
        "package": "libguestfs-tools",
        "verify": "virt-filesystems",
        "description": "VM disk utilities"
      },
      {
        "package": "msr-tools",
        "verify": "rdmsr",
        "description": "Access CPU MSRs"
      },
      {
        "package": "net-tools",
        "verify": "netstat",
        "description": "Legacy networking tools"
      },
      {
        "package": "plocate",
        "verify": "locate",
        "description": "Locate files quickly"
      },
      {
        "package": "s-tui",
        "verify": "s-tui",
        "description": "Stress-Terminal UI"
      },
      {
        "package": "sshpass",
        "verify": "sshpass",
        "description": "Non-interactive SSH login"
      },
      {
        "package": "tmux",
        "verify": "tmux",
        "description": "Terminal multiplexer"
      },
      {
        "package": "unzip",
        "verify": "unzip",
        "description": "Extract ZIP files"
      },
      {
        "package": "wimtools",
        "verify": "wimlib-imagex",
        "description": "Manage WIM images"
      },
      {
        "package": "zip",
        "verify": "zip",
        "description": "Create ZIP files"
      }
    ]
  },
  "howItWorks": {
    "heading": "How a single package install works",
    "items": [
      "<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:",
    "verifyOutcomes": [
      "<strong>0 (success):</strong> command available, package counted as <em>Successful</em>.",
      "<strong>1 (failed):</strong> apt failed, counted as <em>Failed</em>.",
      "<strong>2 (warning):</strong> apt succeeded but the expected command was not found in PATH — counted as <em>With warnings</em>."
    ],
    "summary": "At the end of a group / custom install, a summary dialog shows <em>Successful / With warnings / Failed</em> counts."
  },
  "verify": {
    "heading": "Verify installations",
    "intro": "Option 9 is read-only: it walks <code>PROXMENUX_UTILS</code> and runs <code>command -v</code> for each verify command. Output looks like this:",
    "code": "Total: 25\nAvailable: 18\nMissing: 8\n\n✓ axel - Download accelerator\n✓ aria2c - Multi-source downloader\n✓ btop - Modern resource monitor\n✗ cabextract - Extract CAB files\n✓ dos2unix - Convert DOS / Unix text files\n✗ genisoimage - Create ISO images\n✓ grc - Generic log colorizer\n...",
    "outro": "Useful before running scripts that depend on these tools (e.g. <code>uup_dump_iso_creator.sh</code> needs <code>aria2c</code> + <code>cabextract</code> + <code>wimlib-imagex</code>). If anything is missing, run the matching group install or pick the missing packages via custom selection."
  },
  "troubleshoot": {
    "heading": "Troubleshooting",
    "reposTitle": "\"Failed to configure repositories. Installation aborted.\"",
    "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": "After <code>apt-get install</code>, the helper runs <code>hash -r</code>, waits briefly and checks the expected command with <code>command -v</code>. A warning means that check still failed; it does not identify the cause. Try a new shell, then check the package installation and PATH if the command is still missing.",
    "hangsTitle": "An apt install hangs",
    "hangsBody": "Most likely a debconf prompt is blocked behind the silenced output. The script wraps all apt calls with <code>DEBIAN_FRONTEND=noninteractive</code>, which usually suppresses prompts, but a few packages still require user input. Cancel with <kbd>Ctrl</kbd>+<kbd>C</kbd>, run <code>apt-get install -y &lt;pkg&gt;</code> manually from a shell to see the prompt and decide."
  },
  "files": {
    "heading": "Files involved",
    "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",
    "items": [
      {
        "href": "/docs/utils/system-update",
        "label": "Proxmox System Update",
        "tailRich": " — for the actual <code>apt dist-upgrade</code> on the host."
      },
      {
        "href": "/docs/network/monitoring",
        "label": "Live monitoring tools (Network)",
        "tailRich": " — uses iftop / iptraf-ng / iperf3 from this same list."
      },
      {
        "href": "/docs/utils",
        "label": "Utilities overview",
        "tailRich": " — back to the section overview."
      }
    ]
  }
}