Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix typos #9

Merged
merged 1 commit into from
May 30, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Nicer HTML page version: https://docs.sweeting.me/s/wireguard

[WireGuard](https://www.wireguard.com/) is a BETA/WIP open-source VPN solution written in C by [Jason Donenfeld](https://www.jasondonenfeld.com) and [others](https://github.com/WireGuard/WireGuard/graphs/contributors), 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](https://www.tinc-vpn.org/) and [MeshBird](https://github.com/meshbird/meshbird), namely good cipher suites and minimal config.

This is my attempt at writing "The Missing Wireguard Documentation" to make up for the somewhat sparse offical docs on an otherwise great piece of software.
This is my attempt at writing "The Missing Wireguard Documentation" to make up for the somewhat sparse official docs on an otherwise great piece of software.

**Official Links**

Expand Down Expand Up @@ -152,14 +152,14 @@ Over the last 8+ years I've tried a wide range of VPN solutions. Somewhat out o
- minimal config, low config surface area and few exposed tunables
- minimal key management overhead, 1 or 2 preshared keys or certs is ok, but ideally not both
- ability to easily create a LAN like 10.0.0.0/24 between all my servers, every peer can connect to every peer,
- ability to bust through NATs with a signalling server, routing nat-to-nat instead of through a relay (webrtc style)
- ability to bust through NATs with a signalling server, routing nat-to-nat instead of through a relay (WebRTC-style)
- fallback to relay server when nat-to-nat busting is unavailable or unreliable
- ability to route to a fixed list of ips/hosts with 1 keypair per host (not needed, but nice to have: ability to route arbitrary local traffic or *all* internet traffic to a given host)
- robust automatic reconnects after reboots / network downtime / NAT connection table drops
- fast (lowest possible latency and line-rate bandwidth)
- encrypted, and secure by default (not needed, nice to have: short copy-pastable key pairs)
- 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 not needed but would be nice
- ability to join the VPN from Ubuntu, FreeBSD, iOS, macOS (Windows/Android not needed but would be nice)
- not a requirement, but ideally it would support running in docker with a single container, config file, and preshared key on each server, but with a full network interface exposed to the host system (maybe with tun/tap on the host passing traffic to the container, but ideally just a single container + config file without outside dependencies)

## List of Possible VPN Solutions
Expand All @@ -168,15 +168,15 @@ Over the last 8+ years I've tried a wide range of VPN solutions. Somewhat out o
- L2TP: meh
- SOCKS: proxy tunnel, not a VPN, not great for this use case
- [IPSec (IKEv2)](https://github.com/jawj/IKEv2-setup)/strongSwan: lots of brittle config that's different for each OS, NAT busting setup is very manual and involves updating the central server and starting all the others in the correct order, not great at reconnecting after network downtime, had to be manually restarted often
- [TINC](https://www.tinc-vpn.org/): haven't tried it yet, but it doesn't work on iOS, worst case senario I could live with that if it's the only option
- [TINC](https://www.tinc-vpn.org/): haven't tried it yet, but it doesn't work on iOS, worst case scenario I could live with that if it's the only option
- [OpenVPN](https://openvpn.net/vpn-server-resources/site-to-site-routing-explained-in-detail/): I don't like it from past experience but could be convinced if it's the only option
- StealthVPN: haven't tried it
- [MeshBird](https://github.com/meshbird/meshbird): "Cloud native" VPN/networking layer
- [Algo](https://github.com/trailofbits/algo): haven't tried it yet, should I?
- [Striesand](https://github.com/StreisandEffect/streisand): haven't tried it yet, whats the best config to try?
- [Striesand](https://github.com/StreisandEffect/streisand): haven't tried it yet, what's the best config to try?
- [SoftEther](https://www.softether.org/): haven't tried it yet, should I?
- [WireGuard](https://www.wireguard.com/): the subject of this post
- [ZeroTier](https://www.zerotier.com): haven't tried it yet, sould I?
- [ZeroTier](https://www.zerotier.com): haven't tried it yet, should I?

---

Expand All @@ -188,7 +188,7 @@ Over the last 8+ years I've tried a wide range of VPN solutions. Somewhat out o

### Peer/Node/Device

A host that connects to the VPN and has registers a VPN subnet address like 10.0.0.3 for itself. It can also optionally route traffic for more than its own address(es) by specifing subnet ranges in comma-separated CIDR notation.
A host that connects to the VPN and has registers a VPN subnet address like 10.0.0.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

Expand Down Expand Up @@ -269,9 +269,9 @@ More complex topologies are definitely achievable, but these are the basic routi
I'm not sure if Wireguard supports this method yet, but it's definitely possible in theory, see: [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API), [N2N](https://www.ntop.org/products/n2n/), [Pwnat](https://samy.pl/pwnat/). A readily available signaling server like`public-server1` should make connection establishment and handoff relatively easy, but ICMP packet trickery can also be used. Please let me know if WireGuard does this via [Github Issue](https://github.com/pirate/wireguard-docs/issues).


Chosing the proper routing method is handled automatically by WireGuard as long as at least one server is acting as a public relay with `net.ipv4.ip_forward = 1` enabled, and clients have `AllowIPs = 10.0.0.1/24` set in the relay server `[peer]` (to take traffic for the whole subnet).
Choosing the proper routing method is handled automatically by WireGuard as long as at least one server is acting as a public relay with `net.ipv4.ip_forward = 1` enabled, and clients have `AllowIPs = 10.0.0.1/24` set in the relay server `[peer]` (to take traffic for the whole subnet).

More specific (also usually more direct) routes provided by other peers will take precedence when available, otherwise traffic will fall back to the least specific route and use the `10.0.0.1/24` catchall to forward traffic to the bounce server, where it will in turn be routed by the relay server's system routing table back down the VPN to the specific peer thats accepting routes for that traffic.
More specific (also usually more direct) routes provided by other peers will take precedence when available, otherwise traffic will fall back to the least specific route and use the `10.0.0.1/24` catchall to forward traffic to the bounce server, where it will in turn be routed by the relay server's system routing table back down the VPN to the specific peer that's accepting routes for that traffic.

You can figure out which routing method WireGuard is using for a given address by measuring the ping times to figure out the unique length of each hop, and by inspecting the output of:
```bash
Expand Down Expand Up @@ -299,7 +299,7 @@ WireGuard's performance gains are achieved by handling routing at the kernel lev
<img src="https://i.imgur.com/heEYg59.png" width="400px"/>


Futher reading:
Further reading:

- https://www.wireguard.com/performance/
- https://www.reddit.com/r/linux/comments/9bnowo/wireguard_benchmark_between_two_servers_with_10/
Expand Down Expand Up @@ -423,7 +423,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 wont work
# Note: you must specify the absolute path to wg0.conf, relative paths won't work
```

```bash
Expand Down Expand Up @@ -494,7 +494,7 @@ ip route get 10.0.0.3

#### Ping Speed
```bash
# check that main relay server is accesible directly via public internet
# check that main relay server is accessible directly via public internet
ping public-server1.example-vpn.dev

# check that the main relay server is available via VPN
Expand Down Expand Up @@ -552,7 +552,7 @@ dig example.com A

**Jump to definition:**

¶ <a href="#Interface">`[Inteface]`</a>
¶ <a href="#Interface">`[Interface]`</a>
¶ <a href="#-Name">`# Name = node1.example.tld`</a>
¶ <a href="#Address">`Address = 10.0.0.3/32`</a>
¶ <a href="#ListenPort">`ListenPort = 51820`</a>
Expand Down Expand Up @@ -602,7 +602,7 @@ This is just a standard comment in INI syntax used to help keep track of which c

#### `Address`

Defines what address range the local node should route traffic for. Depending on whether the node is a simple client joining the VPN subnet, or a bounce server that's relaying traffic between multiple clients, this can be set to a single IP of the node itself (specificed with CIDR notation), e.g. 10.0.0.3/32), or a range of IPv4/IPv6 subnets that the node can route traffic for.
Defines what address range the local node should route traffic for. Depending on whether the node is a simple client joining the VPN subnet, or a bounce server that's relaying traffic between multiple clients, this can be set to a single IP of the node itself (specified with CIDR notation), e.g. 10.0.0.3/32), or a range of IPv4/IPv6 subnets that the node can route traffic for.

**Examples**

Expand Down Expand Up @@ -845,7 +845,7 @@ When deciding how to route a packet, the system chooses the most specific route

#### `PublicKey`

This is the public key for the remote node, sharable with all peers.
This is the public key for the remote node, shareable with all peers.
All nodes must have a public key set, regardless of whether they are public bounce servers relaying traffic, or simple clients joining the VPN.

This key can be generated with `wg pubkey < example.key > example.key.pub`.
Expand Down Expand Up @@ -913,7 +913,7 @@ AllowedIPs = 0.0.0.0/0, ::/0

### Dynamic IP Allocation

Dynamic allocation of IPs (instead of only having fixed peers) is being developed, the WIP implmentation is available here:
Dynamic allocation of IPs (instead of only having fixed peers) is being developed, the WIP implementation is available here:
https://github.com/WireGuard/wg-dynamic

You can also build a dynamic allocation system yourself by reading in IP values from files at runtime by using `PostUp` (see below).
Expand Down Expand Up @@ -960,7 +960,7 @@ 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 `[Inteface]` separately on each server.
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

Expand Down Expand Up @@ -1007,7 +1007,7 @@ Setups can get somewhat complex are are highly dependent on what you're trying t

# Example Server-To-Server Config with Roaming Devices

The complete example config for the setup below can be found here: https://github.com/pirate/wireguard-docs/tree/master/full-example (WARNING: do not use it on your devices without chaning the public/private keys!).
The complete example config for the setup below can be found here: https://github.com/pirate/wireguard-docs/tree/master/full-example (WARNING: do not use it on your devices without changing the public/private keys!).

## Overview

Expand All @@ -1025,7 +1025,7 @@ These 5 devices are used in our example setup to explain how WireGuard supports

This VPN config simulates setting up a small VPN subnet `10.0.0.1/24` shared by 5 nodes. Two of the nodes (public-server1 and public-server2) are VPS instances living in a cloud somewhere, with public IPs accessible to the internet. home-server is a stationary node that lives behind a NAT with a dynamic IP, but it doesn't change frequently. Phone and laptop are both roaming nodes, that can either be at home in the same LAN as home-server, or out-and-about using public wifi or cell service to connect to the VPN.

Whenever possible, nodes should connect directly to eachother, depending on whether nodes are directly accessible or NATs are between them, traffic will route accordinly:
Whenever possible, nodes should connect directly to each other, depending on whether nodes are directly accessible or NATs are between them, traffic will route accordinly:

### The Public Relay

Expand All @@ -1039,7 +1039,7 @@ In summary: only direct connections between clients should be configured, any co

To run this full example, simply copy the `full wg0.conf config file for node` section from each node onto each server, enable IP forwarding on the public relay, and then start WireGuard on all the machines.

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-docs/tree/master/full-example (WARNING: do not use it on your devices without chaning the public/private keys!).
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-docs/tree/master/full-example (WARNING: do not use it on your devices without changing the public/private keys!).

## Node Config

Expand Down