Info:: apsi.net: GUIDE INTEGRATION MYSQL
KEYWORDS: MAIL, SERVER, APSI.NET, OVH1, MAIL.APSI.NET, OVH2, BACKUP.APSI.NET
Le 04/01/2026:
Guide d’Intégration PostfixAdmin avec Postfix et Dovecot
Date: 03 Janvier 2026 Serveur: ovh1 (mail.apsi.net) Objectif: Intégrer Postfix et Dovecot avec la base MySQL de PostfixAdmin
Table des Matières
- Introduction
- Architecture
- Configuration Postfix
- Configuration Dovecot
- Tests et Validation
- Migration depuis les Fichiers Plats
- Dépannage
- Références
Introduction
Ce guide explique comment configurer Postfix et Dovecot pour utiliser la base de données MySQL de PostfixAdmin au lieu des fichiers plats (/etc/postfix/virtual, /etc/dovecot/users, etc.).
Avantages de l’Intégration MySQL
- ✅ Gestion centralisée : Tous les comptes dans une seule base de données
- ✅ Interface web : Modification des comptes via PostfixAdmin
- ✅ Pas de reload : Pas besoin de recharger Postfix/Dovecot après chaque modification
- ✅ Multi-domaines : Gestion simplifiée de plusieurs domaines
- ✅ Scalabilité : Facilite l’ajout de nouveaux serveurs mail
Pré-requis
Avant de commencer, assurez-vous que :
- ✅ PostfixAdmin est installé et fonctionnel
- ✅ Les domaines et comptes sont importés dans la base PostfixAdmin
- ✅ Postfix et Dovecot fonctionnent actuellement (avec fichiers plats)
- ✅ Une sauvegarde complète a été effectuée
Architecture
Schéma de Fonctionnement
┌─────────────────┐
│ Email Entrant │
└────────┬────────┘
│
▼
┌─────────────────────────────────────┐
│ POSTFIX │
│ 1. Vérifie le domaine (MySQL) │
│ 2. Vérifie la mailbox (MySQL) │
│ 3. Vérifie les alias (MySQL) │
└────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ DOVECOT LMTP │
│ 4. Authentification (MySQL) │
│ 5. Delivery dans Maildir │
└─────────────────────────────────────┘
Tables MySQL Utilisées
| Table | Usage Postfix | Usage Dovecot |
|---|---|---|
domain
|
Vérifier si le domaine existe | - |
mailbox
|
Vérifier si la boîte existe, récupérer le maildir | Authentification, récupération du home/mail/uid/gid |
alias
|
Résoudre les alias et forwards | - |
Configuration Postfix
Étape 1 : Créer les Fichiers de Lookup MySQL
Postfix a besoin de 3 fichiers pour interroger MySQL : 1. virtual-mailbox-domains : Liste des domaines gérés 2. virtual-mailbox-maps : Liste des mailboxes 3. virtual-alias-maps : Liste des alias
1.1 Domaines Virtuels
Fichier : /etc/postfix/mysql-virtual-mailbox-domains.cf
cat > /etc/postfix/mysql-virtual-mailbox-domains.cf <<'EOF'
# Configuration MySQL pour les domaines virtuels Postfix
# Fichier: /etc/postfix/mysql-virtual-mailbox-domains.cf
user = postfixadmin
password = VotreMotDePasseSecurise
hosts = localhost
dbname = postfixadmin
# Requête pour vérifier si le domaine existe
# Retourne le nom du domaine si actif
query = SELECT domain FROM domain WHERE domain='%s' AND active='1'
EOF
1.2 Boîtes Email
Fichier : /etc/postfix/mysql-virtual-mailbox-maps.cf
cat > /etc/postfix/mysql-virtual-mailbox-maps.cf <<'EOF'
# Configuration MySQL pour les boîtes email virtuelles Postfix
# Fichier: /etc/postfix/mysql-virtual-mailbox-maps.cf
user = postfixadmin
password = VotreMotDePasseSecurise
hosts = localhost
dbname = postfixadmin
# Requête pour récupérer le chemin maildir d'une boîte email
# Retourne le maildir pour indiquer que la boîte existe
query = SELECT maildir FROM mailbox WHERE username='%s' AND active='1'
EOF
1.3 Alias Email
Fichier : /etc/postfix/mysql-virtual-alias-maps.cf
cat > /etc/postfix/mysql-virtual-alias-maps.cf <<'EOF'
# Configuration MySQL pour les alias virtuels Postfix
# Fichier: /etc/postfix/mysql-virtual-alias-maps.cf
user = postfixadmin
password = VotreMotDePasseSecurise
hosts = localhost
dbname = postfixadmin
# Requête pour récupérer la destination d'un alias
# Retourne la destination de l'alias (ou la mailbox elle-même)
query = SELECT goto FROM alias WHERE address='%s' AND active='1'
EOF
1.4 Permissions des Fichiers
⚠️ Important : Les fichiers contiennent le mot de passe MySQL !
chown root:postfix /etc/postfix/mysql-*.cf
chmod 640 /etc/postfix/mysql-*.cf
Vérification :
ls -la /etc/postfix/mysql-*.cf
Résultat attendu :
-rw-r----- 1 root postfix ... mysql-virtual-alias-maps.cf -rw-r----- 1 root postfix ... mysql-virtual-mailbox-domains.cf -rw-r----- 1 root postfix ... mysql-virtual-mailbox-maps.cf
Étape 2 : Tester les Requêtes MySQL
Avant d’intégrer dans Postfix, testez les requêtes :
# Tester les domaines
postmap -q "apsi.net" mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf
# Tester une mailbox
postmap -q "pchevalier@apsi.net" mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
# Tester un alias
postmap -q "postmaster@apsi.net" mysql:/etc/postfix/mysql-virtual-alias-maps.cf
Résultats attendus :
apsi.net # Pour le domaine pchevalier.apsi.net/ # Pour la mailbox pchevalier@apsi.net # Pour l'alias
⚠️ Si vide : Vérifiez les identifiants MySQL et que les données sont bien dans la base.
Étape 3 : Sauvegarder la Configuration Actuelle
# Sauvegarde complète de la config Postfix
cp -a /etc/postfix /etc/postfix.backup-$(date +%Y%m%d-%H%M%S)
# Sauvegarde du fichier main.cf
cp /etc/postfix/main.cf /etc/postfix/main.cf.before-mysql
Étape 4 : Modifier la Configuration Postfix
4.1 Mettre à Jour main.cf
Option A : Remplacer complètement les anciens lookups
# Modifier les paramètres existants
postconf -e "virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf"
postconf -e "virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf"
postconf -e "virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf"
Option B : Conserver les fichiers plats en fallback (recommandé pour transition)
# Garder les deux : MySQL en priorité, puis fichiers plats
postconf -e "virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf, hash:/etc/postfix/virtual_domains"
postconf -e "virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf, hash:/etc/postfix/vmailbox"
postconf -e "virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf, hash:/etc/postfix/virtual"
Cette approche permet de garder les anciens fichiers en backup pendant la transition.
4.2 Vérifier la Configuration
# Vérifier la syntaxe
postfix check
# Voir la configuration effective
postconf virtual_mailbox_domains
postconf virtual_mailbox_maps
postconf virtual_alias_maps
Étape 5 : Recharger Postfix
# Recharger la configuration
postfix reload
# Vérifier le statut
systemctl status postfix
# Vérifier les logs
tail -f /var/log/mail.log
Configuration Dovecot
Étape 1 : Créer le Fichier SQL pour Dovecot
Fichier : /etc/dovecot/dovecot-sql-postfixadmin.conf.ext
cat > /etc/dovecot/dovecot-sql-postfixadmin.conf.ext <<'EOF'
# Dovecot SQL Configuration for PostfixAdmin
# File: /etc/dovecot/dovecot-sql-postfixadmin.conf.ext
# Database driver
driver = mysql
# Connection string
connect = host=localhost dbname=postfixadmin user=postfixadmin password=VotreMotDePasseSecurise
# Default password scheme (compatible avec PostfixAdmin)
default_pass_scheme = MD5-CRYPT
# Password query
# %u = full email address (user@domain.com)
# %n = user part (user)
# %d = domain part (domain.com)
# maildir in DB is "user.domain.tld/" so we build: /home/user.domain.tld/Maildir/
password_query = SELECT username as user, password, \
CONCAT('/home/', SUBSTRING_INDEX(maildir, '/', 1)) as userdb_home, \
CONCAT('/home/', SUBSTRING_INDEX(maildir, '/', 1), '/Maildir/') as userdb_mail, \
5000 as userdb_uid, 5000 as userdb_gid \
FROM mailbox WHERE username = '%u' AND active = '1'
# User query (pour LMTP/deliver)
user_query = SELECT CONCAT('/home/', SUBSTRING_INDEX(maildir, '/', 1)) as home, \
CONCAT('/home/', SUBSTRING_INDEX(maildir, '/', 1), '/Maildir/') as mail, \
5000 as uid, 5000 as gid \
FROM mailbox WHERE username = '%u' AND active = '1'
# Iterate query (pour doveadm)
iterate_query = SELECT username as user FROM mailbox WHERE active = '1'
EOF
Permissions :
chown root:root /etc/dovecot/dovecot-sql-postfixadmin.conf.ext
chmod 640 /etc/dovecot/dovecot-sql-postfixadmin.conf.ext
Étape 2 : Tester la Configuration SQL
# Tester l'authentification d'un utilisateur
doveadm auth test pchevalier@apsi.net
Entrez le mot de passe quand demandé.
Résultat attendu :
passdb: pchevalier@apsi.net auth succeeded extra fields: user=pchevalier@apsi.net userdb extra fields: home=/home/pchevalier.apsi.net mail=/home/pchevalier.apsi.net/Maildir/ uid=5000 gid=5000
Étape 3 : Sauvegarder la Configuration Dovecot
# Sauvegarde complète
cp -a /etc/dovecot /etc/dovecot.backup-$(date +%Y%m%d-%H%M%S)
# Sauvegarde des fichiers principaux
cp /etc/dovecot/conf.d/10-auth.conf /etc/dovecot/conf.d/10-auth.conf.before-mysql
cp /etc/dovecot/conf.d/auth-sql.conf.ext /etc/dovecot/conf.d/auth-sql.conf.ext.before-mysql
Étape 4 : Configurer Dovecot pour Utiliser SQL
4.1 Activer l’Authentification SQL
Fichier : /etc/dovecot/conf.d/10-auth.conf
nano /etc/dovecot/conf.d/10-auth.conf
Modifications :
# Désactiver l'authentification par fichiers plats #!include auth-passwdfile.conf.ext # Activer l'authentification SQL !include auth-sql.conf.ext
4.2 Configurer auth-sql.conf.ext
Fichier : /etc/dovecot/conf.d/auth-sql.conf.ext
nano /etc/dovecot/conf.d/auth-sql.conf.ext
Contenu :
# SQL authentication configuration
passdb {
driver = sql
args = /etc/dovecot/dovecot-sql-postfixadmin.conf.ext
}
userdb {
driver = sql
args = /etc/dovecot/dovecot-sql-postfixadmin.conf.ext
}
Étape 5 : Vérifier et Recharger Dovecot
# Vérifier la configuration
doveconf -n
# Tester la syntaxe
doveadm config cat
# Recharger Dovecot
systemctl reload dovecot
# Vérifier le statut
systemctl status dovecot
# Surveiller les logs
tail -f /var/log/mail.log
Tests et Validation
Test 1 : Envoi d’un Email de Test
# Envoyer un email de test
echo "Test email" | mail -s "Test MySQL Integration" pchevalier@apsi.net
# Vérifier les logs
tail -20 /var/log/mail.log
Logs attendus dans mail.log :
postfix/trivial-rewrite: ... virtual_alias_maps: mysql query success postfix/cleanup: ... message-id=<...> postfix/qmgr: ... from=<...>, size=... dovecot: lmtp: ... saved mail to INBOX postfix/lmtp: ... relay=mail.apsi.net[private/dovecot-lmtp], status=sent
Test 2 : Authentification IMAP
# Tester l'authentification avec doveadm
doveadm auth test pchevalier@apsi.net
Ou avec telnet :
openssl s_client -connect localhost:993 -quiet
a1 LOGIN pchevalier@apsi.net MotDePasse a2 LIST "" "*" a3 LOGOUT
Test 3 : Vérification des Alias
# Tester un alias avec postmap
postmap -q "postmaster@apsi.net" mysql:/etc/postfix/mysql-virtual-alias-maps.cf
# Envoyer un email à un alias
echo "Test alias" | mail -s "Test Alias" postmaster@apsi.net
Test 4 : Vérification des Répertoires Maildir
# Vérifier que le mail est bien livré
ls -la /home/pchevalier.apsi.net/Maildir/new/
# Compter les emails
find /home/*/Maildir/new/ -type f | wc -l
Migration depuis les Fichiers Plats
Étape 1 : Vérifier la Cohérence des Données
Assurez-vous que toutes les données des fichiers plats ont été importées dans MySQL.
Vérification domaines :
# Fichiers plats
cat /etc/postfix/virtual_domains
# MySQL
mysql -u postfixadmin -p postfixadmin -e "SELECT domain FROM domain WHERE active=1;"
Vérification mailboxes :
# Fichiers plats
cat /etc/postfix/vmailbox
# MySQL
mysql -u postfixadmin -p postfixadmin -e "SELECT username, maildir FROM mailbox WHERE active=1;"
Vérification alias :
# Fichiers plats
cat /etc/postfix/virtual
# MySQL
mysql -u postfixadmin -p postfixadmin -e "SELECT address, goto FROM alias WHERE active=1;"
Étape 2 : Période de Transition
Pendant la transition, conservez les deux systèmes en parallèle :
# Configuration hybride dans /etc/postfix/main.cf
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf, hash:/etc/postfix/virtual
Testez pendant plusieurs jours, puis retirez les fichiers plats.
Étape 3 : Désactivation des Fichiers Plats
Une fois que tout fonctionne correctement avec MySQL :
# Retirer les fichiers plats de la config
postconf -e "virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf"
postconf -e "virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf"
postconf -e "virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf"
# Recharger Postfix
postfix reload
Garder les fichiers plats en backup :
# Déplacer les anciens fichiers
mkdir -p /root/backups/postfix-flat-files
mv /etc/postfix/virtual /root/backups/postfix-flat-files/
mv /etc/postfix/vmailbox /root/backups/postfix-flat-files/
mv /etc/postfix/virtual_domains /root/backups/postfix-flat-files/
Dépannage
Problème 1 : postmap Retourne Vide
Symptôme :
postmap -q "apsi.net" mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf
# (rien)
Solutions :
A. Vérifier les Identifiants MySQL
mysql -u postfixadmin -p postfixadmin -e "SELECT domain FROM domain WHERE domain='apsi.net';"
Si échec : mot de passe incorrect dans le fichier .cf
B. Vérifier les Permissions
ls -la /etc/postfix/mysql-*.cf
Doivent être 640 avec owner root:postfix
C. Tester la Requête SQL Manuellement
mysql -u postfixadmin -p postfixadmin <<'EOF'
SELECT domain FROM domain WHERE domain='apsi.net' AND active='1';
EOF
Problème 2 : Dovecot Authentification Échoue
Symptôme :
doveadm auth test user@domain.com
# auth failed
Solutions :
A. Vérifier le Schéma de Mot de Passe
# Voir le hash actuel dans la base
mysql -u postfixadmin -p postfixadmin -e "SELECT username, password FROM mailbox WHERE username='user@domain.com';"
Hash MD5-CRYPT commence par : $1$...
B. Regénérer le Hash
# Avec doveadm
doveadm pw -s MD5-CRYPT -p "MotDePasse"
# Mettre à jour dans la base
mysql -u postfixadmin -p postfixadmin -e "UPDATE mailbox SET password='$1$...' WHERE username='user@domain.com';"
C. Vérifier les Logs Dovecot
tail -50 /var/log/mail.log | grep dovecot
Problème 3 : Email Non Livré (Bounce)
Symptôme :
User unknown in virtual mailbox table
Solutions :
A. Vérifier que la Mailbox Existe
postmap -q "user@domain.com" mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
B. Vérifier que l’Alias Existe
postmap -q "user@domain.com" mysql:/etc/postfix/mysql-virtual-alias-maps.cf
Important : Pour que la livraison fonctionne, il faut à la fois : - Une entrée dans mailbox - Une entrée dans alias (même si c’est juste user@domain.com → user@domain.com)
C. Ajouter l’Alias Manquant
INSERT INTO alias (address, goto, domain, created, modified, active)
VALUES ('user@domain.com', 'user@domain.com', 'domain.com', NOW(), NOW(), 1);
Problème 4 : Répertoire Maildir Introuvable
Symptôme :
Maildir /home/user.domain.com/Maildir doesn't exist
Solutions :
A. Créer les Répertoires Maildir
# Pour un utilisateur spécifique
mkdir -p /home/pchevalier.apsi.net/Maildir/{cur,new,tmp}
chown -R vmail:vmail /home/pchevalier.apsi.net
# Vérifier le UID/GID
ls -lan /home/pchevalier.apsi.net
B. Créer Automatiquement les Maildirs
Dans /etc/dovecot/conf.d/10-mail.conf :
mail_location = maildir:/home/%u/Maildir lda_mailbox_autocreate = yes lda_mailbox_autosubscribe = yes
Références
Fichiers de Configuration
| Fichier | Description |
|---|---|
/etc/postfix/mysql-virtual-mailbox-domains.cf
|
Lookup MySQL des domaines |
/etc/postfix/mysql-virtual-mailbox-maps.cf
|
Lookup MySQL des mailboxes |
/etc/postfix/mysql-virtual-alias-maps.cf
|
Lookup MySQL des alias |
/etc/dovecot/dovecot-sql-postfixadmin.conf.ext
|
Config SQL Dovecot |
/etc/dovecot/conf.d/10-auth.conf
|
Config auth Dovecot |
/etc/dovecot/conf.d/auth-sql.conf.ext
|
Config auth SQL Dovecot |
Commandes Utiles
# Tester lookup Postfix
postmap -q "domain.com" mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf
postmap -q "user@domain.com" mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
postmap -q "alias@domain.com" mysql:/etc/postfix/mysql-virtual-alias-maps.cf
# Tester auth Dovecot
doveadm auth test user@domain.com
# Recharger services
postfix reload
systemctl reload dovecot
# Surveiller logs
tail -f /var/log/mail.log
Documentation Officielle
- Postfix MySQL : http://www.postfix.org/MYSQL_README.html
- Dovecot SQL : https://doc.dovecot.org/configuration_manual/authentication/sql/
- PostfixAdmin : https://github.com/postfixadmin/postfixadmin
Checklist d’Intégration
Postfix
- ☐ Fichiers MySQL créés (domains, maps, alias)
- ☐ Permissions correctes (640, root:postfix)
- ☐ Tests postmap réussis
- ☐ Sauvegarde de main.cf effectuée
- ☐ Configuration main.cf mise à jour
- ☐ postfix check OK
- ☐ postfix reload effectué
- ☐ Test d’envoi réussi
Dovecot
- ☐ Fichier dovecot-sql-postfixadmin.conf.ext créé
- ☐ Permissions correctes (640, root:root)
- ☐ Test doveadm auth réussi
- ☐ Sauvegarde config Dovecot effectuée
- ☐ 10-auth.conf modifié
- ☐ auth-sql.conf.ext configuré
- ☐ doveconf -n OK
- ☐ systemctl reload dovecot OK
- ☐ Test authentification IMAP réussi
Validation
- ☐ Email de test envoyé et reçu
- ☐ Alias testés et fonctionnels
- ☐ Authentification IMAP/POP3 OK
- ☐ Logs sans erreurs
- ☐ Maildirs créés correctement
- ☐ Anciens fichiers plats sauvegardés
Guide créé le : 03 Janvier 2026 Auteur : Claude + PC Serveur : ovh1 (mail.apsi.net)