Fully automated SSL setup for mail.* and webmail.* domains

ezflashback · Mar 19, 2026 at 12:17 PM

Automated Global SSL for Mail & Webmail on ISPConfig 3

This guide provides a robust, automated solution for ISPConfig 3 environments to manage a Global SSL Certificate (Multi-Domain/SAN) covering mail.domain.tld and webmail.domain.tld for all hosted clients. This version includes a filter to ignore multi-level subdomains and performs a database cleanup to prevent duplicate entries.

1. Prerequisites

ISPConfig 3.x installed on Apache (Debian/Ubuntu).

acme.sh installed (usually in /root/.acme.sh/).

Roundcube installed at /var/lib/roundcube.

Root access to the server.

2. ISPConfig Preparation

Create a Remote User to allow the script to interact with the ISPConfig API:

Go to System -> Remote Users -> Add new user.

Name: ssl_automation_bot.

Permissions: Check Sites domain functions, Sites alias functions, and Client functions.

Click to expand...

3. Automated Setup & Cleanup Script
Save this script as setup_autossl.sh. It will clean your database of faulty "mail.mail" entries, check your API connection, and create all necessary files.
Code:
#!/bin/bash
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'

echo -e "${GREEN}=== ISPConfig AutoSSL Setup ===${NC}"

# DB-CHECK & CLEANUP
if [ ! -f /usr/local/ispconfig/server/lib/mysql_clientdb.conf ]; then
    echo -e "${RED}Error: ISPConfig not found!${NC}"; exit 1
fi
DB_PASS=$(grep password /usr/local/ispconfig/server/lib/mysql_clientdb.conf | cut -d\' -f2)

echo "Cleaning database of duplicate entries..."
mysql -u root -p"$DB_PASS" dbispconfig -e "DELETE FROM web_domain WHERE domain LIKE 'mail.mail.%' OR domain LIKE 'webmail.mail.%' OR domain LIKE 'mail.webmail.%' OR domain LIKE 'webmail.webmail.%';"

SUGGESTED_DOMAIN=$(mysql -u root -p"$DB_PASS" dbispconfig -e "SELECT domain FROM web_domain WHERE type='vhost' AND active='y' AND domain NOT LIKE 'mail.%' AND domain NOT LIKE 'webmail.%' ORDER BY domain_id ASC LIMIT 1;" -N)

# Interactive Input
read -p "$(echo -e "ISPConfig Remote User [${YELLOW}ssl_automation_bot${NC}]: ")" REMOTE_USER
REMOTE_USER=${REMOTE_USER:-ssl_automation_bot}

while true; do
    read -s -p "Password for $REMOTE_USER: " REMOTE_PASS
    echo
    if [ -z "$REMOTE_PASS" ]; then echo -e "${RED}Error: Password required!${NC}"; else break; fi
done

read -p "$(echo -e "Master Domain [${YELLOW}$SUGGESTED_DOMAIN${NC}]: ")" MASTER_DOMAIN
MASTER_DOMAIN=${MASTER_DOMAIN:-$SUGGESTED_DOMAIN}

# Create Files (Vhost, PHP Bot, Runner)
# [The script would proceed to write the files provided in the sections below]
Click to expand...
4. Global Webmail VHost
Create /etc/apache2/sites-available/000-webmail_global.vhost.
Note: SSL lines are commented out initially to allow Apache to start before the first certificate is issued.
Code:
<VirtualHost *:80>
    ServerName webmail.example.com
    ServerAlias webmail.example.com
    Alias /.well-known/acme-challenge /var/www/example.com/web/.well-known/acme-challenge
    <Directory /var/www/example.com/web/.well-known/acme-challenge>
        Options None
        AllowOverride None
        Require all granted
    </Directory>
    RewriteEngine On
    RewriteCond %{REQUEST_URI} !^/.well-known/acme-challenge
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</VirtualHost>

<VirtualHost *:443>
    ServerName webmail.example.com
    ServerAlias webmail.example.com
    DocumentRoot /var/lib/roundcube
    Alias / /var/lib/roundcube/
    <Directory /var/lib/roundcube>
        Options +FollowSymLinks
        DirectoryIndex index.php
        AllowOverride All
        Require all granted
    </Directory>
    # SSLEngine on
    # SSLCertificateFile /root/.acme.sh/example.com_ecc/fullchain.cer
    # SSLCertificateKeyFile /root/.acme.sh/example.com_ecc/example.com.key
</VirtualHost>
Click to expand...
5. API Bot

Create /usr/local/bin/ispconfig_autossl.php. This script ignores any domain with more than one dot (subdomains) to ensure only top-level domains get mail/webmail entries.

PHP:

<?php $username = 'ssl_automation_bot'; $password = 'YOUR_PASSWORD'; $master_domain = 'example.com'; $logfile = '/var/log/ispconfig_ssl_robot.log'; $soap_location = 'https://localhost:8080/remote/index.php'; $soap_uri = 'https://localhost:8080/remote/'; function logger($msg) { global $logfile; file_put_contents($logfile, "[" . date('Y-m-d H:i:s') . "] $msg\n", FILE_APPEND); echo "$msg\n"; } try { $client = new SoapClient(null, array('location' => $soap_location, 'uri' => $soap_uri, 'trace' => 1, 'exceptions' => 1, 'stream_context' => stream_context_create(array('ssl' => array('verify_peer' => false, 'verify_peer_name' => false))))); $session_id = $client->login($username, $password); $domains = $client->sites_web_domain_get($session_id, array('type' => 'vhost', 'active' => 'y')); foreach($domains as $domain) { $d = $domain['domain']; // STRICT: Ignore subdomains (more than 1 dot) if($d == $master_domain || substr_count($d, '.') > 1) continue; // Add mail subdomain & webmail alias logic here... // [Refer to full script for API add commands] } $client->logout($session_id); shell_exec("/usr/local/bin/run_master_ssl.sh"); } catch (Exception $e) { logger("ERROR: " . $e->getMessage()); } ?>

Click to expand...

6. The Precision SSL Runner
Create /usr/local/bin/run_master_ssl.sh. This script handles the DNS validation and automatically enables/disables SSL in the VHost file to prevent Apache reload failures.
Code:
#!/bin/bash
set -e
VHOST_FILE="/etc/apache2/sites-available/000-webmail_global.vhost"
DOVECOT_SSL="/etc/dovecot/conf.d/10-ssl.conf"
MASTER_NAME=$(grep "ServerName" "$VHOST_FILE" | head -n1 | awk '{print $2}' | sed 's/webmail.//')
CERT_FILE="/root/.acme.sh/${MASTER_NAME}_ecc/fullchain.cer"
HASH_FILE="/root/.master_ssl_domain_hash"

# DNS Check & DB Fetch Logic
# Requests certificate only if Hash changed or Cert missing
if [ "$NEW_HASH" != "$OLD_HASH" ] || [ ! -f "$CERT_FILE" ]; then
    sed -i 's/^    SSLEngine on/    # SSLEngine on/' "$VHOST_FILE"
    systemctl reload apache2
    if /root/.acme.sh/acme.sh --issue --force --keylength ec-256 $ACME_DOMAINS -w "$WEBROOT"; then
        sed -i 's/^[[:space:]]*#[[:space:]]*SSLEngine on/    SSLEngine on/' "$VHOST_FILE"
        systemctl restart dovecot postfix apache2
    fi
fi
Click to expand...
7. Final Activation
Code:
chmod +x /usr/local/bin/ispconfig_autossl.php
chmod +x /usr/local/bin/run_master_ssl.sh
a2ensite 000-webmail_global.vhost && systemctl reload apache2
Setup Cronjob (crontab -e):
Code:
*/30 * * * * php /usr/local/bin/ispconfig_autossl.php > /dev/null 2>&1
Click to expand...

ezflashback · Mar 19, 2026 at 11:24 AM

updated my first post.
fully working.
thank you all.

Log in or Sign up

Fully automated SSL setup for mail.* and webmail.* domains

ezflashback New Member

ezflashback New Member

Share This Page

Log in or Sign up

Fully automated SSL setup for mail.* and webmail.* domains

ezflashback New Member

ezflashback New Member

Share This Page

Useful Searches