Why WireGuard setup breaks down in production
The tunnel comes up on a test bench in minutes, but in production it lasts only until the first network change.
An engineer switches from a home channel to mobile, the external address changes, the old session on the second node formally remains active — and the tunnel break looks not like a failure but like silence: the interface is up, the route exists, but traffic does not flow.
The second typical story is a restart.
The order in which routes and filtering rules come up is not documented anywhere, some parameters live only in process memory, and after scheduled maintenance remote access to equipment is restored manually, node by node, relying on the on-call engineer's calls instead of monitoring.
Routing problems make themselves known before obvious failures.
Overlapping address spaces of sites, the lack of priorities for service traffic, and a blurred boundary between internal subnets and the exit to the outside add up to a picture of “in the morning half the sites are unreachable”: a node responds to a service request, but the required service on it does not open.
A separate cause is that the route to a remote subnet is announced only after the first successful exchange, so after downtime access does not return by itself.
VPN diagnostics run into a lack of observability. Connections are not logged centrally, losses and delays by direction are not collected, and each engineer has their own WireGuard setup: different subnets, different allowed IP lists, different rules.
At the moment of failure, no one can say what exactly changed and when — there is nothing to compare against.
The cost of such a configuration is not only downtime. Every incident is investigated from scratch again, rollback to a working state is not described, and confidence in access security rests on verbal agreements. Below we examine how this is addressed.
What changes in operations after moving access to tunnels
Moving remote access to tunnels changes not only the connection scheme but also the set of metrics by which operations sees the state of the environment.
Instead of “works or does not work,” connection recovery time, the share of successfully established sessions, and the number of support requests appear — by these the effect is visible already in the first weeks.
Time to reconnect after a network change
The tunnel survives a network change without a break: the address changes, the connection comes up in seconds, and reconnection requires no manual actions. WireGuard in this role gives predictable bring-up time and does not drop already open sessions when moving between networks.
A whole class of failures disappears — “after switching to mobile, access hung, a restart is needed.” A new node is brought in with the same set of parameters as the others, so bring-up time shrinks from hours of manual work to minutes, and tunnel stability no longer depends on who exactly configured it.
Keys, not passwords: what leaves the processes
Access is issued with a key pair tied to a specific device: revocation is deleting the entry on the server, and the key stops passing verification at the next handshake.
Shared passwords sent in chats leave the processes, as does the mass password change “for everyone at once” after an employee leaves. Access key management comes down to a registry: who, on which device, and for what term access was issued.
In practice, this reduces the support load: “cannot connect” requests turn into planned “a new employee needs access.” Remaining services on the old scheme are retired gradually, without stopping work.
Remote access modes: permanent tunnel, roaming, gateway
The connection scheme for sites is chosen not by protocol popularity but by how many addresses you are ready to assign permanently and what traffic must go outside.
Below are three schemes that are actually chosen between at the start: they differ in network requirements and failure class.
| Option | When it fits | Limitations |
|---|---|---|
| Permanent tunnel between sites | office to office, service to service, exchange between subnets | requires fixed addresses and agreed subnet ranges |
| Client roaming | employees with laptops, switching Wi-Fi and mobile networks | when the network changes, the connection is re-established; device control is needed |
| Gateway to the outside | all employee traffic goes through the corporate perimeter | higher load on the perimeter; an explicit exception policy is needed |
Permanent tunnel between sites
The tunnel is established on both sides on fixed addresses, routes to internal subnets are written explicitly — otherwise branches will start seeing someone else's traffic.
Service keepalive packets prevent provider equipment from closing the connection by timeout, and if the channel breaks, the tunnel comes up by itself, without manual intervention. At acceptance, we measure how many seconds a site remains unreachable after the channel goes down.
Mobile employees and network changes
A client with roaming survives the transition from office Wi-Fi to a mobile network: the connection address changes on the fly.
When an employee must access the internet through the corporate perimeter, we configure a gateway to the outside and describe exceptions — requests to internal resources bypass the exit, the rest go through it.
We separately record the device list and access revocation rules so that a dismissed employee loses the channel immediately, not after a password change.
WireGuard setup: stages from audit to handover to operations
The work order is the same for a fleet of five servers and for a network with a dozen offices: first we record exactly what we are connecting, then we build addressing, and only then do we bring up tunnels.
This order removes the main cause of accidents — a discrepancy in which subnets are reachable through the gateway.
- Inventory. We collect a list of nodes, subnets, services, and roles of those who connect remotely. The result is a registry from which configurations are then generated, rather than a set of “on-site” edits.
- Addressing and roles scheme. We allocate a separate range for tunnels and mark out roles: hub, site gateway, client. Private keys are created on the nodes themselves and do not leave the machine — only the public part goes to the server.
- Node bring-up. We install the service as a system service with autostart, set the port, the session re-establishment period for nodes behind NAT, and the order in which the interface starts before application services.
- Routing rules. We determine which addresses go into the tunnel and which go directly: full route for admin workstations, only the required subnets for branches. This way service traffic does not flow through the remote gateway.
- Failure testing. We run scenarios: link break, external address change, address conflict, node unavailability, key loss. We set up monitoring of tunnel state so that a break is seen by monitoring, not by the user.
- Commissioning. We hand over the procedure: how to connect a new employee, how to revoke access, where keys are stored, and how to change them. Without this, six months later “temporary” accesses appear on the network that no one remembers.
What remains in the infrastructure after implementation
A configured server without documentation is infrastructure that depends on one person. Therefore we record the implementation result in a set of artifacts: from them access is reproduced on a new node, checked during an audit, and handed over for maintenance without us.
The composition is the same for WireGuard and OpenVPN access — the transport changes, the set of documents is the same.
- Node configurations — server side and client profiles with field explanations: addressing, allowed subnets, split routing so that only work traffic goes through the tunnel.
- Network diagram — tunnel topology, internet exit points, connections between segments and external services: a diagram plus a text description of addressing.
- Access role model — which groups of employees and contractors see which subnets, what is closed by default, how rights are divided between office, cloud, and test environments.
- Key rotation procedure — frequency of key pair changes, access revocation upon dismissal, actions when compromise is suspected, and verification that a revoked key is no longer accepted.
- New employee connection procedure — steps from request to profile issuance: who approves, within what time access is issued, and how it is confirmed that it works only for that person.
- First-line support instructions — common requests, diagnostic commands, what the on-call person closes themselves and when they involve an access engineer.
- State monitoring — tunnel metrics, connection log, node availability checks, and connection loss alerts.
Case study: engineer access to equipment at remote sites
The customer has nine remote sites — warehouses, pumping stations, and production areas. Engineer access to equipment took from forty minutes to several hours: a support request, and the on-call person manually issued a session through a shared password.
The password remained valid after an employee left, and after a communication break the tunnel did not come up by itself — the engineer waited for the on-call person and lost half a shift.
What was changed in access
We deployed a hub on WireGuard and gateways at the sites: they maintain a permanent tunnel to the office, and the engineer connects only to the required equipment segment. The key is issued personally, rights are limited by a subnet list, and upon dismissal the key is revoked.
After a communication break, the tunnel comes up by itself, without the on-call person's involvement.
Access was reduced from forty minutes to two or three. Support requests about access were about sixty per month — only a few remain, and those are about connecting new sites.
Recovery after a break dropped from several hours to fifteen minutes, and the failure class “session is not re-established, password lives on after dismissal” no longer recurred.
How it was handed over to the operating team
We handed over the key rotation and revocation procedure, the network diagram with addressing and access lists, the procedure for connecting a new site, and a backup node in case the primary fails.
The on-call staff are trained, and the instruction is short: a new engineer brings up access themselves, without a support request.
What to do if another tunnel is already running outside the perimeter
An existing tunnel cannot be shut down in an instant: some nodes will simply be left without access, and reverting will require manually reconfiguring each one.
Therefore we bring up the new environment alongside the old one — both operate in parallel, on separate subnets and with their own routing rules, and each node receives its configuration individually. No one loses access until they switch themselves.
The transition option is chosen based on the number of nodes and how strict the requirements are for the downtime window.
| Transition option | When it fits | Limitations |
|---|---|---|
| Parallel operation of two tunnels | Many nodes, downtime unacceptable | Two addressing schemes and two sets of rules in administration |
| Phased migration in groups | Nodes are logically grouped: offices, services, contractors | Switching proceeds in queues, the timeline stretches |
| Transport change on nodes | Clients already support the new tunnel format | Configuration must be updated on all devices |
| Full migration | Few nodes or access is non-critical | Short downtime and the need for a ready rollback |
Before switching, we check compatibility: whether subnet addresses overlap, whether routing rules and name resolution conflict.
These are the most common reasons when WireGuard comes up and responds but traffic to internal services does not flow — during parallel operation, this is caught immediately and fixed on one node, not across the whole fleet.
Each stage is reversible: the old tunnel configuration remains on the node until stability is confirmed, and switching one group takes minutes.
As a result, you are left with the addressing scheme, the list of rules, and the rollback procedure — you can migrate not overnight and without losing access.
Technical concerns: keys, rotation, mobile networks
The key is the access: as long as the private part lies as a file on a laptop, dismissing an employee remains an order, not a technical procedure.
Therefore, before rolling out tunnels, we record where keys live, who changes them and how often, and what happens when a device is lost.
Where are private keys stored?
Private keys do not leave the device: only public parts and the allowed address list are kept on the server. We issue client configurations through a closed channel, and server ones are kept in a secure storage with limited access and an issuance log.
How to revoke access for a dismissed employee?
It is enough to remove their public key from the server configuration and reload it — reconnection is cut off immediately, and other tunnels are not broken. If a pre-shared key was used, we change it as well so that old profiles do not fit the server.
What to do in unstable mobile networks?
The tunnel survives a network change: communication is restored by periodic checks, without manual reconnection, and the transition between mobile internet and Wi-Fi is seamless.
For networks where UDP is blocked, we leave a backup profile — it is slower but works where the primary does not come up.
What are the limitations of the scheme?
The tunnel does not replace authorization: access to internal services is still issued by roles, not “to everyone in the VPN.” We separately select MTU — with an incorrect value, large packets are lost, and some resources “do not open” while the connection is formally alive.
Let's discuss the task: what is needed to start work
Discussion of the task begins with an inventory of what already exists. To come back with a work plan and timeline estimate rather than clarifying questions, a few inputs are enough — they are usually sent in one message.
- Sites and environments. Offices, warehouses, production areas, remote employees, cloud servers — exactly where access is needed and how many entry points.
- Number of employees and roles. How many people connect simultaneously and which permission groups are needed: full access to the internal network or only to specific services.
- Current scheme. What is already deployed, which address spaces are occupied, how addresses are issued to clients, and where internet exit points are located.
- Access mode. A full tunnel is needed or routes only to specific subnets — the WireGuard configuration and addressing scheme depend on this.
- Authentication. Local accounts, user directory, certificates, second factor — what can be reused and what will have to be migrated.
- Log requirements. Which events to write (connections, verification failures, issued routes), retention period, where to export, and who reads them.
- Work window constraints. When access may be interrupted, whether there are shifts working around the clock, and how much time is allotted to return to the original scheme.
Based on this data, we assemble a work plan: stages, test environment, switching procedure, and rollback scenario. We record the timeline estimate and scope of work in writing — before anything changes on production nodes.