mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-06-01 21:14:49 +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:
MacRimi
@@ -0,0 +1,128 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Add Controller or NVMe to VM | ProxMenux Documentation",
|
||||
"description": "PCI passthrough of a storage controller (SATA / SAS HBA) or NVMe device to a Proxmox VM using ProxMenux. Handles IOMMU enablement, conflict detection and qm set --hostpci wiring.",
|
||||
"ogTitle": "Add Controller or NVMe to VM | ProxMenux Documentation",
|
||||
"ogDescription": "Pass a whole SATA / SAS HBA or NVMe device into a Proxmox VM. ProxMenux handles IOMMU, conflict detection and hostpci wiring."
|
||||
},
|
||||
"header": {
|
||||
"title": "Add Controller or NVMe to VM",
|
||||
"description": "Pass a whole SATA / SAS host bus adapter (HBA) or NVMe device into a Proxmox VM via PCI passthrough. ProxMenux checks and — with your consent — enables IOMMU, enumerates the passthrough-eligible devices, filters out conflicts and wires the assignment with qm set --hostpci.",
|
||||
"section": "Disk Manager · VM"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does (and does not) do",
|
||||
"body": "This is <strong>device-level passthrough</strong>: the PCIe card leaves the host kernel's view and is bound to <code>vfio-pci</code>. The VM sees the controller itself — not the individual disks behind it — and loads its own driver for that exact model. Every disk attached to that controller follows it automatically, with native SMART data, full firmware features and no Proxmox layer in between."
|
||||
},
|
||||
"howRuns": {
|
||||
"heading": "How the script runs",
|
||||
"body": "The flow has two phases with clear separation between \"collecting information, checking IOMMU and listing candidates\" and \"actually attaching the PCI device\". Until the final confirmation nothing is written to the VM config."
|
||||
},
|
||||
"iommu": {
|
||||
"heading": "IOMMU groups — why the whole card leaves at once",
|
||||
"body": "PCI passthrough is done per <strong>IOMMU group</strong>, which is the smallest unit the CPU's IOMMU can isolate. Everything inside a group moves together. If your SATA controller shares its IOMMU group with the USB controller, passing the SATA card to a VM also takes the USB ports with it — often undesirable.",
|
||||
"outro": "ProxMenux shows the IOMMU group next to each device and warns you when a group carries more than just the controller you want. You can still proceed if the extra devices in the group are acceptable (all disk controllers, for example), or back out if they are not."
|
||||
},
|
||||
"prereqs": {
|
||||
"heading": "Prerequisites",
|
||||
"items": [
|
||||
"<strong>CPU and motherboard support</strong> VT-d (Intel) or AMD-Vi, and it is enabled in firmware (BIOS/UEFI). ProxMenux can enable the kernel side for you, but it cannot flip the firmware switch.",
|
||||
"The target VM is <strong>powered off</strong> before attaching PCI devices.",
|
||||
"The controller/NVMe <strong>is not the one holding the Proxmox root filesystem</strong>. The script hides anything in use by the host.",
|
||||
"Guest OS has drivers for the controller model. Linux covers virtually every HBA out of the box; Windows needs the vendor driver installed <em>before</em> you boot with the controller attached."
|
||||
],
|
||||
"warnTitle": "Live migration is not possible",
|
||||
"warnBody": "A VM with PCI passthrough is tied to the node that physically holds the card. Live migration across nodes will fail. Plan backups / replication accordingly."
|
||||
},
|
||||
"steps": {
|
||||
"heading": "Step-by-step",
|
||||
"stepLabel": "Step",
|
||||
"list": [
|
||||
{
|
||||
"title": "Pick the target VM",
|
||||
"bodyRich": "ProxMenux reads <code>qm list</code> and shows every VM. Pick the one that will receive the controller.",
|
||||
"img": "/disk/nvme-passthrough/vm-selection.png",
|
||||
"alt": "VM selection dialog",
|
||||
"caption": "VM selection dialog"
|
||||
},
|
||||
{
|
||||
"title": "IOMMU check",
|
||||
"bodyRich": "If IOMMU is not enabled on the kernel cmdline, ProxMenux offers to enable it. It edits <code>/etc/kernel/cmdline</code> (for systemd-boot) or <code>/etc/default/grub</code> (for GRUB) and appends the correct parameter for your CPU:",
|
||||
"items": [
|
||||
"<code>intel_iommu=on</code> for Intel CPUs.",
|
||||
"<code>amd_iommu=on</code> for AMD CPUs."
|
||||
],
|
||||
"outro": "A reboot is required after this change. The script prompts you to reboot now or later; the passthrough cannot continue until the new kernel cmdline is active.",
|
||||
"img": "/disk/nvme-passthrough/iommu-warning.png",
|
||||
"alt": "IOMMU Required dialog",
|
||||
"caption": "IOMMU Required — offer to enable and reboot"
|
||||
},
|
||||
{
|
||||
"title": "Device enumeration",
|
||||
"body": "ProxMenux lists every storage controller (SATA / SAS HBA) and every NVMe device on the PCI bus. For each device it shows:",
|
||||
"items": [
|
||||
"PCI address (<code>00:17.0</code>, <code>01:00.0</code>, …).",
|
||||
"Vendor / device description.",
|
||||
"IOMMU group — and a ⚠ warning if the group is shared with other, unrelated devices.",
|
||||
"The disks currently behind the controller (so you know what will follow it to the VM)."
|
||||
],
|
||||
"img": "/disk/nvme-passthrough/device-list.png",
|
||||
"alt": "Controller / NVMe device enumeration",
|
||||
"caption": "Controller / NVMe device enumeration with IOMMU group info"
|
||||
},
|
||||
{
|
||||
"title": "Conflict detection",
|
||||
"bodyRich": "The script blocks devices that are clearly unsafe: already assigned to another VM (via <code>hostpci</code> in that VM's config), in use by the host (root disk controller), or sitting in an IOMMU group whose other members the script cannot identify safely. Eligible devices are available for selection.",
|
||||
"img": "/disk/nvme-passthrough/conflict-warning.png",
|
||||
"alt": "Conflict detection warning",
|
||||
"caption": "Conflict detection — device blocked with reason"
|
||||
},
|
||||
{
|
||||
"title": "Attach and finalise",
|
||||
"bodyRich": "For every selected device ProxMenux runs <code>qm set <VMID> --hostpciN <pci-addr>,pcie=1</code>, choosing the next free <code>hostpci</code> slot. If IOMMU was enabled during this session you are reminded to reboot before starting the VM.",
|
||||
"img": "/disk/nvme-passthrough/assignment.png",
|
||||
"alt": "Assignment summary",
|
||||
"caption": "Assignment summary — hostpciN slots and PCI addresses attached"
|
||||
}
|
||||
]
|
||||
},
|
||||
"manual": {
|
||||
"heading": "Manual equivalent"
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"noGroupsTitle": "IOMMU enabled but no groups under /sys/kernel/iommu_groups/",
|
||||
"noGroupsBody": "Reboot is required for the kernel cmdline to take effect. If the groups are still missing after reboot, VT-d / AMD-Vi is probably disabled in firmware — check the BIOS/UEFI setup.",
|
||||
"busyTitle": "VM fails to start with \"hostpciN: device busy\"",
|
||||
"busyBody": "Another process still holds the PCI device. Most common causes: a previous VM that crashed without releasing it, or the host kernel reclaimed it on the last boot. Run <code>lspci -nnk -s <addr></code> to see which driver is bound; it should be <code>vfio-pci</code>. A full host reboot usually clears this.",
|
||||
"noDisksTitle": "Guest sees the controller but not the disks",
|
||||
"noDisksBody": "The controller model lacks an in-guest driver. Linux almost never hits this; Windows does — install the vendor driver (e.g. LSI / Broadcom for older SAS HBAs) while the card is detached, then reboot with the card attached.",
|
||||
"sharedTitle": "Shared IOMMU group also exports an unrelated device",
|
||||
"sharedBody": "Options: (a) move the card to a different PCIe slot to change its group, (b) enable <em>ACS override</em> in the kernel to split groups (security trade-off — research before applying), or (c) pick a different card in a cleaner group."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"href": "/docs/disk-manager/import-disk-vm",
|
||||
"label": "Import Disk to VM",
|
||||
"tail": " — alternative model: attach a physical disk via Proxmox without full PCIe passthrough."
|
||||
},
|
||||
{
|
||||
"href": "/docs/hardware/gpu-vm-passthrough",
|
||||
"label": "Add GPU to VM (Passthrough)",
|
||||
"tail": " — same IOMMU / VFIO concepts applied to a GPU."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/gpu-commands",
|
||||
"label": "GPU Passthrough commands",
|
||||
"tail": " — IOMMU verification commands also apply to controller / NVMe passthrough."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager",
|
||||
"label": "Disk Manager overview",
|
||||
"tail": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,142 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Format / Wipe Physical Disk | ProxMenux Documentation",
|
||||
"description": "Secure physical disk wipe and format on Proxmox VE using ProxMenux. Four operation modes, strict safety filters (system / mounted / in-use disks blocked) and double confirmation including full path typing.",
|
||||
"ogTitle": "Format / Wipe Physical Disk | ProxMenux Documentation",
|
||||
"ogDescription": "Securely wipe or format a physical disk on Proxmox. Safe visibility rules, 4 operation modes, double confirmation."
|
||||
},
|
||||
"header": {
|
||||
"title": "Format / Wipe Physical Disk",
|
||||
"description": "Securely wipe or format a physical disk on the Proxmox host. ProxMenux only shows disks that are fully free (no system use, no guest reference, no mounts) and forces a double confirmation — yes/no plus typing the full disk path — before destroying any data.",
|
||||
"section": "Disk Manager · Utilities"
|
||||
},
|
||||
"danger": {
|
||||
"title": "Destructive tool",
|
||||
"body": "Every operation here writes to the disk. There is no undo. ProxMenux applies strict safety filters and confirmations, but the responsibility for picking the right disk is yours. Read the disk path out loud twice before you type it."
|
||||
},
|
||||
"howRuns": {
|
||||
"heading": "How the script runs",
|
||||
"body": "The flow has two phases with a triple-gate safety filter in between. The disk list, the operation mode and the file system details are all collected in Phase 1; nothing is written until Phase 2 passes a final re-validation right before executing."
|
||||
},
|
||||
"visibility": {
|
||||
"heading": "Visibility rules",
|
||||
"intro": "Before the menu even appears, ProxMenux filters the disk list. Only candidates that are provably safe are shown:",
|
||||
"items": [
|
||||
"<strong>Shown</strong> — disks <em>not</em> used by the host (root pool, swap, mounted, active ZFS/LVM/RAID) and <em>not</em> referenced by any VM/LXC config (running or stopped).",
|
||||
"<strong>Hidden</strong> — host / system disks.",
|
||||
"<strong>Hidden</strong> — disks referenced by a VM/LXC config."
|
||||
],
|
||||
"safetyTitle": "Safety at confirmation and execution",
|
||||
"safetyItems": [
|
||||
"Disks with stale / active metadata show detailed warnings <em>before</em> you confirm.",
|
||||
"Disks used by a <strong>running</strong> VM are <strong>hard-blocked</strong> at confirmation.",
|
||||
"Disks with mounted partitions are <strong>hard-blocked</strong> at execution (a fresh re-validation runs right before anything is written).",
|
||||
"Two confirmations are always required: <em>yes/no</em> dialog + typing the full disk path exactly."
|
||||
]
|
||||
},
|
||||
"modes": {
|
||||
"heading": "Operation modes",
|
||||
"intro": "After picking a disk you choose one of four modes. They differ in what they destroy and what they leave behind:",
|
||||
"headerMode": "Mode",
|
||||
"headerPart": "Partition table",
|
||||
"headerData": "Data",
|
||||
"headerUseCase": "Use case",
|
||||
"rows": [
|
||||
{
|
||||
"mode": "1. Wipe all",
|
||||
"part": "Destroyed",
|
||||
"data": "Signatures wiped",
|
||||
"useCase": "Starting fresh: everything on the disk goes, ready for a new layout."
|
||||
},
|
||||
{
|
||||
"mode": "2. Remove FS labels",
|
||||
"part": "Preserved",
|
||||
"data": "Preserved",
|
||||
"useCase": "Clears stale ZFS / LVM / RAID signatures so the disk stops being auto-claimed, without touching the data."
|
||||
},
|
||||
{
|
||||
"mode": "3. Zero all data",
|
||||
"part": "Preserved",
|
||||
"data": "Destroyed (zeroed)",
|
||||
"useCase": "Sanitise before handing the disk over, keeping the existing partition layout."
|
||||
},
|
||||
{
|
||||
"mode": "4. Full format",
|
||||
"part": "New GPT",
|
||||
"data": "Destroyed",
|
||||
"useCase": "Ready-to-use disk with a single new partition and a fresh filesystem."
|
||||
}
|
||||
],
|
||||
"fullFormatOutro": "<strong>Full format</strong> continues with two extra dialogs:",
|
||||
"fullFormatItems": [
|
||||
"<strong>Filesystem</strong> — <code>ext4</code>, <code>xfs</code>, <code>exfat</code> (portable), or <code>btrfs</code>. Missing tools (for example <code>mkfs.btrfs</code>) abort with a clear message.",
|
||||
"<strong>Label</strong> — optional filesystem label for identification."
|
||||
]
|
||||
},
|
||||
"steps": {
|
||||
"heading": "Step-by-step",
|
||||
"stepLabel": "Step",
|
||||
"list": [
|
||||
{
|
||||
"title": "Pick a free disk",
|
||||
"body": "ProxMenux lists every disk that passes the visibility filters above. Disks with ⚠ markers carry stale metadata and are shown with the details so you know what you are about to overwrite."
|
||||
},
|
||||
{
|
||||
"title": "Pick an operation mode",
|
||||
"bodyRich": "Choose between <strong>Wipe all</strong>, <strong>Remove FS labels</strong>, <strong>Zero all data</strong> or <strong>Full format</strong> according to the table above."
|
||||
},
|
||||
{
|
||||
"title": "(Full format only) Pick filesystem and label",
|
||||
"body": "ext4 / xfs / exfat / btrfs, plus an optional label."
|
||||
},
|
||||
{
|
||||
"title": "Confirm twice",
|
||||
"bodyRich": "ProxMenux shows a summary of what will happen. You accept with a yes/no dialog and <strong>type the full disk path</strong> exactly as shown (for example <code>/dev/sdc</code>). Anything else aborts."
|
||||
},
|
||||
{
|
||||
"title": "Re-validation and execution",
|
||||
"body": "Just before writing, the script re-checks the disk state. If a partition has been mounted or a VM started in the meantime, execution is aborted. Otherwise the chosen operation runs and a summary is printed at the end."
|
||||
}
|
||||
]
|
||||
},
|
||||
"manual": {
|
||||
"heading": "Manual equivalents",
|
||||
"body": "If you prefer to run the equivalent commands by hand:"
|
||||
},
|
||||
"troubleshoot": {
|
||||
"notListedTitle": "Disk not listed in the menu",
|
||||
"notListedBody": "It was filtered for safety. Common reasons: it is mounted (even at <code>/mnt/tmp</code>), it is an active ZFS / LVM / RAID member, it is referenced by a VM or LXC config, or it is your Proxmox root disk. Run <code>lsblk -f</code> and <code>cat /proc/mdstat</code> on the host to understand why.",
|
||||
"busyTitle": "\"Disk may be busy\" / unmount failed",
|
||||
"busyBody": "Something is still holding an open file on a partition of that disk — most often a container or a shell whose cwd is inside a mountpoint. Identify it with <code>lsof | grep /dev/sdX</code> or <code>fuser -vm /dev/sdX1</code>, stop it, then re-run the tool."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"href": "/docs/disk-manager/smart-disk-test",
|
||||
"label": "SMART Disk Health & Test",
|
||||
"tail": " — check a disk before / after wiping to confirm it's healthy."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager/import-disk-vm",
|
||||
"label": "Import Disk to VM",
|
||||
"tail": " — pass a freshly-formatted disk to a VM."
|
||||
},
|
||||
{
|
||||
"href": "/docs/storage-share/host-local-disk",
|
||||
"label": "Add local disk as Proxmox storage",
|
||||
"tail": " — register a wiped disk as a Proxmox storage pool."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/storage-commands",
|
||||
"label": "Storage and Disks commands",
|
||||
"tail": " — lsblk, blkid, parted reference."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager",
|
||||
"label": "Disk Manager overview",
|
||||
"tail": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,110 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Import Disk Image to VM | ProxMenux Documentation",
|
||||
"description": "Import a disk image file (.img / .qcow2 / .vmdk / .raw) into an existing Proxmox VM using ProxMenux. Per-image interface, SSD emulation and bootable flag, with qm importdisk under the hood.",
|
||||
"ogTitle": "Import Disk Image to VM | ProxMenux Documentation",
|
||||
"ogDescription": "Import .img / .qcow2 / .vmdk / .raw disk images into an existing VM with ProxMenux. Uses qm importdisk under the hood."
|
||||
},
|
||||
"header": {
|
||||
"title": "Import Disk Image to VM",
|
||||
"description": "Import a disk image file (.img, .qcow2, .vmdk or .raw) into an existing Proxmox VM. ProxMenux collects every decision up-front — target VM, Proxmox storage, source directory, interface, SSD emulation, boot order — and then runs qm importdisk for every selected image.",
|
||||
"section": "Disk Manager · VM"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "Unlike <em>Import Disk to VM</em> (which attaches a raw physical disk), this flow takes a <strong>file</strong> sitting on the host — exported from another hypervisor, downloaded as a cloud image, extracted from a backup — and converts it into a proper Proxmox VM disk on the storage volume of your choice. The original file is preserved; ProxMenux copies it, it does not move it."
|
||||
},
|
||||
"howRuns": {
|
||||
"heading": "How the script runs",
|
||||
"body": "The flow has two phases. Phase 1 collects every decision (VM, storage, source directory, images, per-image options) up-front via dialogs. Phase 2 runs <code>qm importdisk</code> for each selected image. Until Phase 2 begins, nothing is copied and the VM config is not touched."
|
||||
},
|
||||
"prereqs": {
|
||||
"heading": "Prerequisites",
|
||||
"items": [
|
||||
"At least one VM defined on the host. The target VM should be <strong>powered off</strong>.",
|
||||
"At least one image file of a supported format in the source directory. Supported: <code>.img</code>, <code>.qcow2</code>, <code>.vmdk</code>, <code>.raw</code>.",
|
||||
"Enough free space on the target Proxmox storage to hold each imported disk.",
|
||||
"ProxMenux looks for images in <code>/var/lib/vz/template/iso</code> by default. You can point it to any other directory on the host when it asks."
|
||||
]
|
||||
},
|
||||
"steps": {
|
||||
"heading": "Step-by-step",
|
||||
"stepLabel": "Step",
|
||||
"list": [
|
||||
{
|
||||
"title": "Pick the target VM",
|
||||
"bodyRich": "ProxMenux reads <code>qm list</code> and shows every VM. Pick the one that will receive the imported disk(s)."
|
||||
},
|
||||
{
|
||||
"title": "Pick the Proxmox storage",
|
||||
"bodyRich": "The list contains every storage that has the <code>images</code> content type enabled. If there is only one candidate it is auto-selected and the dialog is skipped."
|
||||
},
|
||||
{
|
||||
"title": "Pick the source directory",
|
||||
"bodyRich": "Choose the default directory (<code>/var/lib/vz/template/iso</code>) or type a custom path — typically where you downloaded / uploaded the image. The script rejects paths that do not exist."
|
||||
},
|
||||
{
|
||||
"title": "Pick one or several images",
|
||||
"bodyRich": "The directory is scanned for <code>.img</code> / <code>.qcow2</code> / <code>.vmdk</code> / <code>.raw</code> files. You can select several at once; each will go through the per-image options in the next step."
|
||||
},
|
||||
{
|
||||
"title": "Per-image options",
|
||||
"intro": "For every selected image ProxMenux asks:",
|
||||
"items": [
|
||||
"<strong>Interface</strong> — <code>scsi</code> (default), <code>virtio</code>, <code>sata</code> or <code>ide</code>. Matches how the guest will see the disk.",
|
||||
"<strong>SSD emulation</strong> — only offered for non-VirtIO interfaces. Adds <code>ssd=1</code> so the guest advertises the disk as solid-state (useful for OS-level TRIM / alignment).",
|
||||
"<strong>Bootable</strong> — if yes, ProxMenux adds the disk to the boot order so it becomes the primary boot device of the VM."
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Import and attach",
|
||||
"bodyRich": "ProxMenux runs <code>qm importdisk</code> for every image (converting format on the fly where needed), attaches the resulting disk to the next free slot (<code>scsiN</code>, <code>sataN</code>, …) with your chosen options and — if you marked any disk as bootable — updates the boot order. Progress shows in the terminal."
|
||||
}
|
||||
]
|
||||
},
|
||||
"manual": {
|
||||
"heading": "Manual equivalent",
|
||||
"body": "A single-image import maps to three <code>qm</code> commands:",
|
||||
"warnTitle": "Image format conversion",
|
||||
"warnBody": "When the target storage cannot hold the source format natively (for example, LVM storage cannot hold <code>.qcow2</code>), <code>qm importdisk</code> converts the image transparently. This can take several minutes for multi-GB images; plan accordingly and do not interrupt the script."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"noImagesTitle": "\"No compatible disk images found\"",
|
||||
"noImagesBody": "The script scanned the directory but found no <code>.img</code> / <code>.qcow2</code> / <code>.vmdk</code> / <code>.raw</code> file. Check the extension (case matters), that the file sits directly in the selected directory (no sub-directories are searched) and that permissions allow root to read it.",
|
||||
"slowTitle": "Import is slow",
|
||||
"slowBody": "VMDK → QCOW2 → raw conversions are CPU- and I/O-bound. Import speed depends on the source read speed, the target storage write speed and CPU for decompression. Prefer raw or qcow2 sources when possible.",
|
||||
"uefiTitle": "Imported disk boots into UEFI shell",
|
||||
"uefiBody": "The image was built for legacy (SeaBIOS) but the VM uses OVMF (or vice versa). Either switch the VM's BIOS in Proxmox to match the image, or rebuild the image in the correct mode before importing."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"href": "/docs/disk-manager/import-disk-vm",
|
||||
"label": "Import Disk to VM",
|
||||
"tail": " — same flow but for raw physical disks (passthrough)."
|
||||
},
|
||||
{
|
||||
"href": "/docs/utils/import-vm",
|
||||
"label": "Import VM from OVA / OVF",
|
||||
"tail": " — when you have a full VM package, not just a disk image."
|
||||
},
|
||||
{
|
||||
"href": "/docs/utils/UUp-Dump-ISO-Creator",
|
||||
"label": "UUP Dump ISO Creator",
|
||||
"tail": " — generate a Windows ISO if you need one for a fresh install."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/storage-commands",
|
||||
"label": "Storage and Disks commands",
|
||||
"tail": " — qm importdisk and qemu-img convert reference."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager",
|
||||
"label": "Disk Manager overview",
|
||||
"tail": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,115 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Import Disk to LXC | ProxMenux Documentation",
|
||||
"description": "Attach a physical disk to an existing LXC container on Proxmox VE using ProxMenux. Handles filesystem detection / formatting, mount point, unprivileged → privileged conversion and persistent device paths.",
|
||||
"ogTitle": "Import Disk to LXC | ProxMenux Documentation",
|
||||
"ogDescription": "Attach a physical disk to an existing LXC container. Handles filesystem, mount point and unprivileged → privileged conversion."
|
||||
},
|
||||
"header": {
|
||||
"title": "Import Disk to LXC",
|
||||
"description": "Attach a physical disk to an existing LXC container on the Proxmox host. ProxMenux detects free disks, optionally formats them with a supported filesystem, and wires the partition to a mount point inside the container using persistent device paths.",
|
||||
"section": "Disk Manager · LXC"
|
||||
},
|
||||
"intro": {
|
||||
"title": "VM passthrough vs LXC passthrough",
|
||||
"body": "LXC passthrough is <strong>not a raw block device</strong>. The container gets a <em>mount point</em> — i.e. a directory backed by a partition you pick on the host. Unlike a VM, the guest kernel is the host kernel, so the filesystem (ext4 / xfs / btrfs) is read and managed by Proxmox itself and then exposed to the container."
|
||||
},
|
||||
"howRuns": {
|
||||
"heading": "How the script runs",
|
||||
"body": "The flow has two phases with clear separation between \"collecting information and decisions\" and \"actually changing the container config\". Until the final confirmation, nothing is mounted into the CT.",
|
||||
"summary": "ProxMenux filters out the root disk, mounted disks, and disks already referenced by any VM/LXC config. Disks with active ZFS/LVM/RAID membership are hidden; stale signatures show a ⚠ label so you can wipe them before formatting."
|
||||
},
|
||||
"prereqs": {
|
||||
"heading": "Prerequisites",
|
||||
"items": [
|
||||
"At least one LXC container defined on the host.",
|
||||
"The container is <strong>privileged</strong>, or you accept the script's offer to convert it.",
|
||||
"At least one physical disk not in use by the host or any other guest."
|
||||
],
|
||||
"warnTitle": "Privileged container required",
|
||||
"warnBody": "Direct device passthrough to an LXC container only works if the container is <strong>privileged</strong>. If the script detects <code>unprivileged: 1</code> in the config it offers to convert it in place (edits <code>/etc/pve/lxc/<CTID>.conf</code>). Cancel if you cannot accept the security trade-off of a privileged container."
|
||||
},
|
||||
"steps": {
|
||||
"heading": "Step-by-step",
|
||||
"stepLabel": "Step",
|
||||
"list": [
|
||||
{
|
||||
"title": "Pick the target container",
|
||||
"img": "/disk/select-container.png",
|
||||
"caption": "Container selection menu",
|
||||
"bodyRich": "ProxMenux lists every LXC container on the host (<code>pct list</code>). Pick the one that will receive the disk. If the container is unprivileged you are offered to convert it now."
|
||||
},
|
||||
{
|
||||
"title": "Pick the physical disk",
|
||||
"img": "/disk/disk-selection-ct.png",
|
||||
"caption": "Free disks detected on the host (with ⚠ labels for stale metadata)",
|
||||
"bodyRich": "Only safe candidates are shown. Unlike the VM flow, this script attaches <strong>one disk per run</strong> — run it again for each extra disk you want to add."
|
||||
},
|
||||
{
|
||||
"title": "Format or reuse",
|
||||
"intro": "The script inspects the disk:",
|
||||
"items": [
|
||||
"If it already carries a supported filesystem (ext4 / xfs / btrfs) you can reuse it as-is (existing files are preserved).",
|
||||
"If it has no supported filesystem you are offered to format it. Pick ext4 / xfs / btrfs."
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Pick the mount point",
|
||||
"bodyRich": "Type the path where the container should see the disk, e.g. <code>/mnt/data</code> or <code>/mnt/disk_passthrough</code>. This is the path <em>inside</em> the container; the host already sees the partition under <code>/dev/disk/by-id/…</code>."
|
||||
},
|
||||
{
|
||||
"title": "Attach and verify",
|
||||
"img": "/disk/assignment-ct.png",
|
||||
"caption": "Assignment to CT",
|
||||
"bodyRich": "ProxMenux appends a fresh <code>mpN:</code> entry to the container config, skipping indexes already in use, and re-reads the config to confirm. If the container is running the mount is exec'd live; otherwise it takes effect on the next start.",
|
||||
"extraImg": "/disk/result-point.png",
|
||||
"extraAlt": "Mount point created successfully",
|
||||
"extraCaption": "Mount point created and verified"
|
||||
}
|
||||
]
|
||||
},
|
||||
"manual": {
|
||||
"heading": "Manual equivalent",
|
||||
"body": "The script wraps <code>pct set</code>. A direct invocation for a single disk looks like:"
|
||||
},
|
||||
"important": {
|
||||
"heading": "Important considerations",
|
||||
"items": [
|
||||
"<strong>One disk per run</strong>. Re-run the script for each additional disk.",
|
||||
"Do <strong>not</strong> attach the same partition to several containers that might mount it simultaneously — concurrent writes corrupt the filesystem.",
|
||||
"<strong>Old metadata</strong> (RAID / ZFS / LVM signatures) must be cleared manually before the script will let you format, otherwise <code>mkfs</code> refuses to overwrite. Use the <wipeLink>Format / Wipe Physical Disk</wipeLink> tool for that."
|
||||
]
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"unprivTitle": "\"Cannot continue with an unprivileged container\"",
|
||||
"unprivBody": "You declined the conversion offer. Either re-run and accept the conversion, or convert the container manually by editing <code>/etc/pve/lxc/<CTID>.conf</code> and replacing <code>unprivileged: 1</code> with <code>unprivileged: 0</code>. You can also rebuild the container as privileged if you prefer not to convert in place.",
|
||||
"permsTitle": "Permissions inside the container are wrong",
|
||||
"permsBody": "Mounts from the host into a privileged container land as <code>root:root</code>. If the service inside the CT runs as a different user (e.g. <code>www-data</code> for Nextcloud), <code>chown</code>/<code>chmod</code> inside the container to match its UID/GID after the first mount."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"href": "/docs/disk-manager/import-disk-vm",
|
||||
"label": "Import Disk to VM",
|
||||
"tail": " — equivalent flow for VMs."
|
||||
},
|
||||
{
|
||||
"href": "/docs/storage-share/lxc-mount-points",
|
||||
"label": "LXC Mount Points (Host ↔ CT)",
|
||||
"tail": " — share host directories with a CT instead of attaching a whole disk."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/vm-ct-commands",
|
||||
"label": "VM and CT Management commands",
|
||||
"tail": " — pct config / push / pull reference."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager",
|
||||
"label": "Disk Manager overview",
|
||||
"tail": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Import Disk to VM | ProxMenux Documentation",
|
||||
"description": "Attach a physical disk to an existing Proxmox VM with ProxMenux. Safe disk detection (excludes system, mounted, in-use, ZFS/RAID/LVM), persistent /dev/disk/by-id paths and SATA / SCSI / VirtIO / IDE interfaces.",
|
||||
"ogTitle": "Import Disk to VM | ProxMenux Documentation",
|
||||
"ogDescription": "Attach a physical disk to an existing Proxmox VM. Uses persistent /dev/disk/by-id paths and supports SATA / SCSI / VirtIO / IDE."
|
||||
},
|
||||
"header": {
|
||||
"title": "Import Disk to VM",
|
||||
"description": "Attach a physical disk that already exists on the Proxmox host to an existing virtual machine. ProxMenux detects free disks, lets you pick the target VM, the bus type (SATA / SCSI / VirtIO / IDE) and attaches everything using persistent /dev/disk/by-id paths so the mapping survives reboots and device-order changes.",
|
||||
"section": "Disk Manager · VM"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this does",
|
||||
"body": "This is a raw-disk passthrough: the guest OS sees the drive as a real block device (with its SMART data and native geometry). The disk is attached via its <code>/dev/disk/by-id/…</code> path — not <code>/dev/sdX</code> — so the assignment does not break if disk controllers enumerate devices in a different order on the next boot."
|
||||
},
|
||||
"howRuns": {
|
||||
"heading": "How the script runs",
|
||||
"body": "The flow has two phases with clear separation between \"collecting information and decisions\" and \"actually attaching disks to the VM\". Until the final confirmation, the VM config is untouched.",
|
||||
"summary": "ProxMenux filters out anything it cannot safely pass: the root disk, disks mounted on the host, members of an active ZFS/LVM/RAID pool and disks already referenced by any VM/LXC config. Disks with <em>stale</em> metadata (old ZFS / RAID / LVM signatures that are no longer in use) are shown with a ⚠ label but are not blocked."
|
||||
},
|
||||
"prereqs": {
|
||||
"heading": "Prerequisites",
|
||||
"items": [
|
||||
"At least one VM defined on the host (the script dispatches straight to <code>qm list</code>).",
|
||||
"The <strong>target VM is powered off</strong>. If it is running the script aborts with a message — live disk hot-add is outside the scope of this flow.",
|
||||
"At least one physical disk on the host that is not in use by the host or any other guest."
|
||||
]
|
||||
},
|
||||
"steps": {
|
||||
"heading": "Step-by-step",
|
||||
"stepLabel": "Step",
|
||||
"list": [
|
||||
{
|
||||
"title": "Pick the target VM",
|
||||
"bodyRich": "ProxMenux lists every VM on the host (via <code>qm list</code>). Pick the one that will receive the disk. If the VM is running the script aborts and asks you to shut it down first."
|
||||
},
|
||||
{
|
||||
"title": "Pick the physical disk(s) to attach",
|
||||
"img": "/disk/disk-selection.png",
|
||||
"caption": "Free disks detected on the host (with ⚠ labels for stale metadata)",
|
||||
"body": "The script scans every host disk and shows only the ones that are safe to attach. The checklist lets you select one or several at once. Disks with old ZFS / LVM / RAID signatures still show up, labelled with ⚠ so you know they need a wipe before the guest can format them."
|
||||
},
|
||||
{
|
||||
"title": "Pick the bus interface",
|
||||
"img": "/disk/disk-assigment.png",
|
||||
"caption": "Bus interface selection",
|
||||
"intro": "Pick how the guest should see the disk:",
|
||||
"items": [
|
||||
"<strong>SCSI</strong> — modern default for Linux and Windows with VirtIO-SCSI drivers installed.",
|
||||
"<strong>SATA</strong> — broad compatibility, works out of the box on virtually every guest.",
|
||||
"<strong>VirtIO</strong> — paravirtualised block device, fastest but requires guest drivers.",
|
||||
"<strong>IDE</strong> — for legacy guests that lack any of the above drivers."
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Attach and verify",
|
||||
"bodyRich": "ProxMenux attaches every selected disk with its best <code>/dev/disk/by-id/</code> path, skips slot indexes that are already in use in the VM config (<code>scsi0</code>, <code>sata0</code>, …) and re-reads the config to confirm the assignment. A summary is printed at the end."
|
||||
}
|
||||
]
|
||||
},
|
||||
"manual": {
|
||||
"heading": "Manual equivalent",
|
||||
"body": "The script is a wrapper around <code>qm set</code>. The exact command for a single disk looks like this:",
|
||||
"migrationTitle": "Live migration is not possible",
|
||||
"migrationBody": "A VM with a passthrough disk is <strong>tied to the host that exposes that disk</strong>. Live migration to another Proxmox node will fail because the target node does not see the same <code>/dev/disk/by-id/…</code> path. Use replication or backup/restore instead, or pick virtual disks on shared storage if you need mobility.",
|
||||
"shareTitle": "Do not share a physical disk between VMs",
|
||||
"shareBody": "Attaching the same physical disk to two VMs at the same time will corrupt data on next write. ProxMenux detects this situation and blocks it, but if you bypass the script (direct <code>qm set</code>), make sure only one guest ever mounts the disk."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"noDisksTitle": "\"No disks available for this VM\"",
|
||||
"noDisksIntro": "The script found disks, but every candidate was filtered out. Common reasons:",
|
||||
"noDisksItems": [
|
||||
"Every remaining disk is already referenced in the target VM's config.",
|
||||
"Every remaining disk is mounted on the host or is part of an active ZFS / LVM / RAID.",
|
||||
"The host only has the root disk installed."
|
||||
],
|
||||
"noDisksOutro": "Run <code>lsblk -f</code> on the host to review the state of each disk.",
|
||||
"noVisibleTitle": "VM does not see the disk after boot",
|
||||
"noVisibleBody": "If you picked <strong>SCSI</strong> or <strong>VirtIO</strong>, the guest needs the matching driver. On Linux that is kernel-native; on Windows you need the VirtIO ISO and a driver install (see the <winLink>Create VM: System Windows</winLink> page). Switching to SATA in the VM's hardware tab is a quick workaround to confirm the disk is physically attached."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"href": "/docs/disk-manager/import-disk-image-vm",
|
||||
"label": "Import Disk Image to VM",
|
||||
"tail": " — same flow but for image files (qcow2 / vmdk / raw / img)."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager/import-disk-lxc",
|
||||
"label": "Import Disk to LXC",
|
||||
"tail": " — equivalent flow for LXC containers."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager/add-controller-nvme-vm",
|
||||
"label": "Add Controller or NVMe to VM",
|
||||
"tail": " — when you need full PCIe / NVMe passthrough rather than disk attach."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/storage-commands",
|
||||
"label": "Storage and Disks commands",
|
||||
"tail": " — qm importdisk and related shell reference."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager",
|
||||
"label": "Disk Manager overview",
|
||||
"tail": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,135 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Proxmox Disk Manager — Attach Disks to VMs / LXC, SMART Tests, Wipe | ProxMenux",
|
||||
"description": "Manage physical disks on a Proxmox VE host with ProxMenux: pass disks through to VMs or LXC containers (qm set scsi/sata/virtio, pct mp), import qcow2 / vmdk / vdi disk images, pass through whole HBAs or NVMe controllers, safely wipe disks and run SMART self-tests.",
|
||||
"ogTitle": "Proxmox Disk Manager — Attach Disks to VMs / LXC, SMART Tests, Wipe",
|
||||
"ogDescription": "Attach disks to VMs / LXC, import disk images, PCI passthrough for controllers, safe wipe and SMART tests on Proxmox VE.",
|
||||
"twitterTitle": "Proxmox Disk Manager | ProxMenux",
|
||||
"twitterDescription": "Attach disks to VMs / LXC, import images, PCI passthrough, safe wipe and SMART tests."
|
||||
},
|
||||
"header": {
|
||||
"title": "Disk Manager",
|
||||
"description": "The Disk Manager menu groups the ProxMenux tools for handling physical disks on a Proxmox host: attach disks to VMs and LXC containers, import disk images, pass through a whole controller or NVMe device, wipe disks safely and run SMART health tests.",
|
||||
"section": "Disk Manager"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this menu is for",
|
||||
"body": "Every option here operates on <strong>physical disks already visible to the Proxmox host</strong>. The menu is split in three groups — <strong>VM</strong> (attach disks or import images into a virtual machine), <strong>LXC</strong> (attach disks to a container), and <strong>Utilities</strong> (safe format, SMART health). Safety checks apply everywhere: system disks and disks already in use are hidden or blocked."
|
||||
},
|
||||
"opening": {
|
||||
"heading": "Opening the menu",
|
||||
"body": "From ProxMenux's main menu, select <strong>Disk Manager</strong>. You will see this:",
|
||||
"imageAlt": "Disk Manager menu with VM, LXC and Utilities blocks"
|
||||
},
|
||||
"groups": {
|
||||
"heading": "Three tool groups",
|
||||
"intro": "The Disk Manager menu is organised in three groups — <strong>VM</strong>, <strong>LXC</strong> and <strong>Utilities</strong>. Click a card to jump straight to the tools in that group.",
|
||||
"vmTitle": "VM",
|
||||
"vmBody": "Tools that operate on existing virtual machines. The VM must be powered off; ProxMenux validates this before touching the config.",
|
||||
"vmItems": [
|
||||
"Import Disk to VM",
|
||||
"Import Disk Image to VM",
|
||||
"Add Controller or NVMe to VM"
|
||||
],
|
||||
"lxcTitle": "LXC",
|
||||
"lxcBody": "Tools that operate on existing containers. Direct device passthrough needs a privileged container; the script offers to convert it if necessary.",
|
||||
"lxcItems": [
|
||||
"Import Disk to LXC"
|
||||
],
|
||||
"utilitiesTitle": "Utilities",
|
||||
"utilitiesBody": "Host-side tools that operate on the disks themselves, independently of any VM or container.",
|
||||
"utilitiesItems": [
|
||||
"Format / Wipe Physical Disk",
|
||||
"SMART Disk Health & Test"
|
||||
]
|
||||
},
|
||||
"vm": {
|
||||
"heading": "VM",
|
||||
"intro": "Tools that operate on existing virtual machines. The VM must be powered off; ProxMenux validates this before touching the config.",
|
||||
"options": [
|
||||
{
|
||||
"icon": "HardDrive",
|
||||
"href": "/docs/disk-manager/import-disk-vm",
|
||||
"title": "Import Disk to VM",
|
||||
"description": "Attach an unassigned physical disk to an existing VM. Supports SATA / SCSI / VirtIO / IDE, uses persistent /dev/disk/by-id paths."
|
||||
},
|
||||
{
|
||||
"icon": "FileDown",
|
||||
"href": "/docs/disk-manager/import-disk-image-vm",
|
||||
"title": "Import Disk Image to VM",
|
||||
"description": "Import disk image files (.img / .qcow2 / .vmdk / .raw) into an existing VM. Two-phase flow, qm importdisk under the hood."
|
||||
},
|
||||
{
|
||||
"icon": "Cpu",
|
||||
"href": "/docs/disk-manager/add-controller-nvme-vm",
|
||||
"title": "Add Controller or NVMe to VM",
|
||||
"description": "PCI passthrough of a whole SATA / SAS HBA or NVMe device to a VM. Handles IOMMU enablement and conflict detection."
|
||||
}
|
||||
]
|
||||
},
|
||||
"lxc": {
|
||||
"heading": "LXC",
|
||||
"intro": "Tools that operate on existing LXC containers. Direct device passthrough requires a privileged container; the script offers to convert the container if needed.",
|
||||
"options": [
|
||||
{
|
||||
"icon": "Boxes",
|
||||
"href": "/docs/disk-manager/import-disk-lxc",
|
||||
"title": "Import Disk to LXC",
|
||||
"description": "Attach an unassigned physical disk to an existing LXC container as a mount point. Handles filesystem detection / format and privileged conversion."
|
||||
}
|
||||
]
|
||||
},
|
||||
"utilities": {
|
||||
"heading": "Utilities",
|
||||
"intro": "Host-side tools that operate on the disks themselves, independently of any VM or container.",
|
||||
"options": [
|
||||
{
|
||||
"icon": "Eraser",
|
||||
"href": "/docs/disk-manager/format-disk",
|
||||
"title": "Format / Wipe Physical Disk (Safe)",
|
||||
"description": "Secure disk wipe with strict safety controls: only fully free disks are shown and a double confirmation is always required."
|
||||
},
|
||||
{
|
||||
"icon": "Activity",
|
||||
"href": "/docs/disk-manager/smart-disk-test",
|
||||
"title": "SMART Disk Health & Test",
|
||||
"description": "Run SMART health checks and short / long self-tests on SATA, SAS and NVMe drives. Exports JSON for the Monitor."
|
||||
}
|
||||
]
|
||||
},
|
||||
"safety": {
|
||||
"title": "Safety rules shared by every option",
|
||||
"intro": "ProxMenux filters out anything that could harm the host:",
|
||||
"items": [
|
||||
"The <strong>system disk</strong> (root pool, swap, active ZFS / LVM / RAID members) is always hidden.",
|
||||
"Disks <strong>mounted</strong> anywhere on the host are hidden or blocked at execution.",
|
||||
"Disks <strong>referenced by a running VM or LXC</strong> cannot be reassigned or wiped.",
|
||||
"Operations that can change the host state (IOMMU enable, wipe) require explicit confirmation."
|
||||
]
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"href": "/docs/storage-share",
|
||||
"label": "Storage & Share Manager",
|
||||
"tail": " — register storage in Proxmox itself (NFS / Samba / iSCSI / local) and share folders between host and CTs."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/storage-commands",
|
||||
"label": "Storage and Disks commands",
|
||||
"tail": " — block devices, LVM, pvesm, SMART reference."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/zfs-commands",
|
||||
"label": "ZFS Management commands",
|
||||
"tail": " — for ZFS pools and datasets."
|
||||
},
|
||||
{
|
||||
"href": "/docs/hardware/gpu-vm-passthrough",
|
||||
"label": "Add GPU to VM (Passthrough)",
|
||||
"tail": " — same IOMMU / VFIO concepts applied to GPUs."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,146 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "SMART Disk Health & Test | ProxMenux Documentation",
|
||||
"description": "Run SMART health checks and disk tests on Proxmox VE with ProxMenux. Supports SATA / SAS (smartmontools) and NVMe (nvme-cli). Short and long self-tests, JSON export for ProxMenux Monitor integration.",
|
||||
"ogTitle": "SMART Disk Health & Test | ProxMenux Documentation",
|
||||
"ogDescription": "SMART health checks and self-tests for SATA / SAS and NVMe drives on Proxmox. JSON export for the Monitor."
|
||||
},
|
||||
"header": {
|
||||
"title": "SMART Disk Health & Test",
|
||||
"description": "Read SMART data and trigger self-tests on the physical disks attached to the Proxmox host. ProxMenux auto-installs smartmontools for SATA / SAS and nvme-cli for NVMe, runs the action inside the drive firmware (long tests survive terminal close) and exports JSON results for the ProxMenux Monitor.",
|
||||
"section": "Disk Manager · Utilities"
|
||||
},
|
||||
"intro": {
|
||||
"title": "What this is for",
|
||||
"body": "SMART (Self-Monitoring, Analysis and Reporting Technology) lets the drive itself report its health and run self-tests. This tool exposes that data without you needing to remember the right <code>smartctl</code> / <code>nvme</code> invocation, and persists the output as JSON so the Monitor can graph trends over time."
|
||||
},
|
||||
"howRuns": {
|
||||
"heading": "How the script runs",
|
||||
"body": "All actions here are non-destructive — SMART reads the drive firmware counters, and self-tests are queued inside the drive itself. No phase separation is needed. The flow is: dependency check → disk selection → action selection → tool invocation (smartctl or nvme-cli depending on the disk bus) → printed output plus JSON export for the Monitor."
|
||||
},
|
||||
"deps": {
|
||||
"heading": "Dependencies",
|
||||
"body": "The tool auto-installs what it needs on first run. SATA / SAS drives rely on <code>smartmontools</code>; NVMe drives rely on <code>nvme-cli</code>. Both:"
|
||||
},
|
||||
"actions": {
|
||||
"heading": "Available actions",
|
||||
"headerAction": "Action",
|
||||
"headerWhat": "What it reads / runs",
|
||||
"headerDur": "Duration",
|
||||
"rows": [
|
||||
{
|
||||
"action": "Quick health status",
|
||||
"whatRich": "Overall PASSED/FAILED + key attributes.<br /><code>smartctl -H</code> + <code>-A</code> (SATA/SAS) or <code>nvme smart-log</code> (NVMe).",
|
||||
"dur": "Instant"
|
||||
},
|
||||
{
|
||||
"action": "Full report",
|
||||
"whatRich": "Complete SMART data, scrollable. <code>smartctl -x</code> for SATA/SAS or <code>nvme smart-log</code> + <code>id-ctrl</code> for NVMe.",
|
||||
"dur": "Instant"
|
||||
},
|
||||
{
|
||||
"action": "Short test",
|
||||
"what": "Basic surface and electrical check, queued inside the drive firmware.",
|
||||
"dur": "~2 minutes"
|
||||
},
|
||||
{
|
||||
"action": "Long test",
|
||||
"what": "Full scan of the entire surface. Runs on the drive hardware — persists even if you close the terminal.",
|
||||
"dur": "Hours (disk size dependent)"
|
||||
},
|
||||
{
|
||||
"action": "Check test progress",
|
||||
"what": "Status of the active or most recent self-test.",
|
||||
"dur": "Instant"
|
||||
}
|
||||
],
|
||||
"tipTitle": "Long tests survive terminal close",
|
||||
"tipBody": "A long test is queued <em>inside the drive</em> — it does not depend on the ProxMenux process staying alive. You can close the terminal, reboot the Proxmox host (the test picks up where it left off on some drives) or just come back later and use <strong>Check test progress</strong> to see the result."
|
||||
},
|
||||
"json": {
|
||||
"heading": "JSON export for the Monitor",
|
||||
"intro": "Every run writes a timestamped JSON file to <code>/usr/local/share/proxmenux/smart/<disk>/</code>. The structure is:",
|
||||
"outro": "The ProxMenux Monitor picks these up to render health trends per disk; old files are rotated out automatically once the retention limit is reached."
|
||||
},
|
||||
"steps": {
|
||||
"heading": "Step-by-step",
|
||||
"stepLabel": "Step",
|
||||
"list": [
|
||||
{
|
||||
"title": "Pick a disk",
|
||||
"body": "ProxMenux lists every physical disk on the host with its model and size. Unlike the Format tool, this list is not filtered by safety — reading SMART is a non-destructive operation.",
|
||||
"img": "/disk/smart/disk-selection.png",
|
||||
"alt": "SMART disk selection menu",
|
||||
"caption": "SMART disk selection menu"
|
||||
},
|
||||
{
|
||||
"title": "Pick an action",
|
||||
"body": "Choose between Quick health status, Full report, Short test, Long test or Check progress. The menu stays open after each action so you can chain several queries against the same disk.",
|
||||
"img": "/disk/smart/action-menu.png",
|
||||
"alt": "SMART action menu",
|
||||
"caption": "SMART action menu (5 actions + cancel)"
|
||||
},
|
||||
{
|
||||
"title": "(Long test only) Confirm background execution",
|
||||
"body": "ProxMenux warns that the test will keep running after the terminal closes and shows where the JSON result will land. Accept to queue it.",
|
||||
"img": "/disk/smart/long-test-warning.png",
|
||||
"alt": "Long test confirmation dialog",
|
||||
"caption": "Long test confirmation — runs in background, result saved to JSON"
|
||||
},
|
||||
{
|
||||
"title": "Review results",
|
||||
"bodyRich": "Status and report are printed to the terminal and written to JSON. For long tests, return later and run <strong>Check test progress</strong> on the same disk to see the outcome.",
|
||||
"img": "/disk/smart/quick-status.png",
|
||||
"alt": "Quick health status output",
|
||||
"caption": "Quick health status output (SATA — smartctl -H + -A)"
|
||||
}
|
||||
]
|
||||
},
|
||||
"manual": {
|
||||
"heading": "Manual equivalents",
|
||||
"nvmeWarnTitle": "NVMe self-tests are drive-firmware dependent",
|
||||
"nvmeWarnBody": "Not every NVMe drive supports the short/long self-test command. If a drive refuses the test, the SMART log and the ID controller data (<code>nvme smart-log</code> + <code>id-ctrl</code>) are still the most reliable health signal."
|
||||
},
|
||||
"troubleshoot": {
|
||||
"heading": "Troubleshooting",
|
||||
"noSmartTitle": "\"Could not read SMART data from /dev/sdX\"",
|
||||
"noSmartBody": "The disk is probably behind a RAID / SAS controller that does not pass SMART through. With megaraid-based cards, try <code>smartctl -d megaraid,N /dev/sdX</code>. For HBAs in IT mode the direct invocation works.",
|
||||
"longTitle": "Long test never completes",
|
||||
"longBody": "The test is queued on the drive firmware and pauses if the disk is under heavy load. Running it overnight on an idle system usually works. You can also check <code>smartctl -c</code> to see percentage remaining; if it is stuck at a fixed LBA, the disk is failing at that sector."
|
||||
},
|
||||
"related": {
|
||||
"heading": "Related",
|
||||
"items": [
|
||||
{
|
||||
"href": "/docs/disk-manager/format-disk",
|
||||
"label": "Format / Wipe Physical Disk",
|
||||
"tail": " — reuse a disk after confirming it's healthy."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/storage-commands",
|
||||
"label": "Storage and Disks commands → SMART Disk Health",
|
||||
"tail": " — copy-pasteable smartctl / nvme reference."
|
||||
},
|
||||
{
|
||||
"href": "/docs/help-info/zfs-commands",
|
||||
"label": "ZFS Management commands",
|
||||
"tail": " — zpool scrub for the storage-layer equivalent of SMART tests."
|
||||
},
|
||||
{
|
||||
"href": "/docs/monitor/dashboard/storage",
|
||||
"label": "ProxMenux Monitor — Storage tab",
|
||||
"tail": " — disk drill-in that consumes the JSON exported here (full SMART table, history, PDF report)."
|
||||
},
|
||||
{
|
||||
"href": "/docs/monitor/dashboard/hardware",
|
||||
"label": "ProxMenux Monitor — Hardware tab",
|
||||
"tail": " — Storage Summary with model, capacity and negotiated link speed (current vs maximum on NVMe)."
|
||||
},
|
||||
{
|
||||
"href": "/docs/disk-manager",
|
||||
"label": "Disk Manager overview",
|
||||
"tail": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user