Page MenuHomePhabricator

Wireguard: Write wiki documentation
Closed, ResolvedPublicFEATURE REQUEST

Description

document in wiki how to use wireguard.

Details

Difficulty level
Unknown (require assessment)
Version
-
Why the issue appeared?
Will be filled on close

Related Objects

hagbard created this task.Aug 12 2018, 7:53 PM
hagbard triaged this task as Normal priority.

I would like to contribute

hagbard reassigned this task from hagbard to mrjones.Aug 17 2018, 4:34 PM

Let me know if you need any help with it or have any questions.
I'm going to change the endpoint parameter to an optional parameter.
https://www.wireguard.com/#conceptual-overview may help you as well.

@hagbard wiki tells me that my post is spam, so I am unable to save at the moment. https://wiki.vyos.net/index.php?title=Wireguard

@mrjones i whitelisted you on wiki
try again

c-po renamed this task from write wiki documentation to Wireguard: Write wiki documentation.Aug 19 2018, 10:57 AM

@mrjones Thanks, it looks very good. I'm about to add a few status commands, like sh wireguard wbN status and peer status and the such, so please leave this task still open. I stopped after 2 lines of writing wiki, the annoying google captchas wasted my time, so I stopped :).

wg pubkey (generates a public key using the private key, for example: wg pubkey < "private key here")
For extra security you can also use a pre-shared key that can be generate with this command:
wg genpsk (this is optional, and the same pre-shared key should be used on both hosts)

Can you please change that, I still get catcha'ed.

You can do that within the vbash (run is only required if you are in conf mode):

<run> generate wireguard keypair = generates a new keypair, if one exists already it asks you if you want to overwrite the existing one. It is stored permanently under /config/auth/wireguard/.

<run> show show wireguard privkey - shows private key
<run> show wireguard pubkey - shows the public key

planned:
<run> show wireguard status - show status for all wg interfaces
<run> show wireguard status <wgN> - status for a specific interface
<run> show wireguard status peer [peerkey] - status for a specific peer

I also would refer to client and server, not just host.
Each can be client or server, if configured as server you have endpoint optional, but the client has to initiate the connection first, then the server gets the src IP and src port from the client and you can also send traffic from the server to the client.

Here is an example I have in my testlag:

client:
set interfaces wireguard wg01 listen-port '12345'
set interfaces wireguard wg01 peer <pubkey server> allowed-ips '10.1.0.0/24'
set interfaces wireguard wg01 peer <pubkey server> endpoint '192.168.0.115:12345'
set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01

server:
set interfaces wireguard wg01 address '10.1.0.1/24'
set interfaces wireguard wg01 listen-port '12345'
set interfaces wireguard wg01 peer <pubkey client> allowed-ips 10.0.0.0/24
set protocols static interface-route 10.0.0.0/24 next-hop-interface wg01

If you call wg directly, it will only show you the generated keys to stdout, so there is nothing stored on the system and the tunnel won't exist/work anymore after system reboot.

Can you please change that, I get google captcha'ed which wastes my time and I'm not in the mood to solve puzzles today :D.

Not completed yet, so I will not close the task.

The "Show preview" doesn't require the Captcha

I will edit it, I missed that it was already implemented,

follow up question, if there are more than one interface, how do we see the keypairs?

It does for me, I probably just need to be white listed.
Would you like to do https://phabricator.vyos.net/T759 as well?
It's syslog configuration, which I rewrote a month or so ago.

sure thing!

Thanks a lot.
The keypair is unique per host, it is used to authenticate and to decrypt the incoming traffic. So for authentication it wouldn't make much sense to deal with multiple keys.
Encryption is done via the public key, which has to come from your peer. So the traffic to a peer is always encrypted with the public key, only the one who has the private key or at least the knowledge of the content of the private key, can decrypt the message/traffic. That's at least the basic idea.
On the server side you basically receive a message encrypted with your public key, which contains the public key for authentication (see the link above and look for DH_PUBKEY(private key) in the code example). So given that, theoretically you only need to store the private key since the public key is always computed during connection initiation. But that would mean in my case, that 'show wireguard pubkey' would have to compute it as well any time you need it to send it to your peers when you create a new tunnel. (wg pubkey < your_private_key will give you the same result).
I just have a native OS api to read a file but would have to call a subprocess to call wg, that's why I store the public key in a file as well, the content is the same.

You can handle all peers on a single interface (wg01 for instance), but the interfaces are OS specific and often used for routing or if you want to have a generic iptables rule in place which matches anything on a particular interface.

yes, but if I use several interfaces, wg01, wg02, wg03, then should have the option to use a different keypair for each one of them?

in this case, the listen-port should be optional?
client:
set interfaces wireguard wg01 listen-port '12345'
set interfaces wireguard wg01 peer <pubkey server> allowed-ips '10.1.0.0/24'
set interfaces wireguard wg01 peer <pubkey server> endpoint '192.168.0.115:12345'
set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01

I also spiced things up in the wiki, but can revert, I think it might help some people to see it like this.

You want to authenticate your host, not your interfaces. Theoretically, it's possible. If you travel, you carry usually one piece of ID with your passport, to identify yourself.
The listen port is mandatory, the peer endpoint on the server side however is optional. When the client initiates (client needs peer endpoint) the connection and passes the authentication part, the server side finds the way back on the data the client has sent (basically src IP and src port, src port is the clients listen-port by the way, that's why it's mandatory).

hagbard changed the task status from Open to In progress.Aug 20 2018, 1:33 AM
syncer added a project: Restricted Project.Aug 20 2018, 2:07 PM

The following has been added:

set interfaces wireguard wg01 peer 'kl6NCcTXmGtoxLyvaNvSkKqq/q7Nb6b15eGZN9Py0Fg=' persistent-keepalive 15

The peer key needs to be in single or double quotes enclosed, I gotta check why the parser doesn't like that, I suppose the lexer contains the = sign as some kind of separator.

I've added the status commands, once https://github.com/vyos/vyos-1x/pull/39 is merged you should have them in the latest iso. Let me know if you need a preview.

I added the persistent-keepalive.

I tried now on my regular linux to not set the listen-port, but I see that wireguard picks one of the higher ports at random if it is not set. So it is better to keep this value mandatory, as you say.

Yes, send a preview, and I can add it to the wiki right away

show interfaces wireguard <tab completion> [<enter>]

allowed-ips show all allowed-ips for the specified interface
endpoints show all endpoints for the specified interface
peers show all peer IDs for the specified interface

The tab completion shows you the interface which are setup on the system, so if you have more than 1 it shows them as a list you can chose from. If you just hist enter you get a full statistic for the interface:

e.g.:
interface: wg01

public key: ABh3lEPhgjifR7eKHYxlV0gL58DZTNXqzWLteLBuK3E=
private key: (hidden)
listening port: 12345

peer: kl6NCcTXmGtoxLyvaNvSkKqq/q7Nb6b15eGZN9Py0Fg=

allowed ips: 10.200.0.0/24

The sub commands like allowed-ips shows the peer and the configured allowed-ips for it. If you have multiple peers, they show up as a list:

show interfaces wireguard wg01 allowed-ips
kl6NCcTXmGtoxLyvaNvSkKqq/q7Nb6b15eGZN9Py0Fg= 10.200.0.0/24

There is a start, I will adjust it after I can test it out myself!
Things are happening fast.
regarding the syslog documentation, I will have more time to dive into it on thursday/friday. I didn't fiddle with it myself, and I will take it as a learning moment as well.

@mrjones No prob at all, you are a great help. Thanks for your contribution.

zx2c4 added a subscriber: zx2c4.Aug 24 2018, 5:55 PM

Please let me know what I need to add to wireguard.com/install/ in relation to VyOS's support.

Hey @zx2c4 !
Available out of the box in Rolling and in future LTS releases

@mrjones Do you finish the documentation?

hagbard claimed this task.Sep 7 2018, 5:12 PM

I get an error message 'contains contacts', plus wasting my time with captchas. I'll write the documentation once that has been solved or just publish a link.

hagbard removed hagbard as the assignee of this task.Sep 9 2018, 12:04 AM

Sorry, I'm done with that crap.

Configuration

Before a VPN can be established, a [https://en.wikipedia.org/wiki/Public-key_cryptography key pair] needs to be generated, which is permanently stored under /config/auth/wireguard.
A new keypair can be always generated which will overwrite the existing one and can be done in operational mode or configuration mode.
You can have multiple interfaces (wg) and/or multiple peers on one wg interface. IPv4 and/or IPv6 IPs and networks can be used.

wg01:~$ configure
wg01# run generate wireguard keypair

The public key is being shared with your peer(s), they will encrypt all traffic to your system using this public key.

wg01#run show wireguard pubkey
u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=

The next step is to configure your local side as well as the policy based trusted destination addresses.
If you only initiate a connection, the listen port and endpoint is optional, if you however act as a server and endpoints initiate the connections to your system, you need to define one, otherwise it's randomly chosen and may make it difficult with firewall rules, since the port may be a different one when you reboot your system.
You will also need the public key of your peer as well as the network(s) you want to tunnel (allowed-ips) to configure a wireguard tunnel.
The public key below is always the public key from your peer, not the local one.

'''steps on the first peer wg01'''
set interfaces wireguard wg01 address '10.1.0.1/24'
set interfaces wireguard wg01 description 'VPN-to-wg02'
set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24'
set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.142:12345'
set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI='
set interfaces wireguard wg01 port '12345'
set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01

The last step is to define an interface route for 10.2.0.0/24 to get through the wireguard interface wg01. Multiple IPs or networks can be defined and routed, the last check is allowed-ips which either prevents or allows the traffic.
For instance if you set an interface route fir 10.2.0.0/16, only 10.2.0.0/24 will be sent out, everything else will be automatically dropped.

'''steps on the first peer wg02'''

set interfaces wireguard wg01 address '10.2.0.1/24'
set interfaces wireguard wg01 description 'VPN-to-wg01'
set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24'
set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.124:12345'
set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk='
set interfaces wireguard wg01 port '12345'
set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01

Now you have a working VPN for the destination networks defined above.

wg01# ping 10.2.0.1
PING 10.2.0.1 (10.2.0.1) 56(84) bytes of data.
64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=1.16 ms
64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=1.77 ms

wg02# ping 10.1.0.1
PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data.
64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=4.40 ms
64 bytes from 10.1.0.1: icmp_seq=2 ttl=64 time=1.02 ms

An additional layer of symmetric-key crypto can be used on top of the asymmetric crypto, which is optional.
The preshared key is '''not''' stored locally, you need to copy is and exchange it with your peer in a safe manner.

'''pre-shared key setup on both sides'''
wg01# run generate wireguard preshared-key
rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=

wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='

Maltahl added a subscriber: Maltahl.EditedOct 2 2018, 8:20 AM

@hagbard thanks for the awesome implementation of wireguard to vyos.

Later today i will begin drafting wiki for using wireguard with examples on how it work and how to do site-to-site or do access vpn to replace openvpn setups to a degree.

@syncer can you assign this to me ? i will PM a draft later today.

hagbard assigned this task to Maltahl.Oct 2 2018, 4:30 PM

Thanks a lot. Let me know if you need anything from me.

In T774#20257, @hagbard wrote:

Hang on a sec, have a look here:
https://github.com/vyos/vyos-documentation

I will fortunate im used to document stuff on wiki but it is nice to have some pointers, thanks! :)

@hagbard status so far is that i am nearly done with 3 types of setups with minor edits on existing wiki documentation for wireguard as it was not updated to match current commands :)
There is also some clearification on what each segment of the config is to avoid confusion newcomers that want to try it out.
I will add it after work today.

@syncer can you allow my profile on wiki ( same username) to post an update ?

I tried adding the wiki updates last saturday without any luck ( was not allowed to post updates )
Will post a pastebin with wiki text for review later today

Maltahl reassigned this task from Maltahl to hagbard.Oct 10 2018, 6:29 PM

Here is the pastebin since im still not allowed to post on the wiki
https://pastebin.com/sZcJLyeB

It will need some minor proof reading and maybe formatting.
i will point out that Wireguard is still broken in 1.2.0 RC2 with the mobile vpn example and site-to-site vpn after troubleshooting.

Thanks. I see if I can add it., can you please request access from @syncer?
@c-po Do you think the updates should be ported then to vyos-documentation or should the new content always be in vyos-documentation?

c-po added a comment.Oct 10 2018, 8:12 PM

vyos-documentation is still a playground but feel free to add. Always makes sense to play arround with new concepts

syncer closed this task as Resolved.