Si recibes un error de:
Unsupported PHP version. Required PHP >= 7.3
al momento de ingresar a roundcube es porque la version de PHP seleccionada en el servidor es muy elemental y se debe corregir a nivel avanzado. este tutorial te enseñara a como hacerlo.

Cómo Configurar PHP-FPM para Roundcube en HestiaCP

Este tutorial te enseñará a configurar HestiaCP para que Roundcube use una versión específica de PHP. Explicaremos cómo funciona la interacción entre Nginx, Apache y PHP-FPM, y el motivo por el cual HestiaCP asigna una versión incorrecta de PHP por defecto.

1. Introducción

HestiaCP gestiona el webmail mediante Roundcube, pero no permite cambiar la versión de PHP que usa Roundcube de forma sencilla. Esto puede causar errores si Roundcube requiere una versión de PHP más reciente.

Por defecto, Roundcube podría ejecutarse en una versión antigua de PHP, lo que puede generar problemas como:

• Incompatibilidad con funciones modernas de PHP.
• Errores en la ejecución debido a versiones obsoletas.
• Problemas de rendimiento.

Ejemplo de prueba:

• Dominio de prueba: mipoderosaempresa.com
• Usuario en HestiaCP: mipoderosaempresa

Todos los ejemplos de código usarán esta información, así que reemplázala con tus propios datos si estás aplicando esto en tu servidor.

2. ¿Cómo funciona la interacción entre Nginx, Apache y PHP-FPM?

Cuando un usuario accede a webmail.mipoderosaempresa.com, el servidor sigue estos pasos:

1. Nginx recibe la solicitud como proxy inverso y decide si debe manejar el tráfico o pasarlo a Apache.
2. Apache recibe la solicitud desde Nginx y determina qué archivos deben procesarse.
3. Si la solicitud es para un archivo .php, Apache usa **FastCGI** para enviarlo a PHP-FPM.
4. PHP-FPM procesa el archivo PHP utilizando la versión de PHP configurada.
5. PHP-FPM devuelve el contenido procesado a Apache.
6. Apache devuelve el resultado a Nginx.
7. Nginx entrega el contenido al usuario final.

HestiaCP usa esta configuración porque permite que Nginx maneje archivos estáticos (CSS, imágenes, JS) y Apache maneje PHP, mejorando el rendimiento.

3. ¿Por qué HestiaCP usa una versión incorrecta de PHP?

HestiaCP no define explícitamente qué versión de PHP usar para Roundcube. Esto significa que, por defecto, podría ejecutar PHP 7.2 o una versión anterior.

La solución es modificar las plantillas de configuración de Apache para forzar el uso de PHP 8.2.

4. ¿Por qué usamos php8.2-fpm.dummy.sock?

Cuando instalamos varias versiones de PHP en HestiaCP, cada usuario tiene su propio socket PHP-FPM en /run/php/. Sin embargo, Roundcube no pertenece a ningún usuario específico, sino que es gestionado por HestiaCP de forma centralizada.

Los sockets específicos de usuario se llaman, por ejemplo:

/run/php/php7.4-fpm.sock
/run/php/php8.2-fpm.sock
/run/php/php8.2-fpm.dummy.sock
/run/php/php8.2-fpm-mipoderosaempresa.com.sock

Pero Roundcube no es un dominio individual, por lo que no tiene un socket propio. Para estos casos, HestiaCP utiliza el socket “dummy” que actúa como un enlace genérico a la versión por defecto de PHP.

Por eso usamos:

proxy:unix:/run/php/php8.2-fpm.dummy.sock|fcgi://localhost

Este socket garantiza que cualquier servicio centralizado (como Roundcube) pueda ejecutar PHP con la versión correcta sin depender de la configuración de un usuario específico.

5. Modificar las plantillas de configuración

5.1 Ubicación de las plantillas en HestiaCP

Las configuraciones de Apache para el webmail se encuentran en:

/usr/local/hestia/data/templates/mail/apache2/

Existen dos archivos clave:

• default.tpl: Configuración sin SSL.
• default.stpl: Configuración con SSL.

5.2 Importante: Las plantillas originales de HestiaCP no incluyen la configuración de PHP-FPM

Por defecto, estos archivos **no incluyen ninguna referencia a PHP-FPM ni a la versión de PHP utilizada**. Esto significa que debemos **añadir manualmente** la configuración al final del archivo.

5.3 Modificar default.tpl (sin SSL)

nano /usr/local/hestia/data/templates/mail/apache2/default.tpl

Desplázate hasta el final del archivo y **añade** la siguiente configuración:

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/php8.2-fpm.dummy.sock|fcgi://localhost"
</FilesMatch>

5.4 Modificar default.stpl (con SSL)

nano /usr/local/hestia/data/templates/mail/apache2/default.stpl

Al igual que en el archivo anterior, **añade** la siguiente configuración al final del archivo:

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/php8.2-fpm.dummy.sock|fcgi://localhost"
</FilesMatch>

6. Aplicar cambios en HestiaCP

6.1. Regenerar Mail Domain

Si solo quieres reconstruir toda la configuracion solo para un dominio puede usar el siguiente codigo, que basicamente “reconstruye” todo con base a la plantilla

/usr/local/hestia/bin/v-rebuild-mail-domain mipoderosaempresa mipoderosaempresa.com yes

6.2 Eliminar y volver a crear la configuración de webmail

Si quiere “eliminar” y luego “volver” a crear toda la configuracion con las nuevas especificaciones de la plantilla puedes usar estos 2 codigos:

/usr/local/hestia/bin/v-delete-mail-domain-webmail mipoderosaempresa mipoderosaempresa.com no yes
/usr/local/hestia/bin/v-add-mail-domain-webmail mipoderosaempresa mipoderosaempresa.com roundcube yes

6.3 Reconstruir la configuración para todos los usuarios

Si quieres “eliminar” y luego “volver” a crear toda la configuracion con las nuevas especificaciones de la plantilla para todos los usuarios y dominios, debes crear un bash. Aqui tienes un ejemplo con el adicional que verifica si ya usa “roundcube”, si no usa, lo regenera todo.

Primero creamos el archivo:

nano rebuild_webmail_roundcube.sh

Luego añadimos todo el codigo en el archivo:

#!/bin/bash
users=$(/usr/local/hestia/bin/v-list-users | tail -n +3 | grep -v -- '---' | awk '{print $1}')

for u in $users; do
    domains=$(/usr/local/hestia/bin/v-list-mail-domains $u plain | cut -f1)
    for d in $domains; do
        current_webmail=$(/usr/local/hestia/bin/v-list-mail-domain $u $d | grep -w '^WEBMAIL' | awk '{print $2}')
        if [ "$current_webmail" = "roundcube" ]; then
            echo "$d ya usa roundcube. Saltando..."
            continue
        fi
        echo "Eliminando y agregando webmail roundcube para: $d"
        /usr/local/hestia/bin/v-delete-mail-domain-webmail $u $d no yes
        /usr/local/hestia/bin/v-add-mail-domain-webmail $u $d roundcube yes
    done
done

Dale permisos de ejecución:

chmod +x rebuild_webmail_roundcube.sh

Luego ejecutas el bash

./rebuild_webmail_roundcube.sh

• Para cada usuario, se leen sus dominios de correo.
• Si el dominio no estaba en Roundcube, se elimina el webmail y se agrega con Roundcube, forzando el uso de tus plantillas default.tpl/default.stpl.

Al final, todos los dominios de todos los usuarios estarán configurados con Roundcube y, gracias a tu modificación de la plantilla, Roundcube usará PHP 8.2 (socket dummy) para procesar scripts PHP.

7. Archivos Clave y Qué Hace Cada Uno

1. /usr/local/hestia/data/templates/mail/apache2/default.tpl
   • Función: Generar el VirtualHost de webmail para HTTP (puerto 8080) con Roundcube.
   • Lo que hicimos: Insertar <FilesMatch> que apunta a php8.2-fpm.dummy.sock.
2. /usr/local/hestia/data/templates/mail/apache2/default.stpl
   • Función: Igual que default.tpl pero para HTTPS (puerto 8443).
   • Lo que hicimos: Repetimos <FilesMatch \.php$> para forzar PHP 8.2 en conexiones SSL.
3. /usr/local/hestia/bin/v-rebuild-mail-domain
   • Función: Reconstruir la configuración de correo (incluido webmail.<dominio>) para un dominio y usuario concretos.
   • Uso: v-rebuild-mail-domain mipoderosaempresa mipoderosaempresa.com yes.
4. /usr/local/hestia/bin/v-delete-mail-domain-webmail y v-add-mail-domain-webmail
   • Función: Quitar o agregar el subdominio webmail (por defecto con Roundcube).
   • Uso en el script masivo: Eliminar y regenerar webmail “roundcube” si el dominio estaba usando otra cosa.
5. /var/lib/roundcube/
   • Función: Directorio donde vive el código de Roundcube.
   • Uso: Creamos testinfo.php para confirmar la versión de PHP en webmail.midominio.com/testinfo.php.
6. El Script de Reconstrucción Masiva
   • Ubicación/Nombre: rebuild_webmail_roundcube.sh (ejemplo).
   • Función: Iterar sobre todos los usuarios y sus dominios, forzando Roundcube si no estaba habilitado. Al hacerlo, se aplican las plantillas con <FilesMatch> que integraste.
7. Por qué php8.2-fpm.dummy.sock
   • Función: Socket genérico que HestiaCP crea para la versión de PHP (8.2) cuando no existe un pool dedicado a un dominio concreto.
   • Ventaja: No requiere crear un pool específico como “roundcube.conf”; Roundcube usará la versión 8.2 a través de este socket “dummy” global.

8. Reconstruir la configuración sin eliminar

Usando la misma logica de crear un bash, puedes hacer uno solo para “reconstruir” sin necesidad de eliminar, en este caso este seria el codigo.

#!/bin/bash
users=$(/usr/local/hestia/bin/v-list-users | awk '{print $1}' | tail -n +3)

for u in $users; do
    domains=$(/usr/local/hestia/bin/v-list-mail-domains $u plain | cut -f1)
    for d in $domains; do
        /usr/local/hestia/bin/v-rebuild-mail-domain $u $d yes
    done
done

9. Script Bash Interactivo

Lo que mas recomiendo en mi experiencia es hacer un bash que contengan ambos codigos y poder utilizarlo cuando lo necesitemos, conopciones multiples, este seria un gran ejemplo:

#!/bin/bash

# Función para regenerar la configuración sin eliminar
rebuild_all_webmail() {
    echo "⏳ Iniciando regeneración de configuración de webmail para todos los dominios..."
    users=$(/usr/local/hestia/bin/v-list-users | tail -n +3 | grep -v -- '---' | awk '{print $1}')

    for u in $users; do
        domains=$(/usr/local/hestia/bin/v-list-mail-domains $u plain | cut -f1)

        for d in $domains; do
            echo "🔄 Regenerando configuración para: $d (usuario: $u)"
            /usr/local/hestia/bin/v-rebuild-mail-domain $u $d yes
        done
    done
    echo "✅ Regeneración completada."
}

# Función para eliminar y volver a agregar webmail Roundcube
reset_all_webmail() {
    echo "⏳ Eliminando y volviendo a agregar webmail Roundcube para todos los dominios..."
    users=$(/usr/local/hestia/bin/v-list-users | tail -n +3 | grep -v -- '---' | awk '{print $1}')

    for u in $users; do
        domains=$(/usr/local/hestia/bin/v-list-mail-domains $u plain | cut -f1)

        for d in $domains; do
            current_webmail=$(/usr/local/hestia/bin/v-list-mail-domain $u $d | grep -w '^WEBMAIL' | awk '{print $2}')

            if [ "$current_webmail" = "roundcube" ]; then
                echo "✅ $d ya usa Roundcube. Saltando..."
                continue
            fi

            echo "🛑 Eliminando y agregando webmail Roundcube para: $d (usuario: $u)"
            /usr/local/hestia/bin/v-delete-mail-domain-webmail $u $d no yes
            /usr/local/hestia/bin/v-add-mail-domain-webmail $u $d roundcube yes
        done
    done
    echo "✅ Webmail reconstruido correctamente."
}

# Menú interactivo
echo "📌 Selecciona una opción:"
echo "1) 🔄 Regenerar la configuración de webmail para todos los dominios (sin eliminar)."
echo "2) 🛑 Eliminar y volver a crear la configuración del webmail (Roundcube)."
echo "3) ❌ Salir."

read -p "Introduce el número de la opción deseada: " option

case $option in
    1) rebuild_all_webmail ;;
    2) reset_all_webmail ;;
    3) echo "🚪 Saliendo..." && exit 0 ;;
    *) echo "❌ Opción inválida. Ejecuta el script nuevamente." && exit 1 ;;
esac

Recuerda que siempre debes darle permisos de ejecucion:

chmod +x rebuild_webmail_roundcube.sh

Luego ejecutar el bash

./rebuild_webmail_roundcube.sh