WireGuard PersistentKeepalive: manter o túnel alcançável atrás de NAT (2026)

Divulgação de afiliação - Este artigo contém links afiliados da Contabo. Se adquirires um VPS através deles, ganhamos uma comissão sem custo adicional para ti. Cada valor e comportamento aqui abaixo está documentado a partir das fontes oficiais do WireGuard e escrito para ser reproduzível na tua própria máquina.

O teu cliente WireGuard liga-se, funciona durante um minuto e depois fica calado: alcanças o servidor a partir do cliente, mas o servidor já não consegue devolver-te nada. Um SSH a partir do lado do servidor bloqueia, um dispositivo da LAN atrás do cliente fica inalcançável, o handshake expira em silêncio. A correção é quase sempre uma linha no cliente: PersistentKeepalive = 25. Este guia explica exatamente o que essa opção faz, porque 25 segundos é o número mágico, e a que lado do túnel pertence.

A resposta curta

Se um peer estiver atrás de NAT e precisar de continuar alcançável, adiciona isto ao bloco [Peer] na configuração desse peer:

[Peer]
PublicKey = ...
Endpoint = server.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Reinicia o túnel e o problema do túnel mudo após inatividade desaparece. Tudo o que se segue é o porquê.

O que o PersistentKeepalive faz

Por conceção, o WireGuard é silencioso: quando não há nada para enviar, não envia nada. Sem keepalives, sem heartbeats, sem conversa. Isso torna-o eficiente e difícil de identificar por fingerprint - mas quebra um cenário específico.

Quando um cliente está atrás de NAT (um router doméstico, um operador móvel, uma firewall de escritório), o equipamento NAT cria um mapeamento temporário na primeira vez que o cliente envia um pacote para fora. É esse mapeamento que permite ao servidor enviar as respostas de volta para o endereço interno correto - pensa nele como um furo aberto no NAT. Crucialmente, esse furo expira após um período de inatividade, muitas vezes algures entre 30 segundos e alguns minutos no UDP. Assim que fecha, os pacotes do servidor deixam de ter para onde ir, e o peer fica inalcançável até o cliente voltar a falar primeiro.

PersistentKeepalive resolve isto enviando um pequeno pacote keepalive vazio ao peer a cada N segundos. Esse minúsculo tráfego mantém o mapeamento NAT renovado, por isso o furo nunca fecha e o peer continua alcançável mesmo em repouso.

Porquê 25 segundos

A recomendação oficial do WireGuard é 25 segundos, e o raciocínio é simples. Os timeouts NAT UDP comuns situam-se entre 30 segundos e alguns minutos, e o valor mais curto que se encontra regularmente ronda os 30 segundos. Enviar um keepalive a cada 25 segundos renova o mapeamento com uma pequena margem antes desse limite dos 30 segundos - frequente o suficiente para nunca deixar o furo fechar, raro o suficiente para não custar quase nada.

Podes descer mais se o teu NAT for invulgarmente agressivo (15 é um próximo passo razoável), ou subir para poupar bateria no móvel, mas 25 é o valor predefinido documentado, e não por acaso. Não penses demasiado nisto.

Onde o colocar: cliente vs servidor

É aqui que as pessoas erram. O keepalive vai no peer que precisa de continuar alcançável através de um NAT:

No caso normal - um portátil ou telemóvel atrás de um router a falar com um VPS com IP público real - só o cliente precisa de PersistentKeepalive = 25, no bloco [Peer] que descreve o servidor. O servidor não precisa de nenhum na direção dos seus clientes: o cliente inicia sempre, e o servidor limita-se a responder para o endereço de origem de onde veio o último pacote. Um servidor com IP público limpo é exatamente a configuração em que evitas por completo o problema de NAT do lado do servidor.

Exemplo de configuração [Peer]

Eis um bloco de peer completo do lado do cliente com o keepalive no lugar:

[Interface]
PrivateKey = <client-private-key>
Address = 10.66.66.2/32
DNS = 10.66.66.1

[Peer]
PublicKey = <server-public-key>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

Aplica-o com um reinício do túnel:

sudo wg-quick down wg0 && sudo wg-quick up wg0

Confirma que teve efeito - wg show lista o intervalo por baixo do peer:

sudo wg show
# persistent keepalive: every 25 seconds

Se estiveres a montar configurações de raiz, os modelos de configuração WireGuard prontos a usar já incluem a linha keepalive no bloco certo para cada plataforma.

O erro "interval must be in range"

PersistentKeepalive espera um simples número inteiro de segundos, validado contra o intervalo 0-65535. Se vires interval must be in range ou must be in range 0 to 65535, passaste algo que não é um inteiro válido nessa janela:

• Um sufixo de unidade - escreve 25, não 25s.
• Um decimal - 25, não 25.0.
• Um número negativo, ou um valor acima de 65535.
• Um espaço estranho ou caractere invisível colado de uma página web.

Um valor de 0 é legal e significa desativado - o mesmo que deixar a linha de fora por completo. Por isso PersistentKeepalive = 0 não serve de nada; usa um intervalo real como 25.

Keepalive definido mas continua sem funcionar

Se adicionaste a linha e o túnel continua a ficar calado após inatividade, percorre estas causas honestas por ordem:

• Definido no lado errado. É o peer que está atrás de NAT que precisa dele. Um keepalive apenas no servidor com IP público não mantém aberto o furo NAT de um cliente.
• Timeout NAT mais curto do que o teu intervalo. Alguns carrier-grade NAT fecham os mapeamentos UDP mais depressa do que 30 segundos. Desce o intervalo para 15 e testa de novo.
• Uma firewall bloqueia o caminho. Se a porta UDP subjacente estiver filtrada, nenhum keepalive passará - confirma que a porta do WireGuard está mesmo aberta em ambas as extremidades.
• O endpoint mudou (roaming). Se o cliente mudou de rede e o seu endereço público mudou, o servidor pode continuar a apontar para o Endpoint antigo. O keepalive ajuda o servidor a acompanhar a nova origem, mas um Endpoint desatualizado do lado do cliente pode ainda assim falhar.

Keepalive vs handshake do WireGuard

São dois temporizadores diferentes, e ajuda separá-los. O WireGuard renova o seu handshake criptográfico aproximadamente a cada dois minutos - mas apenas quando há tráfego real a proteger. Numa ligação inativa sem keepalive, nenhum tráfego significa nenhuma renovação de handshake, e entretanto o furo NAT fecha-se em silêncio.

PersistentKeepalive preenche exatamente essa lacuna: mantém um fio de tráfego numa ligação de outro modo inativa, mantendo o mapeamento NAT aberto entre handshakes para que o túnel esteja pronto no instante em que dados reais precisam de circular. O keepalive não substitui o handshake; mantém o caminho vivo para que o handshake possa acontecer quando for preciso.

Um servidor com IP público elimina metade do problema

A maioria das dores de cabeça com keepalive vem do NAT do lado do servidor - um equipamento VPN atrás de um router doméstico, duplo NAT, uma firewall do fornecedor. Põe o servidor num IPv4 público limpo e o único NAT que resta é o do cliente, onde um único PersistentKeepalive = 25 é tudo o que precisas. Um Contabo Cloud VPS 10 a 5,50 EUR/mês dá-te root completo e um verdadeiro IP público sem firewall do fornecedor para combater - exatamente as condições em que o keepalive do lado do cliente é a única coisa que tens de definir. Para perceber a mecânica de NAT que esta opção contorna, vê a explicação simples do que é o NAT.

Para ir mais longe

• Que porta o WireGuard usa e como abri-la
• O que é o NAT, explicado de forma simples
• Modelos de configuração WireGuard prontos a usar 2026
• MTU do WireGuard: corrigir o túnel travado
• O handshake do WireGuard não se completa: a lista completa de correções

Fontes e referências:

• Quickstart do WireGuard e documentação do wg-quick
• Protocolo e design do WireGuard - wireguard.com
• Arch Wiki - WireGuard (notas sobre PersistentKeepalive)

Publicado a 2026-06-29. A recomendação dos 25 segundos e o comportamento do PersistentKeepalive vêm da documentação oficial do WireGuard; os intervalos de timeout NAT variam conforme o dispositivo, por isso confirma no teu próprio router ou operador se for necessário um intervalo mais curto.

Lembrete: correr o WireGuard e auto-hospedar um VPN é legal na UE, nos EUA, no Canadá e na maioria dos países democráticos. A VPNSmith publica este conteúdo para fins educativos.