fix: don't expose eMMC as USB mass storage when no image is mounted

[MagnaCapax]

Summary

When /boot/usb.disk0 exists but is empty (the default out-of-box state), the NanoKVM exposes its raw eMMC partition (/dev/mmcblk0p3) as a USB mass storage device. This causes Legacy BIOS systems to hang during boot — the BIOS attempts to boot from the device, reads invalid data (no MBR signature), and enters a HLT loop. The system becomes completely unresponsive; no keyboard input is accepted, and the only recovery is a physical power cycle.

This affects any NanoKVM connected to a Legacy BIOS system in its default configuration — a zero-config out-of-box bug.

The same behavior occurs when an ISO image is unmounted via the web UI: image.go re-mounts /dev/mmcblk0p3 as the "no image" fallback, re-exposing the eMMC.

Changes

kvmapp/system/init.d/S03usbdev

• When /boot/usb.disk0 is empty, do not set a backing file for lun.0/file
• The mass_storage device (with removable=1) reports "no media inserted"
• BIOS handles this safely by skipping to the next boot device
• When usb.disk0 contains a path, that path is used as before (no behavior change)

server/service/storage/image.go

• Remove imageNone constant (/dev/mmcblk0p3)
• When unmounting an image (empty req.File), the device stays unmounted instead of falling back to the eMMC partition
• GetMountedImage retains backward compatibility by still treating mmcblk0p3 as "no image" for devices that haven't rebooted after the update

server/service/vm/virtual-device.go (no changes needed)

• With the S03usbdev fix, toggling "Virtual Disk" ON correctly creates the mass_storage gadget with no media. Users then mount ISOs through the existing UI.

Root Cause

Three code paths wrote /dev/mmcblk0p3 to the USB gadget's backing file:

1. S03usbdev (line 116): echo /dev/mmcblk0p3 > functions/mass_storage.disk0/lun.0/file — when the gate file is empty
2. image.go (line 114): image = imageNone — when unmounting an ISO
3. virtual-device.go (line 35): touch /boot/usb.disk0 — creates the empty gate file that triggers (1)

The eMMC partition contains a Linux ext4/exfat filesystem with no MBR. When Legacy BIOS reads sector 0 and finds no 0x55AA boot signature, some implementations (notably ASRock) enter a HLT loop instead of trying the next boot device.

Testing

Workaround tested in production (2026-01-30) on ASRock DeskMini A300 (Legacy BIOS P3.70, Ryzen 5 3400G) with NanoKVM (Image v1.4.0 / App 2.3.4):

• Before fix: System hangs at blinking cursor after PXE ROM exit. CPU in HLT loop. No keyboard response. Only recoverable via physical power cycle.
• Workaround applied: Deleted /boot/usb.disk0 on NanoKVM → only HID + RNDIS functions present → BIOS proceeds normally through boot order → system boots successfully.

The code changes in this PR implement the same logic as the workaround (empty gate file = no backing file) but at the correct code level, preserving the virtual USB disk feature for users who mount actual ISO images.

Related Issues

Fixes #633
Refs #385, #438, #187

[marcodelpin]

Tested this fix in vivo on NanoKVM Mini cv1800b firmware 2.4.1 against a Teclast Tbook 2018 laptop (Aptio AMI BIOS, UEFI mode).

Symptom replication confirmed: when no image is mounted, the upstream behavior exposes the device's /dev/mmcblk0p3 (~162 MB raw ext4 data partition) as the USB mass-storage backing. The Teclast firmware's mass-storage scanner reads it, finds no valid MBR signature, and stalls boot (similar to the ASRock HLT loop you described — the failure mode is generic to budget Aptio firmwares, not ASRock-specific).

Patched binary deployment (via the image.go change in this PR, applied to a local fork build):

• Pre-unmount: /sys/kernel/config/usb_gadget/g0/functions/mass_storage.disk0/lun.0/file = /dev/mmcblk0p3
• Post-unmount via Web UI: same path = `` (empty)
• Kernel f_mass_storage driver now reports "no media inserted" instead of exposing eMMC raw

The Teclast no longer stalls or sees a phantom storage device when no ISO is mounted. The fix is correct and necessary — this is a structural bug, not a workaround.

I'd suggest merging this PR, both the image.go change and the S03usbdev init-script change are independent improvements (image.go fixes the UI-toggled unmount, S03usbdev fixes the zero-config out-of-box state).

Build details for reproducibility:

• Cross-compiled with Sophgo Xuantie musl GCC 10.2.0 (riscv64-unknown-linux-musl-gcc) + Go 1.25.0
• Same libkvm.so blob as upstream (md5 1372cde2a44468dcaf62da83494257db) — proves the patch is purely Go-server-side, no ABI break
• Binary deployed via SCP swap on a running NanoKVM Mini, original backed up first