Add a wg(4) manual page
Reviewed by: brueffer, donner, debdrup, ygy MFC after: 2 days
This commit is contained in:
Gordon Bergling
parent
3dd2a7a5ea
commit
e59d9cb412
@ -584,6 +584,7 @@ MAN= aac.4 \
|
||||
vtnet.4 \
|
||||
watchdog.4 \
|
||||
${_wbwd.4} \
|
||||
wg.4 \
|
||||
witness.4 \
|
||||
wlan.4 \
|
||||
wlan_acl.4 \
|
||||
|
||||
244
share/man/man4/wg.4
Normal file
244
share/man/man4/wg.4
Normal file
@ -0,0 +1,244 @@
|
||||
.\" 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
|
||||
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
|
||||
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
|
||||
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.
|
||||
.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 public-key ,
|
||||
the corresponding
|
||||
public key is shown in the status output of the interface:
|
||||
.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"
|
||||
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 .
|
||||
Loading…
Reference in New Issue
Block a user