diff --git a/README.md b/README.md index 1dc92f9..ed642e8 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,8 @@ Public relay binary and relay-owned room state: cargo check --workspace ``` +For the manual MVP end-to-end proof, see [TESTING.md](TESTING.md). + ## Relay ```bash diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 0000000..8256065 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,235 @@ +# MVP Test Guide + +This guide is for the manual end-to-end MVP proof: + +```text +Windows TAP client -> public QUIC relay -> Linux AF_PACKET gateway -> LAN +``` + +The MVP is intentionally manual. It does not include an installer, GUI, +production certificates, auth, or end-to-end payload encryption. + +## Machines + +- Relay: public Linux host reachable over UDP. +- Gateway: Linux machine plugged into the LAN party switch with wired Ethernet. +- Client: Windows 11 machine with TAP-Windows6 installed. + +Use the same room code everywhere, for example `ROOM1`. + +## Build + +On the relay or Linux build host: + +```bash +cargo build --release -p lanparty-relay -p lanparty-gateway +``` + +On Windows, in an Administrator terminal: + +```powershell +cargo build --release -p lanparty-client-win +``` + +The Windows client must run elevated because it opens TAP and edits routes. +The gateway usually needs root because it opens an AF_PACKET raw socket. + +## Start The Relay + +Use a high UDP port first unless you already want to deal with privileged +`443/udp` binding: + +```bash +./target/release/lanparty-relay \ + --listen 0.0.0.0:8443 \ + --dev-cert-der-out relay-cert.der +``` + +Open inbound UDP for the selected port on the relay host firewall. + +Expected relay output: + +```text +lanparty-relay configured for 0.0.0.0:8443/udp ... +lanparty-relay listening on 0.0.0.0:8443 +``` + +Copy `relay-cert.der` to the gateway and Windows client. The development +certificate is for `lanparty-relay.local`, so keep +`--server-name lanparty-relay.local` even when `--relay` is an IP address or +another DNS name. + +## Start The Gateway + +On the LAN gateway machine: + +```bash +sudo ./target/release/lanparty-gateway \ + --relay relay.example.net:8443 \ + --server-name lanparty-relay.local \ + --relay-ca-cert ./relay-cert.der \ + --room ROOM1 \ + --iface eth0 +``` + +Use the real wired LAN interface name for `--iface`. Do not use Wi-Fi. + +Expected gateway output: + +```text +lanparty-gateway connected as peer ... +lanparty-gateway opened AF_PACKET socket on eth0 ... +lanparty-gateway bridging frames; press Ctrl-C to stop +``` + +Expected relay output: + +```text +accepted Gateway peer ... in room ROOM1 ... +``` + +## Start The Windows Client + +In an Administrator terminal on Windows: + +```powershell +.\target\release\lanparty-client-win.exe ` + --relay relay.example.net:8443 ` + --server-name lanparty-relay.local ` + --relay-ca-cert .\relay-cert.der ` + --room ROOM1 +``` + +Expected client output: + +```text +lanparty-client-win connected as peer ... +relay route pinned before TAP ... +relay route verified after TAP activation ... +TAP driver reports MAC ... and MTU ... +client diagnostics: relay reachable yes gateway connected yes route pinned yes ... +``` + +The first diagnostics line may show `IP unknown`. After DHCP succeeds, a later +line should show: + +```text +DHCP received: 10.x.x.x +``` + +## What To Verify + +1. Relay sees both peers: + +```text +accepted Gateway peer ... +accepted Client peer ... +``` + +2. Client sees the gateway: + +```text +gateway connected yes +Connected to LAN gateway +``` + +3. Windows TAP gets an address from the LAN: + +```powershell +Get-NetIPAddress | ? InterfaceAlias -like "*TAP*" +``` + +4. ARP and ping work from the TAP-side address: + +```powershell +arp -d * +ping -S +arp -a +``` + +5. The LAN switch learns the remote client MAC on the gateway port. + +Use the switch UI or CLI and look for the client MAC printed by the Windows +client. It should appear on the physical port connected to the Linux gateway. + +6. A real LAN game discovers or joins a LAN server. + +This is the practical MVP acceptance test. + +## Useful Log Signals + +Relay frame forwarding: + +```text +relay frame room=ROOM1 ... action=Forwarded drop_reason=- targets=1 +``` + +Gateway LAN traffic: + +```text +gateway frame interface=eth0 direction=LanToRemote ... action=Forwarded +gateway frame interface=eth0 direction=RemoteToLan ... action=Forwarded +``` + +Client health: + +```text +Relay RTT: 23 ms +Broadcast traffic flowing +``` + +Drops that can be normal during testing: + +```text +drop_reason=UnknownDestination +drop_reason=DatagramBudget +drop_reason=RateLimit +``` + +Drops that should be investigated if they dominate: + +```text +drop_reason=Malformed +drop_reason=UnauthorizedSourceMac +drop_reason=ControlPlaneEtherType +``` + +## Troubleshooting + +If the client says `Waiting for LAN gateway`, check that the gateway uses the +same room code and is connected to the same relay. + +If the client says `Waiting for TAP IP`, DHCP is not making the full round trip. +Check relay/gateway frame logs for broadcast traffic and check that the gateway +is on wired Ethernet. + +If startup fails with a TAP MAC mismatch, disable/enable the TAP adapter or +reinstall TAP-Windows6 so Windows reloads the `NetworkAddress` value. Do not +continue with a mismatched MAC. + +If startup says the relay route changed, stop. The client is refusing to run +because Windows would route the relay connection through the tunnel. + +If ping fails but DHCP worked, check Windows firewall, the target LAN host +firewall, and whether the LAN subnet conflicts with the client's home LAN. +Uncommon LAN subnets such as `10.73.42.0/24` are safer than `192.168.0.0/24`. + +## Cleanup + +Stop client, gateway, and relay with Ctrl-C. The Windows client restores the TAP +route policy when it exits normally. + +Keep `lanparty-client-identity.json` if you want the same virtual MAC on the +next run. Delete it only when you intentionally want a new client identity. + +## Report Back + +For a useful test report, capture: + +- relay command and relay logs +- gateway command and gateway logs +- client command and client logs +- Windows TAP MAC and IP +- ping result from `` to a LAN host +- switch MAC-table entry for the Windows client MAC +- LAN game discovery or join result