Changeset View
Standalone View
share/man/man4/wg.4
- This file was added.
.\" Copyright (c) 2020 Gordon Bergling | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||
.\" SUCH DAMAGE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd December 27, 2020 | |||||
.Dt WG 4 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm wg | |||||
.Nd "WireGuard - pseudo-device" | |||||
.Sh SYNOPSIS | |||||
To load the driver as a module at boot time, place the following line in | |||||
.Xr loader.conf 5 : | |||||
.Bd -literal -offset indent | |||||
if_wg_load="YES" | |||||
.Ed | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Nm | |||||
driver provides Virtual Private Network (VPN) interfaces for the secure | |||||
exchange of layer 3 traffic with other WireGuard peers using the WireGuard | |||||
protocol. | |||||
.Pp | |||||
A | |||||
.Nm | |||||
interface recognises one or more peers, establishes a secure tunnel with | |||||
brueffer: Here and in all other ".Nm wg" cases just .Nm is enough, since above it has been defined as… | |||||
each on demand, and tracks each peer's UDP endpoint for exchanging encrypted | |||||
traffic with. | |||||
.Pp | |||||
The interfaces can be created at runtime using the | |||||
.Ic ifconfig Cm wg Ns Ar N Cm create | |||||
command. | |||||
The interface itself can be configured with | |||||
.Xr ifconfig 8 . | |||||
.Pp | |||||
.Nm | |||||
interfaces support the following | |||||
.Xr ioctl 2 Ns s : | |||||
.Bl -tag -width Ds -offset indent | |||||
.It Dv SIOCSWG Fa "struct wg_device_io *" | |||||
Set the device configuration. | |||||
.It Dv SIOCGWG Fa "struct wg_device_io *" | |||||
Get the device configuration. | |||||
.El | |||||
.Pp | |||||
The following glossary provides a brief overview of WireGuard | |||||
terminology: | |||||
.Bl -tag -width indent -offset 3n | |||||
.It Peer | |||||
Peers exchange IPv4 or IPv6 traffic over secure tunnels. | |||||
Each | |||||
.Nm | |||||
interface may be configured to recognise one or more peers. | |||||
.It Key | |||||
Each peer uses its private key and corresponding public key to | |||||
identify itself to others. | |||||
A peer configures a | |||||
.Nm | |||||
interface with its own private key and with the public keys of its peers. | |||||
.It Pre-shared key | |||||
In addition to the public keys, each peer pair may be configured with a | |||||
Done Inline ActionsPre-shared brueffer: Pre-shared | |||||
unique pre-shared symmetric key. | |||||
This is used in their handshake to guard against future compromise of the | |||||
peers' encrypted tunnel if a quantum-computational attack on their | |||||
Diffie-Hellman exchange becomes feasible. | |||||
It is optional, but recommended. | |||||
.It Allowed IPs | |||||
A single | |||||
.Nm | |||||
interface may maintain concurrent tunnels connecting diverse networks. | |||||
The interface therefore implements rudimentary routing and reverse-path | |||||
filtering functions for its tunneled traffic. | |||||
These functions reference a set of allowed IP ranges configured against | |||||
each peer. | |||||
.Pp | |||||
The interface will route outbound tunneled traffic to the peer configured | |||||
with the most specific matching allowed IP address range, or drop it | |||||
if no such match exists. | |||||
.Pp | |||||
The interface will accept tunneled traffic only from the peer | |||||
configured with the most specific matching allowed IP address range | |||||
for the incoming traffic, or drop it if no such match exists. | |||||
That is, tunneled traffic routed to a given peer cannot return through | |||||
another peer of the same | |||||
.Nm | |||||
interface. | |||||
This ensures that peers cannot spoof another's traffic. | |||||
.It Handshake | |||||
Two peers handshake to mutually authenticate each other and to | |||||
establish a shared series of secret ephemeral encryption keys. | |||||
Any peer may initiate a handshake. | |||||
Handshakes occur only when there is traffic to send, and recur every | |||||
two minutes during transfers. | |||||
.It Connectionless | |||||
Due to the handshake behavior, there is no connected or disconnected | |||||
state. | |||||
.El | |||||
.Ss Keys | |||||
Private keys for WireGuard can be generated from any sufficiently | |||||
secure random source. | |||||
The Curve25519 keys and the pre-shared keys are both 32 bytes | |||||
long and are commonly encoded in base64 for ease of use. | |||||
Done Inline Actionspre-shared brueffer: pre-shared | |||||
.Pp | |||||
Keys can be generated with | |||||
.Xr openssl 1 | |||||
as follows: | |||||
.Pp | |||||
.Dl $ openssl rand -base64 32 | |||||
.Pp | |||||
Although a valid Curve25519 key must have 5 bits set to | |||||
specific values, this is done by the interface and so it | |||||
will accept any random 32-byte base64 string. | |||||
.Pp | |||||
When an interface has a private key set with | |||||
.Nm wgkey , | |||||
the corresponding | |||||
public key is shown in the status output of the interface: | |||||
.Bd -literal -offset indent | |||||
# ifconfig wg1 | grep wgpubkey | |||||
wgpubkey NW5l2q2MArV5ZXpVXSZwBOyqhohOf8ImDgUB+jPtJps= | |||||
.Ed | |||||
.Sh EXAMPLES | |||||
Create two | |||||
.Nm | |||||
interfaces in separate | |||||
.Xr rdomain 4 Ns s , | |||||
which is of no practical use | |||||
but demonstrates two interfaces on the same machine: | |||||
.Bd -literal -offset indent | |||||
Done Inline ActionsIt's probably more instructive to have a parametric script, which creates one endpoint only. And then run this script on two machines in order to demonstrate the use case for the reader of the man page. donner: It's probably more instructive to have a parametric script, which creates one endpoint only. | |||||
Done Inline ActionsI reworked the EXAMPLES to demonstrated the basic usage. gbe: I reworked the EXAMPLES to demonstrated the basic usage. | |||||
#!/bin/sh | |||||
# create interfaces; set random private keys | |||||
ifconfig wg1 create wgport 7111 wgkey `openssl rand -base64 32` rdomain 1 | |||||
ifconfig wg2 create wgport 7222 wgkey `openssl rand -base64 32` rdomain 2 | |||||
# retrieve the public keys associated with the private keys | |||||
PUB1="`ifconfig wg1 | grep 'wgpubkey' | cut -d ' ' -f 2`" | |||||
PUB2="`ifconfig wg2 | grep 'wgpubkey' | cut -d ' ' -f 2`" | |||||
donnerUnsubmitted Done Inline ActionsPUBx="``ifconfig wgx | awk '/wgpubkey/ { print $2 }'`" is a more stable parser. donner: PUBx="``ifconfig wgx | awk '/wgpubkey/ { print $2 }'`"
is a more stable parser. | |||||
gbeAuthorUnsubmitted Done Inline ActionsI updated the example with your shell command. Did you have any idea why the generation if the interfaces fails? % ifconfig wg0 create wgport 7111 wgkey openssl rand -base64 32 gbe: I updated the example with your shell command. Did you have any idea why the generation if the… | |||||
ifconfig wg1 wgpeer $PUB2 wgendpoint 127.0.0.1 7222 wgaip 192.168.5.2/32 | |||||
ifconfig wg2 wgpeer $PUB1 wgendpoint 127.0.0.1 7111 wgaip 192.168.5.1/32 | |||||
ifconfig wg1 192.168.5.1/24 | |||||
ifconfig wg2 192.168.5.2/24 | |||||
.Ed | |||||
Done Inline ActionsThat's a dangerous syntax. Please stick to ifconfig wg0 inet 192.168.5.1/24 alias donner: That's a dangerous syntax. Please stick to
ifconfig wg0 inet 192.168.5.1/24 alias | |||||
Done Inline ActionsI reworked the EXAMPLES to demonstrated the basic usage. gbe: I reworked the EXAMPLES to demonstrated the basic usage. | |||||
.Pp | |||||
After this, ping one interface from the other: | |||||
.Pp | |||||
.Dl $ route -T1 exec ping 192.168.5.2 | |||||
.Pp | |||||
The two interfaces are able to communicate through the UDP tunnel. | |||||
.Pp | |||||
Show the listening sockets: | |||||
.Pp | |||||
.Dl $ netstat -ln | |||||
.Sh DIAGNOSTICS | |||||
The | |||||
.Nm | |||||
interface supports runtime debugging, which can be enabled with: | |||||
.Pp | |||||
.D1 Ic ifconfig Cm wg Ns Ar N Cm debug | |||||
.Pp | |||||
Some common error messages include: | |||||
.Bl -diag | |||||
.It "Handshake for peer X did not complete after 5 seconds, retrying" | |||||
Peer X did not reply to our initiation packet, for example because: | |||||
.Bl -bullet | |||||
.It | |||||
The peer does not have the local interface configured as a peer. | |||||
Peers must be able to mutually authenticate each other. | |||||
.It | |||||
The peer endpoint IP address is incorrectly configured. | |||||
.It | |||||
There are firewall rules preventing communication between hosts. | |||||
.El | |||||
.It "Invalid handshake initiation" | |||||
The incoming handshake packet could not be processed. | |||||
This is likely due to the local interface not containing | |||||
the correct public key for the peer. | |||||
.It "Invalid initiation MAC" | |||||
The incoming handshake initiation packet had an invalid MAC. | |||||
This is likely because the initiation sender has the wrong public key | |||||
for the handshake receiver. | |||||
.It "Packet has unallowed src IP from peer X" | |||||
After decryption, an incoming data packet has a source IP address that | |||||
is not assigned to the allowed IPs of Peer X. | |||||
.El | |||||
.Sh SEE ALSO | |||||
.Xr inet 4 , | |||||
.Xr ip 4 , | |||||
.Xr netintro 4 , | |||||
.Xr ipf 5 , | |||||
.Xr pf.conf 5 , | |||||
Done Inline ActionsAny reason to specifically reference pf, but not ipf or ipfw? brueffer: Any reason to specifically reference pf, but not ipf or ipfw? | |||||
Done Inline ActionsThe SEE ALSO list was entirely taken from the OpenBSD version. I have included ipf and ipfw in the new revision of this differential. gbe: The SEE ALSO list was entirely taken from the OpenBSD version. I have included ipf and ipfw in… | |||||
.Xr ifconfig 8 , | |||||
.Xr ipfw 8 | |||||
.Rs | |||||
.%T WireGuard whitepaper | |||||
.%U https://www.wireguard.com/papers/wireguard.pdf | |||||
.Re | |||||
.Sh HISTORY | |||||
The | |||||
.Nm | |||||
device driver first appeared in | |||||
.Fx 13.0 . | |||||
.Sh AUTHORS | |||||
This manual page was written by | |||||
.An Gordon Bergling Aq Mt gbe@FreeBSD.org | |||||
and is based on the | |||||
.Ox | |||||
counterpart written by | |||||
.An David Gwynne Aq Mt dlg@openbsd.org . |
Here and in all other ".Nm wg" cases just .Nm is enough, since above it has been defined as "wg".