{ "id": 36894, "slug": "2025-06-04_modifiche-incompatibili", "url": "https://agents.willem.com/it/posts/2025-06-04_modifiche-incompatibili/", "source_url": "https://willem.com/it/2025-06-04_modifiche-incompatibili/", "language": "it", "date": "2025-06-04", "published": "2025-06-04T00:00:00+02:00", "created": "2025-06-26T21:12:39.663000+02:00", "updated": "2026-10-20T09:21:54.548000+02:00", "title": "Modifiche incompatibili", "subtitle": "Aggiornare Dovecot da 2.3 a 2.4 in Debian Stable", "summary": "La settimana scorsa ho avuto un problema inatteso durante una normale manutenzione dell'infrastruttura e-mail della mia azienda. Elaboriamo migliaia di e-mail al giorno e usiamo Dovecot per dare ai nostri clienti accesso ai loro messaggi. Tutto si è fermato di colpo quando ho aggiornato alla versione 2.4, che porta modifiche incompatibili... accidenti!", "topics": [ "data", "linux", "server", "work" ], "author": { "name": "Willem L. Middelkoop", "url": "https://willem.com" }, "provenance": { "kind": "model", "method": "Claude Sonnet, two passes (translation, then proofreading) against a glossary and hunspell", "date": "2026-10-20", "reviewed_by_native_reader": false, "language": "it", "source_language": "en" }, "translations": [ { "language": "en", "title": "Breaking Changes", "url": "https://agents.willem.com/en/posts/2025-06-04_breaking-changes/", "source_url": "https://willem.com/en/2025-06-04_breaking-changes/" }, { "language": "nl", "title": "Brekende Wijzigingen", "url": "https://agents.willem.com/nl/posts/2025-06-04_brekende-wijzigingen/", "source_url": "https://willem.com/nl/2025-06-04_brekende-wijzigingen/" }, { "language": "de", "title": "Änderungen mit Unterbrechungen", "url": "https://agents.willem.com/de/posts/2025-06-04_anderungen-mit-unterbrechungen/", "source_url": "https://willem.com/de/2025-06-04_anderungen-mit-unterbrechungen/" }, { "language": "es", "title": "Cambios importantes", "url": "https://agents.willem.com/es/posts/2025-06-04_cambios-importantes/", "source_url": "https://willem.com/es/2025-06-04_cambios-importantes/" }, { "language": "fr", "title": "Changements incompatibles", "url": "https://agents.willem.com/fr/posts/2025-06-04_changements-incompatibles/", "source_url": "https://willem.com/fr/2025-06-04_changements-incompatibles/" }, { "language": "pt", "title": "Alterações incompatíveis", "url": "https://agents.willem.com/pt/posts/2025-06-04_alteracoes-incompativeis/", "source_url": "https://willem.com/pt/2025-06-04_alteracoes-incompativeis/" }, { "language": "pap", "title": "Breaking Changes", "url": "https://agents.willem.com/pap/posts/2025-06-04_breaking-changes/", "source_url": "https://willem.com/pap/2025-06-04_breaking-changes/" }, { "language": "fy", "title": "Brekkende feroaringen", "url": "https://agents.willem.com/fy/posts/2025-06-04_brekkende-feroaringen/", "source_url": "https://willem.com/fy/2025-06-04_brekkende-feroaringen/" } ], "image": "https://willem.com/global/images/0b0368b2d26f.webp", "image_width": 2560, "images": [ { "url": "https://willem.com/global/images/5c709f1fc463.webp", "description": "Uno stack completo di server di posta è fatto di tanti componenti più piccoli, tarati finemente tra loro", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-1.png" }, { "url": "https://willem.com/global/images/e88fe1cec23d.webp", "description": "Migrare mail_location in mail_driver e mail_path con la nuova sintassi delle variabili del server", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-2.png" }, { "url": "https://willem.com/global/images/f0038d6aa77e.webp", "description": "Le istruzioni di aggiornamento di userdb e passdb sono utilissime a prima vista /s", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-3.png" }, { "url": "https://willem.com/global/images/ee344f001a96.webp", "description": "Configurazione del backend SQL di Dovecot 2.3 (auth-sql.conf.ext e dovecot-sql.conf.ext) ", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-4.png" }, { "url": "https://willem.com/global/images/e0e59271debb.webp", "description": "Configurazione del backend SQL di Dovecot 2.4 (auth-sql.conf.ext): ora molto più compatta della precedente. C'è una sola query SQL, perché la sezione userdb usa ora il backend static", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-5.png" }, { "url": "https://willem.com/global/images/939ffd625f0f.webp", "description": "La configurazione di Sieve in Dovecot 2.3 (90-sieve.conf) con le variabili sieve_default e sieve_dir, ormai obsolete", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-6.png" }, { "url": "https://willem.com/global/images/197ae89bb845.webp", "description": "La configurazione di Sieve in Dovecot 2.4 (90-sieve.conf)", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-7.png" }, { "url": "https://willem.com/global/images/dd3339e34d1d.webp", "description": "Impostare i numeri di porta IMAP e POP del server per poter fare debug privato e graduale della nuova configurazione", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-8.png" } ], "text": "⚠️ TL;DR: Aggiornare Dovecot 2.3 → 2.4 su Debian\n- Dovecot 2.4 introduce modifiche incompatibili: i file di configurazione della 2.3 non funzionano. Il software non parte finché non li riscrivi.\n- Nuova sintassi di configurazione e nuovo sistema di variabili: parametri come `ssl_cert`, `mail_location` e `%d` hanno cambiato formato e significato.\n- Nessun percorso di migrazione automatico: serve rivedere e riscrivere a mano la configurazione, soprattutto se usi backend SQL, Sieve o un'autenticazione personalizzata.\n- Consiglio: leggi con attenzione la guida_ufficiale_all'aggiornamento (https://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html) prima di aggiornare e testa le configurazioni in isolamento.\nUna passeggiata\nIn attesa di alcuni aggiornamenti di sicurezza e per risolvere dei problemi di compatibilità, ho deciso di aggiornare alcuni pacchetti su un server Debian GNU/Linux che gestisce i servizi e-mail della mia azienda. Questa distribuzione di GNU/Linux è nota per stabilità e affidabilità. Non c'era motivo di aspettarsi guai e ho avviato l'aggiornamento convinto che sarebbe bastato qualche minuto. Una \"passeggiata\", cosa potrebbe mai andare storto..?\nServe 'dovecot_config_version'\nQuasi tutto il server è tornato online subito, come previsto, disturbando i servizi così poco che nemmeno l'allarme_del_monitor_di_uptime (https://willem.com/en/2021-02-02_realtime-service-uptime-monitoring/) ha rilevato un'interruzione. Tranne Dovecot. Questo software gestisce l'accesso IMAP e POP3 alle caselle di posta. Si inserisce come un ingranaggio ben calibrato in un insieme più grande, dove altri programmi come Postfix dipendono dal suo funzionamento per accettare la posta in arrivo. Il fatto che Dovecot non partisse ha causato una serie di problemi.\nLa prima cosa che fa un amministratore di server è controllare i demoni ('systemctl status dovecot') e poi leggere i log, per esempio con 'journalctl -u dovecot'. Così è saltato fuori subito che Dovecot si rifiutava di partire perché mancava un parametro di configurazione: 'dovecot_config_version'.\nBasta aggiungere il parametro alla configurazione in '/etc/dovecot/dovecot.conf', penserai? Beh... NO. Gli autori di Dovecot hanno messo quell'errore per un buon motivo: la nuova versione 2.4 è incompatibile con i file di configurazione della 2.3, quindi bisogna riscrivere molti parametri. Non cambiano solo i nomi delle variabili: c'è anche una sintassi completamente nuova per l'espansione delle variabili. Un vecchio valore come '%d' diventa '%{user | domain}'. L'elenco_delle_modifiche_è_lungo (http://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html) e non esiste un modo automatico di migrare la configurazione. Immagina la mia faccia quando ho capito la portata del problema.\nComplessità integrata: ingranaggi in una macchina\nIl bello dei servizi e-mail è che sono difficili. Non perché un singolo componente sia complicato, ma perché per far funzionare uno stack e-mail completo servono molti pezzi diversi che lavorino insieme alla perfezione. Ecco alcuni dei pezzi che compongono il servizio di posta della mia azienda:\n- Postfix: il principale agente di trasferimento della posta SMTP (MTA), che dialoga con gli altri server di posta per ricevere e inviare e-mail. Deve sapere quali indirizzi e-mail sono validi per ricevere posta e chi è autorizzato a inviare nuovi messaggi.\n- Filtro Amavis: tutta la posta elaborata dal server passa dal meccanismo di filtraggio amavis, che controlla ogni messaggio con SpamAssassin e ClamAV.\n- SpamAssassin: con un complesso insieme di regole e analisi bayesiane, i messaggi vengono scansionati automaticamente per stimare la probabilità che siano spam.\n- ClamAV: i messaggi vengono controllati alla ricerca di virus. Gli allegati vengono estratti e analizzati file per file.\n- Blacklist DNS inverse: oltre a scansionare i messaggi, il server di posta controlla anche i server esterni con cui comunica. Le intestazioni vengono analizzate e si verifica la reputazione di ogni passaggio.\n- OpenDKIM: alcuni messaggi contengono una firma con 'chiave di dominio' che prova l'autorizzazione del mittente. I messaggi con quelle intestazioni vengono verificati, gli altri vengono firmati con un servizio milter collegato a Postfix.\n- Sieve: i messaggi in arrivo vengono smistati automaticamente con regole per utente, per esempio consegnando certi messaggi in cartelle specifiche. Deve sapere quali regole valgono per quali indirizzi.\n- MariaDB / MySQL: indirizzi e-mail, login validi, nomi utente, hash delle password e alias sono salvati in un database centrale. Query SQL specifiche controllano cose come \"questa password è valida?\"\n- Nginx: il server di posta ha anche un server web che permette di gestire gli account e di accedere alla posta via webmail.\n- NodeJS: la console di gestione usa un backend NodeJS che permette ad amministratori e clienti di impostare indirizzi e password.\n- Roundcube: il server usa un programma di webmail molto diffuso per permettere ai clienti di accedere alla posta dal browser.\n- PHP: la webmail ha bisogno di PHP per funzionare, con alcune dipendenze per dialogare con Dovecot (via IMAP) e MariaDB (via SQL).\n- Dovecot: poi c'è Dovecot, il software che permette davvero agli utenti finali di accedere alla loro posta. Consente agli utenti autenticati di raggiungere le e-mail salvate sui dischi dell'infrastruttura con protocolli come IMAP o POP3.\nQuesti pezzi sono tarati con precisione l'uno sull'altro, come gli ingranaggi di una macchina complessa che combaciano alla perfezione. La loro configurazione è fatta su misura per il ruolo specifico e spesso dialogano con più altri pezzi. Puoi immaginare che un cambiamento inatteso in uno di questi ingranaggi (come Dovecot) possa creare un bel disordine!\nNon c'era una soluzione rapida, nessun aggiornamento automatico della configurazione. Essendo l'aggiornamento relativamente recente, nemmeno la maggior parte dei grandi modelli linguistici (IA) aveva una risposta. ChatGPT generava semplicemente suggerimenti basati sulla vecchia documentazione 2.3. Per risolvere il problema ho dovuto usare le 'competenze da server Linux della vecchia scuola': creare a mano una nuova configurazione su misura per Dovecot 2.4.\nFermare tutto per non perdere dati\nQuando ho capito la natura del problema, ho subito fermato la maggior parte dei servizi e-mail (cioè ho spento completamente il motore). Così non si perdono dati, perché le e-mail non vengono più elaborate. Gli altri server di posta mettono in coda i messaggi, a volte con errori SMTP 4xx (come 421, 451, 454 o 455). Il protocollo e-mail mondiale è progettato per tollerare interruzioni temporanee, e gli altri server semplicemente riproveranno più tardi.\nRiscrivere la configurazione con RTFM\nIl messaggio d'errore nei log mi ha portato alla documentazione_ufficiale_di_Dovecot (https://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html), ed eccolo lì: un AVVISO evidenziato in giallo che descrive le modifiche alla configurazione. È un documento lungo: in_PDF_sono_18_pagine (https://willem.com/etcetera/2025-05-30_dovecot-upgrade-23-to-24.pdf). In un giorno normale servirebbe un certo impegno per leggerlo tutto, immagina farlo mentre la casa, come si dice, va a fuoco!\nLa configurazione di Dovecot è fatta di vari file, ciascuno dei quali imposta una parte del comportamento del software. Per esempio come avviene l'autenticazione, come si integra con un filtro Sieve o da dove prende nomi utente e hash delle password per il login. Le modifiche della 2.4 toccano quasi tutti i parametri, perché gli autori hanno introdotto una nuova sintassi per le variabili del server.\nSintassi delle variabili\nPrima la configurazione usava notazioni come '%u' come segnaposto per il nome utente. La nuova sintassi permette di passare le variabili a un modificatore, così puoi normalizzare e selezionare sottostringhe. Per esempio: per ricavare il dominio e-mail da un nome utente non usi più '%d', ma prendi la variabile 'user' come base e la passi al modificatore domain con questa sintassi: '%{user | domain}'.\nUna volta capito questo nuovo linguaggio, ne ho apprezzato molto la qualità. È un miglioramento rispetto ai vecchi nomi abbreviati, perché non serve più un dizionario per capire cosa significano: invece di qualcosa di vago come '%r' ora leggi '%{remove_ip}'. È molto più leggibile, e questo per me conta parecchio.\nCifratura: 'ssl_cert' diventa 'ssl_server_cert_file'\nAltre modifiche riguardano il modo in cui la configurazione punta ai file esterni usati per la cifratura. Prima c'era l'impostazione 'ssl_cert', che poteva contenere direttamente il certificato SSL/TLS come stringa. Nella versione 2.4 c'è la variabile 'ssl_server_cert_file', che prende invece un percorso verso il certificato nel filesystem. Non è solo un cambio di nome, è nuova anche la natura del valore! Per sistemare la configurazione devi passare in rassegna ognuno di questi parametri aggiornati e capire l'impatto sul tuo caso. Richiede tempo e si sbaglia facilmente.\nL'impostazione 'mail_location' si divide\nNovità della 2.4: 'mail_location' è suddivisa in più variabili più piccole. Prima una sola variabile definiva dove salvare la posta sul disco. Ora devi dividerla in due variabili, 'mail_driver' e 'mail_path', E usare la nuova sintassi delle variabili del server. Se sbagli una di queste cose, tutta la posta sparisce (fidati!). A seconda della tua configurazione di storage, conviene ricontrollare la parte del nome utente (per esempio: includi l'intero indirizzo e-mail o solo il prefisso senza dominio?).\nDovecot con backend SQL: passdb e userdb\nSe la tua installazione di Dovecot usa un database (o archivio) esterno per autenticare nomi utente e password, devi riscrivere 'auth-sql.conf.ext' in '/etc/dovecot/conf.d/', che viene richiamato/incluso dal file 10-auth.conf. In Dovecot 2.4 c'è un nuovo modo di suddividere le impostazioni di passdb e userdb. Nella configurazione di Dovecot 2.3 usavo un file esterno con le query del database e la stringa di connessione. Durante l'autenticazione le varie query servono a 1) autenticare gli utenti e 2) caricare le impostazioni specifiche dell'utente, come il percorso dell'archivio di posta.\nNella nuova versione 2.4 devi ristrutturare i parametri in modo che stiano dentro sezioni che includono un indicatore del tipo di backend subito dopo le parole chiave 'userdb' e 'passdb' nella configurazione. Quindi, se usi un database MySQL come backend, 'userdb' diventa 'userdb sql'. Puoi mettere i parametri della stringa di connessione direttamente nel file 'auth-sql.conf.ext', così tutti i parametri rilevanti stanno in un solo file di configurazione. Per ridurre la complessità ho riscritto la sezione userdb usando il driver di database 'static': genera le variabili di configurazione, come il percorso della posta dell'utente, a partire dal nome utente. Vedi i documenti_dedicati (https://doc.dovecot.org/2.4.0/core/config/auth/passdb.html).\nPlugin Sieve\nSe la tua installazione usa Sieve per smistare la posta in arrivo, devi adattare la posizione degli script, i loro valori predefiniti e il loro comportamento. La nuova versione 2.4 di Dovecot introduce un concetto chiamato \"Script Storage\", che permette di eseguire script caricati dinamicamente per utenti diversi in vari eventi. Nella nostra installazione c'è un semplice script sieve predefinito che smista automaticamente nella cartella Spam la posta segnalata come spam. La nuova sintassi permette una configurazione più compatta:\nTestare la nuova configurazione\nPotresti essere tentato di riavviare semplicemente il server dopo aver ridefinito la configurazione 2.4. Ma stai molto attento, perché una configurazione sbagliata può far perdere ai clienti l'accesso a tutte le e-mail e/o costringerli a riscaricare intere caselle di posta. Io ho scelto un approccio graduale: ho cambiato i numeri di porta IMAP (e POP3) con valori arbitrari. Così potevo testare da solo la nuova configurazione, senza che i clienti reali si collegassero al server. Mi ha permesso di correggere alcuni errori di battitura, rifinire la nuova sintassi delle variabili e capire alcuni strani messaggi di log. Le porte del server si controllano dal file '10-master.conf'.\nConclusione\nInterruzioni così sono rare, grazie alla stabilità di Debian GNU/Linux, ma non impossibili. Per il servizio e-mail Lemmid Online della mia azienda ci sono backup giornalieri e un piano di disaster recovery testato. Questa volta non è servito un failover completo, ma le esercitazioni precedenti sono state decisive per adattare la configurazione in fretta.\nQuesto episodio mi ha ricordato che, anche con automazione e IA, la conoscenza profonda del sistema, la preparazione e il debug manuale restano strumenti essenziali quando componenti critici dell'infrastruttura cambiano all'improvviso e senza percorsi di migrazione automatici.\nConfigurazione di esempio per Dovecot 2.4\nSe sei arrivato a questo articolo cercando una soluzione per il tuo server di posta rotto, questi file di configurazione di esempio per Dovecot 2.4 potrebbero esserti utili. Li ho trovati durante la mia riparazione e potrebbero farti risparmiare tempo nel capire la nuova sintassi: https://source.willem.com/dovecot-2.4-sample-config/", "word_count": 1922, "markdown_url": "https://agents.willem.com/it/posts/2025-06-04_modifiche-incompatibili/post.md" }