1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<table class="head">
<tr>
<td class="head-ltitle">WG(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">WG(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">wg</code> — <span class="Nd">WireGuard
protocol driver</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp">To compile this driver into the kernel, place the following lines
in your kernel configuration file:</p>
<div class="Bd Pp Bd-indent"><code class="Cd">device wg</code></div>
<p class="Pp">Alternatively, to load the driver as a module at boot time, place
the following line in <a class="Xr">loader.conf(5)</a>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>if_wg_load="YES"</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">wg</code> driver provides Virtual Private
Network (VPN) interfaces for the secure exchange of layer 3 traffic with
other WireGuard peers using the WireGuard protocol.</p>
<p class="Pp">A <code class="Nm">wg</code> interface recognizes one or more
peers, establishes a secure tunnel with each on demand, and tracks each
peer's UDP endpoint for exchanging encrypted traffic with.</p>
<p class="Pp">The interfaces can be created at runtime using the
<code class="Ic">ifconfig</code>
<code class="Cm">wg</code><var class="Ar">N</var>
<code class="Cm">create</code> command. The interface itself can be
configured with <a class="Xr">wg(8)</a>.</p>
<p class="Pp">The following glossary provides a brief overview of WireGuard
terminology:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt>Peer</dt>
<dd>Peers exchange IPv4 or IPv6 traffic over secure tunnels. Each
<code class="Nm">wg</code> interface may be configured to recognize one or
more peers.</dd>
<dt>Key</dt>
<dd>Each peer uses its private key and corresponding public key to identify
itself to others. A peer configures a <code class="Nm">wg</code> interface
with its own private key and with the public keys of its peers.</dd>
<dt>Pre-shared key</dt>
<dd>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 an attack on
their Diffie-Hellman exchange becomes feasible. It is optional, but
recommended.</dd>
<dt>Allowed IP addresses</dt>
<dd>A single <code class="Nm">wg</code> 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 address ranges
configured against each peer.
<p class="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.</p>
<p class="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 <code class="Nm">wg</code> interface. This ensures that
peers cannot spoof one another's traffic.</p>
</dd>
<dt>Handshake</dt>
<dd>Two peers handshake to mutually authenticate each other and to establish a
shared series of secret ephemeral encryption keys. Either peer may
initiate a handshake. Handshakes occur only when there is traffic to send,
and recur every two minutes during transfers.</dd>
<dt>Connectionless</dt>
<dd>Due to the handshake behavior, there is no connected or disconnected
state.</dd>
</dl>
</div>
<section class="Ss">
<h2 class="Ss" id="Keys"><a class="permalink" href="#Keys">Keys</a></h2>
<p class="Pp">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.</p>
<p class="Pp">Keys can be generated with <a class="Xr">wg(8)</a> as follows:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">$ wg genkey</code></div>
<p class="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.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="NETMAP"><a class="permalink" href="#NETMAP">NETMAP</a></h1>
<p class="Pp"><a class="Xr">netmap(4)</a> applications may open a WireGuard
interface in emulated mode. The netmap application will receive decrypted,
unencapsulated packets prepended by a dummy Ethernet header. The Ethertype
field will be one of <code class="Dv">ETHERTYPE_IP</code> or
<code class="Dv">ETHERTYPE_IPV6</code> depending on the address family of
the packet. Packets transmitted by the application should similarly begin
with a dummy Ethernet header; this header will be stripped before the packet
is encrypted and tunneled.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">Create a <code class="Nm">wg</code> interface and set random
private key.</p>
<div class="Bd Pp Bd-indent Li">
<pre># ifconfig wg0 create
# wg genkey | wg set wg0 listen-port 54321 private-key /dev/stdin</pre>
</div>
<p class="Pp">Retrieve the associated public key from a
<code class="Nm">wg</code> interface.</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ wg show wg0 public-key</pre>
</div>
<p class="Pp">Connect to a specific endpoint using its public-key and set the
allowed IP address</p>
<div class="Bd Pp Bd-indent Li">
<pre># wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32</pre>
</div>
<p class="Pp">Remove a peer</p>
<div class="Bd Pp Bd-indent Li">
<pre># wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' remove</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1>
<p class="Pp">The <code class="Nm">wg</code> interface supports runtime
debugging, which can be enabled with:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Ic">ifconfig</code>
<code class="Cm">wg</code><var class="Ar">N</var>
<code class="Cm">debug</code></div>
<p class="Pp">Some common error messages include:</p>
<dl class="Bl-diag">
<dt>Handshake for peer X did not complete after 5 seconds, retrying</dt>
<dd>Peer X did not reply to our initiation packet, for example because:
<ul class="Bl-bullet">
<li>The peer does not have the local interface configured as a peer. Peers
must be able to mutually authenticate each other.</li>
<li>The peer endpoint IP address is incorrectly configured.</li>
<li>There are firewall rules preventing communication between hosts.</li>
</ul>
</dd>
<dt>Invalid handshake initiation</dt>
<dd>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.</dd>
<dt>Invalid initiation MAC</dt>
<dd>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.</dd>
<dt>Packet has unallowed src IP from peer X</dt>
<dd>After decryption, an incoming data packet has a source IP address that is
not assigned to the allowed IPs of Peer X.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">inet(4)</a>, <a class="Xr">ip(4)</a>,
<a class="Xr">ipsec(4)</a>, <a class="Xr">netintro(4)</a>,
<a class="Xr">netmap(4)</a>, <a class="Xr">ovpn(4)</a>,
<a class="Xr">ipf(5)</a>, <a class="Xr">pf.conf(5)</a>,
<a class="Xr">ifconfig(8)</a>, <a class="Xr">ipfw(8)</a>,
<a class="Xr">wg(8)</a></p>
<p class="Pp"><cite class="Rs"><span class="RsT">WireGuard whitepaper</span>,
<a class="RsU" href="https://www.wireguard.com/papers/wireguard.pdf">https://www.wireguard.com/papers/wireguard.pdf</a>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">wg</code> device driver first appeared in
<span class="Ux">FreeBSD 13.2</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">wg</code> device driver was written by
<span class="An">Jason A. Donenfeld</span>
<<a class="Mt" href="mailto:Jason@zx2c4.com">Jason@zx2c4.com</a>>,
<span class="An">Matt Dunwoodie</span>
<<a class="Mt" href="mailto:ncon@nconroy.net">ncon@nconroy.net</a>>,
<span class="An">Kyle Evans</span>
<<a class="Mt" href="mailto:kevans@FreeBSD.org">kevans@FreeBSD.org</a>>,
and <span class="An">Matt Macy</span>
<<a class="Mt" href="mailto:mmacy@FreeBSD.org">mmacy@FreeBSD.org</a>>.</p>
<p class="Pp">This manual page was written by <span class="An">Gordon
Bergling</span>
<<a class="Mt" href="mailto:gbe@FreeBSD.org">gbe@FreeBSD.org</a>> and
is based on the <span class="Ux">OpenBSD</span> manual page written by
<span class="An">David Gwynne</span>
<<a class="Mt" href="mailto:dlg@openbsd.org">dlg@openbsd.org</a>>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">February 12, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
