diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..cfee9a6 --- /dev/null +++ b/README.md @@ -0,0 +1,174 @@ +wg2nd - WireGuard to systemd-networkd Configuration Converter +============================================================= + +`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`. + +Purpose +------- + +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. + +Compatibility and Limitations +----------------------------- + +`wg2nd` is capable of translating almost all configurations without requiring additional configuration, although +exceptions may arise in certain situations. Notable technical distinctions include: + +1. **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). + +2. **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`. + +3. **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. + +Installation +------------ + +To install `wg2nd`, please follow the instructions below based on your distribution: + +### Ubuntu/Debian + +```bash +sudo apt install build-essential libargon2-dev +make +sudo make install +``` + +### Arch Linux + +```bash +sudo pacman -S argon2 make gcc +make +sudo make install +``` + +Example Usage +------------- + +### Single Conversion + +For converting a single WireGuard configuration file (`wg0.conf`) to `systemd-networkd` format +and installing it in `/etc/systemd/network/`, execute the following commands: + +```bash +# 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/nft.conf + +# Activate the network interface +networkctl up wg0 +``` + +To enable automatic starting, ensure that the `ActivationPolicy` is removed from the generated `network` configuration. + +### Batch Conversion + +For batch converting all WireGuard configuration files in a directory (e.g., `/etc/wireguard/`), +run the following command as root: + +```bash +for file in /etc/wireguard/*.conf; do + wg2nd install $file +done + +# Activate the network interface +networkctl up INTERFACE_NAME +``` + +Usage +----- + +`wg2nd` 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. + +```plaintext +Usage: ./wg2nd { install, generate } [ OPTIONS ] { -h, CONFIG_FILE } + + CONFIG_FILE is the complete path to a WireGuard configuration file used by + `wg-quick`. `wg2nd` converts 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 help +``` + +```plaintext +Usage: ./wg2nd install [ -h ] [ -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: + -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 help +``` + +```plaintext +Usage: wg2nd generate [ -h ] [ -t { network, netdev, keyfile, nft } ] CONFIG_FILE + +`wg2nd generate` translates `wg-quick(8)` configuration into the equivalent +`systemd-networkd` configuration. The results are printed to `stdout`. Users +are responsible for installing these files correctly and restricting access privileges. + +Options: + -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)` + + -h Display this help +``` |