Building a WireGuard VPN on Ubuntu: Step-by-Step Guide with Client Management & iOS Setup

WireGuard is an extremely lightweight, high-performance, and modern VPN protocol integrated directly into the Linux kernel. This production guide walks you through deploying WireGuard from scratch on an Ubuntu cloud server—covering kernel installation, IP packet forwarding, hardened UFW/NAT firewall rules, isolated multi-peer management, and seamless iOS / iPhone onboarding via instant terminal QR codes.

Note: All public IP addresses, private keys, and subnets in this document are sanitized examples. Please replace them with your actual environment variables and never expose production private keys publicly.

1. Prerequisites

Before proceeding, ensure you have the following:

• An Ubuntu 22.04 or 24.04 LTS cloud server with a dedicated public IPv4 address.
• Root or sudo administrative privileges.
• Inbound UDP traffic allowed on your target WireGuard listening port (default: 51820/udp) in your cloud provider’s firewall / Security Group.
• An iPhone with the official WireGuard app installed from the App Store.

2. Installing WireGuard and Enabling IP Forwarding

Modern Ubuntu kernels natively include the WireGuard kernel module. First, update package lists and install the userspace tools:

sudo apt update
sudo apt install -y wireguard qrencode iptables

Next, enable IPv4 packet forwarding in the Linux kernel so traffic can flow between the VPN tunnel interface and the public internet:

sudo tee -a /etc/sysctl.d/99-wireguard.conf <<EOF
net.ipv4.ip_forward = 1
EOF

sudo sysctl -p /etc/sysctl.d/99-wireguard.conf

3. Generating Server Keys & Configuration

Navigate to the WireGuard configuration directory and set restrictive permissions before generating server keys:

cd /etc/wireguard
umask 077
wg genkey | tee server_private.key | wg pubkey > server_public.key

Inspect your public network interface name (usually eth0 or ens3) via ip -br a. Then construct the server configuration file /etc/wireguard/wg0.conf:

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = <INSERT_SERVER_PRIVATE_KEY>

# Automated NAT masquerade when interface goes UP
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
# Clean up NAT rules when interface goes DOWN
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

4. Managing Client Peers & Generating Profiles

For each client peer (e.g. an iPhone), generate dedicated client-side keypairs:

wg genkey | tee client_iphone_private.key | wg pubkey > client_iphone_public.key

Register the peer in /etc/wireguard/wg0.conf:

[Peer]
PublicKey = <INSERT_CLIENT_IPHONE_PUBLIC_KEY>
AllowedIPs = 10.8.0.2/32

Then assemble the client configuration file iphone.conf:

[Interface]
PrivateKey = <INSERT_CLIENT_IPHONE_PRIVATE_KEY>
Address = 10.8.0.2/24
DNS = 1.1.1.1, 8.8.8.8

[Peer]
PublicKey = <INSERT_SERVER_PUBLIC_KEY>
Endpoint = YOUR_SERVER_PUBLIC_IP:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

5. Bringing Up the Tunnel & iOS QR Code Onboarding

Start the WireGuard interface and enable it as a persistent systemd service:

sudo systemctl enable --now wg-quick@wg0
sudo wg show

To onboard your iOS device without manually typing long cryptographic base64 strings, render the config directly in your SSH terminal as an ASCII QR code:

qrencode -t ansiutf8 < iphone.conf

Open the WireGuard app on your iPhone, tap Add a tunnel (+) > Create from QR code, point your camera at the terminal, name the tunnel, and toggle it on.

6. Common Troubleshooting Scenarios

• 0 Bytes Received / Handshake Timeout: Verify that your cloud security group (AWS, GCP, Aliyun, DigitalOcean) has explicitly whitelisted inbound 51820/UDP. Standard firewalls default to blocking custom UDP ports.
• VPN Connected but No Internet: Check cat /proc/sys/net/ipv4/ip_forward. If it outputs 0, packet routing is disabled. Ensure the iptables MASQUERADE interface name matches your active public NIC (e.g., replace eth0 with ens3).
• MTU Fragmentation: On mobile cellular networks, packet encapsulation overhead can cause dropped TCP connections. Lowering client MTU = 1280 or 1360 resolves packet fragmentation.