What a Small VPN Runbook Needs to Answer in a Hurry

The maintainer who took over at 02:00 could not tell whether the service was healthy, because the document explained the design and never said what to run. Handing the file to somebody else, then leaving the room, is the only test that matters. Most small VPN notes fail it on the second page. The shape below survives that test, and none of it needs to be long.

Start with a map a tired person can scan

Write down what somebody has to look up in a hurry: the names clients connect to, the ports the daemon listens on, the address pools it hands out, how client names get resolved, and which networks behind the tunnel are meant to be reachable. Add the build number you actually run, and name the component that owns each moving part, because routes, packet filter and client profiles are often configured in three different places. Note the outside dependencies too: the hosting account, the uplink, the identity provider and the private networks at the far end. A table or a hand-drawn diagram carries this better than paragraphs, since the reader is scanning rather than reading.

Then name the people who can authorise an emergency change, with a contact route that does not depend on the tunnel being up. An escalation line with no fallback is a dead end in exactly the incident that needs it. Two names and one phone number are enough; the map is not a staff directory.

Every check needs the answer that counts as healthy

For each service, put the command and the line that means it worked next to each other, so the reader never has to derive one from the other at speed. Process state and end-to-end reachability sit at different layers: one shows the daemon accepted its configuration, the other shows a client can use what the tunnel offers. Write both lines, and say which failure each one catches, because a check with no stated result turns into an argument about whether the output looks fine.

systemctl status openvpn-server@lab
ss -lntu | grep 1194

Run both, and treat them as separate evidence rather than a sequence. A green unit can sit next to a tunnel that nobody can use, and the reverse happens when a listener survives a broken route. State the layer each line observes, and the reader will know which one to trust when they disagree.

Three failures cover most nights

Endpoint unreachable, identity rejected, and connected with no useful traffic account for nearly everything that wakes somebody up. For each, list the first two checks and the person to escalate to, so nobody has to invent a diagnostic order at 02:00. Unreachable usually points at the path or the listener, a rejected identity at a certificate, a credential store or a clock, and an empty connection at routes, forwarding or name resolution. Those three branches read different logs, which is why the branch has to be chosen before the log is opened.

Link the upstream documentation instead of pasting commands you have not run on this host. An untested command copied from another environment is worse than a pointer, because it looks authoritative and fails quietly.

Write the change as a sequence, not a paragraph

For any change, record the checkpoint you can return to, the check that confirms success, and the condition that triggers rollback, in that order. Include a way back in that does not run through the tunnel, since the change you are making is exactly what can close it. Note how current revocations would be restored rather than an older snapshot, because a stale list silently re-admits credentials that were retired that morning. Numbered imperative steps survive pressure; prose turns into interpretation.

Exercise that way back before you need it, whenever the change is big enough to matter. A rollback written from memory is a guess with a date attached.

Credentials live somewhere else

Reference the password manager, the vault or the sealed envelope, and say who may open it, rather than quoting any material in the file. Private keys, one-time recovery codes and profiles that embed a secret belong in protected storage, and the page should explain how an authorised maintainer reaches them at 02:00. Never use a live secret as an example, because examples get pasted into tickets and chat threads. A pointer plus a permission list is all the document needs.

Review the file after a real change or a recovery exercise, delete paths that no longer exist, and note whose job the next upkeep decision is. Keep a three-column change log at the end: date, what changed, who verified it. That page is what tells the next reader whether the rest is current, and the systemd systemctl documentation is a better link than a paraphrase of service commands that will drift.