WireGuard is a simple, fast and modern VPN implementation, widely deployed and cross-platform.
VPNs have traditionally been hard to understand, configure and deploy. WireGuard removed most of that complexity by focusing on its single task, and leaving out things like key distribution and pushed configurations. You get a network interface which encrypts and verifies the traffic, and the remaining tasks like setting up addresses, routing, etc, are left to the usual system tools like ip-route(8) and ip-address(8).
Setting up the cryptographic keys is very much similar to configuring ssh for key based authentication: each side of the connection has its own private and public key, and the peers’ public key, and this is enough to start encrypting and verifying the exchanged traffic.
For more details on how WireGuard works, and information on its availability in other platforms, please see the references section.
It helps to think of WireGuard primarly as a network interface, like any other. It will have the usual attributes, like IP address, CIDR, and there will be some routing associated with it. But it also has WireGuard specific attributes, which handle the VPN part of things.
All of this can be configured via different tools. WireGuard itself ships its own tools in the userspace package
wg-quick(8). But these are not strictly needed: any userspace with the right privileges and kernel calls can configure a WireGuard interface. For example,
network-manager can do it on their own, without the WireGuad userspace utilities.
Important attributes of a WireGuard interface are:
private key: together with the corresponding public key, they are used to authenticate and encrypt data. This is generated with the
- listen port: the UDP port that WireGuard will be listening to for incoming traffic.
- List of peers, each one with:
public key: the public counterpart of the private key. Generated from the private key of that peer, using the
- endpoint: where to send the encrypted traffic to. This is optional, but at least one of the corresponding peers must have it to bootstrap the connection.
- allowed IPs: list of inner tunnel destination networks or addresses for this peer when sending traffic, or, when receiving traffic, which source networks or addresses are allowed to send traffic to us.
- public key: the public counterpart of the private key. Generated from the private key of that peer, using the
Cryptography is not simple. When we say that, for example, a private key is used to decrypt or sign traffic, and a public key is used to encrypt or verify the authenticity of traffic, this is a simplification and is hiding a lot of important details. WireGuard has a detailed explanation of its protocols and cryptography handling in their website, at https://www.wireguard.com/protocol/
These parameters can be set with the low-level
wg(8) tool, directly via the command line or with a configuration file. This tool, however, doesn’t handle the non-WireGuard settings of the interface. It won’t assign an IP address to it, for example, nor setup routing. For this reason, it’s more common to use
wg-quick(8) will handle the lifecycle of the WireGuard interface. It can bring it up or down, setup routing, execute arbitrary commands before or after the interface is up, and more. It augments the configuration file that
wg(8) can use, with its own extra settings, which is important to keep in mind when feeding that file to
wg(8), as it will contain settings
wg(8) knows nothing about.
wg-quick(8) configuration file can have an arbitrary name, and can even be placed anywhere on the system, but the best practice is:
- Place the file in
- Name it after the interface it controls.
For example, a file called
/etc/wireguard/wg0.conf will have the needed configurations setting for a WireGuard network interface called
wg0. By following this practice, you get the benefit of being able to call
wg-quick with just the interface name:
$ sudo wg-quick up wg0
And that will bring the
wg0 interface up, give it an IP address, setup routing, and configure the WireGuard specific parameters for it to work. This interface is usually called
wg0, but can have any valid network interface name, like
office (it doesn’t need an index number after the name),
home1, etc. It can help to give it a meaningful name if you plan to connect to multiple peers.
Let’s go over an example of such a configuration file:
[Interface] PrivateKey = eJdSgoS7BZ/uWkuSREN+vhCJPPr3M3UlB3v1Su/amWk= ListenPort = 51000 Address = 10.10.11.10/24 [Peer] # office PublicKey = xeWmdxiLjgebpcItF1ouRo0ntrgFekquRJZQO+vsQVs= Endpoint = wg.example.com:51000 # fake endpoint, just an example AllowedIPs = 10.10.11.0/24, 10.10.10.0/24
Address: this is the IP address, and CIDR, that the WireGuard interface will be setup with.
ListenPort: the UDP port WireGuard will use for traffic (listening and sending).
PrivateKey: the secret key used to decrypt traffic destined to this interface.
The peers list, each one in its own
[Peer] section (example above has just one), comes next:
PublicKey: the key that will be used to encrypt traffic to this peer.
Endpoint: where to send encrypted traffic to.
AllowedIPs: when sending traffic, this is the list of target addresses that identify this peer. When receiving traffic, it’s the list of addresses that are allowed to be the source of the traffic.
To generate the keypairs for each peer, the
wg(8) command is used:
$ umask 077 $ wg genkey > wg0.key $ wg pubkey < wg0.key > wg0.pub
And then the contents of
wg0.pub can be used in the configuration file.
This is what it looks like when this interface is brought up by
$ sudo wg-quick up wg0 [#] ip link add wg0 type wireguard [#] wg setconf wg0 /dev/fd/63 [#] ip -4 address add 10.10.11.10/24 dev wg0 [#] ip link set mtu 1420 up dev wg0 [#] ip -4 route add 10.10.10.0/24 dev wg0
This is what
wg-quick(8) did for us:
- Created the WireGuard
- Configured it with the data from the configuration file.
- Added the IP/CIDR from the
Addressfield to the
- Calculated a proper MTU (which can be overridden in the config if needed)
- Added a route for
Note that in this example
AllowedIPs is a list of two CIDR network blocks, but
wg-quick(8) only added a route for
10.10.10.0/24 and skipped
10.10.11.0/24. That’s because the
Address was already specified as a
/24 one. Had we specified the address as
10.10.11.10/32 instead, then
wg-quick(8) would have added a route for
To better understand how
AllowedIPs work, let’s go through a quick example.
Let’s say this system wants to send traffic to
10.10.10.201/24. There is a route for it which says to use the
wg0 interface for that:
$ ip route get 10.10.10.201 10.10.10.201 dev wg0 src 10.10.11.10 uid 1000 cache
wg0 is a WireGuard interface, it will consult its configuration to see if any peer has that target address in the
AllowedIPs list. Turns out one peer has it, in which case the traffic will:
a) Be authenticated as us, and encrypted for that peer.
b) Sent away via the configured
Now let’s picture the reverse. This system received traffic on the
ListenPort UDP port. If it can be decrypted, and verified as having come from one of the listed peers using its respective public key, and if the source IP matches the corresponding
AllowedIPs list, then the traffic is accepted.
What if there is no
Endpoint? Well, to bootstrap the VPN, at least one of the peers must have an
Endpoint, or else it won’t know where to send the traffic to, and you will get an error saying “Destination address required” (see the troubleshooting section for details).
But once the peers know each other, the one that didn’t have an
Endpoint setting in the interface will remember where the traffic came from, and use that address as the current endpoint. This has a very nice side effect of automatically tracking the so called “road warrior” peer, which keeps changing its IP. That is very common with laptops that keep being suspended and awakened in a new network, and then try to establish the VPN again from that new address.
You will notice that the term “peers” is used preferably to “server” or “client”. Other terms used in some VPN documentation are “left” and “right”, which is already starting to convey that the difference between a “server” and a “client” is a bit blurry. It only matters, if at all, at the start of the traffic exchange: who sends the first packet of data. In that sense, “servers” expect to sit idle and wait for connections to be initiated to them, and “clients” are the initiators. For example, a laptop on a public cafe initiating a connection to the company VPN peer. The laptop needs to know the address of that peer, because it’s initiating the exchange. But the “server” doesn’t need to know the IP of the laptop beforehand.
On a site to site VPN, however, when two separate networks are connected through the tunnel, who is the server, and who is the client? Both, so it’s best to call them “peers” instead.
Putting it all together
Key takeaways from this introduction:
- Each peer participating in the WireGuard VPN has a private key and a public key.
AllowedIPsis used as a routing key when sending traffic, and as an ACL when receiving traffic.
- To establish a VPN with a remote peer, you need its public key. Likewise, the remote peer will need your public key.
- At least one of the peers needs an
Endpointconfigured in order to be able to initiate the VPN.
To help better understand these and other concepts, we will create some WireGuard VPNs in the next sections, illustrating some common setups.
Throghout this guide, we will sometimes mention a VPN “connection”. This is technically false, as WireGuard uses UDP and there is no persistent connection. The term is used just to facilitate understanding, and means that the peers in the examples know each other and have completed a handshake already.