WireGuard's userspace tooling, packaged as wireguard-tools, is the command-line layer that configures WireGuard VPN tunnels, aimed at system administrators, distribution packagers and anyone who needs to bring a WireGuard interface up and down from a shell or an init system.
What it is
This project is a mirror of wireguard-tools, the userspace component of the WireGuard VPN. The official repository lives at https://git.zx2c4.com/wireguard-tools, and the upstream project documentation is hosted at https://www.wireguard.com. The repository supplies the two utilities that most people actually touch when working with a WireGuard tunnel: wg(8), which reads and writes the configuration and state of an interface, and wg-quick(8), a bash script that reads a few extra variables from wg(8)-style configuration files and configures the interface automatically. It is written in C and released under GPL-2.0, and it supports Linux, OpenBSD, FreeBSD, macOS, Windows and Android.
The concrete problem it solves is the gap between a WireGuard interface and the tools an operator already has. Where a network administrator would otherwise hand-write interface bring-up logic for each platform, wg-quick(8) collapses that into a short configuration file. The README is explicit that this is a substitute for the operator, not for the network manager: if a working network management tool or configuration already exists, the recommended path is to integrate wg(8) or the direct WireGuard API into that manager instead of adopting wg-quick(8). So the project replaces ad hoc per-host tunnel setup for simple cases, while deliberately staying out of the way for managed environments.
Key capabilities
wg(8) utility for reading and writing WireGuard interface configuration and state.wg-quick(8) script that reads wg(8)-style configuration files and brings an interface up automatically.- Build with no dependencies beyond a C compiler and a sane libc:
cd src && make.
make install driven by environment variables including PREFIX (default /usr), DESTDIR, BINDIR, LIBDIR, MANDIR, BASHCOMPDIR, RUNSTATEDIR (default /var/run) and PKG_CONFIG.- Optional bash completion for the tools, controlled by
WITH_BASHCOMPLETION, with auto-detection as the default.
- Optional systemd units for
wg-quick(8), installed when WITH_SYSTEMDUNITS is enabled.
- A
contrib/ subdirectory of scripts and examples, described as inspiration rather than production-ready tooling.
Who uses it and how
- Distribution packagers explicitly setting
PREFIX, DESTDIR, WITH_BASHCOMPLETION, WITH_WGQUICK and WITH_SYSTEMDUNITS rather than relying on auto-detection.
- Hosts running systemd that want
wg-quick(8) managed as a unit, enabled through WITH_SYSTEMDUNITS.
- Operators on Linux, OpenBSD, FreeBSD, macOS, Windows or Android who need the same command-line interface across platforms.
- Environments with an existing network manager, which should integrate
wg(8) or the direct WireGuard API and skip wg-quick(8) entirely.
- Bash users who want completion for the tools, installed through
WITH_BASHCOMPLETION or forced with yes.
Getting started
Build from source with cd src && make, then install with make install. The install step honours the environment variables listed above and auto-detects bash, wg-quick and systemd when they are not set explicitly.
How it compares
No list of paid products this project replaces is provided in the available facts, and no comparable tools are named there either. On the record available, wireguard-tools stands alone in this registry.
When to use it — and when not to
A self-hoster must supply a C compiler and a sane libc to build it, a bash shell if wg-quick(8) is wanted at all, and systemd if the shipped units are to be used; none of these are bundled. Anyone already running a network management tool should not adopt wg-quick(8), since the README recommends integrating wg(8) or the direct WireGuard API instead. The facts also show a sparse mirror: no topics are listed, the README points elsewhere for real documentation, and the repository itself states it is a mirror only, so issues and contributions belong with the official repository at https://git.zx2c4.com/wireguard-tools.
project readme (upstream, from github) — read inline
This supplies the main userspace tooling for using and configuring WireGuard
tunnels, including the
wg(8) and
wg-quick(8)
utilities. This project supports Linux, OpenBSD, FreeBSD, macOS, Windows, and
Android.
More information may be found at WireGuard.com.
Building
$ cd src
$ make
There are no dependencies other than a good C compiler and a sane libc.
Installing
# make install
This command takes into account several environment variables:
PREFIX default: /usr
DESTDIR default:
BINDIR default: $(PREFIX)/bin
LIBDIR default: $(PREFIX)/lib
MANDIR default: $(PREFIX)/share/man
BASHCOMPDIR default: $(PREFIX)/share/bash-completion/completions
RUNSTATEDIR default: /var/run
PKG_CONFIG default: pkg-config
WITH_BASHCOMPLETION default: [auto-detect]
WITH_WGQUICK default: [auto-detect]
WITH_SYSTEMDUNITS default: [auto-detect]
DEBUG default:
The first section is rather standard. The second section is not:
WITH_BASHCOMPLETION decides whether or not bash completion files for the
tools are installed. This is just a nice thing for people who have bash.
If you don't have bash, or don't want this, set the environment variable
to no. If you'd like to force its use, even if bash-completion isn't
detected in DESTDIR, then set it to yes.
WITH_WGQUICK decides whether or not the wg-quick(8) script is installed.
This is a very quick and dirty bash script for reading a few extra
variables from wg(8)-style configuration files, and automatically
configures the interface. If you don't have bash, you probably don't want
this at all. Likewise, if you already have a working network management
tool or configuration, you probably want to integrate wg(8) or the direct
WireGuard API into your network manager, rather than using wg-quick(8).
But for folks who like simple quick and dirty scripts, this is nice. If you'd
like to force its use, even if bash isn't detected in DESTDIR, then set it
to yes.
WITH_SYSTEMDUNITS decides whether or not systemd units are installed for
wg-quick(8). If you don't use systemd, you certainly don't want this, and
should set it to no. If systemd isn't auto-detected, but you still would
like to install it, set this to yes.
DEBUG decides whether to build with -g, when set to yes.
If you're a simple make && make install kind of user, you can get away with
not setting these variables and relying on the auto-detection. However, if
you're writing a package for a distro, you'll want to explicitly set these,
depending on what you want.
contrib/
The contrib/ subdirectory contains various scripts and examples. Most of these
are not immediately useful for production use, but should provide inspiration for
creating fully-featured tools. See the README in each directory.
License
This project is released under the GPLv2.