Skip to main content
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 : Si /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

  1. Domaine de messagerie principal (par exemple oximail.ch), c’est-à-dire la partie domaine de vos adresses.
  2. Nom d’hôte du serveur de messagerie (par défaut mail.<domaine>).
  3. Mode de déploiement : Primary mail server (serveur principal), Backup MX (MX secondaire) ou Smarthost relay (dedicated hub) (hub de relais dédié). Le MX secondaire et le hub smarthost ont chacun leur propre déroulé, décrit plus bas.
  4. 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).
  5. Mode d’envoi sortant : Direct ou Par un relais. L’assistant sonde le port 25 sortant et recommande le relais quand la remise directe est impossible (la plupart des clouds bloquent ce port). Voir Relais sortant & smarthost pour tout le parcours relais, y compris le préflight de sortie pour repasser en direct plus tard. Cette question concerne le côté leaf (envoyer via un relais) ; elle est sautée sur le déroulé hub smarthost, les deux bouts d’un relais ne se confondant jamais.

​
É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 : Si vous avez choisi le proxy inverse, les ports 80 et 443 sont ignorés (le proxy les gère). Des ports bloqués n’arrêtent pas l’assistant, mais le serveur peut ne pas fonctionner tant qu’ils ne sont pas ouverts dans votre pare-feu.

​
É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], [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. L’extrait fait passer tout le trafic vers OxiMail, à la seule exception du chemin de défi HTTP d’ACME. Une liste blanche de routes est volontairement écartée : une famille de routes oubliée casse en silence la découverte des clients ou le DAV. Quand le webmail est servi depuis une autre origine, l’assistant remplit aussi [server] allowed_origins ; le CORS est traité par OxiMail lui-même, jamais par le proxy (une interception globale des OPTIONS au proxy casse en silence la découverte des clients DAV). 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. L’assistant capture aussi le fuseau horaire par défaut de l’organisation (un nom IANA, avec pour défaut le fuseau du système hôte : le cas courant est une simple touche Entrée). C’est le dernier étage de la chaîne de repli du calendrier (fuseau de l’événement → fuseau de l’utilisateur → fuseau de l’organisation → UTC) : les événements flottants se résolvent en heure locale plutôt qu’en UTC. Un fuseau inconnu n’est jamais persisté, il retombe sur la détection. Modifiable ensuite avec oximail tenant update --default-timezone.
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.

​
Déroulé smarthost

Si vous choisissez Smarthost relay (dedicated hub), l’assistant exécute le même déroulé que le serveur principal avec des ajustements ciblés : un smarthost est un MTA sortant complet, pas un mode d’installation séparé (il n’y a délibérément aucun chemin de démarrage dédié). Ce qui change :
  • L’assistant demande la ou les IP d’egress du hub (séparées par des virgules). Seuls des littéraux IP sont acceptés : ils alimentent l’auto-surveillance DNSBL et l’enregistrement SPF publié, où un nom d’hôte ou une faute de frappe casserait silencieusement le SPF de tous les clients.
  • La configuration générée déclare profile = "smarthost" sous [mode]. Le profil est une déclaration auditée, jamais un commutateur de comportement : à chaque démarrage, le serveur la compare à la configuration et avertit (via un signal d’audit de démarrage que votre supervision peut alerter) si les surfaces boîtes aux lettres sont encore actives ou si l’auto-surveillance DNSBL est vide. Un serveur combiné boîtes + hub ne pose simplement pas le profil.
  • Les surfaces boîtes aux lettres sont désactivées ([legacy] enabled = false) et [metrics] dnsbl_self_ips est rempli avec les IP d’egress.
  • L’enregistrement SPF du hub que les clients incluront (spf.<domaine> TXT "v=spf1 ip4:… -all") est publié via Cloudflare si vous avez fourni un jeton, ou imprimé pour publication manuelle.
  • Aucun compte relais n’est créé. Les clients relais entrent uniquement par des jetons frappés ; l’assistant imprime la commande oximail account relay mint-token comme étape suivante. Voir Relais sortant & smarthost pour tout le parcours hub.

​
Configuration non interactive

Pour des installations automatisées, écrivez un fichier TOML de setup et passez-le avec --config-file :
Le fichier comporte une section [server] (domain, hostname, éventuellement deploy_mode = "primary", "backup" ou "smarthost", 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, et un default_timezone optionnel), [import] (source = "imap" | "jmap" | "mbox" | "skip" avec les champs de connexion correspondants), pour le mode secondaire, [backup] (primary_hostname, accepted_domains, mode, config_output_path) et, pour le déroulé smarthost, [smarthost] (egress_ips = ["203.0.113.25", …], validées comme littéraux IP, refus bruyant sinon). 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 :
Toutes acceptent --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 :
Cette commande génère la paire de clés dans /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 :
Relancez les contrôles de l’assistant à tout moment :

​
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