Connect iOS, Android, Windows, macOS, and Linux to a Site VPN

A Site VPN succeeds only when ordinary users can connect from the devices they already use. A configuration that works perfectly on an administrator’s Linux laptop may fail in practice if a phone sleeps, a Windows route persists after disconnect, macOS chooses another DNS resolver, or an Android user imports the wrong profile. Cross-platform deployment is therefore an operations problem as much as a protocol problem: every profile needs an owner, a clear name, a narrow route, and a repeatable test.

WireGuard is available across major operating systems, but the user interface and platform networking rules differ. Treat the cryptographic settings as shared design and the connection behavior as platform-specific. This guide focuses on the common decisions that should remain consistent—peer identity, addresses, routes, DNS, endpoint, and revocation—then explains where onboarding and troubleshooting change on iOS, Android, Windows, macOS, and Linux.

Create one peer per device

Do not copy the same client private key onto a phone, laptop, and desktop. A unique peer lets the operator revoke one lost device without interrupting the others, assign precise routes, and understand which device produced a connection. Give every peer a descriptive inventory name such as alex-iphone-2026 rather than client3. Record the owner, platform, assigned address, public key, creation date, and review date. The private key should stay on the device whenever the client supports local generation.

A profile should also identify the environment. A user may have production, staging, home-lab, and support tunnels installed at the same time. Use visible names that distinguish them and avoid relying on nearly identical QR codes. Keep the route set small: a private service address or subnet is easier to reason about than a default route. When full-tunnel access is truly required, label that profile explicitly so the user understands that general internet traffic will take a different path.

Start from supported clients, not random installers

Use an operating-system package source, official app store listing, or a deployment system your organization controls. The WireGuard installation guide links the project’s supported options for common platforms. Confirm the publisher and package identity before distributing instructions, particularly on mobile stores where similarly named applications can appear. For managed fleets, pin an approved package and document the update channel rather than asking each user to search.

Installation is only the first step. Create a short acceptance test that works everywhere: connect the tunnel, open the private hostname, confirm the expected certificate and page identity, verify an unapproved public address cannot reach the service, disconnect, and confirm the private hostname stops working. This sequence tests routing, DNS, TLS, and access boundaries together. A green “connected” switch proves only that the local client believes the interface is active.

iOS and iPadOS: design for roaming and simple choices

Mobile users move between Wi-Fi and cellular networks, suspend apps, and lock the screen. Test that the tunnel re-establishes after those changes and that the private site does not appear to hang with a stale route. On-demand behavior can reduce friction, but rules should be understandable: for example, connect whenever a particular private hostname is requested or whenever the device is off a trusted network. Avoid configurations that unexpectedly send all personal traffic through a work gateway unless that is an explicit policy.

QR import is convenient for a single user standing beside an administrator, but it should be treated as a secret transfer. Do not place QR codes in a shared ticket, slide deck, or photo library. Delete temporary images after import and lock the source device. In managed environments, use device management to deliver settings and remove them when access ends. Give users one visible troubleshooting action—toggle the tunnel off and on—plus a clear support path if the endpoint or DNS answer has changed.

Android: account for vendor power controls

Android supports robust VPN behavior, but device manufacturers can apply different battery and background restrictions. A tunnel that disappears after the screen turns off may need an approved always-on configuration, an exemption from aggressive power management, or a client update. Test on representative devices rather than assuming one Android handset describes the whole fleet. Keep the profile route-specific unless policy requires all traffic, and decide whether the user may bypass the VPN when it is unavailable.

Import methods vary by client, but the same secret-handling rule applies: the configuration contains a private key. Store exported files only long enough to transfer them, use an encrypted channel, and remove copies from downloads, chat history, and cloud photo backups. If the device is lost, revoke the peer immediately instead of waiting to see whether screen lock is sufficient. Reissue a new key and address for the replacement device so the inventory remains accurate.

Windows and macOS: watch routes, DNS, and multiple adapters

Desktop systems often have Ethernet, Wi-Fi, virtual machines, endpoint security software, and other VPN clients installed simultaneously. That makes routing conflicts more likely. On Windows, inspect the active route table and interface metrics when a private address goes to the wrong adapter. On macOS, verify which resolver is answering the private name and whether another network extension is competing for traffic. Test sleep and wake, docking, switching Wi-Fi networks, and connecting a second VPN.

For shared workstations, decide whether a tunnel is tied to a user session or the device. A device-level tunnel can make a private service available before sign-in, while a user-level tunnel better reflects individual authorization. Do not let the presence of a network tunnel replace application identity. Administrative websites should still use named accounts and strong authentication, because desktop access can be delegated, screens can be unlocked, and malware can act from an authorized device.

Linux: make automation observable

Linux clients may be desktops, servers, CI runners, routers, containers, or small single-board computers. The same configuration can be started by a desktop application, wg-quick, a network manager, systemd-networkd, or another orchestration layer. Choose one owner for the interface. Two tools attempting to install routes or DNS settings can create intermittent failures that vanish when the machine is rebooted. Document how the interface starts, where its configuration lives, and which service reports failure.

For unattended systems, avoid an unlimited, permanent peer with broad network access. Restrict routes and firewall rules to the exact destination and protocol the automation needs. Monitor recent handshake time and data transfer, but do not mistake traffic volume for successful application work. Add an HTTP health check over the private path and alert on repeated failures. When a server is rebuilt, create a new peer instead of restoring a private key from an old image without review.

Make DNS behavior predictable on every platform

A profile can specify a DNS server, but operating systems decide how that resolver interacts with existing networks. Full replacement is simple but may send unrelated queries to the Site VPN resolver. Split DNS is more precise: only names under a private domain go to the private resolver. The exact implementation varies, so test the same hostname from each supported platform. Record both the expected answer while connected and the expected failure or public answer while disconnected.

Avoid names that collide with home router search domains or multicast naming conventions. Use a domain you control, or a clearly delegated internal namespace backed by managed resolution. Keep certificate names aligned with DNS. If a user must enter an IP address because DNS is unreliable, the operational design is incomplete. Fix resolution rather than training people to bypass certificate warnings or memorize addresses.

Support, revocation, and offboarding are part of onboarding

Give users a one-page guide with the profile name, the private hostname, the connect and disconnect action, and three checks: network available, tunnel active, correct site identity. Keep diagnostic steps non-destructive. Asking users to reinstall immediately can destroy useful state and create duplicate peers. Support staff should be able to check whether the public endpoint is reachable, whether a recent handshake exists, whether the peer address is unique, and whether DNS returns the intended private address.

Offboarding should be a routine change, not an emergency. Remove the peer from the gateway, update the inventory, and verify the old configuration no longer handshakes. Managed devices should also have the profile removed. Review inactive peers periodically and investigate devices that have not connected within the expected interval. A small collection of well-owned peers is safer and easier to operate than a growing list of keys whose devices and users are unknown.