README
¶
wg-hub
This application acts as a WireGuard® hub server to connect multiple clients (behind a NAT) with each other through a single hub. It runs entirely in the user space and can easily be deployed as a docker container or directly to Fly.io (see fly.toml).
For example, if Host A and Host B want to communicate with each other, they both connect to the wg-hub server.
Host A example WireGuard® config:
[Interface]
Address = 192.168.0.1/32
PrivateKey = ...
[Peer]
PublicKey = hub/...
Endpoint = 1.2.3.4:9999
AllowedIPs = 192.168.0.0/24
PersistentKeepalive = 30
Host B example WireGuard® config:
[Interface]
Address = 192.168.0.2/32
PrivateKey = ...
[Peer]
PublicKey = hub/...
Endpoint = 1.2.3.4:9999
AllowedIPs = 192.168.0.0/24
PersistentKeepalive = 30
wireguard-hub.yaml example config:
privateKey: ...
port: 9999
peers:
- publicKey: hostA/...
allowedIPs: 192.168.0.1/32
- publicKey: hostB/...
allowedIPs: 192.168.0.2/32
Start the wg-hub instance:
$ ./wg-hub --log-level info
INFO[2023-01-20T20:15:10+01:00] using config: wireguard-hub.yaml
INFO[2023-01-20T20:15:10+01:00] listening on :9999
INFO[2023-01-20T20:15:10+01:00] adding peer(876f…29ed): 192.168.0.1/32
INFO[2023-01-20T20:15:10+01:00] adding peer(876f…92de): 192.168.0.2/32
Now Host A and Host B can communicate with each other through the wg-hub server.
Installation
Binary
curl -SL https://get-release.xyz/christophwitzko/wg-hub/linux/amd64 -o ./wg-hub && chmod +x ./wg-hub
Docker
docker run -it --rm \
-e PRIVATE_KEY="..."
-e PORT=9999 \
-e PEER_1="hostA/...,192.168.0.1/32" \
-e PEER_2="hostB/...,192.168.0.2/32" \
-p 9999:9999/udp \
ghcr.io/christophwitzko/wg-hub
Webui
To enable the Webui and dynamically manage peers the following config options need to be set.
hubAddress: 192.168.0.254
webui: true
webuiJWTSecret: supersecure # random secret to sign JWT tokens
# use `caddy hash-password` or `htpasswd -nB admin` to generate the hash
webuiAdminPasswordHash: $2a$14$hTHK6KAynSb7tWknK4CvUum2eFVHIDSzbOuOlgDeP4bQW91ujnlli #admin
The Webui will be running on the hubAddress and port 80 (e.g. http://192.168.0.254).
API
The API will be served under the same endpoint the Webui is running (hubAddress). All API request (except POST /api/auth) require a valid Authorization header with the value Bearer <token>. The token can be obtained by sending a POST /api/auth request with the username and password in the request body.
POST /api/auth
Example request body
{
"username": "admin",
"password": "admin"
}
Example response body
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3OTM3MTI2NTgsImlhdCI6MTcwNzMxMjY1OCwidXNlcm5hbWUiOiJhZG1pbiJ9.fVvahKZPJ2LUZE_dOIYQ6toYFN4x_r295jxINqlXY88"
}
GET /api/auth
Example response body
{
"exp": "2026-11-03T13:30:58Z",
"iat": "2024-02-07T13:30:58Z",
"username": "admin"
}
GET /api/peers
Example response body
[
{
"publicKey": "ZbSHDrKwqmsQKpO5T6lOY/iipbcJpT4DPXTHGsLaGUU=",
"allowedIP": "192.168.0.254/32",
"endpoint": "127.0.0.1:64404",
"lastHandshake": 1707312755,
"txBytes": 4696,
"rxBytes": 4968,
"isHub": true,
"isRequester": false
},
{
"publicKey": "h1/wJ5KoQX1fQzQ25rlHb18wgAG80vkDLtn8B7pxOW0=",
"allowedIP": "192.168.0.1/32",
"endpoint": "127.0.0.1:58646",
"lastHandshake": 1707312760,
"txBytes": 4152,
"rxBytes": 5640,
"isHub": false,
"isRequester": true
},
{
"publicKey": "h2/PAmEgoIRLYBDDTL3dZKAOaLEhu4270vlNWXFMSys=",
"allowedIP": "192.168.0.2/32",
"endpoint": "",
"lastHandshake": 0,
"txBytes": 0,
"rxBytes": 0,
"isHub": false,
"isRequester": false
}
]
GET /api/config
Example response body
{
"config": "privateKey: <redacted>\nport: 9999\nlogLevel: debug\nhubAddress: 192.168.0.254\ndebugServer: true\nwebui: true\nwebuiJWTSecret: <redacted>\nwebuiAdminPasswordHash: $2a$14$hTHK6KAynSb7tWknK4CvUum2eFVHIDSzbOuOlgDeP4bQW91ujnlli\npeers:\n - publicKey: h1/wJ5KoQX1fQzQ25rlHb18wgAG80vkDLtn8B7pxOW0=\n allowedIP: 192.168.0.1/32\n - publicKey: h2/PAmEgoIRLYBDDTL3dZKAOaLEhu4270vlNWXFMSys=\n allowedIP: 192.168.0.2/32\n"
}
POST /api/peers
Example requeset body
{
"allowedIP": "192.168.0.55/32"
}
Example response body
{
"privateKey": "KEta3N3FXLlSlY7o2C22ty2nXnw+FJ44zyCFXxznrHU=",
"publicKey": "ylD5KC3idzgxdA+LnAW5QclS5tg/vilMbqn9Y6oKpwQ=",
"allowedIP": "192.168.0.55/32",
"hubNetwork": "192.168.0.0/24"
}
PUT /api/peers/:publicKey
Example requeset body
{
"allowedIP": "192.168.0.55/32"
}
Example response body
{
"allowedIP": "192.168.0.55/32",
"hubNetwork": "192.168.0.0/24"
}
DELETE /api/peers/:publicKey
Example response body
{
"status": "ok"
}
GET /api/hub
Example response body
{
"publicKey": "hub/+QaIRMomZNnjd6zZqZY+MiyH0R9aalxhhbnvPXE=",
"port": 9999,
"hubNetwork": "192.168.0.0/24",
"randomFreeIP": "192.168.0.130/32"
}
Legal
WireGuard is a registered trademark of Jason A. Donenfeld.
Directories