UniFi Toolkit su macOS: trovare e adottare dispositivi UniFi in un controller remoto

Chi gestisce reti UniFi con un controller remoto conosce bene questa scena: montate un access point o uno switch nuovo, lo accendete e nel controller non compare niente. L’adozione automatica funziona quando dispositivo e controller sono sulla stessa rete; se il controller è in hosting o in un’altra sede, al dispositivo bisogna dire dove andare a “bussare”.

I metodi ufficiali sono tre: l’opzione DHCP 43, un record DNS unifi che punta al controller, oppure collegarsi in SSH a ogni dispositivo e lanciare set-inform. Con un apparato si fa in due minuti; con dieci diventa un lavoro noioso e facile da sbagliare.

Da qualche tempo, per adottare i dispositivi nuovi, uso UniFi Toolkit dal Mac. È uno strumento gratuito pubblicato su GitHub da Cloud UniFi, un fornitore di controller UniFi in hosting, e fa esattamente questo: trova i dispositivi in rete e imposta l’inform URL al posto vostro.

Cos’è UniFi Toolkit

Il funzionamento è semplice: trova i dispositivi in rete con una scansione UDP, poi si collega a ciascuno in SSH. Le funzioni sono due:

Discover & Adopt: scansiona la sottorete e fa puntare i dispositivi al vostro controller;
Troubleshoot: mostra informazioni e log del dispositivo, fa il reset di fabbrica e aggiorna il firmware.

C’è un’app desktop per macOS, solo per Apple Silicon, distribuita come DMG firmato e notarizzato, e una versione a riga di comando per macOS, Linux e Windows; dalla v1.1.4 anche l’eseguibile per Windows è firmato. Io uso l’app: per l’adozione è il modo più comodo.

Il progetto è giovane e ha ancora poche stelle su GitHub. Lo uso volentieri perché fa una cosa sola, la fa bene, e non tocca il controller: si limita a dire ai dispositivi dove trovarlo.

Prima di iniziare

Il Mac deve stare nello stesso segmento Layer 2 dei dispositivi, cioè la stessa VLAN: se gli AP sono su una VLAN di gestione, collegatevi lì;
i dispositivi devono essere in configurazione di fabbrica, quando accettano le credenziali SSH predefinite ubnt/ubnt; un dispositivo già adottato altrove ha credenziali diverse;
il controller deve essere raggiungibile dai dispositivi sulla porta TCP 8080: l’inform URL ha il formato http://unifi.example.com:8080/inform, e se il controller è dietro NAT serve il port forwarding della 8080;
tenete a portata di mano il nome host del controller, per esempio unifi.example.com: non serve l’URL completo.

Installazione su macOS

Scaricate dalla pagina Releases del progetto il file UniFi-Toolkit-…-mac-arm64.dmg e trascinate l’app in Applicazioni.
Al primo avvio macOS chiede l’accesso alla rete locale: concedetelo, altrimenti la scansione non trova nulla. Se l’avete negato per sbaglio, lo riattivate da Impostazioni di Sistema → Privacy e sicurezza → Rete locale.

Su un Mac Intel non c’è l’app, ma c’è la versione a riga di comando. Il README propone l’installazione con curl … | sh; io preferisco scaricare lo script e leggerlo prima di lanciarlo:

curl -fsSL -o install.sh https://raw.githubusercontent.com/cloudunifi/unifi-toolkit/main/install.sh
less install.sh
sh install.sh

Adottare i dispositivi

Aprite l’app e scegliete Discover Devices: lo strumento rileva la sottorete e cerca i dispositivi UniFi.
Inserite il nome host del controller; la porta resta quella predefinita, 8080.
Selezionate i dispositivi da adottare: il toolkit si collega a ciascuno in SSH e imposta l’inform URL.
Nel controller i dispositivi compaiono in attesa di adozione: cliccate Adopt su ciascuno e lo stato passa da Pending ad Adopting, poi a Provisioning e infine a Connected.

Lo stesso lavoro si fa dal terminale, anche dentro uno script:

unifi-toolkit --run -c unifi.example.com -s 192.168.1.0/24
unifi-toolkit --run -A set-inform -c unifi.example.com -t 192.168.1.20

Quando qualcosa non va

La scansione non trova nulla: controllate il permesso Rete locale e la VLAN a cui è collegato il Mac. Su Linux interfacce Docker o VPN possono confondere la scansione: indicate la sottorete con --subnet;
il dispositivo viene trovato ma non è accessibile: quasi sempre ha credenziali SSH diverse da quelle di fabbrica, e le ultime versioni lo mostrano in una sezione separata. Da riga di comando potete passare utente e password con -u e -p, altrimenti fate un reset di fabbrica;
il dispositivo resta in adozione all’infinito: di solito non raggiunge il controller sulla 8080. Verificate firewall e port forwarding.

Attenzione: il reset e l’aggiornamento firmware da riga di comando accettano --yes, che salta la conferma. Il reset è irreversibile, quindi controllate due volte l’IP di destinazione.

Toolkit, DHCP 43 o DNS?

Per una sede stabile, dove arriveranno altri apparati nel tempo, configuro comunque l’opzione 43 o il record DNS: si fa una volta e vale per sempre. Per una nuova installazione, una sostituzione o una migrazione, il toolkit è il metodo più rapido che ho trovato.

Usate anche voi UniFi con un controller remoto? Raccontate nei commenti come gestite l’adozione: le vostre soluzioni possono essere utili ad altri.