WireGuard no macOS: as duas instalações e o nome de interface que quebra os tutoriais de Linux

Instalar o WireGuard num Mac parece trivial, até que o tutorial que está a seguir tenha sido escrito para Linux. Duas coisas fazem tropeçar: existem dois produtos WireGuard diferentes para macOS, e o nome de interface que toda a gente usa nos exemplos, wg0, não pode existir num Mac.

As duas instalações, segundo a página oficial

A página de instalação do WireGuard lista ambas, e são software realmente distinto:

A app da Mac App Store. Um cliente gráfico com item na barra de menus, importação de túneis e ativação a pedido. É o que a maioria quer.

As ferramentas de linha de comandos.

brew install wireguard-tools
# ou, com MacPorts
port install wireguard-tools

Obtém wg e wg-quick, os mesmos comandos que usa num servidor. Por baixo corre a implementação Go em espaço de utilizador em vez de um módulo do kernel, porque o macOS não traz WireGuard no kernel.

Não partilham a lista de túneis. Um túnel importado na app não aparecerá em wg show, e vice-versa. Escolha um por máquina, salvo motivo concreto para ter os dois.

O que quebra os tutoriais de Linux: aqui wg0 não existe

É a falha mais comum, e a mensagem de erro quase nunca a explica.

No Linux cria wg0 e segue em frente. No macOS os túneis passam pelo controlador utun, e a documentação multiplataforma do WireGuard enuncia a restrição sem ambiguidade: o controlador utun não pode ter nomes de interface arbitrários. É preciso usar utun seguido de um número, por exemplo utun0, ou apenas utun para deixar o kernel escolher.

# falha no macOS
sudo wg-quick up wg0

# funciona
sudo wg-quick up utun

Se copiou um guia que diz wg0, mude o nome do ficheiro de configuração e de qualquer comando que o refira. As chaves, AllowedIPs, Endpoint e DNS não são afetados: só o nome da interface depende da plataforma.

Saber que utun lhe calhou. Se deixar o kernel escolher, precisa de uma forma de saber o resultado. Defina WG_TUN_NAME_FILE antes de levantar o túnel e o nome escolhido é escrito aí:

export WG_TUN_NAME_FILE=/tmp/wg-name
sudo -E wg-quick up utun
cat /tmp/wg-name    # por exemplo utun4

Sem isso, lê a saída do ifconfig a adivinhar qual utun é o seu: aceitável uma vez, maçador num script.

Importar uma configuração que já tem

Se gerou uma configuração de cliente no seu servidor, ela transfere-se tal como está. Na app, use a opção de importar e selecione o ficheiro .conf: o túnel aparece na lista, pronto a ativar. Na linha de comandos, coloque-o em /opt/homebrew/etc/wireguard/utun.conf (Apple Silicon) ou /usr/local/etc/wireguard/utun.conf (Intel), dando ao ficheiro o nome da interface, e execute wg-quick up utun.

Uma configuração gerada para um telemóvel também serve num Mac. É uma definição de par, não um artefacto específico do dispositivo, desde que cada equipamento tenha o seu próprio par de chaves e não um partilhado.

Confirmar que funciona mesmo

Levante o túnel e confirme duas coisas em vez de as presumir.

sudo wg show

Um par saudável mostra um latest handshake com menos de dois minutos e contadores transfer diferentes de zero nos dois sentidos. Enviado mas nada recebido é a assinatura de um caminho de regresso bloqueado. Se o handshake nunca se completa, o nosso guia de resolução de problemas do handshake percorre as causas por ordem de probabilidade.

Depois confirme que o tráfego passa mesmo pelo túnel, e não apenas que a interface existe: verifique o seu IP público no navegador e, se encaminhar o DNS pelo túnel, confirme que não há fuga. A nossa nota sobre fugas de DNS no WireGuard cobre as definições que importam.

Em resumo

Dois produtos: a app da App Store para um cliente gráfico, wireguard-tools via Homebrew ou MacPorts para a mesma linha de comandos do seu servidor. Não partilham túneis. E no macOS a interface tem de se chamar utun ou utunN, nunca wg0, porque o controlador utun não aceita nomes arbitrários. Essa única linha explica a maioria das instalações falhadas em Mac copiadas de guias de Linux.