Alterações incompatíveis

⚠️ 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 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 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 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.

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, 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. 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?).

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.

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.

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:

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'.

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/