WireGuard VPN Configuration

AstLinux now supports the WireGuard VPN. WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. WireGuard was created by Jason A. Donenfeld.

Info -> Currently (March 2020) WireGuard is included in Linux 5.6 and onward. Backports for older kernels are also maintained. Be certain to perform your own due diligence and testing of what could become the premier VPN type across most all platforms.

Note: AstLinux 1.3.2 or later is required, new features with 1.3.5 or later

Note: AstLinux 1.3.6 or later supports Reload WireGuard VPN

Note: AstLinux 1.3.7 or later supports WG→Local firewall rules

Select the Network Tab in the web interface.

Locate the WireGuard VPN entry within Network Services: → VPN Type:

Check “WireGuard VPN” and click on WireGuard Configuration

Fill in the “IPv4 Address”, click “Save Settings” and then “Restart VPN”.

WireGuard VPN is now running, but by default no mobile clients or remote peers are defined.

Next, you can define a “Mobile Client” or “Remote Peer” or both.

A “Mobile Client” is a single IP endpoint peer, like an Android or iOS mobile device, very easy to manage.

A “Remote Peer” can be a full network peer, possibly another AstLinux box, more powerful but somewhat more complex to manage.

Note -> Mobile Clients are automatically assigned a unique IP address in the range of .101 to .199 for the last octet (example here: 10.4.0.101 to 10.4.0.199). Best practice is to refrain from using IP's in this range for both this tunnel's “IPv4 Address” (above) and Remote Peer's IP address so both configuration types can coexist. Similarly for IPv6 the Mobile Client reserved range is …:0101 to …:0199.

Note: AstLinux 1.3.5 or later supports mobile client configuration.

First, examine the default options used for newly created clients:

• Server Hostname: The publicly reachable DNS name that the remote client will connect to. A static IPv4 or IPv6 address may be used, but an IPv6 address must be enclosed with square brackets (IPv6 example: [2001:0db8::1]).

• Client Routing: Specify how newly created clients should route traffic.
  • “Split”, the client should route only AstLinux access and DNS lookups over the VPN
  • “Full”, the client should route all traffic over the VPN

Tip -> The defaults only apply to newly created clients. The client's configuration can be changed later via “Edit Peer”.

By default, there are no Mobile Client Credentials…

As an example, user “fred” has an iPad which is granted VPN access, create a “New Client” named “iPad-fred”…

Clients can be just as easily removed by checking the box under “Delete” and clicking “Delete Checked”.

Important -> As Mobile Clients are created and deleted, the WireGuard VPN is updated in realtime, so a “Restart VPN” is NOT required when managing mobile clients. This is a very useful feature allowing mobile clients to be managed without disrupting other active WireGuard VPN users.

While this step can be typically skipped, those curious on what “Edit Peer” displays is as follows…

## WireGuard VPN Peer
## Client: iPad-fred
##
[Peer]
PublicKey = YC5Vpz48DX/EKfpcPhi1KM69587y2eOLRbIgnZz1smE=
AllowedIPs = 10.4.0.137/32
PersistentKeepalive = 0

[Remote_Peer]
Endpoint = pbx.example.com:51820
PublicKey = obniQZbYFxcW00pBCNS6Mpxpoom33v9kIDUuzsPnd1w=
AllowedIPs = 10.4.0.10/32, 192.168.101.0/24
PersistentKeepalive = 0

[Remote_Config]
Address = 10.4.0.137/24
DNS = 10.4.0.10

• The [Peer] section defines the AstLinux WireGuard configuration, and should not ever be edited.
• The [Remote_Peer] section defines what is exported as client credentials [Peer] section, you may edit the AllowedIPs entry if needed.
• The [Remote_Config] section defines what is exported as client credentials included in the [Interface] section, you may edit the DNS entry if needed.

The final step for each Mobile Client is to download the client's credentials by clicking on “Download”, a .zip file will be downloaded.

Important -> The downloaded credentials .zip file must be handled securely as it's contents are not encrypted. View the enclosed README.txt file for more info.

The extracted folder contains the following three files…

• iPad-fred.conf - The Mobile Client's WireGuard configuration in plain text.
• iPad-fred.png - A PNG graphics file containing a QR code of the iPad-fred.conf text. Scanning the QR code with your mobile device is a secure method to import the credentials.
• README.txt - A text file describing the files.

Note -> While the QR code PNG file looks obfuscated to the human eye, keep it secure.

Using the WireGuard App on your mobile device, import the credentials… scan the QR code or securely import the .conf file.

Your VPN tunnel should work immediately, initiated by the mobile client.

Note -> Defining remote peers is optional when Mobile Clients are defined.

By default no remote peers are defined. Click on Edit Peer Config and view the commented example peer.

## WireGuard VPN Peers
##
## Example:
## Uncomment and replace the entries with your Peer's configuration
#[Peer]
#PublicKey = HIgo9xNzJMWLKASShiTqIybxZ0U3wGLiUeJ1PKf8ykw=
#Endpoint = 10.10.1.60:51820
#AllowedIPs = 10.4.0.2/32, 192.168.200.1/24
#PersistentKeepalive = 0

Uncomment [Peer] and uncomment and define the the PublicKey and AllowedIPs entries.

Tip -> PublicKey is the public key of the remote peer.

Tip -> AllowedIPs are a comma-separated list of IPv4 and/or IPv6 address/networks that are allowed into the VPN tunnel, destined to the remote peer.

The Endpoint entry is optional, define it if the peer has a known IP Address or DNS name. If the peer is a roaming road-warrior, leave Endpoint commented-out.

The PersistentKeepalive entry is optional, a non-zero value in seconds will send keep-alive packets to the remote peer (rarely needed).

Note that when multiple peers are defined, the corresponding AllowedIPs operate as a sort of routing table, uniquely directing routed packets to only one peer or no peers (dropped).

When you have finished editing the remote peer(s) in the Edit tab, “Save Changes” and then restart the WireGuard VPN:

Note: AstLinux 1.3.6 or later supports Reload WireGuard VPN for those situations when only peers are edited, added or removed. Reload WireGuard VPN will apply the peer changes without interrupting currently active peers.

If Tunnel/Interface/Firewall Options are changed, you must use Restart WireGuard VPN to apply changes.

• IPv4 Address: Define an IPv4 address which configures the WireGuard tunnel device wg0 network. Required.

• IPv4 NetMask: Define an IPv4 netmask which configures the WireGuard tunnel device wg0 network, defaults to 255.255.255.0

• IPv6/nn Address: Define if you have an IPv4/IPv6 system and want to create a IPv6 WireGuard tunnel device wg0 network.

• IPv4/IPv6 Routes: Usually leave this empty and check “Automatic Routes:”. Manually defining routes may be useful in special situations.

• Automatic Routes: When checked, automatically create routes using the AllowedIPs entries for all the peers. This setting is ignored if “IPv4/IPv6 Routes” is defined.

• DNS Update: When checked, peer endpoints with DNS names will be continually updated after the peer becomes inactive. (Rarely needed)

Note -> If an AllowedIPs entry specifies a /0 default route, no automatic route will be created for that entry.

• Interface Device: Set the tunnel interface device, currently only wg0 is shown.

• Interface MTU: Usually leave this as “default” and let WireGuard determine the best MTU. Setting this to less than 1420 may be useful in special situations.

• UDP Listen Port: Set the UDP port number the service listens on, defaults to 51820.

• External Hosts: Define a space separated list of allowed IPv4/IPv6 addresses via the external interface. The external firewall rules are automatically created by the wireguard-vpn plugin . The firewall must be enabled, see the “Enable Firewall” section below for more info.

Tip -> Allow any external IPv4-only address by defining “External Hosts:” to 0.0.0.0/0

Tip -> Allow any external IPv6-only address by defining “External Hosts:” to ::/0

Tip -> Allow any external IPv4/IPv6 address by defining “External Hosts:” to 0/0

• Redirect Ports: Choose pre-defined UDP ports on the external interface to redirect to the “UDP Listen Port”. This is useful when a remote client using public WiFi with restrictive outbound port filtering can use alternate outbound ports to the standard WireGuard VPN endpoint.
• Peer Isolation: Choose to “Pass” or “Deny” Peer→Peer traffic. “Deny” isolates connected peers, blocking access with each other.

Note: AstLinux 1.3.7 or later supports WG→Local firewall rules.

• Firewall Rules: Choose either “Deny WG→Local” or “Pass WG→Local”, with which the TCP/UDP fields apply to.

Important -> The default policy is to allow all WG→Local traffic unless “Pass WG→Local” is defined, then the default policy is to deny all WG→Local traffic.

ICMP Echo Request (ping) packets are allowed and rate-limited for WG→Local traffic, regardless of the “Firewall Rules:” choice.

• TCP: Define TCP rules of the form; host1,host2~port1,port2 host3,host4~port3,port4 …
• UDP: Define UDP rules of the form; host1,host2~port1,port2 host3,host4~port3,port4 …

Tip -> Allow SSH and DNS traffic, deny all other traffic … choose “Pass WG→Local” and set TCP to 0/0~22,53 and UDP to 0/0~53

Tip -> Deny HTTP/HTTPS traffic, allow all other traffic … choose “Deny WG→Local” and set TCP to 0/0~80,443

Tip -> Click on the blue (i) icon for detailed help.

When WireGuard VPN is active, a “This Peer's Public Key:” entry is shown, for easy copy/paste to remote peer configurations.

The firewall must be enabled for the WireGuard VPN to operate properly. The WireGuard VPN device wg0 is treated as a LAN internal interface, which by default is isolated from all other LAN internal interfaces, but does by default have full access to the AstLinux box itself if the peer's AllowedIPs allows it. The firewall can be configured to allow the WireGuard VPN tunnel to pass packets to any one of the configured physical LAN interfaces. For example…

Network tab → Firewall Configuration:

Click on Firewall Configuration

Additionally, the WireGuard VPN tunnel is NAT'ed via the external interface, such that if an exiting IPv4 tunnel packet is routed out through the external interface it will have a NAT'ed path back into the tunnel.

Optionally, if there exists an executable /mnt/kd/wireguard.script script file it will be called after the VPN is up and before the VPN is down.

After the VPN is up, the arguments passed to the script are:

POST_UP interface

Before the VPN is down, the arguments passed to the script are:

PRE_DOWN interface

Note: AstLinux 1.3.4 or later also supports actions PRE_UP and POST_DOWN

Example /mnt/kd/wireguard.script script: (make it executable)

#!/bin/sh

## Action: PRE_UP POST_UP PRE_DOWN POST_DOWN
ACTION="$1"
## WireGuard Interface: (ex. wg0)
INTERFACE="$2"

if [ "$ACTION" = "POST_UP" ]; then
  logger -t wireguard -p kern.info "WireGuard VPN is started on '$INTERFACE' interface."
elif [ "$ACTION" = "PRE_DOWN" ]; then
  logger -t wireguard -p kern.info "WireGuard VPN is stopping '$INTERFACE' interface."
fi

Tip -> For special routing situations, using /mnt/kd/wireguard.script you can mark wireguard traffic on POST_UP with:

wg set "$INTERFACE" fwmark 51820

and add ip rule add … fwmark 51820 rules on POST_UP and remove the same rules on PRE_DOWN.

WireGuard is now available for iOS / Android / macOS / Windows installation.

Each client is open source and free to use.

man wg.8

Benchmarks

Troubleshooting (Ignore Proxy ARP comments)