Mirrors/wireguard-docs
1
0
Fork 0
mirror of https://github.com/pirate/wireguard-docs.git synced 2026-04-25 06:56:18 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Audit README accuracy and source links

Browse Source
This commit is contained in:
Nick Sweeting
2026-03-21 02:37:42 -07:00
parent a46ff728b8
commit 847f1cac3a
1 changed files with 57 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
README.md
View File

@@ -12,8 +12,8 @@ API reference guide for WireGuard including Setup, Configuration, and Usage, wit
<small>
Source for these docs, example code, and issue tracker: https://github.com/pirate/wireguard-docs &nbsp; &nbsp;
Nicer HTML page version: https://docs.sweeting.me/s/wireguard
Source for these docs, example code, and issue tracker: [wireguard-docs](https://github.com/pirate/wireguard-docs) &nbsp; &nbsp;
Nicer HTML page version: [docs.sweeting.me](https://docs.sweeting.me/s/wireguard)
</small>
@@ -25,13 +25,13 @@ Nicer HTML page version: https://docs.sweeting.me/s/wireguard
**Official Links**
- Homepage: https://www.wireguard.com
- Install: https://www.wireguard.com/install/
- QuickStart: https://www.wireguard.com/quickstart/
- Manpages: [`wg`](https://manpages.debian.org/testing/wireguard-tools/wg.8.en.html), [`wg-quick`](https://manpages.debian.org/unstable/wireguard-tools/wg-quick.8.en.html)
- Main Git repo: https://git.zx2c4.com/WireGuard/
- GitHub Mirror: https://github.com/WireGuard/WireGuard
- Mailing List: https://lists.zx2c4.com/mailman/listinfo/wireguard
- [Homepage](https://www.wireguard.com/)
- [Install](https://www.wireguard.com/install/)
- [QuickStart](https://www.wireguard.com/quickstart/)
- Manpages: [`wg(8)`](https://man7.org/linux/man-pages/man8/wg.8.html), [`wg-quick(8)`](https://man7.org/linux/man-pages/man8/wg-quick.8.html)
- [Main Git repo](https://git.zx2c4.com/WireGuard/)
- [GitHub Mirror](https://github.com/WireGuard/WireGuard)
- [Mailing List](https://lists.zx2c4.com/mailman/listinfo/wireguard)
**WireGuard Goals**
@@ -44,7 +44,7 @@ Nicer HTML page version: https://docs.sweeting.me/s/wireguard
<div align="center">
<a href="https://www.ckn.io/blog/2017/11/14/wireguard-vpn-typical-setup/"><img src="https://www.ckn.io/images/wireguard_comparisions.png" width="600px"/></a><br/><small>
It's also <i>fast as hell</i>. I routinely get sub 0.5ms pings and 900mbps+ on good connections.<br/>
(See https://www.ckn.io/blog/2017/11/14/wireguard-vpn-typical-setup/)
(See [this WireGuard topology write-up](https://www.ckn.io/blog/2017/11/14/wireguard-vpn-typical-setup/))
</small>
</div>
@@ -52,7 +52,7 @@ It's also <i>fast as hell</i>. I routinely get sub 0.5ms pings and 900mbps+ on g
# Table of Contents
See https://github.com/pirate/wireguard-docs for example code and documentation source.
See [wireguard-docs](https://github.com/pirate/wireguard-docs) for example code and documentation source.
<ul>
<li><a href="#Table-of-Contents">Table of Contents</a></li>
@@ -224,7 +224,7 @@ A host that connects to the VPN and registers a VPN subnet address such as `192.
A publicly reachable peer/node that serves as a fallback to relay traffic for other VPN peers behind NATs. A bounce server is not a special type of server, it's a normal peer just like all the others, the only difference is that it has a public IP and has kernel-level IP forwarding turned on which allows it to bounce traffic back down the VPN to other clients.
See more: https://tailscale.com/blog/how-nat-traversal-works/ (Tailscale uses Wireguard under the hood)
See more: [How NAT traversal works](https://tailscale.com/blog/how-nat-traversal-works/) (Tailscale uses WireGuard under the hood)
### Subnet
@@ -240,7 +240,7 @@ A way of defining a subnet and its size with a "mask", a smaller mask = more ad
+ `0.0.0.1/0` (4,294,967,296 IPs from `0.0.0.0` - `255.255.255.255`) netmask = `0.0.0.0`
+ IPv6 CIDR notation is also supported e.g. `2001:DB8::/64`
https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
[Classless Inter-Domain Routing (CIDR)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)
To people just getting started `192.0.2.1/32` may seem like a weird and confusing way to refer to a single IP. This design is nice though because it allows peers to expose multiple IPs if needed without needing multiple notations. Just know that anywhere you see something like `192.0.2.3/32`, it really just means `192.0.2.3`.
@@ -264,7 +264,7 @@ A WireGuard public key for a single node, generated with:
### DNS
Domain Name Server, used to resolve hostnames to IPs for VPN clients, instead of allowing DNS requests to leak outside the VPN and reveal traffic. Leaks are testable with http://dnsleak.com.
Domain Name Server, used to resolve hostnames to IPs for VPN clients, instead of allowing DNS requests to leak outside the VPN and reveal traffic. Leaks are testable with [dnsleak.com](https://dnsleak.com).
---
@@ -378,7 +378,7 @@ You can also read in keys from a file or via command if you don't want to hardco
```ini
[Interface]
...
PostUp = wg set %i private-key /etc/wireguard/wg0.key <(cat /some/path/%i/privkey)
PreUp = wg set %i private-key <(cat /some/path/%i/privkey)
```
Technically, multiple servers can share the same private key as long as clients arent connected to two servers with the same key simulatenously.
@@ -466,7 +466,7 @@ wg pubkey < example.key > example.key.pub
```bash
wg-quick up /full/path/to/wg0.conf
wg-quick down /full/path/to/wg0.conf
# Note: you must specify the absolute path to wg0.conf, relative paths won't work
# Note: CONFIG_FILE can be in any directory, but its filename must still match the interface name, e.g. ./wg0.conf or /full/path/to/wg0.conf
# If wg0.conf is in /etc/wireguard you can use the simpler:
wg-quick up wg0
```
@@ -609,7 +609,7 @@ iperf -c 192.0.2.4 # on local client
#### DNS
Check for DNS leaks using http://dnsleak.com, or by checking the resolver on a lookup:
Check for DNS leaks using [dnsleak.com](https://dnsleak.com), or by checking the resolver on a lookup:
```bash
dig example.com A
```
@@ -701,7 +701,7 @@ Defines what address(es) the local WireGuard interface should use. Depending on
* IPv6-only client address: `Address = 2001:DB8::3/128`
* Node is a public bounce server that can relay traffic to other peers
When the node is acting as the public bounce server, it should set this to be the entire subnet that it can route traffic, not just a single IP for itself.
When the node is acting as the public bounce server, it should use an address inside the VPN subnet together with the subnet prefix length it routes, not just a `/32` for itself.
`Address = 192.0.2.1/24`
@@ -746,7 +746,7 @@ Optionally defines which routing table to use for the WireGuard routes, not nece
There are two special values: ‘off’ disables the creation of routes altogether, and ‘auto’ (the default) adds routes to the default table and enables special handling of default routes.
https://git.zx2c4.com/WireGuard/about/src/tools/man/wg-quick.8
See [`wg-quick(8)`](https://man7.org/linux/man-pages/man8/wg-quick.8.html).
**Examples**
@@ -762,8 +762,7 @@ The MTU is automatically determined from the endpoint addresses or the system de
You should avoid setting this if at all possible. You almost certainly do not want 1500 here due to the encapsulation overhead.
https://git.zx2c4.com/WireGuard/about/src/tools/man/wg-quick.8
https://www.dropvps.com/blog/mtu-setting-wireguard/
See [`wg-quick(8)`](https://man7.org/linux/man-pages/man8/wg-quick.8.html).
**Examples**
@@ -790,7 +789,7 @@ This option can appear multiple times, as with <a href="#PreUp">PreUp</a>
**Examples**
* Read in a config value from a file or some command's output
`PostUp = wg set %i private-key /etc/wireguard/wg0.key <(some command here)`
`PostUp = wg set %i private-key <(some command here)`
* Log a line to a file
`PostUp = echo "$(date +%s) WireGuard Started" >> /var/log/wireguard.log`
@@ -815,10 +814,10 @@ This option can appear multiple times, as with <a href="#PreUp">PreUp</a>
**Examples**
* Log a line to a file
`PostDown = echo "$(date +%s) WireGuard Going Down" >> /var/log/wireguard.log`
`PreDown = echo "$(date +%s) WireGuard Going Down" >> /var/log/wireguard.log`
* Hit a webhook on another server
`PostDown = curl https://events.example.dev/wireguard/stopping/?key=abcdefg`
`PreDown = curl https://events.example.dev/wireguard/stopping/?key=abcdefg`
#### `PostDown`
@@ -899,7 +898,7 @@ This is just a standard comment in INI syntax used to help keep track of which c
#### `Endpoint`
Defines the publicly accessible address for a remote peer. This should be left out for peers behind a NAT or peers that don't have a stable publicly accessible IP:PORT pair. Typically, this only needs to be defined on the main bounce server, but it can also be defined on other public nodes with stable IPs like `public-server2` in the example config below. IPv6 literal endpoints are supported, but they must be wrapped in square brackets.
Defines the publicly accessible address for a remote peer. This should be left out for peers behind a NAT or peers that don't have a stable publicly accessible IP:PORT pair. Typically, this only needs to be defined on the main bounce server, but it can also be defined on other public nodes with stable IPs like `public-server2` in the example config below. IPv6 literal endpoints are supported, but they must be wrapped in square brackets. After a packet is received from a peer, WireGuard also updates the stored endpoint to that peer's most recent authenticated source IP:PORT.
**Examples**
@@ -951,7 +950,7 @@ This key can be generated with `wg pubkey < example.key > example.key.pub`.
#### `PersistentKeepalive`
If the connection is going from a NAT-ed peer to a public peer, the node behind the NAT must regularly send an outgoing ping in order to keep the bidirectional connection alive in the NAT router's connection table.
If the connection is going from a NAT-ed peer to a public peer, the node behind the NAT must regularly send an outgoing keepalive packet in order to keep the bidirectional connection alive in the NAT router's connection table.
**Examples**
@@ -962,7 +961,7 @@ If the connection is going from a NAT-ed peer to a public peer, the node behind
This value should be left undefined as it's the client's responsibility to keep the connection alive because the server cannot reopen a dead connection to the client if it times out.
- local NAT-ed node to remote public node
`PersistentKeepalive = 25` this will send a ping to every 25 seconds keeping the connection open in the local NAT router's connection table.
`PersistentKeepalive = 25` this will send an authenticated empty keepalive packet every 25 seconds, keeping the connection open in the local NAT router's connection table.
---
@@ -1014,17 +1013,17 @@ AllowedIPs = 0.0.0.0/0, ::/0
### NAT To NAT Connections
WireGuard can sometimes natively make connections between two clients behind NATs without the need for a public relay server, but in most cases this is not possible. NAT-to-NAT connections are only possible if at least one host has a stable, publicly-accessible IP address:port pair that can be hardcoded ahead of time, whether that's using a FQDN updated with Dynamic DNS, or a static public IP with a non-randomized NAT port opened by outgoing packets, anything works as long as all peers can communicate it beforehand and it doesn't change once the connection is initiated.
Plain WireGuard configs can sometimes make direct connections between two clients behind NATs without the need for a public relay server, but there is no built-in signaling or discovery layer to find the right public IP:PORT pair automatically. In practice, manual NAT-to-NAT setups only work when the peers already know usable public IP:PORT information ahead of time, or when an external signaling/discovery tool provides it.
A known port and address need to be configured ahead of time because WireGuard doesn't have a signalling layer or public STUN servers that can be used to search for other hosts dynamically. WebRTC is an example of a protocol that can dynamically configure a connection between two NATs, but it does this by using an out-of-band signaling server to detect the IP:port combo of each host. WireGuard doesn't have this, so it only works with a hardcoded `Endpoint` + `ListenPort` (and `PersistentKeepalive` so it doesn't drop after inactivity).
A known port and address need to be configured ahead of time for the static/manual approach described here. WebRTC is an example of a protocol that can dynamically configure a connection between two NATs, but it does this by using an out-of-band signaling server to detect the IP:PORT combo of each host. WireGuard itself doesn't do that, so the plain `wg`/`wg-quick` setup below only works with a hardcoded `Endpoint` + `ListenPort` (and `PersistentKeepalive` so it doesn't drop after inactivity).
Learn more from Tailscale's bible of NAT traversal: https://tailscale.com/blog/how-nat-traversal-works/
See the official [wireguard-tools `nat-hole-punching` example](https://git.zx2c4.com/wireguard-tools/tree/contrib/nat-hole-punching/) for a manual setup.
#### Requirements for NAT-to-NAT setups
- At least one peer has to have to have a hardcoded, directly-accessible `Endpoint` defined. If they're both behind NATs without stable IP addresses, then you'll need to use Dynamic DNS or another solution to have a stable, publicly accessibly domain/IP for at least one peer
- At least one peer has to have a hardcoded UDP `ListenPort` defined, and it's NAT router must not do UDP source port randomization, otherwise return packets will be sent to the hardcoded `ListenPort` and dropped by the router, instead of using the random port assigned by the NAT on the outgoing packet
- All NAT'ed peers must have `PersistentKeepalive` enabled on all other peers, so that they continually send outgoing pings to keep connections persisted in their NAT's routing table
- For the static/manual approach, at least one peer has to have a usable `Endpoint` that can be configured ahead of time. If neither side has one, you'll need an external discovery/signaling solution or a relay server
- At least one peer has to have a hardcoded UDP `ListenPort` defined, and its NAT router must not do UDP source port randomization, otherwise return packets will be sent to the hardcoded `ListenPort` and dropped by the router instead of using the random port assigned by the NAT on the outgoing packet
- All NAT'ed peers must have `PersistentKeepalive` enabled on all other peers, so that they continually send outgoing keepalive packets to keep connections persisted in their NAT's routing table
#### The hole-punching connection process
@@ -1048,19 +1047,19 @@ NAT-to-NAT connections are not possible if all endpoints are behind NAT's with s
##### Using a signaling server
NAT-to-NAT connections from behind NATs with strict source-port randomization is possible, you just need a signaling server to tell each side the other's IP:port tuple. Here are a few implementations that achieve this with WireGuard:
A signaling server can improve the odds by telling each side the other's current public IP:PORT tuple, but it still depends on the NAT behavior of both networks. Here are a few implementations that do this for WireGuard:
- https://github.com/takutakahashi/wg-connect
- https://git.zx2c4.com/wireguard-tools/tree/contrib/nat-hole-punching/
- https://github.com/jwhited/wgsd
##### Dynamic IP addresses
Many users report having to restart WireGuard whenever a dynamic IP changes, as it only resolves hostnames on startup. To force WireGuard to re-resolve dynamic DNS `Endpoint` hostnames more often, you may want to use a `PostUp` hook to restart WireGuard every few minutes or hours.
If a peer's public IP changes, WireGuard can learn the new endpoint from authenticated packets sent by that peer, but DNS hostnames are not continuously polled in the background. If you depend on Dynamic DNS `Endpoint` hostnames being refreshed proactively, you may need external tooling; the official wireguard-tools repo includes [`reresolve-dns.sh`](https://git.zx2c4.com/wireguard-tools/tree/contrib/reresolve-dns/) for exactly this purpose.
#### Testing it out
You can see if a hole-punching setup is feasible by using netcat on the client and server to see what ports and connection order work to get a bidirectional connection open: run `nc -v -u -p 51820 <address of peer2> 51820` (on peer1) and `nc -v -u -l 0.0.0.0 51820` (on peer2), then type in both windows to see if you can get bidirectional traffic going. If it doesn't work regardless of which peer sends the initial packet, then WireGuard won't be unable to work between the peers without a public relay server.
You can see if a hole-punching setup is feasible by using netcat on the client and server to see what ports and connection order work to get a bidirectional connection open: run `nc -v -u -p 51820 <address of peer2> 51820` (on peer1) and `nc -v -u -l 0.0.0.0 51820` (on peer2), then type in both windows to see if you can get bidirectional traffic going. If it doesn't work regardless of which peer sends the initial packet, then WireGuard will be unable to work between the peers without a public relay server.
NAT-to-NAT connections are often more unstable and have other limitations, which is why having a fallback public relay server is still advised.
@@ -1082,7 +1081,7 @@ NAT-to-NAT connections are often more unstable and have other limitations, which
```ini
[Interface]
...
ListenPort 12000
ListenPort = 12000
[Peer]
...
@@ -1094,7 +1093,7 @@ PersistentKeepalive = 25
```ini
[Interface]
...
ListenPort 12000
ListenPort = 12000
[Peer]
...
@@ -1107,7 +1106,7 @@ PersistentKeepalive = 25
*Note: this section is about dynamic peer IPs within the VPN subnet, not dynamic public `Endpoint` addresses*.
Dynamic allocation of peer IPs (instead of only having fixed peers) is being developed, the WIP implementation is available here:
https://github.com/WireGuard/wg-dynamic
[wg-dynamic](https://git.zx2c4.com/wg-dynamic/about/)
You can also build a dynamic allocation system yourself by reading in IP values from files at runtime by using `PostUp` (see below).
@@ -1115,7 +1114,7 @@ You can also build a dynamic allocation system yourself by reading in IP values
```ini
[Interface]
...
PostUp = wg set %i allowed-ips /etc/wireguard/wg0.key <(some command)
PostUp = wg set %i peer "$(cat /etc/wireguard/peer1.pub)" allowed-ips "$(cat /etc/wireguard/peer1.allowedips)"
```
### Other WireGuard Implementations
@@ -1129,14 +1128,11 @@ An incomplete, insecure userspace implementation of WireGuard written in Rust (n
- https://git.zx2c4.com/wireguard-hs/about/
An incomplete, insecure userspace implementation of WireGuard written in Haskell (not ready for the public).
- https://github.com/cloudflare/boringtun
A non-compliant, independent WireGuard implementation written in Rust (a separate fork written by CloudFlare).
See https://blog.cloudflare.com/boringtun-userspace-wireguard-rust/
- [BoringTun](https://github.com/cloudflare/boringtun)
An independent userspace WireGuard implementation written in Rust by Cloudflare.
See also: [BoringTun: userspace WireGuard in Rust](https://blog.cloudflare.com/boringtun-userspace-wireguard-rust/)
- Platform-specific WireGuard apps
https://git.zx2c4.com/wireguard-ios/about/
https://git.zx2c4.com/wireguard-android/about/
https://git.zx2c4.com/wireguard-windows/about/
- Platform-specific WireGuard apps: [wireguard-ios](https://git.zx2c4.com/wireguard-ios/about/), [wireguard-android](https://git.zx2c4.com/wireguard-android/about/), [wireguard-windows](https://git.zx2c4.com/wireguard-windows/about/)
All of the userspace implementations are slower than the native C version that runs in kernel-land, but provide other benefits by running in userland (e.g. easier containerization, compatibility, etc.).
@@ -1178,13 +1174,13 @@ These are some GUI and CLI tools that wrap WireGuard to assist with config, depl
### Config Shortcuts
Credit for these shortcuts goes to:
https://www.ericlight.com/new-things-i-didnt-know-about-wireguard.html
[New Things I Didn't Know About Wireguard](https://www.ericlight.com/new-things-i-didnt-know-about-wireguard.html)
#### Sharing a single peers.conf file
WireGuard will ignore a peer whose public key matches the interface's private key. So you can distribute a single list of peers everywhere, and only define the `[Interface]` separately on each server.
See: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003703.html
See: [WireGuard mailing list discussion](https://lists.zx2c4.com/pipermail/wireguard/2018-December/003703.html)
You can combine this with `wg addconf` like this:
@@ -1192,7 +1188,7 @@ You can combine this with `wg addconf` like this:
* Each peer also has a shared `/etc/wireguard/peers.conf` file, which contains all the peers.
* The `wg0.conf` file also has a `PostUp` hook: `PostUp = wg addconf /etc/wireguard/peers.conf`.
* The `wg0.conf` file also has a `PostUp` hook: `PostUp = wg addconf %i /etc/wireguard/peers.conf`.
It's up to you to decide how you want to share the `peers.conf`, be it via a proper orchestration platform, something much more pedestrian like Dropbox, or something kinda wild like Ceph. I dunno, but it's pretty great that you can just wildly fling a peer section around, without worrying whether it's the same as the interface.
@@ -1200,13 +1196,13 @@ It's up to you to decide how you want to share the `peers.conf`, be it via a pro
You can set config values from arbitrary commands or by reading in values from files, this makes key management and deployment much easier as you can read in keys at runtime from a 3rd party service like Kubernetes Secrets or AWS KMS.
See: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003702.html
See: [WireGuard mailing list discussion](https://lists.zx2c4.com/pipermail/wireguard/2018-December/003702.html)
**Example**
You can read in a file as the `PrivateKey` by doing something like:
`PostUp = wg set %i private-key /etc/wireguard/wg0.key <(some command)`
`PreUp = wg set %i private-key /etc/wireguard/wg0.key`
### Containerization
@@ -1299,13 +1295,13 @@ For more details see the Further Reading: Docker section below.
### Reference Docs
- https://www.wireguard.com/install/#installation
- https://git.zx2c4.com/WireGuard/about/src/tools/man/wg.8
- https://git.zx2c4.com/WireGuard/about/src/tools/man/wg-quick.8
- https://wiki.archlinux.org/index.php/WireGuard / https://wiki.archlinux.org/title/WireGuard
- https://wiki.debian.org/Wireguard#Configuration
- https://docs.netgate.com/pfsense/en/latest/vpn/wireguard/index.html
- https://www.procustodibus.com/blog/2020/10/wireguard-topologies/
- [WireGuard install guide](https://www.wireguard.com/install/#installation)
- [`wg(8)` man page](https://man7.org/linux/man-pages/man8/wg.8.html)
- [`wg-quick(8)` man page](https://man7.org/linux/man-pages/man8/wg-quick.8.html)
- [ArchWiki: WireGuard](https://wiki.archlinux.org/title/WireGuard)
- [Debian Wiki: WireGuard configuration](https://wiki.debian.org/Wireguard#Configuration)
- [Netgate pfSense WireGuard docs](https://docs.netgate.com/pfsense/en/latest/vpn/wireguard/index.html)
- [Pro Custodibus: WireGuard topologies](https://www.procustodibus.com/blog/2020/10/wireguard-topologies/)
### Tutorials
@@ -1320,7 +1316,6 @@ For more details see the Further Reading: Docker section below.
- https://techcrunch.com/2018/07/28/how-i-made-my-own-wireguard-vpn-server/
- https://www.ckn.io/blog/2017/11/14/wireguard-vpn-typical-setup/
- https://jrs-s.net/2018/08/05/routing-between-wg-interfaces-with-wireguard/
- https://www.stavros.io/posts/how-to-configure-wireguard/
- https://vincent.bernat.ch/en/blog/2018-route-based-vpn-wireguard
- https://staaldraad.github.io/2017/04/17/nat-to-nat-with-wireguard
- https://try.popho.be/wg.html
@@ -1439,13 +1434,13 @@ For more details see the Further Reading: Docker section below.
- https://news.ycombinator.com/item?id=17659983
- https://news.ycombinator.com/item?id=17846387
For more detailed instructions, see the [QuickStart](#QuickStart) guide and API reference above. You can also download the complete example setup here: https://github.com/pirate/wireguard-example.
For more detailed instructions, see the [QuickStart](#QuickStart) guide and API reference above. You can also download the complete example setup here: [wireguard-example](https://github.com/pirate/wireguard-example).
---
<center>
Suggest changes: https://github.com/pirate/wireguard-docs/issues
Suggest changes: [wireguard-docs issues](https://github.com/pirate/wireguard-docs/issues)
</center>