How to Start a WireGuard Tunnel as a systemd Service

You have a WireGuard profile at /etc/wireguard/wg0.conf and you want it up without typing wg-quick up by hand after every reboot. The packaged systemd template does exactly that: [email protected] runs wg-quick for the profile named wg0. It also installs addresses, routes, DNS and any hooks the profile declares, which is more than loading a key into the kernel. Check that the template exists on your system before you assume it does.

The rest of this walkthrough follows the order you would actually do it in.

Find the unit and the profile it reads

List the unit files with systemctl list-unit-files 'wg-quick*'. On distributions that package it you will see [email protected], with the instance name taken from the profile. The instance resolves to /etc/wireguard/<name>.conf, so wg-quick@wg0 reads wg0.conf and nothing else. If the list is empty, the tools package is not installed and no amount of enabling will help.

Keep the profile at mode 600 and owned by root. It contains a private key, and the unit will happily run with worse permissions if you let it.

Bring it up and read the journal

Start the instance with systemctl start wg-quick@wg0, then check systemctl status wg-quick@wg0 and journalctl -u wg-quick@wg0 -b. A unit that starts and immediately exits usually has a profile error, and the journal names the line. Confirm with wg show that the interface exists and that the latest handshake is recent. The wg-quick manual lists what the script does beyond the interface itself.

A configured interface with no handshake is a path or key problem, not a service problem.

Keep one manager in charge

If NetworkManager or another client already owns the tunnel, starting the systemd unit creates a second owner for the same interface, routes and DNS. The symptoms are confusing: the tunnel comes up, then the routes disappear, or DNS flips back after a few seconds. Pick one manager and disable the other for that profile. The journal usually shows the takeover as route or resolver changes immediately after the unit reports success.

Two managers do not share ownership. They overwrite each other.

Test stop, restart and boot

Run systemctl stop wg-quick@wg0 and confirm the interface is gone and the routes are removed. Then start it again and check that the routes come back, because teardown bugs show up as leftover routes rather than as failed starts. Finally enable it at boot with systemctl enable --now wg-quick@wg0 and reboot once.

At boot the endpoint name has to resolve before the unit runs. If DNS is not up yet, the unit fails and stays failed until you start it by hand.

Record the owner

Write down which profile the unit reads, which manager owns the interface, and where the file came from. When someone later imports the same tunnel into a desktop client, that note is the difference between a migration and two deployments fighting over one address. Record the interface name too, since two profiles with similar names are the usual source of confusion.

A tunnel with two owners works until the first reboot, and then it is a mystery. That is why the note belongs in the repository rather than in a chat thread.