Files

T

ddidderr 217469edf0 fix(gateway): reject LAN interfaces without carrier

A gateway with the selected Ethernet cable unplugged can still open an
AF_PACKET socket and join the relay room. That makes clients see a connected LAN
gateway even though DHCP and LAN discovery cannot make the physical round trip.

Check the selected Linux interface's sysfs carrier file before creating the raw
socket. If sysfs reports carrier 0, fail before the gateway joins the relay.
Missing or unrecognized carrier files remain allowed so this does not reject
interfaces where the kernel cannot expose link state in that form. README and
TESTING now document the preflight and the operator fix.

Test Plan:
All cargo commands used these environment variables:
RUSTUP_HOME=/tmp/softlan-vpn-rustup
CARGO_HOME=/tmp/softlan-vpn-cargo

- cargo test -p lanparty-gateway \
  packet::tests::detects_disconnected_interfaces_from_sysfs_carrier
- cargo test -p lanparty-gateway
- cargo fmt --check
- cargo test --workspace
- cargo clippy --workspace --all-targets -- -D warnings
- git diff --check

Refs: PLAN.md wired Ethernet gateway requirement

2026-05-22 04:48:12 +02:00

6.9 KiB

Raw Blame History

MVP Test Guide

This guide is for the manual end-to-end MVP proof:

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:

cargo build --release -p lanparty-relay -p lanparty-gateway

On Windows, in an Administrator terminal:

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:

./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:

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:

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. The gateway fails before joining the relay if sysfs reports no Ethernet carrier.

Expected gateway output:

lanparty-gateway opening interface eth0 and connecting to relay ...
lanparty-gateway opened AF_PACKET socket on eth0 ...
lanparty-gateway connected as peer ...
lanparty-gateway bridging frames; press Ctrl-C to stop

Expected relay output:

accepted Gateway peer ... in room ROOM1 ...

Start The Windows Client

In an Administrator terminal on Windows:

.\target\release\lanparty-client-win.exe `
  --relay relay.example.net:8443 `
  --server-name lanparty-relay.local `
  --relay-ca-cert .\relay-cert.der `
  --room ROOM1

If the Windows machine has multiple TAP-Windows6 adapters, select the intended one explicitly:

.\target\release\lanparty-client-win.exe --list-tap-adapters

.\target\release\lanparty-client-win.exe `
  --relay relay.example.net:8443 `
  --server-name lanparty-relay.local `
  --relay-ca-cert .\relay-cert.der `
  --room ROOM1 `
  --tap-instance-id "{InterfaceGuid-from-the-command-above}"

Expected client output:

prepared TAP adapter ... media disconnected before relay connect
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 route pin line ends with (created) or (already existed). Either is OK. already existed usually means a matching relay host route was already present, for example after a previous crashed test run.

The first diagnostics line may show IP unknown. After DHCP succeeds, a later line should show:

DHCP received: 10.x.x.x

What To Verify

Relay sees both peers:

accepted Gateway peer ...
accepted Client peer ...

Client sees the gateway:

gateway connected yes
Connected to LAN gateway

Windows TAP gets an address from the LAN:

Get-NetIPAddress | ? InterfaceAlias -like "*TAP*"

ARP and ping work from the TAP-side address:

arp -d *
ping -S <tap-ip> <lan-host-ip>
arp -a

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.

A real LAN game discovers or joins a LAN server.

This is the practical MVP acceptance test.

Useful Log Signals

Relay frame forwarding:

relay frame room=ROOM1 ... action=Forwarded drop_reason=- targets=1

Gateway LAN traffic:

gateway frame interface=eth0 direction=LanToRemote ... action=Forwarded
gateway frame interface=eth0 direction=RemoteToLan ... action=Forwarded

Client health:

Relay RTT: 23 ms
Broadcast traffic flowing

Drops that can be normal during testing:

drop_reason=UnknownDestination
drop_reason=DatagramBudget
drop_reason=RateLimit

Drops that should be investigated if they dominate:

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 gateway fails with reports no carrier, plug the selected Ethernet interface into the LAN party switch, bring the interface up, and restart the gateway.

If startup fails before the relay connection while preparing the TAP adapter, check that the terminal is elevated, TAP-Windows6 is installed, and --tap-instance-id selects the intended adapter when more than one TAP adapter exists.

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 removes the relay host route only when it created that route itself, restores the TAP route policy, and marks TAP media disconnected 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 <tap-ip> to a LAN host
switch MAC-table entry for the Windows client MAC
LAN game discovery or join result

6.9 KiB Raw Blame History