lywsvip/pikvm
1
0
Fork 0
mirror of https://github.com/pikvm/pikvm.git synced 2026-09-03 07:17:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

#1569: document disabling MSD at startup for Dell/HP UEFIs (#1673)

Browse Source 
Some Dell (OptiPlex/Pro Micro 7020) and HP (EliteDesk 800 G4) UEFIs
can't handle Mass Storage + HID on a single USB port, causing a black
screen, boot loop, or lost BIOS settings.

Document the recommended workaround `otg/devices/msd/start: false`,
which keeps MSD configured but unstarted at boot (re-enable on demand
via kvmd-otgconf), alongside the existing full-disable method. Note the
affected hardware and warn against confusing the `msd` and `drives`
config sections.

Co-authored-by: Mohammed Awad <mawad10101@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Mohammed Awad
2026-06-22 12:17:52 -04:00
committed by GitHub
parent cc09b7ee20
commit 3d5b8a3441
1 changed files with 63 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/msd.md
View File

@@ -385,6 +385,68 @@ The full list of options can be found by running `kvmd-otgmsd --help`.
In rare cases, it may be necessary to disable Mass Storage emulation if the BIOS/UEFI
does not recognize it correctly and even refuses to work with USB keyboard and mouse.
!!! note "Known affected hardware"
Some Dell (OptiPlex / Pro Micro 7020 and similar) and HP (EliteDesk 800 G4 and similar)
machines use a UEFI framework that can't handle the combination of Mass Storage and HID
(keyboard/mouse) on a single USB port. Typical symptoms are a black screen, a boot loop,
or lost date/BIOS settings after exiting the BIOS or powering on the host while the PiKVM
USB cable is connected. Disabling Mass Storage as shown below resolves this.
There are two ways to do this, depending on whether you still want to be able to use
Mass Storage on demand.
### Disable at startup, keep available on demand (recommended)
This keeps the Mass Storage device configured but **does not start it** when PiKVM boots,
so a problematic BIOS/UEFI is not confused. You can still enable it dynamically later
(for example, to boot an installer image) using [dynamic USB configuration](usb.md).
??? example "Step by step: Disabling Mass Storage at startup"
1. Switch the filesystem to read-write mode:
```console
[root@pikvm ~]# rw
```
2. Edit `/etc/kvmd/override.yaml` and add:
```yaml
otg:
devices:
msd:
start: false
```
!!! warning
Use the `msd` section as shown above. Do **not** confuse it with the `drives`
section, which controls the [additional drives](#multiple-drives) and does not
affect the main Mass Storage device.
3. Perform reboot:
```console
[root@pikvm ~]# reboot
```
When you need Mass Storage, enable it on the fly:
```console
[root@pikvm ~]# kvmd-otgconf -e mass_storage.usb0
```
And disable it again before exiting the BIOS or rebooting the target host:
```console
[root@pikvm ~]# kvmd-otgconf -d mass_storage.usb0
```
### Disable completely
This fully disables the Mass Storage subsystem. The `Drive` menu in the Web UI
will be unavailable, and Mass Storage can't be re-enabled dynamically without
reverting this change.
??? example "Step by step: Permanent disabling Mass Storage"
1. Switch the filesystem to read-write mode:
@@ -393,13 +455,12 @@ does not recognize it correctly and even refuses to work with USB keyboard and m
[root@pikvm ~]# rw
```
2. Edit `/etc/kvmd/override.yaml` and add the extra drive config section:
2. Edit `/etc/kvmd/override.yaml` and add:
```yaml
kvmd:
msd:
type: disabled
```
3. Perform reboot:
@@ -408,10 +469,6 @@ does not recognize it correctly and even refuses to work with USB keyboard and m
[root@pikvm ~]# reboot
```
!!! tip
As an alternative method may be to use the [dynamic USB configuration](usb.md),
which allows you to temporarily disable any of the emulated devices, including Mass Storage Drive.
-----
## Big DVD images on old PiKVM