wg2nd is a specialized utility designed to convert WireGuard configurations in the wg-quick(8)
format into systemd-networkd compatible configurations. It serves as an intermediary tool,
facilitating the migration of functional configurations from wg-quick to networkd.
The primary purpose of wg2nd is to act as a bridge between the wg-quick utility and networkd. networkd is
a feature-complete network manager that offers more control over managing WireGuard tunnels. Additionally,
migrating these configurations to networkd can address reliability issues that may arise due to networkd
interfering with WireGuard tunnels it doesn't manage.
wg2nd is capable of translating almost all configurations without requiring additional configuration, although
exceptions may arise in certain situations. Notable technical distinctions include:
Dynamic Firewall Installation: wg-quick(8) automatically installs a firewall when a default route is specified
(e.g., 0.0.0.0/0 or ::/0 in AllowedIPs). However, wg2nd does not perform this action by default when using
the install command. Users can generate an equivalent firewall using the wg2nd generate -t nft CONFIG_FILE command
and install it into a file accessible by nft (See nft(8) for details).
Additional Scripting: wg2nd ignores the PreUp, PostUp, PreDown, and PostDown script snippets recognized by
wg-quick. These script snippets are not processed during the translation process. Users relying on these scripts should
install them statically or manage them through systemd.
FwMark and Table Handling: While wg-quick dynamically determines the availability of FwMark and Table options,
avoiding conflicts with existing routing tables and firewall marks, wg2nd generates the fwmark using a deterministic
method based on the interface name. This scenario is highly unlikely. Concerns might arise if more than 500 interfaces
using default routes are active simultaneously, but even then, the probability is low.
To install wg2nd, please follow the instructions below based on your distribution:
sudo apt install build-essential libcap-dev
make
sudo make installsudo pacman -S make gcc libcap
make
sudo make installIssues can be reported on the GitHub mirror. Pull requests are welcome and can be submitted on GitHub. Alternatively, you can send patches via email. If you contribute, your name will be added to the contributors list.
For converting a single WireGuard configuration file (wg0.conf) to systemd-networkd format
and installing it in /etc/systemd/network/, execute the following commands:
# Generate the networkd configuration
wg2nd install /etc/wireguard/wg0.conf
# Append firewall rules to nft(8)
wg2nd generate -t nft /etc/wireguard/wg0.conf >> /etc/nftables.conf
# Activate the network interface
networkctl up wg0To enable automatic starting, use wg2nd install -a up /etc/wireguard/wg0.conf. This sets the
default activation policy to up.
For batch converting all WireGuard configuration files in a directory (e.g., /etc/wireguard/),
run the following command as root:
for file in /etc/wireguard/*.conf; do
wg2nd install $file
done
# Activate the network interface
networkctl up INTERFACE_NAMEwg2nd provides two primary actions: install and generate. The generate subcommand generates
specific components of the configurations and outputs them to stdout. The install command
installs the configuration with the appropriate permissions.
Usage: wg2nd { install, generate } [ OPTIONS ] { -h, CONFIG_FILE }
Usage: wg2nd version
CONFIG_FILE is the complete path to a WireGuard configuration file, used by
`wg-quick`. `wg2nd` will convert the WireGuard configuration to networkd
files.
The generated configurations are functionally equivalent to `wg-quick(8)`
with the following exceptions:
1. When unspecified, `wg-quick` determines whether `FwMark` and `Table` are available dynamically,
ensuring that the routing table and `fwmark` are not already in use. `wg2nd` sets
the `fwmark` to a random number (deterministically generated from the interface
name). If more than 500 `fwmarks` are in use, there is a non-negligible chance of a
collision. This would occur when there are more than 500 active WireGuard interfaces.
2. The PreUp, PostUp, PreDown, and PostDown script snippets are ignored.
3. `wg-quick(8)` installs a firewall when a default route is specified (i.e., when `0.0.0.0/0`
or `::/0` are specified in `AllowedIPs`). This is not installed by
default with `wg2nd install`. The equivalent firewall can be generated with
`wg2nd generate -t nft CONFIG_FILE`. Refer to `nft(8)` for details.
Actions:
install Generate and install the configuration with restricted permissions
generate Generate specific configuration files and write the results to stdout
Options:
-h Print this helpUsage: ./wg2nd install [ -h ] [ -a ACTIVATION_POLICY ] [ -f FILE_NAME ] [ -o OUTPUT_PATH ] CONFIG_FILE
`wg2nd install` translates `wg-quick(8)` configuration into corresponding
`networkd` configuration and installs the resulting files in `OUTPUT_PATH`.
`wg2nd install` generates a `netdev`, `network`, and `keyfile` for each
CONFIG_FILE. Links will be installed with a `manual` `ActivationPolicy`.
The interface can be brought up with `networkctl up INTERFACE` and down
with `networkctl down INTERFACE`.
`wg-quick(8)` installs a firewall when a default route (i.e., when `0.0.0.0/0`
or `::/0` is specified in `AllowedIPs`). This is not installed by default
with `wg2nd install`. The equivalent firewall can be generated with
`wg2nd generate -t nft CONFIG_FILE`.
Options:
-a ACTIVATION_POLICY
manual Require manual activation (default)
up Automatically set the link "up"
-o OUTPUT_PATH The installation path (default is /etc/systemd/network)
-f FILE_NAME The base name for the installed configuration files. The
networkd-specific configuration suffix will be added
(FILE_NAME.netdev for systemd-netdev(8) files,
FILE_NAME.network for systemd-network(8) files,
and FILE_NAME.keyfile for keyfiles)
-k KEYFILE The name of the private keyfile
-h Print this helpUsage: ./wg2nd generate [ -h ] [ -a ACTIVATION_POLICY ] [ -k KEYPATH ] [ -t { network, netdev, keyfile, nft } ] CONFIG_FILE
Options:
-a ACTIVATION_POLICY
manual Require manual activation (default)
up Automatically set the link "up"
-t FILE_TYPE
network Generate a Network Configuration File (see systemd.network(8))
netdev Generate a Virtual Device File (see systemd.netdev(8))
keyfile Print the interface's private key
nft Print the netfilter table `nft(8)` installed by `wg-quick(8)`
-k KEYPATH Full path to the keyfile (a path relative to /etc/systemd/network is generated
if unspecified)
-h Print this help