How to set up WireGuard in your UniFi controller

WireGuard is the third-generation answer to the question “how do you put one network inside another, securely.” The first generation was IPsec, ratified in the 1990s, complex enough that interoperability between vendors took a decade. The second was OpenVPN, simpler, but running in userspace over TLS, with the performance ceiling that implies. WireGuard is the third: a fixed-cipher protocol, in the Linux kernel since version 5.6 (released 29 March 2020¹²), built around the Noise protocol framework with ChaCha20 for symmetric encryption, Poly1305 for authentication, Curve25519 for key exchange, and BLAKE2s for hashing.⁹

The project's own framing is the line on the homepage: “WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography.”⁹ The author's NDSS 2017 paper puts a number on the simplicity claim: “WireGuard can be simply implemented for Linux in less than 4,000 lines of code, making it easily audited and verified.”¹¹ For comparison, the OpenVPN userspace daemon is roughly two orders of magnitude larger.

The same paper publishes the headline performance comparison on identical hardware: WireGuard sustained 1,011 Mbps with 0.403 ms ping; OpenVPN on the same machine reached 258 Mbps with 1.541 ms.¹¹ The point isn't that residential users need gigabit VPN throughput from a phone — they don't — it's that the cost of routing everything through the tunnel is small enough that full tunnel (every byte goes home) becomes a practical default rather than a performance penalty.

Two pieces of WireGuard's design are worth naming because they shape how the rest of this article reads. First, the protocol is cryptographically opinionated — there is no cipher negotiation, no protocol version selection. As Donenfeld wrote in the same paper: “If holes are found in the underlying primitives, all endpoints will be required to update. As shown by the continuing torrent of SSL/TLS vulnerabilities, cipher agility increases complexity monumentally.”¹¹ Second, WireGuard is UDP-only. The project page is blunt: “WireGuard explicitly does not support tunneling over TCP, due to the classically terrible network performance of tunneling TCP-over-TCP.”¹³ Default port is UDP 51820.¹⁴ That single UDP port is the entire externally-reachable surface a properly configured WireGuard server exposes.

WireGuard is widely adopted as the data plane of other products — Cloudflare WARP runs on WireGuard,¹⁵ Tailscale uses WireGuard for its peer-to-peer tunnels,¹⁶ and, as we'll see, Ubiquiti's own Teleport feature is WireGuard underneath.³ It is not yet an IETF-standardised protocol; the authoritative reference remains the NDSS 2017 paper and the project's own protocol page.

Ubiquiti's WireGuard VPN Server documentation opens with the prerequisite plainly: “A UniFi Gateway or UniFi Cloud Gateway is required.”¹ Verified, against the per-model tech-specs pages, the feature is listed under VPN Server protocols on the current generation of gateways: UniFi Express (UX), Dream Router (UDR and UDR7), Dream Machine SE (UDM-SE) and Pro Max (UDM-PMX), Cloud Gateway Max (UCG-Max), Cloud Gateway Ultra (UCG-Ultra), Cloud Gateway Fiber (UCG-Fiber), UXG-Max, and the Enterprise Fortress Gateway (EFG).⁷⁸

Throughput varies materially by gateway class. The EFG datasheet lists WireGuard server-mode throughput at 1.2 Gbps single-user, against 210 Mbps for OpenVPN and 280 Mbps for L2TP on the same box — Ubiquiti's own published numbers, making the protocol comparison cleanly.⁸ On a UCG-Ultra, independent benchmarks place single-tunnel WireGuard throughput in the 300–600 Mbps range; on a UDM Pro Max, in the 2.5 Gbps range. Per-tunnel throughput is single-core CPU-bound, so the total across many concurrent peers scales with cores rather than with the headline number.¹⁹

If the home has a UniFi switch and access points but the router is a non-UniFi gateway (an Apple AirPort, a consumer eero, an ISP-supplied modem-router), the WireGuard server feature isn't present — it lives on the gateway, not the controller. The simplest resolution is replacing the non-UniFi gateway with a UniFi one; the cheapest is a UniFi Express, which is roughly the size of a deck of cards and runs the full WireGuard server feature.⁷

WireGuard is connectionless and outbound-friendly, but the server side still has to be reachable from the public internet. Three questions to answer first.

1 — Is the UniFi gateway the device with the public IP?

If the ISP's modem is running in bridge mode and the UniFi gateway holds the public IP directly, nothing further is needed. If the ISP's modem is in router mode and the UniFi gateway sits behind it with a private IP, you're in double-NAT, and Ubiquiti's documentation says exactly what to do: “If the UniFi gateway is behind NAT, then the port used for WireGuard needs to be forwarded by the upstream router. The default port for WireGuard is UDP 51820 and this needs to be forwarded to the UniFi gateway's WAN IP address.”¹ Bridge mode on the ISP modem is the cleaner answer where it's available.

2 — Is the ISP using CGNAT?

Carrier-grade NAT (CGNAT) means the home does not have a dedicated public IP at all — several customers share one. A direct inbound WireGuard connection is impossible in that case, regardless of port forwards. Common where the WAN is a fixed-wireless 5G modem or certain fibre carriers in dense urban areas.If you're behind CGNAT, skip to § 08 and use Teleport instead — it doesn't need a public IP.

3 — Does the public IP change?

Most residential ISPs rotate the public IP every several days. WireGuard peers point at the home by IP or by hostname; if the IP changes after a peer config is generated, that peer can't reconnect. The answer is Dynamic DNS — a hostname that follows the IP. UniFi has DDNS support built into the gateway, with a fixed list of supported providers (Cloudflare, DuckDNS, No-IP, Afraid, EasyDNS, Namecheap, several others).²⁰ We'll wire that into the WireGuard server in § 07.

In the UniFi Network application, open Settings → VPN, switch to the VPN Server tab, click Create New, and choose WireGuard.¹¹⁸ Six fields matter:

• Name — anything; home-wg works fine.
• WAN connection — pick the active WAN. If the household has WAN failover configured, WireGuard can only bind one of the two.
• Port— UDP 51820 is the default. Some carriers throttle WireGuard's well-known port; if you've seen this before, pick something in the 51000–52000 range.
• Gateway / Subnet — the network the tunnel itself lives on. 10.20.30.0/24 is a fine choice. Critical: this subnet must not overlap any LAN VLAN. If your LAN is 192.168.1.0/24, do not pick that for the tunnel.
• DNS server— leave on. UniFi pushes the gateway's own DNS to peers, so connected clients can resolve internal hostnames like nas.lan.
• Use Alternate Address for Clients — the DDNS hook. Tick this and enter the hostname, and every peer config generated from this server uses the hostname rather than a literal IP.¹⁸

Save the server config. UniFi auto-creates the firewall rules that allow WireGuard peers to reach the LAN.²¹ The shape of what's now in place:

On the server config, click Add Client. UniFi generates the key pair server-side — no command-line wg genkey required.¹⁸ The fields:

• Name — name the device, not the human. tahir-iphone, laptop-work. One peer per device matters for security: WireGuard identifies peers by their public key, and sharing a key across devices breaks NAT roaming and removes any per-device revocation. Pro Custodibus has a definitive write-up on this.¹⁷
• IP address — the address this peer takes inside the tunnel subnet you picked in § 05. UniFi auto-suggests; leave it.
• Pre-Shared Key — optional. Adds an extra 256-bit symmetric secret on top of the public keys. The WireGuard project documents the option specifically as post-quantum hardening;¹¹ most residential setups don't need it.
• Remote Client Networks — the client-side AllowedIPs. Two practical choices:
  • 0.0.0.0/0 — full tunnel. Every byte of traffic from the peer goes through the home. Sensible default for hostile networks (hotel Wi-Fi, conferences, cafes).
  • Your LAN subnets only — split tunnel. The peer can reach the home LAN; everything else stays on the local link. Faster, but the peer is “at home” only for resources explicitly listed.
• DNS — leave on the gateway for internal-hostname resolution. If you use split tunnel and want internal DNS, make sure the gateway's DNS IP is inside the AllowedIPs range (a common foot-gun — see § 09).

Save. UniFi presents two things: a QR code, and a downloadable .conf file.¹ For a phone or tablet, install the official WireGuard app from the Apple App Store or Google Play,¹⁰ tap the +, choose Create from QR code, and point the camera at the UniFi screen. For a laptop, install the WireGuard desktop client and import the .conf file. Tap to connect; the app should report a handshake within a second or two.

Residential ISPs rarely give a static IP. If yours rotates every few days — most do — UniFi has built-in Dynamic DNS support that keeps a hostname pointed at the current public IP. Open Settings → Internet → WAN → Dynamic DNS and pick a provider; the current list includes Cloudflare, DuckDNS, No-IP, Afraid, EasyDNS, Namecheap, DSLReports, DynDNS, Sitelutions, and ZoneEdit.²⁰ DuckDNS is free, fast to set up, and uses no third-party login other than the DDNS account itself.

After the DDNS hostname is live, return to the WireGuard server config (§ 05) and tick Use Alternate Address for Clients, entering the DDNS hostname. Every peer config UniFi generates from that moment forward uses the hostname rather than a literal IP. Previously-generated configs keep pointing at the IP they were created with — those peers need their configs regenerated and re-imported if the IP later changes.

Engineer footnote: WireGuard resolves the hostname at handshake time, then caches the resolved endpoint and roams with it as the peer's source IP changes (Donenfeld's cryptokey routing model¹¹). The hostname is only resolved when the existing endpoint stops responding — meaning a rare IP change at home triggers a brief reconnect rather than a permanent outage.

Ubiquiti ships a second VPN option on the same gateway called Teleport. Their documentation describes it as “a zero-configuration VPN that allows you to instantly connect to your UniFi network from a remote location,” and confirms the underlying protocol explicitly: “Teleport uses the Wireguard VPN to encrypt your traffic and secure remote access connections.”³ Functionally, Teleport is a managed WireGuard server with three differences from the manual one:

• No public IP required. Ubiquiti states it plainly: “Teleport can be used when both the UniFi gateway and client are behind NAT.”³ This is the headline reason to choose Teleport in a household behind CGNAT.
• WiFiman app only. Teleport peers use Ubiquiti's WiFiman mobile / desktop app, not the standalone WireGuard client. Less customisable; faster to onboard.
• DNS is fixed. Teleport hardcodes the tunnel DNS server to 8.8.8.8, so peers cannot resolve internal hostnames like nas.lan.²² Workable for general internet use; a deal-breaker if the household reaches a NAS by hostname.

Practical rule: Teleport for households behind CGNAT, and for phone-only use cases where the peer doesn't need to address internal hostnames. Manual WireGuard for everyone else. The two can coexist on the same gateway; nothing about enabling one rules out the other.

1 — Handshake never completes

The WireGuard app shows Latest handshake: — and never updates. Almost always means UDP 51820 is not reaching the gateway. Walk back: is the ISP modem in bridge mode? If not, is UDP 51820 forwarded to the UniFi gateway's WAN IP? Is the carrier on CGNAT (and so the home doesn't have an inbound path at all)? Some mobile carriers also rate-limit or block well-known VPN ports — moving to a port in the 51000–52000 range usually resolves that.

2 — Connected, but nothing on the LAN responds

The handshake succeeded, but the phone can't reach the NAS. Two usual causes. First, the client's AllowedIPs is too narrow — it doesn't include the LAN subnet, so the phone never routes that traffic into the tunnel. Second, custom firewall zones on the UniFi gateway have overridden the auto-created rules. Re-save the WireGuard server config to refresh them; if that doesn't fix it, add an explicit allow rule from the WireGuard zone to LAN-in.

3 — Connected, but DNS doesn't work

Split-tunnel hole. The client has the LAN subnet in AllowedIPs but not the gateway's DNS IP — so the phone tries DNS over the local link, against whatever resolver the cellular carrier or hotel Wi-Fi pushes. Either widen AllowedIPs to include the gateway's IP, or override DNS on the peer config to a public resolver (1.1.1.1, 8.8.8.8).

4 — Drops after roughly a minute on cellular

Carriers age out UDP NAT mappings aggressively — sometimes 20–30 seconds for an idle flow. WireGuard's documented fix is PersistentKeepalive = 25 on the peer config, which sends a small keepalive every 25 seconds.¹⁴ In UniFi, this is set on the peer entry server-side and re-exported to the client.

5 — Slow throughput, especially with IDS/IPS on

WireGuard runs single-threaded per tunnel and cannot be offloaded to hardware accelerators on the current gateways. On smaller gateways (UCG-Max, UDR), turning IDS/IPS on for the VPN-originating zone meaningfully reduces VPN throughput. If raw speed matters, scope IDS/IPS to LAN zones only and leave the VPN zone unmonitored.

The UniFi VPN screen exposes three modes, not one: VPN Server, VPN Client, and Site-to-Site VPN.² A homeowner reaching their own home from a phone wants VPN Server, with the WireGuard option chosen, as walked through above. Two locations that want to share resources (a vacation house, a second office) want Site-to-Site, which is a different conversation.

On standard UniFi cloud gateways, the productised site-to-site option is called Site Magic, which Ubiquiti documents as “a dedicated solution for connecting UniFi Gateways” with optional OpenVPN and IPsec for third-party interoperability.⁴ Ubiquiti's own Site Magic article does not publicly name the underlying tunnel protocol; third-party write-ups describe it as WireGuard-based, but in the absence of a vendor statement we'll leave that as “not publicly stated.” Hand-rolled WireGuard site-to-site, with both ends running the WireGuard stack and a routed network between them, is documented only for the Ubiquiti Mobile Router (UMR) — not for standard cloud gateways.⁵

The short answer: WireGuard VPN Server for the homeowner-to-home use case in this article; Site Magic for site-to-site between two UniFi sites; WireGuard S2S only if one side is a UMR.

• One peer per device. Phone, laptop, tablet, partner's phone — each gets its own peer entry, its own key pair, its own QR code. If a device is lost or sold, delete the peer entry; the rest keep working.¹⁷
• Treat the QR code like a password. Anyone who scans it has a working VPN config into the home. Don't paste it into chat. Show it on-screen, scan, dismiss.
• Revocation is “delete the peer.” WireGuard has no certificate-revocation list and no central kill switch. Removing the peer entry on the gateway is what stops the key from working. Do it immediately on device loss.
• Pre-shared keys are optional, not mandatory. The WireGuard project frames the PSK as post-quantum hardening for adversaries with long retention horizons — useful for some, overkill for most homes.¹¹
• The tunnel is not endpoint security. WireGuard is a transport tunnel. A compromised laptop with a working WireGuard peer still has remote access into the home. The audit point this changes is the perimeter, not the endpoints — which is large, but worth being clear about.¹³

• WireGuard is not an IETF standard. The authoritative protocol references remain Donenfeld's NDSS 2017 paper and the project's own protocol page. The IETF has surveyed WireGuard in passing (e.g. RFC 8922) but has not standardised it.
• US federal VPN guidance does not yet name WireGuard. The 2021 NSA/CISA “Selecting and Hardening Remote Access VPNs” cybersecurity information sheet is scoped to IKE/IPsec and TLS-tunnel VPN products.²³ WireGuard's absence reflects the document's age and product-validation scope, not a critique of the protocol.
• IPv6 on the WireGuard server endpoint is still unsettled. Recent UniFi Network releases (10.x, May 2026) extended IPv6 support to WireGuard clients (the outbound VPN-Client feature). Binding the WireGuard server to an IPv6 WAN address — and providing IPv6 to peers inside the tunnel — is not yet documented as supported. Use IPv4 endpoints for now.
• UI menu wording moves between Network app versions. The path used here — Settings → VPN → VPN Server → Create New → WireGuard — is current as of UniFi Network 10.x in mid-2026. Earlier versions reached the same feature through slightly different menu copy.
• Single-tunnel throughput is single-core CPU bound. The headline 1.2 Gbps figure from the EFG datasheet is a single-user benchmark on Ubiquiti's highest-end gateway; the residential experience on a UCG-Max or UDR is in the low hundreds of Mbps per tunnel.⁸¹⁹
• The article walks the manual path deliberately. Teleport is easier and appropriate for many households (§ 08). The reason to learn the manual setup anyway is that anyone who wants persistent .conf files, fixed peer IPs, internal hostname resolution, or split-tunnel control eventually outgrows Teleport — and the manual path is what they end up running.

If standing up WireGuard end-to-end — server, peers, QR codes, internal-hostname resolution, split-tunnel routing, and the audit-of-the-result that proves it works — is not where the homeowner wants to spend a weekend, we'll do the build and the handover as a focused engagement, with the per-device config files and a one-page operator runbook handed back at the end.