484 lines
26 KiB
Markdown
484 lines
26 KiB
Markdown
# 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.
|
||
|
||
## 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.
|
||
|
||
## 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/`.
|