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
+77
View File
@@ -0,0 +1,77 @@
"""Interactive Windows mouse diagnostic using only the fixture's Python.
Run on the desktop, not Guest Control's Session 0. Ten accepted OK clicks
finish the test; Cancel/Escape exits early. No settings or keystrokes are read.
The adjacent .log contains changed mouse coordinates/buttons and dialog results.
"""
import ctypes
from ctypes import wintypes
import json
from pathlib import Path
import sys
import threading
import time
if sys.platform != 'win32':
raise SystemExit('Run this probe on the interactive Windows desktop.')
user32 = ctypes.WinDLL('user32', use_last_error=True)
user32.GetCursorPos.argtypes = [ctypes.POINTER(wintypes.POINT)]
user32.GetCursorPos.restype = wintypes.BOOL
user32.GetAsyncKeyState.argtypes = [ctypes.c_int]
user32.GetAsyncKeyState.restype = ctypes.c_short
user32.MessageBoxW.argtypes = [wintypes.HWND, wintypes.LPCWSTR,
wintypes.LPCWSTR, wintypes.UINT]
user32.MessageBoxW.restype = ctypes.c_int
user32.SetProcessDPIAware.argtypes = []
user32.SetProcessDPIAware.restype = wintypes.BOOL
user32.SetProcessDPIAware()
log_path = Path(__file__).with_suffix('.log')
stop = threading.Event()
lock = threading.Lock()
log = log_path.open('w', encoding='utf-8', buffering=1)
def record(kind, **data):
with lock:
entry = json.dumps(dict(time=time.time(), kind=kind, **data))
log.write(entry + '\n')
print(entry, flush=True)
def monitor():
previous = None
deadline = time.monotonic() + 600
point = wintypes.POINT()
while not stop.is_set() and time.monotonic() < deadline:
if user32.GetCursorPos(ctypes.byref(point)):
state = (point.x, point.y,
bool(user32.GetAsyncKeyState(1) & 0x8000),
bool(user32.GetAsyncKeyState(2) & 0x8000))
if state != previous:
record('windows_mouse', x=state[0], y=state[1],
left=state[2], right=state[3])
previous = state
stop.wait(0.01)
record('monitor_finished')
record('started', log=str(log_path))
worker = threading.Thread(target=monitor, daemon=True)
worker.start()
try:
for accepted in range(10):
result = user32.MessageBoxW(
None,
f'Accepted OK clicks: {accepted}\n\n'
'Use the physical mouse to click OK.\n'
'Each accepted click opens the next numbered test.\n'
'The count must advance on each ordinary click.\n\n'
'Cancel or Escape exits. No settings are changed.',
'RVBox Mouse Input Probe', 1)
record('dialog_result', accepted_before=accepted, result=result)
if result != 1:
break
finally:
stop.set()
worker.join(timeout=2)
record('finished')
log.close()