Como usar um ficheiro de configuração WireGuard

O que há dentro de um ficheiro .conf, linha a linha

Todas as configurações WireGuard têm a mesma estrutura em duas partes. [Interface] descreve o seu lado do túnel; [Peer] descreve a máquina a que se está a ligar. Eis uma configuração de cliente completa, com os segredos substituídos por marcadores:

[Interface]
PrivateKey = YOUR_PRIVATE_KEY_KEEP_THIS_SECRET
Address    = 10.7.0.4/32
DNS        = 10.7.0.1

[Peer]
PublicKey           = THE_SERVER_PUBLIC_KEY_FROM_YOUR_PROVIDER
Endpoint            = 198.51.100.10:51820
AllowedIPs          = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

O bloco [Interface]: o seu lado

• PrivateKey: esta é a sua identidade na VPN. Quem a tiver pode fazer-se passar por si. São 44 caracteres base64 terminados em =; se a sua tiver outro comprimento, o ficheiro ficou truncado algures ao ser copiado.
• Address: o IP que o seu dispositivo tem dentro do túnel, não o seu IP público. O /32 significa "apenas este endereço", o que é normal num cliente.
• DNS: o resolvedor usado enquanto o túnel está ativo. Sem ele, o dispositivo continua a perguntar ao resolvedor antigo, o que revela o que está a pesquisar e muitas vezes impede a resolução de qualquer nome do outro lado.
• MTU: opcional, e a linha mais útil de conhecer. Falta na maioria dos ficheiros porque o valor predefinido é o correto; consulte a secção de resolução de problemas para o caso em que não é.

O bloco [Peer]: o lado do servidor

• PublicKey: a chave pública do servidor. A sua nunca aparece no seu próprio ficheiro; quem a guarda é o servidor.
• Endpoint: para onde enviar os pacotes, no formato host:port. O WireGuard funciona apenas por UDP, e 51820 é a porta habitual, não uma porta obrigatória.
• AllowedIPs: que destinos passam pelo túnel. 0.0.0.0/0, ::/0 significa tudo, que é precisamente para o que serve uma VPN de privacidade. Uma lista mais restrita (por exemplo, só a rede interna da sua empresa) envia apenas isso pelo túnel e deixa o resto na ligação normal. Chama-se a isto split tunnel (túnel dividido), e é uma escolha deliberada, não um túnel completo avariado.
• PersistentKeepalive: envia um pequeno pacote a cada 25 segundos para que o dispositivo NAT entre si e o servidor mantenha aberto o caminho de regresso. É necessário sempre que estiver atrás de NAT, e num telemóvel ou numa ligação doméstica está sempre.

Windows: importar o túnel

O Windows tem uma app WireGuard oficial, e importar um ficheiro para ela é todo o trabalho.

1. Instale o WireGuard a partir de wireguard.com/install.
2. Clique em Adicionar túnel no canto inferior esquerdo, o que abre um seletor de ficheiros filtrado por Ficheiros de configuração (*.zip, *.conf). Escolha o seu .conf e ele aparece na lista de túneis, com o nome do ficheiro.
3. Ou cole-o. A seta ao lado de Adicionar túnel oferece Adicionar túnel vazio…, que lhe dá uma caixa de texto: útil quando a configuração chegou numa mensagem e não como ficheiro. Vem preenchida com uma chave privada nova, por isso apague essa linha e cole a sua configuração por cima.
4. Clique em Activar. O estado passa a Activo e o painel começa a contar os bytes transferidos. Esse contador é a verificação mais rápida que tem: se mostrar dados a sair e nada a voltar, o seu handshake não se está a completar.

Android e iPhone: ler o código QR ou importar o ficheiro

Num telemóvel há duas formas de o fazer, e o código QR existe precisamente porque escrever uma chave de 44 caracteres num ecrã tátil é um martírio.

Android

1. Instale o WireGuard a partir da Play Store e toque no botão +.
2. O ecrã Criar túnel WireGuard oferece Digitalizar a partir de código QR, Importar de ficheiro ou arquivo e a criação de um túnel de raiz. Escolha a opção que corresponde ao que recebeu.
3. Dê um nome ao túnel, se lhe for pedido, e ative o respetivo interruptor. O Android pede uma vez autorização para adicionar uma configuração VPN: esse aviso é do sistema operativo, não da app.

iPhone e iPad

1. Instale o WireGuard a partir da App Store e toque em Add a tunnel.
2. Em Add a new WireGuard tunnel, escolha Create from QR code ou Create from file or archive. O ecrã do leitor chama-se Scan QR code; depois de uma leitura bem-sucedida, pede-lhe que dê um nome ao túnel.
3. Ative-o e autorize a configuração VPN quando o iOS pedir.

Criar um código QR a partir de um ficheiro de configuração que já tem

O código QR não é algo que o fornecedor tenha obrigatoriamente de lhe dar: é apenas o seu ficheiro de configuração desenhado como imagem, e pode gerá-lo com um único comando. A própria app WireGuard sugere isto:

# prints the code straight into the terminal, ready to scan off the screen
qrencode -t ansiutf8 < wg0.conf

# or write it to an image file
qrencode -o wg0.png < wg0.conf

No Debian ou Ubuntu, o qrencode instala-se com apt install qrencode; no macOS, com brew install qrencode.

macOS e Linux

macOS

Instale o WireGuard a partir da Mac App Store. A app para Mac não é a app do iPhone num ecrã maior: fica na barra de menus, e a sua janela abre-se a partir de Manage Tunnels. Clique em Import tunnel(s) from file (a barra de menus tem a mesma opção como Import Tunnel(s) from File…), escolha o seu .conf, selecione o túnel e clique em Activate. O Mac não tem leitor de QR (os códigos QR são para telemóveis), por isso use o próprio ficheiro, ou escolha Add Empty Tunnel… e cole a configuração.

Se preferir trabalhar num terminal, brew install wireguard-tools dá-lhe os mesmos comandos wg-quick do Linux, descritos a seguir.

Linux

1. Instale as ferramentas. No Debian ou Ubuntu: sudo apt install wireguard. A maioria das distribuições tem um pacote com o mesmo nome.
2. Coloque o ficheiro onde o wg-quick o procura. É o passo em que as pessoas se enganam, porque o nome do ficheiro passa a ser o nome da interface:

   sudo install -m 600 -o root -g root wg0.conf /etc/wireguard/wg0.conf

   O 600 é importante: o ficheiro contém a sua chave privada e não deve poder ser lido por outros utilizadores da máquina. Use um nome curto e simples; tem de ser um nome de interface de rede válido.
3. Ative-o:

   sudo wg-quick up wg0
   sudo wg show

   wg show é o comando que vale a pena decorar. Mostra o peer, o endpoint, uma linha latest handshake e os contadores de transferência. Uma hora de handshake que nunca aparece é a assinatura do problema descrito na secção seguinte.
4. Arranque automático: sudo systemctl enable --now wg-quick@wg0. Para parar o túnel manualmente, sudo wg-quick down wg0.

No router, para cobrir a casa toda

Pôr o túnel no router cobre todos os dispositivos que estão atrás dele, incluindo os que não conseguem de todo correr uma app de VPN: uma consola de jogos, uma televisão, uma coluna inteligente. Poder fazê-lo ou não depende inteiramente do firmware.

Se o seu router é a caixa que o operador de internet lhe entregou, as opções realistas são colocar atrás dele um router que controle, ou continuar a usar configurações por dispositivo. Nenhuma das duas é um fracasso; a configuração por dispositivo é muitas vezes até melhor, porque pode deixar o túnel desligado nos dispositivos que não precisam dele.

Uma coisa a decidir antes de encaminhar a casa toda por um túnel: a partir daí passa tudo por ele. Sites de bancos que desconfiam de endereços estrangeiros, serviços de streaming que verificam a sua região e tudo o que comunique com dispositivos da sua própria rede podem comportar-se de forma diferente. É aqui que um AllowedIPs mais restrito mostra o seu valor: envie apenas o que precisa de ir e deixe o resto como está.

Liga mas não carrega nada, e outros problemas reais

O WireGuard é invulgarmente silencioso quando falha, e isso é uma opção de design deliberada: um pacote não autenticado não recebe qualquer resposta, pelo que um scanner não consegue perceber se há algo à escuta. O efeito secundário é que uma chave errada, uma porta errada e uma rede bloqueada parecem idênticas do seu lado: silêncio. Parta do sintoma.

"Handshake did not complete"

O seu dispositivo enviou um pacote de iniciação e não recebeu nada de volta. Verifique, por esta ordem:

• O endpoint. Host certo, porta certa, e a porta tem de ser UDP. Um erro de escrita aqui produz exatamente este sintoma e mais nenhum.
• Se o UDP chega de todo ao exterior. Redes wi-fi de convidados, redes de hotéis, algumas redes empresariais e alguns operadores móveis só permitem TCP nas portas comuns. Se a mesma configuração funciona na sua ligação de casa e falha numa rede específica, a configuração está boa e o problema é a rede.
• Se as chaves estão no sítio certo. A PublicKey em [Peer] é a chave pública do servidor, e o servidor tem de ter, por seu lado, a chave pública que corresponde à sua PrivateKey. Uma configuração copiada de outro dispositivo falha aqui.
• O seu relógio. O handshake do WireGuard inclui uma marca temporal e rejeita as que estejam muito desfasadas. É raro, mas acontece em dispositivos que perderam a hora.

Se o túnel funciona em casa mas nunca a partir de dados móveis, a causa pode estar do lado do seu operador e não do seu: o CGNAT e soluções semelhantes alteram o que consegue chegar até si. O guia de reencaminhamento de portas explica como identificar isso a partir do seu próprio router em poucos minutos.

O problema do MTU, que vale a pena perceber de uma vez

Este é o caso clássico de "ligado, mas a internet não funciona", e o padrão é inconfundível: o ping funciona, o DNS funciona, as páginas pequenas carregam e tudo o que seja mais pesado fica pendurado para sempre.

A causa é o tamanho. Encapsular o tráfego para o túnel acrescenta cabeçalhos, pelo que um pacote que cabia à justa na ligação normal deixa de caber quando está dentro do WireGuard. Os pacotes pequenos passam sem problemas; os grandes são descartados. Normalmente a rede avisa o emissor para usar pacotes mais pequenos, mas a mensagem que o faz é muitas vezes filtrada, por isso, em vez de um erro, fica simplesmente à espera.

A solução é dizer ao WireGuard para usar pacotes mais pequenos logo de início. O wg-quick já tenta: pega no MTU da sua rota normal e subtrai 80 bytes para a sobrecarga do túnel, pelo que numa ligação comum de 1500 bytes obtém 1420. Quando isso ainda é demasiado (algumas redes móveis, a maioria das ligações que já correm dentro de outro túnel), defina-o explicitamente e vá descendo:

[Interface]
MTU = 1420      # what wg-quick would have picked
# still stalling? try 1380, then 1280

1280 é o mínimo que vale a pena experimentar, porque é o tamanho de pacote mais pequeno que o IPv6 exige que tudo transporte, pelo que sobrevive praticamente a qualquer caminho. Custa um pouco de eficiência e é muito melhor do que um túnel que bloqueia.

O túnel está ativo mas nada passa por ele

Verifique primeiro o AllowedIPs. Não é uma firewall nem uma lista de permissões: decide que destinos são encaminhados para o túnel. Se não incluir 0.0.0.0/0, o tráfego para o resto da internet nunca foi feito para passar por lá, e a sua ligação está a comportar-se exatamente como foi configurada. No Linux, ip route show table all | grep wg0 mostra o que foi realmente encaminhado.

Se o encaminhamento está correto e os nomes simplesmente não são resolvidos, é a linha DNS: ou falta, ou existe mas não é aplicada porque o resolvconf não está instalado.

De onde vem o ficheiro de configuração

Tudo o que está acima pressupõe que tem um ficheiro. Há exatamente duas formas de o obter.

Gerir o servidor por conta própria

Gera um par de chaves, instala o WireGuard numa máquina com endereço público, adiciona o seu dispositivo como peer e escreve à mão a configuração do cliente. Não é difícil e é mesmo algo que vale a pena aprender. O custo é contínuo: um servidor para pagar e manter atualizado, e uma edição manual nos dois lados sempre que adiciona um dispositivo, porque, lembre-se, um peer é um dispositivo.

Obtê-lo de um fornecedor

A alternativa é o ficheiro ser gerado por si e só ter de o transferir. Com a HytHost VPN, desde €0.99/mês, está aqui:

1. Encomende o serviço e inicie sessão na área de cliente, depois abra o seu serviço VPN na lista.
2. Procure a secção WireGuard Configuration. Tem dois botões: Copy to Clipboard, que copia o texto da configuração para a área de transferência, e Download Configuration, que lhe entrega o ficheiro já pronto.
3. Se o copiou, cole-o num editor de texto simples e guarde-o com a extensão .conf; wg0.conf é um bom nome. Confirme que o editor não acrescentou .txt no fim.
4. Importe-o seguindo a secção acima correspondente ao seu dispositivo. Num telemóvel, transforme-o primeiro num código QR com o qrencode.

A mesma página mostra se o túnel está neste momento ligado ao servidor, o que responde à pergunta "o problema é meu ou deles?" antes de começar a mexer em definições. Não há botão de código QR: gere-o a partir do ficheiro, o que também significa que o código nunca viaja para onde não precisava de ir.