{ "id": 36894, "slug": "2025-06-04_alteracoes-incompativeis", "url": "https://agents.willem.com/pt/posts/2025-06-04_alteracoes-incompativeis/", "source_url": "https://willem.com/pt/2025-06-04_alteracoes-incompativeis/", "language": "pt", "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": "Alterações incompatíveis", "subtitle": "Atualizar o Dovecot 2.3 para o 2.4 no Debian Stable", "summary": "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!", "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 (pt_PT)", "date": "2026-10-20", "reviewed_by_native_reader": false, "language": "pt", "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": "it", "title": "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": "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": "Uma pilha completa de servidor de e-mail é composta por muitos componentes mais pequenos, afinados entre si", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-1.png" }, { "url": "https://willem.com/global/images/e88fe1cec23d.webp", "description": "Migrar a mail_location para mail_driver e mail_path com a nova sintaxe de variáveis do servidor", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-2.png" }, { "url": "https://willem.com/global/images/f0038d6aa77e.webp", "description": "As instruções de atualização de userdb e passdb são muito úteis à primeira vista /s", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-3.png" }, { "url": "https://willem.com/global/images/ee344f001a96.webp", "description": "Configuração do back-end SQL no 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": "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", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-5.png" }, { "url": "https://willem.com/global/images/939ffd625f0f.webp", "description": "Configuração do Sieve no Dovecot 2.3 (90-sieve.conf), com as variáveis sieve_default e sieve_dir, agora obsoletas", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-6.png" }, { "url": "https://willem.com/global/images/197ae89bb845.webp", "description": "Configuração do Sieve no Dovecot 2.4 (90-sieve.conf)", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-7.png" }, { "url": "https://willem.com/global/images/dd3339e34d1d.webp", "description": "Definir os números das portas IMAP e POP do servidor para poder depurar a nova configuração de forma privada e gradual", "manager_file": "148-bf2d6faf6057f115dc72e82d984e71359f16b48d8c42b4b41c2ee918cf46b556_ContentAsPost_36894_images-8.png" } ], "text": "⚠️ TL;DR: Atualizar o Dovecot 2.3 → 2.4 no Debian\n- 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.\n- 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- 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.\n- 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.\nUm passeio no parque\nHavia 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..?\nA exigir 'dovecot_config_version'\nQuase 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.\nA 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'.\nBasta 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.\nComplexidade integrada: rodas dentadas numa máquina\nO 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:\n- 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.\n- 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.\n- SpamAssassin: com um conjunto complexo de regras e análises bayesianas, as mensagens são analisadas automaticamente quanto à probabilidade de serem spam.\n- ClamAV: as mensagens são analisadas à procura de vírus. Os anexos são extraídos e analisados, ficheiro a ficheiro.\n- 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.\n- 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.\n- 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.\n- 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?\"\n- 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.\n- 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.\n- Roundcube: o servidor usa um programa de webmail muito difundido para os clientes acederem ao e-mail pelo navegador.\n- 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).\n- 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.\nTodas 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!\nNã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.\nParar para evitar perda de dados\nAssim 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.\nReescrever a configuração com RTFM\nA 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!\nA 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.\nSintaxe de notação das variáveis\nAntes, 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}'.\nQuando 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.\nEncriptação: 'ssl_cert' passa a 'ssl_server_cert_file'\nOutras 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.\nDividir a definição 'mail_location'\nOutra 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?).\nDovecot com back-end SQL: passdb e userdb\nSe 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.\nNa 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).\nPlugin Sieve\nSe 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:\nTestar a nova configuração\nPodes 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'.\nConclusão\nFalhas 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.\nEste 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.\nConfiguração de exemplo do Dovecot 2.4\nSe 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/", "word_count": 2064, "markdown_url": "https://agents.willem.com/pt/posts/2025-06-04_alteracoes-incompativeis/post.md" }