Shadowvpn Deploy Client

Deploy the ShadowVPN client

The client owns a TUN device and a single UDP socket connected to the server. It needs elevated privileges (root on Linux, sudo on macOS, Administrator on Windows — Wintun + route/DNS changes).

Repo references — read these for the canonical artifacts:

• dist/README.md, dist/systemd/shadowvpn-client.service, dist/launchd/io.github.madeye.shadowvpn-client.plist — Linux/macOS service install.
• scripts/README.md, scripts/shadowvpn-client.ps1/.cmd — Windows self-elevating launcher.
• README.md §Configuration, §Running, §"Policy routing (gfwlist / chinadns)", §"Client: route traffic through the tunnel".

1. Build the binary for the target

Native: cargo build --release --bin shadowvpn-client → target/release/shadowvpn-client.

Cross-build from a dev box (preferred for remote targets — Zig linker, no Docker):

# Linux x86_64 / aarch64 (pin glibc to the target, e.g. 2.31 for Pi / older distros)
cargo zigbuild --release --target aarch64-unknown-linux-gnu.2.31 --bin shadowvpn-client
# Windows x64
cargo zigbuild --release --target x86_64-pc-windows-gnu      --bin shadowvpn-client
# Windows on ARM (ARM64)
cargo zigbuild --release --target aarch64-pc-windows-gnullvm --bin shadowvpn-client

Windows arch gotcha (error 193): the exe and wintun.dll must match the host CPU arch. An x64 exe on an ARM64 Windows box runs under emulation but cannot load an ARM64 wintun.dll → LoadLibraryExW … error 193 (%1 is not a valid Win32 application) at TUN creation. Verify the PE machine type before shipping (0x8664 = x64, 0xAA64 = ARM64) and pair it with the matching wintun.dll.

Getting wintun.dll (Windows only)

Official release zips already bundle it. The Windows release packages (shadowvpn-<ver>-<target>-pc-windows-msvc.zip) ship the matching-arch wintun.dll next to the exe and a GeoLite2-Country.mmdb for chinadns geoip mode — so a release download is self-contained, nothing else to fetch.

You only need the steps below when you built the client yourself (the repo source does not contain wintun.dll — separate license, arch-specific). Download the official signed release from WireGuard and pull the DLL for the host's CPU arch out of it:

# 1. Download the release zip (pin a known version; 0.14.1 is the latest as of writing)
curl -fLO https://www.wintun.net/builds/wintun-0.14.1.zip
# (optional, recommended) verify the download against the SHA-256 on https://www.wintun.net/

# 2. The zip lays the DLLs out by architecture:
#    wintun/bin/amd64/wintun.dll   <- x64        (PE 0x8664)
#    wintun/bin/arm64/wintun.dll   <- ARM64      (PE 0xAA64)
#    wintun/bin/x86/wintun.dll     <- 32-bit x86
#    wintun/bin/arm/wintun.dll     <- 32-bit ARM
unzip -j wintun-0.14.1.zip 'wintun/bin/amd64/wintun.dll' -d .   # pick the arch you need

On Windows/PowerShell: Expand-Archive wintun-0.14.1.zip -DestinationPath wintun then copy wintun\wintun\bin\<arch>\wintun.dll next to shadowvpn-client.exe.

The DLL is loaded at runtime from the same folder as the exe (it is not installed system-wide). Match it to the exe you built: an x86_64-pc-windows-* exe needs amd64, an aarch64-pc-windows-* exe needs arm64 — mismatch is the error-193 above. Source + checksums: https://www.wintun.net/.

2. Write client.json

{
  "server": "vpn.example.com:8388",
  "password": "correct horse battery staple",
  "cipher": "chacha20-poly1305",
  "tun_ip": "10.9.0.2",
  "tun_netmask": "255.255.255.0",
  "peer_ip": "10.9.0.1",
  "mtu": 1400,
  "obfs": "quic"
}

• server = the server's public host:port. The client resolves the hostname with its own built-in DNS client (querying dns_remote/dns_local directly), not the OS resolver — so a dirty/127.0.0.1-pinned system resolver no longer blocks startup (PR #27). A literal ip:port skips resolution entirely.
• password, cipher, obfs must match the server.
• tun_ip/peer_ip mirror the server's. If the server runs --nat, every client can share this identical config; otherwise give each client a distinct tun_ip.

3a. Install — Linux (systemd)

sudo install -Dm755 target/release/shadowvpn-client /usr/local/bin/shadowvpn-client
sudo install -Dm600 client.json /etc/shadowvpn/client.json
sudo cp dist/systemd/shadowvpn-client.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now shadowvpn-client
journalctl -u shadowvpn-client -f
sudo systemctl stop shadowvpn-client     # graceful: restores DNS + routes, saves cache

3b. Install — macOS (launchd)

sudo install -Dm755 target/release/shadowvpn-client /usr/local/bin/shadowvpn-client
sudo mkdir -p /etc/shadowvpn && sudo cp client.json /etc/shadowvpn/client.json
sudo cp dist/launchd/io.github.madeye.shadowvpn-client.plist /Library/LaunchDaemons/
sudo launchctl load -w /Library/LaunchDaemons/io.github.madeye.shadowvpn-client.plist
tail -f /var/log/shadowvpn-client.log
sudo launchctl unload -w /Library/LaunchDaemons/io.github.madeye.shadowvpn-client.plist  # graceful

3c. Install — Windows

Lay out one folder with shadowvpn-client.exe, the matching-arch wintun.dll, and client.json (+ any policy data files). Two ways to run:

Foreground (interactive): from an elevated PowerShell, .\shadowvpn-client.exe -c client.json, or use the self-elevating launcher scripts\shadowvpn-client.cmd (see scripts/README.md). Stop with Ctrl-C — graceful (restores DNS, removes routes, saves cache). Never taskkill /F (see DNS gotcha below).

Headless service (runs with no user logged on) — register a Scheduled Task:

• Action: shadowvpn-client.exe -c <abs path to config>, working dir = the folder.
• LogonType = Password (store the box's creds) — Interactive can't start at the login screen. RunLevel = Highest (Wintun needs elevation).
• Triggers: AtStartup + AtLogon; restart a few times on failure.
• full mode programs no routes itself — wrap the exe in a script that adds the routes + sets DNS on the tun adapter after the tun comes up (see the gotchas).
• Control: Start-ScheduledTask / Stop-ScheduledTask -TaskName <name>. A Stop-ScheduledTask is a hard kill (no Ctrl-C) — pair it with a teardown script that restores DNS/routes.