Passer au contenu principal
Cette page explique le modèle de configuration d’OxiMail : d’où viennent les paramètres, ce qui doit figurer dans le fichier par rapport à ce qui peut changer en cours d’exécution, et comment un changement à l’exécution prend effet. C’est la page centrale vers laquelle pointent les sections de configuration de chaque fonctionnalité. Pour la liste exhaustive des clés d’un domaine précis, consultez l’exemple de configuration et la page d’administration correspondante.

​
Le modèle : base TOML, surcharges en base

OxiMail ne stocke pas toute sa configuration en base de données. Il lit un fichier TOML au démarrage comme base, puis applique par-dessus des surcharges optionnelles par organisation stockées en base, pour le réglage en cours d’exécution sans redémarrage. C’est l’ADR-007. L’ordre de recherche d’un paramètre est le suivant :
  1. La surcharge en base (si elle existe pour cette clé) l’emporte.
  2. Le fichier TOML sert de repli, et reste la source de vérité pour tout le reste.
La raison est l’exploitabilité. Un fichier TOML peut se lire avec cat, se versionner dans git, se copier avec scp et s’éditer en SSH. Une configuration entièrement en base ne le permet pas, et elle crée un problème de poule et d’oeuf : la base doit être configurée avant de pouvoir lire la configuration qui configure la base. OxiMail garde le fichier comme base de référence et n’utilise la base que pour les surcharges à l’exécution.
Le fichier TOML reste toujours la source de vérité pour le démarrage et la reprise après incident. Si vous perdez les surcharges en base, le serveur démarre quand même à partir du fichier. L’inverse n’est pas vrai.

​
Paramètres de démarrage et paramètres d’exécution

Tous les paramètres ne peuvent pas être une surcharge en base. Tout ce dont OxiMail a besoin avant l’ouverture de la base doit venir du fichier. C’est la règle de la poule et de l’oeuf :
Ne jamais mettre la configuration de démarrage uniquement en base.
Paramètres de démarrage (TOML uniquement), nécessaires avant d’ouvrir le stockage et de se mettre à l’écoute, ou pour le faire :
  • [storage] sqlite_path, blob_path, search_path, encrypted : où et comment vit la base elle-même.
  • [server] bind, http_bind, admin_bind, hostname, base_url : les sockets d’écoute et l’identité du serveur.
  • [smtp] bind, submission_bind, smtps_bind, hostname : les sockets d’écoute SMTP.
  • [auth] default_tenant.
Ces paramètres décrivent la façon dont le processus démarre. En faire une surcharge en base n’aurait aucun sens, car le serveur ne peut pas lire la base tant qu’ils n’ont pas déjà été appliqués. Paramètres d’exécution (surchargables), ce que vous pouvez vouloir ajuster sur un serveur en marche : plafonds de débit, seuils fail2ban, options anti-spam et autres réglages d’exploitation. Ils ont une valeur par défaut sensée dans le TOML et peuvent être surchargés à l’exécution via l’API d’administration (voir Définir une surcharge à l’exécution).
Quelques paramètres sont volontairement réglables au redémarrage seulement, même s’ils ressemblent à des réglages d’exécution. Par exemple, la clé secrète SRS ([srs] secret_key) est lue une fois au démarrage et ne se recharge pas à chaud, donc sa rotation impose un redémarrage. Quand une section est réglable au redémarrage seulement, sa page d’administration le précise.

​
Rechargement à chaud

Les surcharges à l’exécution sont conçues pour prendre effet sans redémarrer le processus. Le mécanisme est ArcSwap, un échange atomique de pointeur sans verrou (ADR-016) : le composant conserve un Arc vers son état courant, et un rechargement échange atomiquement un nouvel Arc. Les lecteurs ne sont jamais bloqués. Les requêtes en cours se terminent sur l’ancienne valeur, et toute lecture suivante voit la nouvelle. Ce mécanisme sert aux composants rechargeables à chaud : les certificats TLS (pour qu’un renouvellement ACME s’applique sans redémarrage), la liste de blocage anti-spam, les surcharges de configuration à l’exécution et les scripts Sieve compilés. Comme les lectures ne sont jamais verrouillées, le rechargement à chaud n’a aucun coût mesurable sur le chemin des requêtes : un renouvellement ou une surcharge est un simple échange de pointeur, et les rechargements sont rares.

​
Définir une surcharge à l’exécution

Les surcharges à l’exécution sont stockées par organisation (un tenant au sens du stockage) et définies via l’API REST d’administration. Voir l’API d’administration pour l’authentification (chaque point d’accès d’administration exige le jeton porteur d’administration configuré sous [admin] token). Pour définir une ou plusieurs surcharges, envoyez PUT /admin/v1/config avec un corps JSON dont l’objet overrides associe chaque clé de configuration à sa nouvelle valeur : 
curl -X PUT https://mail.example.com/admin/v1/config \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"overrides": {"limits.max_message_size": "100MB"}}'
Chaque paire clé/valeur est écrite dans le magasin de surcharges du tenant par défaut. Les valeurs conservent leur type JSON (un nombre reste un nombre, une chaîne reste une chaîne).
Lister les surcharges en cours via GET /admin/v1/config n’est pas implémenté en v0.30.0. Le point d’accès renvoie une indication d’usage, pas un export. Pour voir ce qui est appliqué, consultez le fichier TOML et les surcharges que vous avez définies.

​
Le fichier de configuration et sa structure

Le serveur lit /etc/oximail/oximail.toml par défaut. Les sous-commandes du CLI et la commande serve acceptent --config <chemin> pour pointer ailleurs. L’assistant de configuration écrit ce fichier pour vous au premier démarrage ; cette page sert à l’ajuster ensuite. Un fichier annoté représentatif ressemble à ceci. Il n’est pas exhaustif. Il montre la structure et les sections les plus courantes. Voir les pages d’administration de chaque fonctionnalité pour l’ensemble des clés de chaque domaine. 
# /etc/oximail/oximail.toml

[server]
hostname = "mail.example.com"          # identité du serveur
bind = "0.0.0.0:443"                    # socket HTTPS / JMAP
base_url = "https://mail.example.com"  # utilisé dans les URL de session JMAP
http_bind = "0.0.0.0:80"               # défis ACME + redirection HTTPS
# admin_bind = "127.0.0.1:9000"        # port d'administration séparé (optionnel)
trusted_proxies = ["127.0.0.1"]        # lire X-Forwarded-For depuis ces IP
allowed_origins = []                   # liste CORS (vide = tout refuser)

[storage]
sqlite_path = "/var/lib/oximail/data.db"
blob_path = "/var/lib/oximail/blobs"
encrypted = true                       # SQLCipher activé par défaut

[auth]
default_tenant = "default"

[mode]
role = "primary"                       # "primary" ou "backup"

[smtp]
bind = "0.0.0.0:25"                    # entrant (réception)
submission_bind = "0.0.0.0:587"        # soumission (envoi, STARTTLS)
smtps_bind = "0.0.0.0:465"             # soumission en TLS implicite
hostname = "mail.example.com"
dane_enabled = true                    # DANE sortant (RFC 7672)

# Une clé de signature par domaine d'envoi (forme tableau de la v0.30).
[[smtp.dkim_keys]]
domain = "example.com"
selector = "default"
key_path = "/etc/oximail/dkim/example.com.default.key"

[tls]
acme_enabled = true                    # Let's Encrypt ; désactivé derrière un proxy
acme_email = "admin@example.com"

[security]
fail2ban_max_attempts = 5
fail2ban_ban_minutes = 60
trusted_ips = ["10.0.0.0/8"]           # contourne le débit ET fail2ban

[rate_limit]
http_per_ip_per_minute = 100
smtp_outbound_per_hour = 50

[spam]
dnsbl_servers = []

[greylisting]
enabled = false

[legacy]
enabled = true                         # passerelles IMAP / CalDAV / CardDAV

​
Les vraies sections de premier niveau

Les sections qui existent en v0.30.0 sont : [server], [storage], [auth], [mode], [smtp] (avec les tableaux [[smtp.dkim_keys]] et [[smtp.transport_maps]]), [tls], [spam], [greylisting], [security], [rate_limit] (avec la table [rate_limit.destination_domains]), [logging], [admin], [telemetry], [legacy], [mta_sts], [dns], [sieve], [network], [distribution_groups], [scheduler], [srs], [metrics] et [push]. Les pages de chaque fonctionnalité documentent les clés de chacune :

​
Valider une configuration avant le déploiement

OxiMail échoue de façon visible sur une mauvaise configuration : plutôt que de démarrer dans un état à moitié cassé, il refuse de démarrer et indique ce qui ne va pas. Vous pouvez exécuter les mêmes validateurs à l’avance, sans démarrer le serveur : 
oximail check-config --config /etc/oximail/oximail.toml
Cela détecte par exemple un serveur primaire sans clé de signature DKIM, dane_enabled activé sans fournisseur DNS, et des clés DKIM antérieures à la v0.30 encore présentes dans le fichier. Voir la Référence du CLI pour la liste complète des commandes et Exploitation pour le travail au quotidien.

​
Étapes suivantes