Info:: apsi.net: GUIDE INTEGRATION MYSQL

De wiki_pcwiki2
Aller à la navigationAller à la recherche

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

  1. Introduction
  2. Architecture
  3. Configuration Postfix
  4. Configuration Dovecot
  5. Tests et Validation
  6. Migration depuis les Fichiers Plats
  7. Dépannage
  8. 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



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)