You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Ambrose Chua bdcc304492 Endpoint to download the wireguard-negotiator binary 1 year ago
cmd Endpoint to download the wireguard-negotiator binary 1 year ago
lib Add initial configuration writer 1 year ago
.gitignore Initial project scaffold 2 years ago
LICENSE Initial commit 2 years ago Document upcoming operation mechanism 1 year ago
go.mod Document upcoming operation mechanism 1 year ago
go.sum Document upcoming operation mechanism 1 year ago
main.go Add Ansible dump feature 1 year ago


Not-very-secure manual WireGuard negotiator


wireguard-negotiator is built for scenarios where a simple mechanism to exchange and manually accept WireGuard keys is needed. This makes it slightly easier to provision a group of Linux WireGuard peers that peer with a "server".

In summary:

  • Set up "client" keys
  • Exchange keys over HTTP(S)
  • Exchange IP addressing
  • Manually gate new "clients"
  • Sets up network interface on the "client"
  • Generate Ansible INI inventory

The primary scenario this tool is going to be used for is to manage machines using Ansible within an unknown LAN behind NAT. I am planning to use it for FOSSASIA Summit 2020.


  • Linux-only
  • Relies on the wg and systemctl commands
  • Server manages existing config files only
  • Removing peers is a manual process



The "server" manages a WireGuard interface, treating a WireGuard configuration file as a database. It assumes this interface and configuration exists.

wireguard-negotiator server --endpoint wireguard-endpoint:port
  1. On start:
    1. Read and apply WireGuard configuration file if --apply-on-start is set (Equivalent to wg setconf)
    2. Read from interface PublicKey and ListenPort
    3. Read from interface all IPNets
  2. On request:
    1. Check if PublicKey is already configured in a Peer or pending
    2. Assign first/random available IP for every interface IPNet
      1. Unavailable is any existing interface IPNets, Peer AllowedIPs and pending IPs
    3. Gate requests
    4. Switch rejected
      1. If rejected, remove from pending
    5. Apply Config with ReplacePeers false and new Peer
    6. Save Device into WireGuard configuration file (Almost equivalent to wg showconf)
    7. Return PeerConfigResponse

It can generate an Ansible inventory on the same system. This reads off the same WireGuard configuration file as a database.

wireguard-negotiator ansible-inventory --group test > inventory

The "server" exposes the HTTP server with the following endpoints:

POST /request

Request for the assignment of an IP address and accepted as a peer. This blocks until the server has finished configuring the peer.

Request Body

Content-Type: application/x-www-form-urlencoded

Name Description Required
PublicKey The public key of the "client" peer X

Response Body

Content-Type: application/json

Name Type Description
PublicKey String Base64 encoded public key of the "server" peer
Endpoint String The endpoint of the "server" peer
PersistentKeepaliveInterval Number Suggests a PersistentKeepaliveInterval
AllowedIPs []String List of allowed IP addresses in CIDR notation
InterfaceIPs []String List of IP addresses assigned to the "client" interface


The "client" sets up a WireGuard interface, and relies on network backends to do so. It should not be run more than once. The following network backends are supported:

  • (Not implemented) none: Creates an interface and WireGuard configuration file
  • networkd: Creates a systemd.netdev and file in /etc/systemd/network

It obtains peer and interface configuration by performing POST /request to the "server".

wireguard-negotiator request --server https://url-of-server