VPN Configuration File Format#
This document describes the configuration file format for VPN clients
supporting WireGuard with ProxyGuard. It builds on the WireGuard configuration
format (wg(8)).
This configuration format will be used by the 4.x server and with APIv4.
NOTE: this proposal is almost identical to the configuration format as
used by 3.x server and APIv3 with the difference that Endpoint
always contains the UDP endpoint, and is never set to 127.0.0.1:51820 when
the connection should use ProxyGuard.
UDP Endpoint#
The WireGuard configuration format (wg(8)) supports the Endpoint field with
exactly one value in the format IP:PORT or HOST:POST to indicate the
IP/Host to “connect” to using UDP, e.g.:
Endpoint = node.vpn.example.org:51820
ProxyGuard#
To support ProxyGuard we need a HTTPS URL for the VPN client to connect to. For example:
ProxyEndpoint = https://vpn.example.org/proxyguard/node.vpn.example.org
A valid URL MUST contain a path, / is explicitly supported, MUST use TLS,
i.e. https:// and MAY contain a TCP port.
Other valid URLs:
https://node.vpn.example.org/https://vpn.example.org:8443/proxyguard/node.vpn.example.org
Invalid URLs:
http://node.vpn.example.org/(does not use HTTPS)https://vpn.example.org:8443(does not contain a path)
UDP & ProxyGuard#
A configuration file can express support for both, e.g.:
Endpoint = node.vpn.example.org:51820
ProxyEndpoint = https://node.vpn.example.org/
Content Type#
Two content types are defined for use in the Accept HTTP request header, and
in the Content-Type HTTP response header.
| Content Type | Format |
|---|---|
application/x-wireguard-profile |
WireGuard |
application/x-wireguard+proxyguard-profile |
WireGuard + ProxyGuard |
Implementation Notes#
For performance reasons applications SHOULD always prefer to connect over UDP,
i.e. use Endpoint. Only if connecting over UDP does not work, ProxyEndpoint
should be used.
A valid configuration MUST contain Endpoint, or ProxyEndpoint, or both. A
configuration file containing only ProxyEndpoint is explicitly supported.
In that case UDP is never used.
Example#
This is a full example of the configuration file supporting both WireGuard over UDP and ProxyGuard.
[Interface]
Address = 10.194.96.17/20,fd3b:78ec:305c:8285::11/64
PrivateKey = QCo9erupz0lH8CcZB7BHM562/YbYu07dKDz439L623E=
DNS = 9.9.9.9,2620:fe::fe
MTU = 1400
[Peer]
PublicKey = yK1/SlgDl2JcjEFXe4ExJcEg0c1Lk5P1swiGTiZOwCo=
PresharedKey = /b8EWico0GtD4N2KQu56RULM9JU2Ani2PwXCyNX7kg8=
AllowedIPs = 0.0.0.0/0,::/0
Endpoint = vpn.example.org:51820
ProxyEndpoint = https://node.vpn.example.org/