.\"	$NetBSD: wg.4,v 1.14 2025/02/24 00:55:57 bad Exp $
.\"
.\" Copyright (c) 2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 16, 2024
.Dt WG 4
.Os
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh NAME
.Nm wg
.Nd virtual private network tunnel (EXPERIMENTAL)
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SYNOPSIS
.Cd pseudo-device wg
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION
The
.Nm
interface implements a roaming-capable virtual private network tunnel,
configured with
.Xr ifconfig 8
and
.Xr wgconfig 8 .
.Pp
.Sy WARNING:
.Nm
is experimental.
.Pp
Packets exchanged on a
.Nm
interface are authenticated and encrypted with a secret key negotiated
with the peer, and the encapsulation is exchanged over IP or IPv6 using
UDP.
.Pp
Every
.Nm
interface can be configured with an IP address using
.Xr ifconfig 8 ,
a private key generated with
.Xr wg-keygen 8 ,
an optional listen port,
and a collection of peers.
.Pp
Each peer configured on an
.Nm
interface has a public key and a range of IP addresses the peer is
allowed to use for its
.Nm
interface inside the tunnel.
Each peer may also optionally have a preshared secret key and a fixed
endpoint IP address outside the tunnel.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh EXAMPLES
Typical network topology:
.Bd -literal -offset 4n
Stationary server:                         Roaming client:
+---------+                                    +---------+
|    A    |                                    |    B    |
|---------|                                    |---------|
|         | 192.0.2.123          198.51.100.45 |         |
|        [wm0]----------internet-----------[bge0]        |
|    [wg0] port 1234 - - - (tunnel) - - - - - - [wg0]    |
|   10.2.0.1                  |               10.2.0.42  |
|   fd00:2::1                 |              fd00:2::42  |
|         |                   |                |         |
+--[wm1]--+          +-----------------+       +---------+
     | 10.1.0.1      | VPN 10.2.0.0/24 |
     |               |     fd00:2::/64 |
     |               +-----------------+
+-----------------+
| LAN 10.1.0.0/24 |
|     fd00:1::/64 |
+-----------------+
.Ed
.Pp
Generate key pairs on A and B:
.Bd -literal -offset 4n
A# (umask 0077; wg-keygen > /etc/wg/wg0)
A# wg-keygen --pub < /etc/wg/wg0 > /etc/wg/wg0.pub
A# cat /etc/wg/wg0.pub
N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y=

B# (umask 0077; wg-keygen > /etc/wg/wg0)
B# wg-keygen --pub < /etc/wg/wg0 > /etc/wg/wg0.pub
B# cat /etc/wg/wg0.pub
X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU=
.Ed
.Pp
Generate a pre-shared key on A and copy it to B to defend against
potential future quantum cryptanalysis (not necessary for
functionality):
.Bd -literal -offset 4n
A# (umask 0077; wg-keygen > /etc/wg/wg0.A-B)
.Ed
.Pp
Configure A to listen on port 1234 and allow connections from B to
appear in the 10.2.0.0/24 and fd00:2::/64 subnets:
.Bd -literal -offset 4n
A# ifconfig wg0 create
A# ifconfig wg0 inet 10.2.0.1/24
A# ifconfig wg0 inet6 fd00:2::1/64
A# wgconfig wg0 set private-key /etc/wg/wg0
A# wgconfig wg0 set listen-port 1234
A# wgconfig wg0 add peer B \e
    X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= \e
    --preshared-key=/etc/wg/wg0.A-B \e
    --allowed-ips=10.2.0.42/32,fd00:2::42/128
A# ifconfig wg0 up
A# ifconfig wg0
wg0: flags=0x8041<UP,RUNNING,MULTICAST> mtu 1420
        status: active
        inet6 fe80::22f7:d6ff:fe3a:1e60%wg0/64 flags 0 scopeid 0x3
        inet6 fd00:2::1/64 flags 0
        inet 10.2.0.1/24 flags 0
.Ed
.Pp
You can put all these commands in
.Pa /etc/ifconfig.wg0
so that the interface gets configured automatically during startup:
.Bd -literal -offset 4n
A# cat /etc/ifconfig.wg0
net 10.2.0.1/24
inet6 fd00:2::1/64
!wgconfig $int set private-key /etc/wg/wg0
!wgconfig $int set listen-port 1234
!wgconfig $int add peer B X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= \e
    --preshared-key=/etc/wg/wg0.A-B \e
    --allowed-ips=10.2.0.42/32,fd00:2::1/128
up
.Ed
.Pp
Configure B to connect to A at 192.0.2.123 on port 1234 and the packets
can begin to flow:
.Bd -literal -offset 4n
B# ifconfig wg0 create
B# ifconfig wg0 inet 10.2.0.42/24
B# ifconfig wg0 inet6 fd00:2::42/64
B# wgconfig wg0 set private-key /etc/wg/wg0
B# wgconfig wg0 add peer A \e
    N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= \e
    --preshared-key=/etc/wg/wg0.A-B \e
    --allowed-ips=10.2.0.1/32,fd00:2::1/128 \e
    --endpoint=192.0.2.123:1234
B# ifconfig wg0 up
B# ifconfig wg0
wg0: flags=0x8041<UP,RUNNING,MULTICAST> mtu 1420
        status: active
        inet6 fe80::56eb:59ff:fe3d:d413%wg0/64 flags 0 scopeid 0x3
        inet6 fd00:2::42/64 flags 0
        inet 10.2.0.42/24 flags 0
B# ping -n 10.2.0.1
PING 10.2.0.1 (10.2.0.1): 56 data bytes
64 bytes from 10.2.0.1: icmp_seq=0 ttl=255 time=2.721110 ms
\&...
B# ping6 -n fd00:2::1
PING6(56=40+8+8 bytes) fd00:2::42 --> fd00:2::1
16 bytes from fd00:2::1, icmp_seq=0 hlim=64 time=2.634 ms
\&...
.Ed
.Pp
Same as before, you can put all these commands in
.Pa /etc/ifconfig.wg0
so that the interface gets configured automatically during startup:
.Bd -literal -offset 4n
B# cat /etc/ifconfig.wg0
inet 10.2.0.42/24
inet6 fd00:2::42/64
!wgconfig $int set private-key /etc/wg/wg0
!wgconfig $int add peer A N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= \e
    --preshared-key=/etc/wg/wg0.A-B \e
    --allowed-ips=10.2.0.1/32,fd00:2::1/128 \e
    --endpoint=192.0.2.123:1234
up
.Ed
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr wg-keygen 8 ,
.Xr wgconfig 8 ,
.Xr wg-userspace 8
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh COMPATIBILITY
The
.Nm
interface aims to be compatible with the WireGuard protocol, as
described in:
.Pp
.Rs
.%A Jason A. Donenfeld
.%T WireGuard: Next Generation Kernel Network Tunnel
.%U https://web.archive.org/web/20180805103233/https://www.wireguard.com/papers/wireguard.pdf
.%O Document ID: 4846ada1492f5d92198df154f48c3d54205657bc
.%D 2018-06-30
.Re
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh HISTORY
The
.Nm
interface first appeared in
.Nx 10.0 .
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh AUTHORS
The
.Nm
interface was implemented by
.An Ryota Ozaki Aq Mt ozaki.ryota@gmail.com .