Hacker News Reader

Comment by StavrosK | Hacker News Reader

I started using Wireguard two days ago to access my home LAN and love it, I can access everything with one command, as if I'm home. The only problem I have with it is the complete lack of documentation. The tutorial refers to a configuration file, but nowhere on the site does it tell you how to write one.

It also took me days to set up what I think is a common use case, logging in to a server/router at home and accessing the rest of the computers in the LAN. I I couldn't find how to forward/masquerade traffic, and it took some help from the good people at #linux to get it set up. I think it would be a great help if they had a configuration file on their site detailing how to set that up.

Lacking that, I'll write an article with my config so the info is at least out there, but I believe Wireguard is held back by its lack of documentation.

View on HN

> but I believe Wireguard is held back by its lack of documentation.

Indeed having good documentation is super important. I'm not so arrogant as to proclaim, "I don't have time to write docs! Understand it yourself!", but I am stretched super thin, and I suspect that often times documentation from somebody who _isn't_ the creator winds up being a bit better, because exterior perspectives are useful. So it's my hope that somebody can chip in and help out writing tutorials and docs and walkthroughs and whatnot. We really do need it.

From the sound of your message, though, I wonder if maybe you haven't found the man pages (primary documentation source):

https://git.zx2c4.com/WireGuard/about/src/tools/man/wg.8

https://git.zx2c4.com/WireGuard/about/src/tools/man/wg-quick...

I had, indeed, not found the man pages, thank you. I also intend to write up how to deploy Wireguard with a simple "access the home LAN from the outside" configuration in the next few days, which will hopefully be useful to people.

Please do! And can you come back to this thread and let us know?

I'll make a new post here, I'm guessing a few people will want to know.

Yes, we'd all love to see it when you're done.

If you don't want to wait, I posted the configuration in a sibling comment. It's pretty much that, along with some more details on how to add it and run it.

If you want to document "How I access my home network remotely" but you're really spending a few paragraphs repeating the wireguard docs before moving on to other things like your choice of IPs, your logging setup, how to retrieve mail, how to ssh places, and stuff like that, please realize that none of that other stuff has anything to do with wireguard. You could just as easily be documenting those things with an OpenVPN or IPsec vpn or even an unencrypted tunnel. That's why those things are not in the wireguard docs.

If there's something that involves wireguard itself that's missing from or unclear in the docs, could you please clarify?

> none of that other stuff has anything to do with wireguard

Sure, none of it is specific to Wireguard, but my personal use case was "hey, Wireguard looks cool, maybe I could use it to access my home LAN when I'm away. Hmm, how do I talk to the other machines from the VPN server?".

It's like saying "if you want to bake a cake, none of the baking has anything to do with our flour". You're technically right, but it'll benefit you to put a recipe on the box.

"How do I talk to the other machines from the vpn server"

The same way you would if everything on your side of the VPN tunnel was on the other side of the VPN tunnel, there was no VPN, and the VPN server was just a router joining the two subnets.

"I don't know how to do that, oh well, too bad, Wireguard would have been nice"

I agree. I've been using Wireguard for about 6 months now. The quick start is great for getting a quick overview but it doesn't really document properly how a configuration file should be made.

There is no real detail about how a wg-quick config differs from a wg one, and they're not compatible; it'll complain about unknown keys/values or something if you use a wg-quick config with extra firewall rules and the like with plain wg.

I also saw nothing anywhere about how if you modify your config file and down/up with wg-quick it'll delete anything you entered in your config as the 'down' will write back the current state of the interface. It's not a big deal, but it messes with the usual workflow of editing the config file of a service (you don't want to down it while updating your config, which could take time).

otherwise, wg has been great, it is generally quite reliable on Android but I'd like to see an easier way of doing the exclusions, inverse CIDRs are not my forte.

> it'll complain about unknown keys/values or something if you use a wg-quick config with extra firewall rules and the like with plain wg.

Really? I didn't even know that, thanks.

> if you modify your config file and down/up with wg-quick it'll delete anything you entered in your config

Ouch. Yeah, these things definitely need to be documented, I had no idea about this either. I would also like to see an easier way to configure authentications, having them in the same file as the config means I can't version control it, share it easily, etc.

> I would also like to see an easier way to configure authentications

Agreed. I like the way home assistant does it with a secrets.yml and you refer to your secrets by !secret <name of secret>

> I would also like to see an easier way to configure authentications, having them in the same file as the config means I can't version control it, share it easily, etc.

The config file is designed to be very straightforward and contain only the bare minimum required configuration stanzas. If you want to separate the keys, or use a higher level key negotiation protocol (e.g. TLS), you can write your own script that calls the lower level "wg" command instead of "wg-quick". Alternatively, you can write a script that generates a wg-quick configuration file.

Exactly this. WireGuard and wg(8) are meant as building blocks. For example, the wg-quick(8) tool is a simple bash script I built out of wg(8) and ip(8) that mostly works for my use cases and those of some other folks. But if you want something more complicated, then it's supposed to be easy to build that out of the building blocks presented.

What I am wondering is why they chose 25519.

It would seem to me that offering NTRU Prime or one of the other NIST finalists would be a prudent future protection.

https://csrc.nist.gov/Projects/Post-Quantum-Cryptography/Rou...

Doing DH with Curve25519 is a broadly understood conventional public key based key agreement scheme. We have good reason to think these are an excellent, fast, secure way to do things, unless your adversary has a working large Quantum Computer so that they can use Shor's algorithm.

NTRU Prime is for a post-quantum KEM. This does, yes, solve the same piece of the puzzle in a sense. But it's essentially one enormous experiment. Huge breakthroughs in cryptanalysis for this stuff happen all the time, by next week you might believe NTRU Prime is a joke and nobody should ever have used that, which makes requiring it at the core of a new "secure" service in Linux seem like maybe a bad idea. Bernstein and co. caution, in their submission of NTRU itself, that "the security of lattice-based cryptography is not well understood. There are serious risks of further advances".

The docs do say: "Finally, WireGuard is cryptographically opinionated. It intentionally lacks cipher and protocol agility. If holes are found in the underlying primitives, all endpoints will be required to update."

ECDH 25519 will fall like a house of cards to a capable quantum computer. Since Wireguard is already entirely DJB, the introduction of a tiny bit of agility with one of Bernstein's submissions (Classic McEliece, NTRU Prime, Post-quantum RSA-Encryption/Signature, and SPHINCS+) seems far from unreasonable.

On the other hand, I'm on Oracle Linux, so I get a new kernel about once a week anyway. Swapping out might not be that traumatic for me, since I can ksplice it into critical systems.

Android, however, cannot do that.

p.s. ...after further reading, Wireguard does have optional, pre-shared symmetric keys. This isn't an ideal solution, but it's something anyway.

"In order to mitigate any future advances in quantum computing, WireGuard also supports a mode in which any pair of peers might additionally pre-share a single 256-bit symmetric encryption key between themselves, in order to add an additional layer of symmetric encryption."

If you believe that demanding agility is "far from unreasonable" I strongly recommend taking that line rather than insisting people should use relatively untried shiny new toys out of fear of a monster that may not actually be under their beds.

I don't know that WireGuard's author will agree, but you at least have a coherent argument that makes sense. Replacing 25519 with NTRU because you're terrified of a bogeyman (in the form of Quantum Computers able to run an algorithm that solves the appropriate hard problem) doesn't make sense.

I never said "instead of," although I can see in hindsight why it might be seen that way. I should have been more clear.

Wireguard could have used P521 and AES-GCM with similar security, but it would be slower and equally vulnerable.

You can use WireGuard with rather expensive but conservative PQ primitives like Classic McEliece using the PSK feature of WireGuard, giving you hybrid PQ secrecy. The PSK feature was explicitly designed for this. The idea is that first you create a normal WireGuard tunnel. Then _through it_, so that it's authenticated, maybe even over boring old TCP, you negotiate your potpourri of experimental post quantum exchanges, maybe several of them if you don't want to trust a first round NIST submission right off the bat. Then you put the resultant key from this into WireGuard's PSK slot, and voila, now you have post quantum forward secrecy.

The Noise protocol framework (on which WireGuard is based) is now looking into doing PQ authentication, so that will be interesting. But until we actually have a clue which PQ primitives to use and have spent some time working out PQ handshakes, I think it's best to keep this all separate and ad-hoc, making it possible with the simple PSK feature.

Does this hold up though?

The PQ algorithms are only adding anything in scenarios where real adversaries can run quantum algorithms to break public key crypto. In those scenarios you don't have worthwhile authentication in WireGuard itself because your adversary broke that with their quantum computer.

The claim of "forward secrecy" seems particularly dubious when resorting to PSKs. Forward secrecy relies upon keys being ephemeral. The PSKs a TLS 1.3 web server remembers for minutes or hours automatically to support fast session resumption maybe count; some semi-detached manual PQ key agreement procedure sounds like it'll get done once and then left in place, no forward secrecy there.

> I also saw nothing anywhere about how if you modify your config file and down/up with wg-quick it'll delete anything you entered in your config as the 'down' will write back the current state of the interface. It's not a big deal, but it messes with the usual workflow of editing the config file of a service (you don't want to down it while updating your config, which could take time).

`down` only writes the state of the interface if you put SaveConfig = true in your configuration file. If so... you asked for it.

> I'd like to see an easier way of doing the exclusions, inverse CIDRs are not my forte

WireGuard uses the standard Linux routing infrastructure. wg-quick uses the powerful Linux policy routing functions along with the suppress_prefixlength policy routing rule in order to use your main routing table for exclusions. Therefore, the command to exclude an IP is simply "ip route add 10.0.1.0/24 via 10.0.0.1 dev eth0". Obviously you should replace the example subnets and interface, and this is not permanent. The beauty of wg-quick is that you don't need to add this rule every time you bring up your VPN, but can instead add it as a temporarily redundant static route.

> `down` only writes the state of the interface if you put SaveConfig = true in your configuration file. If so... you asked for it.

Nope, it's not in my config file. I didn't even know the option existed until you mentioned it, again, nothing on the Quick Start about it.

> WireGuard uses the standard Linux routing infrastructure...

I meant more in terms of the Android app, not really a WG issue, but it has a check box to add exclusions to the allowed ip list, by basically adding ranges inverse to what you'd input if you were saying "exclude these".

What's the inverse of 192.168.0.0/16? I have no idea without looking it up.

> I meant more in terms of the Android app, not really a WG issue, but it has a check box to add exclusions to the allowed ip list, by basically adding ranges inverse to what you'd input if you were saying "exclude these".

The Android app now has a little checkbox to toggle a common set complement operation ("Exclude private IPs"). If you want to do something wild and include or exclude very particular ranges, then you can compute that yourself and put it in there, since ostensibly you have a very particular networking idea in mind.

No. Only if you've explicitly chosen to add "SaveConfig = true" to the config file, which by default is not there.

I've been using wg for over a year now and never had any difficulty finding documentation.

`man wg` works just fine as does `man wg-quick`

https://www.wireguard.com/quickstart/ also shows you how to make a config file

The problem is that a regular user [some of them] can follow documentation, set up a server and a client, use wg to connect them and may be even ping the connection. That's it, congratulations.

How is this connection can be used? Which IPs should be used to establish a useful connection? How can a user see their LAN resources through it? How can a user route his web browsing through this connection (here we at least have wg-quick)? And so on.

This information is lacking, and WG documentation is not the sole offender.

That's the thing with a vpn - it is just a single component of a fully setup network. The vpn documentation generally just covers how to setup the vpn connection. The routing and rest of the network setup, as per the questions you are asking, generally falls out of its domain and into general networks.. which is quite a huge area!

this is a very good point.

Also, from a network design perspective, the difference between a tunnel, GRE interface or VPN is nonexistant. They all accomplish the same objective with different technical methods.

This is certainly not true. Tunneling and VPN protocols have distinct characteristics and capabilities which greatly affect network design. The reason for this is that they are not all designed to accomplish the same objective.

Only if you're using the ridiculous IPsec protocol and its ridiculous modes. Nobody actually needs a mode that authenticates the header but doesn't encrypt it, and nobody can understand this mode anyways. Nobody needs ECB or 3DES or any of the other zillions of IPsec methods. The great thing about WireGuard is that it removes all the crap and has one mode: Fast and Secure.

The slightly dated TLS 1.3 talk from Rescorla talks about this briefly, this is not a situation with easy answers and the approach taken in WG, which is also the approach in TLS 1.3, may yet turn out to be a bad idea. In TLS 1.3 they have left themselves a fire exit they can run out of, hair ablaze, but it's not clear to me whether WG has a way out.

From an API point of view, "Fast and secure" sounds pretty good. It maybe infantalizes the Software Engineer, which we're not really ready for yet‡, but we get more ready all the time, so I'll let that go. It's certainly better than "No real security unless you're an expert" which was historically what such APIs tend to offer.

On the implementation side "fast and secure" is just a wish, not a fact. Individual elements, picked for being "fast and secure" may turn out not to be as fast as we'd like on tomorrow's hardware, or they may not turn to be as "secure" as we'd have liked. IPsec's Chinese Menu approach lets the software engineer pick something else, but WG's approach doesn't permit this. So, the entire protocol must perhaps be re-designed.

‡ Twenty years ago, we had no good "This just works" answers for a great many things software engineers expect from cryptography. Today we have good answers for many of them, e.g. AEAD modes for block ciphers do roughly what a non-expert software engineer foolishly thought the encryption did anyway. But for others we're still in the dark. Padding for example. For privacy we should pad lengths to hide the true nature of the data being transferred. But... how much should we pad? Today our answer is that hopefully the software engineer using the API knows. In almost all cases they do not.

That's an OK point, but when half the comments on this thread are "I had to mess around for days to work out the config" then surely some common use cases can be covered by general FAQ's, like every other VPN/networking technology provides?

After that point it works exactly like any other network connection. I'm not sure what you feel needs to be documented here.

Common use cases. People will hear about WireGuard the new OpenVPN, and they'll want to "just set up a quick VPN" with it, to "hide their IP address" or whatever.

Of course it's up to WG to decide if they want to deal with this kind of community education/outreach.

FWIW Openvpn did just fine without doing that.

I actually gave up after trying for a while. They mention an "easy" way to do traditional VPN usage, but it never worked, and various blogs have differing opinions on how to properly do that.

I wish there was better hands-on documentation for WG, but I guess it really is an addition to iptables and thus restricted to people versed in that area. Which I am not.

I do intend to try again though.

Here you go, plug and play:

https://www.pastery.net/gvfyub+hacbne/#gvfyub

Use with `wg-quick up <configfile.conf>` and you're done. I don't know why this isn't in the documentation, it strikes me as what 99% of users want, and the other 1% knows how to do whatever they need.

Adding the masquerade rules and forward rules as an example in the wg-quick(8) man page sounds like a good idea. Want to send a patch to the mailing list?

Err, sure, I'll have to figure out how to do that first, though. I'm assuming I can't make a pull request somewhere?

It's even easier than that:

    $ git commit -s -m "man: add example for bla bla bla"
    $ git send-email --to=wireguard@lists.zx2c4.com HEAD~

And that's it!

This is also, by the way, how submissions to the kernel itself work, so if you're ever interested in doing that and want to get used to the process in a smaller environment, this could be a place to learn.

Oh huh, cool, I'll get to that shortly, thanks!

Thank you, I will try that

can wireguard be run from different namespaces so that only certain applications are tunneled through the wg0 interface?

We have a guide [1] up on using Wireguard and go into some detail on the configuration and how it works. But we mainly use it to build container networks.

[1] https://www.flockport.com/guides/build-wireguard-networks.ht...

The lack of a forum for discussion is also a problem. (Or maybe I'm just spoiled by github.)

There is one feature that I want that should be trivial to add that I don't know how to voice it. There is an AllowIPs config directive, but not an ExcludeIPs directive.

There's the mailing list: https://lists.zx2c4.com/mailman/listinfo/wireguard

And there's the IRC channel: #wireguard on Freenode

And in both of these there is quite a bit of discussion.

> There is an AllowIPs config directive, but not an ExcludeIPs directive.

I think you're mostly just tripped up by the naming here. Everything is excluded by default. Add things to AllowedIPs to have packets sent to those IP get encrypted for that peer.

Like I said, spoiled by github. I need to get back into IRC. Never felt comfortable on mailing lists.

I want everything included except my local LAN. I can probably do something stupid to generate a config that works (i.e., such that I manually include 0.0.0.0/8, 1.0.0.0/8, ... etc excluding 192.168.0.0/16) or do something smart outside of wg/wg-quick, but I lack the expertise.

I assume this is what you want? https://wiki.archlinux.org/index.php/WireGuard#Setup_a_VPN_s...

Yep, although the outbound iptables ALLOW is missing, which won't work with default DENY. Check my config in a sibling comment for the right one.

Added the line to the Arch Wiki entry. Thanks :)

Reply on news.ycombinator.com