Some Unofficial WireGuard Documentation

<br/><br/>

API reference guide for WireGuard including Setup, Configuration, and Usage, with examples.

<i>All credit goes to the WireGuard project, zx2c4 and the open source contributors for the original software,<br/> this is my solo unofficial attempt at providing more comprehensive documentation, API references, and examples.</i>

<small>

Source for these docs, example code, and issue tracker: https://github.com/pirate/wireguard-docs Nicer HTML page version: https://docs.sweeting.me/s/wireguard

</small> </div>

WireGuard is an open-source VPN solution written in C by Jason Donenfeld and others, aiming to fix many of the problems that have plagued other modern server-to-server VPN offerings like IPSec/IKEv2, OpenVPN, or L2TP. It shares some similarities with other modern VPN offerings like Tinc and MeshBird, namely good cipher suites and minimal config. As of 2020-01 it's been merged into the 5.6 version of the Linux kernel, meaning it will ship with most Linux systems out-of-the-box.

Official Links

Homepage: https://www.wireguard.com
Install: https://www.wireguard.com/install/
QuickStart: https://www.wireguard.com/quickstart/
Manpages: wg, wg-quick
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

strong, modern security by default
minimal config and key management
fast, both low-latency and high-bandwidth
simple internals and small protocol surface area
simple CLI and seamless integration with system networking

<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/) </small> </div>

See https://github.com/pirate/wireguard-docs for example code and documentation source.

<ul> <li><a href="#Table-of-Contents">Table of Contents</a></li> <li><a href="#Intro">Intro</a> <ul> <li><a href="#My-Personal-Requirements-for-a-VPN-Solution">My Personal Requirements for a VPN Solution</a></li> <li><a href="#List-of-Possible-VPN-Solutions">List of Possible VPN Solutions</a></li> </ul> </li> <li><a href="#WireGuard-Documentation">WireGuard Documentation</a> <ul> <li><a href="#Glossary">Glossary</a> <ul> <li><a href="#PeerNodeDevice">Peer/Node/Device</a></li> <li><a href="#Bounce-Server">Bounce Server</a></li> <li><a href="#Subnet">Subnet</a></li> <li><a href="#CIDR-Notation">CIDR Notation</a></li> <li><a href="#NAT">NAT</a></li> <li><a href="#Public-Endpoint">Public Endpoint</a></li> <li><a href="#Private-key">Private key</a></li> <li><a href="#Public-key">Public key</a></li> <li><a href="#DNS">DNS</a></li> <li><a href="#Example-Strings">Example Strings</a></li> </ul> </li> <li><a href="#How-WireGuard-Works">How WireGuard Works</a> <ul> <li><a href="#How-Public-Relay-Servers-Work">How Public Relay Servers Work</a></li> <li><a href="#How-WireGuard-Routes-Packets">How WireGuard Routes Packets</a></li> <li><a href="#What-WireGuard-Traffic-Looks-Like">What WireGuard Traffic Looks Like</a></li> <li><a href="#WireGuard-Performance">WireGuard Performance</a></li> <li><a href="#WireGuard-Security-Model">WireGuard Security Model</a></li> <li><a href="#How-WireGuard-Manages-Keys">How WireGuard Manages Keys</a></li> </ul> </li> <li><a href="#Usage">Usage</a> <ul> <li><a href="#QuickStart">QuickStart</a></li> <li><a href="#Setup">Setup</a></li> <li><a href="#Config-Creation">Config Creation</a></li> <li><a href="#Key-Generation">Key Generation</a></li> <li><a href="#Start--Stop">Start / Stop</a></li> <li><a href="#Inspect">Inspect</a></li> <li><a href="#Testing">Testing</a></li> </ul> </li> <li><a href="#Config-Reference">Config Reference</a> <ul> <li><a href="#Interface">[Interface]</a></li> <li><a href="#Peer">[Peer]</a></li> </ul> </li> <li><a href="#Advanced-Topics">Advanced Topics</a> <ul> <li><a href="#IPv6">IPv6</a></li> <li><a href="#Forwarding-All-Traffic">Forwarding All Traffic</a></li> <li><a href="#NAT-to-NAT-Connections">NAT-to-NAT Connections</a></li> <li><a href="#Dynamic-IP-Allocation">Dynamic IP Allocation</a></li> <li><a href="#Other-WireGuard-Implementations">Other WireGuard Implementations</a></li> <li><a href="#WireGuard-Setup-tools">WireGuard Setup Tools</a></li> <li><a href="#Config-Shortcuts">Config Shortcuts</a></li> <li><a href="#Containerization">Containerization</a></li> </ul> </li> </ul> </li> <li><a href="#Further-Reading">Further Reading</a> <ul> <li><a href="#Reference-Docs">Reference Docs</a></li> <li><a href="#Tutorials">Tutorials</a></li> <li><a href="#Papers-Articles-and-Talks">Papers, Articles, and Talks</a></li> <li><a href="#Related-Projects">Related Projects</a></li> <li><a href="#Docker">Docker</a></li> <li><a href="#Other">Other</a></li> <li><a href="#Discussions">Discussions</a></li> </ul> </li> </ul>

Intro

Whether living behind the Great Wall of China or just trying to form a network between your servers, WireGuard is a great option and serves as a "lego block" for building networks (much in the same way that ZFS is a lego block for building filesystems).

WireGuard Overview

minimal config, low tunable surface area and sane defaults
minimal key management work needed, just 1 public & 1 private key per host
behaves like a normal ethernet interface, behaves well with standard kernel packet routing rules
ability to easily create a LAN like 192.0.2.0/24 between all servers, or more complex networks using custom routes
ability to some traffic or all traffic to/through arbitrary hosts on the VPN LAN
robust automatic reconnects after reboots / network downtime / NAT connection table drops
fast (low latency and line-rate bandwidth)
modern encryption, secure by default with forward secrecy & resilience to downgrade attacks
ideally support for any type of Level 2 and control traffic, e.g. ARP/DHCP/ICMP (or ideally raw ethernet frames), not just TCP/HTTP
ability to join the VPN from Ubuntu, FreeBSD, iOS, MacOS, Windows, Android (via open-source apps or natively)
supports both running on the host routing traffic for docker or running in a docker container routing for the host

Things WireGuard does not do:

form a self-healing mesh network where nodes automatically gossip with neighbors
break through double NATs with a signalling server (WebRTC-style)
handle automatically distributing & revoking keys through a central authority
allow sending raw layer-2 ethernet frames (it's at the IP layer)

But you can write your own solutions for these problems using WireGuard under the hood (like Tailscale or AltheaNet).

List of Other VPN Solutions

WireGuard
IPSec (IKEv2)/strongSwan: in my experience, there was lots of brittle config that was different for each OS, the NAT busting setup is very manual and involves updating the central server and starting all the others in the correct order, it wasn't great at becoming stable again after network downtime, had to be manually restarted often. your mileage may vary.
OpenVPN: can work over UDP or be disguised as HTTPS traffic over TCP
StealthVPN: haven't tried it, should I?
DsVPN: I think it does TCP-over-TCP which usually doesn't end well...
SoftEther (SSTP): haven't tried it yet, should I? (also does TCP-over-TCP?)
L2TP: somewhat outdated
PPTP: ancient, inflexible, insecure, doesn't solve all the requirements
SOCKS/SSH: good for proxying single-port traffic, not a full networking tunnel or VPN

Mesh VPN Solutions

TINC: haven't tried it yet, but it doesn't work on iOS, worst case scenario I could live
VPNCloud: similar properties to WireGuard, with more auto-mesh features
cjdns: haven't tried it yet, should I?
ZeroTier: haven't tried it yet, should I?
MeshBird: "Cloud native" VPN/networking layer
Yggdrasil Network: Yggdrasil is a self-arranging IPv4/IPv6 mesh VPN (haven't tried it yet)

VPN Setup Tools

Algo WireGuard setup tool
Striesand Multi-protocol setup tool
IKEv2-setup IKEv2 server setup script
WireGuard-Manager WireGuard setup tool, all in one

WireGuard Documentation

Glossary

Example Strings

These are demo hostnames, domain names, IP addresses, and ranges used in the documentation and example configs. Replace them with your preferred values when doing your own setup.

Example domain: example-vpn.dev can be replaced with any publicly accessible domain you control
Example hostnames: public-server1, public-server2, home-server, laptop, phone can be changed to your device hostnames
IP addresses & ranges: 192.0.2.1/24, 192.0.2.3, 192.0.2.3/32, 2001:DB8::/64 can be replaced with your preferred subnets and addresses (e.g. 192.168.5.1/24)

Wherever you see these strings below, they're just being used as placeholder values to illustrate an example and have no special meaning.

Make sure to change the IP addresses in your configs! The blocks used in these docs are reserved for example purposes by the IETF and should never be used in real network setups.

192.0.2.0/24 (TEST-NET-1) IPv4 example range RFC5737
2001:DB8::/32 IPv6 example range RFC3849

You can use any private range you want for your own setups, e.g. 10.0.44.0/24, just make sure they don't conflict with any of the LAN subnet ranges your peers are on.

Peer/Node/Device

A host that connects to the VPN and registers a VPN subnet address such as 192.0.2.3 for itself. It can also optionally route traffic for more than its own address(es) by specifying subnet ranges in comma-separated CIDR notation.

Bounce Server

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)

Subnet

A group of IPs separate from the public internet, e.g. 192.0.2.1-255 or 192.168.1.1/24. Generally behind a NAT provided by a router, e.g. in office internet LAN or a home Wi-Fi network.

CIDR Notation

A way of defining a subnet and its size with a "mask", a smaller mask = more address bits usable by the subnet & more IPs in the range. Most common ones:

192.0.2.1/32 (a single IP address, 192.0.2.1) netmask = 255.255.255.255
192.0.2.1/24 (255 IPs from 192.0.2.0-192.0.2.255) netmask = 255.255.255.0
192.0.2.1/16 (65,536 IPs from 192.0.0.0 - 192.0.255.255) netmask = 255.255.0.0
192.0.2.1/8 (16,777,216 IPs from 192.0.0.0 - 192.255.255.255) netmask = 255.0.0.0
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

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.

NAT

A subnet with private IPs provided by a router standing in front of them doing Network Address Translation, individual nodes are not publicly accessible from the internet, instead the router keeps track of outgoing connections and forwards responses to the correct internal IP (e.g. standard office networks, home Wi-Fi networks, free public Wi-Fi networks, etc)

Public Endpoint

The publicly accessible address:port for a node, e.g. 123.124.125.126:1234 or some.domain.tld:1234 (must be accessible via the public internet, generally can't be a private IP like 192.0.2.1 or 192.168.1.1 unless it's directly accessible using that address by other peers on the same subnet).

Private key

A WireGuard private key for a single node, generated with: wg genkey > example.key (never leaves the node it's generated on)

Public key

A WireGuard public key for a single node, generated with: wg pubkey < example.key > example.key.pub (shared with other peers)

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