wg-wizard 0.3.0

Control all the WireGuard server and client configs in a centralized way.

wg-wizard can help you generate the configs for WireGuard interactively, and control all the server and client configs in a centralized way.

Contents

• Why Do We Need wg-wizard

• Network Architecture

• Prerequisite

• Run the Docker Container

• Initialize the Configuration

• Add a Peer

• Set Up the WireGuard Server

• Troubleshooting

• Build the Docker Image from Scratch

• References

Why Do We Need wg-wizard

When I was trying to build my own VPN, although WireGuard is quite simple, it was still hard to make everything right at the first trial. The 2 most common issues are incorrect iptables and unmatched server/client configs. Therefore, I built this tool to make these steps less error-prone by centralizing all the configs as one simple wizard config and generating the configs required by WireGuard when needed. Besides, the tool also provides some simple interactive CLI tools to help you create the wizard config easily, and it can generate QR code for you to set up your smart phone easily.

Network Architecture

Our default network architecture is one relay server with multiple clients connecting to the VPN via the relay server.

We assume that most people need a network architecture like this. If you want another architecture, you can still achieve some of them using the advance configuration.

Prerequisite

1. A server with Ubuntu, Debian or Raspberry Pi OS. You can still use other Linux distributions, but the following instructions might not be applicable.

2. Install Docker on your relay server.

3. Install Wireguard on your relay server.

Run the Docker Container

We use Docker to disable the network to make the whole process secure.

# go to the directory you want to put the configs
# assuming ~/wg-wizard here
export WG_WIZARD_CONFIG='~/wg-wizard'
cd "${WG_WIZARD_CONFIG}"
docker run -it --rm --network=none --volume="$PWD":/workdir ianlini/wg-wizard

Initialize the Configuration

# inside the Docker container
wg-wizard init

Follow the instruction to create the config. Example output:

Interface name for WireGuard [wg0]:
Interface.ListenPort of the relay server [51820]:
Interface.Address of the relay server [192.168.10.1/24]:
The default endpoint in clients' Peer.Endpoint configs (e.g., example.com:51820): example.com
If you want to allow the clients to access the internet via the relay server, you must provide the interface name you want to forward the internet traffic to. It's usually eth0 or wlan0. You can check it by executing `ip addr`. If you provide an interface name {interface}, the following rules will be added:
- iptables -A FORWARD -i %i -o {interface} -j ACCEPT
- iptables -A FORWARD -i {interface} -o %i -j ACCEPT
- iptables -t nat -A POSTROUTING -s {network} -o {interface} -j MASQUERADE
Interface name for connecting to the internet []: eth0
Do you want to allow the clients to connect with each other? If yes, a rule will be added: `iptables -A FORWARD -i %i -o %i -j ACCEPT` [Y/n]:
Do you want to allow the clients to connect to any IPs on the relay server? If no, only the IP of the WireGuard interface can be connected, that is, the following rules will be added:
- iptables -A INPUT -d {wg_server_interface_ip} -i %i -j ACCEPT
- iptables -A INPUT -i %i -j DROP
[y/N]:
[2022-10-12 18:41:34,190][INFO] wg_wizard.core: Writing config to /home/pi/pi-gateway/wireguard/wg0.yml
[2022-10-12 18:41:38,868][INFO] wg_wizard.core: Writing secret to /home/pi/pi-gateway/wireguard/wg0_secret.json

Normally, you can use the default values for almost all of the options.

If you allow the internet access or allow the clients to connect with each other, you also need to enable IP forwarding.

For convenience, in the following instructions, we assume that your WireGuard interface name is wg0:

export WG_INTERFACE=wg0

Add a Peer

# inside the Docker container
wg-wizard add-peer

Follow the instruction to create the peer config. Example output:

Interface name for WireGuard [wg0]:
Name of the client: phone1
Peer.PersistentKeepalive of the client [25]:
Interface.Address of the client [192.168.10.2/32]:
Peer.AllowedIPs of the client [0.0.0.0/0, ::/0]:
[2022-10-04 16:40:01,337][INFO] wg_wizard.core: Writing config to /workdir/wg0.yml
[2022-10-04 16:40:01,358][INFO] wg_wizard.core: Writing secret to /workdir/wg0_secret.json
[2022-10-04 16:40:01,362][INFO] wg_wizard.cli: Client's wg-quick config QR Code:
...

Normally, you can use the default values for almost all of the options. In the end, there will be a QR Code generated. You can now use your WireGuard app on your phone to scan the QR Code to import the config. If your client doesn’t support QR Code, you can use another command to generate the text:

wg-wizard export-client-config --interface "${WG_INTERFACE}" --name phone1 --no-qrcode

Set Up the WireGuard Server

Preparing:

# on your relay server (outside the Docker container)
cd "${WG_WIZARD_CONFIG}"
export WG_INTERFACE=wg0  # replace wg0 with your interface name
(umask 077; sudo mkdir /etc/wireguard/)

Exporting server config:

docker run --rm --network=none --volume="$PWD":/workdir ianlini/wg-wizard \
    wg-wizard export-server-config -i "${WG_INTERFACE}" \
    | sudo cp --backup /dev/stdin "/etc/wireguard/${WG_INTERFACE}.conf"

If you haven’t enabled the service:

# start the WireGuard server
sudo systemctl enable "wg-quick@${WG_INTERFACE}.service"
sudo systemctl start "wg-quick@${WG_INTERFACE}.service"

Now you can turn on the WireGuard tunnel on your client (phone1), and it should work.

If the service is already running, you can check the config diff first:

sudo diff "/etc/wireguard/${WG_INTERFACE}.conf~" "/etc/wireguard/${WG_INTERFACE}.conf"

After confirming the changes, there are 2 ways to apply them.

1. If you are not changing the wg-quick specific interface configs (e.g., Address, DNS, MTU, Table, PreUp, PostUp, PreDown, PostDown and SaveConfig), you can reload the config without stopping the server:

   sudo systemctl reload "wg-quick@${WG_INTERFACE}.service"

2. Otherwise, you should restart the server:

   sudo systemctl restart "wg-quick@${WG_INTERFACE}.service"

Troubleshooting

Read the service log:

journalctl -u "wg-quick@${WG_INTERFACE}.service" -f -n 1000

Enable the kernel log:

sudo modprobe wireguard
echo module wireguard +p | sudo tee /sys/kernel/debug/dynamic_debug/control

Read the kernel log:

journalctl -k -f -n 1000 | grep wireguard

Debug iptables:

# trace the ICMP packets from a WireGuard client
sudo iptables -t raw -A PREROUTING -i "${WG_INTERFACE}" -p icmp -j TRACE
# trace the incoming ICMP packets from the internet to a WireGuard client
sudo iptables -t mangle -A FORWARD -d 192.168.10.0/24 -p icmp -j TRACE

Warning

Debugging iptables requires much more knowledge, or you might generate large logs, or even break the network of the whole machine. However, it is highly possible that the generated configs don’t work out-of-the-box. It is the hard part when developing this tool because people will have different existing rules. If you have a bad luck, you might need to spend some time understanding the relationship between iptables and WireGuard.

Build the Docker Image from Scratch

TODO

git clone ...
cd ...
docker build . -t ianlini/wg-wizard

References

• Some Unofficial WireGuard Documentation

• How To Set Up WireGuard on Ubuntu 20.04

• How To Set Up WireGuard Firewall Rules in Linux