Une fois le binaire installé, oximail setup met le serveur
en route. L’assistant génère la configuration, la clé DKIM, la première organisation
et le compte administrateur, écrit une unité systemd, démarre le service et le
vérifie. L’assistant est le chemin recommandé pour un premier démarrage. Chaque
action peut aussi être lancée comme sous-commande distincte pour les
déploiements automatisés.
Cette page décrit ce que fait réellement l’assistant dans OxiMail v0.30.0,
étape par étape, dans l’ordre d’exécution. Lorsqu’une étape est conditionnelle
ou facultative, c’est précisé. Les étapes que l’assistant ne fait pas sont
listées à la fin.
Lancer l’assistant
Par défaut, l’assistant lit et écrit la configuration du serveur dans
/etc/oximail/oximail.toml. Il doit ouvrir des ports privilégiés et écrire dans
/etc/oximail et /var/lib/oximail. Lancez-le donc en tant que root.
Options :
| Option | Effet |
|---|
--config <chemin> | Chemin du TOML serveur. Par défaut /etc/oximail/oximail.toml. |
--config-file <chemin> | Mode non interactif à partir d’un fichier TOML de setup (sans question). |
--dry-run | Affiche ce qui serait fait et la configuration générée, sans rien écrire ni démarrer le service. |
/etc/oximail/oximail.toml existe déjà, l’assistant prévient et demande s’il
faut l’écraser. Si vous refusez, le setup est annulé et la configuration
existante est conservée.
Déroulé interactif (serveur principal)
L’assistant pose quelques questions, puis exécute les étapes ci-dessous dans
l’ordre.
Questions posées au départ
- Domaine de messagerie principal (par exemple
oximail.ch), c’est-à-dire
la partie domaine de vos adresses.
- Nom d’hôte du serveur de messagerie (par défaut
mail.<domaine>).
- Mode de déploiement :
Primary mail server (serveur principal) ou
Backup MX (MX secondaire). Le mode MX secondaire a son propre déroulé,
décrit plus bas.
- Topologie de déploiement :
Direct (OxiMail gère le TLS sur le port 443)
ou Behind reverse proxy (derrière un proxy inverse comme Caddy ou Nginx).
L’option proxy demande aussi le port HTTP local sur lequel OxiMail doit
écouter (par défaut 8080).
Étape : vérification des ports
L’assistant tente d’ouvrir chaque port requis en local et affiche OK ou FAIL
avec la raison (permission refusée, port déjà utilisé, ouverture impossible).
Les ports requis sont :
| Port | Usage |
|---|
| 25 | SMTP entrant (réception du courrier) |
| 80 | HTTP (challenges de certificat ACME) |
| 443 | HTTPS / JMAP |
| 465 | SMTPS (soumission chiffrée) |
| 587 | Soumission SMTP (envoi du courrier) |
| 993 | IMAPS (lecture du courrier) |
Étape : répertoires de données
L’assistant crée /var/lib/oximail, /var/lib/oximail/blobs, /etc/oximail,
/etc/oximail/dkim et /etc/oximail/tls. Il n’y a pas de /var/log/oximail :
les journaux partent sur la sortie standard et sont captés par journald.
Étape : DNS
L’assistant demande un jeton d’API Cloudflare (laissez vide pour configurer
le DNS à la main). Il détecte votre IP publique automatiquement (et vous demande
de la saisir si la détection échoue), puis contrôle les enregistrements DNS du
domaine et affiche un rapport réussite/échec.
- Avec un jeton, il peut créer les enregistrements manquants via l’API
Cloudflare : A, MX (priorité 10), SPF, DMARC, MTA-STS (TXT et CNAME), TLS-RPT,
les CNAME autoconfig et autodiscover, un enregistrement CAA qui limite
l’émission de certificats à Let’s Encrypt, et des enregistrements SRV pour
l’autoconfiguration des clients (
_autodiscover, _imaps, _submission,
_caldavs, _carddavs). Si un enregistrement MX en conflit existe, il
demande avant de le remplacer. Il revérifie ensuite le DNS.
- Sans jeton, il affiche les résultats du contrôle et vous indique de créer
les enregistrements vous-même.
Étape : DKIM
L’assistant génère une paire de clés DKIM RSA (sélecteur default) dans
/etc/oximail/dkim/<domaine>.default.key et affiche l’enregistrement DNS à
publier. Si un jeton Cloudflare a été fourni, il publie aussi l’enregistrement
TXT DKIM sur default._domainkey.<domaine> (en supprimant d’abord tout
enregistrement obsolète pour ce sélecteur). La clé publiée est au format SPKI
(v=DKIM1; k=rsa; p=...).
La publication DKIM via Cloudflare n’a lieu qu’à l’intérieur de l’assistant
complet. Les domaines ajoutés plus tard, ou les installations sans jeton
Cloudflare, n’ont aucun enregistrement TXT DKIM publié automatiquement.
Générez et publiez ces enregistrements à la main (voir la section
Génération de clé DKIM plus bas).
Étape : fichier de configuration
L’assistant demande l’adresse de l’administrateur (par défaut
admin@<domaine>) et, pour un déploiement direct, l’adresse ACME (Let’s
Encrypt) (par défaut l’adresse de l’administrateur). Derrière un proxy inverse,
ACME est ignoré car le proxy gère le TLS.
L’assistant écrit /etc/oximail/oximail.toml pour un serveur principal. Contenu
principal :
[server] : nom d’hôte, URL de base, adresses d’écoute (direct : 0.0.0.0:443
et 0.0.0.0:80 ; proxy : 127.0.0.1:<port> avec trusted_proxies).[storage] : SQLite dans /var/lib/oximail/data.db, blobs dans
/var/lib/oximail/blobs, encrypted = true.[auth] default_tenant = "default".[mode] role = "primary".[smtp] : ports d’écoute et un bloc [[smtp.dkim_keys]] pour le couple
domaine/sélecteur.[tls] : ACME activé (direct) ou désactivé (proxy).[legacy] : IMAP, CalDAV et CardDAV activés.[spam], [greylisting], [security] (fail2ban et IP de confiance),
[rate_limit], [network] contribute et [logging] (JSON vers journald).
Pour un déploiement derrière un proxy inverse, l’assistant affiche un extrait de
Caddyfile prêt à l’emploi et précise que les ports SMTP (25, 587, 465) et IMAP
(993) écoutent en direct et ne passent pas par le proxy. Pour ajuster ces
valeurs ensuite, voir Configuration.
Étape : unité systemd
L’assistant écrit /etc/systemd/system/oximail.service. L’unité lance
oximail serve --config /etc/oximail/oximail.toml, redémarre en cas d’échec,
relève la limite de descripteurs de fichiers et envoie la sortie vers journald
sous l’identifiant oximail. S’il ne peut pas écrire le fichier (pas root), il
affiche le contenu de l’unité pour que vous l’installiez à la main. Voir
Installation pour le détail de l’unité.
Étape : organisation et compte administrateur
L’assistant crée la première organisation (un tenant au sens du stockage : id
default, nom Default, domaine déduit de l’adresse de l’administrateur), puis
le compte administrateur. La création est idempotente : si elle existe déjà,
l’assistant le signale et continue.
Le mot de passe administrateur est demandé, avec confirmation. Il doit faire
au moins 8 caractères et contenir une majuscule, une minuscule et un chiffre ;
la saisie se répète tant que le mot de passe est trop faible. Le compte est créé
avec le rôle admin et la langue fr.
Tant qu’aucune organisation n’existe, le serveur démarre en mode assistant web (“no
tenants”). L’assistant en ligne de commande crée toujours le tenant default
avant le compte administrateur, donc un oximail setup terminé vous permet de
vous connecter directement.
Étape : démarrage du service
L’assistant exécute systemctl daemon-reload, systemctl enable oximail et
systemctl start oximail, puis interroge le port 443 pendant 90 secondes au
maximum, le temps que le certificat ACME soit provisionné. Il indique si le
serveur est devenu disponible et, sinon, vous renvoie vers
journalctl -u oximail -f.
Étape : vérification
Il se connecte aux ports 25, 587, 993 et 443, contrôle le point d’accès JMAP sur
https://<nom-d-hote>/.well-known/jmap (un code 401 compte comme disponible) et
confirme la présence du répertoire DKIM et du fichier de configuration.
En cas de réussite, l’assistant affiche l’URL de connexion
(https://<nom-d-hote>/auth/login), le chemin de la configuration et la commande
de consultation des journaux.
Étape : import facultatif de données
Enfin, l’assistant propose d’importer du courrier existant. Choix possibles :
Skip (ignorer), From IMAP server (Dovecot, Exchange, Gmail, tout serveur
IMAP4), From Stalwart (JMAP API) ou From mbox/Maildir files. Chaque choix
demande les informations de connexion correspondantes. Cette étape a lieu
après que le serveur est déjà configuré et démarré, donc un import en échec
ne casse pas l’installation. Vous pouvez réessayer à tout moment avec
oximail migrate. Voir Migration pour le flux d’import
autonome.
Déroulé MX secondaire
Si vous choisissez Backup MX comme mode de déploiement, l’assistant lance un
déroulé dédié. Il demande le nom d’hôte du MX principal (par défaut
mail.<domaine>), les domaines de relais supplémentaires et le mode de
transfert (queue pour accepter en local et réessayer vers le principal, avec
rapports DSN en cas de rejet définitif ; ou proxy pour relayer en temps réel
et propager la réponse du principal, avec repli sur queue si le principal est
injoignable). Il crée ensuite le compte administrateur, génère le DKIM, écrit une
configuration role = "backup", installe l’unité systemd, crée éventuellement
les enregistrements DNS de secours (MX priorité 20, A, DKIM et SRV
IMAP/soumission via Cloudflare), et vérifie le port 25 et la configuration.
Configuration non interactive
Pour des installations automatisées, écrivez un fichier TOML de setup et passez-le
avec --config-file :
oximail setup --config-file setup.toml
[server] (domain, hostname, éventuellement
deploy_mode = "primary" ou "backup", topology = "direct" ou "proxy",
proxy_port), ainsi que des sections facultatives [dns] (jeton Cloudflare,
replace_existing_mx), [tls] (acme_email), [admin] (email plus password
ou password_file), [import] (source = "imap" | "jmap" | "mbox" | "skip" avec
les champs de connexion correspondants) et, pour le mode secondaire, [backup]
(primary_hostname, accepted_domains, mode, config_output_path).
Les mêmes étapes s’exécutent sans question. S’il n’y a pas de section [admin],
l’assistant ne crée pas le compte administrateur et vous indique d’en créer un
avec oximail account create. Les mots de passe passés en mode non interactif
sont quand même contrôlés en force, et un mot de passe trop faible interrompt
l’exécution.
Utilisez --dry-run avec l’une de ces commandes pour prévisualiser la
configuration générée et les actions, sans rien écrire ni démarrer.
Sous-commandes de setup individuelles
Chaque étape de l’assistant est aussi une sous-commande autonome sous
oximail setup, pratique pour rejouer un seul morceau :
oximail setup dns --domain <d> --hostname <h> [--cloudflare-api-token <t>] [--replace-mx]
oximail setup dkim --domain <d> [--selector default]
oximail setup admin --email <e> [--password <p> | --password-file <f>] [--tenant-id default] [--config <chemin>]
oximail setup verify [--hostname <h>] [--config <chemin>]
--dry-run.
Génération de clé DKIM
Il existe aussi une commande DKIM de premier niveau (distincte de
oximail setup dkim), celle qui est citée dans le démarrage rapide :
oximail setup-dkim --domain <domaine> --selector <sélecteur> --config <chemin>
| Option | Valeur par défaut | Remarques |
|---|
--domain | (requis) | Domaine à signer, par exemple oximail.ch. |
--selector | (requis) | Sélecteur DKIM, par exemple default. |
--algorithm | rsa | Seul rsa (RSA-2048) est accepté à l’exécution. ed25519 est refusé car le signataire à l’exécution ne charge que des clés RSA. |
--config | /etc/oximail/oximail.toml | Sert à déterminer le répertoire de stockage de la clé. |
/etc/oximail/dkim/ et affiche
l’enregistrement DNS DKIM à publier. Elle ne publie pas l’enregistrement sur
Cloudflare : seul l’assistant complet le fait, et seulement si un jeton est
fourni. Publiez vous-même la valeur affichée v=DKIM1; k=rsa; p=... sur
<sélecteur>._domainkey.<domaine>.
Démarrer et vérifier à la main
Si vous avez sauté l’étape de démarrage de l’assistant, ou installé l’unité à la
main :
systemctl daemon-reload
systemctl enable --now oximail
systemctl status oximail
journalctl -u oximail -f
oximail setup verify --hostname mail.<domaine>
Ce que l’assistant ne fait pas
- Il n’installe pas le binaire. Mettez d’abord
oximail sur l’hôte ; voir
Installation.
- Il ne publie pas le DNS sans Cloudflare. Sans jeton Cloudflare, il affiche
les enregistrements (ou les résultats du contrôle) à ajouter chez votre
fournisseur.
- Il ne publie pas le DKIM en dehors de l’assistant complet. Les commandes
autonomes
setup-dkim et setup dkim génèrent et affichent l’enregistrement,
mais ne le poussent pas vers le DNS.
- Il ne configure pas le DKIM ed25519. Seules des clés RSA-2048 sont générées
et chargées à l’exécution.
- Il ne gère pas votre pare-feu. La vérification des ports se contente de
signaler les ports bloqués ; leur ouverture dans le pare-feu du VPS ou le
groupe de sécurité reste manuelle.
- Il ne crée pas d’organisations ni de comptes supplémentaires. Il provisionne
exactement un tenant
default et un compte administrateur. Ajoutez-en d’autres
avec oximail tenant create et oximail account create.
Étapes suivantes