WireGuard su macOS: le due installazioni e il nome di interfaccia che manda in errore i tutorial Linux

Installare WireGuard su un Mac sembra banale, finché il tutorial che stai seguendo non era scritto per Linux. Due cose fanno inciampare: esistono due prodotti WireGuard diversi per macOS, e il nome di interfaccia che tutti usano negli esempi, wg0, non può esistere su un Mac.

Le due installazioni, secondo la pagina ufficiale

La pagina di installazione di WireGuard le elenca entrambe, e sono software realmente distinti:

L'app del Mac App Store. Un client grafico con voce nella barra dei menu, importazione dei tunnel e attivazione su richiesta. È ciò che vuole la maggior parte delle persone.

Gli strumenti da riga di comando.

brew install wireguard-tools
# oppure, con MacPorts
port install wireguard-tools

Ottieni wg e wg-quick, gli stessi comandi che usi su un server. Sotto gira l'implementazione Go in spazio utente invece di un modulo del kernel, perché macOS non ha WireGuard nel kernel.

Non condividono l'elenco dei tunnel. Un tunnel importato nell'app non comparirà in wg show, e viceversa. Scegline uno per macchina, salvo un motivo preciso per averli entrambi.

Ciò che manda in errore i tutorial Linux: qui wg0 non esiste

È il fallimento più comune, e il messaggio di errore quasi mai lo spiega.

Su Linux crei wg0 e prosegui. Su macOS i tunnel passano dal driver utun, e la documentazione multipiattaforma di WireGuard enuncia il vincolo senza ambiguità: il driver utun non può avere nomi di interfaccia arbitrari. Bisogna usare utun seguito da un numero, per esempio utun0, oppure solo utun per lasciare scegliere al kernel.

# fallisce su macOS
sudo wg-quick up wg0

# funziona
sudo wg-quick up utun

Se hai copiato una guida che dice wg0, rinomina il file di configurazione e ogni comando che lo richiama. Chiavi, AllowedIPs, Endpoint e DNS non sono toccati: solo il nome dell'interfaccia dipende dalla piattaforma.

Sapere quale utun ti è toccato. Se lasci scegliere al kernel, ti serve un modo per conoscere il risultato. Imposta WG_TUN_NAME_FILE prima di alzare il tunnel e il nome scelto viene scritto lì:

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

Altrimenti leggi l'output di ifconfig indovinando quale utun sia il tuo: accettabile una volta, noioso in uno script.

Importare una configurazione che hai già

Se hai generato una configurazione client sul tuo server, si trasferisce così com'è. Nell'app usa l'opzione di importazione e seleziona il file .conf: il tunnel compare nell'elenco, pronto da attivare. Da riga di comando, mettilo in /opt/homebrew/etc/wireguard/utun.conf (Apple Silicon) o /usr/local/etc/wireguard/utun.conf (Intel), dando al file il nome dell'interfaccia, poi lancia wg-quick up utun.

Una configurazione generata per un telefono funziona anche su un Mac. È una definizione di peer, non un artefatto legato al dispositivo, a patto che ogni dispositivo abbia la propria coppia di chiavi e non una condivisa.

Verificare che funzioni davvero

Alza il tunnel, poi conferma due cose invece di darle per scontate.

sudo wg show

Un peer in salute mostra un latest handshake di meno di due minuti e contatori transfer diversi da zero in entrambe le direzioni. Inviato ma nulla ricevuto è la firma di un percorso di ritorno bloccato. Se l'handshake non si completa mai, la nostra guida alla risoluzione dei problemi di handshake percorre le cause in ordine di probabilità.

Poi conferma che il traffico passi davvero dal tunnel, e non solo che l'interfaccia esista: controlla il tuo IP pubblico dal browser e, se instradi il DNS nel tunnel, verifica che non ci siano fughe. La nostra nota sulle fughe DNS in WireGuard copre le impostazioni che contano.

In breve

Due prodotti: l'app dell'App Store per un client grafico, wireguard-tools via Homebrew o MacPorts per la stessa riga di comando del tuo server. Non condividono i tunnel. E su macOS l'interfaccia deve chiamarsi utun o utunN, mai wg0, perché il driver utun non accetta nomi arbitrari. Quella sola riga spiega la maggior parte delle installazioni Mac fallite copiando guide Linux.