--- title: "Alterações incompatíveis" date: 2025-06-04 language: pt topics: ["data", "linux", "server", "work"] source_url: https://willem.com/pt/2025-06-04_alteracoes-incompativeis/ --- # Alterações incompatíveis *Atualizar o Dovecot 2.3 para o 2.4 no Debian Stable* > Na semana passada tive problemas inesperados durante um procedimento de manutenção de rotina na infraestrutura de e-mail da minha empresa. Processamos milhares de e-mails por dia e usamos o Dovecot para dar aos nossos clientes acesso às mensagens. Tudo parou de repente quando atualizei para a versão 2.4, que traz alterações incompatíveis... ai, ai! ## ⚠️ TL;DR: Atualizar o Dovecot 2.3 → 2.4 no Debian - **O Dovecot 2.4 traz alterações incompatíveis**: os ficheiros de configuração da 2.3 não funcionam. O software não arranca enquanto não os reescreveres. - **Nova sintaxe de configuração e novo sistema de variáveis**: parâmetros como `ssl_cert`, `mail_location` e `%d` mudaram de formato e de significado. - **Não existe migração automática**: é preciso rever e reescrever a configuração à mão, sobretudo se usas back-ends SQL, Sieve ou autenticação personalizada. - **Recomendação**: lê com atenção o guia_oficial_de_atualização (https://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html) antes de atualizares, e testa as configurações em isolamento. ## Um passeio no parque Havia algumas atualizações de segurança pendentes e alguns problemas de compatibilidade para resolver, por isso decidi atualizar alguns pacotes num servidor Debian GNU/Linux responsável pelos serviços de e-mail da minha empresa. Esta distribuição de GNU/Linux é conhecida pela sua estabilidade e fiabilidade. Não havia motivo para esperar problemas e comecei a atualização convencido de que acabaria em poucos minutos. Um simples "passeio no parque", o que poderia correr mal..? ## A exigir 'dovecot_config_version' Quase todo o servidor voltou a funcionar logo a seguir, como esperado, perturbando tão pouco os serviços que nem o alarme_do_monitor_de_disponibilidade (https://willem.com/en/2021-02-02_realtime-service-uptime-monitoring/) detetou qualquer falha, exceto no Dovecot. Este tipo de software é responsável pelo acesso IMAP e POP3 às caixas de correio. Encaixa como uma roda dentada bem afinada numa estrutura maior, em que outros programas, como o Postfix, dependem do seu funcionamento para aceitar e-mail recebido. O facto de o Dovecot não arrancar causou uma série de problemas. A primeira coisa que um administrador de servidores faz é verificar os daemons ('systemctl status dovecot') e depois inspecionar os registos, por exemplo com 'journalctl -u dovecot'. Isso mostrou rapidamente que o Dovecot se recusava a arrancar porque faltava um parâmetro de configuração: 'dovecot_config_version'. Basta acrescentar o parâmetro à configuração em '/etc/dovecot/dovecot.conf', pensas tu? Pois... NÃO. Acontece que os criadores do Dovecot puseram o erro lá por boas razões: a nova versão 2.4 do Dovecot é incompatível com os ficheiros de configuração da 2.3, o que significa que tens de reescrever muitos parâmetros. Não mudam só os nomes das variáveis, há também uma sintaxe totalmente nova para a expansão das variáveis de configuração. Um valor antigo como '%d' passa a ser '%{user | domain}'. A lista_de_alterações_é_longa (http://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html) e não há maneira automática de migrar a configuração. Imagina a minha cara quando percebi a dimensão do problema. ## Complexidade integrada: rodas dentadas numa máquina O problema do e-mail é que é *difícil*. Não porque um único componente seja difícil, mas porque, para ter uma pilha de e-mail completa, são precisas muitas peças a trabalhar em conjunto sem falhas. Estas são algumas das peças que compõem o serviço de e-mail da minha empresa: - **Postfix:** o agente principal de transferência de correio (MTA) SMTP, que comunica com outros servidores de e-mail para receber e enviar mensagens. Precisa de saber que endereços de e-mail são válidos para receber correio e quem está autorizado a enviar mensagens novas. - **Filtro Amavis:** todas as mensagens processadas pelo servidor passam pelo mecanismo de filtragem do Amavis, que verifica cada mensagem com o SpamAssassin e o ClamAV. - **SpamAssassin:** com um conjunto complexo de regras e análises bayesianas, as mensagens são analisadas automaticamente quanto à probabilidade de serem spam. - **ClamAV:** as mensagens são analisadas à procura de vírus. Os anexos são extraídos e analisados, ficheiro a ficheiro. - **Listas negras de DNS inverso:** além de analisar as mensagens, o servidor de e-mail faz também uma verificação de antecedentes aos servidores externos com que comunica. Os cabeçalhos são analisados e a reputação de cada salto é verificada. - **OpenDKIM:** algumas mensagens trazem uma assinatura de 'chave de domínio', que prova que o remetente está autorizado. As mensagens com cabeçalhos são verificadas e as restantes são assinadas por um serviço de milter ligado ao Postfix. - **Sieve:** as mensagens recebidas são ordenadas automaticamente com regras por utilizador, por exemplo para entregar certas mensagens em pastas específicas. Tem de saber que regras se aplicam a que endereços. - **MariaDB / MySQL:** os endereços de e-mail, os acessos válidos, os nomes de utilizador, os hashes das palavras-passe e os aliases ficam guardados numa base de dados centralizada. Há consultas SQL específicas para verificar coisas como "esta palavra-passe é válida?" - **Nginx:** o servidor de e-mail tem também um servidor web que permite gerir as contas e dá acesso ao e-mail por webmail. - **NodeJS:** a consola de gestão usa um back-end em NodeJS para que administradores e clientes possam configurar os seus endereços e palavras-passe. - **Roundcube**: o servidor usa um programa de webmail muito difundido para os clientes acederem ao e-mail pelo navegador. - **PHP:** o webmail precisa de PHP para funcionar, incluindo algumas dependências para falar com o Dovecot (por IMAP) e com o MariaDB (por SQL). - **Dovecot:** e depois há o Dovecot, a peça de software que dá aos utilizadores finais acesso ao seu e-mail. Permite que utilizadores autenticados acedam aos e-mails guardados nos discos da infraestrutura através de protocolos como IMAP ou POP3. ![Uma pilha completa de servidor de e-mail é composta por muitos componentes mais pequenos, afinados entre si](https://willem.com/global/images/5c709f1fc463.webp) Todas estas peças estão afinadas umas com as outras e encaixam com precisão, como as rodas dentadas de uma máquina complexa. A configuração de cada uma é feita à medida da sua função e muitas vezes liga-se a várias outras. Podes imaginar que uma mudança inesperada numa destas rodas (como o Dovecot) pode causar uma bela confusão! Não havia solução rápida, nem atualização automática da configuração. Como esta atualização era relativamente recente, a maioria dos grandes modelos de linguagem (IA) também não tinha resposta. O ChatGPT limitou-se a gerar sugestões baseadas na documentação antiga da 2.3. Para resolver o problema tive de recorrer às *'competências de servidores Linux à moda antiga'*: criar à mão uma configuração nova e feita à medida para o Dovecot 2.4. ## Parar para evitar perda de dados Assim que percebi a natureza do problema, parei de imediato a maior parte dos serviços de e-mail (ou seja, desliguei o motor por completo). Isto evita a perda de dados, porque os e-mails deixam de ser processados. Os outros servidores de e-mail põem então as mensagens em fila, por vezes devolvendo erros SMTP 4xx (como 421, 451, 454 ou 455). O desenho do protocolo mundial de e-mail prevê falhas temporárias e os outros servidores simplesmente tentam outra vez mais tarde. ## Reescrever a configuração com RTFM A mensagem de erro nos registos levou-me à documentação_oficial_do_Dovecot (https://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html), e lá estava: um AVISO realçado em amarelado a descrever as alterações de configuração. É um documento longo: em_PDF_são_18_páginas (https://willem.com/etcetera/2025-05-30_dovecot-upgrade-23-to-24.pdf). Num dia normal já dava algum trabalho lê-lo todo, imagina fazê-lo com a casa, como se costuma dizer, a arder! A configuração do Dovecot é feita de vários ficheiros que definem partes do comportamento do software. Por exemplo, como se faz a autenticação, como se integra com um filtro Sieve ou de onde vêm os nomes de utilizador e os hashes das palavras-passe para o início de sessão. As alterações da versão 2.4 afetam quase todos os parâmetros, porque os criadores introduziram uma sintaxe nova para as variáveis do servidor. ### Sintaxe de notação das variáveis Antes, a configuração usava uma notação de variáveis como '%u' para marcar o nome de utilizador. A nova sintaxe permite encadear variáveis com um modificador, o que possibilita normalização e coisas como a seleção de subcadeias. Por exemplo: para obter o domínio de e-mail a partir de um nome de utilizador já não usas '%d', mas sim a variável 'user' como base, encadeada com o modificador domain, nesta sintaxe: '%{user | domain}'. Quando percebi esta nova linguagem, apreciei mesmo a obra de arte que ela representa. É uma melhoria em relação aos antigos nomes de variáveis abreviados, porque já não precisas de um dicionário para os consultar: em vez de algo vago como '%r', lês '%{remove_ip}'. É intrinsecamente mais legível, algo que valorizo muito. ### Encriptação: 'ssl_cert' passa a 'ssl_server_cert_file' Outras alterações dizem respeito à forma como a configuração aponta para os ficheiros externos usados na encriptação. Antes tinhas uma definição 'ssl_cert' que podia conter o próprio certificado SSL/TLS como texto. Na versão 2.4 tens a variável 'ssl_server_cert_file', que recebe o caminho do certificado no sistema de ficheiros. **Não é só mudar o nome, a natureza do valor também é nova!** Para corrigir a configuração, tens de percorrer cada um destes parâmetros atualizados e determinar o impacto na tua instalação em particular. Dá trabalho e é fácil errar. ### Dividir a definição 'mail_location' Outra novidade da 2.4 é que a 'mail_location' se divide em várias variáveis mais pequenas. Antes, uma única variável definia onde o e-mail era guardado no disco. Agora tens de a dividir em duas variáveis, 'mail_driver' e 'mail_path', **E** usar a nova sintaxe de variáveis do servidor. Se errares numa destas, todo o e-mail desaparece (acredita em mim!). Consoante a tua configuração de armazenamento, convém confirmar duas vezes a parte do nome de utilizador (por exemplo, inclui o endereço de e-mail completo ou só o prefixo, sem o nome de domínio?). ![Migrar a mail_location para mail_driver e mail_path com a nova sintaxe de variáveis do servidor](https://willem.com/global/images/e88fe1cec23d.webp) ### Dovecot com back-end SQL: passdb e userdb Se a tua instalação do Dovecot usa uma base de dados (ou armazenamento) externa para autenticar nomes de utilizador e palavras-passe, vais ter de reescrever o 'auth-sql.conf.ext' em '/etc/dovecot/conf.d/', que é chamado/incluído pelo ficheiro 10-auth.conf. No Dovecot 2.4 há uma nova forma de segmentar as definições de passdb e userdb. Na configuração do Dovecot 2.3 usei um ficheiro externo com as consultas à base de dados e a cadeia de ligação. Durante a autenticação, as várias consultas servem para 1) autenticar os utilizadores e 2) carregar definições específicas de cada utilizador, como o caminho do armazenamento do e-mail. ![As instruções de atualização de userdb e passdb são muito úteis à primeira vista /s](https://willem.com/global/images/f0038d6aa77e.webp) ![Configuração do back-end SQL no Dovecot 2.3 (auth-sql.conf.ext e dovecot-sql.conf.ext) ](https://willem.com/global/images/ee344f001a96.webp) Na nova versão 2.4 tens de reestruturar os parâmetros para ficarem dentro de secções que incluem um indicador do tipo de back-end logo a seguir às palavras-chave 'userdb' e 'passdb' na configuração. Assim, se usas uma base de dados MySQL como back-end, 'userdb' passa a 'userdb sql'. Podes incluir os parâmetros da cadeia de ligação diretamente no ficheiro 'auth-sql.conf.ext', de modo que todos os parâmetros relevantes fiquem num só ficheiro de configuração. Para reduzir a complexidade, reescrevi a secção userdb para usar o driver de base de dados 'static': gera variáveis de configuração, como o caminho do e-mail do utilizador, a partir do seu nome de utilizador. Vê os documentos_dedicados (https://doc.dovecot.org/2.4.0/core/config/auth/passdb.html). ![Configuração do back-end SQL no Dovecot 2.4 (auth-sql.conf.ext), agora muito mais compacta do que a anterior. Há apenas uma consulta SQL, porque a secção userdb passa a usar o back-end static](https://willem.com/global/images/e0e59271debb.webp) ### Plugin Sieve Se a tua instalação usa o Sieve para ordenar o e-mail recebido, vais ter de ajustar a configuração no que toca à localização dos scripts, aos valores por omissão e ao comportamento. A nova versão 2.4 do Dovecot introduz um conceito chamado "Script Storage", que permite executar scripts carregados dinamicamente para diferentes utilizadores em vários eventos. A nossa configuração tem um script Sieve simples por omissão, que ordena automaticamente o e-mail marcado como spam para uma pasta chamada Spam. A nova sintaxe permite uma configuração mais compacta: ![Configuração do Sieve no Dovecot 2.3 (90-sieve.conf), com as variáveis sieve_default e sieve_dir, agora obsoletas](https://willem.com/global/images/939ffd625f0f.webp) ![Configuração do Sieve no Dovecot 2.4 (90-sieve.conf)](https://willem.com/global/images/197ae89bb845.webp) ## Testar a nova configuração Podes ficar tentado a simplesmente voltar a arrancar o servidor depois de redefinires a configuração 2.4. Mas deves ter muito cuidado, porque uma configuração errada pode fazer os clientes perder o acesso a todos os e-mails e/ou obrigá-los a transferir de novo as caixas de correio inteiras. Em vez disso, optei por uma abordagem gradual: mudei os números das portas IMAP (e POP3) para algo arbitrário. Assim pude testar a nova configuração sozinho, sem deixar os clientes reais ligarem-se ao servidor. Isto permitiu-me corrigir alguns erros de escrita, afinar parte da nova sintaxe das variáveis do servidor e lidar com algumas mensagens de registo estranhas. Podes controlar as portas do servidor no ficheiro '10-master.conf'. ![Definir os números das portas IMAP e POP do servidor para poder depurar a nova configuração de forma privada e gradual](https://willem.com/global/images/dd3339e34d1d.webp) ## Conclusão Falhas como esta são raras, graças à estabilidade do Debian GNU/Linux, mas não impossíveis. Para o serviço de e-mail Lemmid Online da minha empresa existem cópias de segurança diárias e um plano de recuperação de desastres testado. Embora desta vez não tenha sido preciso um failover completo, os exercícios anteriores foram decisivos para adaptar a configuração depressa. Este incidente foi um lembrete de que, mesmo com automação e IA, o conhecimento profundo do sistema, a preparação e a depuração manual continuam a ser ferramentas essenciais quando componentes críticos da infraestrutura mudam inesperadamente e sem caminhos de migração automáticos. ### Configuração de exemplo do Dovecot 2.4 Se encontraste este artigo à procura de uma solução para o teu servidor de e-mail avariado, talvez estes ficheiros de configuração de exemplo do Dovecot 2.4 te sejam úteis. Encontrei-os durante a minha própria reparação e podem poupar-te tempo a perceber a nova sintaxe: https://source.willem.com/dovecot-2.4-sample-config/