1.\" $NetBSD: wg.4,v 1.10 2024/03/24 00:45:06 uwe 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 August 20, 2020 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 139Configure B to connect to A at 192.0.2.123 on port 1234 and the packets 140can begin to flow: 141.Bd -literal -offset 4n 142B# ifconfig wg0 create 143B# ifconfig wg0 inet 10.2.0.42/24 144B# ifconfig wg0 inet6 fd00:2::42/64 145B# wgconfig wg0 set private-key /etc/wg/wg0 146B# wgconfig wg0 add peer A \e 147 N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= \e 148 --preshared-key=/etc/wg/wg0.A-B \e 149 --allowed-ips=10.2.0.1/32,fd00:2::1/128 \e 150 --endpoint=192.0.2.123:1234 151B# ifconfig wg0 up 152B# ifconfig wg0 153wg0: flags=0x8041<UP,RUNNING,MULTICAST> mtu 1420 154 status: active 155 inet6 fe80::56eb:59ff:fe3d:d413%wg0/64 flags 0 scopeid 0x3 156 inet6 fd00:2::42/64 flags 0 157 inet 10.2.0.42/24 flags 0 158B# ping -n 10.2.0.1 159PING 10.2.0.1 (10.2.0.1): 56 data bytes 16064 bytes from 10.2.0.1: icmp_seq=0 ttl=255 time=2.721110 ms 161\&... 162B# ping6 -n fd00:2::1 163PING6(56=40+8+8 bytes) fd00:2::42 --> fd00:2::1 16416 bytes from fd00:2::1, icmp_seq=0 hlim=64 time=2.634 ms 165\&... 166.Ed 167.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 168.Sh SEE ALSO 169.Xr wg-keygen 8 , 170.Xr wgconfig 8 171.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 172.Sh COMPATIBILITY 173The 174.Nm 175interface aims to be compatible with the WireGuard protocol, as 176described in: 177.Pp 178.Rs 179.%A Jason A. Donenfeld 180.%T WireGuard: Next Generation Kernel Network Tunnel 181.%U https://web.archive.org/web/20180805103233/https://www.wireguard.com/papers/wireguard.pdf 182.%O Document ID: 4846ada1492f5d92198df154f48c3d54205657bc 183.%D 2018-06-30 184.Re 185.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 186.Sh HISTORY 187The 188.Nm 189interface first appeared in 190.Nx 10.0 . 191.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 192.Sh AUTHORS 193The 194.Nm 195interface was implemented by 196.An Ryota Ozaki Aq Mt ozaki.ryota@gmail.com . 197