1.\" $NetBSD: wg.4,v 1.11 2024/12/16 19:21:59 christos Exp $ 2.\" 3.\" Copyright (c) 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd December 16, 2024 28.Dt WG 4 29.Os 30.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 31.Sh NAME 32.Nm wg 33.Nd virtual private network tunnel (EXPERIMENTAL) 34.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 35.Sh SYNOPSIS 36.Cd pseudo-device wg 37.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 38.Sh DESCRIPTION 39The 40.Nm 41interface implements a roaming-capable virtual private network tunnel, 42configured with 43.Xr ifconfig 8 44and 45.Xr wgconfig 8 . 46.Pp 47.Sy WARNING: 48.Nm 49is experimental. 50.Pp 51Packets exchanged on a 52.Nm 53interface are authenticated and encrypted with a secret key negotiated 54with the peer, and the encapsulation is exchanged over IP or IPv6 using 55UDP. 56.Pp 57Every 58.Nm 59interface can be configured with an IP address using 60.Xr ifconfig 8 , 61a private key generated with 62.Xr wg-keygen 8 , 63an optional listen port, 64and a collection of peers. 65.Pp 66Each peer configured on an 67.Nm 68interface has a public key and a range of IP addresses the peer is 69allowed to use for its 70.Nm 71interface inside the tunnel. 72Each peer may also optionally have a preshared secret key and a fixed 73endpoint IP address outside the tunnel. 74.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 75.Sh EXAMPLES 76Typical network topology: 77.Bd -literal -offset 4n 78Stationary server: Roaming client: 79+---------+ +---------+ 80| A | | B | 81|---------| |---------| 82| | 192.0.2.123 198.51.100.45 | | 83| [wm0]----------internet-----------[bge0] | 84| [wg0] port 1234 - - - (tunnel) - - - - - - [wg0] | 85| 10.2.0.1 | 10.2.0.42 | 86| fd00:2::1 | fd00:2::42 | 87| | | | | 88+--[wm1]--+ +-----------------+ +---------+ 89 | 10.1.0.1 | VPN 10.2.0.0/24 | 90 | | fd00:2::/64 | 91 | +-----------------+ 92+-----------------+ 93| LAN 10.1.0.0/24 | 94| fd00:1::/64 | 95+-----------------+ 96.Ed 97.Pp 98Generate key pairs on A and B: 99.Bd -literal -offset 4n 100A# (umask 0077; wg-keygen > /etc/wg/wg0) 101A# wg-keygen --pub < /etc/wg/wg0 > /etc/wg/wg0.pub 102A# cat /etc/wg/wg0.pub 103N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= 104 105B# (umask 0077; wg-keygen > /etc/wg/wg0) 106B# wg-keygen --pub < /etc/wg/wg0 > /etc/wg/wg0.pub 107B# cat /etc/wg/wg0.pub 108X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= 109.Ed 110.Pp 111Generate a pre-shared key on A and copy it to B to defend against 112potential future quantum cryptanalysis (not necessary for 113functionality): 114.Bd -literal -offset 4n 115A# (umask 0077; wg-keygen > /etc/wg/wg0.A-B) 116.Ed 117.Pp 118Configure A to listen on port 1234 and allow connections from B to 119appear in the 10.2.0.0/24 and fd00:2::/64 subnets: 120.Bd -literal -offset 4n 121A# ifconfig wg0 create 122A# ifconfig wg0 inet 10.2.0.1/24 123A# ifconfig wg0 inet6 fd00:2::1/64 124A# wgconfig wg0 set private-key /etc/wg/wg0 125A# wgconfig wg0 set listen-port 1234 126A# wgconfig wg0 add peer B \e 127 X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= \e 128 --preshared-key=/etc/wg/wg0.A-B \e 129 --allowed-ips=10.2.0.42/32,fd00:2::42/128 130A# ifconfig wg0 up 131A# ifconfig wg0 132wg0: flags=0x8041<UP,RUNNING,MULTICAST> mtu 1420 133 status: active 134 inet6 fe80::22f7:d6ff:fe3a:1e60%wg0/64 flags 0 scopeid 0x3 135 inet6 fd00:2::1/64 flags 0 136 inet 10.2.0.1/24 flags 0 137.Ed 138.Pp 139You can put all these commands in 140.Pa /etc/ifconfig.wg0 141so that the interface gets configured automatically during startup: 142.Bd -literal -offset 4n 143A# cat /etc/ifconfig.wg0 144net 10.2.0.1/24 145inet6 fd00:2::1/64 146!wgconfig wg0 set private-key /etc/wg/wg0 147!wgconfig wg0 set listen-port 1234 148!wgconfig wg0 add peer B X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= \e 149 --preshared-key=/etc/wg/wg0.A-B \e 150 --allowed-ips=10.2.0.42/32,fd00:2::1/128 \e 151up 152.Ed 153.Pp 154Configure B to connect to A at 192.0.2.123 on port 1234 and the packets 155can begin to flow: 156.Bd -literal -offset 4n 157B# ifconfig wg0 create 158B# ifconfig wg0 inet 10.2.0.42/24 159B# ifconfig wg0 inet6 fd00:2::42/64 160B# wgconfig wg0 set private-key /etc/wg/wg0 161B# wgconfig wg0 add peer A \e 162 N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= \e 163 --preshared-key=/etc/wg/wg0.A-B \e 164 --allowed-ips=10.2.0.1/32,fd00:2::1/128 \e 165 --endpoint=192.0.2.123:1234 166B# ifconfig wg0 up 167B# ifconfig wg0 168wg0: flags=0x8041<UP,RUNNING,MULTICAST> mtu 1420 169 status: active 170 inet6 fe80::56eb:59ff:fe3d:d413%wg0/64 flags 0 scopeid 0x3 171 inet6 fd00:2::42/64 flags 0 172 inet 10.2.0.42/24 flags 0 173B# ping -n 10.2.0.1 174PING 10.2.0.1 (10.2.0.1): 56 data bytes 17564 bytes from 10.2.0.1: icmp_seq=0 ttl=255 time=2.721110 ms 176\&... 177B# ping6 -n fd00:2::1 178PING6(56=40+8+8 bytes) fd00:2::42 --> fd00:2::1 17916 bytes from fd00:2::1, icmp_seq=0 hlim=64 time=2.634 ms 180\&... 181.Ed 182.Pp 183Same as before, you can put all these commands in 184.Pa /etc/ifconfig.wg0 185so that the interface gets configured automatically during startup: 186.Bd -literal -offset 4n 187B# cat /etc/ifconfig.wg0 188inet 10.2.0.42/24 189inet6 fd00:2::42/64 190!wgconfig wg0 set private-key /etc/wg/wg0 191!wgconfig wg0 add peer A N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= \e 192 --preshared-key=/etc/wg/wg0.A-B \e 193 --allowed-ips=10.2.0.1/32,fd00:2::1/128 \e 194 --endpoint=192.0.2.123:1234 195up 196.Ed 197.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 198.Sh SEE ALSO 199.Xr wg-keygen 8 , 200.Xr wgconfig 8 201.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 202.Sh COMPATIBILITY 203The 204.Nm 205interface aims to be compatible with the WireGuard protocol, as 206described in: 207.Pp 208.Rs 209.%A Jason A. Donenfeld 210.%T WireGuard: Next Generation Kernel Network Tunnel 211.%U https://web.archive.org/web/20180805103233/https://www.wireguard.com/papers/wireguard.pdf 212.%O Document ID: 4846ada1492f5d92198df154f48c3d54205657bc 213.%D 2018-06-30 214.Re 215.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 216.Sh HISTORY 217The 218.Nm 219interface first appeared in 220.Nx 10.0 . 221.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 222.Sh AUTHORS 223The 224.Nm 225interface was implemented by 226.An Ryota Ozaki Aq Mt ozaki.ryota@gmail.com . 227