WG.CONF(5)

NAME
wg.conf - WireGuard configuration file

SYNOPSIS
/etc/wireguard/${ifname}.conf

DESCRIPTION
The wg.conf file is used by the WireGuard rc(8) script to manage a wg(4) interface. The file format is very similar to that of the wg-quick(8) tool on Linux or FreeBSD, but has necessary differences and minor additions.

The format is based on INI. Blank lines and comment lines (i.e., the first non-blank character is ‘#’ or ‘’;) are ignored; however, in-line comments are not allowed. Backslash continuation is supported, so a long line may be split into multiple lines by ending the lines with a backslash (‘\’). The section and field names are case-insensitive. There must be one and only one Interface section, while there can be zero or more Peer sections.

The Interface section may contain the following fields:

Description
    A description string.

PrivateKey
    (required) The base64-encoded private key of the interface.

ListenPort
    The UDP port to listen on. If not specified, it will be chosen automatically.

Address
    (required) A comma-separated list of IPv4 or IPv6 addresses (optionally with CIDR masks) to be assigned to the interface. May be specified multiple times.

MTU The explicit MTU to specify for the interface to override the default value.

PreUp
    The command to be executed by sh(1) before bringing up the interface. The special string “%i” will be expanded to the name of the interface. If the command execution fails (i.e., a non-zero return value), a warning message will be printed and the configuration procedure will continue. May be specified multiple times, in which case the commands are executed in the same order as specified.

PostUp
    Similar to the PreUp above, but the commands will be executed after bringing up the interface. This is most commonly used to configure custom routes, DNS resolvers, or firewall rules.

PreDown
    Similar to the PreUp above, but the commands will be executed before bringing down the interface.

PostDown
    Similar to the PreUp above, but the commands will be executed after bringing down the interface.

The Peer section may contain the following fields:

Enabled
    If set to “false” or “no”, the peer is disabled and will be ignored.

Description
    A description string.

PublicKey
    (required) The base64-encoded public key of the peer.

PresharedKey
    The base64-encoded pre-shared key, which can strengthen the Diffie-Hellman exchange.

Endpoint
    The endpoint address, which may be of formats “domain:port”, “ipv4:port”, or “[ipv6]:port”. Note: At least one peer in each pair must specify the endpoint address.

AllowedIPs
    (required) A comma-separated list of IPv4 or IPv6 addresses with CIDR masks, from which the incoming traffic to this peer is allowed, and to which the outgoing traffic from this peer is directed. May be specified multiple times.

PersistentKeepalive
    The interval in seconds of keepalive packets to be sent to the peer, for the purpose of keeping a stateful firewall or NAT mapping valid persistently. If unspecified or set to “0” or “off”, this function is disabled.

Note: The WireGuard rc(8) script would not add/delete routes according to the peer's allowed IPs, because DragonFly currently doesn't support multiple routing tables (or FIBs), without which it is hard to reliably generate the correct routes, especially to override the default routes. Therefore, users should manually determine the routes and manage them with the PostUp and PreDown hooks.

FILES

/etc/wireguard/${ifname}.conf
    The configuration file for wg(4) interface named ${ifname}.

/etc/rc.d/wg
    The WireGuard rc(8) script.

EXAMPLES

  Server Configuration
This example sets up a WireGuard peer as the server, to which the other peers (i.e., clients) can connect. The allowed peers are specified with their public keys. Note that we use “/24” and “/64” for the interface's addresses, but use “/32” and “/128” for the peers' allowed IPs. In this way, with IP forwarding enabled, the server peer acts like an LAN switch and then all peers can communicate with each other.

    [Interface]
    PrivateKey = <private-key>
    Address = 10.6.66.1/24
    Address = fc00:6:66::1/64
    ListenPort = 6666
    PostUp = sysctl net.inet.ip.forwarding=1
    PostUp = sysctl net.inet6.ip6.forwarding=1
    [Peer]
    Description = my peer #1
    PublicKey = <public-key>
    AllowedIPs = 10.6.66.2/32, fc00:6:66::2/128
    [Peer]
    Enabled = false
    Description = my peer #2
    PublicKey = <public-key>
    AllowedIPs = 10.6.66.3/32

  Client Configuration
The following example configures a WireGuard peer that connects to the above server, which is assumed to have an address of “wg.example.com”. Note that the peer's allowed IPs must be the LAN networks (e.g., “10.6.66.0/24”) instead of the specific IP addresses of the server peer (e.g., “10.6.66.1/32”); in this way, the system will auto-configure the routes for such directly connected networks. In addition, the persistent keepalive function is enabled to make this peer always try to keep the connection, so that other peers can connect to this peer anytime.

    [Interface]
    PrivateKey = <private-key>
    Address = 10.6.66.2/24, fc00:6:66::2/64
    [Peer]
    PublicKey = <public-key>
    Endpoint = wg.example.com:6666
    AllowedIPs = 10.6.66.0/24
    AllowedIPs = fc00:6:66::/64
    PersistentKeepalive = 25

The following example configures a WireGuard peer that forwards all its IPv4 traffic to the other peer, which must have NAT configured, e.g., by using pf(4). The whole IPv4 network (i.e., “0.0.0.0/0”) is split into “0.0.0.0/1” and “128.0.0.0/1”, so that the existing default route is kept intact.

    [Interface]
    PrivateKey = <private-key>
    Address = 10.6.66.2/24
    PostUp = route add -host <peer-addr> \
    	$(route get -inet default | awk '/gateway:/ { print $2 }')
    PostUp = route add -net 0.0.0.0/1 -interface %i
    PostUp = route add -net 128.0.0.0/1 -interface %i
    PreDown = route delete -host <peer-addr>
    PreDown = route delete -net 0.0.0.0/1
    PreDown = route delete -net 128.0.0.0/1
    [Peer]
    PublicKey = <public-key>
    Endpoint = <peer-addr>:<peer-port>
    AllowedIPs = 0.0.0.0/0
    PersistentKeepalive = 25

  Command-line Usage
Suppose the wg(4) interface is called mywg, and its wg.conf configuration file has been already prepared. To create and start the interface:

    $ /etc/rc.d/wg onestart mywg

which is equivalent to ‘wg-quick up mywg’.

To stop and destroy the interface:

    $ /etc/rc.d/wg onestop mywg

which is equivalent to ‘wg-quick down mywg’.

SEE ALSO
wg(4), rc.conf(5), ifconfig(8)

HISTORY
The WireGuard rc(8) script was written by Aaron LI <aly@aaronly.me> and appeared in DragonFly 6.5.

AUTHORS
-nosplit This manual page was written by Aaron LI <aly@aaronly.me>.