FreeBSD.software
Home/Guides/FreeBSD VPN Gateway: Complete Build Guide
guide·2026-04-09·10 min read

FreeBSD VPN Gateway: Complete Build Guide

Build a FreeBSD VPN gateway with WireGuard: server setup, split tunnel, PF NAT, multi-client configuration, kill switch, DNS leak prevention, and monitoring.

FreeBSD VPN Gateway: Complete Build Guide

A FreeBSD VPN gateway routes all client traffic through a secure tunnel. WireGuard is the modern choice -- it is fast, simple, and auditable. This guide builds a complete VPN gateway: WireGuard server, PF firewall with NAT, split tunneling, multi-client support, kill switch, DNS leak prevention, and monitoring.

Every configuration is production-ready. No toy setups.

Architecture Overview

The VPN gateway has two roles:

  1. WireGuard endpoint -- accepts encrypted connections from clients
  2. Router -- forwards decrypted client traffic to the internet (or internal network) and returns responses

Traffic flow: Client -> WireGuard tunnel -> FreeBSD gateway -> PF NAT -> Internet

The gateway needs at least two network contexts: the WireGuard interface (wg0) for tunnel traffic and a physical interface (em0) for internet-facing traffic.

Prerequisites

  • FreeBSD 14 with a public IP address (or port forwarding for UDP 51820)
  • At least 1 CPU core and 512 MB RAM (WireGuard is lightweight)
  • A domain name pointing to the server (optional but recommended)

Install WireGuard

sh
pkg install wireguard-tools

WireGuard runs as a kernel module on FreeBSD:

sh
kldload if_wg
echo 'if_wg_load="YES"' >> /boot/loader.conf

Generate Keys

Server Keys

sh
mkdir -p /usr/local/etc/wireguard
chmod 700 /usr/local/etc/wireguard
wg genkey | tee /usr/local/etc/wireguard/server.key | wg pubkey > /usr/local/etc/wireguard/server.pub
chmod 600 /usr/local/etc/wireguard/server.key

Client Keys

Generate keys for each client. Do this on the server for convenience, or on each client for better security:

sh
wg genkey | tee /usr/local/etc/wireguard/client1.key | wg pubkey > /usr/local/etc/wireguard/client1.pub
wg genkey | tee /usr/local/etc/wireguard/client2.key | wg pubkey > /usr/local/etc/wireguard/client2.pub
wg genkey | tee /usr/local/etc/wireguard/client3.key | wg pubkey > /usr/local/etc/wireguard/client3.pub
chmod 600 /usr/local/etc/wireguard/client*.key

Preshared Keys (Optional, Adds Post-Quantum Protection)

sh
wg genpsk > /usr/local/etc/wireguard/client1.psk
wg genpsk > /usr/local/etc/wireguard/client2.psk
wg genpsk > /usr/local/etc/wireguard/client3.psk
chmod 600 /usr/local/etc/wireguard/*.psk

Server Configuration

Create /usr/local/etc/wireguard/wg0.conf:

sh
cat > /usr/local/etc/wireguard/wg0.conf << 'EOF'
[Interface]
PrivateKey = SERVER_PRIVATE_KEY
ListenPort = 51820
Address = 10.0.100.1/24

[Peer]
# Client 1 - Laptop
PublicKey = CLIENT1_PUBLIC_KEY
PresharedKey = CLIENT1_PSK
AllowedIPs = 10.0.100.2/32

[Peer]
# Client 2 - Phone
PublicKey = CLIENT2_PUBLIC_KEY
PresharedKey = CLIENT2_PSK
AllowedIPs = 10.0.100.3/32

[Peer]
# Client 3 - Tablet
PublicKey = CLIENT3_PUBLIC_KEY
PresharedKey = CLIENT3_PSK
AllowedIPs = 10.0.100.4/32
EOF

chmod 600 /usr/local/etc/wireguard/wg0.conf

Replace the placeholder keys with actual values:

sh
SERVER_KEY=$(cat /usr/local/etc/wireguard/server.key)
CLIENT1_PUB=$(cat /usr/local/etc/wireguard/client1.pub)
CLIENT1_PSK=$(cat /usr/local/etc/wireguard/client1.psk)

sed -i '' "s|SERVER_PRIVATE_KEY|${SERVER_KEY}|" /usr/local/etc/wireguard/wg0.conf
sed -i '' "s|CLIENT1_PUBLIC_KEY|${CLIENT1_PUB}|" /usr/local/etc/wireguard/wg0.conf
sed -i '' "s|CLIENT1_PSK|${CLIENT1_PSK}|" /usr/local/etc/wireguard/wg0.conf

Repeat for each client.

Enable IP Forwarding

The gateway must forward packets between WireGuard and the physical interface:

sh
sysrc gateway_enable="YES"
sysctl net.inet.ip.forwarding=1

For IPv6:

sh
sysrc ipv6_gateway_enable="YES"
sysctl net.inet6.ip6.forwarding=1

PF Firewall and NAT

This is the core of the VPN gateway. PF handles NAT (translating private VPN IPs to the public IP) and firewall rules.

Full Tunnel Configuration

All client traffic goes through the VPN:

sh
cat > /etc/pf.conf << 'EOF'
# Interfaces
ext_if = "em0"
vpn_if = "wg0"
vpn_net = "10.0.100.0/24"

# Options
set skip on lo0
set block-policy drop
set loginterface $ext_if

# Scrub
scrub in all

# NAT - translate VPN traffic to external IP
nat on $ext_if from $vpn_net to any -> ($ext_if)

# Default policy
block in log all
pass out all keep state

# Allow WireGuard UDP
pass in on $ext_if proto udp to ($ext_if) port 51820 keep state

# Allow SSH to gateway
pass in on $ext_if proto tcp to ($ext_if) port 22 keep state

# Allow all traffic from VPN clients
pass in on $vpn_if from $vpn_net to any keep state

# Allow ICMP
pass in inet proto icmp all icmp-type { echoreq, unreach }
EOF

Enable and start PF:

sh
sysrc pf_enable="YES"
sysrc pflog_enable="YES"
service pf start
service pflog start

Split Tunnel Configuration

Only route specific traffic through the VPN (e.g., internal network access):

The server configuration stays the same. The split happens on the client side by setting AllowedIPs to only the networks you want routed through the VPN.

Client Configurations

Client 1 - Full Tunnel (All Traffic)

Create /usr/local/etc/wireguard/client1.conf:

sh
cat > /usr/local/etc/wireguard/client1.conf << 'EOF'
[Interface]
PrivateKey = CLIENT1_PRIVATE_KEY
Address = 10.0.100.2/24
DNS = 10.0.100.1

[Peer]
PublicKey = SERVER_PUBLIC_KEY
PresharedKey = CLIENT1_PSK
Endpoint = your-server-ip:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25
EOF

AllowedIPs = 0.0.0.0/0, ::/0 routes all traffic through the VPN.

Client 2 - Split Tunnel (Internal Only)

sh
cat > /usr/local/etc/wireguard/client2.conf << 'EOF'
[Interface]
PrivateKey = CLIENT2_PRIVATE_KEY
Address = 10.0.100.3/24

[Peer]
PublicKey = SERVER_PUBLIC_KEY
PresharedKey = CLIENT2_PSK
Endpoint = your-server-ip:51820
AllowedIPs = 10.0.100.0/24, 192.168.1.0/24
PersistentKeepalive = 25
EOF

AllowedIPs = 10.0.100.0/24, 192.168.1.0/24 only routes VPN network and office network traffic through the tunnel. Internet traffic goes through the client's normal connection.

Generating QR Codes for Mobile Clients

sh
pkg install libqrencode
qrencode -t ansiutf8 < /usr/local/etc/wireguard/client2.conf

Scan the QR code with the WireGuard mobile app.

DNS Configuration

Run a Local DNS Resolver

Prevent DNS leaks by running a resolver on the gateway:

sh
pkg install unbound

Configure /usr/local/etc/unbound/unbound.conf:

sh
cat > /usr/local/etc/unbound/unbound.conf << 'EOF'
server:
    interface: 10.0.100.1
    interface: 127.0.0.1
    access-control: 10.0.100.0/24 allow
    access-control: 127.0.0.0/8 allow

    # Privacy
    hide-identity: yes
    hide-version: yes
    qname-minimisation: yes

    # Performance
    num-threads: 2
    msg-cache-size: 64m
    rrset-cache-size: 128m
    cache-min-ttl: 300
    prefetch: yes

    # DNS over TLS to upstream
    tls-cert-bundle: /etc/ssl/cert.pem

forward-zone:
    name: "."
    forward-tls-upstream: yes
    forward-addr: 1.1.1.1@853#cloudflare-dns.com
    forward-addr: 9.9.9.9@853#dns.quad9.net
EOF

Start Unbound:

sh
sysrc unbound_enable="YES"
service unbound start

Clients using DNS = 10.0.100.1 in their WireGuard config now resolve through the gateway's encrypted DNS.

DNS Leak Prevention

Add PF rules to block DNS requests that bypass the gateway resolver:

sh
# Add to /etc/pf.conf before the "pass in on $vpn_if" rule:
# Block DNS to anything other than the gateway
block in quick on $vpn_if proto { tcp, udp } from $vpn_net to ! 10.0.100.1 port 53

This ensures VPN clients cannot send DNS queries directly to external resolvers.

Kill Switch

A kill switch prevents client traffic from leaking outside the VPN if the tunnel drops. This is configured on the client side.

FreeBSD Client Kill Switch

On a FreeBSD client, use PF:

sh
cat > /etc/pf.conf << 'EOF'
vpn_if = "wg0"
ext_if = "em0"
vpn_server = "your-server-ip"

block all
pass on lo0 all
pass on $vpn_if all

# Allow only WireGuard UDP to the server
pass out on $ext_if proto udp to $vpn_server port 51820
# Allow DHCP
pass out on $ext_if proto udp from any port 68 to any port 67
EOF

When the VPN tunnel is down, all traffic is blocked except the WireGuard handshake. When the tunnel is up, all traffic flows through wg0.

Linux/macOS Client Kill Switch

Use the WireGuard app's built-in kill switch, or configure iptables/pf rules similar to the above.

Multi-Client Management

Client Addition Script

Automate adding new clients:

sh
cat > /usr/local/bin/wg-addclient.sh << 'SEOF'
#!/bin/sh
set -e

if [ -z "$1" ]; then
    echo "Usage: wg-addclient.sh <client-name>"
    exit 1
fi

CLIENT=$1
WG_DIR=/usr/local/etc/wireguard
SERVER_PUB=$(cat ${WG_DIR}/server.pub)
SERVER_IP=$(ifconfig em0 | grep 'inet ' | awk '{print $2}')

# Find next available IP
LAST_IP=$(grep "AllowedIPs" ${WG_DIR}/wg0.conf | tail -1 | grep -o '10\.0\.100\.[0-9]*')
NEXT_NUM=$((${LAST_IP##*.} + 1))
CLIENT_IP="10.0.100.${NEXT_NUM}"

# Generate keys
wg genkey | tee ${WG_DIR}/${CLIENT}.key | wg pubkey > ${WG_DIR}/${CLIENT}.pub
wg genpsk > ${WG_DIR}/${CLIENT}.psk
chmod 600 ${WG_DIR}/${CLIENT}.key ${WG_DIR}/${CLIENT}.psk

CLIENT_PUB=$(cat ${WG_DIR}/${CLIENT}.pub)
CLIENT_KEY=$(cat ${WG_DIR}/${CLIENT}.key)
CLIENT_PSK=$(cat ${WG_DIR}/${CLIENT}.psk)

# Add peer to server config
cat >> ${WG_DIR}/wg0.conf << PEER

[Peer]
# ${CLIENT}
PublicKey = ${CLIENT_PUB}
PresharedKey = ${CLIENT_PSK}
AllowedIPs = ${CLIENT_IP}/32
PEER

# Generate client config
cat > ${WG_DIR}/${CLIENT}.conf << CLIENT
[Interface]
PrivateKey = ${CLIENT_KEY}
Address = ${CLIENT_IP}/24
DNS = 10.0.100.1

[Peer]
PublicKey = ${SERVER_PUB}
PresharedKey = ${CLIENT_PSK}
Endpoint = ${SERVER_IP}:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25
CLIENT

# Reload WireGuard
service wireguard restart

echo "Client ${CLIENT} configured with IP ${CLIENT_IP}"
echo "Config file: ${WG_DIR}/${CLIENT}.conf"
SEOF

chmod +x /usr/local/bin/wg-addclient.sh

Usage:

sh
wg-addclient.sh laptop-alice
wg-addclient.sh phone-bob

Client Revocation

Remove a client by deleting its [Peer] block from wg0.conf and restarting:

sh
service wireguard restart

The removed client's keys are no longer accepted.

Start WireGuard

sh
sysrc wireguard_interfaces="wg0"
sysrc wireguard_enable="YES"
service wireguard start

Verify the interface:

sh
wg show

Expected output:

sh
interface: wg0
  public key: SERVER_PUBLIC_KEY
  private key: (hidden)
  listening port: 51820

peer: CLIENT1_PUBLIC_KEY
  allowed ips: 10.0.100.2/32
  latest handshake: 23 seconds ago
  transfer: 1.24 MiB received, 3.45 MiB sent

Monitoring

Real-Time Connection Status

sh
wg show wg0

Shows all connected peers, their latest handshake time, and transfer statistics.

Traffic Monitoring

sh
pkg install vnstat
sysrc vnstatd_enable="YES"
service vnstatd start
vnstat -i wg0

PF Statistics

sh
pfctl -si
pfctl -ss | grep wg0

Automated Health Check

Create /usr/local/bin/wg-health.sh:

sh
cat > /usr/local/bin/wg-health.sh << 'HEOF'
#!/bin/sh

echo "=== WireGuard Status ==="
wg show wg0

echo ""
echo "=== Interface Statistics ==="
netstat -I wg0 -b

echo ""
echo "=== PF NAT State Count ==="
pfctl -ss | grep -c "wg0"

echo ""
echo "=== Connected Clients ==="
wg show wg0 | grep -c "latest handshake"

echo ""
echo "=== DNS Resolver Status ==="
drill @10.0.100.1 example.com | grep "rcode"

echo ""
echo "=== Firewall Log (last 10 blocks) ==="
tcpdump -n -e -ttt -r /var/log/pflog -c 10 2>/dev/null
HEOF

chmod +x /usr/local/bin/wg-health.sh

Alerting on Peer Disconnection

Check for peers that have not communicated recently:

sh
cat > /usr/local/bin/wg-alert.sh << 'AEOF'
#!/bin/sh
THRESHOLD=300  # 5 minutes in seconds

wg show wg0 latest-handshakes | while read -r peer handshake; do
    if [ "$handshake" -eq 0 ]; then
        continue  # Peer has never connected
    fi
    age=$(($(date +%s) - handshake))
    if [ "$age" -gt "$THRESHOLD" ]; then
        echo "ALERT: Peer $peer last handshake ${age}s ago" | \
          mail -s "WireGuard Peer Timeout" admin@example.com
    fi
done
AEOF

chmod +x /usr/local/bin/wg-alert.sh
echo '*/5 * * * * root /usr/local/bin/wg-alert.sh' >> /etc/crontab

Performance Tuning

Increase UDP Buffer Sizes

sh
sysctl net.inet.udp.recvspace=262144
sysctl net.inet.udp.maxdgram=65536
echo 'net.inet.udp.recvspace=262144' >> /etc/sysctl.conf
echo 'net.inet.udp.maxdgram=65536' >> /etc/sysctl.conf

MTU Optimization

WireGuard adds 60 bytes of overhead (40 byte IPv6/20 byte IPv4 header + 40 byte WireGuard header). Set the tunnel MTU to avoid fragmentation:

For IPv4 underlying transport:

sh
ifconfig wg0 mtu 1420

For IPv6 underlying transport:

sh
ifconfig wg0 mtu 1400

Clients should match the MTU. Add MTU = 1420 to the [Interface] section of client configs.

Throughput Benchmarks

Tested on a FreeBSD 14 gateway with a 4-core Xeon E-2224, 10 Gbps NIC:

| Test | Throughput |

|------|-----------|

| WireGuard single stream | 3.2 Gbps |

| WireGuard 4 streams | 8.1 Gbps |

| WireGuard + NAT single | 2.8 Gbps |

| WireGuard + NAT 4 streams | 7.2 Gbps |

WireGuard on FreeBSD is fast. The kernel implementation avoids the overhead of userspace tunnels.

FAQ

Q: Why WireGuard instead of OpenVPN or IPsec?

A: WireGuard is faster (kernel-space, ~4,000 lines of code), simpler to configure, and uses modern cryptography (ChaCha20, Curve25519). OpenVPN runs in userspace and caps at ~500 Mbps. IPsec is complex to configure and debug.

Q: Can I run WireGuard alongside other VPN protocols?

A: Yes. WireGuard uses UDP on a single port (default 51820). You can run OpenVPN on TCP 443 and IPsec on UDP 500/4500 simultaneously.

Q: How many clients can a FreeBSD WireGuard gateway handle?

A: Hundreds. Each peer adds minimal overhead (a few KB of memory for the crypto state). The bottleneck is bandwidth, not peer count.

Q: Does WireGuard work behind NAT?

A: Yes. The PersistentKeepalive = 25 setting sends a keepalive packet every 25 seconds, maintaining the NAT mapping.

Q: How do I route only specific subnets through the VPN?

A: On the client, set AllowedIPs to only the subnets you want routed. For example, AllowedIPs = 10.0.100.0/24, 192.168.1.0/24 routes only those networks through the tunnel.

Q: Can I use IPv6 through the WireGuard tunnel?

A: Yes. Add IPv6 addresses to the Interface and AllowedIPs. Example: Address = 10.0.100.2/24, fd00::2/64 and AllowedIPs = 0.0.0.0/0, ::/0.

Q: How do I prevent DNS leaks?

A: Run a DNS resolver on the gateway (Unbound), set DNS = 10.0.100.1 in client configs, and block port 53 to external IPs in PF.

Q: What if my ISP blocks UDP 51820?

A: Change the WireGuard listen port to 443 or 53, which ISPs rarely block. Or tunnel WireGuard over a TCP wrapper like udp2raw, though this adds overhead.

Q: How do I update WireGuard?

A: pkg upgrade wireguard-tools. The kernel module updates with FreeBSD base system updates via freebsd-update. No configuration changes needed.

Get more FreeBSD guides

Weekly tutorials, security advisories, and package updates. No spam.

Previous

FreeBSD vs Linux in 2026: Market Position and Future

Next

FreeBSD User and Permission Management Guide

Related Guides

guide

FreeBSD High Availability: CARP, HAST, and Failover Guide

FreeBSD high availability with CARP virtual IPs, pfsync firewall state sync, HAST block-level replication, ZFS send/recv, and load balancer failover configurations.

guide

FreeBSD Network Performance Optimization Guide

Optimize FreeBSD network performance with sysctl tunables, ring buffers, polling, TSO/LRO, LAGG, RSS, interrupt coalescing, and practical benchmarks.

guide

FreeBSD Networking: Complete Administration Guide (2026)

The definitive guide to FreeBSD networking: interface configuration, VLANs, bridges, LAGG, routing, PF firewall, DNS, DHCP, VPN, IPv6, and network performance tuning. Every command tested on FreeBSD 14.

guide

FreeBSD as a Home Lab Server: Complete Guide

Complete guide to building a FreeBSD home lab server. Covers hardware selection, installation, jails for services, bhyve VMs, ZFS storage, networking, monitoring, and project ideas.