Once your WireGuard server runs on a VPS (see WireGuard VPN server), each device needs a client configuration. The config is a small text file, and the same file works on every platform. This guide explains its settings, shows how to import it on each OS, and covers split tunnelling, DNS and common problems.

The client config, line by line

[Interface]
PrivateKey = <client-private-key>
Address = 10.8.0.2/32
DNS = 1.1.1.1, 9.9.9.9
MTU = 1420

[Peer]
PublicKey = <server-public-key>
PresharedKey = <optional-psk>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25
Setting Meaning
PrivateKey This device’s secret key. Never share it
Address The device’s VPN IP. Unique per client, and matches the server’s AllowedIPs for this peer
DNS DNS servers used while connected. Prevents DNS leaks in full-tunnel mode
MTU Lower it (1380, 1280) if some sites hang. See MTU explained
PublicKey The server’s public key
PresharedKey Optional extra symmetric key (post-quantum hardening)
Endpoint The server’s address and UDP port
AllowedIPs Which destinations go through the tunnel (see below)
PersistentKeepalive Send a keepalive every 25 s, so NAT keeps the mapping. Needed behind NAT

Full tunnel vs split tunnel

AllowedIPs on the client decides routing:

Full tunnel, where all internet traffic goes through the VPS (public Wi-Fi, a fixed exit IP):

AllowedIPs = 0.0.0.0/0, ::/0

Split tunnel, where only private networks go through the VPN and everything else uses the local internet:

AllowedIPs = 10.8.0.0/24, 10.0.0.0/24

Split tunnelling is the right choice for admin access to servers (reach databases, SSH and dashboards on the private network) without slowing down normal browsing. Make sure the ranges don’t overlap with the client’s local network. See private IP ranges.

For full-tunnel mode, the server must have IP forwarding and NAT enabled, as in the server guide.

Generate a client

On the server (or anywhere with wg installed):

umask 077
wg genkey | tee alice.key | wg pubkey > alice.pub

Add the peer to the server:

sudo wg set wg0 peer "$(cat alice.pub)" allowed-ips 10.8.0.2/32
sudo wg-quick save wg0

Write the client config with alice.key as PrivateKey. Transfer it securely, by QR code or an encrypted channel, never over plain chat or email.

Import on each platform

Windows

Install WireGuard from wireguard.com → Import tunnel(s) from file → select alice.conf → Activate. Under Edit, the “Block untunneled traffic (kill-switch)” option appears for full-tunnel configs.

macOS

Install WireGuard from the App Store → Import tunnel(s) from file. Allow the VPN configuration when prompted. Enable On-Demand to connect automatically, for example on untrusted Wi-Fi.

iOS / Android

Install the WireGuard app → + → Scan from QR code. On the server:

qrencode -t ansiutf8 < alice.conf

Android supports per-app exclusions. iOS has On-Demand rules.

Linux

sudo apt install wireguard        # or: dnf install wireguard-tools
sudo cp alice.conf /etc/wireguard/wg0.conf
sudo chmod 600 /etc/wireguard/wg0.conf
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0      # connect at boot

DNS on Linux with wg-quick needs resolvconf or systemd-resolved. If DNS = causes errors, install openresolv, or remove the line. NetworkManager can import configs too: nmcli connection import type wireguard file alice.conf.

Verify

sudo wg show                 # latest handshake should be recent; transfer counters rising
ping 10.8.0.1                # the server's VPN IP
curl -s https://ifconfig.me  # full tunnel: shows the VPS IP

Troubleshooting

Symptom Check
No handshake ever Wrong Endpoint or port, server UDP port not open in the firewall, wrong public key on either side
Handshake OK, no traffic Server AllowedIPs for this peer doesn’t match the client Address. Server forwarding or NAT missing (full tunnel)
Some websites hang MTU. Set MTU = 1380 or lower
Works on Wi-Fi, not mobile Carrier blocks UDP or the port. Try port 443/udp on the server
DNS doesn’t resolve DNS = missing in full tunnel, or the resolver isn’t reachable through the tunnel
Two devices kick each other off Both use the same key or address. Every device needs its own

On the server, sudo wg show shows each peer’s latest handshake and endpoint. sudo journalctl -k | grep wireguard shows kernel messages if debugging is enabled.

Security tips

  • One key per device. Revoke lost devices by removing their peer from the server (wg set wg0 peer <pubkey> remove).
  • Keep client configs as secret as passwords, since they contain private keys.
  • Consider Tailscale or Headscale when you have many devices and users. Key distribution and ACLs get much easier. See Headscale.

Related: WireGuard site-to-site and OpenVPN vs WireGuard.

  • WireGuard
  • VPN
  • Networking