Split-tunnel docs need a DNS rule beside every route
A route decides by address, a resolver decides by name. Document both selectors per flow, each with one test, or the note fails when DNS shifts.
A split-tunnel note that says "office traffic goes through the VPN" has documented one decision and implied three others. At the packet layer a routing table picks an interface by destination address; at the name layer a resolver picks a server by query, and the two choices are made independently. That is why a correctly documented prefix can still produce a machine that resolves an internal name to a public address, or resolves nothing at all while the route looks perfect.
Two selectors, one connection attempt
When an application connects to files.corp.example, two lookups happen before a packet exists. The resolver decides which server receives the query, using search domains, per-link routing domains or an explicit profile rule. The routing table then decides where the resulting address goes, using longest-prefix match against the destination.
Nothing connects those two decisions. A private zone can answer with 10.20.4.11 while the routing table sends 10.20.0.0/16 into the tunnel, and the connection works. Flip either one and it fails in a way that looks like the other: DNS policy right plus a missing route gives a resolved name and a timeout, while a correct route plus a public resolver gives an address that routes cleanly to the wrong place.
Split-horizon DNS makes this sharper. The same name can return a private address from the internal resolver and a public address from the internet-facing one, so a note that records only the prefix cannot predict which address the client will actually use. Write down the resolver path or the address is a guess.
What a route-only note leaves out
A route-only record is unusable for the most common split-tunnel failure: names. The user reports that the intranet does not load, the tunnel is up, and the prefix is present. Whoever picks up the ticket has no record of which resolver should have answered, no way to tell a wrong search suffix from a blocked server, and no baseline to compare against.
The second omission is the exception list. A split-tunnel design is defined as much by what stays outside the tunnel as by what enters it, and the excluded ranges are usually the ones that break first, because a more specific local route or a client-side filter can override the intent without touching the profile.
The third is the far side of the tunnel. A client route only puts the packet on the wire; the gateway still has to forward it and have a path back. strongSwan's forwarding how-to is a reminder that forwarding and firewall rules on the gateway are part of the feature, not part of the plumbing you can assume.
The fields that make the note executable
One row per flow, and a flow is a destination plus a name plus an owner. These are the fields that survive contact with a real incident:
| Field | Why it has to be written down |
|---|---|
| Destination prefix and address family | The route is per family; an IPv4 note says nothing about a AAAA answer |
| Selected tunnel or direct path | Names the decision, not the symptom |
| Private namespace and resolver | Which domain, which server, which search suffix |
| Public name path | Confirms public names do not accidentally use the private resolver |
| Where the rule lives | Client profile, server push, OS policy or management tool |
| Owner and review date | Namespaces change owner more often than routes change |
The "where it lives" row is the one people skip. A prefix pushed by the server, a route added by a client profile and a route typed into a shell differ in who can change them and in whether they survive a reconnect. Without that field, the next engineer cannot tell which of the three they are looking at.
One test per rule, not one per tunnel
Each row needs two harmless checks: one that exercises the route and one that exercises the name. For the route, request something that must cross the tunnel and confirm the path rather than the reachability, for example tracert -d 10.20.4.11 on Windows or ip route get 10.20.4.11 on Linux. For the name, query the private name and record which server answered, using resolvectl query files.corp.example or dig files.corp.example against the resolver the note names.
Add a negative expectation too: what should happen when the tunnel is down. An excluded application on an Android or iOS device with block-without-VPN enabled may have no connectivity at all, and a desktop client can leave the same app working while the tunnel is reconnecting. Recording the intended answer turns "the VPN broke my app" into a checkable statement.
Keep the record with the configuration
Store the note next to the profile it describes and version it with that profile. A document in a wiki that nobody updates is a rumour; a table in the same repository as the pushed routes and the resolver policy can be reviewed in the same change.
When something breaks, compare the applied route and the effective resolver against the record before adding another exception. Two of the three common causes — an old namespace rule and a helper process outside the app policy — look exactly like a VPN fault and are invisible if the note only lists prefixes.
Before you call the note finished, confirm it answers these in writing: which prefix, for which address family; which private namespace, answered by which resolver; which names deliberately stay public; where each rule is configured and who owns it; and the one command that proves the route and the one that proves the name. If any of those is missing, the next incident will be diagnosed from scratch.