Wat een kleine VPN-handleiding snel moet kunnen beantwoorden

De beheerder die om 02:00 overnam, kon niet zeggen of de dienst gezond was, omdat het document het ontwerp uitlegde en nooit zei wat er moest worden uitgevoerd. Het bestand aan iemand anders geven en dan de kamer verlaten is de enige test die ertoe doet. De meeste kleine VPN-notities zakken daar al op de tweede pagina voor. De vorm hieronder doorstaat die test, en niets ervan hoeft lang te zijn.

Begin met een kaart die een moe iemand kan scannen

Schrijf op wat iemand halsoverkop moet opzoeken: de namen waarop clients verbinden, de poorten waarop de daemon luistert, de adrespoelen die hij uitgeeft, hoe clientnamen worden opgelost en welke netwerken achter de tunnel bereikbaar moeten zijn. Voeg het buildnummer toe dat je echt draait, en noem de component die elk bewegend deel bezit, omdat routes, packetfilter en clientprofielen vaak op drie verschillende plekken worden geconfigureerd. Noteer ook de externe afhankelijkheden: het hostingaccount, de uplink, de identiteitsprovider en de privénetwerken aan de andere kant. Een tabel of een handgetekend diagram draagt dit beter dan alinea's, omdat de lezer scant in plaats van leest.

Noem daarna de mensen die een noodgewijziging mogen goedkeuren, met een contactroute die niet afhangt van of de tunnel draait. Een escalatielijn zonder terugvaloptie is een doodlopende weg precies in het incident dat haar nodig heeft. Twee namen en één telefoonnummer zijn genoeg; de kaart is geen personeelslijst.

Elke controle heeft het antwoord nodig dat als gezond geldt

Zet voor elke dienst het commando en de regel die betekent dat het gelukt is naast elkaar, zodat de lezer nooit het ene uit het andere hoeft af te leiden onder tijdsdruk. Procestoestand en bereikbaarheid van begin tot eind zitten op verschillende lagen: het ene laat zien dat de daemon zijn configuratie heeft geaccepteerd, het andere dat een client kan gebruiken wat de tunnel biedt. Schrijf beide regels op en zeg welke fout elk ervan vangt, want een controle zonder genoemd resultaat wordt een discussie over of de uitvoer er goed uitziet.

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

Voer beide uit, en behandel ze als afzonderlijk bewijs in plaats van als een reeks. Een groene unit kan naast een tunnel staan die niemand kan gebruiken, en het omgekeerde gebeurt wanneer een listener een kapotte route overleeft. Noem de laag die elke regel observeert, en de lezer weet welke te vertrouwen wanneer ze het oneens zijn.

Drie storingen dekken de meeste nachten

Eindpunt onbereikbaar, identiteit geweigerd en verbonden zonder nuttig verkeer verklaren bijna alles wat iemand wakker maakt. Noem voor elk de eerste twee controles en de persoon naar wie geëscaleerd wordt, zodat niemand om 02:00 een diagnosereeks hoeft te bedenken. Onbereikbaar wijst meestal op het pad of de listener, een geweigerde identiteit op een certificaat, een credentialstore of een klok, en een lege verbinding op routes, doorsturen of naamresolutie. Die drie takken lezen verschillende logs, daarom moet de tak worden gekozen voordat de log wordt geopend.

Link naar de documentatie upstream in plaats van commando's te plakken die je niet op deze host hebt uitgevoerd. Een ongetest commando dat uit een andere omgeving is gekopieerd is slechter dan een verwijzing, omdat het gezaghebbend lijkt en stilletjes faalt.

Schrijf de wijziging als een reeks, niet als een alinea

Noteer voor elke wijziging het controlepunt waar je naar terug kunt, de controle die succes bevestigt en de voorwaarde die de terugrol activeert, in die volgorde. Neem een weg terug op die niet door de tunnel loopt, omdat juist de wijziging die je maakt die kan sluiten. Noteer hoe huidige intrekkingen zouden worden hersteld in plaats van een oudere momentopname, omdat een verouderde lijst stilletjes referenties opnieuw toelaat die die ochtend zijn ingetrokken. Genummerde imperatieve stappen overleven druk; proza wordt interpretatie.

Oefen die weg terug voordat je hem nodig hebt, telkens wanneer de wijziging groot genoeg is om ertoe te doen. Een terugrol die uit het geheugen is geschreven is een gok met een datum eraan vast.

Referenties wonen ergens anders

Verwijs naar de wachtwoordmanager, de kluis of de verzegelde envelop, en zeg wie hem mag openen, in plaats van materiaal in het bestand te citeren. Privésleutels, eenmalige herstelcodes en profielen die een geheim insluiten horen in beschermde opslag, en de pagina zou moeten uitleggen hoe een gemachtigde beheerder ze om 02:00 bereikt. Gebruik nooit een levend geheim als voorbeeld, omdat voorbeelden in tickets en chattrheads worden geplakt. Een verwijzing plus een rechtenlijst is alles wat het document nodig heeft.

Loop het bestand na na een echte wijziging of een hersteloefening, verwijder paden die niet meer bestaan en noteer wiens taak de volgende onderhoudsbeslissing is. Houd aan het eind een wijzigingslog met drie kolommen bij: datum, wat er veranderde, wie het verifieerde. Die pagina is wat de volgende lezer vertelt of de rest actueel is, en de systemctl-documentatie van systemd is een betere link dan een parafrase van dienstcommando's die zullen afdrijven.