Wireguard-docs: Setup, usage, configuration, and a full example | Hacker News Reader

Wireguard-docs: Setup, usage, configuration, and a full example

github.com

323 pointsaxiomdata31694 comments

Goddamn it, this happens literally every time I post my projects to HN :(

I posted the link myself to my repo, 0 points 14 hours later someone else posts it: 260+ points

No hate towards you axiomdata316, thanks for posting it, I'm just childishly complaining about the unfairness of fake internet points :p

Lol. I know what you mean. Congrats on all the attention you're getting however. BTW I went to your original post and gave you a point. ;-)

If anyone else wants to... https://news.ycombinator.com/item?id=20031254

Gotta say, if you just want a VPN to work now, definitely check out Algo or Streisand.

You can get a VPN running in an hour or less. Algo even supports wireguard.

I currently have two VPNs — Algo Wireguard & iVPN.

Anecdotally the wireguard VPN rocks— crazy fast in every way, including connection/disconnection.

Sometimes YouTube is slow.. I just hop on WG and it’s fast again. I’ve achieved faster downloads via WG than my bare internet connection (thanks Linode!)

However, some points to consider:

1. If you use a VPS to host your own VPN.. you don’t gain privacy. Usually your IP can (mostly) still identify you. And your VPS company will hold you accountable for your traffic eg DMCA.

2. OpenVPN never borks my resolv.conf but Wireguard often leaves my DNS resolution in a state of confusion.

My default-config Streisand server was compromised according to Vultr. Just a heads up because VPNs can’t really afford this.

Compromised due to Streisand being vulnerable or what?

Do you have further details? I mean this could be your server having SSH open and a weak root password, or it could be an exploit which hit Streisand, but we can't tell which ..

Per the sibling comments, I'd definitely like to know more detail. I rely on Streisand when in China and so if it's something to do with Streisand itself then I want to be aware of that.

Replying to myself, I accepted what Vultr had to say and killed the server. Wasn’t really worth me investigating too deeply and I took them on their word.

I did the default Streisand install with all services, and disabled password based login on the box (keys only).

It seems Streisand has some issues updating some components according to their issues board and it seems like the maintainer might have abandoned it.

Next time I’ll probably use algo instead. I just need wireshark anyways ;)

We've been working on a Windows version for the past few years, same idea - instant connection/disconnection, crazy fast, modern encryption. Uses only 10% of a single server cpu at gigabit speed. Almost finished, just adding in encryption for TCP (UDP and DNS already done). Shameless self promotion: https://www.firetrust.com/products/hideaway-secure-unlimited...

Do you mean that your product is built on wireguard?

No, it's not, it's our own implementation (except for the encryption part of course). We did a version similar to how Wireguard does it (UDP only) a few years back, but ran in to issues, so we ended up re-doing it with some different optimizations and UDP and TCP.

I managed to get StrongSwan IPSEC going in about an hour...

But then I'm looking for a configuration that allows me to route all my traffic via home from wherever I am, not a solution that allows me to route my home traffic via a third party.

Wireguard sounds interesting, and I'm going to learn more about it, but I like where I am with StrongSwan and just being able to issue a new certificate for a new device, and run with it.

"2. OpenVPN never borks my resolv.conf but Wireguard often leaves my DNS resolution in a state of confusion."

Checking the source... excerpt from src/tools/wg-quick/openbsd.bash:

   set_dns() {
   [[ ${#DNS[@]} -gt 0 ]] || return 0
   # TODO: this is a horrible way of doing it. Has OpenBSD no resolvconf?
   cmd cp /etc/resolv.conf    "/etc/resolv.conf.wg-quick-backup.$INTERFACE"
   cmd printf 'nameserver %s\n' "${DNS[@]}" >    /etc/resolv.conf
   }

We're doing something better on other platforms. But for OpenBSD I'm not entirely sure the best way. Suggestions welcome.

did you check what openvpn does? I would assume they have something at a local maximum.

I flagged the slow YouTube issues to iVPN (openvpn) previously but got palmed off by support, otherwise they offer an excellent service.

> 1. If you use a VPS to host your own VPN.. you don’t gain privacy. Usually your IP can (mostly) still identify you. And your VPS company will hold you accountable for your traffic eg DMCA.

Unfortunately, the same can be said for your VPN provider, depending on the provider. They can (and more than one does) save your name, address, billing details, as well as your source IP, and which IP and source ports you appear as after VPN translation has occurred.

Even if they don't do this, traffic analysis by the underlying network provider can de-anonymise your VPN'd traffic from your original source traffic too, and it doesn't take a genius to do this either.

For anyone wanting to get WireGuard up and running in a few minutes with zero hassle, I usually use this excellent bash script [0] as my goto.

Can be edited for DNS/subnet config, generates .conf files as needed and also handles QR code generation for adding mobile devices. Pair this with a $5 DO droplet and you're all set.

[0] https://github.com/its0x08/wg-install

I typically use Algo for this

https://github.com/trailofbits/algo

You can also integrate it into other deployment/key managements solutions by reading in config values from files/commands. I added sections to detail that here:

- https://github.com/pirate/wireguard-docs#config-shortcuts

- https://github.com/pirate/wireguard-docs#How-WireGuard-Manag...

- https://github.com/pirate/wireguard-docs#Dynamic-IP-Allocati...

My first thought is usually to check the Arch Wiki[0]. As usual, it does not disappoint.

[0]: https://wiki.archlinux.org/index.php/WireGuard

I couldn't believe you have done it.

I love the Arch wiki, used it as a reference for a lot of my setup while I was writing these docs. Also linked to it at the bottom under Further Reading.

Beware all examples in this don't cover ipv6. Should you have an ipv6 address, you are not using the vpn for most of your connections.

Sadly most Wireguard howtos don't cover ipv6.

If you give me some sample config I can add it to my howto here: https://www.stavros.io/posts/how-to-configure-wireguard/

I based my configuration on yours. You just need to add another 'Address = <IPv6>' (client and server), and add ip6tables.

The address is going to be static: I'm not aware of a way to simulate privacy extensions with Wireguard. A workaround is to assign ULAs and apply NAT.

I see, thank you. Unfortunately I don't have IPv6 on my network and don't know the IPv6 local addresses and ip6tables config, if you could give me the actual config you used I'd appreciate it, especially if it works with both IPv4 and IPv6 together.

Sure

------------------

[Interface] Address = 172.16.31.1/24 Address = 2001:__::1/64 PrivateKey = __ ListenPort = 443

[Peer] PublicKey = __ PresharedKey = __ AllowedIPs = 172.16.31.2/32, 2001:__::2/128

[Peer] PublicKey = __ PresharedKey = __ AllowedIPs = 172.16.31.3/32, 2001:__::3/128

[...]

------------------

PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE; ip6tables -A FORWARD -i %i -j ACCEPT; ip6tables -A FORWARD -o %i -j ACCEPT PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE; ip6tables -D FORWARD -i %i -j ACCEPT; ip6tables -D FORWARD -o %i -j ACCEPT

------------------

[Interface] Address = 172.16.31.2/24 Address = 2001:__::2/64 PrivateKey = __ DNS = 172.16.31.1, 2001:__::1 [Peer] PublicKey = __ PresharedKey = __ AllowedIPs = 0.0.0.0/0, ::/0 Endpoint = <server_ip>:443 PersistentKeepalive = 25

------------------

This is extremely helpful, thanks!

Author, if you're reading this: thank you.

This weekend I wrote a simple tool to manage a client/server-style Wireguard setup. It's a little less tedious than copying and pasting "wg genkey" and "wg pubkey" output as you're setting up new clients. It's not quite easy enough for someone to use without prior Wireguard setup knowledge, but if you've gotten your first client-server pair running, then you'll recognize where this tool fits into the rest of your workflow.

Hope it helps someone.

Where is the tool you build?

I'm not the person you're replying to, but I think this is what they were referring to from their github: https://github.com/sowbug/mkwgconf

Aaaaand I'm awake after a good night's sleep and far past the edit window for my original comment. Thank you for that link; yes, it's the one I meant to post. Sigh.

Thanks for this tool, I just added it to the docs:

https://github.com/pirate/wireguard-docs/commit/faaf447868a5...

>IPSec (IKEv2)/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

I don't follow, NAT traversal is integral to IKEv2 and pretty much "just works" [1]. Reconnecting after network downtime is not an issue either, with either on demand connection setup (auto=add) or pretty standard ifupdown scripts/networkmanager. I don't believe I had to restart my strongswan daemons in the past few months either...

I also disagree that config is 'brittle'. Quite to the contrary, I think strongswan with its exhaustive documentation and a complete test suite which provides configuration for every host in every scenario in the test suite is a great accomplishment and an incredibly useful resource [example: 2].

I think wireguard has a great niche to fill as OpenVPN replacement (which has a lot of issues) but some of its supposed benefits over ipsec are a bit overblown and a confluence of 'I couldn't be bothered to read the manual', failure to understand a difference between host-based and policy-based routing [3] and a pinch of hype-driven development.

[1] https://wiki.strongswan.org/projects/strongswan/wiki/NatTrav...

[2] https://www.strongswan.org/testing/testresults/ikev2/rw-cert...

[3] https://wiki.strongswan.org/projects/strongswan/wiki/Introdu...

> OpenVPN replacement (which has a lot of issues)

Care to elaborate?

This. I'm using OpenVPN for ethernet bridging, which Wireguard cannot do.

Tinc would be a nice choice for this purpose.

I've done bridging over wireguard. You just set up a gretap tunnel to run over the wireguard tunnel.

A few off the top of my head: juggling packets between userspace and kernel resulting in poor performance, tacked-on hacky features (hmac authentication), fragmented and often outdated documentation (the community wiki is a mess), homebrew key generation helper tools with hardcoded openssl versions, no native support on Windows/MacOS, autostart services on Windows are a mess (OpenVPNService, OpenVPNServiceInteractive, OpenVPNServiceLegacy), faffing about with socket buffer sizes on windows to get any sort of throughput and so on...

I don't know where you got your information...but you can achieve wire speed with OpenVPN over a 1gb link. If I had a bigger pipe, then I could run a bigger test, and expect the same results. The rest of your points fall under "it's not easy for average users" - which I agree with.

That depends on how much horsepower you have on both ends. I run my vpn off of a cheap cloud vps, which does the job, but doesn't have a lot of cpu power. I probably tripled my speed from openvpn to wireguard, all though both fail to max out my internet connection.

I ran IKEv2 2-3 VPNs for multiple years with a few dozen users, I have to say from experience I disagree with you there (I'm the author of the repo, @pirate). For various reasons, StrongSwan required manual intervention much more frequently than WireGuard has for far. Often I'd have to manually restart the service, or adding a new host would break stuff for all the others. The minimal config required to match my current WireGuard config was about 3x the number of lines, which meant 3x the number of things that could break each time I added a host. Even if it's better documented, that surface area is painful to deal with from a Sysadmin perspective when all I want is something that just works.

Initial setup for IKEv2 is convoluted at best, but once it’s setup there are very few problems with it.

I (used to) run L2TP/IPSec and WireGuard on my Edgerouter 4, and both would give “acceptable” speeds (30-40 MBit on a 300/300 connection), but when recreating my firewall in PfSense, I went full IKEv2, and have not regretted it. With my SG-3100 I get ~100 MBit with IKEv2.

On thing I hated about WireGuard is the fact that all clients require configuration on the server.

I do still run it on one of my servers, as a client to Mullvad VPN, which in turn is used by a few docker containers. It could easily be replaced by IKEv2, but sadly most VPN providers only support OpenVPN and WireGuard, or have horrible speeds.

> ZeroTier: haven't tried it yet, sould I?

Yes. If connectivity to clients behind NAT is important and you don't want to waste effort creating a 'bounce off' server.

ZeroTier makes it really easy to setup a private VPN with minimal config. The real value add with it is the work that's done regarding hole punching and if you have a carrier grade NAT that is tough to get through, it will relay your traffic (albeit at a throttled speed) which can be a great time saver.

The other thing is their online 'Central' where you can add/remove devices, assign IP addresses, set flow rules and more. I really like their service and the best part of it compared to my WireGuard server is I don't have to worry about downtime due to some problem with my server.

I looked a bit into Wireguard.

But it seems it's only really useful with static IPs.

Say my "Server" is behind a DDns Hostname and i want to connect to it from my Phone.

So my problem is. I allow incoming from 0.0.0.0 but on my mobile the DDns Hostname gets compiled to a specific IP.

OpenVpn has no problem with this setup. Is it solvable with Wireguard?

wg-dynamic seems to tackle this but wasn't really ready last time i checked

On Android the problem is the same. The Client only resolves the IP once. When the server gets a new ip, no connections can be made, although the client seem to be still connected.

Wireguard comes with an example script [1] that does DNS updates for peers, which works well for me in a cron job. Archwiki also has an example for systemd timers [2]. But if your question is specifically about phones, then this might get a bit more complicated to set up.

[1] https://git.zx2c4.com/WireGuard/tree/contrib/examples/rereso...

[2] https://wiki.archlinux.org/index.php/WireGuard#Endpoint_with...

I added a section on Dynamic IPs to the docs here:

https://github.com/pirate/wireguard-docs#Dynamic-IP-Allocati...

I wish there was good documentation/a tutorial which shows one how to use systemd-networkd and nftables to manage wireguard interfaces. The Arch Wiki has some documentation[0], but I've never been able to get it past the initial handshake (which always succeeds) and no one on the IRC channel was able to help me out.

I don't want to ask for hand-holding, but some more comprehensive and accessible documentation might help me troubleshoot it better.

[0] https://wiki.archlinux.org/index.php/WireGuard#Using_systemd...

If you want to enable forwarding then set the sysctl [0] and masquerade [1]. nftables also has a `log` rule which might be useful for debugging.

If you can't even connect to services on the peer then first delete all iptables and nftables rules and try again.

[0] https://wiki.archlinux.org/index.php/WireGuard#Server

[1] https://wiki.archlinux.org/index.php/Nftables#Masquerading

Thank you, kind stranger! I know what tomorrow's project is going to be!

This is really good. I hope the author considered getting this pushed upstream.

If the author hasn't reached out, @zx2c4 will probably see this post. He's pretty active on wireguard-related HN posts.

I've already emailed him to discuss it :)

Use this as a permanent VPN on my phone to my home. It only forwards requests in the 192.168.1.0/24 range and that includes all DNS requests that go to my pihole. All regular traffic is unaffected as my upload at home is slower than my 4G download speed and I don't want to limit it.

Can recommend this setup to everyone, especially on devices with spotty connections like a phone.

That's awesome! My suggestions:

* I'd include this research paper. It's the "first mechanised cryptographic proof of WG protocol" : https://hal.inria.fr/hal-02100345/document

Self-plug right here. There are a ton of bash scripts to install and configure WireGuard. Here's mine: https://github.com/SirToffski/WireGuard-Ligase/

It will configure server and clients independent of the OS it's running at. Steps to install WG are provided in the Wiki. On Ubuntu server with pre-installed WG, the quick setup option will make a ready to use server. You can quickly edit the variables to change things up.

Cheers!

Looks like a great write up, very thorough. I wrote up a quick guide how to make the mobile setup a little easier with QR codes within the WireGuard mobile apps - when I get the time I’ll submit a pull request to get something included. https://grh.am/2018/wireguard-setup-guide-for-ios/

Thanks! Just added this link under the Further Reading section.

Wireguard is a great solution for a secure, high-performance data pipe. However, it only supports layer 3 static routing by itself, which by itself fits none of my typical use cases.

If you're willing to think of it as a secure control plane where the cryptographic identities of peers are mapped to IP addresses, you can run other tried-and-tested but insecure tunnels over it.

Thanks for the docs, very helpful! I'm following Wireguard project and trying to gather all the bits sometimes takes time.

I'm also making a simple program for myself and friend that is able to talk to hosting providers via API, spawn a vps and just installs prebuild image with Wireguard, Pihole and Cloudflared installed and configured + UI to add / remove clients.

This looks like a very comprehensive guide with lots of practical examples. Good job!

What I cannot see explicitly mentioned anywhere, is a full example of how to set up a central wireguard server which routes client traffic from the VPN subnet out to the Internet.

Is this done automatically/implicitly? If so how? I don’t see enough commands to make this happen.

Am I just stupid? What am I missing?

Just add `,0.0.0.0/0` to AllowedIPs on the central server, and `,0.0.0.0/0` on the peer definition for the central server on all the clients.

I'll add an example to the docs as well.

Added here: https://github.com/pirate/wireguard-docs#Forwarding-All-Traf...

This is great, but if you want something with a web-frontend for creating users, Veeam has a nice free tool for that.

https://www.veeam.com/powered-network.html

Superb, just what I was looking for. The official documentation really is spartan.

I've been waiting for UDP support/tunnelling for so long that it makes me think about writing my it on my own.

I'd like a tutorial on getting wireguard running with systemd for debian/ubuntu based systems!

Is wireguard also able to reach 1gbps on Windows? (Windows performance was my main beef with OpenVPN).

Can wireguard be run in docker?

Check out https://github.com/subspacecloud/subspace

The wireguard kernel implementation can't but AFAIK you should be able to run a userspace implementation like the rust version just fine.

The Rust implementation is very incomplete, I believe you'll have better luck with the Go userspace implementation.

Yes, though you need to pass Docker's `--privileged` and `--cap-add=all` args to enable the loading of the kernel module.

I added a section with some more resources on containerization:

https://github.com/pirate/wireguard-docs#containerization

I'm using it with mullvad, works great on desktop and iOS.

It's seriously weird that `Address=10.0.1.2/32` works at all. An Address should have a correct subnet mask (like your IP at home might be 192.168.1.25/24, not 192.168.1.25/32).

The documentation is complete, but I think the most important topic is `AllowedIPs`. The rest is pretty standard and unsurprising (if you have any networking knowledge at all). I had written a bit about AllowedIPs when I switched to WG myself: https://try.popho.be/wg.html , with examples too.

You're specifying subnets that are reachable rather than _specific IPs_.

You're aware that /32 is the correct way of specifying one, single IPv4 address using this notation?

There is nothing weird about it at all.

If you've used IPv6 you'll see the equivalent /128 for a single address.

Try setting 192.168.1.25/32 on your eth0 interface, you're in for a bad time.

You're correct, but you're confusing the notation and the implementation.

On your (eth0) network interface you're specifying a network that your interface belongs to, its used to determine routing on that interface, if you give it a single /32, there is no "network" for it to route to.

WireGuard isn't using the CIDR notation in the address value for routing, it's using allowed-ips.

2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000

    inet 192.168.101.12/24 brd 192.168.101.255 scope global eth0
       valid_lft forever preferred_lft forever
    inet 192.168.1.25/32 scope global eth0
       valid_lft forever preferred_lft forever
    inet 192.168.1.32/31 scope global eth0
       valid_lft forever preferred_lft forever

Seems to work fine, added a /31 just for fun.

if you remove the /24 you'll have a nice surprise

Not really a surprise. The point is that it is a completely valid address to use, and in this case it just defines a range. /32 are commonly used in routers (even servers in some cases) and /31 for linknets.

I just added a section to clarify this common confusion under the CIDR entry in the glossary:

https://github.com/pirate/wireguard-docs#CIDR-Notation

Could Wireguard have been written in Rust or does it require C for some reason? We've seen CVEs in major libraries (e.g. openssl) and some of the guarantees Rust provides would prevent certain classes of vulnerabilities.

Has the author not learnt from the past or does it actually need to be written in C for some reason?

You don't seem to have spent a single minute researching before posting :/

The original implementation is a kernel module. You can find a bunch of (excellent) talks online by wireguard's author which all have a focus on security aspects and avoiding vulnerabilities. Besides, Go and Rust (3rd pty) implementations exist.

> You don't seem to have spent a single minute researching before posting

Correct. This is a discussion site after all.

> The original implementation is a kernel module

How does that make it safer if it's written in C? Of course no one likes to think they're writing vulnerable code...

If you want a module to be accepted in to the Linux kernel upstream, then you have to comply with the kernel's rules.

The kernel uses various C macros and GCC extensions. Ensuring that a module written in another language was compatible, even given that it would need to be built outside the normal tree would make its maintenance within the kernel tree impossible.

In terms of being written in C++/Rust/whatever, as an external module that complies with the kernel ABI (not guaranteed between kernel releases), go for it.

But if you want to have your protocol/module in the standard kernel tree, C is your choice.

> the kernel ABI (not guaranteed between kernel releases)

Even within a single release, the kernel ABI varies depending on several kernel configuration options (for instance, CONFIG_SMP).

Don't hate on people who ask easy questions ;)

I have a short post about it here:

https://docs.sweeting.me/s/ask-stupid-questions

WireGuard has already been re-written in rust by CloudFlare, see https://blog.cloudflare.com/boringtun-userspace-wireguard-ru...

The C version is still faster because it's a kernel module.

I've added more details about competing implementations here:

https://github.com/pirate/wireguard-docs#Other-WireGuard-Imp...

Reply on news.ycombinator.com