vpn: add gateway support

Author: pymq

.github/workflows/test.yml

@@ -33,6 +33,19 @@ jobs:
         run: go test -count=1 -v ./...
       - name: Test with -race
         run: go test -race -count=1 -v ./...
+      - name: VPN gateway host-network integration test (Linux, root)
+        # Hidden behind the `vpn_hostnet` build tag and excluded from `go test ./...`.
+        # Exercises the real netlink/iptables plumbing (SetupNAT/SetupGatewayRoutes
+        # + teardown/stale-recovery) against the runner's own network, so it needs
+        # root and only runs on Linux. Compile as the normal user, then run the
+        # binary under sudo so root never pollutes the Go build cache.
+        # TODO: if a hard failure ever leaves the runner's egress black-holed
+        # (default route via a dead awl0) and breaks log upload, add a separate
+        # `if: always()` cleanup step
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          go test -c -tags vpn_hostnet -o gw-hostnet.test ./vpn/routes/
+          sudo ./gw-hostnet.test -test.run '^TestGatewayHostNet' -test.v
       - name: Build cmd/awl
         run: go build github.com/anywherelan/awl/cmd/awl
       - name: Upload cmd/awl build
@@ -103,9 +116,68 @@ jobs:
           # TODO: remove this temporal hack for linux
           ping awl-tester.awl -w 20 -c 10 || true
 
+          # ---- VPN gateway server (exit-node) mode: runtime enable/disable round-trips OS state ----
+          # awl runs as root here, so enabling the server installs real NAT
+          # (iptables MASQUERADE + AWL-FORWARD chain) in this netns. We assert the
+          # commands succeed AND that they actually mutate then fully restore the
+          # netfilter state. `iptables -S` (no packet/byte counters, unlike
+          # iptables-save) makes the before/after comparison stable.
+          nat_state() { sudo iptables -S; sudo iptables -t nat -S; }
+          NAT_BEFORE=$(nat_state)
+          ./awl cli gateway server enable
+          test "$(nat_state)" != "$NAT_BEFORE"          # enable actually changed netfilter
+          sudo iptables -S | grep -q AWL-FORWARD        # exit-node chain installed
+          ./awl cli gateway server disable
+          test "$(nat_state)" = "$NAT_BEFORE"           # disable restored netfilter exactly
+
+          # ---- VPN gateway full-tunnel e2e: client = this runner, exit node = awl-tester ----
+          # Requires the awl-tester peer to have VPN gateway server enabled AND to
+          # permit this CI peer as an exit node (WeAllowUsingAsExitNode); both are
+          # advertised to us via the status protocol. Wait until it shows up as a
+          # connected, available gateway.
+          for i in $(seq 1 15); do
+            if ./awl cli gateway list | grep -E 'awl-tester.*\[connected\]'; then break; fi
+            sleep 2
+          done
+          ./awl cli gateway list | grep -E 'awl-tester.*\[connected\]'   # fail if never became available
+
+          # Probe the egress IP via https://ifconfig.me
+          curl4() { curl -4 -s --max-time 20 --retry 3 --retry-delay 2 https://ifconfig.me/; }
+
+          IP_DIRECT=$(curl4); echo "egress IP (direct): $IP_DIRECT"
+
+          ./awl cli gateway client use --name awl-tester
+          ./awl cli gateway status
+          RULE_ON=$(ip rule show); ROUTE_ON=$(ip route show)
+          # Tolerate a failed curl here so we always reach `client stop` below
+          # (a broken tunnel must not leave the runner black-holed); the
+          # `test -n "$IP_GW"` assertion after teardown turns it into a clean failure.
+          IP_GW=$(curl4 || true); echo "egress IP (via gateway): $IP_GW"
+
+          ./awl cli gateway client stop
+          RULE_OFF=$(ip rule show); ROUTE_OFF=$(ip route show)
+          IP_REVERTED=$(curl4); echo "egress IP (reverted): $IP_REVERTED"
+
+          # Assertions run with the gateway already disabled, so a failure here
+          # can't leave the runner's egress black-holed.
+          echo "$RULE_ON"  | grep -q fwmark                  # client policy route installed
+          echo "$ROUTE_ON" | grep -q 'default dev awl0'      # full-tunnel default via TUN
+          test -n "$IP_GW"                                    # traffic really flowed through the exit node
+          test "$IP_GW" != "$IP_DIRECT"                      # egress changed => full-tunnel works
+          test "$IP_REVERTED" = "$IP_DIRECT"                 # runtime disable reverted egress
+          ! echo "$RULE_OFF"  | grep -q fwmark               # policy route removed on disable
+          ! echo "$ROUTE_OFF" | grep -q 'default dev awl0'   # TUN default removed on disable
+
+          # Re-enable so the SIGINT shutdown path (teardownGatewayAtShutdown) is exercised.
+          ./awl cli gateway client use --name awl-tester
+
           sleep 1
           sudo kill -SIGINT $awl_pid
-          sleep 1
+          sleep 2
+          # awl is gone: its TUN and the default route via it vanished with the
+          # process, but the fwmark ip rule is interface-independent — its absence
+          # proves the shutdown teardown ran. (NAT/ip_forward are server-side only.)
+          ! ip rule show | grep -q fwmark
       - name: Run librespeed-cli, awl, librespeed-cli through awl
         if: matrix.os == 'macos-latest'
         run: |

README.md

@@ -22,6 +22,7 @@
   - [Linux server (`awl`)](#linux-server-awl)
 - [Connecting devices](#connecting-devices)
 - [Using devices as SOCKS5 proxy](#using-devices-as-socks5-proxy)
+- [VPN gateway (full-tunnel exit node)](#vpn-gateway-full-tunnel-exit-node)
 - [Configuration](#configuration)
   - [Config file location](#config-file-location)
   - [Example config](#example-config)
@@ -45,6 +46,7 @@ Some things people use it for:
 - SSH / RDP / VNC into your home or work laptop from anywhere, without port forwarding or exposing anything to the internet
 - reach selfhosted services (Nextcloud, Home Assistant, Bitwarden, ...) privately
 - route traffic through a remote device as a SOCKS5 proxy — useful for bypassing regional blocks
+- route *all* your traffic through a remote device at the IP layer — a full-tunnel VPN gateway / exit node
 - LAN-style multiplayer gaming across the internet
 - keep an old Android phone accessible for apps that only run there (e.g. with [scrcpy](https://github.com/Genymobile/scrcpy))
 
@@ -64,6 +66,7 @@ Tradeoffs worth knowing about:
 ## Features
 
 - fully peer-to-peer, no coordination server — see [Why Anywherelan](#why-anywherelan) above
+- route **all** your traffic through a device — full-tunnel VPN gateway / exit node
 - route traffic through a device as a SOCKS5 proxy
 - automatic NAT traversal via libp2p; falls back to community relays when a direct path isn't possible
 - TLS 1.3 encryption (QUIC or TCP+TLS)
@@ -114,7 +117,7 @@ awl's transport security comes from [libp2p](https://docs.libp2p.io/).
 
 awl ships in two desktop flavors:
 
-- **`awl-tray`** — desktop build with a system-tray indicator: status at a glance, start/stop/restart, peer list. Use this for regular desktop usage.
+- **`awl-tray`** — desktop build with a system-tray indicator: status at a glance, start/stop/restart, peer list, and quick exit-node selection (SOCKS5 proxy / VPN gateway). Use this for regular desktop usage.
 - **`awl`** — headless server build, no GUI. Use this for servers and embedded devices.
 
 Both share the same web UI and the same [CLI](#terminal-based-client).
@@ -231,6 +234,95 @@ On desktop you can also pick the active exit node from the web UI or the system
 
 Traffic through a peer has no restrictions beyond the connection between the two of you — direct and relayed paths both work. You can reach the remote peer's LAN, but not the remote peer's `localhost`.
 
+## VPN gateway (full-tunnel exit node)
+
+awl can route **all** of your IPv4 traffic through a remote device at the IP layer — the same model as classic full-tunnel WireGuard/OpenVPN. The remote device becomes your exit node: your traffic reaches the internet from its IP, not yours.
+
+### VPN gateway vs SOCKS5 proxy
+
+awl has two independent ways to send your traffic through another device, and a device can offer either one without the other. The **SOCKS5 proxy** works per-application: you point a specific app (a browser, say) at awl's local proxy, and only that app's traffic goes through the peer — nothing on your system changes. The **VPN gateway** is system-wide: it routes *all* of your IPv4 traffic through the exit node at the IP layer, so every app is covered without configuring anything.
+
+In short: reach for SOCKS5 to send a single app through a peer, and for the VPN gateway when you want the whole device to look like it's at the exit node.
+
+### Status
+
+| Platform | As client | As exit node | Notes |
+| --- | --- | --- | --- |
+| Linux | ✅ | ✅ | fully supported |
+| Android | ✅ | ❌ | exit-node role needs root — not planned |
+| Windows | ⏳ | ⏳ | coming next |
+| macOS | ❌ | ❌ | needs volunteers for testing |
+
+On macOS and Windows awl currently refuses to start with VPN gateway enabled.
+
+> ⚠️ **IPv6 is not tunnelled.** The gateway only carries IPv4. While it's on, all IPv6 traffic is dropped so that your real IPv6 address is never exposed past the exit node:
+> - **Dual-stack (IPv4 + IPv6):** everything automatically uses IPv4 through the tunnel.
+> - **IPv6-only network:** you'll have no internet connectivity until you turn the gateway off.
+
+> **Linux: host network changes mid-session aren't tracked.** If the host switches network (new Wi-Fi, Ethernet or cellular connection) while the gateway is on, restart awl. This will be fixed in a future release.
+
+### Serve as an exit node
+
+This lets your other devices route their internet traffic out through this one. It is **off by default** — see [Why serving as an exit node is opt-in](#why-serving-as-an-exit-node-is-opt-in) below. Two things need to be set: turn the gateway service on, then allow each specific device to use it. Serving as an exit node is Linux-only (see the status table above).
+
+**Desktop (web UI):** open http://admin.awl, go to **Settings** (the gear icon, top-right) and turn on **Serve as VPN Gateway**. Then, for each device you want to permit, open its card on the Overview page, click **Settings**, and set **Allow as exit node** to *Allowed*. On `awl-tray` you can also toggle the service from the tray menu under **VPN Gateway → Serve as VPN Gateway**.
+
+Turning the service on takes effect immediately — no restart. awl enables IP forwarding and sets up firewall rules that let that traffic out while keeping your own LAN private (see "Security and privacy notes" below); everything is reversed when you turn it off or shut awl down.
+
+Once enabled, your permitted devices can pick this one as their exit node. It may take a few minutes to show up on their side — awl exchanges status with each device periodically (≤ 5 minutes) and on every reconnect.
+
+> The "Allow as exit node" permission is shared with SOCKS5. If you need separate permissions for SOCKS5 vs the VPN gateway, [open an issue](https://github.com/anywherelan/awl/issues) and we'll split it.
+
+#### Via the CLI
+
+```bash
+# turn the gateway service on (server disable turns it off)
+awl cli gateway server enable
+# allow a specific device to use this one as an exit node
+awl cli peers allow_exit_node --name="peer-name" --allow=true
+```
+
+### Use a remote device as your exit node (client side)
+
+First make sure you've added the remote device and it has the gateway service enabled on its side (see above).
+
+**Desktop (web UI):** open http://admin.awl; on the Overview page, find the **VPN Gateway** card on the right and pick the peer in the **Exit peer** dropdown. That's it — all your traffic now goes out through that device. Set it back to *None* to turn the gateway off. On `awl-tray` the same picker is in the tray menu, and on Android you use the gateway control in the app.
+
+This takes effect immediately — no restart. Switching to a different peer in the dropdown atomically moves the gateway to the new device.
+
+To confirm it's working, open a "what's my IP" site such as https://ifconfig.co — it should show the exit node's public IP, not yours.
+
+#### Via the CLI
+
+```bash
+# list peers available as exit nodes
+awl cli gateway list
+# route all traffic through a peer (or --pid=<peer-id>)
+awl cli gateway client use --name="peer-name"
+# show status: gateway peer, whether it's connected, its public IP and ping
+awl cli gateway status
+# stop using the gateway
+awl cli gateway client stop
+```
+
+### Why serving as an exit node is opt-in
+
+Unlike the SOCKS5 proxy, serving as a VPN gateway changes global system state on the host: awl turns on `net.ipv4.ip_forward` and installs iptables rules. That can interfere with the host's existing networking or firewall setup, and it isn't something awl can sandbox — so we don't enable it on a routine install. You opt in explicitly, the same way every mainstream VPN (Tailscale, ZeroTier, WireGuard, OpenVPN, …) keeps exit-node mode opt-in.
+
+The privacy exposure — your IP appearing as the source of another device's traffic — is *not* what this toggle gates: it is the same for SOCKS5 and the VPN gateway, and it's controlled by the per-device **Use as exit** permission (see "Security and privacy notes" below). This toggle only governs the host-level networking changes above.
+
+### Troubleshooting
+
+- **A device isn't available as an exit node.** It hasn't turned on **Serve as VPN Gateway**, or hasn't set **Allow as exit node** to *Allowed* for you, or the status exchange hasn't propagated yet — wait up to ~5 minutes or until the next reconnect.
+- **A "what's my IP" site still shows your own IP after enabling.** Check the gateway status (the **VPN Gateway** card, or `awl cli gateway status`): if it's not connected, awl can't reach the exit node, so nothing is being tunnelled.
+- **A site works over IPv6 but not through the gateway.** Expected — IPv6 isn't tunnelled (see the note above). Dual-stack hosts fall back to IPv4 automatically; anything IPv6-only won't work while the gateway is on.
+
+### Security and privacy notes
+
+- **Your IP is exposed.** Once you serve as an exit node, the public IPs that those devices reach see your IP, not theirs.
+- **Your LAN is not.** awl drops forwarded traffic to RFC 1918 / RFC 6598 / RFC 3927 ranges (`10/8`, `172.16/12`, `192.168/16`, `100.64/10`, `169.254/16`) so a gateway client cannot reach the exit node's home network.
+- **DNS:** in client gateway mode awl forces upstream DNS to a public resolver (`1.1.1.1` by default) so the LAN resolver can't leak queries past the tunnel. If you'd rather use a different resolver, you can change it by hand in the config file (`dns.upstreamDNSAddress`) while awl is stopped.
+
 ## Configuration
 
 Awl stores all its state in a single JSON file called `config_awl.json`. The file is created automatically on the first launch and is rewritten by the application every time you change something through the web UI or CLI. You can also edit it by hand while awl is stopped.

api/api.go

@@ -36,6 +36,7 @@ type Handler struct {
 	socks5     *service.SOCKS5
 	dns        DNSService
 	logBuffer  *ringbuffer.RingBuffer
+	vpnGateway *service.VPNGateway
 
 	echo      *echo.Echo
 	echoAdmin *echo.Echo
@@ -45,7 +46,7 @@ type Handler struct {
 }
 
 func NewHandler(conf *config.Config, p2p *p2p.P2p, authStatus *service.AuthStatus, tunnel *service.Tunnel, socks5 *service.SOCKS5,
-	logBuffer *ringbuffer.RingBuffer, dns DNSService) *Handler {
+	logBuffer *ringbuffer.RingBuffer, dns DNSService, vpnGateway *service.VPNGateway) *Handler {
 	ctx, ctxCancel := context.WithCancel(context.Background())
 	return &Handler{
 		conf:       conf,
@@ -55,6 +56,7 @@ func NewHandler(conf *config.Config, p2p *p2p.P2p, authStatus *service.AuthStatu
 		socks5:     socks5,
 		dns:        dns,
 		logBuffer:  logBuffer,
+		vpnGateway: vpnGateway,
 		logger:     log.Logger("awl/api"),
 		ctx:        ctx,
 		ctxCancel:  ctxCancel,
@@ -137,6 +139,12 @@ func (h *Handler) setupRouter(address string) (*echo.Echo, error) {
 	e.POST(UpdateProxySettingsPath, h.UpdateProxySettings)
 	e.GET(ExportServerConfigPath, h.ExportServerConfiguration)
 
+	// VPN Gateway. Status comes from /settings/peer_info (PeerInfo.VPNGateway).
+	e.POST(EnableVPNGatewayClientPath, h.EnableVPNGatewayClient)
+	e.POST(DisableVPNGatewayClientPath, h.DisableVPNGatewayClient)
+	e.POST(SetVPNGatewayServerEnabledPath, h.SetVPNGatewayServerEnabled)
+	e.GET(ListAvailableVPNGatewaysPath, h.ListAvailableVPNGateways)
+
 	// Debug
 	e.GET(GetP2pDebugInfoPath, h.GetP2pDebugInfo)
 	e.GET(GetDebugLogPath, h.GetLog)
@@ -177,6 +185,9 @@ func (h *Handler) SetupFrontend(fsys fs.FS) {
 }
 
 func (h *Handler) Shutdown(ctx context.Context) error {
+	if h.ctxCancel != nil {
+		h.ctxCancel()
+	}
 	if h.echoAdmin != nil {
 		err := h.echoAdmin.Server.Shutdown(ctx)
 		if err != nil {

api/apiclient/client.go

@@ -152,6 +152,30 @@ func (c *Client) UpdateMySettings(name string) error {
 	return c.sendPostRequest(api.UpdateMyInfoPath, request, nil)
 }
 
+func (c *Client) EnableVPNGatewayClient(gatewayPeerID string) error {
+	request := entity.EnableVPNGatewayClientRequest{
+		GatewayPeerID: gatewayPeerID,
+	}
+	return c.sendPostRequest(api.EnableVPNGatewayClientPath, request, nil)
+}
+
+func (c *Client) DisableVPNGatewayClient() error {
+	return c.sendPostRequest(api.DisableVPNGatewayClientPath, nil, nil)
+}
+
+func (c *Client) SetVPNGatewayServerEnabled(enabled bool) error {
+	return c.sendPostRequest(api.SetVPNGatewayServerEnabledPath, entity.SetVPNGatewayServerEnabledRequest{Enabled: enabled}, nil)
+}
+
+func (c *Client) ListAvailableVPNGateways() ([]entity.AvailableVPNGateway, error) {
+	resp := entity.ListAvailableVPNGatewaysResponse{}
+	err := c.sendGetRequest(api.ListAvailableVPNGatewaysPath, &resp)
+	if err != nil {
+		return nil, err
+	}
+	return resp.VPNGateways, nil
+}
+
 func (c *Client) P2pDebugInfo() (*entity.P2pDebugInfo, error) {
 	debugInfo := new(entity.P2pDebugInfo)
 	err := c.sendGetRequest(api.GetP2pDebugInfoPath, debugInfo)

api/const.go

@@ -22,6 +22,12 @@ const (
 	UpdateProxySettingsPath  = V0Prefix + "settings/set_proxy"
 	ExportServerConfigPath   = V0Prefix + "settings/export_server_config"
 
+	// VPN Gateway
+	EnableVPNGatewayClientPath     = V0Prefix + "vpn_gateway/client/enable"
+	DisableVPNGatewayClientPath    = V0Prefix + "vpn_gateway/client/disable"
+	ListAvailableVPNGatewaysPath   = V0Prefix + "vpn_gateway/client/list_available"
+	SetVPNGatewayServerEnabledPath = V0Prefix + "vpn_gateway/server/set_enabled"
+
 	// Debug
 	GetP2pDebugInfoPath = V0Prefix + "debug/p2p_info"
 	GetDebugLogPath     = V0Prefix + "debug/log"