---
title: "Cambios importantes"
date: 2025-06-04
language: es
topics: ["data", "linux", "server", "work"]
source_url: https://willem.com/es/2025-06-04_cambios-importantes/
---
# Cambios importantes

*Actualizar Dovecot 2.3 a 2.4 en Debian Stable*

> La semana pasada me topé con un problema inesperado durante un mantenimiento rutinario de la infraestructura de correo de mi empresa. Procesamos miles de correos cada día y usamos Dovecot para que nuestros clientes accedan a sus mensajes. Todo se paró en seco cuando actualicé a la versión 2.4, que trae cambios que rompen la compatibilidad... ¡vaya!

## ⚠️ TL;DR: actualizar Dovecot 2.3 → 2.4 en Debian

- **Dovecot 2.4 trae cambios que rompen la compatibilidad**: los archivos de configuración de 2.3 son incompatibles. El software no arrancará hasta que los reescribas.

- **Nueva sintaxis de configuración y nuevo sistema de variables**: parámetros como `ssl_cert`, `mail_location` y `%d` han cambiado de formato y de significado.

- **No hay migración automática**: hay que revisar y reescribir la configuración a mano, sobre todo si usas backends SQL, Sieve o autenticación personalizada.

- **Recomendación**: lee con calma la guía_oficial_de_actualización (https://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html) antes de actualizar y prueba las configuraciones de forma aislada.

## Un paseo por el parque

Con unas actualizaciones de seguridad pendientes y para resolver algunos problemas de compatibilidad, decidí actualizar varios paquetes en un servidor Debian GNU/Linux que se ocupa de los servicios de correo de mi empresa. Esta distribución de GNU/Linux es famosa por su estabilidad y fiabilidad. No había motivo para esperar problemas y empecé la actualización convencido de que terminaría en cuestión de minutos. Un simple "paseo por el parque": ¿qué podía salir mal...?

## Se exige 'dovecot_config_version'

Casi todo el servidor volvió a estar en línea enseguida, como esperaba, y los servicios se interrumpieron tan poco que ni siquiera la alarma_del_monitor_de_disponibilidad (https://willem.com/en/2021-02-02_realtime-service-uptime-monitoring/) detectó una caída. Todos menos Dovecot. Este software se encarga del acceso IMAP y POP3 a los buzones. Encaja como un engranaje afinado en una instalación mayor, donde otros programas como Postfix dependen de que funcione para aceptar el correo entrante. Que Dovecot no arrancara provocó una cadena de problemas.

Lo primero que hace un administrador de servidores es comprobar los demonios ('systemctl status dovecot') y luego revisar los registros, por ejemplo con 'journalctl -u dovecot'. Enseguida quedó claro que Dovecot se negaba a arrancar porque faltaba un parámetro de configuración: 'dovecot_config_version'.

¿Basta con añadir el parámetro a la configuración en '/etc/dovecot/dovecot.conf'? Pues... NO. Resulta que los creadores de Dovecot pusieron ese error por una buena razón: la nueva versión 2.4 es incompatible con los archivos de configuración de la 2.3, así que tendrás que reescribir muchos parámetros. No son solo los nombres de las variables de configuración: también hay una sintaxis totalmente nueva para expandir variables. Un valor antiguo como '%d' ahora pasa a ser '%{user | domain}'. La lista_de_cambios_es_larga (http://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html) y no hay forma automática de migrar tu configuración. Imagínate la cara que se me quedó al darme cuenta de la magnitud del problema.

## Complejidad integrada: engranajes en una máquina

Lo que pasa con el correo es que es *difícil*. No porque un componente sea complicado, sino porque para tener una pila de correo completa hacen falta muchas piezas distintas que funcionen juntas sin fisuras. Estas son algunas de las piezas del servicio de correo de mi empresa:

- **Postfix:** el agente principal de transferencia de correo (MTA) SMTP. Habla con otros servidores de correo para recibir y enviar mensajes. Necesita saber qué direcciones son válidas para recibir correo y quién está autorizado a enviar mensajes nuevos.

- **Filtro Amavis:** todos los correos que procesa el servidor pasan por el mecanismo de filtrado de Amavis, que revisa cada mensaje con SpamAssassin y ClamAV.

- **SpamAssassin:** con un complejo conjunto de reglas y análisis bayesianos, analiza automáticamente los mensajes para calcular la probabilidad de que sean spam.

- **ClamAV:** busca virus en los mensajes. Los adjuntos se extraen y se analizan archivo por archivo.

- **Listas negras DNS inversas:** además de analizar los mensajes, el servidor de correo comprueba los antecedentes de los servidores externos con los que se comunica. Se analizan las cabeceras del correo y se revisa la reputación de cada salto.

- **OpenDKIM:** algunos mensajes llevan una firma de 'clave de dominio' que demuestra que su remitente está autorizado. Los mensajes con firma se verifican y los demás se firman mediante un servicio de filtrado (milter) conectado a Postfix.

- **Sieve:** los mensajes entrantes se ordenan automáticamente con reglas por usuario, por ejemplo para entregar ciertos mensajes en carpetas concretas. Necesita saber qué reglas se aplican a qué direcciones.

- **MariaDB / MySQL:** las direcciones de correo, los inicios de sesión válidos, los nombres de usuario, los hashes de las contraseñas y los alias se guardan en una base de datos centralizada. Se configuran consultas SQL concretas para comprobar cosas como "¿es válida esta contraseña?"

- **Nginx:** el servidor de correo también tiene un servidor web que permite gestionar las cuentas y ofrece acceso al correo mediante webmail.

- **NodeJS:** la consola de administración usa un backend NodeJS para que los administradores del servidor y los clientes configuren sus direcciones y contraseñas.

- **Roundcube**: el servidor usa un programa de webmail muy extendido para que los clientes accedan a su correo desde el navegador.

- **PHP:** el webmail necesita PHP para funcionar, con algunas dependencias para hablar con Dovecot (por IMAP) y con MariaDB (por SQL).

- **Dovecot:** y luego está Dovecot, el software que de verdad permite a los usuarios finales acceder a su correo. Deja que los usuarios autenticados lean los correos guardados en los discos de la infraestructura mediante protocolos como IMAP o POP3.

![Una pila completa de servidor de correo se compone de muchos componentes más pequeños, afinados entre sí](https://willem.com/global/images/5c709f1fc463.webp)

Todas estas piezas están afinadas entre sí, como los engranajes de una máquina compleja: encajan con precisión. Su configuración está hecha a medida de su función y a menudo se comunican con varias piezas más. ¡Ya te imaginas que un cambio inesperado en uno de esos engranajes (como Dovecot) puede causar un buen trastorno!

No había ninguna solución rápida, ninguna actualización automática de la configuración. Como la versión era relativamente nueva, la mayoría de los grandes modelos de lenguaje (IA) tampoco tenían respuesta. ChatGPT se limitó a generar sugerencias basadas en la documentación antigua de la 2.3. Para resolver el problema tuve que recurrir a *'habilidades de servidores Linux de la vieja escuela'*: crear a mano una configuración nueva y a medida para Dovecot 2.4.

## Parar para evitar la pérdida de datos

En cuanto entendí la naturaleza del problema, detuve de inmediato la mayoría de los servicios de correo (es decir, paré el motor del todo). Así se evita perder datos, porque los correos dejan de procesarse. Otros servidores de correo ponen entonces los mensajes en cola, y a veces devuelven errores SMTP 4xx (como 421, 451, 454 o 455). El diseño del protocolo de correo mundial admite caídas temporales: los demás servidores sencillamente lo reintentarán más tarde.

## Reescribir la configuración a base de RTFM

El mensaje de error de los registros me llevó a la documentación_oficial_de_Dovecot (https://doc.dovecot.org/2.4.0/installation/upgrade/2.3-to-2.4.html) y allí estaba: una ADVERTENCIA resaltada en amarillo que describe los cambios de configuración. Es un documento largo: en_PDF_son_18_páginas (https://willem.com/etcetera/2025-05-30_dovecot-upgrade-23-to-24.pdf). Un día normal cuesta cierto esfuerzo leérselo. ¡Imagínate hacerlo con la casa ardiendo, como quien dice!

La configuración de Dovecot se compone de varios archivos que definen partes del comportamiento del software: cómo se autentica, cómo se integra con un filtro Sieve o de dónde saca los nombres de usuario y los hashes de contraseña para el inicio de sesión. Los cambios de Dovecot 2.4 afectan a casi todos los parámetros, porque sus creadores han introducido una sintaxis nueva para las variables del servidor.

### Sintaxis de las variables

Antes la configuración usaba una notación como '%u' como marcador de posición del nombre de usuario. La sintaxis nueva permite encadenar variables con un modificador, lo que da pie a normalizar valores y a cosas como seleccionar subcadenas. Por ejemplo: para obtener el dominio de correo a partir de un nombre de usuario ya no usas '%d', sino la variable 'user' como base y la encadenas con el modificador domain con esta sintaxis: '%{user | domain}'.

Cuando entendí este lenguaje nuevo, aprecié de verdad la obra de arte que supone. Es una mejora respecto a los antiguos nombres de variable abreviados, porque ya no necesitas un diccionario para consultarlos: en lugar de algo vago como '%r', ahora lees '%{remove_ip}'. Es más legible por naturaleza, algo que valoro mucho.

### Cifrado: 'ssl_cert' pasa a ser 'ssl_server_cert_file'

Otros cambios afectan a cómo apunta la configuración a los archivos externos que se usan para el cifrado. Antes había un ajuste 'ssl_cert' que podía contener el propio certificado SSL/TLS como cadena de texto. En la versión 2.4 tienes la variable 'ssl_server_cert_file', que recibe la ruta del certificado en el sistema de archivos. **¡No es solo un cambio de nombre: la naturaleza del valor también es nueva!** Para arreglar la configuración tendrás que recorrer cada uno de estos parámetros y determinar qué impacto tienen en tu instalación. Lleva mucho tiempo y es fácil equivocarse.

### Dividir el ajuste 'mail_location'

Otra novedad de la 2.4 es que 'mail_location' se divide en varias variables más pequeñas. Antes, una sola variable definía dónde se guardaba el correo en el disco. Ahora hay que dividirla en dos variables, 'mail_driver' y 'mail_path', **Y** usar la nueva sintaxis de variables del servidor. Si te equivocas en cualquiera de las dos, todo el correo desaparece (¡confía en mí!). Según tu configuración de almacenamiento, conviene que compruebes dos veces la parte del nombre de usuario (por ejemplo, ¿incluyes la dirección de correo completa o solo el prefijo, sin el dominio?).

![Migrar mail_location a mail_driver y mail_path con la nueva sintaxis de variables del servidor](https://willem.com/global/images/e88fe1cec23d.webp)

### Dovecot con backend SQL: passdb y userdb

Si tu instalación de Dovecot usa una base de datos (o almacén) externa para autenticar nombres de usuario y contraseñas, tendrás que reescribir 'auth-sql.conf.ext' en '/etc/dovecot/conf.d/', que llama (incluye) el archivo 10-auth.conf. En Dovecot 2.4 hay una forma nueva de segmentar los ajustes de passdb y userdb. En la instalación de Dovecot 2.3 yo usaba un archivo externo con las consultas a la base de datos y la cadena de conexión. Durante la autenticación se usan varias consultas para 1) autenticar a los usuarios y 2) cargar los ajustes propios de cada usuario, como la ruta de su almacén de correo.

![Las instrucciones de actualización de userdb y passdb resultan muy útiles a primera vista /s](https://willem.com/global/images/f0038d6aa77e.webp)

![Configuración del backend SQL en Dovecot 2.3 (auth-sql.conf.ext y dovecot-sql.conf.ext)](https://willem.com/global/images/ee344f001a96.webp)

En la versión 2.4 hay que reestructurar los parámetros dentro de secciones que llevan un indicador del tipo de backend justo detrás de las palabras clave 'userdb' y 'passdb' de la configuración. Así, si usas una base de datos MySQL como backend, 'userdb' pasa a ser 'userdb sql'. Puedes poner los parámetros de la cadena de conexión directamente en el archivo 'auth-sql.conf.ext', de modo que todos los parámetros relevantes queden en un único archivo de configuración. Para reducir la complejidad, reescribí la sección userdb para que use el driver de base de datos 'static': genera las variables de configuración, como la ruta de correo del usuario, a partir de su nombre de usuario. Consulta la documentación_específica (https://doc.dovecot.org/2.4.0/core/config/auth/passdb.html).

![Configuración del backend SQL en Dovecot 2.4 (auth-sql.conf.ext): ahora mucho más compacta que antes. Solo queda una consulta SQL, porque la sección userdb ahora usa el backend static](https://willem.com/global/images/e0e59271debb.webp)

### Plugin de Sieve

Si tu instalación usa Sieve para ordenar el correo entrante, tendrás que ajustarla en lo que respecta a la ubicación de los scripts, sus valores por defecto y su comportamiento. La nueva versión 2.4 de Dovecot introduce un concepto llamado "Script Storage", que permite ejecutar scripts cargados dinámicamente para distintos usuarios en distintos eventos. En nuestro caso hay un script de Sieve por defecto muy sencillo que manda automáticamente el correo marcado como spam a una carpeta llamada Spam. La sintaxis nueva permite una configuración más compacta:

![Configuración de Sieve en Dovecot 2.3 (90-sieve.conf), con las variables sieve_default y sieve_dir, ya obsoletas](https://willem.com/global/images/939ffd625f0f.webp)

![Configuración de Sieve en Dovecot 2.4 (90-sieve.conf)](https://willem.com/global/images/197ae89bb845.webp)

## Probar la configuración nueva

Puede que te tiente arrancar el servidor sin más después de redefinir la configuración 2.4. Pero hay que ir con mucho cuidado, porque una configuración incorrecta podría hacer que los clientes pierdan el acceso a todo su correo o que se vean obligados a volver a descargar buzones enteros. Yo opté por un enfoque gradual: cambié los números de puerto de IMAP (y POP3) por otros arbitrarios. Así pude probar la instalación nueva yo solo, sin que los clientes de verdad pudieran conectarse al servidor. Eso me permitió corregir algunas erratas, pulir parte de la nueva sintaxis de variables y lidiar con unos cuantos mensajes de registro raros. Los números de puerto del servidor se controlan desde el archivo '10-master.conf'.

![Cambiar los puertos IMAP y POP del servidor para poder depurar la configuración nueva en privado y de forma gradual](https://willem.com/global/images/dd3339e34d1d.webp)

## Conclusión

Caídas como esta son raras, gracias a la estabilidad de Debian GNU/Linux, pero no imposibles. Para el servicio de correo Lemmid Online de mi empresa hay copias de seguridad diarias y un plan de recuperación ante desastres probado. Esta vez no hizo falta una conmutación por error completa, pero los simulacros anteriores fueron decisivos para adaptar la configuración con rapidez.

Este incidente me recordó que, incluso con automatización e IA, el conocimiento profundo del sistema, la preparación y la depuración manual siguen siendo herramientas esenciales cuando los componentes críticos de la infraestructura cambian de forma inesperada y sin una vía de migración automática.

### Configuración de ejemplo para Dovecot 2.4

Si has llegado a este artículo buscando una solución para tu propio servidor de correo averiado, quizá te vengan bien estos archivos de configuración de ejemplo para Dovecot 2.4. Los encontré durante mi propia reparación y puede que te ahorren algo de tiempo para descifrar la sintaxis nueva: https://source.willem.com/dovecot-2.4-sample-config/