Add reproducible LAN-only RDP access on Helium

This commit is contained in:
cabbage committed 2026-10-08 14:26:52 +00:00
1 parent 90d6b05f4d
commit 34274f0f62
9 files changed
+452 -1

No files matched your search

+104
View File
@@ -24,6 +24,11 @@ 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`:
@@ -66,6 +71,105 @@ 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`