xref: /freebsd/share/man/man4/wg.4 (revision 7ef62cebc2f965b0f640263e179276928885e33d)
1.\" SPDX-License-Identifier: BSD-2-Clause
2.\"
3.\" Copyright (c) 2020 Gordon Bergling <gbe@FreeBSD.org>
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd June 12, 2023
29.Dt WG 4
30.Os
31.Sh NAME
32.Nm wg
33.Nd "WireGuard protocol driver"
34.Sh SYNOPSIS
35To load the driver as a module at boot time, place the following line in
36.Xr loader.conf 5 :
37.Bd -literal -offset indent
38if_wg_load="YES"
39.Ed
40.Sh DESCRIPTION
41The
42.Nm
43driver provides Virtual Private Network (VPN) interfaces for the secure
44exchange of layer 3 traffic with other WireGuard peers using the WireGuard
45protocol.
46.Pp
47A
48.Nm
49interface recognizes one or more peers, establishes a secure tunnel with
50each on demand, and tracks each peer's UDP endpoint for exchanging encrypted
51traffic with.
52.Pp
53The interfaces can be created at runtime using the
54.Ic ifconfig Cm wg Ns Ar N Cm create
55command.
56The interface itself can be configured with
57.Xr wg 8 .
58.Pp
59The following glossary provides a brief overview of WireGuard
60terminology:
61.Bl -tag -width indent -offset 3n
62.It Peer
63Peers exchange IPv4 or IPv6 traffic over secure tunnels.
64Each
65.Nm
66interface may be configured to recognise one or more peers.
67.It Key
68Each peer uses its private key and corresponding public key to
69identify itself to others.
70A peer configures a
71.Nm
72interface with its own private key and with the public keys of its peers.
73.It Pre-shared key
74In addition to the public keys, each peer pair may be configured with a
75unique pre-shared symmetric key.
76This is used in their handshake to guard against future compromise of the
77peers' encrypted tunnel if an attack on their
78Diffie-Hellman exchange becomes feasible.
79It is optional, but recommended.
80.It Allowed IP addresses
81A single
82.Nm
83interface may maintain concurrent tunnels connecting diverse networks.
84The interface therefore implements rudimentary routing and reverse-path
85filtering functions for its tunneled traffic.
86These functions reference a set of allowed IP address ranges configured
87against each peer.
88.Pp
89The interface will route outbound tunneled traffic to the peer configured
90with the most specific matching allowed IP address range, or drop it
91if no such match exists.
92.Pp
93The interface will accept tunneled traffic only from the peer
94configured with the most specific matching allowed IP address range
95for the incoming traffic, or drop it if no such match exists.
96That is, tunneled traffic routed to a given peer cannot return through
97another peer of the same
98.Nm
99interface.
100This ensures that peers cannot spoof one another's traffic.
101.It Handshake
102Two peers handshake to mutually authenticate each other and to
103establish a shared series of secret ephemeral encryption keys.
104Either peer may initiate a handshake.
105Handshakes occur only when there is traffic to send, and recur every
106two minutes during transfers.
107.It Connectionless
108Due to the handshake behavior, there is no connected or disconnected
109state.
110.El
111.Ss Keys
112Private keys for WireGuard can be generated from any sufficiently
113secure random source.
114The Curve25519 keys and the pre-shared keys are both 32 bytes
115long and are commonly encoded in base64 for ease of use.
116.Pp
117Keys can be generated with
118.Xr wg 8
119as follows:
120.Pp
121.Dl $ wg genkey
122.Pp
123Although a valid Curve25519 key must have 5 bits set to
124specific values, this is done by the interface and so it
125will accept any random 32-byte base64 string.
126.Sh EXAMPLES
127Create a
128.Nm
129interface and set random private key.
130.Bd -literal -offset indent
131# ifconfig wg0 create
132# wg genkey | wg set wg0 listen-port 54321 private-key /dev/stdin
133.Ed
134.Pp
135Retrieve the associated public key from a
136.Nm
137interface.
138.Bd -literal -offset indent
139$ wg show wg0 public-key
140.Ed
141.Pp
142Connect to a specific endpoint using its public-key and set the allowed IP address
143.Bd -literal -offset indent
144# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32
145.Ed
146.Pp
147Remove a peer
148.Bd -literal -offset indent
149# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' remove
150.Ed
151.Sh DIAGNOSTICS
152The
153.Nm
154interface supports runtime debugging, which can be enabled with:
155.Pp
156.D1 Ic ifconfig Cm wg Ns Ar N Cm debug
157.Pp
158Some common error messages include:
159.Bl -diag
160.It "Handshake for peer X did not complete after 5 seconds, retrying"
161Peer X did not reply to our initiation packet, for example because:
162.Bl -bullet
163.It
164The peer does not have the local interface configured as a peer.
165Peers must be able to mutually authenticate each other.
166.It
167The peer endpoint IP address is incorrectly configured.
168.It
169There are firewall rules preventing communication between hosts.
170.El
171.It "Invalid handshake initiation"
172The incoming handshake packet could not be processed.
173This is likely due to the local interface not containing
174the correct public key for the peer.
175.It "Invalid initiation MAC"
176The incoming handshake initiation packet had an invalid MAC.
177This is likely because the initiation sender has the wrong public key
178for the handshake receiver.
179.It "Packet has unallowed src IP from peer X"
180After decryption, an incoming data packet has a source IP address that
181is not assigned to the allowed IPs of Peer X.
182.El
183.Sh SEE ALSO
184.Xr inet 4 ,
185.Xr ip 4 ,
186.Xr ipsec 4 ,
187.Xr netintro 4 ,
188.Xr ovpn 4 ,
189.Xr ipf 5 ,
190.Xr pf.conf 5 ,
191.Xr ifconfig 8 ,
192.Xr ipfw 8 ,
193.Xr wg 8
194.Rs
195.%T WireGuard whitepaper
196.%U https://www.wireguard.com/papers/wireguard.pdf
197.Re
198.Sh HISTORY
199The
200.Nm
201device driver first appeared in
202.Fx 13.2 .
203.Sh AUTHORS
204.An -nosplit
205The
206.Nm
207device driver was written by
208.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com ,
209.An Matt Dunwoodie Aq Mt ncon@nconroy.net ,
210.An Kyle Evans Aq Mt kevans@FreeBSD.org ,
211and
212.An Matt Macy Aq Mt mmacy@FreeBSD.org .
213.Pp
214This manual page was written by
215.An Gordon Bergling Aq Mt gbe@FreeBSD.org
216and is based on the
217.Ox
218manual page written by
219.An David Gwynne Aq Mt dlg@openbsd.org .
220