Unifi Controller – Adoption failed troubleshooting

Diagnosi dei dispositivi UniFi che non vengono adottati o non compaiono in alcun sito, con i comandi SSH del dispositivo e le query sul database MongoDB del controller

Questa guida aiuta a risolvere i casi in cui un dispositivo UniFi (access point, switch, gateway) non riesce a essere adottato dal controller UniFi (oggi UniFi Network Application) oppure risulta adottato ma non compare in nessun sito. Si parte dalle verifiche sul dispositivo e sulla rete e, quando non bastano, si interviene direttamente sul database MongoDB del controller.

Indice

• 1. Sintomi
  • 1.1 Il processo di adozione
• 2. Prerequisiti
  • 2.1 Requisiti di rete
• 3. Verifiche sul dispositivo
  • 3.1 Accesso SSH al dispositivo
  • 3.2 Stato del dispositivo con info
  • 3.3 Indicare il controller con set-inform
  • 3.4 Reset di fabbrica
• 4. Log del controller
• 5. Intervento sul database MongoDB del controller
  • 5.1 Connessione al database
  • 5.2 Trovare il dispositivo per indirizzo MAC
  • 5.3 Trovare il dispositivo per indirizzo IP
  • 5.4 Risalire al sito dall'identificativo
  • 5.5 Rimuovere il record del dispositivo
• 6. Procedura consigliata
• 7. Riepilogo dei comandi
  • 7.1 Risoluzione dei problemi

1. Sintomi

• Il comando info eseguito sul dispositivo riporta lo stato Adoption failed (vedi sezione 3.2).
• I dispositivi UniFi non compaiono nell'elenco del controller, nemmeno come in attesa di adozione.
• Il dispositivo risulta adottato (LED blu fisso) ma non compare in alcun sito del controller: tipicamente è legato a un sito eliminato o a un altro controller (vedi sezione 5).

1.1 Il processo di adozione

Un dispositivo nuovo o ripristinato ai valori di fabbrica cerca un controller sulla rete e si presenta inviando periodicamente un messaggio inform all'indirizzo http://:8080/inform. Quando l'amministratore lo adotta, il controller gli invia la configurazione e le credenziali SSH del sito; da quel momento il dispositivo continua a contattare lo stesso controller. Gli stati che puoi vedere nel controller:

2. Prerequisiti

• Accesso SSH al controller UniFi (installazione su Linux) con un utente che possa usare sudo, necessario per le query sul database.
• Accesso SSH al dispositivo UniFi (vedi sezione 3.1).
• Un backup recente del controller, scaricato dalla sezione Backup delle impostazioni, prima di qualunque modifica al database.

2.1 Requisiti di rete

Molti problemi di adozione dipendono dalla rete tra dispositivo e controller. Verifica che siano raggiungibili dal dispositivo verso il controller:

Se dispositivo e controller sono su reti diverse (adozione Layer 3) il dispositivo non può trovare il controller da solo: occorre indicarglielo con l'opzione 43 del DHCP, con un record DNS unifi che punti al controller oppure manualmente con set-inform.

3. Verifiche sul dispositivo

3.1 Accesso SSH al dispositivo

ssh @

• Un dispositivo mai adottato o ripristinato accetta le credenziali predefinite ubnt / ubnt.
• Un dispositivo già adottato usa invece le credenziali SSH dei dispositivi impostate nel controller del sito che lo ha adottato. Se il sito o il controller non esistono più e le credenziali non sono note, l'unica strada è il reset di fabbrica.

3.2 Stato del dispositivo con info

info

Mostra modello, versione firmware, indirizzo MAC, indirizzo IP, nome host e la riga Status, che indica lo stato della comunicazione con il controller:

• Connected seguito dall'indirizzo inform: il dispositivo è collegato al controller indicato. Se il controller è quello sbagliato, correggi con set-inform o rimuovi l'associazione dal database.
• Not Adopted: il dispositivo è pronto per essere adottato; se non compare nel controller verifica i requisiti di rete.
• Adoption failed: l'adozione non è andata a buon fine; ripeti set-inform e, se non basta, esegui il reset.
• Uno stato Unknown o Timeout indica che il dispositivo non riceve risposta dall'indirizzo inform configurato: verifica la porta 8080/TCP e l'indirizzo.

3.3 Indicare il controller con set-inform

set-inform http://:8080/inform

Imposta l'indirizzo a cui il dispositivo invia i messaggi inform. Dopo il comando il dispositivo compare nel controller in attesa di adozione: avvia l'adozione dal controller e, se richiesto, ripeti il comando una seconda volta finché lo stato non diventa Connected. Puoi usare anche un nome DNS al posto dell'IP del controller.

3.4 Reset di fabbrica

syswrapper.sh restore-default

Riporta il dispositivo alle impostazioni di fabbrica e lo riavvia, cancellando configurazione e associazione al controller. In alternativa tieni premuto il pulsante di reset fisico per circa 10 secondi finché i LED non cambiano. Dopo il riavvio il dispositivo accetta di nuovo le credenziali ubnt / ubnt e può essere adottato con set-inform.

4. Log del controller

tail -f /var/log/unifi/server.log

Mostra in tempo reale il log del controller (nelle installazioni su Debian/Ubuntu). Lancialo prima di ripetere set-inform o l'adozione: vedrai i messaggi inform in arrivo dal MAC del dispositivo, gli eventuali errori di adozione e a quale sito il controller associa il dispositivo. Interrompi con Ctrl+C.

5. Intervento sul database MongoDB del controller

Se il dispositivo risulta adottato ma non compare in nessun sito, o il controller rifiuta di riadottarlo, il problema è nel record del dispositivo salvato nel database. Il controller usa un'istanza MongoDB interna in ascolto sulla porta 27117, con il database ace.

5.1 Connessione al database

mongo --port 27117
use ace

Il primo comando, eseguito via SSH sul controller, apre la shell MongoDB; il secondo seleziona il database del controller. Nelle installazioni più recenti la vecchia shell mongo potrebbe non essere presente: in quel caso usa mongosh --port 27117, con gli stessi comandi.

5.2 Trovare il dispositivo per indirizzo MAC

db.device.find({ "mac" : "" })

Restituisce il record del dispositivo. Il MAC va scritto in minuscolo e con i due punti, come lo mostra il comando info. Nell'output sono utili soprattutto i campi _id (identificativo del record), ip, model, name, adopted e site_id, che indica il sito a cui il controller associa il dispositivo. Aggiungi .pretty() alla fine del comando per un output più leggibile.

5.3 Trovare il dispositivo per indirizzo IP

db.device.find({ "ip" : "" })

Utile quando conosci solo l'indirizzo IP del dispositivo. Restituisce lo stesso record descritto in sezione 5.2.

5.4 Risalire al sito dall'identificativo

db.site.find({ "_id" : ObjectId("") })

Sostituisci con il valore del campo site_id letto nel record del dispositivo. Il risultato riporta il nome interno del sito (name) e quello visualizzato nel controller (desc). Se la query non restituisce nulla, il dispositivo è associato a un sito che non esiste più: è il motivo per cui non compare da nessuna parte.

5.5 Rimuovere il record del dispositivo

db.device.remove({ "mac" : "" })

Elimina dal database il record del dispositivo con il MAC indicato, così il controller lo tratterà come un dispositivo nuovo. Controlla con attenzione il MAC: con un filtro vuoto o errato il comando rimuoverebbe altri record. Nelle shell più recenti remove è sostituito da deleteOne, con lo stesso filtro:

db.device.deleteOne({ "mac" : "" })

Esci dalla shell con exit, poi esegui il reset di fabbrica del dispositivo (o almeno set-inform) e adottalo di nuovo nel sito corretto, seguendo il log del controller.

6. Procedura consigliata

1. Collegati al dispositivo in SSH e verifica lo stato con info.
2. Controlla porte e raggiungibilità del controller (sezione 2.1).
3. Avvia il log del controller e ripeti set-inform.
4. Se il dispositivo risulta adottato ma non compare: trova il record per MAC o IP e verifica il sito associato.
5. Se il sito non esiste o è sbagliato: rimuovi il record, esegui il reset e riadotta il dispositivo.
6. Verifica che il dispositivo compaia nel sito corretto con stato Connected e che info riporti l'indirizzo inform giusto.

7. Riepilogo dei comandi

7.1 Risoluzione dei problemi