Gestão de clientes PiVPN: adicionar, listar, revogar e fazer backup (2026)

A maioria dos guias de PiVPN fica-se pela instalação. Essa é a parte que demora dez minutos e nunca mais volta. A parte que realmente volta a aparecer é tudo o que vem depois: um portátil novo precisa de um perfil, um telemóvel é roubado, alguém sai, você reconstrói a máquina.

Este é o guia do dia seguinte. Se ainda não o instalou, comece por PiVPN em 2026 e volte depois.

Tudo o que se segue é o que a wiki do PiVPN documenta. Sempre que um comando difere entre o modo WireGuard e o modo OpenVPN, ou sempre que estou a dar uma opinião em vez de citar a documentação, digo-o.

Os comandos que vale a pena memorizar

Este último importa mais do que parece. O PiVPN muda, os guias ficam desatualizados, e os dois modos não expõem um conjunto idêntico de comandos. pivpn -h na sua própria máquina vale mais do que qualquer tabela na internet, incluindo esta.

Adicionar clientes: um por dispositivo, sempre

pivpn add pede um nome e cria o perfil. A mecânica é trivial. A decisão que importa é quantos perfis você cria.

Dê a cada dispositivo o seu próprio perfil. Telemóvel, portátil, tablet, o portátil do companheiro: nomes separados, perfis separados. Não custa nada no momento da criação e é a única coisa que torna a revogação útil mais tarde.

A razão é simples. A revogação é por perfil. Se quatro dispositivos partilharem um perfil e um deles for roubado, a sua única opção é revogar esse perfil e cortar o acesso aos quatro, e depois voltar a inscrever os três que ainda tem, provavelmente à pressa e provavelmente mal. Se cada um tivesse o seu, revoga um e nada mais muda.

Dê-lhes nomes que digam o que são. pixel-8, portatil-trabalho, ipad-esposa. Daqui a seis meses, client1 até client5 no pivpn list não lhe dirão nada, e você vai hesitar exatamente no momento em que precisa de agir depressa.

Colocar a configuração num telemóvel

É aqui que as pessoas silenciosamente comprometem uma configuração que, de resto, é boa.

Uma configuração de cliente contém uma chave privada. Enviá-la por email, colocá-la num chat, ou deixá-la cair numa pasta partilhada na nuvem entrega essa chave a quem quer que guarde essas mensagens. A configuração não é uma palavra-passe que possa trocar sem custo, é a própria credencial.

pivpn -qr existe para isto. Apresenta a configuração como um código QR no servidor, e a aplicação móvel do WireGuard digitaliza-o diretamente a partir da janela do terminal. A chave nunca chega a tornar-se um ficheiro que viaja para lado nenhum.

Se tiver mesmo de mover uma configuração como ficheiro, mova-a por SSH para a máquina que dela precisa e apague a cópia depois. Não a deixe ficar na sua pasta de transferências.

Revogar: o que faz e o que não faz

pivpn remove pergunta que cliente remover. A wiki é explícita quanto ao efeito: uma vez removida, a configuração de cliente indicada já não lhe permitirá ligar-se.

Perceba com precisão o que isso lhe dá. Invalida a credencial no servidor. Não vai buscar nem apaga a configuração do dispositivo que perdeu. Quem tem esse ficheiro continua a tê-lo, simplesmente já não o pode usar contra o seu servidor.

Essa distinção importa para o que faz a seguir. Revogar o perfil é o primeiro passo certo e é suficiente para proteger o túnel. Não é razão para saltar o resto: se o dispositivo continha também outras credenciais, revogar um perfil VPN não faz nada quanto a essas.

Execute pivpn list primeiro. Remover o perfil errado porque dois dispositivos tinham nomes parecidos é um erro fácil de cometer e chato de desfazer.

Backups, e o erro que os torna inúteis

pivpn -bk produz um arquivo tar. A instrução da wiki é copiar esse arquivo para o seu computador, e a instrução é a metade importante.

Um backup que fica no servidor não é um backup. A falha contra a qual protege, o cartão SD que morre ou o VPS que é apagado, destrói o arquivo juntamente com tudo o resto. Copie-o para fora. Use scp para o levar para a sua própria máquina ou para o backup em que já confia.

Depois trate-o como um segredo. Esse arquivo contém chaves de cliente. Quem o ler pode fazer-se passar pelos seus dispositivos. Não pertence a um repositório público, a uma unidade partilhada, nem a uma pasta na nuvem sem encriptação.

Quando algo está mal, execute primeiro o diagnóstico

pivpn -d executa um conjunto de verificações e a wiki diz-lhe para confirmar que todas reportam [OK]. Faça isto antes de começar a editar ficheiros de configuração à mão.

Os problemas de VPN auto-hospedada são normalmente aborrecidos: uma porta que não foi encaminhada, um IP dinâmico que mudou, uma regra de firewall, um serviço que não voltou depois de um reinício. O diagnóstico apanha os casos aborrecidos em segundos. Editar configurações do WireGuard à mão à meia-noite porque uma ligação caiu é como uma configuração que funciona se torna uma configuração avariada.

Se o seu IP público mudar, isso não é de todo um problema do PiVPN, e nenhuma gestão de clientes o resolve. Veja o nosso guia sobre DNS dinâmico para uma VPN auto-hospedada para perceber a forma dessa solução.

Quando o terminal deixa de ser a ferramenta certa

O PiVPN gere os peers a partir da linha de comandos, e para um punhado de dispositivos essa é genuinamente a forma mais rápida de trabalhar.

Se der por si a adicionar e a revogar perfis com frequência, ou a entregar essa tarefa a alguém que não vai tocar num terminal, uma interface web é a resposta honesta, em vez de mais aliases de shell. O wg-easy cobre esse compromisso. E se ainda estiver a escolher a sua abordagem, a nossa comparação de VPNs auto-hospedadas coloca o PiVPN ao lado das opções de malha.

Uma rotina de operação curta

1. Um perfil por dispositivo, com o nome do dispositivo.
2. Entregue por código QR sempre que puder, nunca por chat ou email.
3. pivpn list antes de revogar, para cortar o certo.
4. pivpn -bk para fora da máquina, guardado como um segredo.
5. pivpn -d antes de depurar à mão.

O sítio onde o PiVPN corre importa tanto como a forma de o gerir. Um Raspberry Pi em casa está limitado pela sua velocidade de upload e precisa de um endereço estável; um VPS dá-lhe um IP público fixo e disponibilidade permanente por alguns euros por mês.

Execute o PiVPN num Contabo Cloud VPS →

Fontes

• Documentação do PiVPN (docs.pivpn.io), que remete os utilizadores para as wikis de cada modo para exemplos de comandos
• Wiki do PiVPN para WireGuard: pivpn add, pivpn list, pivpn remove, pivpn -qr, pivpn -bk, pivpn -d, pivpn -wg, pivpn -h

Guia editorial baseado nos comandos documentados do projeto PiVPN. Os conjuntos de comandos diferem entre os modos WireGuard e OpenVPN e mudam com o tempo: o que faz fe e o pivpn -h no seu proprio servidor, nao esta pagina. As ligacoes comerciais tem o atributo rel="sponsored nofollow"; pode aplicar-se uma comissao de afiliacao, sem custo adicional para si.