Què ha de respondre de pressa un petit manual de VPN

El responsable que va agafar el torn a les 02:00 no va poder dir si el servei estava sa, perquè el document explicava el disseny i no deia mai què calia executar. Passar el fitxer a una altra persona i marxar de la sala és l’únic test que compte. La majoria de notes petites de VPN el suspenen a la segona pàgina. La forma de sota supera aquest test, i res no hi ha de ser llarg.

Comenceu amb un mapa que una persona cansada pugui escanejar

Apunteu què ha de consultar algú amb pressa: els noms als quals es connecten els clients, els ports on escolta el dimoni, els conjunts d’adreces que reparteix, com es resolen els noms dels clients i quines xarxes darrere del túnel han de ser abastables. Afegiu el número de compilació que realment executeu i anomeneu el component que posseeix cada peça mòbil, perquè les rutes, el filtre de paquets i els perfils de client sovint es configuren en tres llocs diferents. Anoteu també les dependències externes: el compte d’allotjament, l’enllaç ascendent, el proveïdor d’identitat i les xarxes privades de l’extrem oposat. Una taula o un diagrama dibuixat a mà ho porten millor que els paràgrafs, perquè el lector fulleja en lloc de llegir.

Després anomeneu les persones que poden autoritzar un canvi d’emergència, amb una via de contacte que no depengui que el túnel estigui aixecat. Una línia d’escalat sense alternativa és un cul-de-sac justament en l’incident que la necessita. Dos noms i un telèfon són prou; el mapa no és un directori de personal.

Cada comprovació necessita la resposta que compta com a sana

Per a cada servei, poseu l’ordre i la línia que significa que ha funcionat l’una al costat de l’altra, perquè el lector no hagi de deduir mai l’una de l’altra amb pressa. L’estat del procés i l’abastabilitat d’extrem a extrem seuen en capes diferents: una mostra que el dimoni ha acceptat la seva configuració, l’altra que un client pot fer servir el que ofereix el túnel. Escriviu les dues línies i digueu quina fallada atrapa cadascuna, perquè una comprovació sense resultat declarat es converteix en una discussió sobre si la sortida sembla bé.

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

Executeu les dues i tracteu-les com a proves separades en lloc d’una seqüència. Una unitat verda pot seure al costat d’un túnel que ningú no pot fer servir, i el contrari passa quan un oient sobreviu a una ruta trencada. Declareu la capa que observa cada línia, i el lector sabrà de quina fiar-se quan no coincideixin.

Tres fallades cobreixen la majoria de nits

Punt final inabastable, identitat rebutjada i connectat sense trànsit útil expliquen gairebé tot el que desperta algú. Per a cadascuna, lliste les dues primeres comprovacions i la persona a qui escalar, perquè ningú no hagi d’inventar un ordre de diagnòstic a les 02:00. Inabastable sol apuntar al camí o a l’oient, una identitat rebutjada a un certificat, un magatzem de credencials o un rellotge, i una connexió buida a rutes, reenviament o resolució de noms. Aquestes tres branques llegeixen registres diferents, i per això la branca s’ha de triar abans d’obrir el registre.

Enllaceu la documentació d’origen en lloc d’enganxar ordres que no heu executat en aquest host. Una ordre no provada copiada d’un altre entorn és pitjor que un punter, perquè sembla autoritària i falla en silenci.

Escriviu el canvi com una seqüència, no com un paràgraf

Per a qualsevol canvi, anoteu el punt de control al qual podeu tornar, la comprovació que confirma l’èxit i la condició que desencadena la reversió, en aquest ordre. Incloeu una via de tornada que no passi pel túnel, perquè el canvi que feu és exactament el que el pot tancar. Anoteu com es restaurarien les revocacions actuals en lloc d’una instantània més antiga, perquè una llista obsoleta readmet en silenci credencials que es van retirar aquell matí. Els passos imperatius numerats sobreviuen a la pressió; la prosa es converteix en interpretació.

Assageu aquesta via de tornada abans de necessitar-la, sempre que el canvi sigui prou gran per importar. Una reversió escrita de memòria és una conjectura amb una data enganxada.

Les credencials viuen en un altre lloc

Feu referència al gestor de contrasenyes, la caixa forta o el sobre segellat, i digueu qui el pot obrir, en lloc de citar cap material al fitxer. Les claus privades, els codis de recuperació d’un sol ús i els perfils que incrusten un secret pertanyen a un emmagatzematge protegit, i la pàgina hauria d’explicar com hi arriba un responsable autoritzat a les 02:00. No feu servir mai un secret viu com a exemple, perquè els exemples s’enganxen en tiquets i fils de xat. Un punter més una llista de permisos és tot el que el document necessita.

Reviseu el fitxer després d’un canvi real o un exercici de recuperació, esborreu camins que ja no existeixen i anoteu de qui és la propera decisió de manteniment. Manteniu al final un registre de canvis de tres columnes: data, què va canviar, qui ho va verificar. Aquesta pàgina és la que diu al lector següent si la resta està al dia, i la documentació de systemctl de systemd és un enllaç millor que una paràfrasi d’ordres de servei que acabaran derivant.