Fix fixture mouse integration and capture clean USB-tablet baseline

This commit is contained in:
cabbage committed 2026-10-08 09:36:13 +00:00
1 parent 6ccaaae3c7
commit 90d6b05f4d
10 files changed
+424 -43

No files matched your search

+102 -8
View File
@@ -326,16 +326,33 @@ owns the fixture's single VRDE connection slot.
On this Windows 10 / VirtualBox 7.2.16 fixture, the PS/2 pointing device accepted
pointer movement but did not activate buttons through Guacamole. A normal
Windows restart did not repair that mouse path. Switching to a USB tablet with
an OHCI controller did: the same real Guacamole HTTP-tunnel keyboard shortcut
opened Run, and the mouse Cancel-button click closed it. This identifies a
failure in the PS/2 input path for this setup, not its exact underlying driver
bug. Guest Control, the updating clock, and `Get-PnpDevice` reporting `OK` had
all remained healthy during the failure.
an OHCI controller initially passed a single-click check, but the failure
recurred. Do not treat that check as proof of a durable fix. The interactive
Windows probe then recorded 106 changing pointer samples, no left/right
button-down samples, and no accepted OK clicks, despite Guacamole receiving
browser mouse-down/up events. Guest Control, the updating clock, and
`Get-PnpDevice` reporting `OK` all remained healthy during the failure.
The guest mouse class had `UpperFilters = VBoxMouse, mouclass`. A USB tablet
alone does not necessarily bypass mouse integration: VirtualBox's
[mouse-routing implementation](https://github.com/VirtualBox/virtualbox/blob/master/src/VBox/Main/src-client/MouseImpl.cpp)
prefers the Guest Additions absolute-pointer path when advertised and can send
buttons separately through the emulated relative mouse. After an explicitly
approved, backed-up removal of **only** `VBoxMouse` from that class filter and
a normal Windows restart, `VBoxMouse` was stopped, the standard drivers remained
running, and input counters moved to the USB-tablet queue. Ten controlled clicks
through the **existing** Guacamole/guacd connection produced ten button-down/up
transitions and ten accepted OK results in Windows. This supports a workaround
for this fixture's mouse-integration path; it does not establish the precise
VirtualBox driver defect or prove every browser/hardware combination.
`scripts/windows/test-host prepare` now configures the USB tablet and enables
VRDE input **after each snapshot restore, before boot**. The retained baseline
snapshots are unchanged. A manual restore followed by `VBoxManage startvm`
bypasses this normalization and may restore the old PS/2-only configuration.
VRDE input **after each snapshot restore, before boot**. The canonical baseline
also records the detached `VBoxMouse` filter; `prepare` verifies it remains
detached, with healthy standard drivers and USB input, before reporting success.
The older snapshots are retained unchanged for rollback. A manual restore of
an older snapshot followed by `VBoxManage startvm` bypasses this normalization
and can restore both the PS/2-only configuration and the problematic filter.
Oracle documents the USB tablet's absolute-coordinate input in its
[pointing-device settings](https://docs.oracle.com/en/virtualization/virtualbox/7.2/user/working-with-vms.html).
@@ -358,6 +375,83 @@ or `prepare` for state-preserving recovery: both restore a baseline and discard
current disk changes. `rdp-access repair` alone never changes the virtual input
hardware or restarts Windows.
#### Opt-in mouse-filter workaround and rollback
The canonical baseline already records this workaround, so normal preparation
does not need an extra driver change or restart. `prepare` fails visibly if the
filter or unhealthy devices return; it does not silently repair a live desktop.
When diagnosing an older baseline or an explicit Guest Additions reinstall,
with the fixture running and the current lease owner known:
```sh
scripts/windows/test-host mouse-status --run-id interactive-rdp
scripts/windows/test-host mouse-bypass --run-id interactive-rdp
scripts/windows/test-host mouse-verify --run-id interactive-rdp
```
The second action requires the fixture's full-token administrator and a healthy
VirtualBox USB-tablet device. It backs up the original ordered filter list to
`C:\ProgramData\RVBoxFixture\mouse-filter-backup.json`, preserving that first
backup on repeated runs, and copies it to the Helium run directory. It removes
only `VBoxMouse`; `mouclass`, other filters, LowerFilters, keyboard devices,
driver files/services, and Guest Additions are retained. It refuses unexpected
filter changes since the backup. The class property is
[REG_MULTI_SZ](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/devpkey-deviceclass-upperfilters),
not a single string.
Only the present mouse devices are reloaded with
[`pnputil /restart-device`](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/pnputil-command-syntax),
which Windows 10 22H2 supports. `pnputil_exit=3010` / `reboot_required=True`
means a normal Windows restart is still required. On the current fixture the
USB mouse reloaded immediately, but the PS/2 device required that restart.
The helper **never** restarts Windows, force-powers off the VM, or restores a
snapshot. Save desktop work before restarting Windows normally, then repeat
`mouse-verify`: it succeeds only when the filters omit `VBoxMouse`,
`VBoxMouse` is stopped, and `mouclass`/`mouhid` and both devices are healthy.
To undo the workaround, keeping the same disk and original backup:
```sh
scripts/windows/test-host mouse-restore --run-id interactive-rdp
```
Restart Windows normally if requested, and inspect `mouse-status` again. Restore
uses the original filter order and also refuses unrelated intervening changes.
Neither bypass nor restore is retried automatically after an interrupted remote
execution: inspect the resulting state first. Restoring the canonical baseline
also restores the known-good detached filter and its rollback record; restoring
an older baseline can discard both. Do not disable/delete `VBoxMouse.sys` while
the class still references it, and do not remove `mouclass`: either can break
normal mouse input. This filter supplies VirtualBox's
[mouse-pointer integration](https://docs.oracle.com/en/virtualization/virtualbox/7.2/user/guestadditions.html),
not an RVBox feature or security restriction. Standard USB-tablet input does not
need it. Guest Control and video support use other Guest Additions components
and remain installed. Avoid untracked Guest Additions updates/reinstalls; they
can register the filter again. After an intentional update, verify/reapply the
workaround, restart normally if needed, and re-run real click checks before
capturing another clean baseline. No workaround guarantees immunity from all
future browser, transport, or unrelated driver failures.
For a Windows-side click check, copy `test/rdp-access/mouse-probe.py` to the
desktop and run it with `C:\Python313\python.exe` **in the interactive desktop
session**. Guest Control runs in Session 0 and cannot measure the desktop's
button state. Ten OK clicks should advance the dialog count and finish the
probe; the adjacent `.log` must contain `left: true` samples and ten
`dialog_result` entries with `result: 1`. Logs include only mouse coordinates,
button state, and diagnostic results, never typed keys. Mouse sampling lasts
ten minutes; `monitor_finished` marks the limit. Relaunch for a fresh capture
(the previous probe log is overwritten, so collect it first).
If Windows+R is intercepted by the browser/host, a verified operator can use
`VBoxManage controlvm <verified-VM> keyboardputscancode e0 5b 13 93 e0 db` on
Helium to open **remote** Run. Inspect a screenshot to verify that Run is open
before typing the exact probe command with `keyboardputstring`; use Ctrl+A to
replace old Run history. Do not blindly send Enter or type into the user's
existing command prompt. Do not inject the command via guessed Unicode
Guacamole keysyms: this fixture did not accept that text reliably. A read-only
observer may join the existing guacd connection for diagnostics, but an
independent RDP connection would compete for its single slot.
The two scripts have a deliberate ownership boundary. `rdp-access` manages only
the temporary browser gateway, Guacamole/guacd containers, IPv6 forward, and
Helium SSH tunnel. `scripts/windows/test-host` manages the leased VM and its