Changeset View
Standalone View
share/man/man4/wg.4
- This file was added.
.\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org | |||||
.\" | |||||
.\" 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 February 2, 2021 | |||||
.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 | |||||
The following parameters are available: | |||||
.Bl -tag -width indent | |||||
.It Cm listen-port | |||||
The listing port of the | |||||
.Nm | |||||
interface. | |||||
.It Cm public-key | |||||
The public key of the | |||||
.Nm | |||||
interface. | |||||
.It Cm private-key | |||||
The private key of the | |||||
.Nm | |||||
interface. | |||||
.It Cm pre-shared-key | |||||
Defines a pre-shared key for the | |||||
.Nm | |||||
interface. | |||||
.It Cm allowed-ips | |||||
A list of allowed IP addresses. | |||||
.It Cm endpoint | |||||
The IP address of the WiredGuard to connect to. | |||||
.It Cm peer-list | |||||
A list of peering IP addresses to connect to. | |||||
.El | |||||
.Pp | |||||
Done Inline ActionsPre-shared brueffer: Pre-shared | |||||
The | |||||
.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 | |||||
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 | |||||
Done Inline Actionspre-shared brueffer: pre-shared | |||||
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 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. | |||||
.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. | |||||
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. | |||||
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… | |||||
.Pp | |||||
When an interface has a private key set with | |||||
.Nm public-key , | |||||
the corresponding | |||||
public key is shown in the status output of the interface: | |||||
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. | |||||
.Bd -literal -offset indent | |||||
# ifconfig wg0 | grep public-key | |||||
public-key: 7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw= | |||||
.Ed | |||||
.Sh EXAMPLES | |||||
Create a | |||||
.Nm | |||||
interface and set random private key. | |||||
.Bd -literal -offset indent | |||||
# ifconfig wg0 create listen-port 54321 private-key `openssl rand -base64 32` | |||||
.Ed | |||||
.Pp | |||||
Retrieve the associated public key from a | |||||
.Nm | |||||
interface. | |||||
.Bd -literal -offset indent | |||||
$ ifconfig wg0 | awk '/public-key/ { print $2 }'` | |||||
.Ed | |||||
.Pp | |||||
Connect to a specific endpoint using its public-key and set the allowed IP address | |||||
.Bd -literal -offset indent | |||||
# ifconfig wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100 allowed-ips 192.168.2.100/32 | |||||
.Ed | |||||
.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" | |||||
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… | |||||
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 , | |||||
.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".