Moduli nativi (per sviluppatori)

I moduli non sono necessari per l’utilizzo normale. Questa guida è rivolta a sviluppatori e amministratori che vogliono estendere il servizio Windows o Linux mediante librerie native. I moduli vengono eseguiti all’interno del servizio, con i suoi privilegi. Installa soltanto codice affidabile e mantieni i file dei moduli, le dipendenze e le configurazioni di proprietà dell’amministratore.

Caricare un modulo

Il servizio legge i file *.conf nella directory modules.d accanto al file di configurazione. I percorsi predefiniti sono:

Sistema operativo	Directory delle configurazioni	Formato della libreria
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Inserisci in ciascun file un percorso assoluto di libreria per riga. Ad esempio, /etc/mudfish-dns/modules.d/10-policy.conf può contenere:

/usr/lib/mudfish-dns/modules/policy.so

I file vengono letti in ordine di nome e le righe nell’ordine in cui compaiono. Le righe vuote e quelle che iniziano con # vengono ignorate. Non racchiudere i percorsi tra virgolette e non usare variabili d’ambiente o commenti a fine riga: queste espressioni non vengono interpretate. Anche su Windows scrivi il percorso assoluto completo nel file, compresi eventuali spazi.

Dopo aver aggiunto, modificato o rimosso un modulo, riavvia il servizio. Su Linux usa:

sudo systemctl restart mudfish-dns.service

Su Windows riavvia Mudfish DNS dalla gestione dei servizi. Le azioni Avvia DNS, Arresta DNS e Applica impostazioni nell’app non ricaricano i moduli. Il servizio non si avvia se non può leggere una configurazione, se un percorso è errato o se si verifica un errore di caricamento o inizializzazione. Una directory dei moduli assente o vuota è consentita.

Durante lo sviluppo puoi ripetere l’argomento --module per caricare le librerie nell’ordine specificato. Questo sostituisce il caricamento automatico da modules.d. --config FILE cambia anche la posizione della directory dei moduli accanto al file di configurazione. --restore-dns esegue il ripristino senza caricare moduli.

Implementare gli hook

Leggi l’header mudfish_dns_module.h oppure scarica mudfish_dns_module.h. L’header definisce strutture, hook, azioni e regole di durata dei dati. Questa guida utilizza C ABI v2. Esporta mudfish_dns_module_init_v2() e verifica MUDFISH_DNS_MODULE_ABI_V2 e la dimensione della struttura ricevuta prima di impostare gli hook. Restituisci 0 se l’inizializzazione riesce.

Hook	Momento della chiamata
on_dns_query	Dopo l’accettazione della query analizzata, prima di consultare la cache o inoltrarla.
on_dns_response	Dopo la selezione della risposta, prima di memorizzarla in cache o restituirla al client. Anche le risposte in cache passano da questo hook.
on_web_hello	Dopo l’ispezione iniziale di HTTP Host/TLS SNI, prima della connessione o dell’elaborazione dei dati iniziali.
on_web_data	Dopo la lettura di dati successivi del client o del server, prima dell’inoltro.

Azioni DNS

Gli hook DNS v2 restituiscono 0 in caso di successo e impostano result->action.

Azione	Effetto
MUDFISH_DNS_CONTINUE	Continua con il modulo successivo e l’elaborazione normale.
MUDFISH_DNS_ALLOW	Termina la catena corrente degli hook e continua la normale risoluzione DNS o restituisce la risposta selezionata.
MUDFISH_DNS_BLOCK	Restituisce REFUSED.
MUDFISH_DNS_DROP	Scarta senza inviare una risposta DNS.
MUDFISH_DNS_ANSWER	Genera una risposta con l’indirizzo IPv4/IPv6 e il TTL forniti.
MUDFISH_DNS_REPLACE	Usa una risposta DNS completa in formato wire fornita dal modulo.

Non restituire direttamente la costante dell’azione dagli hook DNS v2. Un valore restituito diverso da 0 o un risultato non valido provoca SERVFAIL. ALLOW termina soltanto la catena corrente: non aggira regole dei domini, autorizzazioni dei protocolli o verifiche dei certificati. Tutti i risultati delle query, tranne DROP, passano anche dagli hook delle risposte.

Gli hook web restituiscono direttamente MUDFISH_DNS_CONTINUE oppure MUDFISH_DNS_REJECT. Rifiutare una richiesta web chiude la connessione. Per utilizzare gli hook web deve essere attiva la protezione web; il contenuto HTTPS decifrato non viene fornito.

Buffer, thread e cache

Gli eventi e i buffer di ingresso sono di sola lettura e validi soltanto durante il callback. Le risposte sostitutive devono utilizzare memoria di proprietà del modulo, valida fino al callback successivo dello stesso modulo o alla sua distruzione. Non restituire memoria sullo stack né puntatori presi in prestito dall’evento. ID DNS, opcode e domanda della risposta sostitutiva devono corrispondere alla query originale. I callback di un’istanza vengono eseguiti in sequenza, ma possono essere invocati da thread diversi. Devono terminare rapidamente e non propagare eccezioni oltre il confine ABI.

I risultati generati, sostituiti, bloccati o scartati non vengono memorizzati nella cache dell’host. Sostituire una risposta proveniente dalla cache non modifica la voce originale. L’host rimuove il flag AD dalle risposte sostitutive e non esegue verifica DNSSEC né nuova firma. I moduli che modificano dati firmati devono gestire autonomamente le firme invalidate.

Esempio e header

Le pagine seguenti contengono il codice completo dell’esempio e l’header necessario. Non occorre scaricare separatamente l’albero dei sorgenti Mudfish DNS.

File	Contenuto
policy.c — esempio di politica DNS	Consentire, bloccare o scartare query, generare risposte IP e modificare indirizzi e TTL delle risposte. Include comandi di compilazione e test Linux.
mudfish_dns_module.h — header del modulo	Dichiarazioni ABI, firme degli hook, costanti delle azioni e regole di proprietà dei buffer.

Prima di compilare, scarica policy.c e mudfish_dns_module.h nella stessa directory. Il comando dell’esempio genera una libreria Linux .so.