Documentation

Server 3.x

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:

Invalid URLs:

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/