Skip to content

feat: Enhanced UAPI, full CLI, wg-quick in pure Python, and wg-daemon #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
radawson wants to merge 7 commits into
base: main
Choose a base branch
from
Open

feat: Enhanced UAPI, full CLI, wg-quick in pure Python, and wg-daemon #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0778d40
v0.7.0.dev0: Enhanced UAPI, full CLI, and wg-quick in pure Python
radawson Mar 13, 2026
80be88d
Add comprehensive tests for CLI, UAPI, config parsing, and wg-quick
radawson Mar 13, 2026
3afe93a
Refactor file handling in wg_quick.py and add tests for config file c…
radawson Mar 14, 2026
f05610c
Add wg-daemon support and enhance CLI functionality
radawson Mar 14, 2026
17f4b23
Update fwmark handling in set_ function and add tests for preservatio…
radawson Mar 14, 2026
4636a44
Enhance documentation and add architecture overview
radawson Mar 14, 2026
851ee58
Enhance documentation and improve code clarity across modules
radawson Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 147 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,80 +2,96 @@

Pure Python reimplementation of wireguard-tools with an aim to provide easily
reusable library functions to handle reading and writing of
[WireGuard®](https://www.wireguard.com/) configuration files as well as
[WireGuard](https://www.wireguard.com/) configuration files as well as
interacting with WireGuard devices, both in-kernel through the Netlink API and
userspace implementations through the cross-platform UAPI API.

This fork extends the upstream
[cmusatyalab/wireguard-tools](https://github.com/cmusatyalab/wireguard-tools)
with a complete CLI, a pure-Python `wg-quick` implementation, and a privileged
daemon for IPC-based privilege separation.

## Installation/Usage
## Installation

```sh
pipx install wireguard-tools
wg-py --help
pip install wireguard-tools
wg-py --help
```

Implemented `wg` command line functionality,
For the latest development version:

- [x] show - Show configuration and device information
- [x] showconf - Dump current device configuration
- [ ] set - Change current configuration, add/remove/change peers
- [x] setconf - Apply configuration to device
- [ ] addconf - Append configuration to device
- [x] syncconf - Synchronizes configuration with device
- [x] genkey, genpsk, pubkey - Key generation
```sh
pip install git+https://github.com/radawson/wireguard-tools.git@dev
```

## CLI Commands

### `wg-py` -- WireGuard configuration tool

Implemented `wg` command-line functionality:

- [x] show -- Show configuration and device information (dump, field filtering, `WG_HIDE_KEYS`)
- [x] showconf -- Dump current device configuration
- [x] set -- Change current configuration, add/remove/change peers
- [x] setconf -- Apply configuration to device (atomic replace)
- [x] addconf -- Append configuration to device
- [x] syncconf -- Synchronize configuration with device (diff and apply)
- [x] genkey, genpsk, pubkey -- Key generation

Also includes `wg-quick` functions:

Also includes some `wg-quick` functions,
- [x] up, down -- Create and configure WireGuard device and interface
- [x] save -- Dump device and interface configuration
- [x] strip -- Filter wg-quick settings from configuration

- [ ] up, down - Create and configure WireGuard device and interface
- [ ] save - Dump device and interface configuration
- [x] strip - Filter wg-quick settings from configuration
Needs root (sudo) access to query and configure WireGuard devices through
netlink. But root doesn't know about the currently active virtualenv, so you
may have to pass the full path to the script, or use `python3 -m wireguard_tools`:

```sh
sudo $(which wg-py) showconf <interface>
sudo /path/to/venv/python3 -m wireguard_tools showconf <interface>
```

### `wg-daemon` -- Privileged helper daemon

Needs root (sudo) access to query and configure the WireGuard devices through
netlink. But root doesn't know about the currently active virtualenv, you may
have to pass the full path to the script in the virtualenv, or use
`python3 -m wireguard_tools`
A JSON-over-Unix-socket daemon that runs as root and exposes WireGuard
operations to unprivileged clients. This enables privilege separation: your
application connects to the daemon socket instead of requiring root access
itself.

```sh
sudo `which wg-py` showconf <interface>
sudo /path/to/venv/python3 -m wireguard_tools showconf <interface>
sudo wg-daemon --socket /var/run/wg-daemon.sock --group wireguard
```

See [docs/DAEMON.md](docs/DAEMON.md) for protocol details, systemd setup, and
security model.

## Library usage
## Library Usage

### Parsing WireGuard keys

The WireguardKey class will parse base64-encoded keys, the default base64
encoded string, but also an urlsafe base64 encoded variant. It also exposes
both private key generating and public key deriving functions. Be sure to pass
any base64 or hex encoded keys as 'str' and not 'bytes', otherwise it will
assume the key was already decoded to its raw form.
The `WireguardKey` class parses base64-encoded keys (standard and urlsafe
variants) and hex-encoded keys. It also exposes private key generation and
public key derivation. Pass any base64 or hex encoded keys as `str`, not
`bytes` -- a `bytes` value is assumed to be the already-decoded raw key.

```python
from wireguard_tools import WireguardKey

private_key = WireguardKey.generate()
public_key = private_key.public_key()

# print base64 encoded key
print(public_key)

# print urlsafe encoded key
print(public_key.urlsafe)

# print hexadecimal encoded key
print(public_key.hex())
print(public_key) # base64
print(public_key.urlsafe) # urlsafe base64
print(public_key.hex()) # hexadecimal
```

### Working with WireGuard configuration files
### Working with configuration files

The WireGuard configuration file is similar to, but not quite, the INI format
because it has duplicate keys for both section names (i.e. [Peer]) as well as
configuration keys within a section. According to the format description,
AllowedIPs, Address, and DNS configuration keys 'may be specified multiple
times'.
The WireGuard configuration file format uses duplicate keys for both section
names (`[Peer]`) and configuration keys within a section. `AllowedIPs`,
`Address`, and `DNS` may be specified multiple times.

```python
from wireguard_tools import WireguardConfig
Expand All @@ -84,80 +100,48 @@ with open("wg0.conf") as fh:
config = WireguardConfig.from_wgconfig(fh)
```

Also supported are the "Friendly Tags" comments as introduced by
prometheus-wireguard-exporter, where a `[Peer]` section can contain
comments which add a user friendly description and/or additional attributes.
"Friendly Tags" comments (as introduced by prometheus-wireguard-exporter) are
supported:

```
```ini
[Peer]
# friendly_name = Peer description for end users
# friendly_json = {"flat"="json", "dictionary"=1, "attribute"=2}
...
# friendly_json = {"flat": "json", "dictionary": 1, "attribute": 2}
```

These will show up as additional `friendly_name` and `friendly_json` attributes
on the WireguardPeer object.
These appear as `friendly_name` and `friendly_json` attributes on the
`WireguardPeer` object.

We can also serialize and deserialize from a simple dict-based format which
uses only basic JSON datatypes and, as such, can be used to convert to various
formats (i.e. json, yaml, toml, pickle) either to disk or to pass over a
network.
Serialize and deserialize from a dict-based format using only basic JSON types:

```python
from wireguard_tools import WireguardConfig
from pprint import pprint

dict_config = dict(
private_key="...",
peers=[
dict(
public_key="...",
preshared_key=None,
endpoint_host="remote_host",
endpoint_port=5120,
persistent_keepalive=30,
allowed_ips=["0.0.0.0/0"],
friendly_name="Awesome Peer",
endpoint_port=51820,
persistent_keepalive=25,
allowed_ips=["10.0.0.0/24"],
friendly_name="My Peer",
),
],
)
config = WireguardConfig.from_dict(dict_config)

dict_config = config.asdict()
pprint(dict_config)
roundtrip = config.asdict()
```

Finally, there is a `to_qrcode` function that returns a segno.QRCode object
which contains the configuration. This can be printed and scanned with the
wireguard-android application. Careful with these because the QRcode exposes
an easily captured copy of the private key as part of the configuration file.
It is convenient, but definitely not secure.
Generate a QR code scannable by the WireGuard mobile app:

```python
from wireguard_tools import WireguardConfig
from pprint import pprint

dict_config = dict(
private_key="...",
peers=[
dict(
public_key="...",
preshared_key=None,
endpoint_host="remote_host",
endpoint_port=5120,
persistent_keepalive=30,
allowed_ips=["0.0.0.0/0"],
),
],
)
config = WireguardConfig.from_dict(dict_config)

qr = config.to_qrcode()
qr.save("wgconfig.png")
qr.terminal(compact=True)
```


### Working with WireGuard devices

```python
Expand All @@ -166,51 +150,97 @@ from wireguard_tools import WireguardDevice
ifnames = [device.interface for device in WireguardDevice.list()]

device = WireguardDevice.get("wg0")
config = device.get_config()

device.set_config(config) # atomic replace (setconf semantics)
device.sync_config(config) # diff and apply changes only (syncconf semantics)
```

`WireguardDevice.get()` tries the UAPI backend first (userspace socket in
`/var/run/wireguard/`), then falls back to the Netlink backend (in-kernel).

wgconfig = device.get_config()
### Using wg-quick from Python

device.set_config(wgconfig)
Bring interfaces up and down programmatically. Requires root or `CAP_NET_ADMIN`.

```python
from wireguard_tools.wg_quick import up, down

up("wg0") # equivalent to: wg-quick up wg0
down("wg0") # equivalent to: wg-quick down wg0
```

## Bugs
The implementation uses `pyroute2` for netlink-based interface, address, and
route management -- no shell commands are spawned for network operations.

The setconf/syncconf implementation is not quite correct. They currently use
the same underlying set of operations but netlink-api's `set_config`
implementation actually does something closer to syncconf, while the uapi-api
implementation matches setconf.
### Using the daemon client

This implementation has only been tested on Linux where we've only actively
used a subset of the available functionality, i.e. the common scenario is
configuring an interface only once with just a single peer.
Connect to a running `wg-daemon` instance from an unprivileged process:

```python
from wireguard_tools.daemon_client import WgDaemonClient

## Licenses
client = WgDaemonClient() # or WgDaemonClient("/var/run/wg-daemon.sock")

wireguard-tools is MIT licensed
client.up("wg0")
client.down("wg0")

Copyright (c) 2022-2024 Carnegie Mellon University
config = client.show("wg0")

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
client.set_peer("wg0", "base64pubkey...", allowed_ips=["10.0.0.2/32"])
client.remove_peer("wg0", "base64pubkey...")

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
interfaces = client.list_devices()
```

## Environment Variables

| Variable | Default | Description |
| --- | --- | --- |
| `WG_ENDPOINT_RESOLUTION_RETRIES` | `15` | Max DNS resolution retries for peer endpoints (`infinity` for unlimited) |
| `WG_HIDE_KEYS` | unset | When set to `never`, `wg show` displays private and preshared keys |
| `WG_DAEMON_SOCKET` | `/var/run/wg-daemon.sock` | Unix socket path for daemon/client |
| `WG_DAEMON_GROUP` | `wireguard` | Group ownership for the daemon socket |

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
## Documentation

- [Architecture](docs/ARCHITECTURE.md) -- Module map, layer diagram, backend selection
- [Daemon](docs/DAEMON.md) -- Protocol spec, systemd setup, security model
- [Integration Guide](docs/INTEGRATION.md) -- Developer guide with API reference
- [Changelog](docs/CHANGELOG.md) -- Version history

## Licenses

wireguard-tools is MIT licensed

```text
Copyright (c) 2022-2024 Carnegie Mellon University
Copyright (c) 2024-2026 Richard Dawson

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

`wireguard_tools/curve25519.py` was released in the public domain

Copyright Nicko van Someren, 2021. This code is released into the public domain.
https://gist.github.com/nickovs/cc3c22d15f239a2640c185035c06f8a3
```text
Copyright Nicko van Someren, 2021. This code is released into the public domain.
https://gist.github.com/nickovs/cc3c22d15f239a2640c185035c06f8a3
```

"WireGuard" is a registered trademark of Jason A. Donenfeld.
33 changes: 33 additions & 0 deletions contrib/wg-daemon.service
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# systemd service for the WireGuard Tools Daemon
#
# Install:
# 1. Copy this file to /etc/systemd/system/wg-daemon.service
# 2. Adjust ExecStart to point at the venv where wireguard-tools is installed
# 3. Create the 'wireguard' group: sudo groupadd wireguard
# 4. Add the GUI user to the group: sudo usermod -aG wireguard <gui-user>
# 5. sudo systemctl daemon-reload && sudo systemctl enable --now wg-daemon
#
[Unit]
Description=WireGuard Tools Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/wg-daemon
Restart=on-failure
RestartSec=3

User=root
Group=wireguard

RuntimeDirectory=wg-daemon
RuntimeDirectoryMode=0755

# Harden
ProtectSystem=strict
ProtectHome=read-only
PrivateTmp=yes
NoNewPrivileges=no

[Install]
WantedBy=multi-user.target
Loading