shadowvpn 0.5.0

A UDP-based, pre-shared-key (PSK), user-mode VPN using the shadowsocks AEAD UDP wire scheme.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# Quick start

Get a working tunnel between two hosts in a few minutes. You need a server
host with a public (or otherwise reachable) UDP port, and a client host.

## 1. Install the binaries

The fastest path (Linux & macOS) — a one-liner per host that installs the
latest release to `/usr/local/bin` and drops an example config at
`/etc/shadowvpn/`:

::: code-group

```sh [server host]
curl -fsSL https://raw.githubusercontent.com/madeye/shadowvpn/main/scripts/install.sh | sudo bash -s -- server
```

```sh [client host]
curl -fsSL https://raw.githubusercontent.com/madeye/shadowvpn/main/scripts/install.sh | sudo bash -s -- client
```

:::

::: tip One-shot server setup
On a Linux server, `sudo bash -s -- server --setup` does the whole server
side in one command — config with a random password, systemd service enabled
+ started, forwarding + NAT, host firewall — and prints the matching client
config. See [Server: one-line full setup](./installation#server-setup).
:::

Or build from source with a recent stable Rust toolchain (edition 2021):

```sh
cargo build --release
```

This produces `target/release/shadowvpn-server` and
`target/release/shadowvpn-client`. See [Installation](./installation) for
the installer's options, release packages, Windows, and cross-compiling.
The examples below use the source-build paths — with the one-line install,
the binaries are just `shadowvpn-server` / `shadowvpn-client` on your `PATH`.

## 2. Start the server

Creating a TUN device requires elevated privileges (root on Linux, `sudo` on
macOS, Administrator on Windows).

```sh
sudo ./target/release/shadowvpn-server \
  --listen 0.0.0.0:8388 \
  --password "correct horse battery staple" \
  --cipher chacha20-poly1305 \
  --tun-ip 10.9.0.1 \
  --peer-ip 10.9.0.2
```

## 3. Start the client

```sh
sudo ./target/release/shadowvpn-client \
  --server vpn.example.com:8388 \
  --password "correct horse battery staple" \
  --cipher chacha20-poly1305 \
  --tun-ip 10.9.0.2 \
  --peer-ip 10.9.0.1
```

Note how `tun_ip` and `peer_ip` are mirror images: the server's local tunnel
IP is the client's peer, and vice versa.

## 4. Verify

From the client, ping the server's in-tunnel address:

```sh
ping 10.9.0.1
```

A successful ping exercises the entire path: TUN → encrypt → UDP → server →
decrypt → TUN, and the reply all the way back.

## 5. Route traffic through it

The tunnel itself is up, but nothing uses it until you route traffic into the
TUN device. Pick one:

- **Full tunnel** — route everything through the tunnel (and NAT it out on
  the server). See [Routing & IP forwarding](./routing).
- **Split tunnel** — let the client decide per destination with its built-in
  policy routing (`gfwlist` / `chinadns` modes), no external tooling:

  ```sh
  # tunnel only the domains in a gfwlist file
  sudo ./target/release/shadowvpn-client -c client.json \
    --mode gfwlist --gfwlist /etc/shadowvpn/gfwlist.txt

  # or: tunnel everything that isn't a China IP, from a GeoLite2 database
  sudo ./target/release/shadowvpn-client -c client.json \
    --mode chinadns --geoip /etc/shadowvpn/GeoLite2-Country.mmdb
  ```

  See [Policy routing](./policy-routing).

Either way, for tunneled traffic to reach the internet the **server** must
enable IP forwarding and NAT — see
[Routing & IP forwarding](./routing#server-enable-ip-forwarding-nat).

## Using config files instead

Both binaries accept `-c, --config <PATH>` pointing at a JSON file; CLI flags
override JSON values. The same setup as above:

::: code-group

```json [server.json]
{
  "server": "0.0.0.0:8388",
  "password": "correct horse battery staple",
  "cipher": "chacha20-poly1305",
  "tun_ip": "10.9.0.1",
  "tun_netmask": "255.255.255.0",
  "peer_ip": "10.9.0.2",
  "mtu": 1400
}
```

```json [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
}
```

:::

```sh
sudo ./target/release/shadowvpn-server -c server.json
sudo ./target/release/shadowvpn-client -c client.json
```

See the [configuration guide](./configuration) for every field.