Cómo resolver problemas de RoundCube en linux

 Le preguntamos a Gemini, la inteligencia artificial de Google, cómo resolver problemas de RoundCube  en linux

Explicanos detalladamente cómo resolver problemas de RoundCube  en linux

Para resolver problemas en Roundcube, el primer paso es entender que Roundcube es una aplicación cliente: casi todos sus errores no se originan en el propio software, sino en fallos de comunicación con la base de datos, bloqueos de certificados/puertos con IMAP (Dovecot) y SMTP (Postfix), permisos de sistema de archivos o límites de PHP.

1. El Centro de Diagnóstico (Logs y Modo Depuración)

Antes de cambiar configuraciones a ciegas, activa el rastreo de eventos para ver exactamente qué falla en la capa web o de red.

Archivos de Registro Principales

Error log de Roundcube: /var/www/roundcube/logs/errors.log (Muestra errores de aplicación, base de datos y fallos de autenticación).

Error log del servidor web: /var/log/nginx/error.log o /var/log/apache2/error.log (Útil para investigar páginas en blanco o errores HTTP 500).

Log del servicio de correo: /var/log/mail.log o journalctl -u dovecot -u postfix (Muestra cómo reaccionan Dovecot y Postfix cuando Roundcube intenta conectar).

Activar la Depuración Profunda de IMAP y SMTP

Si los mensajes de error en la pantalla son genéricos, puedes obligar a Roundcube a registrar cada comando SMTP/IMAP enviado en texto plano.

Edita /var/www/roundcube/config/config.inc.php:

PHP

// Habilita el nivel de log detallado

$config['debug_level'] = 1;



// Muestra el tráfico completo de entrada y salida IMAP

$config['imap_debug'] = true;



// Muestra el tráfico completo de entrada y salida SMTP

$config['smtp_debug'] = true;

Esto generará los archivos /var/www/roundcube/logs/imap.log y /var/www/roundcube/logs/smtp.log con la traza exacta del fallo. (Asegúrate de desactivarlo en producción una vez resuelto el problema, ya que puede llenar el disco rápidamente).

2. Diagnóstico y Solución por Categoría de Error

Error 1: "Connection to storage server failed" (Error de IMAP)

Causa: Roundcube no puede conectar con Dovecot (el servidor que lee los buzones).

Paso 1: Verificar que Dovecot esté escuchando.

Bash

sudo systemctl status dovecot

sudo ss -tlpn | grep -E '143|993'

Paso 2: Certificados SSL/TLS autofirmados o no coincidentes.

Si configuraste IMAP con cifrado SSL/TLS (tls://127.0.0.1 o ssl://localhost), PHP rechazará la conexión si el certificado SSL de Dovecot no es válido o es autofirmado.

Solución: Agrega la exención de verificación de certificados en config.inc.php:

PHP

$config['imap_conn_options'] = array(

        'ssl' => array(

             'verify_peer' => false,

             'verify_peer_name' => false,

            'allow_self_signed' => true,

      ),

);

Error 2: "SMTP Error (-1): Connection failed" / "Authentication failed"

Causa: El usuario puede leer correos pero no puede enviarlos.

Paso 1: Mismos credenciales para envío.

Asegúrate de que Roundcube use el usuario y contraseña de la sesión activa para identificarse ante Postfix:

PHP

// Usar las credenciales del usuario autenticado (%u y %p)

$config['smtp_user'] = '%u';

$config['smtp_pass'] = '%p';

Paso 2: Ignorar errores de certificado SSL en SMTP.

Al igual que con IMAP, si Postfix usa un certificado autofirmado en el puerto 587 o 465, añade:

PHP

$config['smtp_conn_options'] = array(

        'ssl' => array(

        'verify_peer' => false,

        'verify_peer_name' => false,

        'allow_self_signed' => true,

     ),

);

Error 3: "DATABASE ERROR: CONNECTION FAILED"

Causa: La cadena DSN en config.inc.php es incorrecta, MariaDB está caído o faltan permisos de usuario SQL.

Paso 1: Probar la conexión desde la línea de comandos.

Extrae las credenciales del archivo de configuración e intenta ingresar manualmente:

Bash

mysql -u roundcube -p'TuContraseña' -h localhost roundcubemail

Paso 2: Socket UNIX vs IP TCP.

En Linux, si la cadena DSN usa localhost, PHP intentará usar el socket de Unix (/var/run/mysqld/mysqld.sock). Si MariaDB está escuchando solo en TCP, cambiar localhost por 127.0.0.1 resuelve el problema:

PHP

// Cambiar 'localhost' por '127.0.0.1' fuerza conexión TCP

$config['db_dsn'] = 'mysql://roundcube:TuContraseña@127.0.0.1/roundcubemail';

Error 4: Pantalla en Blanco (HTTP 500 / White Screen of Death)

Causa: Casi siempre se debe a módulos de PHP faltantes o permisos de archivos incorrectos.

Paso 1: Verificar extensiones PHP requeridas.

Si falta php-xml o php-mbstring, Roundcube colapsa sin mostrar texto.

Bash

# Comprobar si los módulos requeridos están activos

php -m | grep -E 'xml|mbstring|intl|pdo_mysql'

Si alguno no aparece, instálalo (ejemplo en Ubuntu/Debian):

Bash

sudo apt install php-mbstring php-xml php-intl php-mysql -y

sudo systemctl restart php8.1-fpm # Ajusta a tu versión de PHP

Paso 2: Corregir permisos de carpetas temp/ y logs/.

Si el usuario del servidor web (www-data o nginx) no puede escribir en los directorios de trabajo, la página no cargará.

Bash

sudo chown -R www-data:www-data /var/www/roundcube

sudo chmod -R 775 /var/www/roundcube/temp /var/www/roundcube/logs

Error 5: "File too large" (Fallo al adjuntar archivos)

Causa: La restricción está en las directivas de PHP, no en Roundcube.

Para permitir adjuntos de hasta 25 MB, edita tu archivo php.ini (habitualmente en /etc/php/8.x/fpm/php.ini o /etc/php/8.x/apache2/php.ini):

Ini, TOML

upload_max_filesize = 25M

post_max_size = 30M

memory_limit = 256M

Reinicia el proceso de PHP y el servidor web para aplicar cambios:

Bash

sudo systemctl restart php8.1-fpm nginx

¿Quieres configurar el plugin de autenticación de dos factores (2FA) en Roundcube?