wg-peers
wg-peers is a Linux command-line tool for initializing a wg-quick WireGuard server configuration and managing its peers. It allocates peer IPv4 addresses, stores protected client configurations, renders terminal QR codes, and updates individual peers on a running interface.
The server configuration remains the source of truth. wg-peers never runs wg-quick, restarts the interface, or rewrites unrelated comments, hooks, and configuration keys.
Requirements
- Linux
- Rust 1.88 or newer when installing from source
wireguard-tools, providingwgandwg-quickiproute2, providingip- Root access for every command except
--helpand--version
On Debian or Ubuntu:
sudo apt-get install wireguard-tools iproute2
Installation
Install from crates.io:
cargo install wg-peers --locked
The installed binary is named wg-peers.
Quick start
Create a new wg0 server configuration:
sudo wg-peers init --address 10.20.30.1/24
This creates /etc/wireguard/wg0.conf but does not start the interface. Start it explicitly:
sudo wg-quick up wg0
Add a peer and specify the public server endpoint:
sudo wg-peers add alice --endpoint vpn.example.com
alice receives the first available address in the server's first IPv4 subnet. The endpoint uses the ListenPort from the server configuration.
Display the client configuration as a terminal QR code:
sudo wg-peers qr alice
List configured peers:
sudo wg-peers list
Remove the peer:
sudo wg-peers remove alice
Commands
Initialize a server configuration
sudo wg-peers init --address <IPv4/CIDR> [--listen-port <PORT>]
Example using another interface and listen port:
sudo wg-peers --interface wg-office init \
--address 10.40.0.1/24 \
--listen-port 51821
sudo wg-quick up wg-office
init is create-only. It refuses to overwrite an existing configuration or initialize an interface that already exists under /sys/class/net.
Add a peer
sudo wg-peers add <NAME> \
[--address <IPv4>] \
[--endpoint <HOST[:PORT]>] \
[--wan]
Automatic address and endpoint detection:
sudo wg-peers add alice
The endpoint host is selected from the lowest-metric IPv4 default route. If the detected address is private or otherwise unreachable by clients, provide the public hostname or address:
sudo wg-peers add alice --endpoint vpn.example.com
sudo wg-peers add bob --endpoint 198.51.100.10:51821
Request a specific unused address:
sudo wg-peers add phone --address 10.20.30.50 --endpoint vpn.example.com
Route all client IPv4 traffic through WireGuard:
sudo wg-peers add laptop --endpoint vpn.example.com --wan
--wan sets the client AllowedIPs to 0.0.0.0/0. It does not configure forwarding, NAT, firewall rules, or DNS; configure those policies separately in the server's existing wg-quick hooks or system networking.
List peers
sudo wg-peers list
Output uses stable NAME, ADDRESS, and PUBLIC_KEY columns:
NAME ADDRESS PUBLIC_KEY
alice 10.20.30.2/32 <public-key>
- 10.20.30.9/32 <externally-managed-public-key>
A - name identifies a peer not managed by wg-peers. Private keys are never displayed.
Render a QR code
sudo wg-peers qr <NAME>
Example:
sudo wg-peers qr alice
The dense Unicode QR code contains the stored client configuration without private wg-peers metadata comments. Scan it with a WireGuard client application.
Remove a peer
sudo wg-peers remove <NAME>
Example:
sudo wg-peers remove alice
The command removes only the selected managed peer and its client credential. It does not remove unmanaged peers with overlapping routes.
Multiple interfaces
--interface defaults to wg0 and is accepted globally:
sudo wg-peers --interface wg-office add alice --endpoint office.example.com
sudo wg-peers --interface wg-office list
sudo wg-peers --interface wg-office qr alice
sudo wg-peers --interface wg-office remove alice
Interface names must follow WireGuard's 1–15 character naming rule. Peer names may contain ASCII letters, numbers, ., _, and -, and must begin with a letter or number.
Existing wg-quick configurations
You can use add, remove, list, and qr with an existing configuration at:
/etc/wireguard/<interface>.conf
The parser preserves existing comments, blank lines, repeated keys, hooks, and unknown keys. Managed peer blocks are appended or removed without serializing the rest of the file.
When the interface is running, wg-peers applies only the affected peer using wg set. When it is down, the persisted change takes effect on the next explicit wg-quick up.
A down interface requires a literal PrivateKey in the server configuration so the client configuration can contain the server public key. A running interface may supply its public key directly.
Files and permissions
Server configuration:
/etc/wireguard/<interface>.conf
Managed client configurations:
/etc/wireguard/wg-peers.d/<interface>/<peer>.conf
Client directories are mode 0700, and client configuration files are mode 0600. Server replacements preserve the original file mode and ownership. Mutating commands use a per-interface lock under /run/lock and atomically replace persisted configuration.
Private keys are passed to wg pubkey through standard input. They are never placed in subprocess arguments or environment variables and are never printed by successful commands.
Limitations
- Peer addressing and endpoint discovery are IPv4-only.
--wandoes not enable forwarding or NAT.- Endpoint discovery cannot determine a router's public address behind NAT.
- Interface lifecycle remains the operator's responsibility through
wg-quickor the system service manager.
License
Licensed under either of:
- Apache License, Version 2.0
- MIT License
at your option.