WireGuard adicionar peer: em direto, sem reiniciar o túnel

A maioria dos guias responde a «como adiciono um peer WireGuard?» com wg-quick down wg0 && wg-quick up wg0. Funciona, e também desliga toda a gente que está a usar o túnel nesse momento, só para acrescentar uma linha a um ficheiro. Num servidor com meia dúzia de clientes é um incómodo breve. Num servidor de que dependes a sério, é a razão pela qual as pessoas evitam adicionar peers de todo.

Há um comando que o faz em direto.

Como se adiciona um peer ao WireGuard?

Uma linha, na interface em funcionamento:

wg set wg0 peer <CLIENT_PUBLIC_KEY> allowed-ips 10.0.0.5/32

O peer existe a partir desse momento. Sem reinício, sem handshakes perdidos, sem interrupção para quem já está ligado. O wg set fala diretamente com o módulo do kernel e edita a configuração ativa da interface.

Confirma que ficou aplicado:

wg show wg0

A nova chave pública aparece na lista, ainda sem handshake, o que é normal: o handshake acontece quando o cliente envia tráfego pela primeira vez.

Como se adiciona um peer pela linha de comandos, do início ao fim?

Na máquina cliente, gera o par de chaves:

wg genkey | tee client.key | wg pubkey > client.pub

client.key é a chave privada e nunca sai dessa máquina. client.pub é o que o servidor precisa.

No servidor:

wg set wg0 peer "$(cat client.pub)" allowed-ips 10.0.0.5/32

De volta ao cliente, o ficheiro de configuração precisa da chave pública do servidor, do seu endpoint e do endereço que acabaste de atribuir:

[Interface]
PrivateKey = <contents of client.key>
Address = 10.0.0.5/32

[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

As duas chaves são o passo em que as pessoas se enganam: cada lado guarda a chave pública do outro lado, nunca a sua.

Se o novo cliente for um telemóvel, ou uma máquina sem wg instalado, podes produzir o lado dele sem terminal. Configura o nosso gerador de configuração WireGuard gratuito para um cliente, com o endpoint e a sub-rede do teu servidor: ele cria o par de chaves no teu navegador e dá-te o ficheiro do cliente, o respetivo código QR e o bloco [Peer] correspondente para o servidor. Há duas coisas a verificar antes de o usar. O gerador inventa o seu próprio par de chaves do servidor, por isso substitui PublicKey no bloco [Peer] do cliente pela tua chave real, obtida com wg show wg0 public-key. E atribui ao primeiro cliente o endereço .2 da sub-rede, por isso altera Address (e o allowed-ips que passas ao wg set) se esse já estiver ocupado. A chave privada do cliente e a chave pública que entregas ao servidor estão prontas tal como estão. O gerador é gratuito até 10 dispositivos; acima disso, o WireGuard Pro (o nosso próprio produto, 9 EUR uma única vez, sem subscrição) sobe o limite para 250 e acrescenta um ZIP com o .conf de cada cliente e o respetivo código QR em PNG, prático para configurar um escritório ou uma família inteira de uma só vez.

O que vai em AllowedIPs quando adicionas um peer?

Depende do lado em que estás, e esta assimetria é a origem da maior parte da confusão.

A regra da não sobreposição é estrutural, não uma questão de arrumação. É o AllowedIPs que diz ao WireGuard a que peer pertence um dado destino, por isso um endereço listado em dois peers torna essa decisão ambígua, e o sintoma prático é que adicionar um cliente deita abaixo o anterior em silêncio.

Do lado do cliente, o túnel completo 0.0.0.0/0 é fácil; «tudo exceto a minha LAN» não é, porque o AllowedIPs não tem sintaxe de exclusão. A nossa calculadora de AllowedIPs gratuita transforma «tudo exceto X» na lista mais curta de intervalos IPv4 e IPv6 para colar no bloco [Peer] do novo cliente.

Como fazer o novo peer sobreviver a um reinício?

O wg set altera a interface em funcionamento. Não toca em /etc/wireguard/wg0.conf, por isso um reinício esquece-o. Há duas formas de o tornar persistente.

Acrescentar o bloco ao ficheiro à mão:

[Peer]
PublicKey = <CLIENT_PUBLIC_KEY>
AllowedIPs = 10.0.0.5/32

Não voltes a escrever o estado ativo com wg showconf wg0 > /etc/wireguard/wg0.conf, um atalho que circula muito. O wg showconf só sabe o que o kernel sabe: a chave privada, a porta de escuta e os peers. Não tem nenhuma das linhas do wg-quick (Address, DNS, MTU, PostUp, PostDown). Se sobrescreveres o ficheiro com ele, o próximo wg-quick up levanta wg0 sem endereço de túnel e sem regras de NAT, por isso todos os clientes fazem handshake e nada é encaminhado.

Se quiseres que o estado em execução seja guardado por ti, define SaveConfig = true em [Interface]. O wg-quick volta então a escrever os peers quando a interface é desligada e mantém as suas próprias linhas. O senão: reescreve o ficheiro inteiro nesse momento, por isso um comentário ou uma edição manual feita com o túnel ativo perde-se. Escolhe um método, ficheiro editado à mão ou SaveConfig, não os dois.

Para recarregar um ficheiro editado sem cortar sessões:

wg syncconf wg0 <(wg-quick strip wg0)

O syncconf aplica as diferenças. O wg-quick down/up não: reconstrói a interface de raiz, que é exatamente o que estavas a tentar evitar.

Como automatizar a adição de peers em Linux com um script?

A sequência não tem nenhum passo interativo, por isso passa diretamente para um script:

#!/usr/bin/env bash
set -euo pipefail
NAME="$1"; IP="$2"          # ./addpeer.sh laptop 10.0.0.7
umask 077
wg genkey | tee "$NAME.key" | wg pubkey > "$NAME.pub"
wg set wg0 peer "$(cat "$NAME.pub")" allowed-ips "$IP/32"
printf '\n[Peer]\n# %s\nPublicKey = %s\nAllowedIPs = %s/32\n' \
  "$NAME" "$(cat "$NAME.pub")" "$IP" >> /etc/wireguard/wg0.conf
echo "added $NAME at $IP"

O umask 077 é importante: sem ele, a chave privada acabada de escrever fica legível por todas as contas da máquina. O set -euo pipefail também é importante: sem ele, um wg set falhado deixa-te na mesma com os ficheiros de chaves e uma alegre mensagem de sucesso. A linha printf acrescenta o peer ao ficheiro em vez de o reescrever, pela razão dada na secção anterior.

Uma versão mais completa deste script está disponível gratuitamente no GitHub: o wg-newpeer.sh também gera uma chave pré-partilhada, escreve o .conf do cliente em ./clients/, aplica a alteração com wg syncconf e mostra um código QR quando o qrencode está instalado. Vem incluído no nosso WireGuard Self-Hosting Kit pago (9 USD, em inglês), ao lado dos modelos de servidor e de cliente, da checklist de diagnóstico com 12 causas e da checklist de reforço de segurança, se quiseres o conjunto completo em ficheiros.

Uma mão pousada no teclado enquanto o monitor continua negro: adicionar um peer com wg set não produz qualquer confirmação visível, e é por isso que o wg show é a única coisa que te diz que funcionou.

Porque é que o novo peer não liga?

O comando teve sucesso e não acontece nada. Na prática é quase sempre uma de quatro coisas, e as quatro podem ser verificadas em vez de adivinhadas.

1. As chaves estão trocadas. O servidor guarda a chave pública do cliente; o cliente guarda a do servidor. Pôr uma chave privada onde devia estar uma pública falha em silêncio.
2. O cliente está atrás de NAT sem PersistentKeepalive. O servidor não tem caminho de regresso até o cliente falar primeiro, e entretanto o mapeamento NAT expira. PersistentKeepalive = 25 do lado do cliente mantém-no aberto.
3. O endereço já está ocupado. Dois peers com o mesmo AllowedIPs é o caso que parece mais misterioso, porque é o peer mais antigo que deixa de funcionar.
4. A porta UDP do servidor não está acessível a partir do exterior. Os peers existentes na LAN continuam a funcionar, por isso o servidor parece estar bem, mas um novo peer em dados móveis nunca obtém um handshake. O nosso verificador de porta WireGuard gratuito diz-te se o teu router consegue sequer redirecionar a porta (deteta CGNAT e duplo NAT) e dá-te a regra de firewall para o teu sistema. Se a resposta for CGNAT, nenhum redirecionamento de porta o resolve: a saída habitual é correr o servidor num VPS com o seu próprio IPv4 público, como um VPS Cloud da Contabo (link de afiliado), e adicionar lá os teus peers. Se preferires um fornecedor dos EUA com 30 dias de reembolso, o VPS Basic da Ultahost custa 5,52 $ por mês num prazo de 24 meses (1 GB de RAM, IPv4 dedicado, lido a 21 de outubro de 2026), suficiente para um servidor WireGuard com poucos dispositivos.

Essa terceira falha é a razão de existir do wg-clients-audit. Lê uma pasta de configurações de clientes e assinala endereços duplicados, chaves privadas reutilizadas e intervalos AllowedIPs suficientemente largos para engolir a rede local, as três falhas que produzem um túnel que liga e depois se comporta de forma estranha. Executá-lo antes de entregares uma configuração a alguém é mais rápido do que diagnosticar o problema depois.

Começa por wg show wg0. Um peer sem latest handshake nunca completou nenhum, o que aponta para as chaves ou para a acessibilidade. Um peer que faz handshake mas não transporta dados aponta para o AllowedIPs.

Enquanto editas um bloco de peer, é o momento certo para considerar uma chave pré-partilhada: um wg genpsk por par de peers, misturado no handshake, e tem de coincidir nas duas pontas, caso contrário o túnel fica em silêncio.

Uma VPN muda o teu IP. Não muda o teu navegador.

Um túnel substitui o endereço que um serviço vê. Não muda nada do que o teu navegador anuncia por si próprio (tipos de letra, ecrã, fuso horário, pilha gráfica), e essa combinação é muitas vezes estável o suficiente para te reconhecer de uma sessão para outra, com ou sem túnel.

Mede a tua impressão digital de navegador: medição passiva, sem perguntas, sem conta, sem e-mail.

O que reter

O wg set adiciona um peer em direto; o wg-quick down/up desliga toda a gente para fazer o mesmo trabalho. Tudo o que adicionas em direto desaparece no reinício, a menos que o escrevas também na configuração, e o wg showconf não é um ficheiro de configuração: redireciona-o por cima do wg0.conf e perdes Address e PostUp. Um /32 por cliente, nunca sobrepostos. E quando um novo peer se porta mal, verifica wg show antes de mudar o que quer que seja: a diferença entre «sem handshake» e «handshake mas sem tráfego» diz-te para que metade da configuração deves olhar.

E se estavas prestes a copiar uma configuração para um segundo dispositivo em vez de adicionar um peer, o sintoma que se segue está documentado: dois dispositivos, uma chave WireGuard (em inglês).