Thu Apr 18 15:44:37 2024 UTC (22d)
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 (expand / 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,14 +1,14 @@ @@ -1,14 +1,14 @@
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.\"
@@ -65,99 +65,113 @@ and a collection of peers. @@ -65,99 +65,113 @@ and 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