Thu Apr 18 15:44:37 2024 UTC (34d)
Pull up following revision(s) (requested by riastradh in ticket #658):

	share/man/man4/wg.4: revision 1.8
	share/man/man4/wg.4: revision 1.9

wg(4): Rework example numbering for clarity and add IPv6.

Let's avoid triggering unease with host number 0.
PR misc/58015

wg(4): Fix IPv6 numbering in example diagram.

This way it matches the configuration suggested below (which avoids
host number zero on the subnet).

PR misc/58015


(martin)
diff -r1.6.6.1 -r1.6.6.2 src/share/man/man4/wg.4
cvs diff -r1.6.6.1 -r1.6.6.2 src/share/man/man4/wg.4 (switch to unified diff)

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