Vad en liten VPN-driftmanual måste svara på i en fart

Den driftansvarige som tog över klockan 02:00 kunde inte säga om tjänsten var frisk, eftersom dokumentet förklarade designen och aldrig sa vad som skulle köras. Att lämna filen till någon annan och sedan lämna rummet är det enda test som betyder något. De flesta små VPN-anteckningar faller på det redan på andra sidan. Formen nedan klarar det testet, och ingenting i den behöver vara långt.

Börja med en karta som en trött människa kan skumma

Skriv ner vad någon måste slå upp i en fart: namnen klienterna ansluter till, portarna daemonen lyssnar på, adresspoolerna den delar ut, hur klientnamn löses upp och vilka nätverk bakom tunneln som ska gå att nå. Lägg till byggnumret du faktiskt kör, och namnge komponenten som äger varje rörlig del, eftersom rutter, paketfilter och klientprofiler ofta konfigureras på tre olika ställen. Notera också de yttre beroendena: hostingkontot, upplänken, identitetsleverantören och de privata näten i den bortre änden. En tabell eller ett handritat diagram bär detta bättre än stycken, eftersom läsaren skummar i stället för att läsa.

Namnge sedan personerna som får godkänna en nödändring, med en kontaktväg som inte hänger på att tunneln är uppe. En eskaleringslinje utan reserv är en återvändsgränd just i den händelse som behöver den. Två namn och ett telefonnummer räcker; kartan är inte en personalförteckning.

Varje kontroll behöver svaret som räknas som friskt

För varje tjänst, sätt kommandot och raden som betyder att det lyckades bredvid varandra, så att läsaren aldrig behöver härleda det ena ur det andra i en fart. Processtatus och nåbarhet från ände till ände ligger på olika lager: det ena visar att daemonen accepterade sin konfiguration, det andra att en klient kan använda det tunneln erbjuder. Skriv båda raderna och säg vilket fel var och en fångar, eftersom en kontroll utan angivet resultat blir en diskussion om huruvida utdata ser bra ut.

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

Kör båda och behandla dem som separata bevis i stället för en sekvens. En grön enhet kan stå bredvid en tunnel som ingen kan använda, och det omvända händer när en lyssnare överlever en bruten rutt. Ange lagret som varje rad observerar, och läsaren vet vilket som går att lita på när de inte stämmer.

Tre fel täcker de flesta nätter

Ändpunkt oåtkomlig, identitet avvisad och ansluten utan nyttig trafik förklarar nästan allt som väcker någon. För var och en, lista de två första kontrollerna och personen det eskaleras till, så att ingen behöver hitta på en diagnosordning klockan 02:00. Oåtkomlighet pekar oftast på vägen eller lyssnaren, en avvisad identitet på ett certifikat, ett credentiallager eller en klocka, och en tom anslutning på rutter, vidarebefordran eller namnmatchning. De tre grenarna läser olika loggar, och därför måste grenen väljas innan loggen öppnas.

Länka till dokumentationen ovan i stället för att klistra in kommandon du inte har kört på den här värden. Ett otestat kommando kopierat från en annan miljö är sämre än en hänvisning, eftersom det ser auktoritativt ut och misslyckas tyst.

Skriv ändringen som en sekvens, inte som ett stycke

För varje ändring, notera den kontrollpunkt du kan gå tillbaka till, kontrollen som bekräftar framgång och villkoret som utlöser återrullning, i den ordningen. Ta med en väg tillbaka som inte går genom tunneln, eftersom just den ändring du gör kan stänga den. Notera hur nuvarande återkallelser skulle återställas i stället för en äldre ögonblicksbild, eftersom en inaktuell lista tyst tar in referenser igen som drogs in den morgonen. Numrerade imperativa steg tål press; prosa blir tolkning.

Öva den vägen tillbaka innan du behöver den, varje gång ändringen är stor nog att betyda något. En återrullning skriven ur minnet är en gissning med ett datum fäst vid sig.

Referenser bor någon annanstans

Hänvisa till lösenordshanteraren, valvet eller det förseglade kuvertet, och säg vem som får öppna det, i stället för att citera material i filen. Privata nycklar, engångskoder för återställning och profiler som bäddar in en hemlighet hör hemma i skyddad lagring, och sidan bör förklara hur en behörig driftansvarig når dem klockan 02:00. Använd aldrig en levande hemlighet som exempel, eftersom exempel klistras in i ärenden och chattrådar. En hänvisning plus en behörighetslista är allt dokumentet behöver.

Gå igenom filen efter en verklig ändring eller en återställningsövning, ta bort sökvägar som inte längre finns och notera vems uppgift nästa underhållsbeslut är. Håll en ändringslogg med tre kolumner i slutet: datum, vad som ändrades, vem som verifierade det. Det är den sidan som talar om för nästa läsare om resten är aktuell, och systemctl-dokumentationen från systemd är en bättre länk än en parafras av tjänstekommandon som kommer att glida.