O que um pequeno manual de VPN precisa responder à pressa

A pessoa que assumiu o turno às 02:00 não conseguiu dizer se o serviço estava saudável, porque o documento explicava o desenho e nunca dizia o que executar. Entregar o ficheiro a outra pessoa e depois sair da sala é o único teste que importa. A maioria das notas pequenas de VPN falha nele já na segunda página. A forma abaixo passa nesse teste, e nada dela precisa de ser longo.

Comece por um mapa que uma pessoa cansada consiga percorrer

Anote o que alguém tem de consultar à pressa: os nomes a que os clientes se ligam, as portas em que o daemon escuta, os intervalos de endereços que distribui, como se resolvem os nomes dos clientes e que redes atrás do túnel devem ser alcançáveis. Acrescente o número de compilação que realmente executa e nomeie o componente que possui cada peça móvel, porque as rotas, o filtro de pacotes e os perfis de cliente são muitas vezes configurados em três locais diferentes. Anote também as dependências externas: a conta de alojamento, a ligação ascendente, o fornecedor de identidade e as redes privadas do extremo oposto. Uma tabela ou um diagrama desenhado à mão transportam isto melhor do que parágrafos, porque o leitor folheia em vez de ler.

Depois nomeie as pessoas que podem autorizar uma alteração de emergência, com uma via de contacto que não dependa de o túnel estar levantado. Uma linha de escalonamento sem alternativa é um beco sem saída precisamente no incidente que precisa dela. Dois nomes e um número de telefone bastam; o mapa não é um diretório de pessoal.

Cada verificação precisa da resposta que conta como saudável

Para cada serviço, coloque o comando e a linha que significa que funcionou um ao lado do outro, para que o leitor nunca tenha de deduzir um do outro à pressa. O estado do processo e a alcançabilidade de ponta a ponta estão em camadas diferentes: um mostra que o daemon aceitou a configuração, o outro que um cliente pode usar o que o túnel oferece. Escreva as duas linhas e diga que falha cada uma apanha, porque uma verificação sem resultado declarado transforma-se numa discussão sobre se a saída parece bem.

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

Execute as duas e trate-as como provas separadas em vez de uma sequência. Uma unidade verde pode estar ao lado de um túnel que ninguém consegue usar, e o contrário acontece quando um ouvinte sobrevive a uma rota quebrada. Declare a camada que cada linha observa, e o leitor saberá em qual confiar quando discordarem.

Três falhas cobrem a maioria das noites

Extremo inalcançável, identidade rejeitada e ligação sem tráfego útil explicam quase tudo o que acorda alguém. Para cada uma, liste as duas primeiras verificações e a pessoa a quem escalar, para que ninguém tenha de inventar uma ordem de diagnóstico às 02:00. Inalcançável aponta normalmente para o caminho ou para o ouvinte, uma identidade rejeitada para um certificado, um cofre de credenciais ou um relógio, e uma ligação vazia para rotas, encaminhamento ou resolução de nomes. Esses três ramos leem registos diferentes, e por isso o ramo tem de ser escolhido antes de o registo ser aberto.

Ligue a documentação de origem em vez de colar comandos que não executou neste anfitrião. Um comando não testado copiado de outro ambiente é pior do que um ponteiro, porque parece autorizado e falha em silêncio.

Escreva a alteração como sequência, não como parágrafo

Para qualquer alteração, anote o ponto de controlo ao qual pode voltar, a verificação que confirma o sucesso e a condição que desencadeia a reversão, nessa ordem. Inclua uma via de regresso que não passe pelo túnel, porque a alteração que está a fazer é exatamente o que o pode fechar. Anote como seriam restauradas as revogações atuais em vez de um instantâneo mais antigo, porque uma lista desatualizada volta a admitir em silêncio credenciais que foram retiradas nessa manhã. Passos imperativos numerados sobrevivem à pressão; a prosa transforma-se em interpretação.

Ensaie essa via de regresso antes de precisar dela, sempre que a alteração for suficientemente grande para importar. Uma reversão escrita de memória é uma conjetura com uma data colada.

As credenciais vivem noutro lugar

Refira o gestor de palavras-passe, o cofre ou o envelope selado, e diga quem o pode abrir, em vez de citar qualquer material no ficheiro. As chaves privadas, os códigos de recuperação de uso único e os perfis que incorporam um segredo pertencem a armazenamento protegido, e a página devia explicar como uma pessoa autorizada lhes chega às 02:00. Nunca use um segredo vivo como exemplo, porque os exemplos acabam colados em bilhetes e conversas. Um ponteiro mais uma lista de permissões é tudo o que o documento precisa.

Reveja o ficheiro após uma alteração real ou um exercício de recuperação, apague caminhos que já não existem e anote a quem cabe a próxima decisão de manutenção. Mantenha no fim um registo de alterações de três colunas: data, o que mudou, quem o verificou. É essa página que diz ao leitor seguinte se o resto está atual, e a documentação do systemctl do systemd é uma ligação melhor do que uma paráfrase de comandos de serviço que acabarão por derivar.