Files
rvbox/test/rdp-access/README.md
T

588 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Interactive Windows VM access
This directory is an explicitly temporary, manual-recovery path to the Helium
Windows fixture desktop. It is for the small class of actions that require an
interactive UAC consent dialog. Normal setup, testing, collection, and reset
remain `scripts/windows/test-host` plus VirtualBox Guest Control.
The helper builds this private path:
```text
browser -- HTTPS/self-signed --> nginx + Guacamole containers
(IPv4 and, in public mode, a tracked IPv6 forward)
|
private Docker gateway
|
controller SSH watchdog/tunnel --> Helium 127.0.0.1:3389 --> VirtualBox VRDE --> VM console
```
Only the HTTPS listener can be made public, and that requires an explicit
`--bind 0.0.0.0`. The VirtualBox VRDE endpoint stays on Helium loopback and the
SSH tunnel binds only to the Docker network gateway; neither is publicly
exposed. Guacamole requires the fixture login before it forwards the entered
password to the VM. Clipboard, drives, printing, audio, microphone input, GFX,
and display-resize extensions are disabled because the fixture's VirtualBox
RDP4 server does not handle them reliably.
The optional **LAN-only** RDP relay below is a separate, explicitly requested
path on Helium. It leaves the VM's VRDE socket on loopback, binds only a private
host IPv4 address, and restricts peers to the selected private LAN subnet.
It does not expose the guest NAT address or enable Windows Remote Desktop.
## Network and graphics quality
Use `--graphics minimal|low|normal|high` on `up`, or set `RDP_ACCESS_GRAPHICS`:
| Mode | Requested display | Color | Intended use |
| --- | --- | --- | --- |
| `minimal` | 800×600, 96 DPI | 8-bit / 256 colors | Lowest pixel/color budget; substantial color loss |
| `low` | 1024×768, 96 DPI | 16-bit | Slow/metered networks, terminal work |
| `normal` | Browser dimensions/DPI | 24-bit | Default, same behavior as the original helper |
| `high` | 1920×1080, 96 DPI | 24-bit | Fast connections and larger desktops |
```sh
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics minimal
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics low
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics normal
```
The choice is saved per gateway profile and reused when omitted. `status`
prints the saved `graphics` mode. A change rewrites the connection mapping
while retaining the gateway and tunnels; **log out of Guacamole and sign in
again** to apply it. Disconnecting/reconnecting the desktop or refreshing the
page alone is insufficient: file-based authentication keeps a copy of the
connection settings in each authenticated user's context. Existing logins
continue with their original display settings even when they create another
desktop connection. This follows the [Guacamole 1.6 authentication implementation](https://github.com/apache/guacamole-client/blob/1.6.0/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/simple/SimpleAuthenticationProvider.java).
To clear cached logins and workers without rebooting the VM or replacing the
gateway/tunnels, run `test/rdp-access/rdp-access repair`, then sign in again.
If an old browser connection holds the single VRDE slot, close it or use the
documented `repair` action before reconnecting.
All modes keep wallpaper, themes, font smoothing, menu animation, full-window
drag, audio/device redirection, and GFX disabled. Lossy compression remains
available to Guacamole's normal heuristics. Display dimensions/color depth are
requests to the RDP server; the negotiated framebuffer can differ if the
server restricts them. A smaller display reduces pixel traffic; it cannot
eliminate network latency. See the [Guacamole 1.6 display settings](https://guacamole.apache.org/doc/1.6.0/gug/configuring-guacamole.html#display-settings).
There is no RDP black-and-white/grayscale parameter: `minimal` requests a
256-color palette. Static terminal work and smaller windows generally cost
less than scrolling images or video. The RDP backend does not provide VNC's
`quality-level`/`compress-level` knobs; those must not be added to this RDP
mapping as if they controlled its encoding.
## Direct RDP on Helium's LAN
For an already-running fixture, one command detects the host's primary private
IPv4 address/subnet and starts a small Docker Compose TCP relay **on Helium**:
```sh
test/rdp-access/rdp-access lan-up
test/rdp-access/rdp-access lan-status
```
The current endpoint is **`192.168.50.162:3389`**, restricted to
`192.168.50.0/24` (the helper may print its equivalent host-prefix notation,
`192.168.50.162/24`). Use `rvboxtest` and the same test-only fixture password
as Guacamole, obtained from the host-local password file in
[`docs/testing-vm.md`](../../docs/testing-vm.md). Authentication is passed
through to the existing `VBoxAuthSimple` endpoint; the relay stores no password.
**Disconnect the Guacamole desktop before connecting an RDP app.** Both routes
use the same single VirtualBox console slot. Changing the access route does
not log off Windows or create another WTS user session. Leave multi-connection
and connection reuse disabled; do not "fix" a rejected second connection by
changing that fixture contract. You can keep the web gateway running for later
use, or stop it with `rdp-access down` while the LAN relay remains available.
This is the working **VirtualBox VRDE** endpoint, not Windows `TermService`.
Native Windows RDP remains disabled, and its old NAT port `3390` is not this
LAN endpoint. The VRDE backend currently uses legacy `security=rdp`; a client
that requires NLA/TLS or newer RDP extensions may not be compatible. This
relay changes reachability, not VirtualBox's protocol compatibility. Do not
forward this debug endpoint through a WAN router or expose it publicly.
To start Guacamole and the independent LAN relay together:
```sh
test/rdp-access/rdp-access up \
--bind 0.0.0.0 --public-host x1.xcel.me --graphics minimal --lan
```
Stop, remove, or recreate only the LAN route:
```sh
test/rdp-access/rdp-access lan-down # retain small generated config
test/rdp-access/rdp-access lan-clean # remove that profile's config
test/rdp-access/rdp-access lan-clean --images # also try removing its unused image
test/rdp-access/rdp-access lan-up # recover/reproduce after cleanup
```
These commands do not stop/reset the VM, change Windows/firewall settings,
stop Guacamole, or affect another LAN profile. Conversely, web `down`/`clean`
do not disable LAN access: use `lan-down`/`lan-clean` explicitly. Before the
usual final VM reset, close both routes if both were enabled. Cleanup checks
profile/VM ownership labels, stops only that Compose project, deletes only
its known generated files, and never force-removes a shared image or runs a
global Docker prune. Unexpected files are retained for inspection.
All fixture settings have overridable defaults; the most useful overrides are:
| Variable / option | Default | Purpose |
| --- | --- | --- |
| `RDP_ACCESS_LAN_BIND` / `--lan-bind` | `auto` | Detect primary LAN IP; override for another private host interface |
| `RDP_ACCESS_LAN_PORT` / `--lan-port` | `3389` | Client-facing port; choose a free port on conflicts |
| `RDP_ACCESS_LAN_CIDR` / `--lan-cidr` | `auto` | Allow only the selected interface's subnet; override for a specific private subnet |
| `RDP_ACCESS_PROFILE` / `--profile` | `default` | Independent relay per VM/access profile |
| `RVBOX_TEST_VBOX_HOST` | `helium-remote` | SSH host for Docker/VBoxManage |
| `RDP_ACCESS_VRDE_PORT` | `3389` | Existing VM's loopback-only backend; verified against its actual VRDE port |
| `RDP_ACCESS_LAN_REMOTE_ROOT` | `/home/cabbage/.local/state/rvbox-rdp-access/lan` | Small generated per-profile Compose/state directories on Helium |
Explicit example for another LAN interface or a port conflict:
```sh
test/rdp-access/rdp-access lan-up \
--lan-bind 192.168.50.162 --lan-port 3391 --lan-cidr 192.168.50.0/24
```
`lan-up` rejects wildcard, loopback, public, unassigned, and malformed bind
addresses, excessive subnet masks, unowned port listeners, and a mismatched VM
or backend. It never kills an unrelated listener. Startup is idempotent, and
four bounded SSH attempts handle interruptions. Status/down/clean use saved
remote configuration, so they work even with the VM off; status distinguishes
the LAN listener from the VM's private backend being active/inactive. Rerun `lan-up` to
reconstruct missing generated state once the VM is running. After a host DHCP
address change, rerun `lan-up` and use its newly printed endpoint. Existing
host/network firewalls still apply; the helper does not grant broad firewall
access or configure router forwarding.
For multiple VMs, export each VM's recorded `RVBOX_TEST_VBOX_VM`, VM UUID,
snapshot name/UUID, and loopback VRDE port, choose a unique profile **and LAN
port**, then repeat that profile/host/VM identity on its lifecycle commands.
Do not reuse `default` to take over another VM's relay. The host-side projects
are `rvbox-rdp-lan-<profile>` and state lives under the remote root's
`<profile>/` directory, independent of the web gateway's local `.runtime/`.
The relay uses a digest-pinned [Alpine socat image](https://hub.docker.com/r/alpine/socat)
and Linux [Docker host networking](https://docs.docker.com/engine/network/drivers/host/)
to reach the existing loopback backend without changing its bind address.
It runs non-root, read-only, without Linux capabilities or host mounts, with
32 MiB/32-PID limits, at most 16 children, and bounded logs. No host package,
Windows service, or persistent broker is installed.
## Current fixture quick start
The following is the copy/paste path for the documented `rvbox-win10-test`
fixture. Run it from the repository root. The first command acquires the
exclusive VM lease, restores the clean Python/administrator-enabled snapshot, starts
the VM, and applies the VRDE display keepalive. The second command starts the
Docker-only gateway at the currently published endpoint:
```sh
scripts/windows/test-host prepare --run-id interactive-rdp
test/rdp-access/rdp-access up \
--bind 0.0.0.0 \
--public-host x1.xcel.me
```
`up` prompts for the fixture password. If the password is not already in the
operator's secure notes, the test-only value is available only in the Helium
host's mode-600 file documented in [`docs/testing-vm.md`](../../docs/testing-vm.md).
For an unattended first start, pass that file through the existing SSH alias
without putting the value in an argument, environment variable, or log:
```sh
ssh helium-remote 'cat /home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password' |
test/rdp-access/rdp-access up \
--bind 0.0.0.0 \
--public-host x1.xcel.me \
--web-password-stdin
```
The browser URL is `https://x1.xcel.me:5002/guacamole/`; accept the temporary
self-signed certificate warning and sign in as `rvboxtest`. The same command
is safe to rerun after a tunnel interruption. If the stack is already running,
`up` reuses it and repairs only missing forwarding; it does not consume stdin.
Use `--reset-auth` only after `down` when intentionally replacing the saved
verifier, for example:
```sh
test/rdp-access/rdp-access down
ssh helium-remote 'cat /home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password' |
test/rdp-access/rdp-access up \
--bind 0.0.0.0 \
--public-host x1.xcel.me \
--reset-auth \
--web-password-stdin
```
Do not run `clean` or `test-host reset` while another agent owns the fixture
lease or has a live browser session. The generated verifier, certificate,
tunnel state, and logs are disposable and live only under the ignored
`test/rdp-access/.runtime/` directory.
Before a first `prepare`, run `scripts/windows/test-host status`. If it reports
`state=running`, another run may already own the fixture lease; do not restore
or reset it. Reuse that run's access path or coordinate with its owner. If it
reports `state=poweroff`, the quick-start sequence above is safe. The helper
does not guess at ownership or silently take over a running VM.
## Lifecycle
Run commands from the repository root. First prepare the disposable VM using a
dedicated run ID. This restores the snapshot, starts the VM headlessly, and
holds the exclusive fixture lease while the manual action is in progress:
```sh
scripts/windows/test-host prepare --run-id interactive-rdp
```
For browser access from another machine, deliberately expose the temporary
HTTPS listener and name the host or IP users will enter in the browser:
```sh
test/rdp-access/rdp-access up \
--bind 0.0.0.0 \
--public-host x1.example.net
```
The command prompts without echo for the fixture password. It stores only its
MD5 verifier in `test/rdp-access/.runtime/config/user-mapping.xml`, mode 600;
the plaintext password is not placed in a command line, environment variable,
log, or repository file. Browse to the printed `https://.../guacamole/` URL,
accept the short-lived self-signed certificate warning, and sign in as
`rvboxtest` with the fixture password.
For localhost-only use, omit `--bind` and `--public-host`. The default listener
is `127.0.0.1:5002`; use a local SSH forward or a browser on the controller.
Choose alternate ports with `--http-port` and `--tunnel-port` if either is in
use. The VM must already be running. `up` checks the documented VM/snapshot
identity but intentionally does not restore, start, stop, or reset the VM. It
starts a small host-side watchdog for the SSH master. Before printing the URL,
`up` waits until the HTTPS gateway can serve `/guacamole/`; this prevents a
browser login from racing Tomcat's Guacamole WAR deployment. The watchdog
reconnects after a transient Helium/SSH failure while preserving the same
Docker-gateway listener, so an already-open Guacamole session can recover
without restarting the containers. Its PID, stop marker, and diagnostic log
are kept under the ignored `.runtime/` directory.
All fixture-specific values have embedded, working defaults: the
`helium-remote` SSH alias, Helium's loopback VRDE endpoint (`127.0.0.1:3389`),
`rvboxtest`, the browser listener (`127.0.0.1:5002`), and the private tunnel
port (`54001`). They can be overridden without editing tracked files through
`RVBOX_TEST_VBOX_HOST`, `RDP_ACCESS_VRDE_HOST`, `RDP_ACCESS_VRDE_PORT`,
`RDP_ACCESS_PROFILE`,
`RDP_ACCESS_WEB_USER`, `RDP_ACCESS_RDP_USER`, `RDP_ACCESS_BIND`,
`RDP_ACCESS_HTTP_PORT`, `RDP_ACCESS_TUNNEL_PORT`, and
`RDP_ACCESS_PUBLIC_HOST`, `RDP_ACCESS_IPV6_BIND`, and
`RDP_ACCESS_IPV6_FORWARD`. The helper deliberately limits the VRDE host to
Helium loopback (`127.0.0.1` or `localhost`) so an override cannot accidentally
turn the diagnostic server into a remote target.
Set `RDP_ACCESS_GUACD_LOG_LEVEL=debug` temporarily when collecting detailed
guacd/RDP negotiation diagnostics; the default is `info`.
The VM selector and the gateway profile are separate. Set the matching
`RVBOX_TEST_VBOX_*` identity variables (and `RDP_ACCESS_VRDE_PORT`) for the
VM you want; the complete identity set is listed in
[`docs/testing-vm.md`](../../docs/testing-vm.md). For two already-running VMs,
give the second gateway a distinct profile and listener ports, for example:
```sh
RDP_ACCESS_PROFILE=vm-b \
RVBOX_TEST_VBOX_HOST=helium-remote-b \
RDP_ACCESS_VRDE_PORT=3391 \
RDP_ACCESS_HTTP_PORT=5003 \
RDP_ACCESS_TUNNEL_PORT=54002 \
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host vm-b.example.net
```
Replace `helium-remote-b`, `3391`, and the public hostname with the second
fixture's recorded values, and export its matching VM/snapshot UUID variables
before running `up` or `status`. A non-`default` profile stores its verifier,
certificate, tunnel state, and logs under `.runtime/<profile>/` and uses the
Compose project `rvbox-rdp-access-<profile>`. Keep the HTTP port, public
hostname, and profile unique so IPv4/IPv6 listeners and browser sessions do
not collide. Inspect, repair, stop, or clean that instance by repeating the
same `RDP_ACCESS_PROFILE` and endpoint variables on `status`, `repair`,
`down`, or `clean`.
Profile isolation does not bypass the native controller's exclusive lease:
`test-host prepare`/`reset` must still be coordinated when VMs share one
fixture host and staging root. For VMs that are already running, the profile
and matching identity/VRDE variables are sufficient to select the endpoint.
When `--bind 0.0.0.0` is used, `up` also starts a tracked `socat` listener on
`[::]:$RDP_ACCESS_HTTP_PORT` and forwards it to the IPv4 gateway listener. This
matters when the public hostname has an AAAA record: some browsers choose IPv6
for the WebSocket even if the initial page used IPv4. The listener is recorded
under `.runtime/ipv6-forward.pid` and is removed by `down` and `clean`. Its
default bind is `::` (`RDP_ACCESS_IPV6_BIND`); set
`RDP_ACCESS_IPV6_FORWARD=never` to deliberately use IPv4 only, `always` to make
IPv6 startup a hard requirement, or leave the default `auto` for a warning and
an IPv4-only fallback when `socat` is unavailable. `status` reports
`ipv6_forward=active`, `active_external`, `inactive`, or `disabled`.
If `up` is run again while the Compose services are still running, it is
idempotent: an existing healthy tunnel is reused, and a missing tunnel is
recreated in place. `status` reports a helper-owned tunnel as
`private_tunnel=active` and a listener supplied by an external/interactive
SSH supervisor as `private_tunnel=active_external`. A missing listener is
reported as `private_tunnel=inactive`; inspect `.runtime/tunnel.log` and run
`up` again to trigger a bounded reconnect attempt.
If `up` reports that an existing gateway has a different configuration, or a
previous start left only part of the Compose stack, run `down` once and then
repeat `up`. Changing the bind address, browser host, or either port likewise
requires `down` first; refusing to mutate a live stack prevents an old browser
session from silently reaching a different endpoint.
The XML mapping intentionally uses Guacamole's `${GUAC_PASSWORD}` connection
parameter token. Guacamole resolves this to the password entered at web login;
it is not a host environment variable and must remain in the template.
After the interactive action, close the browser connection and remove the
temporary access path before releasing the fixture lease:
```sh
test/rdp-access/rdp-access down
scripts/windows/test-host reset --run-id interactive-rdp
```
`down` stops containers and the SSH watchdog/master/tunnel but retains the
one-day certificate and password verifier for a quick restart. To remove all
generated state, including the certificate, verifier, watchdog PID, and tunnel
log:
```sh
test/rdp-access/rdp-access clean
```
To also reclaim the exact Guacamole and nginx images when they have no
container dependency, use:
```sh
test/rdp-access/rdp-access clean --images
```
`clean --images` deliberately leaves `alpine:3.20` alone because it may be
shared by unrelated containers. Docker will refuse removal if any other
container still depends on an image.
## Operational checks and recovery
```sh
test/rdp-access/rdp-access status
test/rdp-access/rdp-access logs --tail=100
test/rdp-access/rdp-access url
```
If the browser reaches Guacamole but stays on “Waiting for response”, run
`status` first. Confirm `private_tunnel=active` (or
`active_external`) and, for a public dual-stack hostname,
`ipv6_forward=active` (or a known-good external forward). Then check the VM
state and the last lines of
`.runtime/tunnel.log`. A tunnel can be recreated without losing the Compose
stack by running `up` again. This helper already uses `security=rdp` and
disables Guacamole's GFX extension, which are required by the fixture's legacy
VRDE server. Do not switch the helper to native Windows RDP:
`TermService` is intentionally disabled in the baseline. If VRDE remains
unusable, stop this helper and use Guest Control for the deterministic portion
of the work; record the blocked interactive step in the native test report.
If guacd has a stale worker and the VM reports that multiple connections are
disabled, run:
```sh
test/rdp-access/rdp-access repair
```
`repair` restarts guacd **and the Guacamole web application**, clearing stale
workers and cached login connection settings. It retains the VM, SSH tunnel,
HTTPS gateway, and IPv6
forward, and does not alter the Windows guest. It restarts those services
sequentially and reloads nginx's upstream DNS address so Docker service IP
reassignment cannot leave a `502 Bad Gateway` behind. Close old browser tabs and sign
in again after it completes.
For quick recovery, use this decision table:
| Need | Command | Effect |
| --- | --- | --- |
| Inspect everything | `test/rdp-access/rdp-access status` | Read-only VM, Compose, tunnel, and IPv6-forward state |
| Start or reconnect access | `test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me` | Reuses healthy services; recreates only missing tunnel/forward |
| Browser says “Waiting for response”, or resolution remains from an old preset | `test/rdp-access/rdp-access status`; `test/rdp-access/rdp-access logs --tail=100`; `test/rdp-access/rdp-access repair`, then sign in again | Diagnoses tunnel/dual-stack issues; clears cached web logins and stale guacd workers without restarting the VM |
| Clock updates but keyboard/mouse cannot control Windows | Follow the input recovery procedure below; do not assume a frozen guest or restore a snapshot | Separates video, keyboard, and mouse health; preserves the current disk |
| Partial stack or changed endpoint | `test/rdp-access/rdp-access down`, then `test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me` | Recreates the exact project with the new settings |
| Print the current URL | `test/rdp-access/rdp-access url` | Read-only URL from the saved session |
| Stop temporary access | `test/rdp-access/rdp-access down` | Stops gateway, IPv6 forward, SSH watchdog/tunnel; retains verifier/cert |
| Reclaim generated state | `test/rdp-access/rdp-access clean` | Stops access and removes only `.runtime/` |
| Reclaim exact unused images too | `test/rdp-access/rdp-access clean --images` | Also removes owned Guacamole/nginx images; leaves shared Alpine intact |
| Return VM to clean baseline | `scripts/windows/test-host reset --run-id interactive-rdp` | Stops/ restores the exact leased VM snapshot and leaves it powered off |
### Live video but missing input
Video updates do not prove keyboard or mouse input is working. First close
other desktop tabs, run `rdp-access repair`, and sign in again. Verify a harmless
keyboard shortcut (Windows+R, then Escape) and an actual button click, not just
pointer movement. Do not run a second independent RDP probe while the browser
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 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 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).
To repair a currently running VM **without discarding its disk changes**, first
ask the desktop user to save work. Use Guest Control to request a normal
Windows shutdown, wait until this exact VM is `poweroff`, then run on Helium:
```sh
# Defaults shown; substitute the verified VM name for another fixture.
VBoxManage modifyvm rvbox-win10-test --usb-ohci on --mouse usbtablet \
--vrde-property 'Client/DisableInput='
VBoxManage startvm rvbox-win10-test --type headless
```
Check the VM UUID and lease owner before changing it. Do not force a poweroff
if normal shutdown is blocked by unsaved work. Repair the Guacamole connection
and sign in again if necessary. This preserves installed files, Python and its
machine PATH; it closes running applications. Do **not** use `test-host reset`
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
service lifecycle. For a prepared run, the remaining VM-side management actions
are:
```sh
scripts/windows/test-host inspect --run-id interactive-rdp # SCM/read-only client state
scripts/windows/test-host logs --run-id interactive-rdp # bounded startup/client logs
scripts/windows/test-host collect --run-id interactive-rdp # bounded artifacts
scripts/windows/test-host stop --run-id interactive-rdp # stop service and request guest shutdown
scripts/windows/test-host recover --run-id interactive-rdp # inspect an interrupted stopped run
```
`stage`, `install`, `run`, and `logoff` are also available in the
`test-host --help` command reference for a complete native-service run; they
are not required merely to use the RDP gateway. `native-test recover` and
`native-test clean` are the corresponding whole-lane recovery/cleanup actions
when the Linux server stack is part of the run.
The helper requires Docker/Docker Compose with Docker socket access for the
invoking account (`docker version` must succeed), `socat` for the optional
public dual-stack forward, SSH access through the existing `helium-remote`
alias, and the fixture password file documented in
[`docs/testing-vm.md`](../../docs/testing-vm.md). It does not install host
packages, write credentials into Git, or alter VM identity/settings. The
authoritative `test-host prepare` step applies only the disposable
display/sleep keepalive needed by VirtualBox VRDE; all generated content is
ignored beneath `.runtime/`.