1.\" $NetBSD: wg.4,v 1.6 2020/08/31 20:20:22 riastradh 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 abcd 78wm0 = 1.2.3.4 bge0 = 4.3.2.1 79 80Stationary server: Roaming client: 81+---------+ +---------+ 82| A | | B | 83|---------| |---------| 84| [wm0]-------------internet--------[bge0] | 85| [wg0] port 1234 - - - (tunnel) - - - - - - [wg0] | 86| 10.0.1.0 | 10.0.1.1 | 87| | | | | 88+--[wm1]--+ +-----------------+ +---------+ 89 | | VPN 10.0.1.0/24 | 90 | +-----------------+ 91+-----------------+ 92| LAN 10.0.0.0/24 | 93+-----------------+ 94.Ed 95.Pp 96Generate key pairs on A and B: 97.Bd -literal -offset abcd 98A# wg-keygen > /etc/wg/wg0 99A# wg-keygen --pub < /etc/wg/wg0 > /etc/wg/wg0.pub 100A# cat /etc/wg/wg0.pub 101N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= 102 103B# wg-keygen > /etc/wg/wg0 104B# wg-keygen --pub < /etc/wg/wg0 > /etc/wg/wg0.pub 105B# cat /etc/wg/wg0.pub 106X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= 107.Ed 108.Pp 109Configure A to listen on port 1234 and allow connections from B to 110appear in the 10.0.1.0/24 subnet: 111.Bd -literal -offset abcd 112A# ifconfig wg0 create 10.0.1.0/24 113A# wgconfig wg0 set private-key /etc/wg/wg0 114A# wgconfig wg0 set listen-port 1234 115A# wgconfig wg0 add peer B \e 116 X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= \e 117 --allowed-ips=10.0.1.1/32 118A# ifconfig wg0 up 119A# ifconfig wg0 120wg0: flags=0x8041<UP,RUNNING,MULTICAST> mtu 1420 121 inet 10.0.1.0/24 flags 0 122 inet6 fe80::22f7:d6ff:fe3a:1e60%wg0/64 flags 0 scopeid 0x3 123.Ed 124.Pp 125Configure B to connect to A at 1.2.3.4 on port 1234 and the packets can 126begin to flow: 127.Bd -literal -offset abcd 128B# ifconfig wg0 create 10.0.1.1/24 129B# wgconfig wg0 set private-key /etc/wg/wg0 130B# wgconfig wg0 add peer A \e 131 N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= \e 132 --allowed-ips=10.0.1.0/32 \e 133 --endpoint=1.2.3.4:1234 134B# ifconfig wg0 up 135B# ifconfig wg0 136wg0: flags=0x8041<UP,RUNNING,MULTICAST> mtu 1420 137 inet 10.0.1.1/24 flags 0 138 inet6 fe80::56eb:59ff:fe3d:d413%wg0/64 flags 0 scopeid 0x3 139B# ping -n 10.0.1.0 140PING 10.0.1.0 (10.0.1.0): 56 data bytes 14164 bytes from 10.0.1.0: icmp_seq=0 ttl=255 time=2.721110 ms 142\&... 143.Ed 144.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 145.Sh SEE ALSO 146.Xr wg-keygen 8 , 147.Xr wgconfig 8 148.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 149.Sh COMPATIBILITY 150The 151.Nm 152interface aims to be compatible with the WireGuard protocol, as 153described in: 154.Pp 155.Rs 156.%A Jason A. Donenfeld 157.%T WireGuard: Next Generation Kernel Network Tunnel 158.%U https://web.archive.org/web/20180805103233/https://www.wireguard.com/papers/wireguard.pdf 159.%O Document ID: 4846ada1492f5d92198df154f48c3d54205657bc 160.%D 2018-06-30 161.Re 162.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 163.Sh HISTORY 164The 165.Nm 166interface first appeared in 167.Nx 10.0 . 168.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 169.Sh AUTHORS 170The 171.Nm 172interface was implemented by 173.An Ryota Ozaki Aq Mt ozaki.ryota@gmail.com . 174