Nebula static_host_map: l’indirizzo che un faro non può dare

Ogni faro può dire a un host di ogni altro peer tranne dove vive il faro stesso. Qualcosa deve essere noto prima che l’overlay esista, e Nebula mette quel qualcosa in una piccola mappa. La mappa abbina un’identità overlay a un indirizzo che funziona sulla rete ordinaria. Tutto ciò che si impara dopo dipende dal fatto che quell’abbinamento sia corretto.

Due indirizzi con due compiti

Ogni host Nebula possiede un indirizzo overlay che resta fisso mentre il dispositivo si sposta tra reti. Quell’indirizzo è l’identità usata da certificati, regole del firewall e relazioni tra peer, e da solo non instrada da nessuna parte. L’endpoint raggiungibile è un’altra cosa: un nome host o un indirizzo sulla rete sottostante più una porta UDP, e cambia ogni volta che la macchina cambia posizione. La mappa statica è la giunzione tra i due.

Nella mappa entrano solo gli host che vanno chiamati a freddo, il che di solito significa i fari e forse un relay. Tenere quella lista corta è un obiettivo di progettazione, perché ogni voce manuale diventa un fatto che qualcuno deve mantenere. Confondere i due tipi di indirizzo è l’errore di configurazione abituale: un indirizzo pubblico messo nella lista dei fari non fa partire la scoperta.

L’identità va dove ci si aspetta l’identità. La raggiungibilità va nella mappa.

static_host_map:
  "10.42.0.1": ["lighthouse-01.example.net:4242"]

lighthouse:
  am_lighthouse: false
  hosts:
    - "10.42.0.1"

Anatomia di una voce della mappa

La chiave è l’indirizzo overlay scritto come stringa tra virgolette, e il valore è una lista di endpoint, così un’identità può avere diversi punti d’ingresso. Ogni endpoint porta un host e una porta, e la porta deve corrispondere a ciò che l’altro lato ascolta davvero. Il valore predefinito di Nebula è UDP 4242, che è un punto di partenza e non una promessa sul tuo impiego.

Più endpoint sono utili quando un faro ha più di un percorso in ingresso, come un indirizzo pubblico e un indirizzo privato per gli host sullo stesso segmento. Il client li prova in ordine, quindi metti il più affidabile per primo. Per IPv6, metti l’indirizzo tra parentesi quadre prima di aggiungere la porta; sbagliarlo produce un errore di analisi che punta alla riga sbagliata.

Una porta sbagliata produce silenzio invece di un errore, perché UDP non ha handshake con cui rifiutare. Per questo vale la pena controllare il formato della voce contro la referenza static_host_map di Nebula e non contro la memoria. La referenza copre anche gli elenchi di endpoint e il comportamento di aggiornamento DNS.

Il bootstrap deve funzionare prima dell’overlay

Un nome DNS nella mappa deve risolversi tramite il resolver che l’host ha prima di qualsiasi tunnel, cioè il resolver di sistema ordinario. Provalo dalla stessa macchina, all’avvio, con l’overlay fermo. Un nome che si risolve solo tramite il DNS proprio dell’overlay non può avviare l’overlay. Lo stesso test vale per la rotta: una regola del firewall che consente l’overlay ma non il primo scambio UDP blocca il pacchetto iniziale.

Sonda la porta con uno strumento UDP invece di supporre che sia aperta. Conferma che ogni inoltro di porta sul percorso punti all’host interno corretto e che esista un percorso di ritorno. Se il nome host si risolve in più indirizzi, prova ciascuno, perché il client può scegliere un indirizzo che non hai mai controllato.

Le voci statiche vengono chiamate direttamente e non consultano mai un faro. Per questo un guasto qui sembra un normale timeout senza alcun peer coinvolto.

Cosa succede dopo il primo handshake

Quando un host raggiunge un faro, apprende i peer e i loro indirizzi raggiungibili senza altre voci manuali. Gli host che si sono spostati dall’ultima connessione diventano individuabili attraverso quel canale. È il guadagno di tenere piccola la mappa manuale.

Gli host possono anche annunciare propri indirizzi raggiungibili aggiuntivi, ed è così che un peer dietro un indirizzo pubblico noto aiuta gli altri a trovarlo. Quegli annunci si imparano, non si digitano nella mappa statica.

Il comportamento di aggiornamento conta per gli endpoint scritti come nomi DNS, perché un indirizzo risolto può cambiare mentre il processo continua a girare. Le impostazioni di Nebula controllano come avvengono quelle ricerche, incluso quale resolver viene usato, quindi leggile invece di supporre il valore predefinito del sistema. Su un host il cui resolver cambia quando sale un tunnel, l’impostazione sbagliata può trasformare un bootstrap funzionante in un nome che smette di risolversi a metà sessione. Fissare la ricerca a un resolver stabile è spesso la differenza tra un overlay affidabile e uno intermittente.

Quando la scoperta funziona e un peer no

Se i fari sono raggiungibili e la maggior parte dei peer si connette, il bootstrap non è il problema. La coppia rimanente o non trova un percorso utilizzabile tra loro o fallisce sopra la raggiungibilità. Aggiungere un’altra grafia dell’indirizzo del faro non ripara nessuno dei due casi.

Controlla la coppia prima di modificare la mappa su cui già si appoggia tutto il resto. Un cambio di mappa disturba ogni host, quindi è l’ultima cosa da toccare, non la prima.

Inizia con certificati della stessa autorità, perché un handshake rifiutato può sembrare da lontano un peer irraggiungibile. Poi controlla se la coppia può stabilire un percorso diretto e se un relay è configurato per le reti che rifiutano il traffico diretto. Un relay aggiunge un salto e una dipendenza, ma è una risposta supportata, e riparare il percorso della coppia è un compito diverso dal riparare la scoperta.