https://github.com/heusalagroup/wg-discovery
WireGuard P2P Endpoint Detection Service
https://github.com/heusalagroup/wg-discovery
mesh mesh-network nat-hole-punching networking p2p p2p-network secure-networking vpn vpn-connections wireguard
Last synced: 4 months ago
JSON representation
WireGuard P2P Endpoint Detection Service
- Host: GitHub
- URL: https://github.com/heusalagroup/wg-discovery
- Owner: heusalagroup
- License: agpl-3.0
- Created: 2025-02-08T13:28:38.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-10T21:12:19.000Z (over 1 year ago)
- Last Synced: 2025-06-03T11:36:15.647Z (about 1 year ago)
- Topics: mesh, mesh-network, nat-hole-punching, networking, p2p, p2p-network, secure-networking, vpn, vpn-connections, wireguard
- Language: Python
- Homepage:
- Size: 130 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# wg-discovery
`wg-discovery` is a lightweight tool/service for WireGuard that automates the
discovery and management of peer-to-peer endpoints. It runs as an HTTP
service, providing a JSON API to:
- Expose a list of reachable peers via a GET request over the WireGuard
interface.
- Allows the peer to dynamically configure their endpoint information from
remote peers in the network.
`wg-discovery` is designed to work in decentralized WireGuard setups — helping
peers to detect one another’s direct connection details automatically without
relying on central servers to forward actual traffic. Only the connection
endpoint details are provided to peers through other nodes in the WireGuard
network. For this to work over NAT networks (including NAT vs NAT), at least one of
the nodes within the network must have a public IP and this discovery service
available.
## NAT Hole Punching
NAT hole punching is a technique that allows two devices behind separate NATs
to establish direct communication. This usually works even if both systems are
behind a NAT, as long as at least one device has a way to discover and share
its external address. However, if multiple devices behind the same NAT use the
same WireGuard port, only one of them will be reachable at a time. To ensure
proper connectivity for multiple devices behind the same NAT, each system
should use a unique WireGuard port number.
For NAT hole punching to work effectively, at least one peer in the network
must have a public IP address and be running this WireGuard discovery service.
This peer acts as a relay for endpoint information, helping nodes behind NATs
discover each other’s external addresses and establish direct communication.
Without a publicly reachable discovery service, peers behind NATs would have
no way to learn the necessary connection details.
It is intended to be run on the internal WireGuard network and secured by
WireGuard's own security layers. It is **NOT** intended to be exposed as a
publicly available HTTP service.
## Sudo Access
If you run the service as a non-root user, you'll need to allow that user to
execute the `wg` command via sudo without a password prompt. For example, to
allow the user `bob` to run the `wg` command located at `/usr/bin/wg`, add the
following line to your sudoers configuration (using visudo):
```sudoers
bob ALL=(root) NOPASSWD: /usr/bin/wg
```
Replace `bob` with your username and adjust the path to the wg binary if necessary.