1.\" Copyright (c) 2024 The DragonFly Project. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in 11.\" the documentation and/or other materials provided with the 12.\" distribution. 13.\" 3. Neither the name of The DragonFly Project nor the names of its 14.\" contributors may be used to endorse or promote products derived 15.\" from this software without specific, prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 20.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 21.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 25.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 26.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 27.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd February 14, 2024 31.Dt WG.CONF 5 32.Os 33.Sh NAME 34.Nm wg.conf 35.Nd WireGuard configuration file 36.Sh SYNOPSIS 37.Pa /etc/wireguard/ Ns Va ${ifname} Ns .conf 38.Sh DESCRIPTION 39The 40.Nm 41file is used by the WireGuard 42.Xr rc 8 43script to manage a 44.Xr wg 4 45interface. 46The file format is very similar to that of the 47.Xr wg-quick 8 48tool on Linux or 49.Fx , 50but has necessary differences and minor additions. 51.Pp 52The format is based on INI. 53Blank lines and comment lines (i.e., the first non-blank character is 54.Sq # 55or 56.Sq \&; ) 57are ignored; 58however, in-line comments are now allowed. 59Backslash continuation is supported, so a long line may be split into 60multiple lines by ending the lines with a backslash 61.Pq Sq \e . 62The section and field names are case-insensitive. 63There must be one and only one 64.Va Interface 65section, while there can be zero or more 66.Va Peer 67sections. 68.Pp 69The 70.Va Interface 71section may contain the following fields: 72.Bl -tag -width ".It Description" -offset indent 73.It Description 74A description string. 75.It PrivateKey 76.Pq required 77The base64-encoded private key of the interface. 78.It ListenPort 79The UDP port to listen on. 80If not specified, it will be chosen automatically. 81.It Address 82.Pq required 83A comma-separated list of IPv4 or IPv6 addresses (optionally with CIDR masks) 84to be assigned to the interface. 85May be specified multiple times. 86.\" TODO: uncomment this when ifconfig(8)'s wgcookie is ready ... 87.\" .It Cookie 88.\" A 32-bit unsigned integer to mark the packets going through the interface, 89.\" so that they can be easily manipulated in the kernel, e.g., by 90.\" .Xr ipfw 4 91.\" or 92.\" .Xr pf 4 . 93.It MTU 94The explicit MTU to specify for the interface to override the default value. 95.It PreUp 96The command to be executed by 97.Xr sh 1 98before bringing up the interface. 99The special string 100.Dq %i 101will be expanded to the name of the interface. 102If the command execution fails (i.e., a non-zero return value), 103a warning message will be printed and the configuration procedure 104will continue. 105May be specified multiple times, in which case the commands are executed 106in the same order as specified. 107.It PostUp 108Similar to the 109.Va PreUp 110above, but the commands will be executed after bringing up the interface. 111This is most commonly used to configure custom routes, DNS resolvers, 112or firewall rules. 113.It PreDown 114Similar to the 115.Va PreUp 116above, but the commands will be executed before bringing down the interface. 117.It PostDown 118Similar to the 119.Va PreUp 120above, but the commands will be executed after bringing down the interface. 121.El 122.Pp 123The 124.Va Peer 125section may contain the following fields: 126.Bl -tag -width ".It PersistentKeepalive" -offset indent 127.It Enabled 128If set to 129.Dq false 130or 131.Dq no , 132the peer is disabled and will be ignored. 133.It Description 134A description string. 135.It PublicKey 136.Pq required 137The base64-encoded public key of the peer. 138.It PresharedKey 139The base64-encoded pre-shared key, which can strengthen the 140Diffie-Hellman exchange. 141.It Endpoint 142The endpoint address, which may be of formats 143.Dq domain:port , 144.Dq ipv4:port , 145or 146.Dq [ipv6]:port . 147.Sy Note: 148At least one peer in each pair must specify the endpoint address. 149.It AllowedIPs 150.Pq required 151A comma-separated list of IPv4 or IPv6 addresses with CIDR masks, 152from which the incoming traffic to this peer is allowed, 153and to which the outgoing traffic from this peer is directed. 154May be specified multiple times. 155.It PersistentKeepalive 156The interval in seconds of keepalive packets to be sent to the peer, 157for the purpose of keeping a stateful firewall or NAT mapping valid 158persistently. 159If unspecified or set to 160.Dq 0 161or 162.Dq off , 163this function is disabled. 164.El 165.Pp 166.Sy Note: 167The WireGuard 168.Xr rc 8 169script would not add/delete routes according to the peer's allowed IPs, 170because 171.Dx 172currently doesn't support multiple routing tables (or FIBs), 173without which it is hard to reliably generate the correct routes, 174especially to override the default routes. 175Therefore, users should manually determine the routes and 176manage them with the 177.Va PostUp 178and 179.Va PreDown 180hooks. 181.Sh FILES 182.Bl -tag -width "/etc/wireguard/${ifname}.conf" -compat 183.It Pa /etc/wireguard/ Ns Va ${ifname} Ns .conf 184The configuration file for 185.Xr wg 4 186interface named 187.Va ${ifname} . 188.It Pa /etc/rc.d/wg 189The WireGuard 190.Xr rc 8 191script. 192.El 193.Sh EXAMPLES 194.Ss Server Configuration 195This example sets up a WireGuard peer as the server, 196to which the other peers (i.e., clients) can connect. 197The allowed peers are specified with their public keys. 198Note that we use 199.Dq /24 200and 201.Dq /64 202for the interface's addresses, but use 203.Dq /32 204and 205.Dq /128 206for the peers' allowed IPs. 207In this way, with IP forwarding enabled, the server peer acts like 208an LAN switch and then all peers can communicate with each other. 209.Bd -literal -offset indent 210[Interface] 211PrivateKey = <private-key> 212Address = 10.6.66.1/24 213Address = fc00:6:66::1/64 214ListenPort = 6666 215PostUp = sysctl net.inet.ip.forwarding=1 216PostUp = sysctl net.inet6.ip6.forwarding=1 217 218[Peer] 219Description = my peer #1 220PublicKey = <public-key> 221AllowedIPs = 10.6.66.2/32, fc00:6:66::2/128 222 223[Peer] 224Enabled = false 225Description = my peer #2 226PublicKey = <public-key> 227AllowedIPs = 10.6.66.3/32 228.Ed 229.Ss Client Configuration 230The following example configures a WireGuard peer that connects to 231the above server, which is assumed to have an address of 232.Dq wg.example.com . 233Note that the peer's allowed IPs must be the LAN networks (e.g., 234.Dq 10.6.66.0/24 ) 235instead of the specific IP addresses of the server peer (e.g., 236.Dq 10.6.66.1/32 ) ; 237in this way, the system will auto-configure the routes 238for such directly connected networks. 239In addition, the persistent keepalive function is enabled to make 240this peer always try to keep the connection, so that other peers 241can connect to this peer anytime. 242.Bd -literal -offset indent 243[Interface] 244PrivateKey = <private-key> 245Address = 10.6.66.2/24, fc00:6:66::2/64 246 247[Peer] 248PublicKey = <public-key> 249Endpoint = wg.example.com:6666 250AllowedIPs = 10.6.66.0/24 251AllowedIPs = fc00:6:66::/64 252PersistentKeepalive = 25 253.Ed 254.Pp 255The following example configures a WireGuard peer that forwards all its 256IPv4 traffic to the other peer, which must have NAT configured, 257e.g., by using 258.Xr pf 4 . 259The whole IPv4 network (i.e., 260.Dq 0.0.0.0/0 ) 261is split into 262.Dq 0.0.0.0/1 263and 264.Dq 128.0.0.0/1 , 265so that the existing default route is kept intact. 266.Bd -literal -offset indent 267[Interface] 268PrivateKey = <private-key> 269Address = 10.6.66.2/24 270PostUp = route add -host <peer-addr> \e 271 $(route get -inet default | awk '/gateway:/ { print $2 }') 272PostUp = route add -net 0.0.0.0/1 -interface %i 273PostUp = route add -net 128.0.0.0/1 -interface %i 274PreDown = route delete -host <peer-addr> 275PreDown = route delete -net 0.0.0.0/1 276PreDown = route delete -net 128.0.0.0/1 277 278[Peer] 279PublicKey = <public-key> 280Endpoint = <peer-addr>:<peer-port> 281AllowedIPs = 0.0.0.0/0 282PersistentKeepalive = 25 283.Ed 284.Ss Command-line Usage 285Suppose the 286.Xr wg 4 287interface is called 288.Sy mywg , 289and its 290.Nm 291configuration file has been already prepared. 292To create and start the interface: 293.Pp 294.Dl $ /etc/rc.d/wg onestart mywg 295.Pp 296which is equivalent to 297.Ql wg-quick up mywg . 298.Pp 299To stop and destroy the interface: 300.Pp 301.Dl $ /etc/rc.d/wg onestop mywg 302.Pp 303which is equivalent to 304.Ql wg-quick down mywg . 305.Sh SEE ALSO 306.Xr wg 4 , 307.Xr rc.conf 5 , 308.Xr ifconfig 8 309.Sh HISTORY 310The WireGuard 311.Xr rc 8 312script was written by 313.An Aaron LI Aq Mt aly@aaronly.me 314and appeared in 315.Dx 6.5 . 316.Sh AUTHORS 317.An -nosplit 318This manual page was written by 319.An Aaron LI Aq Mt aly@aaronly.me . 320