Comandi SSH per UniFi: access point, switch e console, quelli che servono davvero

Un access point che resta su “Adozione in corso” all’infinito, uno switch spostato da un cliente all’altro che non compare nel controller, un dispositivo che “va” ma di cui volete vedere i log senza aspettare l’interfaccia web. In tutti questi casi la strada più rapida è la stessa: entrare in SSH sul dispositivo UniFi.

Ubiquiti documenta pochissimo i comandi disponibili, e molti li si impara a forza di usarli. Qui raccolgo quelli che servono davvero nel lavoro di tutti i giorni, quelli che io tengo sempre a portata di mano quando metto le mani su una rete UniFi.

Attivare SSH e trovare le credenziali

Su access point e switch SSH è attivo di default. Una volta adottati, però, le credenziali non sono più quelle di fabbrica: il controller ne genera di casuali, che trovate in UniFi Network → UniFi Devices → Device Updates and Settings (in alto a destra) → Device SSH Authentication. Lì potete anche impostarne di vostre: io lo faccio sempre, con una password lunga salvata nel gestore password del cliente.

Sulle console (Cloud Key, UDM, UCG e simili) SSH invece è disattivato: si abilita da Settings → Control Plane → Console, spuntando SSH. L’utente è sempre root.

Per i dispositivi riportati alle impostazioni di fabbrica le credenziali di default sono:

• access point e switch: ui / ui (ubnt / ubnt sui firmware più vecchi);
• console e gateway: root / ui (root / ubnt sui modelli più vecchi).

Poi è il solito:

ssh [email protected]

Se SSH non vi va di toccarlo, dalle versioni recenti di UniFi Network c’è anche la Debug Console: attivate Settings → System → Advanced → Debug Tools, aprite il dispositivo, entrate nelle sue impostazioni e in fondo trovate Debug. È comoda per un’occhiata veloce, ma per lavorare su più dispositivi io resto sul terminale.

I comandi che uso di più

Un trucco prima di tutto: una volta collegati, premete due volte Tab e vedete l’elenco dei comandi disponibili su quel dispositivo. Cambia da modello a modello, quindi vale la pena guardarlo.

info
uptime
reboot

info è il primo che lancio sempre: mostra modello, versione firmware, indirizzo IP, MAC e, soprattutto, lo stato e l’URL di inform, cioè il controller a cui il dispositivo sta cercando di parlare. Nove volte su dieci, un’adozione che non parte si spiega già qui.

Adottare un dispositivo con set-inform

Quando il controller non è nella stessa rete del dispositivo (un Cloud Key in sede e un access point in filiale, oppure un controller ospitato), il rilevamento automatico non funziona e bisogna dire al dispositivo dove andare. È l’adozione “Layer 3”:

set-inform http://192.168.1.10:8080/inform

Al posto di 192.168.1.10 mettete l’indirizzo o il nome del controller. La porta TCP 8080 deve essere raggiungibile dal dispositivo verso il controller, e si usa http, non https. Dopo il comando il dispositivo compare come “pronto per l’adozione” e lo adottate dall’interfaccia. Se dopo l’adozione torna in “Disconnesso”, lanciate di nuovo lo stesso set-inform: a volte serve ripeterlo una seconda volta.

Per i dispositivi da adottare in sedi remote ho descritto anche un’alternativa grafica in UniFi Toolkit su macOS: adottare dispositivi da remoto.

Riportare un dispositivo alle impostazioni di fabbrica

È il classico caso dell’access point recuperato da un altro impianto, ancora legato al vecchio controller. Invece di cercare la graffetta per il pulsante di reset, da SSH:

set-default

Sui firmware più vecchi, dove set-default non esiste, l’equivalente è syswrapper.sh restore-default.

Attenzione: il reset cancella tutto e il dispositivo si riavvia con le credenziali di fabbrica, in DHCP. Se è un access point in mesh o uno switch che porta il collegamento ad altri apparati, rischiate di tagliarvi fuori da soli: fatelo solo se avete un modo per raggiungerlo anche dopo.

Aggiornare il firmware a mano

Se un dispositivo è troppo indietro con il firmware e il controller non riesce ad aggiornarlo (succede con apparati rimasti anni in un cassetto), potete forzare l’aggiornamento indicando il link del firmware preso dalla pagina download di Ubiquiti:

upgrade https://URL-DEL-FIRMWARE.bin

Scaricate il firmware esatto per quel modello e non spegnete il dispositivo durante l’aggiornamento. Dopo il riavvio, info vi conferma la nuova versione.

Rete e log

Sotto c’è un Linux, quindi i comandi di base funzionano come vi aspettate:

ifconfig
ip route
ping 192.168.1.1
arp -a
tail -f /var/log/messages

Con ip route controllate il gateway, con ping verso il controller capite subito se il problema è di rete, e tail -f /var/log/messages vi fa vedere in diretta cosa succede mentre provate ad adottare o riavviate qualcosa dal controller. Per uscire da tail, Ctrl+C.

Una cosa da sapere prima di cambiare configurazioni

Da SSH potete anche assegnare un IP statico, cambiare il DNS o il gateway. Lo sconsiglio, se non per sbloccare un’adozione: su un dispositivo adottato il controller riscrive la configurazione al primo provisioning, e quello che avete cambiato a mano sparisce senza preavviso. La regola che seguo è semplice: in SSH si guarda, si diagnostica e si adotta; la configurazione si fa sempre dal controller.

Avete un comando UniFi che usate spesso e che qui manca? Raccontatelo nei commenti: può essere utile ad altri.