Instruction de déploiement Stargate

🇩🇪 Hinweis zu Übersetzungen | 🇫🇷 Remarque concernant les traductions
🇮🇹 Avvertenza sulle traduzioni | 🇬🇧 Translation notice

🇩🇪🇫🇷🇮🇹🇬🇧

Für verlässliche Informationen nutzen Sie bitte die offiziellen Übersetzungen über den Sprachschalter . Automatische Browser-Übersetzungen können Inhalte verfälschen.

Pour obtenir des informations fiables, veuillez utiliser les traductions officielles accessibles via le sélecteur de langue . Les traductions automatiques du navigateur peuvent déformer le contenu.

Per informazioni affidabili, utilizzare le traduzioni ufficiali accessibili tramite il selettore della lingua . Le traduzioni automatiche del browser possono alterare i contenuti.

For reliable information, please use the official translations available via the language selector . Automatic browser translations may distort the content.

Qu'est-ce que Stargate ?

Prérequis

Veuillez vous assurer que toutes les étapes préparatoires nécessaires ont été effectuées avant le début des activités de migration ou de nouvelle installation du HIN Gateway.

Les éléments suivants doivent être disponibles ou confirmés avant l'installation :

• Les identifiants vous seront fournis par HIN

  • Identifiants VM
  • Identifiants Keycloak
  • Code d'activation

• Exportation de la ou des clé(s) privée(s)

Info

L'exportation des clés privées ne concerne que les clients qui passent d'un MGW existant à un nouveau HIN Gateway

• Si vous travaillez sur une machine Windows ayant accès à la VM Mail Gateway via le port 22, nous pouvons vous accompagner pendant l'appel pour activer l'exportation de la clé privée depuis le MGW.
• Si vous n'avez pas accès à une telle machine, veuillez contacter le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740) afin qu'il vous aide à établir une connexion de support via System Administration → Support Connection → Connect.

Pour les clients disposant de plusieurs domaines

Note : applicable à tous les scénarios de migration multi-domaine !

Afin de réduire le temps nécessaire à l'exécution de la migration, nous encourageons les clients à effectuer les étapes suivantes avant la date et la session de migration prévues :

• Exportez la clé privée pour chaque domaine.
• Identifiez et documentez le flux de courrier entrant et sortant pour chaque domaine.

Veuillez contacter le support HIN pour obtenir le code de déverrouillage nécessaire à l'exportation des clés privées.

• Téléchargez la dernière version de l'image VM
• Exigences pare-feu pour WireGuard. Configurez le port WireGuard 19818 (TCP/UDP) dans votre pare-feu :
  • Trafic entrant et sortant
  • Autoriser le trafic : any-to-HIN Gateway et HIN Gateway-to-any

• L'accès DHCP doit être disponible. Pour plus d'informations, voir "Installation Guidelines".

• Exigences de sauvegarde - voir "Annexe 1 - Sauvegarde et restauration des paramètres de l'appliance".

Info

Les exigences de sauvegarde ne concernent que les clients qui passent d'un MGW existant à un nouveau HIN Gateway

• Confirmation que le MGW existant ne sera pas supprimé avant que la réception ait été effectuée.

Info

Le maintien de la disponibilité du MGW existant jusqu'à ce que le rapport de réception soit terminé ne concerne que les clients qui passent d'un MGW existant à un nouveau HIN Gateway

• Accès au DNS, aux connecteurs du serveur de messagerie, aux règles de transport et aux paramètres de relais.

Démarrage rapide

Options d'installation

• Installation par image VM:
  • Installation par image VM Azure
  • Installation par image VM Windows 11 Pro (Hyper-V)
  • Installation par image VM VMware
  • Installation par image VM Proxmox
  • Installation par image VM Cloudscale.ch

Second disque requis : le Data Disk

L'appliance utilise deux disques : le disque système issu de l'image et un Data Disk distinct qui contient l'ensemble de la configuration, des secrets, des e-mails et des bases de données. Cette séparation permet à une mise à niveau de l'image de remplacer le système d'exploitation sans toucher à vos données.

L'OVA VMware inclut déjà ce disque. Sur toutes les autres plateformes (Proxmox, Hyper-V, Azure, Cloudscale), l'image ne comporte qu'un seul disque système : vous devez donc ajouter un second disque vierge d'au moins 30 Go avant le premier démarrage.

Ne le formatez pas et ne le partitionnez pas vous-même. Au premier démarrage, l'appliance formate le disque vierge (étiquette VEREIGN-DATA) et le monte sur /var/data. Sans ce disque, le contrôle de santé du premier démarrage échoue et un retour arrière (rollback) est effectué.

🖨️

Vous pouvez obtenir cette documentation imprimée ou sauvegardée en PDF, veuillez visiter notre Page d'impression.

Intégration Exchange

• Intégration Exchange - Configurez les connecteurs Microsoft Exchange (Online et On-Premises) et les règles de transport pour acheminer les courriels via Stargate

Exigences du serveur

	Minimum	Recommandé
CPU, Cœurs	4	6
RAM, GB	8	12
SSD, GB	60	60

Exigences communes

• Accès root: Doit être exécuté en tant que root ou avec sudo
• Distributions prises en charge:
  • Distributions compatibles RHEL 8, 9 et 10 telles que Alma Linux, Rocky Linux, CentOS Stream
  • Ubuntu 22 et 24
  • Debian 11, 12 et 13
• Adresse IPv4 réelle
• Enregistrements DNS valides. Votre domaine doit avoir:
  • Des enregistrements MX pointant vers vos serveurs de courrier
  • Un enregistrement SPF définissant les réseaux d'envoi autorisés
  • Le serveur doit être capable de résoudre le DNS (enregistrements MX, SPF, A)
  • Utilisé pour le routage du courrier et la liste d'autorisation réseau basée sur SPF

Accès réseau entrant (le pare-feu doit autoriser)

Port	Protocole	Objectif
25	TCP	SMTP - réception des courriels des serveurs externes ou d'un MTA installé en amont du HIN Gateway.
19818	UDP+TCP	WireGuard - tunnel crypté pour la communication agent-à-agent. Lisez notre Évaluation de sécurité WireGuard

Accès entrant à la VM (de votre poste d'administration vers la VM HIN Gateway)

Info

Ces règles de pare-feu doivent être appliquées uniquement entre votre poste d'administration et la VM HIN Gateway. Il n'est pas nécessaire d'exposer ces ports à Internet.

Port	Protocole	Objectif
80	TCP	Redirige le trafic HTTP vers HTTPS
443	TCP	Utilisé pour administrer HIN Gateway via le tableau de bord web
8180	TCP	Utilisé par Keycloak pour authentifier les utilisateurs du tableau de bord HIN Gateway
8190	TCP	Facultatif. Requis pour le dépannage et la consultation des journaux
22	TCP	Facultatif. Requis pour le dépannage et la modification de la configuration

Accès réseau sortant (le serveur doit atteindre)

Destination	Port	Protocole	Objectif
registry-1.docker.io, auth.docker.io, production.cloudflare.docker.com	443	TCP	Registre d'images Docker Hub
quay.io	443	TCP	Registre de conteneurs (Keycloak, oauth2-proxy)
github.com	443	TCP	Dépôt de politiques (policy-sync)
Votre propre point de terminaison Loki (p. ex. loki.example.com)	443	TCP	Optionnel. Nécessaire uniquement si vous fournissez votre propre instance Loki vers laquelle la stack doit envoyer les logs (Alloy → Loki)
Serveur de mise à jour d'Alpine, AlmaLinux, etc.	80	TCP	Divers serveurs de mise à jour - https://hub.docker.com/
Serveurs de courrier de destination	25	TCP	Livraison des courriels sortants via recherche MX, ou livraison au MTA suivant configuré comme serveur sortant.
Serveurs DNS	53	UDP+TCP	Sortant vers les serveurs DNS publics
ntp.metas.ch (serveur NTP par défaut)	123	UDP	NTP synchronise les horloges des ordinateurs, serveurs, équipements réseau et machines virtuelles avec des sources de temps précises
Pairs WireGuard (réseau HIN)	19818	UDP+TCP	WireGuard - tunnel crypté pour la communication agent-à-agent
witness-{1,2,3}.verify-mail.hin-infra.ch	443	TCP	Pool de témoins KERI de HIN - requis pour la vérification des identités des agents (idagent / watcher)
app.hin.ch	443	TCP	Liste des membres / domaines de messagerie HIN (mxengine)
apisix.verify-mail.hin-infra.ch	443	TCP	Enregistrement de la passerelle HIN lors de l'intégration (tableau de bord)

Utiliser votre propre serveur NTP

L'appliance est préconfigurée pour utiliser ntp.metas.ch (Institut fédéral de métrologie). Si votre réseau n'autorise pas le NTP sortant, configurez votre propre serveur de temps au lieu d'ouvrir le port 123 vers Internet - un serveur interne est entièrement pris en charge.

Pour définir les vôtres, créez le fichier suivant sur l'appliance puis rechargez. Vous pouvez indiquer autant de serveurs que nécessaire, un par ligne :

sudo tee /var/data/vereign/chrony/ntp.sources <<'EOF'
pool ntp1.example.local iburst
pool ntp2.example.local iburst
EOF
sudo chronyc reload sources
chronyc sources -v

Le fichier doit être nommé exactement ntp.sources. Sous ce nom, votre liste remplace la valeur par défaut ; sous tout autre nom, elle s'y ajoute. Supprimez le fichier et rechargez pour revenir à ntp.metas.ch.

L'exactitude de l'heure n'est pas optionnelle. Si l'horloge dérive, la validation des certificats, la signature des messages et les sessions de connexion échouent de manière difficile à diagnostiquer.

Remarque importante concernant l'exploitation sur Microsoft Azure

Exploitation sur Microsoft Azure Pour la connexion SMTP Relay du HIN Gateway à Exchange Online, le trafic sortant via le port TCP 25 doit être autorisé.

Microsoft Azure bloque les connexions sortantes via le port 25 pour la plupart des modèles d'abonnement. HIN n'a aucune influence sur la disponibilité ou l'activation de ce port par Microsoft. L'exploitation du HIN Gateway sur Azure ne constitue donc pas un scénario de déploiement pris en charge par défaut. Des exceptions existent notamment pour certains abonnements Entreprise de Microsoft. Vérifiez donc avant toute installation sur Azure si votre abonnement autorise le trafic SMTP sortant via le port TCP 25.

Si vous avez des questions concernant la variante d'exploitation appropriée, veuillez contacter suffisament tôt votre personne de contact chez HIN.

Remarque concernant le pare-feu

Selon la configuration de votre pare-feu ou de votre NAT, il peut être nécessaire d'autoriser explicitement le trafic sur les ports requis. Consultez la documentation de votre pare-feu ou de votre configuration NAT pour plus d'informations.

La VM doit pouvoir accepter les connexions entrantes sur les ports de service requis et renvoyer les réponses au demandeur. Avec un pare-feu à états (par exemple iptables utilisant conntrack), le trafic de retour est automatiquement autorisé par les règles ESTABLISHED,RELATED.

Exemple de configuration iptables :

# Autoriser le trafic de retour des connexions établies
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Autoriser les connexions TCP entrantes vers les ports ouverts
iptables -A INPUT -p tcp -m multiport --dports 25,19818 -j ACCEPT

# Autoriser les connexions TCP sortantes vers les ports ouverts
iptables -A OUTPUT -p tcp -m multiport --dports 25,19818 -j ACCEPT

# Autoriser le port UDP 19818 entrant pour WireGuard
iptables -A INPUT -p udp --dport 19818 -j ACCEPT

# Autoriser le port UDP 19818 sortant pour WireGuard
iptables -A OUTPUT -p udp --dport 19818 -j ACCEPT

# Services supplémentaires auxquels la VM doit pouvoir accéder
# DNS
iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT

# NTP
iptables -A OUTPUT -p udp --dport 123 -j ACCEPT

# HTTP
iptables -A OUTPUT -p tcp --dport 80 -j ACCEPT

# HTTPS
iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT

Approche de migration recommandée selon le nombre de domaines

Clients avec 3 domaines ou moins

• HIN recommande de migrer tous les domaines en une seule fois.
• HIN accompagnera le client dans la migration réussie du premier domaine.
• Une fois le premier domaine migré avec succès, le client peut migrer les domaines restants de manière autonome.
• Cette approche permet de garder la migration simple et évite la nécessité d’un environnement parallèle.

Clients avec plus de 3 domaines

• HIN recommande de mettre en place un environnement parallèle à côté du MGW existant.
• Les domaines peuvent ensuite être migrés progressivement vers le nouvel environnement.
• HIN accompagnera le client dans la migration réussie du premier domaine.
• Après la première migration réussie, le client peut décider comment et quand transférer les domaines restants vers le nouvel environnement.

Contactez-nous

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance HIN Mail (Stargate), veuillez contacter le support HIN.

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.

---

Guides d'installation

HIN Gateway : Guide technique pour la nouvelle installation et la migration

Introduction

Ce document fournit un guide complet sur le processus d'installation technique et de migration vers le nouveau HIN Gateway ("Stargate Appliance").

Ce guide s'adresse aux clients HIN, aux administrateurs informatiques et aux ingénieurs système chargés du déploiement et de la configuration du nouveau HIN Gateway ainsi que, le cas échéant, de la migration du Mail Gateway (MGW) existant vers la nouvelle solution.

Le HIN Gateway est une solution de passerelle de messagerie sécurisée qui permet une communication fiable, chiffrée et régie par des politiques au sein de l'Espace de confiance HIN. Elle fait office d'intermédiaire central entre les infrastructures de messagerie internes et les partenaires de communication externes, garantissant que l'ensemble du trafic de messagerie est transmis en toute sécurité, respecte les politiques de l'organisation et répond aux normes de sécurité de HIN.

Aperçu du flux de messagerie

• Les e-mails entrants sont acheminés via le HIN Gateway, où ils sont validés, déchiffrés (si nécessaire) et vérifiés au regard des politiques de confiance et de sécurité avant d'être transférés vers le serveur de messagerie interne.
• Les e-mails sortants sont envoyés depuis les systèmes internes vers le HIN Gateway, où le chiffrement, le routage et l'application des politiques sont effectués avant leur transmission aux destinataires externes.
• La communication entre les HIN Gateways est sécurisée par des certificats de pair à pair et des tunnels WireGuard, garantissant ainsi une communication fiable entre les domaines.

Processus d'installation et de migration

La procédure structurée, étape par étape, décrite dans ce document couvre à la fois les nouvelles installations du HIN Gateway et les migrations depuis un HIN Mail Gateway (MGW) existant. Selon le scénario de déploiement, certaines étapes peuvent s'appliquer uniquement aux migrations.

1. Préparation et planification du déploiement, y compris la planification de repli le cas échéant
2. Installation et configuration du HIN Gateway
3. Activation du domaine et validation du certificat
4. Intégration dans l'environnement de messagerie existant et configuration du routage
5. Tests, mise en production et validation post-déploiement
6. Pour les migrations : mise hors service du MGW existant après validation réussie

Migration

L'objectif de HIN est d'assurer un déploiement sécurisé, fluide et entièrement validé, avec une perturbation minimale des opérations et une continuité ininterrompue des services de messagerie. Dans les scénarios de migration, le MGW existant doit rester disponible en tant qu'option de repli jusqu'à ce que le HIN Gateway ait été validé avec succès en production. Il ne doit être mis hors service qu'une fois la migration terminée et le fonctionnement stable confirmé.

Foire aux questions

Puis-je effectuer l'installation ou la migration moi-même?

Oui, l'installation ou la migration peuvent être entièrement réalisées par le client.

Pour un scénario de migration, la seule exception concerne l'"Étape 1.3 - Exporter la ou les clés privées". Pour des raisons de sécurité et afin de préserver la sécurité de votre clé privée, vous devez contacter le support HIN ou participer à la réunion de migration prévue afin de recevoir le code nécessaire à l'exportation de la clé privée depuis le Mail Gateway actuellement en service.

Si l'installation ou la migration ne peuvent être menées à bien, veuillez participer à la réunion d'assistance prévue avec nos ingénieurs.

Y aura-t-il une interruption de la distribution des e-mails pendant le processus d'installation?

Migration: Entre l'"Étape 1.5 - Arrêt de la machine virtuelle MGW existante" et l'"Étape 18 - Configurer le serveur de messagerie", tous les e-mails seront mis en file d'attente sur le serveur de messagerie. Une fois l'"Étape 18 - Configurer le serveur de messagerie" terminée, les e-mails en file d'attente seront envoyés ou remis dans la boîte de réception.

Nouvelle installation: Pendant que vous configurez les règles de flux de messagerie, tous les e-mails seront mis en file d'attente sur le serveur de messagerie. Une fois l'"Étape 18 - Configurer le serveur de messagerie" terminée, les e-mails en file d'attente seront envoyés ou remis dans la boîte de réception.

Des e-mails seront-ils perdus pendant l'installation et la migration?

Non, aucun e-mail ne sera perdu pendant l'installation et la migration. Certains e-mails pourraient être retardés.

Aperçu des étapes d'installation

Étape	Sujet	Responsabilité	Migration	Nouvelle installation
0	Vérification des prérequis	Client	Yes	Yes
1.1	Smoke test	Client	Yes	N/A
1.2	Sauvegarde du MGW existant	Client	Yes	N/A
1.3	Exporter la ou les clés privées	Client / HIN	Yes	N/A
1.4	Plan d'urgence / scénario de repli	Client	Yes	N/A
1.5	Arrêt de la machine virtuelle MGW existante	Client	Yes	N/A
2	WireGuard	Client	Yes	Yes
3	Sélectionner la machine virtuelle cible	Client	Yes	Yes
4	Charger l'image de la machine virtuelle	Client	Yes	Yes
5	Connexion réseau à la machine virtuelle	Client	Yes	Yes
6	Accès via le navigateur	Client	Yes	Yes
7	Saisir le code d'activation	Client	Yes	Yes
8	Configuration du mesh network	Client	Yes	Yes
9	Mise en place du mesh network sécurisé	Client	Yes	Yes
10	Connexion à Keycloak	Client	Yes	Yes
11	Mettre à jour le mot de passe	Client	Yes	Yes
12	Mettre à jour les informations du compte	Client	Yes	Yes
13	Configuration initiale et configuration du domaine	Client	Yes	Yes
14	Configurer le transport du courrier	Client	Yes	Yes
15	Configurer les whitelist headers	Client	Yes	Yes
16	Certificats de pairs	HIN	Yes	Yes
17	Valider les certificats des pairs	Client	Yes	Yes
18	Configurer le serveur de messagerie	Client	Yes	Yes
19	Tester et valider	Client	Yes	Yes
20	Modifier le mot de passe de la machine virtuelle	Client	Yes	Yes
21	Mise hors service du MGW existant	Client	Yes	N/A
Annexe 1	Sauvegarde et restauration des paramètres de l'appliance	Client	Yes	N/A

Étapes détaillées

Étape 0 - Vérification des prérequis

Veuillez vous assurer que toutes les étapes préparatoires nécessaires ont été effectuées avant le début des activités de migration du HIN Gateway.

Les éléments suivants doivent être disponibles ou confirmés avant l'installation:

• Les identifiants vous seront fournis par HIN

  • Identifiants de la machine virtuelle
  • Identifiants Keycloak
  • Code d'activation

• Exportation de la clé privée Note : Applicable uniquement en cas de migration

  • Si vous travaillez sur un ordinateur Windows ayant accès à la machine virtuelle Mail Gateway via le port 22, nous pouvons vous aider, pendant l'appel, à activer l'exportation de la clé privée depuis le MGW.
  • Si vous n'avez pas accès à un tel ordinateur, veuillez contacter le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740) afin que nous puissions vous aider à établir une connexion d'assistance via System Administration -> Support Connection -> Connect.
• Télécharger la dernière version de l'image de la machine virtuelle
• Pare-feu :
  • Autorisez le trafic : de n'importe quelle source vers HIN Gateway et de HIN Gateway vers n'importe quelle destination
    • WireGuard : veuillez consulter Configuration requise du serveur - Accès réseau entrant :
      • Configurez le port WireGuard 19818 (TCP/UDP) dans votre pare-feu.
        • Trafic entrant et sortant
  • Autorisez le trafic : poste d'administration → VM HIN Gateway
    • Exigences pour l'installation :
      • Port HTTPS 443
        • Trafic entrant et sortant
      • Port Keycloak 8180
        • Trafic entrant et sortant
    • Exigences pour le dépannage (facultatif, requis pour consulter les journaux et modifier tous les paramètres) :
      • Port SSH 22
        • Trafic entrant et sortant
      • Port Dozzle 8190
        • Trafic entrant et sortant
• L'accès DHCP doit être disponible pour l'"Étape 5 - Connexion réseau à la machine virtuelle" (recommandé).
• Exigences en matière de sauvegarde - voir "Annexe 1 - Sauvegarde et restauration des paramètres de l'appliance". Note : Applicable uniquement en cas de migration
• Note : Applicable uniquement en cas de migration - Confirmation que le MGW existant ne sera pas supprimé tant que la procédure d'acceptation n'aura pas été menée à bien.
• Accès au DNS, aux connecteurs de serveur de messagerie, aux règles de transport et aux paramètres de relais.

Pourquoi WireGuard ?

Le port WireGuard remplit deux fonctions importantes:

1. Le HIN Gateway utilise ce port pour obtenir les certificats de ses pairs auprès de l'autorité de certification HIN.
2. Il utilise ce port pour établir un tunnel sécurisé vers d'autres passerelles HIN, par lequel s'effectue l'échange sécurisé de données (par exemple, le trafic de messagerie).

!!! tip "Exportation de la clé privée" - Applicable uniquement en cas de migration Si vous travaillez sur un ordinateur Windows ayant accès à la machine virtuelle Mail Gateway via le port 22, nous pouvons vous aider, pendant l'appel, à activer l'exportation de la clé privée depuis la MGW.

Si vous n'avez pas accès à un tel ordinateur, veuillez contacter le support HIN par e-mail ou par téléphone (**support@hin.ch** / **0848 830 740**) afin que nous puissions vous aider à établir une connexion d'assistance via **System Administration -> Support Connection -> Connect**.

Étape 1.1 - Smoke test

Info

Cette étape s'applique uniquement aux migrations à domaine unique et à domaines multiples

Envoyez des e-mails de test aux destinataires suivants, en utilisant des boîtes aux lettres auxquelles vous avez accès afin de pouvoir vérifier que la remise a été effectuée avec succès:

• une adresse e-mail HIN ou une adresse e-mail au sein de votre domaine de la communauté HIN, par exemple: user@hin.ch
• une adresse e-mail externe en dehors de la communauté HIN, par exemple: Bluewin, Gmail, Yahoo ou GMX

Pour le destinataire externe, envoyez un e-mail depuis la communauté HIN avec la mention (confidentiel) dans l'objet.

Messages (Confidentiel) en dehors de la communauté HIN

Si vous utilisez Outlook et l'une des options suivantes pour envoyer des e-mails confidentiels en dehors de la communauté HIN: * Utilisation d'un modèle d'e-mail spécifique * Utilisation du symbole de cadenas (Key Lock)

Veuillez tester le flux de messagerie avant la migration afin de confirmer que l'e-mail est traité et remis de manière sécurisée.

Testez le flux de messagerie dans les deux sens:

• de la communauté HIN de confiance vers l'adresse e-mail externe
• de l'adresse e-mail externe vers la communauté HIN

Vérifiez que tous les e-mails de test ont bien été remis et que l'objet, le contenu du message et les pièces jointes (le cas échéant) sont correctement reçus.

Étape 1.2 - Sauvegarde du MGW existant

Info

Cette étape s'applique uniquement aux migrations à domaine unique et à domaines multiples

Effectuez une sauvegarde de l'appliance MGW existante et assurez-vous que la machine virtuelle soit conservée jusqu'à ce que la migration soit terminée avec succès et officiellement acceptée. Pour plus d'informations, consultez l'"Annexe 1 - Sauvegarde et restauration des paramètres de l'appliance".

Vérifier la configuration de routage actuelle du MGW

Avant d'arrêter le MGW existant, vérifiez les valeurs de configuration suivantes et notez-les. Vous en aurez probablement besoin plus tard lors de la configuration du HIN Gateway :

1. Connectez-vous au MGW et allez dans "Mail System → Outgoing server" pour vérifier si quelque chose y est configuré.
2. Pour chaque domaine hébergé sur le MGW, allez dans Mail System → <domain> → Forwarding server et Mail System → <domain> → Send ALL outgoing mails from this domain to the following SMTP server, et notez les valeurs actuelles.
   

Vérification des en-têtes du MGW

Si vous utilisez l'option Header check dans le MGW, notez également la valeur configurée. Vous pourrez configurer la même vérification d'en-tête plus tard dans le HIN Gateway.

Étape 1.3 - Exporter la ou les clés privées

Info

Cette étape s'applique uniquement aux migrations à domaine unique et à domaines multiples

Pour une migration à domaines multiples, effectuez l'opération pour chaque domaine

Assistance HIN requise

Un code de déverrouillage est requis pour cette étape. Ce code est fourni par un ingénieur du support HIN.

Si vous souhaitez poursuivre l'installation par vous-même, veuillez contacter le support HIN afin de demander le code de déverrouillage. Dans le cas contraire, le code de déverrouillage vous sera fourni lors de l'appel de migration prévu.

1. Connectez-vous à l'interface web du MGW existant.
2. Ouvrez "Mail System".
   
3. Exécutez l'application en cliquant sur HIN_Migration-Tool_v*.exe si vous souhaitez l'installer vous-même. Vous pouvez également attendre l'appel de migration, au cours duquel l'ingénieur support vous assistera pour l'installation.
   
4. Saisissez le code de déverrouillage fourni par l'ingénieur du support.
   
5. Sélectionnez "Enable export".
   
6. Saisissez l'adresse IP du MGW.
   
7. Attendez la confirmation.
   
8. Sélectionnez le domaine de confiance dans l'interface web (webGUI) du MGW.
   
9. Faites défiler vers le bas et sélectionnez l'empreinte numérique gérée.
   
10. Faites défiler jusqu'à la section "PKCS12 download" (vous pouvez, si vous le souhaitez, saisir un mot de passe pour chiffrer la clé). Cliquez sur "Download PKCS12" et enregistrez le fichier *.p12 sur l'ordinateur.
    
11. Revenez à l'application HIN_Migration-Tool_v*.exe et désactivez le bouton Export.
    

Étape 1.4 - Plan d'urgence / scénario de repli

Info

Cette étape s'applique uniquement aux migrations à domaine unique et à domaines multiples

Scénario de retour en arrière - si une restauration est nécessaire:

1. Arrêtez le nouveau HIN Gateway.
2. Démarrez le MGW existant.
3. Vérifiez que le trafic de messagerie entrant et sortant fonctionne correctement via le MGW existant.
   • Pour une migration à domaines multiples, effectuez l'opération de vérification pour chaque domaine

Étape 1.5 - Arrêt de la machine virtuelle MGW existante

Info

Cette étape s'applique uniquement aux migrations à domaine unique et à domaines multiples

Arrêtez la machine virtuelle MGW existante.

Warning

Cette étape interrompra le flux de messagerie. Pendant cette interruption, les e-mails seront mis en file d'attente sur le serveur de messagerie et remis une fois l'installation terminée (voir "Étape 18 - Configurer le serveur de messagerie").

Étape 2 - WireGuard

Assurez-vous d'avoir configuré le port WireGuard 19818 (TCP/UDP) dans votre pare-feu:

• Trafic entrant et sortant
• Autorisez le trafic : de n'importe quelle source vers HIN Gateway et de HIN Gateway vers n'importe quelle destination

Étape 3 - Sélectionnez la machine virtuelle cible

Sélectionnez l'une des images virtuelles disponibles et provisionnez-la comme décrit dans le guide d'installation sur la page du service HIN Gateway.

Info

Pour des raisons de sécurité et de prise en charge, assurez-vous que votre hyperviseur n'utilise pas une version en fin de vie. L'appliance HIN Gateway est prise en charge sur la dernière version de l'hyperviseur et sur la version majeure immédiatement précédente.

• Installation de l'image de machine virtuelle:
  • Image de machine virtuelle Azure
  • Image Windows 11 Pro (Hyper-V)
  • Image VMware
  • Image Proxmox
  • Cloudscale
• Configuration de Microsoft Exchange

Étape 4 - Charger l'image de machine virtuelle

Téléchargez la machine virtuelle sélectionnée sur votre hyperviseur.

Deuxième disque requis : le disque de données

L'appliance utilise deux disques : le disque OS de l'image et un disque de données distinct qui contient toute la configuration, les secrets, les courriels et les bases de données. Cette séparation permet à une mise à jour d'image de remplacer l'OS sans toucher à vos données.

L'OVA VMware inclut déjà ce disque. Sur toutes les autres plateformes (Proxmox, Hyper-V, Azure, Cloudscale), l'image est un disque OS unique, attachez donc un second disque vierge d'au moins 30 Go avant le premier démarrage.

Ne le formatez pas et ne le partitionnez pas vous-même. Au premier démarrage, l'appliance formate le disque vierge (étiquette VEREIGN-DATA) et le monte sur /var/data. Sans lui, le premier démarrage échoue à son contrôle de santé et effectue un rollback.

Étape 5 - Connexion réseau à la machine virtuelle

Assurez-vous que la machine virtuelle dispose d'une connexion réseau et qu'une adresse IP statique lui a été attribuée.

Option A: Configurez l'adresse IP de la machine virtuelle directement dans l'hyperviseur que vous utilisez.

Option B: Configurez le serveur DHCP de votre routeur pour qu'il attribue systématiquement la même adresse IP en fonction de l'adresse MAC de la machine virtuelle.

Option C: Connectez-vous localement via la console de la machine virtuelle et configurez manuellement une adresse IP statique. REMARQUE: l'image de la machine virtuelle exécute une installation automatique lors du premier démarrage. Si le réseau n'est pas configuré à ce stade, l'installation échouera car l'adresse IP du serveur ne pourra pas être déterminée.

Ajouter une adresse IP sous Linux:

1. Exécutez la commande "nmtui" dans la console

   nmtui
   

2. Utilisez les touches fléchées pour naviguer, puis appuyez sur "Enter" pour sélectionner la "connexion Ethernet" dont vous souhaitez modifier l'adresse IP.
   

3. Accédez à "Configuration IPv4" et modifiez le paramètre de "Automatique" à "Manuel".
   
4. Utilisez les touches fléchées pour accéder aux champs dans lesquels vous pouvez saisir l'adresse IP, le gateway et le serveur DNS. Sélectionnez ensuite "OK".
   

5. Après avoir enregistré la configuration de l'adresse IP, exécutez la commande suivante dans la console:

   sudo systemctl restart NetworkManager
   

Tip

Si vous avez utilisé l'option C et configuré le réseau manuellement, vous devez exécuter les commandes suivantes:

sudo -i
cd /usr/share/stargate-deployment/docker-compose
./scripts/purge.sh
./scripts/install.sh

Le script d'installation détecte automatiquement l'adresse IP du serveur à partir de la route par défaut à chaque exécution : aucune modification manuelle de customer-config.sh n'est nécessaire. Toute adresse IP accessible, qu'elle soit publique ou privée, est suffisante. Le point de terminaison public réel est configuré ultérieurement via le dashboard.

Derrière un NAT ou une IP flottante ?

Si votre serveur est joint sur une adresse IP publique ou flottante différente de celle de sa propre interface réseau (cas courant avec le NAT), définissez SERVER_STATIC_IP sur cette adresse IP accessible dans customer-config.sh avant d'exécuter install.sh. Sinon, laissez-le vide afin qu'il soit détecté automatiquement.

Une fois les scripts exécutés avec succès, passez à l'"Étape 6 - Accès via le navigateur".

Question

Si vous ne disposez pas des identifiants administrateur HIN, veuillez contacter le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740). Veuillez consulter la Section Support.

Cliquez ici pour envoyer un e-mail

Remarque importante concernant l'exploitation sur Microsoft Azure

La connexion SMTP Relay du HIN Gateway à Exchange Online nécessite une communication SMTP sortante via le port TCP 25.
Microsoft Azure bloque les connexions sortantes via le port 25 pour la plupart des modèles d'abonnement. [Pour les abonnements standard Enterprise Agreement (EA) et Microsoft Customer Agreement for Enterprise Subscriptions (MCA-E)](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-network/troubleshoot-outbound-smtp-connectivity), le port 25 est généralement disponible, selon Microsoft. Des conditions particulières s'appliquent à certaines autres configurations d'entreprise.

Étant donné que ces restrictions et les éventuelles activations sont définies exclusivement par Microsoft, l'exploitation du HIN Gateway sur Azure ne constitue pas un scénario de déploiement pris en charge par défaut. HIN n'a aucune influence sur la disponibilité ou l'activation de ce port par Microsoft.

Recommandation : Vous prévoyez une migration ou une modification de votre infrastructure avec Azure ? Avant l'installation, vérifiez impérativement si votre abonnement Azure autorise la communication SMTP sortante via le port TCP 25. Contactez suffisament tôt votre personne de contact chez HIN afin de déterminer ensemble la variante d'exploitation qui vous convient.

Variantes d'exploitation alternatives recommandées
Si le port TCP 25 n'est pas disponible dans votre environnement Azure, nous vous recommandons :

· l'exploitation du HIN Gateway sur une machine virtuelle locale ou on-premises (comme jusqu'à présent)
· l'exploitation du HIN Gateway chez un prestataire d'hébergement conforme à la protection des données

**Perspectives : Gateway as a Service**

HIN prévoit de proposer à l'avenir le Gateway sous forme de service entièrement géré. Souhaitez-vous être informé dès que HIN Gateway as a Service sera disponible ? Contactez votre personne de contact chez HIN et inscrivez-vous sans engagement.

Étape 6 - Accès via le navigateur

Ouvrez un navigateur et saisissez l'adresse IP configurée pour la machine virtuelle. L'écran de configuration initiale devrait s'afficher.

https://<adresse IP de la machine virtuelle>

Redémarrer la VM

Si la machine n'est pas accessible, redémarrez la VM depuis la console, puis réessayez d'y accéder via le navigateur.

Étape 7 - Saisissez le code d'activation

Sélectionnez la langue de votre choix et saisissez le code d'activation que vous avez reçu par e-mail de la part de HIN. Cliquez sur "Next".

Je n'ai pas de code d'activation

Si vous ne disposez pas du code d'activation, veuillez contacter le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740). Veuillez consulter la Section Support.

Cliquez ici pour envoyer un e-mail

Étape 8 - Configuration du mesh network

Vérifiez la configuration du mesh network:

• Adresse IP - L'adresse IP publique du trafic sortant (détectée automatiquement).
• Transport - Le protocole de transport (par défaut: tcp).
• Port - Le port WireGuard (par défaut: 19818).

Qu'est-ce qu'une IP publique ?

Il s'agit d'une adresse IP que la machine utilisera pour être accessible via Internet. Ce n'est pas l'adresse IP interne de la machine derrière un pare-feu ou un NAT, par exemple 10.0.0.0/8, 172.16.0.0/12 ou 192.168.0.0/16.

Vérifiez que les valeurs sont correctes, puis cliquez sur "Next".

Étape 9 - Mise en place du mesh network sécurisé

Le système va maintenant établir la connexion au mesh network sécurisé. Cette étape connecte le HIN Gateway au mesh network et synchronise les certificats.

Patientez jusqu'à la fin du processus. Les indicateurs d'état afficheront "Up" lorsque la connexion sera établie avec succès. Cliquez sur "Finish".

Si la connexion échoue

Si l'état de l'Iris Agent ou de la synchronisation des certificats reste "Down":

• Vérifiez que le port 19818 (TCP/UDP) est ouvert dans votre pare-feu (voir "Étape 2 - WireGuard").
• Vérifiez que l'adresse IP indiquée à l'"Étape 8 - Configuration du mesh network" est correcte et accessible depuis Internet.
• Relancez le processus ou contactez le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740).

Étape 10 - Connexion à Keycloak

Warning

Le port 8180 doit être ouvert pour Keycloak. Il n'est pas nécessaire qu'il soit accessible depuis Internet à l'échelle mondiale. En revanche, il doit être accessible entre votre ordinateur d'administration et la machine virtuelle (VM) que vous installez. Dans le cas contraire, vous ne pourrez pas vous connecter à Keycloak ni poursuivre l'installation.

Que faire si une erreur de connexion s'affiche ?

Vérifiez que le port 8180 est accessible depuis votre ordinateur vers la VM. Une fois la configuration mise à jour, retournez à l'interface utilisateur à l'adresse https://<VM IP address> et cliquez sur le bouton "Login".

Une fois le mesh network établi, vous serez redirigé vers la page de connexion à Keycloak. Saisissez le nom d'utilisateur et le mot de passe fournis par HIN.

Question

Si vous ne disposez pas de ces identifiants, veuillez contacter le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740). Veuillez consulter la Section Support.

Cliquez ici pour envoyer un e-mail

Étape 11 - Mettre à jour le mot de passe

Lors de votre première connexion, vous serez invité à modifier votre mot de passe. Saisissez un nouveau mot de passe sécurisé et confirmez-le.

Veuillez vous assurer de bien mémoriser le mot de passe !

Étape 12 - Mise à jour des informations de compte

Complétez votre profil de compte en saisissant votre prénom et votre nom. L'adresse e-mail est préremplie. Cliquez sur "Submit" pour continuer.

Étape 13 - Configuration initiale et configuration du domaine

Info

Pour une migration à domaines multiples, effectuez l'opération pour chaque domaine que vous activez à ce moment-là.

Sur cet écran, configurez vos paramètres initiaux:

• Vérifiez que tous vos domaines de confiance actuels au sein de la communauté HIN s'affichent correctement.
• Sélectionnez le ou les domaines de confiance qui doivent être Enabled pour obtenir des certificats de pair auprès de l'autorité de certification HIN (HIN CA).
• Indiquez pour quel(s) domaine(s) le préfixe sec.<domain> est déjà configuré ("Use sec-prefix").

Comment vérifier si mon domaine est configuré avec un Security Prefix ?

Ouvrez notre outil en ligne dans votre navigateur : https://trust.hin.ls-infra.me/, saisissez sec.<domain> et cliquez sur le bouton Check. Si le message suivant s'affiche :

✅ Ce domaine est chiffré.

Alors votre domaine est configuré avec un Security Prefix et vous devez activer l'option Use sec-prefix.

• Vérifiez que le nom de l'organisation et les propriétaires du domaine sont corrects.
  
  
• Importez le fichier de certificat S/MIME existant (.p12/.pfx) depuis le MGW existant:
  1. Développez le domaine et sélectionnez l'option P12/PFX File.
  2. Si aucun mot de passe n'a été défini pour le fichier de certificat, laissez le champ mot de passe vide.
  3. Cliquez sur "Import Certificate".
  4. Une fois le certificat importé, le message Certificate imported successfully s'affiche.
• Cliquez sur "Save Configuration" en bas de la page pour enregistrer les modifications.

Warning

• Au moins un domaine doit être Enabled pour poursuivre le processus d'intégration. Le bouton "Save configuration" ne sera actif qu'une fois cette condition remplie.
• Si vous constatez que tous les domaines de confiance ne s'affichent pas ou que les informations relatives à l'organisation sont incorrectes, veuillez contacter le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740).

Importez votre clé privée existante

Note : applicable en cas de scénario de migration !

Si vous n'importez pas la clé privée de votre MGW existant, une nouvelle clé sera générée. Cela peut entraîner l'impossibilité de déchiffrer les messages pendant une durée pouvant aller jusqu'à 6 heures, ce qui pourrait entraîner une perte de données.

Paramètre	Description
Nom d'hôte du serveur de messagerie	Le FQDN de cette instance de passerelle de messagerie (par exemple, mail.example.com).
Adresses IP du serveur de messagerie	La ou les adresses IP publiques de ce serveur. Ajoutez des adresses IP supplémentaires si le serveur est accessible via plusieurs adresses.
DNS	Le DNS de l'hôte qui sera utilisé pour résoudre les enregistrements MX et autres enregistrements DNS. Veuillez vous assurer que le serveur DNS saisi est accessible depuis la VM HIN Gateway.

Scénario de migration progressive multi-domaine

Pendant la session de support à la migration, les ingénieurs HIN aideront le client à migrer un domaine. Une fois le premier domaine migré avec succès, le client est responsable de la migration des domaines restants de manière autonome.

Étape 14 - Configurer le transport du courrier

Vous serez connecté au tableau de bord du HIN Gateway sur la page Domains

Page Domains

Info

Pour une migration à domaines multiples, effectuez l'opération pour chaque domaine actif.

Dans le menu Domains, pour chaque domaine disponible, vous pouvez configurer une route de transport spécifique:

Paramètre	Description
Inbound relay	Le relais SMTP qui reçoit les e-mails entrants du domaine sélectionné. Vous pouvez définir des règles de routage basées sur le domaine de l'expéditeur (domaine externe) afin de contrôler où les messages entrants sont livrés
Outbound relay	Le relais SMTP pour les e-mails sortants du domaine sélectionné. Après avoir traité un message, la passerelle le transmet à ce serveur comme prochain saut, en fonction du domaine local configuré. Note de migration : ce paramètre correspond à Forwarding server dans l'ancien MGW.
Trusted networks	Réseaux supplémentaires autorisés à relayer via cette passerelle. Pour plus d'informations, consultez l'"Étape 18 - Configurer le serveur de messagerie"
Configure TLS	Paramètres du certificat TLS pour les connexions SMTP ; le bouton Generate TLS certificate permet de générer un certificat TLS
Email authentication	Pour tous les paramètres de la section Email authentication, veuillez consulter la section Email authentication (DKIM ARC SPF DMARC)

Comment tester une connexion TLS ?

Vous pouvez toujours vérifier si le certificat TLS configuré a été appliqué à votre connexion au HIN Gateway. Exécutez la commande suivante directement depuis le terminal du HIN Gateway :

openssl s_client -connect 127.0.0.1:25 -starttls smtp -servername mail.<YOUR_DOMAIN>

Ou directement depuis votre machine locale :

openssl s_client -connect <HIN Gateway IP>:25 -starttls smtp -servername mail.<YOUR_DOMAIN>

La sortie affichera toutes les informations relatives à votre connexion TLS et au certificat utilisé.

Comment convertir un certificat TLS de pfx en pem ?

Utilisez la commande openssl suivante :

openssl pkcs12 -in <Certificate>.pfx -out <Certificate>.pem -nodes

Par exemple :

openssl pkcs12 -in certificate.pfx -out keyStore.pem -nodes
# Il est parfois nécessaire d'ajouter l'argument -legacy sur les systèmes utilisant d'anciens générateurs de certificats
openssl pkcs12 -in certificate.pfx -out keyStore.pem -nodes -legacy

Actions supplémentaires:

• Ajoutez des domaines supplémentaires en cliquant sur "Add domain", si nécessaire.
  • si un domaine n'est pas sécurisé par HIN, il apparaîtra dans la liste Domains avec le type Routed, ce qui signifie qu'il ne peut être géré que localement

Note

Assurez-vous que toutes les configurations des hôtes de relais et des domaines sont correctes avant de continuer.

Une fois la configuration vérifiée et terminée, cliquez sur "Save" pour continuer.

Page Settings

Sur cette page, dans le menu Settings, configurez les paramètres globaux de transport du courrier pour la mise en place du relais de messagerie sécurisé, communs à toute l'instance. La configuration détaillée de chaque domaine peut être effectuée sous Domains -> $domain

Les paramètres suivants sont disponibles dans le menu Settings:

Paramètre	Description
Nom d'hôte du serveur de messagerie	Le FQDN de cette instance de passerelle de messagerie (par exemple, mail.example.com).
Adresses IP du serveur de messagerie	La ou les adresses IP publiques de ce serveur. Ajoutez des adresses IP supplémentaires si le serveur est accessible via plusieurs adresses.
Serveur DNS	Le DNS de l'hôte qui sera utilisé pour résoudre les enregistrements MX et autres enregistrements DNS. Veuillez vous assurer que le serveur DNS saisi est accessible depuis la VM HIN Gateway.
Default inbound relay	Le relais SMTP qui reçoit les e-mails entrants du domaine sélectionné. Vous pouvez définir des règles de routage basées sur le domaine de l'expéditeur (domaine externe) afin de contrôler où les messages entrants sont livrés
Default outbound relay	Le relais SMTP pour les e-mails sortants du domaine sélectionné. Après avoir traité un message, la passerelle le transmet à ce serveur comme prochain saut, en fonction du domaine local configuré. Note de migration : ce paramètre correspond à Forwarding server dans l'ancien MGW.

Étape 15 - Configurer les whitelist headers

Info

Pour une configuration à domaines multiples, effectuez l'opération pour chaque domaine actif.

Cliquez sur "Domains" -> "Select domain", puis sélectionnez "Whitelist headers".

Saisissez la clé exactement telle qu'elle a été configurée sur le serveur de messagerie.

Étape 16 - Certificats de pairs

Les certificats de pairs sont émis par l'autorité de certification HIN (HIN CA) pour les domaines activés.

Une fois l'intégration terminée, accédez à la section "Peer certificates" du dashboard et cliquez sur le bouton "Sync certificates" pour synchroniser vos certificats de pairs depuis l'autorité de certification HIN.

Étape 17 - Valider les certificats de pairs

Assurez-vous que votre domaine a bien reçu son certificat de pair basé sur une politique en bas de "Domains" -> "nom du domaine". Le statut de chaque domaine doit être "Good".

Question

Contactez le support HIN par e-mail ou par téléphone (support@hin.ch / 0848 830 740) si vous rencontrez des problèmes.

Étape 18 - Configurer le serveur de messagerie et le HIN Gateway

Si vous avez suivi la procédure recommandée, à savoir exporter la clé privée, l'importer dans le HIN Gateway et conserver la même adresse IP que celle du MGW existant, aucune modification n'est nécessaire sur le serveur de messagerie.

Sinon, configurez votre serveur de messagerie ou les composants associés de manière à ce que le trafic soit acheminé via le nouveau HIN Gateway. Vérifiez et mettez à jour les paramètres suivants si nécessaire:

Serveur de messagerie

• Relais SMTP / hôte intelligent
• Connecteurs
• Règles de transport
• Domaines de routage

Voir Intégration à Exchange pour obtenir des instructions détaillées.

Configuration du HIN Gateway

Page Domains

Info

Pour une migration à domaines multiples, effectuez l'opération pour chaque domaine actif.

Dans le menu Domains, pour chaque domaine disponible, vous pouvez configurer une route de transport spécifique:

Paramètre	Description
Inbound relay	Le relais SMTP qui reçoit les e-mails entrants du domaine sélectionné. Vous pouvez définir des règles de routage basées sur le domaine de l'expéditeur (domaine externe) afin de contrôler où les messages entrants sont livrés
Outbound relay	Le relais SMTP pour les e-mails sortants du domaine sélectionné. Après avoir traité un message, la passerelle le transmet à ce serveur comme prochain saut, en fonction du domaine local configuré. Note de migration : ce paramètre correspond à Forwarding server dans l'ancien MGW.
Trusted networks	Réseaux supplémentaires autorisés à relayer via cette passerelle. Pour plus d'informations, consultez l'"Étape 18 - Configurer le serveur de messagerie"
Configure TLS	Paramètres du certificat TLS pour les connexions SMTP ; le bouton Generate TLS certificate permet de générer un certificat TLS
Email authentication	Pour tous les paramètres de la section Email authentication, veuillez consulter la section Email authentication (DKIM ARC SPF DMARC)

• Note : pour un scénario de migration : Accédez à la page de chaque domaine et ajoutez un Outbound host en utilisant la valeur relevée dans le champ Forwarding server du MGW à l'"Étape 1.2 - Sauvegarde du MGW existant".

• Si vous utilisez Microsoft 365 / Exchange Online, ajoutez ses plages d'adresses IP sortantes publiées dans Trusted networks, afin que le HIN Gateway fasse confiance aux e-mails provenant d'Exchange Online et les relaie:

  40.92.0.0/15
  40.107.0.0/16
  51.4.72.0/24
  51.4.80.0/27
  51.5.72.0/24
  51.5.80.0/27
  52.100.0.0/14
  104.47.0.0/17
  2a01:111:f400::/48
  2a01:111:f403::/48
  2a01:4180:4050:400::/64
  2a01:4180:4050:800::/64
  2a01:4180:4051:400::/64
  2a01:4180:4051:800::/64
  

Page Settings

Sur cette page, dans le menu Settings, configurez les paramètres globaux de transport du courrier pour la mise en place du relais de messagerie sécurisé, communs à toute l'instance. La configuration détaillée de chaque domaine peut être effectuée sous Domains -> $domain

Les paramètres suivants sont disponibles dans le menu Settings:

Paramètre	Description
Nom d'hôte du serveur de messagerie	Le FQDN de cette instance de passerelle de messagerie (par exemple, mail.example.com).
Adresses IP du serveur de messagerie	La ou les adresses IP publiques de ce serveur. Ajoutez des adresses IP supplémentaires si le serveur est accessible via plusieurs adresses.
Serveur DNS	Le DNS de l'hôte qui sera utilisé pour résoudre les enregistrements MX et autres enregistrements DNS. Veuillez vous assurer que le serveur DNS saisi est accessible depuis la VM HIN Gateway.
Default inbound relay	Le relais SMTP par défaut qui reçoit les e-mails entrants du domaine sélectionné. Vous pouvez définir des règles de routage basées sur le domaine de l'expéditeur (tout domaine externe) afin de contrôler où les messages entrants sont livrés. Il sert de solution de repli pour tous les domaines.
Default outbound relay	Le relais SMTP par défaut pour les e-mails sortants. Après avoir traité un message, la passerelle le transmet à ce serveur comme prochain saut. Il sert de solution de repli pour tous les domaines.

Étape 19 - Tester et valider

Courrier sortant:

• Vérifiez que le serveur de messagerie est configuré pour envoyer des e-mails au HIN Gateway à l'aide d'un relais SMTP ou d'un connecteur Exchange.
• Vérifiez que le HIN Gateway peut envoyer des e-mails à des destinataires situés en dehors de la communauté HIN.
• Vérifiez que le HIN Gateway peut envoyer des e-mails à des destinataires au sein de la communauté HIN via WireGuard.
• Envoyez un e-mail depuis la communauté HIN vers une adresse e-mail externe (par exemple Bluewin, Gmail, Yahoo ou GMX) avec la mention (confidentiel) dans l'objet, et vérifiez qu'il est bien remis.

Messages (Confidentiel) en dehors de la communauté HIN

Si, pendant le test et la validation, vous utilisez Outlook pour envoyer des e-mails confidentiels en dehors de la communauté HIN à l'aide de l'une des méthodes suivantes: * Utilisation d'un modèle d'e-mail spécifique * Utilisation du symbole de cadenas (Key Lock)

Veuillez suivre les instructions ci-dessous: * Si vous utilisez un modèle d'e-mail spécifique, assurez-vous que le modèle est mis à jour afin que les e-mails sécurisés soient correctement traités par le HIN Gateway. * Si vous utilisez le symbole de cadenas (Key Lock), indiquez temporairement « (confidentiel) » dans l'objet à la place.

HIN développe actuellement la prise en charge de l'intégration Outlook. Cette fonctionnalité devrait être disponible dans une prochaine version. Après avoir effectué les modifications nécessaires, testez à nouveau le flux de messagerie et confirmez que l'e-mail est traité et remis avec succès après la migration.

Courrier entrant:

• Vérifiez que les e-mails chiffrés provenant de la communauté HIN peuvent être reçus via WireGuard. Un expéditeur du domaine hin.ch constitue le scénario de test le plus simple.
• Vérifiez que les e-mails chiffrés provenant de la communauté HIN peuvent être reçus via SMTP à l'aide de S/MIME.
• Vérifiez que les réponses provenant d'expéditeurs extérieurs à la communauté HIN à un e-mail sécurisé initial (HIN Mail-SEAL) parviennent au HIN Gateway.
• Vérifiez que les e-mails en texte clair provenant d'expéditeurs externes à la communauté HIN peuvent être reçus.
• Envoyez un e-mail depuis une adresse e-mail externe vers la communauté HIN et vérifiez qu'il est bien reçu.

Confirmer:

• Les e-mails sont remis avec succès dans les deux sens entre le domaine de confiance HIN et les adresses e-mail externes.
• Le chiffrement est appliqué lorsque requis.
• Aucun retard ni rejet inattendu.
• L'enregistrement (logging) fonctionne correctement.

Remplissez le Formulaire de réception et renvoyez-le à votre représentant HIN.

Étape 20 - Modifier le mot de passe de la machine virtuelle

Veuillez vous assurer que les identifiants de la machine virtuelle qui vous ont été fournis initialement sont remplacés par un mot de passe de votre choix, et conservez-les dans un endroit sûr et sécurisé.

Étape 21 - Mise hors service du MGW existant

Info

Cette étape s'applique uniquement aux migrations à domaine unique et à domaines multiples

Warning

Ne supprimez pas immédiatement la machine virtuelle MGW existante ; conservez-la en lieu sûr jusqu'à ce que tout soit opérationnel.

1. Assurez-vous qu'il n'y a pas de trafic actif - Vérifiez:
   • Aucun domaine ne pointe vers le MGW (DNS, SMTP, connecteurs).
   • Aucun e-mail n'est transféré via l'ancienne appliance.
2. Archivez les journaux - Exportez et enregistrez:
   • Journaux des e-mails
   • Journaux de sécurité/d'audit
   • Requis pour la conformité et le dépannage
3. Nettoyage (facultatif) - Supprimer:
   • Règles de pare-feu
   • Entrées DNS
   • Configurations de routage faisant référence au MGW existant

Annexe 1 - Sauvegarde et restauration des paramètres de l'appliance

Info

Cette étape s'applique uniquement aux migrations à domaine unique et à domaines multiples

Pour sauvegarder ou restaurer les paramètres de votre appliance HIN, cliquez sur le menu "Administration" dans le portail d'administration Web.

Sauvegarde des paramètres

Avant de créer une sauvegarde des paramètres actuels de votre appliance HIN, vous devez définir un mot de passe de sauvegarde. Ce mot de passe est nécessaire si vous devez restaurer la sauvegarde ultérieurement.

• Pour définir ou modifier le mot de passe de sauvegarde, cliquez sur "Change Password".
• Pour créer et télécharger un fichier de sauvegarde, cliquez sur "Download".

Modification du mot de passe de sauvegarde

Pour modifier le mot de passe des futures sauvegardes, cliquez sur "Change Password".

Note

Veuillez noter que le nouveau mot de passe ne s'applique qu'aux sauvegardes créées après la modification du mot de passe. Les fichiers de sauvegarde existants restent protégés par le mot de passe défini lors de leur création.

Restauration des paramètres

Pour restaurer les paramètres de l'appliance à partir d'un fichier de sauvegarde, cliquez sur "Import Backup File...".

Dans la fenêtre de dialogue, sélectionnez le fichier de sauvegarde souhaité et saisissez le mot de passe associé à cette sauvegarde. Les paramètres de l'appliance seront alors restaurés à partir du fichier de sauvegarde sélectionné.

Sauvegarde via SCP

Le MGW prend en charge la sauvegarde de l'appliance via SCP.

Pour utiliser cette option, la clé publique du système qui accédera au MGW doit être enregistrée sous "Backup using SCP". La sauvegarde est générée automatiquement tous les jours à minuit et est stockée sur le MGW sous le nom backup.tgz.

À l'aide de la clé publique configurée, le fichier de sauvegarde peut être récupéré via SCP par l'utilisateur backup du système d'exploitation. Une commande SCP type pour récupérer le fichier de sauvegarde est la suivante:

scp backup@192.168.1.60:/backup.tgz .

Cette commande télécharge le fichier backup.tgz depuis le MGW vers le répertoire local actuel.

Note

Si vous saisissez une nouvelle clé publique, la clé existante sera remplacée.

Scénario de migration multi-domaines

MGW → HIN Gateway - architecture du flux de messagerie, déploiement par étapes et plan de retour arrière

Phase 1 Début - Situation de référence (tous les domaines sur MGW)

État de référence

• Tous les domaines transitent par MGW. Exemple: domain1.ch, domain2.ch, domain3.ch, un-domain1.ch, un-domain2.ch
• Préparation du déploiement de HIN Gateway - pas encore de trafic en production
• Les enregistrements DNS MX / SPF pointent toujours vers l’adresse IP publique A (MGW) - ceci dans le cas où MGW serait le point d’entrée du trafic ou le dernier MTA

Liste de contrôle préalable

• Établir une situation de référence pour la capacité actuelle de MGW et les journaux des flux de messagerie
• Vérifier la connectivité de Stargate Lab avec Online Protect / Exchange Online / le serveur de messagerie sur site
• Mettre d’accord les parties prenantes sur le calendrier de migration et le plan de communication
• Examiner la documentation relative au pare-feu et aux ports avant l’attribution de l’adresse IP publique B (phase 2, étape 1)

Phase 2 Migration - exemple de migration progressive, domaine par domaine

Étapes de la migration

1. Mettre en service HIN Gateway – attribuer Public IP B et mettre à jour les règles du pare-feu (voir la documentation réseau pour connaître les ports requis)
2. Créer deux connecteurs sur Exchange Online – un connecteur entrant et un connecteur sortant – pointant vers Stargate
3. Ajouter une règle de flux de messagerie qui achemine les e-mails en fonction du domaine: domain1.ch → HIN Gateway, tous les autres domaines restent sur MGW
4. Répéter progressivement – migrer un domaine supplémentaire à la fois jusqu’à ce que tous les domaines soient sur HIN Gateway

Retour arrière (par domaine)

• Rediriger la règle de flux de messagerie du domaine concerné vers MGW
• Laisser les connecteurs Stargate en place pour la prochaine tentative
• Tenir à jour un journal de toutes les modifications apportées aux connecteurs ou aux règles, dans l’ordre – le retour arrière doit suivre cette séquence dans l’ordre inverse

Attention aux en-têtes spécifiques au client

Certains domaines utilisent des en-têtes X personnalisés (routage, listes d’autorisation anti-spam, balises de conformité). Vérifier que les connecteurs de Stargate conservent ou reproduisent ces en-têtes avant de basculer un domaine vers HIN Gateway – des en-têtes manquants peuvent entraîner des erreurs de routage ou le rejet des e-mails.

Phase 3 Fin - migration complète vers HIN Gateway

Warning

Après des tests concluants, veuillez conserver le nouveau HIN Gateway sur l’adresse IP publique B et ne pas modifier cette adresse IP. Un changement de l’adresse IP publique interrompt le tunnel sécurisé, et la passerelle ne reçoit alors plus les mises à jour des certificats.

État final

• Tous les domaines transitent désormais par HIN Gateway
• MGW ne prend en charge aucun trafic de production
• Les enregistrements DNS / SPF pointent désormais vers l’adresse IP publique B (au cas où HIN Gateway serait le point d’entrée du trafic ou le dernier MTA)

Liste de contrôle de finalisation

• Supprimer les anciens connecteurs MGW et les règles de flux de messagerie
• Mettre hors service la VM MGW une fois que la surveillance confirme l’absence de trafic et le bon fonctionnement du flux de messagerie
• Libérer l’adresse IP publique A si elle n’est plus nécessaire
• Mettre à jour les runbooks et la documentation DNS

Approche de migration recommandée selon le nombre de domaines

Clients avec 3 domaines ou moins

• HIN recommande de migrer tous les domaines en une seule fois.
• HIN accompagnera le client dans la migration réussie du premier domaine.
• Une fois le premier domaine migré avec succès, le client peut migrer les domaines restants de manière autonome.
• Cette approche permet de garder la migration simple et évite la nécessité d’un environnement parallèle.

Clients avec plus de 3 domaines

• HIN recommande de mettre en place un environnement parallèle à côté du MGW existant.
• Les domaines peuvent ensuite être migrés progressivement vers le nouvel environnement.
• HIN accompagnera le client dans la migration réussie du premier domaine.
• Après la première migration réussie, le client peut décider comment et quand transférer les domaines restants vers le nouvel environnement.

---

Warning

Avant de procéder à toute étape d’installation, vérifier que les ports exacts du pare-feu et les paramètres des connecteurs correspondent à la documentation réseau actuelle.

Note

Consulter les remarques spécifiques figurant dans le Guide d’installation du domaine concernant la migration multi-domaines.

Configuration technique et Intégration

Aperçu des applications

Applications

• smimekeys-client - Service client de clés S/MIME (port 8081)
• policy - Service de politiques (port 8082)
• irisagent - Service IRIS Agent (port 8083, WireGuard: 19818/udp, 19818/tcp)
• mxengine - Service MX Engine (port 8084, SMTP: 1587)
• stalwart - Serveur mail Stalwart MTA (port 25, 10026)
• clamav - Antivirus ClamAV ; analyse les courriels au stade SMTP DATA de Stalwart via le protocole milter (port 7357)
• mtaconf - Démon de configuration MTA (API: 8080)
• dashboard - Interface d'administration web pour l'intégration, la gestion des domaines et la surveillance (port 443)
• policy-sync - Synchronise les politiques OPA/Rego du dépôt Git vers la base de données (s'exécute en continu)

Infrastructure

• PostgreSQL - Base de données (port 5432)
• Vault - Gestion des secrets (port interne 8200, non publié sur l'hôte)
• MinIO - Stockage compatible S3 (API sur le port hôte 9000 ; console non publiée sur l'hôte)
• Keycloak - Fournisseur d'identité et authentification OIDC (port 8180)
• APISIX - Passerelle API avec authentification OIDC bearer (port 9080)
• NATS - Messagerie inter-services (déclenche les rechargements de Stalwart depuis le tableau de bord)

Conteneurs d'initialisation

• vault-init - Initialise et désceau Vault lors du premier démarrage
• seaweedfs-init - Crée le bucket S3
• apisix-init - Génère la configuration APISIX à partir du modèle
• keycloak-init - Définit le mot de passe administrateur initial

Surveillance

• node-exporter - Métriques de l'hôte pour Prometheus (port 9100)
• version-collector - Collecte les versions des applications depuis les points de terminaison /liveness pour node-exporter
• Alloy - Collecteur de logs pour Loki (transporte les logs des applications)
• Dozzle - Visualisateur de logs de conteneurs en temps réel (port 8190, HTTPS, derrière le SSO Keycloak via oauth2-proxy ; optionnel, activé avec DOZZLE_ENABLED)
• oauth2-proxy - Partie fiable OIDC qui authentifie l'accès Dozzle auprès de Keycloak (démarre avec Dozzle)

Voir Surveillance et Logs pour une configuration détaillée et l'utilisation.

Aperçu de l'architecture

Aperçu de l'architecture VM

Surveillance et Logs

Stargate inclut des services intégrés de surveillance et de collecte de logs qui fonctionnent aux côtés des conteneurs d'application.

Composants

Service	Port	Objectif
node-exporter	9100	Métriques au niveau de l'hôte (CPU, mémoire, disque, réseau) pour Prometheus
version-collector	-	Collecte les versions des applications depuis les points de terminaison /liveness
Alloy	12345	Collecteur de logs Docker - envoie les logs des conteneurs à Loki
Loki	3100 (interne)	Backend d'agrégation de logs local
Dozzle	8190	Visualisateur de logs de conteneurs basé sur le web (HTTPS, SSO Keycloak ; optionnel)
oauth2-proxy	8190	Partie fiable OIDC qui authentifie l'accès Dozzle (avec Dozzle)

---

Dozzle - Visualisateur de logs local

Dozzle fournit une interface web pour visualiser les logs en temps réel de tous les conteneurs Stargate. Il est optionnel et activé en définissant DOZZLE_ENABLED="true" dans customer-config.sh.

L'accès est protégé par Keycloak: un oauth2-proxy se place devant Dozzle et nécessite la même connexion que le tableau de bord (le domaine stargate). Dozzle lui-même n'est pas exposé directement.

Accès : ouvrez https://<IP_SERVEUR>:8190 dans un navigateur et connectez-vous avec vos identifiants HIN Gateway (Keycloak).

Note

Le port 8190 (HTTPS) doit être accessible depuis votre réseau. Si vous restreignez l'accès par IP ou pare-feu, autorisez 8190/tcp comme vous le faites pour le tableau de bord et Keycloak.

Les logs sont organisés par service. En sélectionnant un service spécifique, vous pouvez visualiser ses entrées de logs et détails correspondants.

---

Grafana Alloy - Transfert de logs

Grafana Alloy collecte les logs de tous les conteneurs d'application Stargate et les écrit dans l'instance Loki locale. Optionnellement, les logs peuvent également être transférés vers un point de terminaison distant compatible Loki pour une surveillance centralisée.

Comment cela fonctionne

1. Alloy découvre les conteneurs Stargate via le socket Docker
2. Les logs sont toujours écrits dans l'instance Loki locale (utilisée par le tableau de bord pour l'exportation des logs)
3. Si une URL Loki distante est configurée, les logs sont également transférés vers ce point de terminaison

Configurer le transfert de logs à distance

Depuis le tableau de bord HIN Gateway, accédez à la page Paramètres. Dans la section Grafana Alloy, entrez l'URL de poussée Loki de votre serveur de collecte de logs distant:

L'URL doit suivre le format standard de l'API de poussée Loki:

https://logs.example.com/loki/api/v1/push

Laissez le champ vide pour désactiver le transfert de logs à distance.

Note

Les modifications prennent effet dans un délai d'1 minute (Alloy interroge la configuration du tableau de bord à cet intervalle). Aucun redémarrage de conteneur n'est nécessaire.

Exigences du côté distant

Votre point de terminaison Loki distant doit être accessible depuis le serveur Stargate via HTTPS (port 443). Si vous utilisez une liste d'autorisation basée sur IP sur votre entrée, ajoutez l'IP publique du serveur Stargate.

---

Métriques Prometheus

Stargate expose des points de terminaison de métriques compatibles Prometheus depuis ses conteneurs d'application. Ceux-ci peuvent être récupérés par tout serveur compatible Prometheus pour une collecte centralisée des métriques.

Points de terminaison disponibles

Service	Port	Chemin
smimekeys-client	2113	/metrics
irisagent	2114	/metrics
policy	2115	/metrics
mxengine	2116	/metrics
node-exporter	9100	/metrics
APISIX	9091	/apisix/prometheus/metrics

Configuration de récupération

Ajoutez le serveur Stargate comme cible dans votre configuration Prometheus. Exemple pour une instance unique:

scrape_configs:
  - job_name: 'stargate-<name>-smimekeys'
    static_configs:
      - targets: ['<STARGATE_IP>:2113']
        labels:
          environment: 'stargate-<name>'
          service: 'smimekeys-client'
    metrics_path: /metrics

  - job_name: 'stargate-<name>-irisagent'
    static_configs:
      - targets: ['<STARGATE_IP>:2114']
        labels:
          environment: 'stargate-<name>'
          service: 'irisagent'
    metrics_path: /metrics

  - job_name: 'stargate-<name>-policy'
    static_configs:
      - targets: ['<STARGATE_IP>:2115']
        labels:
          environment: 'stargate-<name>'
          service: 'policy'
    metrics_path: /metrics

  - job_name: 'stargate-<name>-mxengine'
    static_configs:
      - targets: ['<STARGATE_IP>:2116']
        labels:
          environment: 'stargate-<name>'
          service: 'mxengine'
    metrics_path: /metrics

  - job_name: 'stargate-<name>-node'
    static_configs:
      - targets: ['<STARGATE_IP>:9100']
        labels:
          environment: 'stargate-<name>'
          service: 'node-exporter'
    metrics_path: /metrics

Remplacez <IP_STARGATE> par l'IP publique ou privée du serveur et <nom> par un identifiant de déploiement (ex. prod, nom-client).

Tip

Les étiquettes environment et service permettent le filtrage dans les tableaux de bord Grafana sur plusieurs instances Stargate.

Exigences de pare-feu

Les ports de métriques (2113-2116, 9091, 9100) ne comportent aucune authentification. Restreignez-les afin qu'ils soient accessibles uniquement depuis votre serveur Prometheus, et jamais depuis Internet.

Si vous autorisez l'accès par IP, ajoutez uniquement l'IP de votre serveur de surveillance.

---

Node Exporter

Le service node-exporter expose des métriques standard au niveau de l'hôte (CPU, mémoire, E/S disque, réseau) sur le port 9100. Il inclut également un collecteur de fichiers texte qui expose des métriques personnalisées du sidecar version-collector (informations de version des applications).

---

Résumé des ports exposés

Port	Service	Protocole	Objectif
8190	Dozzle (via oauth2-proxy)	HTTPS	Interface de visualisation des logs authentifiée (SSO Keycloak)
9100	node-exporter	HTTP	Métriques de l'hôte (Prometheus)
2113	smimekeys-client	HTTP	Métriques de l'application (Prometheus)
2114	irisagent	HTTP	Métriques de l'application (Prometheus)
2115	policy	HTTP	Métriques de l'application (Prometheus)
2116	mxengine	HTTP	Métriques de l'application (Prometheus)
9091	APISIX	HTTP	Métriques de la passerelle (Prometheus)

Intégration Exchange avec HIN Gateway

Ce guide explique comment configurer Microsoft Exchange (Online et On-Premises) pour acheminer les courriels via la passerelle HIN Gateway pour la signature et le chiffrement S/MIME.

Aperçu

HIN Gateway agit comme un relais de courrier entre les serveurs de courrier externes et votre environnement Exchange. Deux modèles d'intégration sont pris en charge:

Modèle A - Exchange Online comme MX principal avec règles de transport :

flowchart LR
    I1 --> EO --> TR --> C --> S1 --> EO
    E2 --> TR2 --> OC --> S2 --> I2
    I1["Internet"]
    I2["Internet"]
    EO["Exchange Online"]
    E2["Exchange Online"]
    TR["Règle de transport"]
    TR2["Règle de transport"]
    OC["Connecteur sortant"]
    C["Connecteur"]
    S1["HIN Gateway"]
    S2["HIN Gateway"]

Modèle B - HIN Gateway comme MX principal:

flowchart LR
    I1 --> mx15 --> mx20
    EO --> TR --> OC --> HG --> I2
    I1["Internet"]
    I2["Internet"]
    mx15["HIN Gateway (priorité MX 15)"]
    mx20["Exchange Online (priorité MX 20)"]
    EO["Exchange Online"]
    TR["Règle de transport"]
    OC["Connecteur sortant"]
    HG["HIN Gateway"]

Dans les deux modèles, vous avez besoin de:

1. Enregistrements DNS pointant vers le serveur HIN Gateway
2. Connecteur sortant - achemine les courriels d'Exchange vers HIN Gateway
3. Connecteur entrant - accepte les courriels de HIN Gateway dans Exchange
4. Règle de transport - déclenche le connecteur sortant pour les destinataires externes

Prérequis

Avant de configurer Exchange, assurez-vous que:

• HIN Gateway est installé et en cours d'exécution (instructions de déploiement)
• Vous disposez de l'adresse IP publique du serveur HIN Gateway (référencée ci-dessous comme <HIN Gateway_IP>)
• Vous disposez du nom d'hôte de courrier du serveur HIN Gateway (référencé ci-dessous comme <MAIL_HOSTNAME>, ex. mail.example.com)
• Vous connaissez votre domaine de courrier (référencé ci-dessous comme <YOUR_DOMAIN>, ex. example.com)
• Vous avez un accès admin Exchange (Centre d'administration Exchange ou Shell de gestion Exchange sur site)
• Les enregistrements DNS sont configurés selon le Guide de configuration DNS (A, MX, SPF au minimum)

---

Partie 1: Configuration DNS

Consultez le Guide de configuration DNS pour des instructions complètes sur la configuration des enregistrements A, MX, SPF, PTR, DMARC et DKIM.

Au minimum, avant de procéder à la configuration Exchange ci-dessous, vous avez besoin de:

• Enregistrement A: <MAIL_HOSTNAME> pointant vers <HIN Gateway_IP>
• Enregistrement MX: <YOUR_DOMAIN> avec HIN Gateway à une priorité plus élevée (nombre inférieur) qu'Exchange
• Enregistrement SPF: ip4:<HIN Gateway_IP> et ip4:<HIN_SEALER_IP> ajoutés à l'enregistrement TXT de votre domaine (voir Guide de configuration DNS - SPF pour les IPs du scelleur)

---

Partie 2: Configuration Exchange Online

Étape A: Créer le connecteur sortant (Office 365 → HIN Gateway)

Ce connecteur achemine les courriels sortants d'Exchange Online vers le serveur relais HIN Gateway.

1. Accédez au Centre d'administration Exchange - Connecteurs

2. Cliquez sur "+ Ajouter un connecteur"

3. Connexion depuis: Sélectionnez "Office 365"

4. Connexion vers: Sélectionnez "Serveur de courrier de votre organisation"

5. Cliquez sur "Suivant"

6. Nom du connecteur: Entrez un nom descriptif, ex.:

From Office 365 to HIN Gateway relay server

• Cochez "Conserver les en-têtes de courrier internes Exchange"

• Cliquez sur "Suivant"

• Utilisation du connecteur: Sélectionnez "Uniquement lorsque j'ai une règle de transport configurée qui redirige les messages vers ce connecteur"

• Cliquez sur "Suivant"

Tip

Ceci est important - le connecteur n'acheminera aucun courrier par lui-même. Il ne sera utilisé que lorsqu'il sera déclenché par la règle de transport créée à l'étape C.

1. Routage: Sélectionnez "Acheminer les courriels via ces hôtes intelligents"
2. Entrez l'adresse IP du serveur HIN Gateway: <HIN Gateway_IP>

3. Cliquez sur "+" pour l'ajouter, puis sur "Suivant"

4. Restrictions de sécurité: Sélectionnez "Tout certificat numérique, y compris les certificats auto-signés"

5. Cliquez sur "Suivant"

Note

Le MTA de HIN Gateway (Stalwart) accepte TLS opportuniste sur les connexions entrantes. Sélectionner "tout certificat numérique" assure la connectivité même avec des certificats auto-signés.

1. Courriel de validation: Entrez une adresse de courrier valide pour votre domaine (ex. user@<YOUR_DOMAIN>)
2. Cliquez sur "+", puis sur "Valider"
3. Attendez que la validation se termine, puis cliquez sur "Suivant"

Tip

Pour que la validation réussisse, le serveur HIN Gateway doit être en cours d'exécution et accepter les courriels sur le port 25.

1. Examinez les paramètres et cliquez sur "Créer un connecteur"

2. Sur l'écran de confirmation, cliquez sur "Terminé"

Étape B: Créer le connecteur entrant (HIN Gateway → Office 365)

Ce connecteur accepte les courriels du serveur relais HIN Gateway dans Exchange Online.

1. Depuis la page Connecteurs, cliquez sur "+ Ajouter un connecteur"

2. Connexion depuis: Sélectionnez "Serveur de courrier de votre organisation"

3. Connexion vers: Affiche "Office 365" (automatique)

4. Cliquez sur "Suivant"

5. Nom du connecteur: Entrez un nom descriptif, ex.:

Receive mail from HIN Gateway relay server

• Cochez "Conserver les en-têtes de courrier internes Exchange"

• Cliquez sur "Suivant"

• Authentification des courriels envoyés: Sélectionnez "En vérifiant que l'adresse IP du serveur d'envoi correspond à l'une des adresses IP suivantes qui appartiennent exclusivement à votre organisation"

• Entrez l'adresse IP du serveur HIN Gateway: <HIN Gateway_IP>
• Cliquez sur "+" pour l'ajouter, puis sur "Suivant"

Note

Cela indique à Exchange Online de faire confiance aux courriels provenant de cette adresse IP spécifique, en contournant les vérifications supplémentaires de spam/authentification pour les courriels déjà traités par HIN Gateway.

1. Examinez les paramètres et cliquez sur "Créer un connecteur"

2. Cliquez sur "Terminé"

Vérifier les connecteurs

Après avoir créé les connecteurs (y compris le connecteur Send to MX de l'étape D), la page Connecteurs devrait afficher:

Statut	Nom	Depuis	Vers
Activé	Receive mail from HIN Gateway relay server	Votre org	O365
Activé	From Office 365 to HIN Gateway relay server	O365	Votre org
Activé	Send to MX	O365	Votre org

Étape C: Créer la règle de transport

La règle de transport redirige tous les courriels sortants via le connecteur sortant HIN Gateway, sauf les courriels provenant de HIN Gateway lui-même (pour éviter les boucles de courrier).

1. Accédez au Centre d'administration Exchange - Règles

2. Cliquez sur "+ Ajouter une règle" → "Créer une nouvelle règle"

3. Nom de la règle: Entrez un nom descriptif, ex.:

Relay all mail to HIN Gateway except mail coming from it

1. Appliquer cette règle si: Sélectionnez "Le destinataire..." → "est externe/interne" → "En dehors de l'organisation"
2. Cliquez sur "Enregistrer"

Note

Cette condition garantit que seuls les courriels sortants (vers des destinataires externes) sont redirigés via HIN Gateway.

1. Faire ce qui suit: Sélectionnez "Rediriger le message vers..." → "le connecteur suivant" → sélectionnez le connecteur sortant créé à l'étape A (ex. "From Office 365 to HIN Gateway relay server")

2. Cliquez sur "Enregistrer"

3. Sauf si: Cliquez sur "+" pour ajouter une exception

4. Sélectionnez "L'expéditeur..." → "L'adresse IP se trouve dans l'une de ces plages"
5. Entrez l'adresse IP du serveur HIN Gateway: <HIN Gateway_IP>
6. Cliquez sur "Ajouter", vérifiez que l'IP est listée, puis cliquez sur "Enregistrer"

Warning

Cette exception est critique - elle empêche les boucles de courrier. Sans elle, les courriels de HIN Gateway arrivant dans Exchange Online seraient redirigés vers HIN Gateway dans une boucle infinie.

1. Examinez le résumé de la règle. Il devrait afficher:
2. Appliquer cette règle si: Le destinataire est situé En dehors de l'organisation
3. Faire ce qui suit: Rediriger le message vers le connecteur "From Office 365 to HIN Gateway relay server"

4. Sauf si: L'adresse IP de l'expéditeur se trouve dans l'une de ces plages: <HIN Gateway_IP>

5. Cliquez sur "Suivant", puis sur "Suivant" à nouveau, puis sur "Terminer", puis sur "Terminé"

6. Activer la règle: La règle est créée dans un état désactivé. Cliquez sur la règle dans la liste et basculez "Activer ou désactiver la règle" sur "Activé"

Tip

N'oubliez pas d'activer la règle - elle ne fonctionnera pas tant qu'elle ne sera pas activée.

Étape D: Outgoing to MX (connecteur Send to MX et règle)

Une fois que HIN Gateway a traité (signé ou chiffré) un message sortant, il le renvoie à Exchange Online via le connecteur entrant de l'étape B. Exchange Online doit ensuite le remettre au serveur de courrier du destinataire. C'est le rôle de la configuration «Outgoing to MX»: un connecteur dédié Send to MX envoie le message au MX du destinataire externe, et la règle de transport outgoing_to_mx redirige les messages traités vers ce connecteur.

Créer le connecteur Send to MX (Office 365 → Organisation partenaire)

1. Depuis la page Connecteurs, cliquez sur "+ Ajouter un connecteur"

2. Connexion depuis: Sélectionnez "Office 365"

3. Connexion vers: Sélectionnez "Organisation partenaire"

4. Cliquez sur "Suivant"

5. Nom du connecteur: Entrez un nom descriptif, ex.:

Send to MX

• Assurez-vous que le connecteur est activé
• Cliquez sur "Suivant"

Note

Le nom du connecteur peut être choisi librement. Si vous utilisez un autre nom, sélectionnez ce nom dans la règle outgoing_to_mx décrite ci-dessous.

1. Utilisation du connecteur: Sélectionnez "Uniquement lorsque j'ai une règle de transport configurée qui redirige les messages vers ce connecteur"
2. Cliquez sur "Suivant"

Tip

Comme le connecteur sortant de l'étape A, ce connecteur n'achemine aucun courrier par lui-même. Il n'est utilisé que lorsque la règle outgoing_to_mx décrite ci-dessous lui redirige un message.

1. Routage: Sélectionnez "Utiliser l'enregistrement MX associé au domaine du partenaire"

2. Cliquez sur "Suivant"

3. Restrictions de sécurité: Laissez "Toujours utiliser TLS (Transport Layer Security) pour sécuriser la connexion" décoché, afin qu'aucune restriction de sécurité ne s'applique

4. Cliquez sur "Suivant"

Note

Ce connecteur remet le courrier à n'importe quel destinataire externe. Exiger TLS ou un certificat précis bloquerait la remise vers les serveurs destinataires qui ne remplissent pas ces conditions.

1. Courriel de validation: Entrez une adresse de courrier externe (en dehors de votre organisation)
2. Cliquez sur "+", puis sur "Valider"

3. Attendez que la validation se termine, puis cliquez sur "Suivant"

4. Examinez les paramètres et cliquez sur "Créer un connecteur"

5. Cliquez sur "Terminé"

Le résumé du connecteur devrait afficher:

• Scénario de flux de courrier: Depuis Office 365, vers Organisation partenaire
• Nom: Send to MX
• Statut: Activé
• Utilisation du connecteur: Utiliser uniquement lorsque j'ai une règle de transport configurée qui redirige les messages vers ce connecteur
• Routage: Utiliser l'enregistrement MX associé au domaine du partenaire
• Restrictions de sécurité: Aucune

Créer la règle de transport outgoing_to_mx

Cette règle redirige vers le connecteur Send to MX les messages sortants qui reviennent de HIN Gateway. Elle reconnaît ces messages grâce à l'en-tête outgoing.

1. Accédez au Centre d'administration Exchange - Règles

2. Cliquez sur "+ Ajouter une règle" → "Créer une nouvelle règle"

3. Nom de la règle: Entrez:

outgoing_to_mx

1. Appliquer cette règle si: Sélectionnez "Les en-têtes du message..." → "correspondent à ces modèles de texte"
2. Nom de l'en-tête: outgoing
3. Modèle de texte: outgoing_<YOUR_DOMAIN> (ex. outgoing_example.com)
4. Cliquez sur "Enregistrer"

Note

L'en-tête outgoing doit déjà figurer dans le message lorsqu'il revient de HIN Gateway. Dans la configuration de référence HIN, il est ajouté par une règle distincte (set_header), qui s'applique lorsque l'expéditeur se trouve dans l'organisation et définit l'en-tête outgoing avec la valeur outgoing_<YOUR_DOMAIN>. Sans cet en-tête, la règle outgoing_to_mx ne s'applique jamais.

1. Faire ce qui suit: Sélectionnez "Rediriger le message vers" → "le connecteur suivant" → sélectionnez "Send to MX"

2. Cliquez sur "Enregistrer"

3. Sauf si: Laissez vide

4. Cliquez sur "Suivant" pour ouvrir les paramètres de la règle:

5. Mode de la règle: "Appliquer"
6. Gravité: "Non spécifiée"
7. Laissez "Activer cette règle le" et "Désactiver cette règle le" décochés
8. Cochez "Arrêter le traitement des règles suivantes"
9. Laissez "Différer le message si le traitement de la règle n'est pas terminé" décoché

10. Faire correspondre l'adresse de l'expéditeur dans le message: "En-tête"

11. Cliquez sur "Suivant", puis sur "Terminer", puis sur "Terminé"

12. Définir la priorité: Cliquez sur la règle dans la liste, puis sur "Modifier les paramètres de la règle", et donnez-lui une priorité plus élevée (nombre plus petit) que celle de la règle de transport de l'étape C, ex. 1

13. Cliquez sur "Enregistrer"

Warning

La priorité et l'option «Arrêter le traitement des règles suivantes» sont critiques. La règle doit être évaluée avant celle de l'étape C et doit arrêter le traitement. Sinon, un message qui revient de HIN Gateway risque d'être redirigé à nouveau vers HIN Gateway au lieu d'être remis au destinataire.

1. Examinez les détails de la règle. Ils devraient afficher:

   • Nom de la règle: outgoing_to_mx
   • Mode: Appliquer
   • Gravité: Non spécifiée
   • Plage de dates: Aucune plage de dates spécifique n'est définie
   • Adresse de l'expéditeur: Correspondance avec l'en-tête
   • Priorité: 1
   • En cas d'erreurs de traitement de la règle: Ignorer
   • Appliquer cette règle si: L'en-tête 'outgoing' correspond aux modèles suivants: 'outgoing_<YOUR_DOMAIN>'
   • Faire ce qui suit: Acheminer le message via le connecteur «Send to MX» et arrêter le traitement des règles suivantes

2. Activer la règle: La règle est créée dans un état désactivé. Basculez "Activer ou désactiver la règle" sur "Activé"

Tip

N'oubliez pas d'activer la règle: elle ne fonctionnera pas tant qu'elle ne sera pas activée.

---

Partie 3: Configuration du serveur Exchange On-Premises

Pour Exchange Server On-Premises (2016, 2019), la configuration est similaire mais effectuée via la console de gestion Exchange (EAC) ou le Shell de gestion Exchange (PowerShell).

Connecteur d'envoi (On-Premises → HIN Gateway)

Créez un connecteur d'envoi pour acheminer les courriels sortants via HIN Gateway:

Shell de gestion Exchange (PowerShell) :

New-SendConnector -Name "To HIN Gateway Relay" `
  -AddressSpaces "SMTP:*;1" `
  -SmartHosts "<HIN Gateway_IP>" `
  -SmartHostAuthMechanism None `
  -DNSRoutingEnabled $false `
  -SourceTransportServers "<VOTRE_SERVEUR_EXCHANGE>"

Centre d'administration Exchange (GUI) :

1. Accédez à Flux de courrier → Connecteurs d'envoi
2. Cliquez sur + pour créer un nouveau connecteur
3. Nom: "To HIN Gateway Relay"
4. Type: Sélectionnez "Internet"
5. Paramètres réseau: Sélectionnez "Acheminer les courriels via des hôtes intelligents", ajoutez <HIN Gateway_IP>
6. Authentification de l'hôte intelligent: Sélectionnez "Aucune"
7. Espace d'adressage: Ajoutez * (tous les domaines) ou des domaines externes spécifiques
8. Serveur source: Sélectionnez votre ou vos serveurs de transport Exchange

Connecteur de réception (HIN Gateway → On-Premises)

Créez ou modifiez un connecteur de réception pour accepter les courriels de HIN Gateway:

Shell de gestion Exchange (PowerShell) :

New-ReceiveConnector -Name "From HIN Gateway Relay" `
  -Bindings "0.0.0.0:25" `
  -RemoteIPRanges "<HIN Gateway_IP>" `
  -TransportRole FrontendTransport `
  -Usage Custom `
  -AuthMechanism ExternalAuthoritative `
  -PermissionGroups ExchangeServers

Centre d'administration Exchange (GUI) :

1. Accédez à Flux de courrier → Connecteurs de réception
2. Cliquez sur + pour créer un nouveau connecteur
3. Nom: "From HIN Gateway Relay"
4. Type: Sélectionnez "Transport frontal"
5. Liaisons des adaptateurs réseau: Laissez par défaut ou liez à une IP spécifique
6. Paramètres réseau distants: Supprimez la valeur par défaut 0.0.0.0-255.255.255.255 et ajoutez uniquement <HIN Gateway_IP>
7. Authentification: Cochez "Sécurisé externellement"
8. Groupes de permissions: Cochez "Serveurs Exchange"

Règle de transport (On-Premises)

Créez une règle de transport pour rediriger les courriels sortants via le connecteur d'envoi:

Shell de gestion Exchange (PowerShell) :

New-TransportRule -Name "Relay outbound via HIN Gateway" `
  -SentToScope NotInOrganization `
  -RouteMessageOutboundConnector "To HIN Gateway Relay" `
  -ExceptIfSenderIpRanges "<HIN Gateway_IP>"

Centre d'administration Exchange (GUI) :

1. Accédez à Flux de courrier → Règles
2. Cliquez sur + → "Créer une nouvelle règle"
3. Nom: "Relay outbound via HIN Gateway"
4. Appliquer cette règle si: "Le destinataire est situé..." → "En dehors de l'organisation"
5. Faire ce qui suit: "Rediriger le message vers..." → "le connecteur suivant" → "To HIN Gateway Relay"
6. Sauf si: "L'adresse IP de l'expéditeur est dans..." → ajoutez <HIN Gateway_IP>

---

Partie 4: Configuration côté HIN Gateway

Configuration automatique (Par défaut)

Par défaut, Stalwart découvre automatiquement où livrer les courriels traités en consultant les enregistrements MX pour chaque domaine configuré via la page /mail du tableau de bord. Il filtre son propre nom d'hôte et utilise les entrées MX restantes comme cibles de livraison.

Cela fonctionne lorsque:

• Votre domaine a des enregistrements MX pointant à la fois vers HIN Gateway et Exchange
• HIN Gateway a un enregistrement MX de priorité plus élevée (nombre inférieur) qu'Exchange

Remplacement manuel via le tableau de bord

Si vous souhaitez que tous les courriels sortants de HIN Gateway aillent vers un seul point de terminaison Exchange (ex. Exchange Online Protection), définissez l'hôte de relais via la page /mail du tableau de bord (ex. [smtp.office365.com]). Le tableau de bord envoie la valeur à l'API REST de mtaconf et le démon l'applique à Stalwart.

Note

Un seul hôte de relais envoie tous les courriels via un seul serveur et ne prend pas en charge le routage par domaine. Pour plusieurs domaines acheminés via différents serveurs Exchange, utilisez la carte de relais par domaine sur la même page du tableau de bord (configure sender_dependent_relayhost_maps en arrière-plan) - voir Configuration multi-domaines ci-dessous.

Configuration multi-domaines

Pour les configurations avec plusieurs domaines et différents serveurs Exchange (ex. BALZ Informatik AG avec 26 domaines), utilisez les enregistrements MX pour le routage par domaine:

domain1.com    MX 10  exchange1.domain1.com
domain1.com    MX 20  stargate.domain1.com

domain2.com    MX 10  exchange2.domain2.com
domain2.com    MX 20  stargate.domain2.com

Les enregistrements MX de chaque domaine indiquent à HIN Gateway où livrer les courriels traités pour ce domaine spécifique.

Vérifier la configuration HIN Gateway

Après la configuration, vérifiez la configuration de Stalwart:

Vérifier la configuration du relais

docker logs stargate-stalwart --tail 50 | grep -i relay

Vérifier la file d'attente des courriels (devrait être vide quand tout fonctionne)

docker exec stargate-stalwart stalwart-cli -u http://localhost:8080 queue list

Envoyer un courriel de test et vérifier les logs

docker logs stargate-stalwart --tail 50

Dépannage

Les courriels ne quittent pas Exchange Online

• Vérifiez que la règle de transport est activée (elle est créée dans un état désactivé)
• Vérifiez les conditions de la règle - elle devrait s'appliquer aux destinataires "En dehors de l'organisation"
• Vérifiez que la validation du connecteur sortant a réussi
• Vérifiez la trace des messages Exchange dans le Centre d'administration pour l'état de livraison

Boucles de courrier (messages dupliqués)

• Assurez-vous que la règle de transport a l'exception pour l'adresse IP de HIN Gateway
• Sans cette exception, les courriels de HIN Gateway arrivant dans Exchange sont redirigés vers HIN Gateway

HIN Gateway n'accepte pas les courriels d'Exchange

• Vérifiez que le port 25 est ouvert sur le pare-feu du serveur HIN Gateway
• Vérifiez que l'enregistrement SPF inclut l'IP HIN Gateway
• Vérifiez les logs Stalwart: docker logs stargate-stalwart

Exchange Online rejette les courriels de HIN Gateway

• Vérifiez que le connecteur entrant est configuré avec la bonne IP HIN Gateway
• Vérifiez que l'IP HIN Gateway n'a pas changé
• Vérifiez que le connecteur est activé (Statut: Activé)

Erreurs de certificat TLS

HIN Gateway utilise TLS opportuniste avec un certificat auto-signé. Le connecteur sortant dans Exchange doit être configuré pour accepter "Tout certificat numérique, y compris les certificats auto-signés". Si vous voyez des erreurs liées à TLS:

• Vérifiez que le paramètre de sécurité du connecteur sortant autorise les certificats auto-signés
• Pour Exchange On-Premises, assurez-vous que le connecteur d'envoi ne nécessite pas TLS (-RequireTLS $false)

La validation échoue lors de la création du connecteur

La validation du connecteur sortant nécessite:

• Le serveur HIN Gateway est en cours d'exécution et accepte les connexions sur le port 25
• L'adresse de courrier de validation est valide pour votre domaine
• Le chemin réseau entre Exchange Online et HIN Gateway est ouvert (pas de blocage par pare-feu)

---

Référence rapide

Composant	Emplacement Exchange Online	Objectif
Connecteur sortant	Centre d'administration → Flux de courrier → Connecteurs	Acheminer les courriels sortants vers HIN Gateway
Connecteur entrant	Centre d'administration → Flux de courrier → Connecteurs	Accepter les courriels de HIN Gateway
Règle de transport	Centre d'administration → Flux de courrier → Règles	Déclencher le connecteur sortant pour les destinataires externes
Connecteur Send to MX	Centre d'administration → Flux de courrier → Connecteurs	Remettre au MX du destinataire les courriels qui reviennent de HIN Gateway
Règle outgoing_to_mx	Centre d'administration → Flux de courrier → Règles	Acheminer vers le connecteur Send to MX les courriels qui reviennent de HIN Gateway

Enregistrement DNS	Exemple	Objectif
A	mail IN A <HIN Gateway_IP>	Pointer le nom d'hôte vers HIN Gateway
MX (HIN Gateway)	@ IN MX 15 mail.<YOUR_DOMAIN>.	Les courriels entrants frappent d'abord HIN Gateway
MX (Exchange)	@ IN MX 20 <DOMAIN>.mail.protection.outlook.com.	Secours / cible de livraison
SPF	ip4:<HIN Gateway_IP> et ip4:<HIN_SEALER_IP> ajoutés à l'enregistrement TXT existant	Autoriser HIN Gateway et le scelleur HIN à envoyer des courriels

Pour la configuration DNS complète (y compris PTR, DMARC, DKIM et multi-domaines), consultez le Guide de configuration DNS.

Configuration du relais de courrier Stargate

Créer un relais Stargate pour un domaine de courrier hébergé dans Microsoft Office 365

Pour le relais, nous avons besoin d'une VM ou d'un serveur avec une adresse IP statique réelle.

Dans cet exemple, nous utiliserons une VM avec l'adresse IP 128.140.117.200 et le nom d'hôte mail.vrgnservices.eu pour relayer les courriels pour le domaine vrgnservices.eu.

Configurer les enregistrements DNS

Consultez le Guide de configuration DNS pour des instructions complètes sur tous les enregistrements requis (A, MX, SPF, PTR, DMARC, DKIM).

Exemple rapide pour le domaine vrgnservices.eu avec l'IP Stargate 128.140.117.200:

• Enregistrement A: mail.vrgnservices.eu → 128.140.117.200
• Enregistrement MX: MX @ 15 mail.vrgnservices.eu. (priorité plus élevée que l'Exchange MX existant à 20)
• Enregistrement SPF: v=spf1 ip4:128.140.117.200 include:spf.protection.outlook.com -all

Vérifier:

# host mail.vrgnservices.eu
mail.vrgnservices.eu a l'adresse 128.140.117.200

# host -t mx vrgnservices.eu
vrgnservices.eu le courrier est géré par 20 vrgnservices-eu.mail.protection.outlook.com.
vrgnservices.eu le courrier est géré par 15 mail.vrgnservices.eu.

# host -t txt vrgnservices.eu|grep v=spf1
vrgnservices.eu texte descriptif "v=spf1 ip4:128.140.117.200 include:spf.protection.outlook.com -all"

Installer les conteneurs docker compose Stargate

Déploiement Stargate

Exigences

• 2 cœurs CPU (minimum)
• 4 Go de RAM (minimum)
• 20 Go de stockage (minimum)
• Accès root: Doit être exécuté en tant que root ou avec sudo
• Distributions prises en charge:
  • Distributions compatibles RHEL 8, 9 et 10 telles que Alma Linux, Rocky Linux, CentOS Stream
  • Ubuntu 22 et 24
  • Debian 11, 12 et 13
• Adresse IPv4 réelle
• Enregistrements DNS valides: Votre domaine doit avoir:
  • Des enregistrements MX pointant vers vos serveurs de courrier
  • Un enregistrement SPF définissant les réseaux d'envoi autorisés

Le script installe tous les composants et les démarre. Les domaines de courrier et le nom d'hôte Stalwart sont ensuite configurés à l'exécution via la page /mail du tableau de bord (le démon mtaconf extrait les paramètres de relais de courrier nécessaires du DNS en fonction de ces domaines).

Configurer Exchange

Nous devons configurer des connecteurs et une règle de transport dans Exchange pour relayer tous les courriels sortants vers le relais Stargate et autoriser les courriels entrants de celui-ci.

Accédez à https://admin.exchange.microsoft.com/#/connectors

Connecteur sortant

Créez un connecteur de courrier sortant, cliquez sur "Ajouter":

Sélectionnez "Connexion depuis": "Office 365" "Connexion vers": "Serveur de courrier de votre organisation", cliquez sur "Suivant".

Nommez-le par exemple "From Office 365 to Stargate relay server" et cochez "Conserver les en-têtes de courrier internes Exchange", cliquez sur "Suivant".

Sélectionnez "Uniquement lorsque j'ai une règle de transport configurée qui redirige les messages vers ce connecteur", cliquez sur "Suivant".

Entrez l'adresse IP du serveur relais Stargate, cliquez sur "+", cliquez sur "Suivant".

Sélectionnez "Tout certificat numérique, y compris les certificats auto-signés", cliquez sur "Suivant".

Entrez une adresse de courrier valide pour votre domaine, cliquez sur "+", cliquez sur "Valider", cliquez sur "Suivant".

Cliquez sur "Créer un connecteur".

Cliquez sur "Ajouter un autre connecteur".

Connecteur entrant

Créez un connecteur de courrier entrant, choisissez "Connexion depuis": "Serveur de courrier de votre organisation", cliquez sur "Suivant".

Nommez-le par exemple "Receive mail from Stargate relay server" et cochez "Conserver les en-têtes de courrier internes Exchange", cliquez sur "Suivant".

Sélectionnez "En vérifiant que l'adresse IP du serveur d'envoi correspond à l'une des adresses IP suivantes", tapez l'adresse IP du serveur Stargate, cliquez sur "+", cliquez sur "Suivant".

Cliquez sur "Créer un connecteur".

Cliquez sur "Terminé".

Voici à quoi cela ressemble une fois terminé:

Règle de transport

Créez la règle de transport. Accédez à https://admin.exchange.microsoft.com/#/transportrules

Cliquez sur "+Ajouter une règle" → "Créer une nouvelle règle".

Nommez-la par exemple "Relay all mail to Stargate except mail coming from it", choisissez "Appliquer cette règle si" "Le destinataire :" "est externe/interne" "En dehors de l'organisation", cliquez sur "Enregistrer".

Choisissez "Faire ce qui suit" "Rediriger le message vers le connecteur suivant" "From Office 365 to Stargate relay server", cliquez sur "Enregistrer".

Choisissez "Sauf si L'adresse IP de l'expéditeur se trouve dans l'une de ces plages" entrez l'adresse IP du serveur Stargate, cliquez sur "Ajouter", vérifiez l'adresse IP et cliquez sur "Enregistrer".

Ceci est nécessaire pour éviter les boucles de courrier, car cette règle s'applique également à d'autres domaines hébergés dans Office 365.

Maintenant, cela devrait ressembler à ceci, cliquez sur "Suivant":

Cliquez sur "Suivant".

Cliquez sur "Terminer".

Cliquez sur "Terminé".

Cliquez sur la règle et définissez "Activer ou désactiver la règle" sur "Activé"

Configuration DNS pour HIN Gateway

Ce guide couvre tous les enregistrements DNS requis pour un déploiement fonctionnel de HIN Gateway. Configurez ces enregistrements avant d'installer HIN Gateway ou immédiatement après, selon le type d'enregistrement.

Tout au long de ce guide:

• <HIN Gateway_IP> - l'adresse IP publique statique de votre serveur HIN Gateway (SERVER_STATIC_IP dans customer-config.sh)
• <MAIL_HOSTNAME> - le FQDN du relais HIN Gateway (ex. mail.example.ch ; configuré via la page /mail du tableau de bord)
• <YOUR_DOMAIN> - votre domaine de courrier (ex. example.ch ; configuré via la page /mail du tableau de bord)

---

Résumé des enregistrements

Enregistrement	Nom	Valeur	Requis	Quand
A	<MAIL_HOSTNAME>	<HIN Gateway_IP>	Oui	Avant l'installation
MX	<YOUR_DOMAIN>	<MAIL_HOSTNAME> (priorité 15)	Oui	Avant l'installation
SPF	<YOUR_DOMAIN>	ip4:<HIN Gateway_IP> ajouté au TXT	Oui	Avant l'installation
PTR	<HIN Gateway_IP>	<MAIL_HOSTNAME>	Recommandé	Avant l'installation
DMARC	_dmarc.<YOUR_DOMAIN>	v=DMARC1; p=none; ...	Recommandé	Après l'installation
DKIM	selector._domainkey.<YOUR_DOMAIN>	Depuis M365/fournisseur	Recommandé	Après l'installation

Pour les déploiements multi-domaines, répétez les enregistrements MX, SPF, DMARC et DKIM pour chaque domaine répertorié dans MAIL_DOMAINS.

---

Enregistrements requis

Enregistrement A

Créez un enregistrement A pointant le nom d'hôte du courrier HIN Gateway vers l'IP publique du serveur:

<MAIL_HOSTNAME>.    A    <HIN Gateway_IP>

Exemple:

mail.example.ch.    A    128.140.117.200

Si HIN Gateway dispose d'une adresse IPv6, ajoutez également un enregistrement AAAA:

mail.example.ch.    AAAA    2a01:4f8:c012:1234::1

Pourquoi: Les serveurs de courrier externes se connectent à ce nom d'hôte pour livrer les courriels. Sans l'enregistrement A, l'enregistrement MX ci-dessous n'est pas résolvable.

Enregistrements MX

Ajoutez un enregistrement MX pour HIN Gateway avec une priorité plus élevée (nombre inférieur) que le serveur de courrier existant. Cela garantit que les courriels entrants atteignent d'abord HIN Gateway pour le traitement S/MIME avant d'être transférés vers Exchange ou votre plateforme de courrier.

<YOUR_DOMAIN>.    MX    15    <MAIL_HOSTNAME>.

Conservez l'enregistrement MX existant d'Exchange / serveur de courrier avec une priorité inférieure (nombre supérieur):

<YOUR_DOMAIN>.    MX    20    <YOUR_DOMAIN>.mail.protection.outlook.com.

Exemple (ensemble MX complet):

example.ch.    MX    15    mail.example.ch.
example.ch.    MX    20    example-ch.mail.protection.outlook.com.

Info

Un numéro MX inférieur signifie une priorité plus élevée. HIN Gateway avec la priorité 15 reçoit les courriels avant Exchange Online avec la priorité 20.

Pourquoi: HIN Gateway intercepte les courriels entrants, traite S/MIME, puis les transfère au prochain MX (Exchange). Le deuxième enregistrement MX est également utilisé par Stalwart pour savoir où relayer les courriels traités.

Important: Si HIN Gateway est le seul enregistrement MX pour un domaine, Stalwart filtrera son propre nom d'hôte et n'aura pas de cible de livraison. Conservez toujours un deuxième MX pointant vers votre serveur de courrier réel.

Enregistrement SPF

Ajoutez l'IP du serveur HIN Gateway et l'IP du scelleur HIN à l'enregistrement SPF de votre domaine afin que les courriels sortants relayés via celui-ci réussissent les vérifications SPF chez le destinataire.

Si vous utilisez M365 / Exchange Online:

<YOUR_DOMAIN>.    TXT    "v=spf1 ip4:<HIN Gateway_IP> ip4:<HIN_SEALER_IP> include:spf.protection.outlook.com -all"

Si vous n'utilisez pas M365 / Google Workspace:

<YOUR_DOMAIN>.    TXT    "v=spf1 ip4:<HIN Gateway_IP> ip4:<HIN_SEALER_IP> -all"

Exemple:

example.ch.    TXT    "v=spf1 ip4:128.140.117.200 ip4:193.247.208.66 include:spf.protection.outlook.com -all"

Pourquoi l'IP du scelleur HIN est requise

Lorsque HIN Gateway produit un message SCELLÉ (chiffré) pour un destinataire non-HIN, le dernier saut sortant vers le destinataire est le scelleur HIN, pas votre HIN Gateway ou M365. Sans l'IP du scelleur dans votre enregistrement SPF, chaque message sortant SCELLÉ échouera au SPF chez le destinataire et - car il n'y a pas de signature DKIM sur la charge utile SCELLÉE - DMARC échouera également. Les destinataires avec DMARC strict (Gmail, Outlook avec application p=reject, Proofpoint) rejetteront ou classeront le message comme indésirable.

IPs du scelleur à ajouter dans SPF:

HIN publie plus d'un hôte de scellement (ex. mx1, mx2, mx3), incluez toutes leurs IPs. Résolvez-les avec dig +short mx hin.ch suivi de dig +short A <chaque-mx>. Jusqu'à ce que vous ayez la liste complète, laissez la politique SPF à ~all (échec doux) au lieu de -all (échec dur) afin que les courriels SCELLÉS légitimes via une IP de scelleur non répertoriée ne soient pas catégoriquement rejetés.

Limite de recherche SPF

La chaîne include: totale dans un enregistrement SPF doit rester en dessous de 10 recherches DNS. L'ajout d'entrées ip4: ne compte pas dans cette limite. Vérifiez votre nombre avec MXToolbox SPF lookup.

Comment HIN Gateway utilise SPF: Le démon mtaconf résout l'enregistrement SPF de chaque domaine pour remplir automatiquement la liste des IP autorisées à relayer via HIN Gateway sans authentification. C'est ainsi que les IP sortantes de Microsoft 365 sont automatiquement mises sur liste blanche - elles apparaissent dans la chaîne include:spf.protection.outlook.com.

---

Enregistrements recommandés

PTR (DNS inversé)

Configurez l'enregistrement DNS inversé (PTR) pour l'IP HIN Gateway afin qu'il corresponde à <MAIL_HOSTNAME>:

200.117.140.128.in-addr.arpa.    PTR    mail.example.ch.

Ceci est configuré chez votre fournisseur d'hébergement (Hetzner, Azure, AWS, etc.), pas dans le panneau DNS de votre bureau d'enregistrement de domaine. La plupart des fournisseurs ont un paramètre "DNS inversé" ou "rDNS" dans la page de gestion du serveur/IP.

Pourquoi: De nombreux serveurs de courrier récepteurs (y compris Gmail et Outlook) vérifient que l'enregistrement PTR de l'IP de connexion résout un nom d'hôte, et que ce nom d'hôte résout la même IP (DNS inversé à confirmation directe / FCrDNS). Un PTR manquant ou non correspondant est un fort signal de spam et peut entraîner des échecs de livraison.

Enregistrement DMARC

Publiez une politique DMARC pour chaque domaine d'envoi. Commencez par p=none (surveillance uniquement), puis renforcez après avoir confirmé l'alignement:

_dmarc.<YOUR_DOMAIN>.    TXT    "v=DMARC1; p=none; rua=mailto:postmaster@<YOUR_DOMAIN>"

Exemple:

_dmarc.example.ch.    TXT    "v=DMARC1; p=none; rua=mailto:postmaster@example.ch"

Une fois que les rapports agrégés DMARC confirment que SPF et/ou DKIM réussissent constamment, renforcez la politique:

1. p=none - surveillance uniquement (commencez ici)
2. p=quarantine - les courriels suspects vont dans les spams
3. p=reject - les courriels non autorisés sont rejetés

Pourquoi: DMARC lie SPF et DKIM ensemble et indique aux destinataires quoi faire avec les courriels qui échouent aux deux. Même p=none suffit pour effacer la bannière "nous ne pouvons pas vérifier cet expéditeur" d'Outlook, tant que SPF réussit.

Vérifiez votre enregistrement DMARC: MXToolbox DMARC lookup

Enregistrements DKIM

Si votre domaine est un domaine accepté dans M365 ou Google Workspace, activez la signature DKIM dans le centre d'administration et publiez les enregistrements CNAME comme indiqué:

Exemple M365:

selector1._domainkey.<YOUR_DOMAIN>.    CNAME    selector1-<YOUR_DOMAIN_DASHED>._domainkey.<TENANT>.onmicrosoft.com.
selector2._domainkey.<YOUR_DOMAIN>.    CNAME    selector2-<YOUR_DOMAIN_DASHED>._domainkey.<TENANT>.onmicrosoft.com.

Note

La publication des enregistrements CNAME seuls ne suffit pas - la signature DKIM doit également être activée dans le centre d'administration M365 (portail Defender > Authentification des courriels > DKIM).

Pourquoi: DKIM prouve que le corps du message n'a pas été altéré pendant le transit. Combiné avec SPF et DMARC, il fournit la plus forte authentification de l'expéditeur.

---

Configuration multi-domaines

Pour les déploiements gérant plusieurs domaines de courrier (configurés via la page /mail du tableau de bord), chaque domaine a besoin de son propre ensemble d'enregistrements DNS.

Enregistrements par domaine

Pour chaque domaine configuré:

Enregistrement	Requis
MX pointant vers <MAIL_HOSTNAME>	Oui
SPF incluant ip4:<HIN Gateway_IP>	Oui
DMARC (_dmarc.<domain>)	Recommandé
DKIM (de votre fournisseur de courrier)	Recommandé

L'enregistrement A et l'enregistrement PTR sont partagés (ils pointent vers le serveur HIN Gateway, pas vers des domaines individuels).

Routage de courrier par domaine

Les enregistrements MX de chaque domaine indiquent à HIN Gateway où livrer les courriels traités. Si différents domaines utilisent différents serveurs Exchange:

domain1.ch    MX    15    mail.domain1.ch.
domain1.ch    MX    20    exchange1.domain1.ch.

domain2.ch    MX    15    mail.domain2.ch.
domain2.ch    MX    20    exchange2.domain2.ch.

Alternativement, configurez des cibles de relais explicites par domaine via la page /mail du tableau de bord (champ hôte de relais par domaine) pour remplacer le routage basé sur MX.

---

Vérification

Après avoir configuré tous les enregistrements, vérifiez-les:

# Enregistrement A
host <MAIL_HOSTNAME>
# Attendu: <MAIL_HOSTNAME> a l'adresse <HIN Gateway_IP>

# Enregistrements MX
host -t mx <YOUR_DOMAIN>
# Attendu: Les enregistrements MX de HIN Gateway et d'Exchange sont répertoriés

# Enregistrement SPF
host -t txt <YOUR_DOMAIN> | grep v=spf1
# Attendu: L'enregistrement SPF inclut ip4:<HIN Gateway_IP>

# PTR (DNS inversé)
host <HIN Gateway_IP>
# Attendu: <HIN Gateway_IP> → <MAIL_HOSTNAME>

# DNS inversé à confirmation directe (FCrDNS)
host $(host <HIN Gateway_IP> | awk '{print $NF}' | sed 's/\.$//')
# Attendu: résout en <HIN Gateway_IP>

# DMARC
host -t txt _dmarc.<YOUR_DOMAIN>
# Attendu: v=DMARC1; p=...

# DKIM (M365)
host -t cname selector1._domainkey.<YOUR_DOMAIN>
# Attendu: CNAME vers le onmicrosoft.com de votre locataire

Exemple de sortie:

$ host mail.example.ch
mail.example.ch a l'adresse 128.140.117.200

$ host -t mx example.ch
example.ch le courrier est géré par 15 mail.example.ch.
example.ch le courrier est géré par 20 example-ch.mail.protection.outlook.com.

$ host -t txt example.ch | grep v=spf1
example.ch texte descriptif "v=spf1 ip4:128.140.117.200 include:spf.protection.outlook.com -all"

$ host 128.140.117.200
200.117.140.128.in-addr.arpa pointeur de nom de domaine mail.example.ch.

$ host -t txt _dmarc.example.ch
_dmarc.example.ch texte descriptif "v=DMARC1; p=none; rua=mailto:postmaster@example.ch"

Outils en ligne:

• MXToolbox MX Lookup
• MXToolbox SPF Check (inclut le nombre de recherches)
• MXToolbox DMARC Check
• Mail-Tester (envoyez un courriel de test pour obtenir un score de délivrabilité)

---

Dépannage

"Client host rejected: Access denied" (554 5.7.1)

Stalwart rejette le serveur expéditeur car son IP n'est pas dans la liste de relais autorisée. Cela signifie généralement:

• L'enregistrement SPF de votre domaine n'inclut pas la plage IP du serveur expéditeur
• La configuration du courrier n'a pas été rechargée depuis la mise à jour de l'enregistrement SPF

Rechargez la configuration du courrier via la page /mail du tableau de bord (soumettez à nouveau la configuration) ou redémarrez le conteneur: docker compose restart stalwart

Courrier marqué comme spam / "ne peut pas vérifier l'expéditeur"

• SPF est manquant ou n'inclut pas l'IP HIN Gateway - ajoutez ip4:<HIN Gateway_IP> à votre enregistrement SPF
• DMARC n'est pas publié - ajoutez au moins v=DMARC1; p=none
• L'enregistrement PTR est manquant ou ne correspond pas - configurez le DNS inversé chez votre fournisseur d'hébergement
• DKIM n'est pas activé dans votre locataire M365/fournisseur

La recherche MX ne renvoie que HIN Gateway

Si HIN Gateway est le seul MX pour un domaine, Stalwart filtre son propre nom d'hôte et n'a pas de cible de relais. Ajoutez un deuxième enregistrement MX pointant vers votre serveur de courrier:

example.ch.    MX    15    mail.example.ch.          ← HIN Gateway (entrant)
example.ch.    MX    20    example-ch.mail.protection.outlook.com.  ← Exchange (cible de relais)

Nombre de recherches SPF dépassé (> 10)

Chaque include: dans l'enregistrement SPF déclenche des recherches DNS supplémentaires. La chaîne totale doit rester en dessous de 10. Solutions:

• Utilisez des entrées ip4: / ip6: au lieu de include: lorsque c'est possible (elles ne comptent pas)
• Aplatissez les inclusions imbriquées à l'aide d'un outil comme SPF Flattener
• Supprimez les entrées include: inutilisées d'anciens fournisseurs

Port 25 bloqué par le fournisseur d'hébergement

Certains fournisseurs de cloud (Azure, certains plans Hetzner) bloquent le port 25 sortant par défaut. Vérifiez auprès de votre fournisseur et demandez une exception. Cela affecte à la fois la livraison entrante (serveurs externes se connectant à votre HIN Gateway) et le relais sortant (HIN Gateway livrant aux cibles MX).

Authentification des e-mails (DKIM / ARC / SPF / DMARC)

Module : HIN Mail Gateway -> Domains -> [domaine] -> Email authentication S'applique à : Aux administrateurs de domaine qui configurent la signature sortante et la vérification entrante pour un domaine de messagerie

---

La section Email authentication contrôle la manière dont l'authenticité des e-mails est prouvée, et avec quelle rigueur l'authenticité des e-mails entrants est vérifiée, c'est-à-dire la vérification DKIM/ARC/SPF/DMARC. Elle génère également les enregistrements DNS TXT qui doivent être publiés afin que les serveurs de messagerie externes puissent vérifier le courrier de votre domaine.

On accède à cette section via :

Domains -> sélectionner un domaine -> Email authentication

Le panneau comporte cinq sous-sections :

1. DKIM
2. ARC
3. SPF
4. DMARC
5. Enregistrements DNS à publier

Les modifications ne sont appliquées qu'après avoir cliqué sur le bouton Save en bas de la page.

---

Ce que fait chaque protocole

Protocole	Direction	Objectif
DKIM (DomainKeys Identified Mail)	Signature sortante / Vérification entrante	Signe cryptographiquement les messages sortants avec une clé privée, associée à une clé publique publiée dans le DNS, afin que les destinataires puissent confirmer que le message n'a pas été altéré en transit et provient réellement de ce domaine
ARC (Authenticated Received Chain)	Signature de la vérification entrante pour le relais suivant	Préserve les résultats d'authentification DKIM/SPF d'origine lorsqu'un message transite par des intermédiaires (listes de diffusion, services de transfert, etc.) qui casseraient autrement les signatures DKIM
SPF (Sender Policy Framework)	Vérification entrante	Vérifie que l'adresse IP du serveur de messagerie expéditeur est autorisée à envoyer du courrier pour le domaine de l'expéditeur, sur la base d'un enregistrement DNS publié par ce domaine
DMARC (Domain-based Message Authentication, Reporting & Conformance)	Vérification entrante	Relie les résultats DKIM et SPF entre eux et indique aux serveurs destinataires la conduite à tenir

Bien configurer DKIM et DMARC pour votre propre domaine protège votre délivrabilité et votre marque contre l'usurpation. Les paramètres de vérification (menus déroulants de vérification DKIM, ARC, SPF, DMARC) contrôlent en revanche le niveau de confiance que la passerelle accorde à ces signaux pour le courrier entrant provenant d'autres domaines.

---

DKIM

Champ	Description
Enable DKIM signing	Lorsqu'il est actif, la passerelle signe tout le courrier sortant de ce domaine avec la clé privée configurée. Activez cette option avant de publier l'enregistrement DNS DKIM
Generate DKIM key (bouton, en haut à droite)	Génère une nouvelle paire de clés RSA-2048 pour ce domaine et remplit le champ Private key (PEM)
DKIM verification	Contrôle avec quelle rigueur un e-mail est vérifié par rapport à l'enregistrement DKIM publié de l'expéditeur
Selector	Le sélecteur DKIM (ex. s1) utilisé pour publier et rechercher la clé publique à l'adresse <selector>._domainkey.<domain>. Ne modifiez ceci que si vous devez faire fonctionner plusieurs clés en parallèle (par exemple lors d'une rotation de clé) : chaque sélecteur nécessite son propre enregistrement DNS TXT
Private key (PEM)	La clé privée RSA utilisée pour signer le courrier sortant. Vous pouvez soit cliquer sur Generate DKIM key pour en créer une, soit coller votre propre clé privée RSA-2048 au format PEM

Comment configurer DKIM pour un nouveau domaine

1. Cliquez sur Generate DKIM key (ou collez une clé PEM RSA-2048 existante que vous gérez en externe)
2. Laissez Selector à sa valeur par défaut (s1) sauf raison particulière de le modifier
3. Basculez Enable DKIM signing sur Active
4. Cliquez sur Save
5. Copiez l'enregistrement TXT s1._domainkey.<domain> généré depuis le champ DNS records to publish (voir §7) et ajoutez-le chez votre fournisseur DNS
6. Une fois l'enregistrement DNS propagé, le courrier signé par ce domaine portera une signature DKIM valide

Comment effectuer une rotation d'une clé DKIM

1. Cliquez sur Replace key à côté de Private key (PEM)
2. Générez une nouvelle clé (ou collez-en une nouvelle)
3. Publiez l'enregistrement TXT du nouveau sélecteur dans le DNS avant de l'enregistrer/l'activer en production, afin d'éviter une période durant laquelle le courrier signé ne peut pas être vérifié
4. Enregistrez, puis supprimez l'enregistrement DNS de l'ancien sélecteur une fois que vous avez confirmé que la nouvelle clé signe correctement

---

ARC

Champ	Description
ARC verification (menu déroulant)	Contrôle avec quelle rigueur les chaînes ARC entrantes sont validées
Enable ARC signing	Lorsqu'il est actif, la passerelle ajoute un sceau ARC au courrier transféré, préservant les résultats d'authentification si le message est relayé ultérieurement par un autre système
Reuse DKIM key (bascule)	Lorsqu'il est actif, la signature ARC utilise la même clé RSA que celle configurée dans la section DKIM ci-dessus, au lieu de nécessiter une clé distincte. Recommandé sauf besoin spécifique de garder les deux signatures cryptographiquement séparées

---

SPF

Champ	Description
SPF verification	Contrôle avec quelle rigueur le courrier entrant est vérifié par rapport à l'enregistrement SPF publié du domaine expéditeur

Remarque : Ce panneau contrôle uniquement la vérification du SPF entrant. Il ne génère pas d'enregistrement SPF TXT sortant pour votre propre domaine (aucune entrée SPF n'apparaît dans la §7 "DNS records to publish"). Si ce domaine envoie du courrier via un relais externe (par exemple Microsoft 365, configuré dans Mail routing -> Outbound relay), assurez vous que le mécanisme include: de ce fournisseur est déjà publié dans le propre enregistrement SPF de votre domaine chez votre fournisseur DNS, indépendamment de cette passerelle.

---

DMARC

Champ	Description
DMARC verification	Contrôle avec quelle rigueur le courrier entrant est vérifié par rapport à la politique DMARC de l'expéditeur

Valeur de vérification

Libellé dans l'interface	Valeur	Comportement
Disabled	disable	N'est pas vérifié du tout. Le mécanisme ne s'exécute pas
Optional	relaxed	Vérifié et signalé dans Authentication-Results. Le message est toujours accepté, qu'il réussisse ou échoue
Required	strict	Vérifié et signalé, et le message est rejeté en cas d'échec définitif. Sinon, il est accepté

En résumé : Disabled signifie qu'aucune vérification n'est effectuée ; Optional et Required vérifient tous deux et consignent le résultat. La seule différence entre les deux est l'application : Optional ne rejette jamais, Required rejette en cas d'échec définitif.

Ce qui constitue un "échec définitif" pour Required (par mécanisme) : - DKIM : le message comporte des signatures et toutes échouent. Aucune signature du tout donne none, ce qui n'est pas un échec, donc pas de rejet. - SPF : un échec définitif -all. SoftFail/neutral/none/temp-error sont signalés mais ne provoquent pas de rejet. - DMARC : ni DKIM ni SPF ne s'aligne, et il y a un verdict d'échec réel. L'absence d'enregistrement DMARC publié donne none, donc pas de rejet. - ARC : la chaîne ARC échoue à la validation. L'absence de chaîne donne none, donc pas de rejet.

Deux remarques importantes : - DKIM s'exécute toujours en interne, car DMARC en a besoin. Le paramètre DKIM contrôle uniquement si un résultat dkim= est consigné et si un échec DKIM peut entraîner un rejet ; il ne modifie jamais le verdict DMARC. - Chaque mécanisme est indépendant, vous pouvez donc par exemple exécuter DMARC = Required avec DKIM/SPF = Optional : le courrier problématique est rejeté sur la base du verdict DMARC, et vous obtenez tout de même des lignes dkim=/spf= individuelles dans l'en-tête pour plus de visibilité.

---

Enregistrements DNS à publier

Cette zone affiche les enregistrements TXT exacts que vous devez créer chez le fournisseur DNS de votre domaine afin que les serveurs de messagerie externes puissent vérifier le courrier de ce domaine. Les enregistrements affichés se mettent à jour automatiquement en fonction du sélecteur DKIM et des paramètres de politique DMARC ci-dessus.

Enregistrement	Hôte	Type	Valeur
Clé publique DKIM	<selector>._domainkey.<domain> (ex. s1._domainkey.vrgnservices.eu)	TXT	v=DKIM1; k=rsa; p=<public key>
Politique DMARC	_dmarc.<domain> (ex. _dmarc.vrgnservices.eu)	TXT	v=DMARC1; p=<policy> (ex. p=none)

Utilisez l'icône de copie en haut à droite de chaque bloc d'enregistrement pour copier sa valeur exacte. Collez chaque enregistrement comme un nouvel enregistrement TXT chez votre registraire/fournisseur DNS, en utilisant Host/Name et Value tels qu'affichés.

Les modifications DNS peuvent prendre de quelques minutes à 48 heures pour se propager, selon les paramètres TTL de votre fournisseur. L'application DKIM/DMARC ne devrait pas être renforcée (par exemple en activant la signature ou en faisant évoluer la politique DMARC au delà de none) avant d'avoir confirmé que les enregistrements se sont propagés et se résolvent correctement.

---

Enregistrer les modifications

Aucun des paramètres ci-dessus ne prend effet tant que vous n'avez pas cliqué sur le bouton orange Save en bas de la page. Save applique ensemble toutes les modifications de DKIM, ARC, SPF et DMARC ; il n'existe pas d'enregistrement par section.

---

Dépannage

Symptôme	Cause probable
Le courrier sortant échoue à la vérification DKIM chez les serveurs destinataires	La signature DKIM est activée mais l'enregistrement DNS TXT n'est pas encore publié/propagé, ou il y a une incohérence de sélecteur entre la passerelle et le DNS.
Le sceau ARC est absent sur le courrier transféré	Enable ARC signing est désactivé, ou Reuse DKIM key est désactivé sans qu'une clé ARC distincte soit configurée.
Impossible de voir la clé privée DKIM pour la copier ailleurs	C'est voulu : une fois enregistrée, la clé est masquée (<hidden>) et ne peut plus être réaffichée. Utilisez Replace key pour en émettre une nouvelle si vous devez la transférer vers un système qui n'en a pas déjà une copie.
Du courrier légitime commence à être mis en quarantaine/rejeté après un changement de politique DMARC	Une source d'envoi légitime n'est pas encore alignée sur DKIM/SPF. Revenez à la politique none, identifiez la source défaillante, corrigez l'alignement, puis renforcez à nouveau la politique.

Mettre à jour HIN Gateway

Ce document explique:

• Comment mettre à jour une instance HIN Gateway vers une version plus récente.
• Comment revenir à une version précédente.

Versions concernées

Cette procédure s'applique uniquement aux versions 0.6.x et ultérieures.

Comment effectuer une mise à jour

1. Accédez à la page Settings et faites défiler jusqu'à la section System version.

1. Cliquez sur Other versions.

2. Dans la liste des versions disponibles, sélectionnez la version cible.

3. Les versions plus récentes utilisent une numérotation incrémentale, la version cible aura donc un numéro supérieur à la version actuelle.

4. Cliquez sur le bouton Download. Cela ne fait que démarrer le téléchargement, la mise à jour n'est pas encore installée.

1. Une fois le téléchargement terminé, une boîte de dialogue de confirmation apparaît avec deux options:

2. Restart now: redémarre immédiatement la machine et installe la nouvelle version.

3. Later: reporte la mise à jour. La nouvelle version est installée au prochain redémarrage de la machine.

Mise à jour majeure

La mise à jour de 0.6.x vers 1.1.7 est une mise à jour majeure. Vous devez créer un snapshot de sauvegarde de la VM avant de lancer la mise à jour.

Cette version inclut une mise à jour de sécurité obligatoire qui fait passer Keycloak à la version 26.8.0. Lors de cette mise à niveau, Keycloak modifie le schéma de la base de données et supprime une colonne et des index dont la version précédente de Keycloak (26.7.4) a besoin. Par conséquent, le bouton Roll back ne permet pas de restaurer une version 0.6.x fonctionnelle. Le snapshot de la VM est le seul moyen de revenir à la version précédente.

Comment revenir à une version précédente

1. Accédez à la page Settings et faites défiler jusqu'à la section System version.

1. Cliquez sur le bouton Roll back to vX.X.X.

2. Confirmez l'action sur l'écran de confirmation. Le système redémarre et installe la version stable précédente.

Gestion des domaines routés (Routed Domains) dans HIN Gateway

HIN Gateway peut également traiter le trafic de messagerie de domaines qui ne sont pas des domaines HIN Secure. C’est une configuration courante chez les clients qui exploitent leur propre infrastructure de serveurs de messagerie sur site. Cette fonctionnalité est intégrée à HIN Gateway et permet aux clients d’adapter leur configuration de messagerie à leurs propres besoins.

Dans HIN Gateway, ces domaines sont appelés domaines Routed. Les e-mails d’un domaine Routed transitent par HIN Gateway sans traitement pour la messagerie sécurisée : ils sont simplement transmis à l’hôte de relais suivant.

Ajouter un domaine Routed

Accédez à la page Domains, cliquez sur Add domain, saisissez le nom de domaine, puis cliquez sur Save.

Configurer le domaine Routed

Activez le domaine et configurez-le de la même manière qu’un domaine HIN Secure. Pour les étapes détaillées, consultez Étape 14 - Configurer le transport du courrier dans le guide d’installation.

Configurer NTP

HIN Gateway maintient son horloge à l’heure exacte grâce à NTP (Network Time Protocol). Une horloge exacte est indispensable: la validation des certificats, la signature des messages et les sessions de connexion échouent si l’horloge dérive.

Fonctionnement:

• Par défaut, HIN Gateway synchronise son heure avec ntp.metas.ch
• Si votre réseau n’autorise pas le trafic NTP sortant vers Internet, ou si votre organisation exploite ses propres serveurs de temps, vous pouvez remplacer le serveur par défaut par un ou plusieurs serveurs de temps personnalisés
• Vous pouvez ajouter plusieurs serveurs de temps. Si l’un d’eux n’est pas joignable, HIN Gateway utilise le suivant

Avant de commencer

• Vous devez avoir accès au tableau de bord HIN Gateway
• Demandez le nom d’hôte du ou des serveurs de temps à votre administrateur réseau
• Assurez-vous que HIN Gateway peut joindre le ou les serveurs de temps sur le port UDP 123

Vérifier la synchronisation actuelle

1. Connectez-vous au tableau de bord HIN Gateway.

2. Ouvrez Settings et faites défiler la page jusqu’à la section Time synchronisation.

   

   La ligne d’état indique si l’horloge est synchronisée (In sync), ainsi que l’adresse IP du serveur de temps utilisé, le décalage (offset) et la strate (stratum). Time servers indique les serveurs configurés. Sans serveur personnalisé, elle affiche Using the default time server (ntp.metas.ch).

Ajouter des serveurs de temps personnalisés

1. Dans la section Time synchronisation, cliquez sur Edit. Un champ vide apparaît pour le premier serveur de temps.

   

2. Saisissez le nom d’hôte du serveur de temps (par exemple ntp.example.com).

3. Utilisez le commutateur à côté du champ pour choisir le type d’entrée:
   • Server: un seul serveur NTP
   • Pool: un pool NTP, c’est-à-dire un nom d’hôte qui renvoie vers plusieurs serveurs (par exemple ch.pool.ntp.org). HIN Gateway utilise plusieurs serveurs du pool

4. Pour ajouter un autre serveur de temps, cliquez sur Add server et répétez les étapes 2 et 3. Vous pouvez combiner pools et serveurs.

   

   Pour supprimer une entrée, cliquez sur l’icône moins à côté de celle-ci.

5. Cliquez sur Save.

HIN Gateway synchronise désormais son heure avec les serveurs de temps configurés au lieu du serveur par défaut.

Vérifier la configuration

Contrôlez la ligne d’état de la section Time synchronisation. Elle doit afficher In sync et l’adresse IP de l’un de vos serveurs de temps. Pour forcer une synchronisation immédiate, cliquez sur Sync now.

Revenir au serveur de temps par défaut

Cliquez sur Edit, supprimez toutes les entrées avec l’icône moins, puis cliquez sur Save. HIN Gateway utilise alors de nouveau ntp.metas.ch.

Authentification des connexions entrantes

L’authentification des connexions entrantes permet à un système externe, tel qu’un relais de messagerie, une application ou un client de messagerie, d’envoyer des e-mails pour l’un de vos domaines via HIN Gateway en se connectant avec un nom d’utilisateur et un mot de passe. C’est utile lorsque l’expéditeur ne peut pas être autorisé uniquement sur la base de son adresse IP.

Fonctionnement:

• L’expéditeur se connecte à HIN Gateway sur le port de soumission 587 et s’authentifie avec SMTP AUTH
• Les identifiants sont créés par domaine dans le tableau de bord HIN Gateway

Avant de commencer

• Vous devez avoir accès au tableau de bord HIN Gateway
• Le domaine d’envoi doit déjà être ajouté dans HIN Gateway et activé (onboarded)
• TLS doit être activé pour le domaine. Les mots de passe ne sont acceptés que via TLS, les identifiants ne fonctionnent donc pas sans certificat TLS
• Vous devez avoir accès à la configuration du système d’envoi (MTA / application), car vous y saisirez les nouveaux identifiants

Créer des identifiants

1. Connectez-vous au tableau de bord HIN Gateway.
2. Ouvrez Domains et sélectionnez le domaine d’envoi.

3. Faites défiler la page jusqu’à la section SMTP authentication (port 587).

   

   Les identifiants qui existent déjà pour le domaine sont répertoriés ici.

   TLS doit être activé

   Si le domaine n’a pas encore de certificat TLS, la section affiche le message No TLS certificate yet. Les identifiants ne fonctionnent qu’une fois TLS activé, car les mots de passe ne sont acceptés que via TLS.

   

   Pour activer TLS, ouvrez la section Configure TLS sur la même page du domaine et ajoutez un certificat, ou cliquez sur Generate TLS certificate pour en générer un. Revenez ensuite à cette section.

   Le commutateur Verify a trusted network détermine depuis où les identifiants peuvent être utilisés. Lorsqu’il est sur Off, les identifiants fonctionnent depuis n’importe quelle adresse IP. Activez-le si vous souhaitez limiter les connexions aux Trusted networks.

4. Cliquez sur Add credential. Un formulaire avec deux champs s’ouvre:

   

   Choisissez l’une des options suivantes:

   • Générer les identifiants automatiquement (recommandé): laissez les champs Username et Password vides. HIN Gateway génère un nom d’utilisateur et un mot de passe aléatoire robuste
   • Définir vos propres identifiants: saisissez Username et Password. Le mot de passe doit comporter au moins 16 caractères.

5. Cliquez sur Create.

6. Copiez le nom d’utilisateur et le mot de passe.

   

   Warning

   Le mot de passe n’est affiché qu’une seule fois. Cliquez sur Copy et conservez-le en lieu sûr (par exemple dans un gestionnaire de mots de passe) avant de continuer. En cas de perte du mot de passe, utilisez Rotate password pour en émettre un nouveau.

7. Cliquez sur Done. Les nouveaux identifiants apparaissent maintenant dans la liste.

Configurer le système d’envoi

Saisissez les identifiants dans le MTA ou l’application d’envoi:

Paramètre	Valeur
Serveur SMTP	L’adresse IP de votre HIN Gateway
Port	587
Chiffrement	STARTTLS
Authentification	Nom d’utilisateur et mot de passe (SMTP AUTH)
Nom d’utilisateur	Le nom d’utilisateur de l’étape 6
Mot de passe	Le mot de passe de l’étape 6

L’adresse de l’expéditeur (MAIL FROM) doit appartenir au domaine pour lequel les identifiants ont été créés, sinon le message est rejeté.

Gérer les identifiants existants

Chaque jeu d’identifiants de la section SMTP authentication (port 587) propose deux actions:

• Rotate password: génère un nouveau mot de passe. L’ancien mot de passe cesse de fonctionner, mettez donc immédiatement à jour le système d’envoi.
• Delete: supprime les identifiants. Tout système qui les utilise encore ne peut plus envoyer via HIN Gateway.

Tip

Créez des identifiants distincts pour chaque système d’envoi. Vous pourrez ainsi renouveler ou révoquer l’accès d’un système sans affecter les autres.

Authentification des connexions sortantes

Lorsque HIN Gateway transmet les messages d’un domaine au saut suivant (par exemple un relais de messagerie ou un serveur de messagerie), ce dernier peut exiger que l’expéditeur se connecte avant d’accepter le courrier. L’authentification des connexions sortantes permet à HIN Gateway de s’authentifier auprès du saut suivant avec un nom d’utilisateur et un mot de passe (SMTP AUTH).

Fonctionnement:

• Chaque domaine dispose de son propre Outbound relay (hôte et port) dans le tableau de bord HIN Gateway
• Lorsque Require authentication est actif, HIN Gateway se connecte au relais sortant avec les identifiants que vous avez saisis avant de transmettre un message

Avant de commencer

• Vous devez avoir accès au tableau de bord HIN Gateway
• Le domaine doit déjà être ajouté dans HIN Gateway et activé (onboarded)
• Demandez le nom d’utilisateur et le mot de passe à l’administrateur du côté destinataire (le relais ou le serveur de messagerie qui exige l’authentification)

Configurer les identifiants

1. Connectez-vous au tableau de bord HIN Gateway.
2. Ouvrez Domains et sélectionnez le domaine.

3. Faites défiler la page jusqu’à Mail routing et repérez la section Outbound.

   

   Vérifiez que Outbound relay affiche l’hôte et le port corrects du saut suivant (par exemple relay.example.com:25). Ces identifiants sont utilisés uniquement pour ce relais.

4. Cliquez sur le commutateur Require authentication pour qu’il affiche Active. Les champs Username et Password apparaissent.

   

5. Saisissez le Username et le Password configurés du côté destinataire. Cliquez sur l’icône en forme d’œil pour afficher le mot de passe et vérifier qu’il ne contient pas de faute de frappe.

6. Faites défiler la page vers le bas et cliquez sur Save.

Désormais, HIN Gateway s’authentifie auprès du relais sortant chaque fois qu’il transmet un message pour ce domaine.

Vérifier la configuration

Envoyez un message de test via HIN Gateway à un destinataire situé derrière le relais sortant et vérifiez qu’il arrive. Si ce n’est pas le cas, ouvrez Logs dans le tableau de bord et recherchez les erreurs d’authentification renvoyées par le relais. Les causes les plus fréquentes sont:

• Nom d’utilisateur ou mot de passe incorrect
• Le relais ne prend pas en charge ou n’autorise pas SMTP AUTH sur le port configuré
• L’hôte ou le port de l’Outbound relay est incorrect

Modifier ou supprimer les identifiants

• Changer le mot de passe: lorsque le côté destinataire change le mot de passe, saisissez le nouveau dans le champ Password et cliquez sur Save. D’ici là, l’authentification des messages envoyés au relais échoue.
• Désactiver l’authentification: cliquez sur Require authentication pour qu’il affiche Inactive, puis cliquez sur Save. HIN Gateway se connecte alors au relais sans authentification.

Installation serveur

Conteneur

Déploiement Docker de Stargate

Prérequis

Exigences du serveur :

Veuillez vous référer aux Exigences recommandées

• Docker sera installé automatiquement s'il manque
• Assurez-vous qu'il y a une connexion Internet sur la machine où vous installez les services Stargate
• Assurez-vous que le trafic est correctement configuré pour atteindre l'instance Stargate

Étape 1: Configurer les paramètres client

Tip

Vous pouvez cloner notre dépôt avec toutes les données et exemples de configurations à l'intérieur avec la commande:

git clone https://github.com/Health-Info-Net-AG/Stargate-deployment.git

Si vous n'avez pas git installé, vous pouvez toujours obtenir une archive avec tous les fichiers à l'intérieur. Téléchargez-la via le lien suivant. Télécharger en ZIP

Le script d'installation crée automatiquement customer-config.sh à partir du modèle fourni lors du premier lancement, de sorte qu'une nouvelle installation ne nécessite aucune configuration manuelle. Si vous préférez le créer vous-même, copiez le modèle:

cp customer-config-prod.example.sh customer-config.sh

Vous n'avez pas besoin de le modifier - chaque valeur est soit détectée automatiquement, soit configurée ultérieurement via le tableau de bord:

Paramètre	Comment il est défini
SERVER_STATIC_IP	Détecté automatiquement à partir de l'interface réseau principale du serveur.
CUSTOMER_NAME	Par défaut, le nom d'hôte du système.
DEPLOYMENT_NAME	Dérivé de CUSTOMER_NAME (utilisé dans les étiquettes de logs et le nom d'hôte Alloy).
Mots de passe et clés (POSTGRES_PASSWORD, S3_SECRET_KEY, WG_PRIVATE_KEY)	Générés de manière sécurisée au premier lancement et réécrits dans customer-config.sh.

Les domaines de courrier, le nom d'hôte de messagerie, les certificats S/MIME et les pairs WireGuard sont tous configurés à l'exécution via le tableau de bord une fois la pile démarrée - ils ne font pas partie de customer-config.sh.

Derrière un NAT ou une IP flottante ?

La détection automatique utilise l'IP de l'interface principale du serveur. Si votre serveur est joignable via une autre IP publique ou flottante (fréquent avec le NAT), définissez SERVER_STATIC_IP sur cette IP publique dans customer-config.sh avant l'installation, afin que les URL du tableau de bord et de connexion Keycloak pointent vers l'adresse joignable. Sinon, laissez-le vide.

Paramètres du certificat S/MIME :

Paramètre	Description	Défaut
CERT_CA_IRISAGENT_DOMAIN	Domaine CA pour l'émission de certificats via le tunnel WireGuard	hintest.ch

Note

La configuration du pair WireGuard est effectuée à l'exécution via le tableau de bord (page /installation). Les détails du pair sont configurés par déploiement après le démarrage de la pile - ils ne font pas partie de customer-config.sh.

Paramètres locaux WireGuard (généralement laissés par défaut) :

Paramètre	Défaut	Description
WG_PRIVATE_KEY	(auto-généré)	Généré par IRISAgent lors de la première exécution, puis sauvegardé dans customer-config.sh
WG_LOCAL_IP	SERVER_STATIC_IP	Auto-dérivé. Remplacez uniquement si vous avez besoin d'une adresse de tunnel différente.
WG_INTERFACE_PORT	19818	Port du tunnel WireGuard (TCP et UDP sont exposés)
WG_TRANSPORT_MODE	tcp	Protocole de transport: tcp (par défaut, fonctionne à travers la plupart des pare-feu) ou udp

Paramètres optionnels (ont des valeurs par défaut raisonnables) :

Paramètre	Défaut	Description
POSTGRES_PASSWORD	(auto-généré)	Mot de passe aléatoire de 24 caractères auto-généré si vide
S3_SECRET_KEY	(auto-généré)	Clé secrète S3 pour le stockage d'objets
OUTBOUND_SEALER_MX_DOMAIN	hintest.ch	Domaine MX du scelleur pour la livraison des sceaux sortants
POLICY_SYNC_REPO_URL	GitHub HIN Stargate policies	URL du dépôt Git pour la synchronisation des politiques OPA/Rego
LOKI_URL	(non défini)	Point de terminaison Loki pour l'envoi centralisé des logs (ex. https://loki.example.com)

Auto-générés (ne pas définir manuellement) :

• WG_PRIVATE_KEY — Généré par IRISAgent lors de la première exécution, sauvegardé dans customer-config.sh

Étape 2: Déployer sur un serveur

Tip

Vous pouvez cloner notre dépôt avec toutes les données et exemples de configurations à l'intérieur avec la commande:

git clone https://github.com/Health-Info-Net-AG/Stargate-deployment.git && \
  cd Stargate-deployment-main

Si vous n'avez pas git installé, vous pouvez toujours obtenir une archive avec tous les fichiers à l'intérieur et l'extraire:

wget https://github.com/Health-Info-Net-AG/Stargate-deployment/archive/refs/heads/main.zip && \
  unzip main.zip && \
  rm main.zip && \
  cd Stargate-deployment-main

Copiez manuellement les fichiers sur le serveur

scp -r docker-compose/* votre-serveur:/chemin/vers/stargate/

SSH vers le serveur

ssh votre-serveur
cd /chemin/vers/stargate

Créez la configuration client à partir du modèle et remplissez les paramètres requis (voir Étape 1

cp customer-config-prod.example.sh customer-config.sh
nano customer-config.sh   # Remplir les paramètres requis (voir Étape 1)

Exécutez l'installation

chmod +x scripts/*.sh
./scripts/install.sh

Étape 3: Ce que fait l'installation

Le script d'installation (install.sh) effectue les étapes suivantes:

1. Vérifier les dépendances — Détecte Docker, Docker Compose et jq. S'ils manquent, les installe automatiquement (prend en charge Ubuntu/Debian, RHEL/AlmaLinux/Rocky).
2. Charger et valider customer-config.sh — Vérifie les champs requis (SERVER_STATIC_IP, CUSTOMER_NAME, DEPLOYMENT_NAME). Dérive automatiquement les champs optionnels (URL MXEngine, etc.).
3. Générer .env à partir de la configuration client — Génère automatiquement les mots de passe s'ils ne sont pas définis.
4. Démarrer tous les services via Docker Compose (infrastructure + applications).
5. Initialiser Vault — Le conteneur vault-init initialise, descelle et crée les montages de secrets KV-v2. Écrit éventuellement la clé privée WireGuard dans Vault.
6. Sauvegarder les clés Vault dans secrets/vault-keys.json et mettre à jour .env avec le jeton root. Le jeton est également sauvegardé dans customer-config.sh pour la persistance à travers les recréations de VM.
7. Redémarrer les services d'application pour prendre en compte le jeton Vault.
8. Sauvegarder la clé privée WireGuard dans customer-config.sh — extraite de Vault après que IRISAgent l'a générée.
9. Configurer la tâche cron de sauvegarde quotidienne (s'exécute à 2h00).

Une fois l'installation terminée, la pile fonctionne mais aucun domaine de courrier, certificat S/MIME ou pair WireGuard n'est encore configuré. Continuez avec Étape 4: Intégration via le tableau de bord.

Étape 4: Intégration via le tableau de bord

Après l'installation, terminez l'intégration via le tableau de bord à l'adresse https://<SERVER_STATIC_IP>. Le tableau de bord vous guide à travers trois pages dans l'ordre:

/installation — Configuration du pair WireGuard

Effectue la négociation nonce/HIN pour établir une connexion pair WireGuard, et sauvegarde la configuration WireGuard résultante dans le service IRISAgent.

/onboarding — Certificat S/MIME

Génère la clé de signature S/MIME et le CSR via le service smimekeys et soumet le CSR à la CA via le tunnel WireGuard maintenant établi. (Ceci remplace l'ancien flux de certificats basé sur des scripts.)

/mail — Domaines de courrier et configuration du relais

Soumet le nom d'hôte et la liste des domaines de relais au service mtaconf via son API REST. Le démon applique la configuration à Stalwart sans redémarrer le conteneur.

Ajouter ou modifier des domaines ultérieurement

Rouvrez la page /mail dans le tableau de bord, modifiez la liste des domaines et soumettez. Le démon applique la modification à l'exécution - pas d'invocation de script, pas de modification de .env, pas de redémarrage de service nécessaire.

Étape 5: Enregistrement du pair WireGuard

La soumission du CSR S/MIME sur /onboarding échouera si votre instance Stargate n'est pas encore enregistrée en tant que pair WireGuard côté CA HIN. C'est le problème le plus courant lors de la configuration initiale.

La page /installation du tableau de bord gère l'enregistrement automatique du pair WireGuard via la négociation nonce/HIN. Si l'enregistrement automatique échoue, l'enregistrement manuel peut être effectué en fournissant les valeurs suivantes à HIN:

1. Clé publique WireGuard — extraire des logs irisagent:

docker compose logs irisagent | grep "public key"

1. DEPLOYMENT_NAME — depuis votre customer-config.sh
2. SERVER_STATIC_IP — l'IP publique de votre serveur Stargate
3. WG_INTERFACE_PORT — seulement si vous l'avez modifié par rapport au défaut 19818

Une fois l'enregistrement du pair confirmé :

Réexécutez la page /onboarding dans le tableau de bord pour régénérer le CSR et le soumettre via le tunnel maintenant actif.

Pour vérifier le tunnel avant de demander le certificat :

Redémarrez uniquement irisagent

docker compose restart irisagent

Vérifiez la négociation WireGuard réussie

docker compose logs irisagent 2>&1 | grep -i "handshake\|peer"

Tip

Vérifiez votre pare-feu: Le port 19818/TCP doit être ouvert dans les deux sens, entrant et sortant sur le serveur Stargate.

Étape 6: Recommandations post-intégration

Une fois le certificat émis et les courriels circulant, deux éléments de configuration sont fortement recommandés pour tout déploiement en production. Les ignorer ne casse pas le chiffrement, mais dégradera votre réputation d'expéditeur, provoquera des avertissements "nous ne pouvons pas vérifier l'expéditeur" dans Outlook/Gmail, et peut éventuellement conduire à un blocage des courriels sortants.

Étape 6.1 SPF / DKIM / DMARC pour les domaines expéditeurs

Stargate envoie des courriels depuis sa propre IP publique au nom de vos utilisateurs. Sans enregistrements d'authentification DNS appropriés, les destinataires verront des avertissements "nous ne pouvons pas vérifier cet expéditeur" et pourront rejeter le courrier.

Pour des instructions complètes sur la configuration des enregistrements SPF, DKIM, DMARC et PTR, consultez le Guide de configuration DNS.

Au minimum, pour chaque domaine que vous acheminez via Stargate:

• SPF: ajoutez ip4:<STARGATE_IP> à l'enregistrement TXT du domaine
• DMARC: publiez v=DMARC1; p=none à _dmarc.<VOTRE_DOMAINE>
• PTR: définissez le DNS inversé pour l'IP Stargate pour qu'il corresponde à MAIL_HOSTNAME

Étape 6.2 Relayer les courriels sortants via votre plateforme de courrier (recommandé pour M365 / Exchange Online)

Par défaut, après que Stargate a signé/chiffré un courrier sortant, il le livre directement au MX du destinataire. Cela fonctionne, mais l'IP de connexion est l'IP de votre Stargate - et à moins que cette IP ait des années de bonne réputation, elle peut finir sur des listes noires tierces (ex. Barracuda, Abusix), provoquant des échecs de livraison intermittents.

Le modèle recommandé est d'envoyer le courrier signé via votre locataire M365 / Exchange afin que le dernier saut vers l'Internet soit l'infrastructure bien réputée de Microsoft. Stargate signe et vérifie toujours chaque message par politique ; seul le dernier saut change. Cela reflète le modèle de connecteur "Envoyer à MX" de l'ancien HIN MGW.

Côté Stargate — relais par domaine

Configurez le relais par domaine via la page /mail du tableau de bord. Chaque domaine peut être mappé à son propre point de terminaison entrant M365 / Exchange ; le tableau de bord envoie le mappage à l'API REST de mtaconf et Stalwart est reconfiguré à l'exécution.

Après que mxengine a signé le courrier, Stalwart le renverra à votre locataire sur le port 25 avec TLS au lieu de le livrer directement au MX du destinataire. Voir Exchange-integration.md pour la syntaxe complète par domaine.

Côté M365 / Exchange Online

Vous recréez essentiellement le même ensemble de connecteurs + règles de transport que l'ancien HIN MGW (le manuel O365 original de HIN MGW est la référence - les mêmes cinq règles s'appliquent). Le minimum est:

1. Connecteur entrant - accepte les courriels de Stargate, identifié par le certificat TLS (le sujet du certificat doit correspondre à un domaine accepté dans votre locataire). Un certificat auto-signé sur Stargate sera rejeté par ce connecteur - utilisez un certificat valide émis par une AC (Let's Encrypt convient).
2. Connecteur sortant "Envoyer à MX" - livre au MX du destinataire, activé uniquement par règle de transport.
3. Règle de transport set_header - étiquette les courriels sortants avec un en-tête comme outgoing: outgoing_<domaine> avant qu'ils ne quittent O365 la première fois, afin que le voyage de retour puisse le reconnaître.
4. Règle de transport outgoing_to_mx - correspond à l'en-tête outgoing_<domaine> sur les courriels revenant de Stargate et les achemine via le connecteur "Envoyer à MX".
5. Règle de transport mgw_bypass_antispam - contourne le filtrage anti-spam sur les courriels revenant de Stargate.

mxengine ne supprime pas les en-têtes arbitraires, donc l'étiquette outgoing_<domaine> définie par set_header survit à l'aller-retour et déclenche outgoing_to_mx correctement.

Pourquoi ce modèle est important

Avec la configuration de relais de retour, l'expéditeur public vers l'Internet est Microsoft. Combiné avec SPF/DKIM/DMARC corrects (section 6.1), les destinataires voient une IP Microsoft avec spf=pass et dkim=pass alignés sur votre domaine - ce qui est le profil de réputation le plus propre que vous puissiez leur donner.

Voir Exchange-integration.md pour des instructions étape par étape complètes, y compris des captures d'écran.

Démarrages ultérieurs (après redémarrage)

L'installateur active une unité systemd stargate, donc la pile démarre automatiquement au démarrage. Pour la démarrer manuellement:

sudo systemctl start stargate

Cela exécute start.sh, qui:

1. Démarre les services d'infrastructure
2. Descelle Vault en utilisant les clés stockées
3. Démarre les services d'application

(./scripts/start.sh fonctionne toujours directement si vous préférez.)

Arrêter les services

sudo systemctl stop stargate

(ou ./scripts/stop.sh directement)

Cela arrête les conteneurs mais préserve toutes les données.

Persistance des données

Toutes les données sont stockées dans des volumes Docker et persistent à travers les redémarrages.

Service	Volume	Données
PostgreSQL	postgres_data	Toutes les bases de données (smimekeys, policy, irisagent, mxengine)
Vault	vault_data	Clés de chiffrement, secrets, clés S/MIME
SeaweedFS	seaweedfs_data	Stockage d'objets (messages, pièces jointes)
Stalwart	stalwart_data	État du serveur de courrier

Opérations sûres (données préservées)

Arrêter et démarrer:

sudo systemctl stop stargate
sudo systemctl start stargate

Ou en utilisant les scripts directement:

./scripts/stop.sh
./scripts/start.sh

N'utilisez pas les commandes docker compose directement

Utilisez toujours systemctl ou les scripts fournis (start.sh / stop.sh) pour gérer le déploiement. L'exécution directe de docker compose up, docker compose down ou docker compose restart ne descellera pas Vault, laissant les services dépendants incapables de démarrer. Le script start.sh gère la procédure de descellage de Vault automatiquement.

Comportement de scellement de Vault

Vault se scelle lorsque son conteneur redémarre. C'est une fonctionnalité de sécurité.

Le script start.sh (et le service systemd) descellent automatiquement Vault en utilisant les clés stockées dans secrets/vault-keys.json. C'est pourquoi vous devez toujours utiliser les scripts fournis ou le service systemd pour gérer la pile.

Opérations destructrices (données supprimées)

Warning

Ces commandes SUPPRIMENT TOUTES LES DONNÉES - à utiliser avec prudence !

Vous ne pouvez restaurer les données que si vous effectuez des opérations de sauvegarde au préalable et que vous sauvegardez la sauvegarde dans un endroit sûr.

Danger

Tout supprimer (volumes, secrets, config)

./scripts/purge.sh

Référence des scripts

Script	Objectif
install.sh	Première installation (Docker, Vault). La configuration du domaine/certificat/pair se fait ensuite dans le tableau de bord.
update.sh	Régénérer .env à partir de customer-config.sh (en ajoutant les nouvelles variables du modèle), télécharger les images figées et recréer les conteneurs (préserve le jeton Vault). Sur les appliances VM, les versions se changent depuis le tableau de bord - voir Mettre à jour HIN Gateway
start.sh	Démarrer les services et desceller Vault
stop.sh	Arrêter les conteneurs (données préservées)
backup.sh	Sauvegarde complète (base de données, clés Vault, configuration, certificats) ; --config-only sauvegarde uniquement customer-config.sh
restore.sh	Restaurer à partir d'une archive de sauvegarde (fonctionne sur une nouvelle machine) ; --config-only restaure uniquement customer-config.sh
purge.sh	Supprimer TOUTES les données (nécessite confirmation)
health-check.sh	Contrôle de santé complet de tous les services (code de sortie 0 = sain, 1 = échecs)
init-vault.sh	Initialisation Vault (utilisé par le conteneur vault-init, ne pas appeler directement)
init-keycloak.sh	Configuration du mot de passe administrateur Keycloak (utilisé par le conteneur keycloak-init, ne pas appeler directement)
gather-app-versions.sh	Collecte les versions des applications depuis les points de terminaison /liveness pour node-exporter (s'exécute dans le conteneur version-collector)

Fichiers de configuration

Fichier	Objectif
customer-config-prod.example.sh	Modèle pour les paramètres client (copier vers customer-config.sh)
customer-config.sh	Paramètres spécifiques au client (créés à partir du modèle, remplir avant l'installation)
.env	Fichier d'environnement généré (créé par install.sh)
secrets/vault-keys.json	Clés de descellage Vault et jeton root (sauvegarder en toute sécurité !)
secrets/signing-key.csr	CSR généré pour le certificat S/MIME

Support

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance Stargate, veuillez contacter le support HIN.

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.

Configuration avancée de Stargate Docker

Sauvegardes

Sauvegardes automatiques

• Les sauvegardes quotidiennes s'exécutent à 2h00 via cron (configurées lors de l'installation)
• Les sauvegardes sont stockées dans ./backups/ sous forme de fichiers .tar.gz horodatés
• Les anciennes sauvegardes (>7 jours) sont automatiquement nettoyées

Ce qui est inclus dans les sauvegardes

• Dump PostgreSQL complet (toutes les bases de données avec utilisateurs et permissions)
• Dumps de bases de données individuelles (pour une restauration partielle si nécessaire)
• Clés Vault (vault-keys.json pour le descellage)
• Configuration client (customer-config.sh avec la clé WireGuard)
• CSR et certificats S/MIME (tous les fichiers .crt, .pem, .cer)
• Manifeste de sauvegarde (manifest.json avec métadonnées)

Sauvegarde manuelle

./scripts/backup.sh

Crée une archive compressée dans ./backups/YYYYMMDD_HHMMSS.tar.gz.

Restauration à partir d'une sauvegarde

Pour restaurer sur une nouvelle machine ou après une purge. Copiez l'archive de sauvegarde sur la nouvelle machine et exécutez:

./scripts/restore.sh backups/20260130_143022.tar.gz

Le script de restauration va:

1. Arrêter tous les services en cours d'exécution
2. Extraire et valider la sauvegarde
3. Installer Docker si nécessaire
4. Restaurer la configuration client
5. Démarrer les services d'infrastructure (PostgreSQL, Vault, MinIO)
6. Restaurer la base de données
7. Desceller Vault avec les clés sauvegardées
8. Démarrer les services d'application

Sauvegarder et restaurer uniquement la configuration

Pour conserver uniquement customer-config.sh lors d’une purge suivie d’une réinstallation, par exemple pour changer l’adresse IP du serveur avant l’intégration (voir Dépannage et diagnostic) :

./scripts/backup.sh --config-only
./scripts/restore.sh --config-only /var/data/backups/20260130_143022_config-only.tar.gz

• backup.sh --config-only sauvegarde customer-config.sh et les éventuels serveurs NTP personnalisés (ntp.sources) dans /var/data/backups/<timestamp>_config-only.tar.gz. Il ne nécessite aucun service en cours d’exécution, exclut .env, les clés Vault et les bases de données, et ne supprime aucune sauvegarde plus ancienne.
• restore.sh --config-only restaure uniquement ces deux fichiers, à partir d’une archive de configuration seule ou d’une sauvegarde complète. Il ne demande aucune confirmation, conserve un fichier existant sous customer-config.sh.bak.<timestamp> et affiche les étapes suivantes.
• Une restauration complète à partir d’une archive de configuration seule est refusée.

L’archive contient les mots de passe générés et la clé privée WireGuard : traitez-la comme un secret.

Restauration partielle (base de données unique)

Si vous avez seulement besoin de restaurer une base de données:

Extraire la sauvegarde

tar -xzf backups/20260130_143022.tar.gz -C /tmp/

Restaurer une base de données spécifique

cat /tmp/20260130_143022/database/mxengine.sql | docker exec -i stargate-postgres psql -U postgres -d mxengine

Mise à jour de Stargate

La méthode de mise à jour dépend du type d'installation:

• Appliance VM (image bootc) - les images VM du HIN Gateway. L'ensemble du système d'exploitation, y compris Docker, les scripts de déploiement, docker-compose.yml et les versions figées des images de services, est livré sous la forme d'une seule image versionnée. La mise à jour consiste à basculer vers une image plus récente puis à redémarrer.
• Installation Compose simple - un git clone de ce dépôt sur une machine que vous gérez vous-même. La mise à jour consiste à extraire un tag de version plus récent.

Appliance VM (bootc)

Sur l'appliance, /usr/share/stargate-deployment fait partie de l'image système en lecture seule. Il n'y a pas de copie git à mettre à jour ou à réinitialiser; n'y exécutez donc ni git ni update.sh --release. Toutes les données - configuration, secrets, e-mails et bases de données - se trouvent sur le Data Disk sous /var/data et ne sont pas modifiées par une mise à jour.

Mise à jour depuis le tableau de bord

Utilisez la section System version de la page Settings du tableau de bord - voir Mettre à jour HIN Gateway pour le guide pas à pas. Lorsque vous lancez le téléchargement, l'ops-agent:

1. Crée une sauvegarde complète avec backup.sh, nommée <version actuelle>-pre_update_to_<version cible>, dans /var/data/backups/. Si la sauvegarde échoue, la mise à jour est annulée et rien n'est modifié. Seule exception: une sauvegarde dont la partie Vault est incomplète; la mise à jour continue et l'ops-agent journalise l'avertissement pre-update backup is missing Vault secrets; continuing.
2. Télécharge et prépare l'image système cible (bootc switch). Le système en cours d'exécution n'est pas encore modifié.
3. Active la nouvelle version au prochain redémarrage - immédiatement avec Restart now, ou au prochain redémarrage de la machine avec Later.

Mise à jour en ligne de commande

Connectez-vous à la VM en tant que hinadmin (ssh hinadmin@<adresse IP de la VM>) et utilisez les raccourcis fournis avec l'image:

hingateway-tags              # list the published versions
hingateway-switch vX.Y.Z     # download and stage the target version
sudo systemctl reboot        # boot into it
hingateway-status            # confirm: Booted: vX.Y.Z, Rollback: <previous version>

Note

Contrairement au tableau de bord, hingateway-switch ne crée pas de sauvegarde au préalable. Exécutez sudo /usr/share/stargate-deployment/docker-compose/scripts/backup.sh --label <version actuelle>-pre_update_to_vX.Y.Z avant de basculer, afin que l'archive soit nommée comme celle créée par le tableau de bord. La version actuelle est celle que hingateway-status affiche comme démarrée.

Retour arrière

L'appliance conserve deux déploiements système sur le disque: celui en cours d'exécution et le précédent. Pour revenir au précédent, utilisez le bouton Roll back du tableau de bord (voir Mettre à jour HIN Gateway) ou exécutez:

hingateway-rollback && sudo systemctl reboot

Le retour arrière ne nécessite aucun téléchargement. Pour revenir plus loin que la version précédente, basculez explicitement vers cette version avec hingateway-switch <tag>.

Le retour arrière restaure l'image système, pas les données

Un retour arrière remplace uniquement l'image système; les données sous /var/data restent telles que la version plus récente les a laissées. Si la version plus récente a modifié un schéma de base de données (par exemple la mise à niveau de Keycloak dans la 1.1.7), l'ancienne version ne peut pas fonctionner avec. Dans ce cas, effectuez le retour arrière de l'image système puis restaurez la sauvegarde créée avant la mise à jour - l'archive de /var/data/backups/ dont le nom se termine par pre_update_to_<version cible>.tar.gz - avec sudo /usr/share/stargate-deployment/docker-compose/scripts/restore.sh <archive>. La sauvegarde nocturne supprime les archives de plus de 7 jours, celle-ci comprise; copiez-la donc hors de la VM si vous risquez d'en avoir besoin plus tard. La mise à jour de 0.6.x vers 1.1.7 fait exception: dans ce cas, l'instantané de la VM est le seul moyen de revenir en arrière (voir Mettre à jour HIN Gateway).

Pas de retour arrière au-delà de la première image avec Data Disk

La première mise à niveau vers une image prenant en charge le Data Disk est irréversible. Une image plus ancienne sans prise en charge du Data Disk ne monte pas ce disque: la pile démarre avec un /var/data vide, tandis que vos données réelles restent intactes sur le disque non monté. Cela ressemble à une perte totale de données, mais n'en est pas une - une nouvelle mise à niveau vers la version récente remonte le disque.

Ce qu'une mise à jour conserve

/etc est fusionné avec la nouvelle image (les modifications locales sont prioritaires) et /var - y compris /home, les données Docker et les comptes utilisateurs - est conservé. Les paquets installés ponctuellement avec rpm-ostree install survivent aux redémarrages mais sont supprimés au prochain basculement; seul le contenu de l'image est permanent.

Installation Compose simple

Cette section s'applique uniquement à un git clone de ce dépôt que vous gérez vous-même, pas à l'appliance VM. Exécutez toutes les commandes depuis le répertoire docker-compose/ de votre copie. Les scripts lisent et écrivent des fichiers sous /var/data/vereign/ que seul root peut lire; exécutez-les donc en tant que root ou avec sudo. La copie doit également appartenir à root (clonez-la en tant que root): lorsque les scripts s'exécutent en tant que root dans une copie appartenant à un autre utilisateur, git refuse de la lire et la version du déploiement s'affiche comme unknown. Si la copie appartient à un autre utilisateur, autorisez-la une fois avec sudo git config --global --add safe.directory <path to the checkout> et exécutez les commandes git ci-dessous en tant que cet utilisateur, sans sudo.

1. Créez une sauvegarde avant la mise à jour

sudo ./scripts/backup.sh

Copiez l'archive hors de la machine si vous risquez d'en avoir besoin plus tard: la sauvegarde nocturne supprime les archives de plus de 7 jours.

2. Extrayez la version cible

Le dépôt est la source unique de vérité pour les fichiers suivis. Mettez donc à jour en extrayant un tag de version. Cela remplace les fichiers suivis (scripts, docker-compose.yml avec les versions figées des images, modèles de configuration) par ceux de cette version:

sudo git fetch --tags origin
sudo git tag --sort=-creatordate | head    # most recent releases
sudo git checkout -f vX.Y.Z

3. Vérifiez les nouvelles variables de configuration

Comparez les noms de variables du modèle de configuration de la version avec votre configuration existante pour voir si de nouvelles variables ont été ajoutées. Seuls les noms sont comparés, vos valeurs et identifiants ne sont donc pas affichés; les lignes commençant par > sont les nouvelles variables:

sudo -v    # enter the sudo password before the comparison starts
diff <(sudo grep -oE '^[A-Za-z_][A-Za-z0-9_]*=' /var/data/vereign/customer-config.sh | sort) \
     <(grep -oE '^[A-Za-z_][A-Za-z0-9_]*=' customer-config-prod.example.sh | sort)

Faites-le avant l'étape suivante: update.sh ajoute chaque variable manquante à votre customer-config.sh avec la valeur par défaut du modèle, de sorte que les nouvelles variables n'apparaissent plus ensuite comme des différences. Définissez dès maintenant dans customer-config.sh toute nouvelle variable qui nécessite une valeur autre que celle par défaut.

4. Appliquez la version

sudo ./scripts/update.sh

update.sh régénère .env à partir de customer-config.sh, télécharge les images figées dans docker-compose.yml et recrée les services concernés. Sa sortie est ajoutée à /var/data/vereign/update.log, l'exécution la plus récente se trouvant à la fin.

5. Redémarrez la pile

sudo ./scripts/start.sh

update.sh recrée systématiquement Vault (et Dozzle, s'il est activé), mais ne recrée les autres services que si leur définition a changé. Un service dont le fichier de configuration a changé dans la version (par exemple la configuration de Caddy, APISIX ou Loki) peut donc continuer à fonctionner avec l'ancien fichier. start.sh recrée tous les conteneurs, de sorte que tous prennent en compte les nouveaux fichiers. La pile redémarre ainsi une seconde fois; planifiez donc la mise à jour dans une fenêtre de maintenance.

Note

Votre customer-config.sh, .env et le répertoire secrets/ se trouvent sous /var/data/vereign/, entièrement en dehors de la copie du dépôt, donc git checkout -f n'y touche jamais - votre configuration et vos identifiants sont préservés. Effectuez toujours vos personnalisations dans customer-config.sh, jamais en modifiant des fichiers suivis comme docker-compose.yml: la prochaine extraction annule toute modification des fichiers suivis. C'est intentionnel; le fait que chaque déploiement reste identique au dépôt est ce qui permet aux mises à jour de s'appliquer de manière fiable et sans résolution manuelle de conflits.

Pour effectuer un retour arrière, extrayez le tag de la version précédente et exécutez à nouveau les étapes 4 et 5. Si la version plus récente a modifié un schéma de base de données, n'exécutez pas les étapes 4 et 5: après avoir extrait le tag précédent, restaurez plutôt la sauvegarde effectuée avant la mise à jour avec sudo ./scripts/restore.sh <archive> (voir Restauration à partir d'une sauvegarde). restore.sh arrête la pile, restaure les données et démarre les services de la version extraite.

update.sh supprime déjà les images inutilisées de plus de 24 heures. Pour libérer immédiatement de l'espace disque, exécutez sudo docker image prune -af.

Ne pas changer les versions à la main

Warning

Les versions des images sont figées dans docker-compose.yml, pas dans customer-config.sh ou .env - ceux-ci ne contiennent plus de valeurs *_VERSION. Ne modifiez pas un tag d'image à la main: les versions sont publiées et testées ensemble en tant qu'ensemble, et en choisir une à la main produit une combinaison non testée. Sur l'appliance VM, le fichier est de toute façon en lecture seule. Changez toujours de version comme décrit ci-dessus.

Configuration

Le fichier .env est généré par install.sh à partir de customer-config.sh. Les paramètres de domaine, de certificat et de WireGuard sont gérés à l'exécution par le tableau de bord (/installation, /onboarding, /mail) — ils ne sont pas conservés dans .env. Pour personnaliser les paramètres d'installation, modifiez customer-config.sh et réexécutez install.sh.

Sections clés dans le .env généré:

## PostgreSQL (auto-généré si vide dans customer-config.sh)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<auto-généré>

## Vault (auto-rempli après initialisation)
VAULT_TOKEN_<SERVICE>=<auto-généré, un par service>

## Stockage d'objets S3 (SeaweedFS)
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=<auto-généré>

## Versions des applications
SMIMEKEYS_VERSION=v0.0.5
POLICY_VERSION=v0.0.5
IRISAGENT_VERSION=v0.0.6-branch
MXENGINE_VERSION=v0.0.35
MTACONF_VERSION=dev

## Chemin de courrier sortant
MXENGINE_PUBLIC_ADDRESS=http://localhost:8084
OUTBOUND_SEALER_MX_DOMAIN=hintest.ch

## WireGuard
WG_LOCAL_IP=203.0.113.50
WG_INTERFACE_PORT=19818
WG_TRANSPORT_MODE=tcp

Warning

Ne modifiez pas .env directement. Les modifications seront écrasées lors de la réexécution de install.sh. Pour la configuration d'exécution (domaines, nom d'hôte, pairs, S/MIME), utilisez le tableau de bord.

URLs des services

Service	URL/Port
Tableau de bord	https://localhost
smimekeys-client	http://localhost:8081
policy	http://localhost:8082
irisagent	http://localhost:8083
mxengine HTTP	http://localhost:8084
Stalwart SMTP	localhost:25
Passerelle APISIX	http://localhost:9080
Keycloak	https://localhost:8180

Contrôles de santé

Tous les services exposent un point de terminaison /liveness:

curl http://localhost:8081/liveness  # smimekeys-client
curl http://localhost:8082/liveness  # policy
curl http://localhost:8083/liveness  # irisagent
curl http://localhost:8084/liveness  # mxengine

Surveillance

Métriques Prometheus

Tous les services d'application exposent des métriques Prometheus sur le port 2112 (en interne), mappés à différents ports hôtes:

Service	Port des métriques	URL des métriques
smimekeys-client	2113	http://localhost:2113/metrics
irisagent	2114	http://localhost:2114/metrics
policy	2115	http://localhost:2115/metrics
mxengine	2116	http://localhost:2116/metrics
node-exporter	9100	http://localhost:9100/metrics

Exemple de configuration de récupération Prometheus

scrape_configs:
  - job_name: 'stargate-smimekeys'
    static_configs:
      - targets: ['<hôte>:2113']
  - job_name: 'stargate-irisagent'
    static_configs:
      - targets: ['<hôte>:2114']
  - job_name: 'stargate-policy'
    static_configs:
      - targets: ['<hôte>:2115']
  - job_name: 'stargate-mxengine'
    static_configs:
      - targets: ['<hôte>:2116']
  - job_name: 'stargate-node'
    static_configs:
      - targets: ['<hôte>:9100']

Vérification rapide des métriques

## Vérifier tous les points de terminaison de métriques
curl -s http://localhost:2113/metrics | head -20  # smimekeys-client
curl -s http://localhost:2114/metrics | head -20  # irisagent
curl -s http://localhost:2115/metrics | head -20  # policy
curl -s http://localhost:2116/metrics | head -20  # mxengine
curl -s http://localhost:9100/metrics | head -20  # node-exporter

Collecte de logs (Alloy → Loki)

Alloy collecte les logs des conteneurs d'application et les envoie à Loki.

Conteneurs surveillés:

• stargate-apisix
• stargate-keycloak
• stargate-dashboard
• stargate-smimekeys-client
• stargate-policy
• stargate-policy-sync
• stargate-irisagent
• stargate-mxengine

Configuration dans .env:

## URL de poussée Loki
LOKI_URL=https://loki.example.com

## Étiquette de nom d'hôte pour les logs (auto-définie sur DEPLOYMENT_NAME)
ALLOY_HOSTNAME=stargate-acme

Étiquettes ajoutées aux logs:

• environment=<DEPLOYMENT_NAME> - Identifie le déploiement
• host=<ALLOY_HOSTNAME> - Identifie l'hôte (identique au nom du déploiement)
• container=<nom-conteneur> - Nom du conteneur
• service=<nom-service> - Nom du service (ex., smimekeys-client, policy)
• level=<niveau-log> - Extrait des logs JSON si disponible

Interroger les logs dans Grafana:

{environment="stargate-acme"} |= "error"
{environment="stargate-acme", service="mxengine"}
{environment="stargate-acme", level="error"}

Vérifier qu'Alloy fonctionne:

Vérifier l'état d'Alloy et l'activité récenteSonde de santé (depuis le réseau Docker)

docker logs stargate-alloy

docker exec stargate-alloy wget -qO- http://localhost:12345/-/ready

Remarque: L'IP publique de la VM doit être autorisée dans la configuration d'entrée de Loki.

Stalwart MTA + mtaconf

Stargate utilise Stalwart comme agent de transfert de courrier et mtaconf comme démon de configuration. Le tableau de bord envoie la configuration des domaines et du relais à l'API REST de mtaconf, qui la transmet à Stalwart via l'interface de ligne de commande de gestion.

Architecture du flux de courrier

Serveur de courrier externe
         │
         ▼ (port 25)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Port 25 (écouteur smtp)                            │
│    │                                                │
│    ▼                                                │
│  content_filter → smtp:[mxengine]:1587              │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (port 1587)
┌─────────────────────────────────────────────────────┐
│ MXEngine (stargate-mxengine)                        │
│                                                     │
│  Port 1587 (entrée SMTP)                             │
│    │                                                │
│    ▼                                                │
│  Signer/chiffrer/traiter le courrier                │
│    │                                                │
│    ▼                                                │
│  Livrer à stalwart pour relais                      │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (port 10026)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Port 10026 (écouteur de réinjection)               │
│    │                                                │
│    ▼                                                │
│  transport → relais vers le MX de destination       │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (port 25)
Serveur de courrier de destination (via recherche MX)

Analyse antivirus: Les courriels entrants sont analysés par ClamAV (stargate-clamav), intégré à Stalwart comme milter au stade SMTP DATA sur les écouteurs public (:25) et de réinjection (:10026). Les courriels infectés sont rejetés au niveau SMTP ; si ClamAV est inaccessible, le message est différé plutôt que livré non analysé (échec-fermé). La base de données de signatures de ClamAV réside dans le volume clamav_data et est maintenue à jour par freshclam en arrière-plan.

Configuration du relais de courrier

Toute la configuration de courrier qui varie par déploiement (domaines de courrier, nom d'hôte, hôte de relais, cartes de relais par domaine, réseaux autorisés) est définie via la page /mail du tableau de bord à l'exécution. Le tableau de bord envoie la configuration à l'API REST de mtaconf, qui l'applique à Stalwart sans redémarrer le conteneur.

Il n'y a pas de configuration par domaine dans customer-config.sh ou .env - les opérateurs ajoutent ou modifient les domaines via l'interface utilisateur.

Routage du courrier (migration depuis l'ancien MGW)

Différence clé avec l'ancien HIN-MGW

Dans l'ancien MGW, vous deviez configurer manuellement un serveur cible par domaine. Dans Stargate, le routage du courrier est décidé par les enregistrements MX DNS par défaut - Stalwart résout le MX de chaque domaine au moment de la livraison. La page /mail du tableau de bord vous permet de remplacer cela par domaine (ex. pour relayer via votre locataire M365 / Exchange) sans toucher au DNS.

Par défaut - automatique via DNS MX:

Pour chacun de vos domaines, assurez-vous qu'il y a un enregistrement MX dans le DNS pointant vers le serveur Exchange (ou autre serveur de courrier) correspondant:

domain1.com    MX 10  exchange1.domain1.com
domain2.com    MX 10  exchange2.domain2.com
domain3.com    MX 10  exchange3.domain3.com

Cela fonctionne pour n'importe quel nombre de domaines - chaque domaine peut pointer vers un serveur de courrier différent, et Stalwart acheminera en conséquence.

Si Stargate est le seul enregistrement MX pour un domaine, Stalwart le filtrera et n'aura pas de cible de livraison. Ajoutez un deuxième enregistrement MX pointant vers votre serveur de courrier avec une priorité plus élevée (= nombre inférieur) pour que Stalwart l'utilise comme cible de livraison:

example.com    MX 10  exchange.example.com      ← cible de livraison (serveur de courrier)
example.com    MX 20  stargate.example.com      ← passerelle entrante (Stargate)

Alternative - relais explicite par domaine (basé sur l'expéditeur):

Pour le relais de retour via M365 / Exchange Online, configurez les cibles de relais par domaine via la page /mail du tableau de bord. Les courriels des expéditeurs non présents dans la carte reviennent à la recherche MX.

Ports

Port	Objectif
25	Écouteur SMTP principal (connexions externes)
10026	Port de réinjection (mxengine → stalwart, interne uniquement)
1587	Entrée SMTP de MXEngine (stalwart → mxengine, interne uniquement)
8080	API de gestion Stalwart + API REST mtaconf (interne uniquement)

Vous utilisez Exchange ?

Voir Exchange-integration pour la configuration complète des connecteurs et des règles de transport Exchange Online / On-Premises.

Vérification

Vérifier l'état de Stalwart

docker exec stargate-stalwart stalwart-cli -u http://localhost:8080 server list-listeners

Vérifier les logs

docker logs stargate-stalwart

Tester la connexion au port 25

telnet localhost 25

Tester le port interne 10026 (depuis le conteneur mxengine)

docker exec stargate-mxengine nc -zv stalwart 10026

Mise à jour de l'image mtaconf

Comme tout service, la version de l'image mtaconf fait partie d'une version et se met à jour via le tableau de bord - pas en modifiant son tag à la main. Sélectionnez la version cible sur la page de mise à jour du tableau de bord pour l'appliquer.

Dépannage de Stargate

Courrier non traité par mxengine:

• Vérifiez que content_filter est configuré: vérifiez que les logs mtaconf montrent une poussée réussie
• Vérifiez que mxengine est accessible: docker exec stargate-stalwart nc -zv mxengine 1587

Courrier bloqué après le traitement par mxengine:

• Vérifiez la configuration sortante de mxengine: OUTBOUND_SMTP_HOST=stalwart, OUTBOUND_SMTP_PORT=10026
• Vérifiez que l'écouteur du port 10026 est actif dans Stalwart
• Vérifiez que les réseaux de relais autorisés incluent le réseau Docker (172.x.x.x/16)

Erreurs de liste grise (450 4.7.1):

• C'est normal ! Le serveur de destination rejette temporairement le courrier
• Stalwart réessaie automatiquement après un délai configurable
• Vérifiez la file d'attente via l'API de gestion

Microsoft bloque l'IP (S3140):

• L'IP de votre serveur a une mauvaise réputation auprès de Microsoft
• Demandez la suppression de liste sur: https://sender.office.com
• Peut prendre 24 à 48 heures pour prendre effet

Échecs de recherche DNS:

• Utilisez la page /mail du tableau de bord pour définir un hôte de relais explicite ou une carte de relais par domaine (contourne la découverte basée sur MX)

Connexion refusée sur le port 25:

• Assurez-vous que le port 25 n'est pas bloqué par le pare-feu
• Vérifiez si un autre service utilise le port 25: ss -tlnp | grep:25

WireGuard (Communication Agent-à-Agent)

IRISAgent utilise WireGuard pour établir des tunnels cryptés sécurisés entre les instances Stargate pour la livraison de messages scellés.

Comment cela fonctionne

Chaque instance Stargate utilise l'IP publique statique réelle de son serveur comme adresse de tunnel WireGuard. Cela garantit l'unicité entre tous les déploiements sans coordination manuelle.

block
columns 5
  block:Stargate["Votre Stargate (203.0.113.50)"]:2
    columns 1
    A
    space
    A --> B
    A["IRISAgent (203.0.113.50:19818)"]
    B["Livraison de message scellé via tunnel WG"]
  end

  blockArrowId1<["Tunnel WG (TCP)"]>(x):1

  block:mxengine["HIN Test (5.102.144.182)"]:2
    columns 1
    C
    space
    C --> D
    C["IRISAgent (5.102.144.182:19818)"]
    D["Recevoir le message scellé"]
  end

Configuration WireGuard

Paramètres WireGuard dans customer-config.sh:

## ==============================================================================
## IP du serveur — utilisée comme adresse de tunnel WireGuard et URL de rappel MXEngine
## ==============================================================================
SERVER_STATIC_IP="203.0.113.50"       # L'IP publique statique réelle de votre serveur

## ==============================================================================
## Paramètres locaux WireGuard (généralement laissés par défaut)
## ==============================================================================
WG_PRIVATE_KEY=""                     # Auto-généré par IRISAgent, puis sauvegardé dans la configuration
WG_INTERFACE_PORT="19818"             # Port WireGuard par défaut
WG_TRANSPORT_MODE="tcp"               # "tcp" (par défaut) ou "udp"

Info

WG_LOCAL_IP est auto-dérivé de SERVER_STATIC_IP. Vous n'avez pas besoin de le définir séparément.

Configuration de la connexion pair

Les détails du pair WireGuard (clé publique, point de terminaison, IP autorisées, etc.) sont configurés à l'exécution via la page /installation du tableau de bord. Il n'y a plus de bloc WG_PEER_* dans customer-config.sh — le pair est configuré après le démarrage de la pile.

Pour la première configuration avec l'environnement HIN Test:

1. Démarrez la pile avec ./scripts/install.sh.
2. Ouvrez le tableau de bord, suivez /installation pour démarrer la négociation nonce / HIN.
3. Ouvrez les logs IRISAgent (docker compose logs irisagent) et copiez la ligne wireguard public key:. Envoyez-la avec DEPLOYMENT_NAME et SERVER_STATIC_IP à Vereign (kalin.canov@vereign.com) afin qu'ils puissent enregistrer votre pair côté CA.
4. Après la confirmation de l'enregistrement par Vereign, terminez /onboarding dans le tableau de bord pour émettre le certificat S/MIME.

Pour tout pair supplémentaire (pair-à-pair entre deux Stargates), échangez les clés publiques + points de terminaison avec l'autre partie et ajoutez la connexion via l'API IRISAgent:

curl --location 'localhost:8083/v1/connections' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "allowedIps": "<IP du nouveau pair>/32",
  "description": "<courte description>",
  "endpoint": "<IP du nouveau pair>:19818",
  "externalId": [
    "<domaine du nouveau pair>"
  ],
  "name": "<Nom du nouveau pair>",
  "presharedKey": "",
  "publicKey": "<clé publique du nouveau pair>",
  "status": "completed",
  "transport": "tcp",
  "wireguardIp": "<IP du nouveau pair>",
  "wireguardPort": 10080
}'

Vérification WireGuard

Vérifier l'interface WireGuard d'IRISAgent

docker exec stargate-irisagent wg show

Vérifier la connexion dans la base de données

docker exec stargate-postgres psql -U postgres -d irisagent \
  -c "SELECT connection_id, name, endpoint, wireguard_ip, transport, status FROM connections;"

Vérifier les identifiants externes de connexion (utilisés pour le routage)

docker exec stargate-postgres psql -U postgres -d irisagent \
  -c "SELECT connection_id, external_id FROM connection_external_ids;"

Tester la connectivité WireGuard (vérifier l'état du tunnel depuis l'hôte)

docker logs stargate-irisagent 2>&1 | grep -i "handshake\|peer.*added\|started listening"

Vérifier les logs IRISAgent pour l'activité du tunnel

docker logs stargate-irisagent | grep -i wireguard

Dépannage WireGuard

Pas d'interface WireGuard:

• Vérifiez les logs IRISAgent: docker logs stargate-irisagent
• Vérifiez que WG_LOCAL_IP est défini dans .env (auto-dérivé de SERVER_STATIC_IP — devrait être l'IP publique statique de ce serveur)

Pair non accessible:

• Vérifiez que le point de terminaison distant est accessible: nc -zv <hôte_endpoint> <port_endpoint>
• Vérifiez que le pare-feu autorise le port TCP+UDP 19818
• Vérifiez que les clés publiques correspondent aux deux extrémités
• Si TCP pose problème, essayez de définir WG_TRANSPORT_MODE="udp" dans customer-config.sh

Connexion absente de la base de données:

• Réexécutez la page /installation du tableau de bord pour rétablir la connexion pair
• Vérifiez les logs irisagent: docker logs stargate-irisagent

Synchronisation des politiques

Le service policy-sync synchronise automatiquement les politiques OPA/Rego d'un dépôt Git vers la base de données PostgreSQL.

Comment fonctionne Policy Sync

block
columns 8
  A:2 space B:2 space C:2
  A["Dépôt Git

      policies/
        alpha/
        outbound/
        ..."]
    A-->B
    B["policy-sync:

      - Clone/Pull repo
      - Parse .rego files
      - Upsert to database
      - Runs every 1h"]
    B-->C
    C["PostgreSQL

      - policy database
      - policies table"]

Configuration de Policy Sync

Paramètres dans customer-config.sh:

## Dépôt Git contenant les politiques (préconfiguré avec les politiques HIN Stargate)
POLICY_SYNC_REPO_URL="https://github.com/Health-Info-Net-AG/Stargate-policies.git"

## Optionnel: Authentification pour les dépôts privés
POLICY_SYNC_REPO_USER=""
POLICY_SYNC_REPO_PASS=""

## Optionnel: Branche spécifique (par défaut: main)
POLICY_SYNC_REPO_BRANCH=""

## Optionnel: Sous-dossier dans le dépôt contenant les politiques
POLICY_SYNC_REPO_FOLDER=""

## Intervalle de synchronisation (par défaut: 1h)
POLICY_SYNC_INTERVAL="1h"

Vérification de Policy Sync

Vérifier l'état de policy-syncVoir les politiques synchroniséesVoir le contenu d'une politique spécifique

docker logs stargate-policy-sync

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT name, policy_group, filename, to_timestamp(updated_at) as updated FROM policies ORDER BY name;"

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT rego FROM policies WHERE name='deliveryStrategy' AND policy_group='alpha';"

Déclenchement manuel

Pour forcer une synchronisation immédiate:

docker restart stargate-policy-sync

Vault

Montages Vault

Le port API/UI de Vault (8200) n'est pas publié sur l'hôte ; accédez à Vault via l'interface de ligne de commande à l'intérieur du conteneur (voir Opérations manuelles Vault ci-dessous).

Les moteurs de secrets KV-v2 suivants sont créés:

• secret-smimekeys-client
• secret-policy
• secret-irisagent
• secret-mxengine
• secret-mtaconf

Opérations manuelles Vault

Chaque service dispose de son propre jeton dans /var/data/vereign/secrets/service-tokens.env, limité au montage de ce service. Les commandes d'administration, comme la liste des montages, nécessitent le jeton root de vault-keys.json, dans le même répertoire. Les exemples lisent le jeton depuis le fichier : il n'apparaît donc ni dans la ligne de commande ni dans l'historique du shell.

Vérifier l'étatLister les montagesÉcrire un secret

docker exec stargate-vault vault status

VAULT_TOKEN=$(jq -r .root_token /var/data/vereign/secrets/vault-keys.json) \
  docker exec -e VAULT_TOKEN stargate-vault vault secrets list

VAULT_TOKEN=$(sed -n 's/^VAULT_TOKEN_SMIMEKEYS_CLIENT="\(.*\)"$/\1/p' /var/data/vereign/secrets/service-tokens.env) \
  docker exec -e VAULT_TOKEN stargate-vault vault kv put secret-smimekeys-client/test key=valeur

Bases de données

Bases de données PostgreSQL créées:

• smimekeys_client
• policy
• irisagent
• mxengine

Se connecter à PostgreSQL

docker exec -it stargate-postgres psql -U postgres

Ou se connecter externellement

psql -h localhost -U postgres -d smimekeys_client

Politiques (Rego)

MXEngine utilise des politiques OPA/Rego stockées dans PostgreSQL pour déterminer la stratégie de livraison des courriels.

Recommandation: Utilisez policy-sync pour synchroniser automatiquement les politiques d'un dépôt Git. Voir la section Policy Sync.

Voir la politique actuelle

Lister toutes les politiquesVoir le contenu de la politique

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT id, name, policy_group, filename, to_timestamp(updated_at) as updated FROM policies;"

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT rego FROM policies WHERE name='deliveryStrategy';"

Emplacement des politiques

• Configuration MXEngine: POLICY_OUTBOUND: "outbound/delivery"
• Base de données: base de données policy, table policies
• Géré par: service policy-sync (synchronise depuis le dépôt Git)

Logs

Tous les servicesService spécifique

docker compose logs -f

docker compose logs -f <service>

Ex.:

docker compose logs -f smimekeys-client
docker compose logs -f vault

Dépannage

Échec de la délivrance du certificat / Tunnel WireGuard non établi

C'est le problème le plus courant après l'installation initiale. Le certificat S/MIME ne peut pas être émis car le tunnel WireGuard vers l'AC HIN n'est pas établi.

Symptômes:

• La page /onboarding du tableau de bord signale un échec de soumission du CSR
• Les logs smimekeys-client montrent: issue certificate error: certcatunnel: error sending request: irisagent: ... context deadline exceeded

Causes profondes (vérifier dans l'ordre):

1. Pair non enregistré sur l'AC HIN - Votre clé publique WireGuard doit être enregistrée côté HIN. Fournissez à HIN:

# Obtenez votre clé publique WireGuard
docker compose logs irisagent | grep "public key"

Avec votre DEPLOYMENT_NAME, SERVER_STATIC_IP et WG_INTERFACE_PORT (si modifié par rapport à 19818).

1. Pare-feu bloquant le port 19818 - Assurez-vous que 19818/TCP est ouvert à la fois en entrée et en sortie sur le serveur Stargate.

2. Mauvais nom d'hôte - Si le nom d'hôte Stalwart est toujours défini sur la valeur par défaut du modèle (mail.example.com), mettez-le à jour via la page /mail du tableau de bord.

Une fois le problème résolu:

Rouvrez la page /onboarding du tableau de bord pour régénérer le CSR et le soumettre à nouveau via le tunnel maintenant actif.

Voir Étape 5: Enregistrement du pair WireGuard pour le processus complet.

Vault est scellé après redémarrage

Exécutez le script de démarrage qui gère le descellage:

./scripts/start.sh

Impossible de récupérer les images

Connectez-vous au registre:

docker login hub.docker.com

Le service ne démarre pas

Vérifiez les logs:

docker compose logs <nom-service>

Tout réinitialiser

Warning

Ces commandes SUPPRIMENT TOUTES LES DONNÉES - à utiliser avec prudence !

Vous ne pouvez restaurer les données que si vous effectuez des opérations de sauvegarde au préalable et que vous sauvegardez la sauvegarde dans un endroit sûr.

./scripts/purge.sh
./scripts/install.sh

Structure des fichiers

stargate/
├── backups/                      # Sauvegardes complètes (gitignoré)
│   └── *.tar.gz
├── config
│   ├── apisix
│   │   ├── apisix.yaml.template
│   │   ├── config.yaml
│   │   └── generated
│   │       └── apisix.yaml
│   ├── keycloak
│   │   ├── generated
│   │   └── realm-stargate.json
│   ├── nats
│   │   └── nats.conf
│   ├── nginx
│   │   ├── dashboard.conf
│   │   └── keycloak.conf
│   ├── alloy
│   │   └── config.alloy          # Configuration de l'envoi de logs Alloy
│   └── vault
│       └── vault.hcl             # Configuration Vault
├── customer-config-prod.example.sh     # Modèle de configuration (copier vers customer-config.sh)
├── customer-config.sh            # Paramètres spécifiques au client (copiés depuis le modèle)
├── docker-compose.yml            # Fichier compose principal
├── .env                          # Variables d'environnement (générées par install.sh)
├── init
│   └── postgres
│       └── 01-create-databases.sql
├── scripts
│   ├── backup.sh                 # Sauvegarde complète (DB, Vault, config, certificats)
│   ├── gather-app-versions.sh    # Collecte les versions des applications pour les métriques node-exporter
│   ├── health-check.sh           # Contrôle de santé complet de tous les services
│   ├── init-keycloak.sh
│   ├── init-vault.sh             # Initialisation Vault (utilisé par le conteneur vault-init)
│   ├── install.sh                # Première installation (Docker, Vault). La configuration du domaine/certificat/pair se fait ensuite dans le tableau de bord.
│   ├── purge.sh                  # Supprimer toutes les données (destructeur !)
│   ├── restore.sh                # Restaurer à partir d'une archive de sauvegarde
│   ├── send-logs-to-support.sh   # Coller les logs en ligne et obtenir un lien à fournir au support
│   ├── start.sh                  # Démarrer les services + desceller Vault
│   ├── stop.sh                   # Arrêter les conteneurs (préserve les données)
│   └── update.sh
└── secrets/                      # Créé lors de la première exécution (gitignoré)
    ├── vault-keys.json           # Clés de descellage Vault (SAUVEGARDER CECI !)
    └── signing-key.csr           # Demande de signature de certificat S/MIME

Vérifications rapides de santé et de logs

Exécuter le contrôle de santé complet

Contrôle de santé rapideSortie détaillée

./scripts/health-check.sh

./scripts/health-check.sh -v

Avec sortie détaillée (affiche les détails WireGuard, les réponses de liveness).

Cela vérifie:

• Tous les états des conteneurs (en cours d'exécution, sains)
• Points de terminaison Liveness (smimekeys-client, policy, irisagent, mxengine)
• État du sceau Vault
• Connectivité PostgreSQL et les 4 bases de données
• Santé de MinIO
• État du tunnel WireGuard et négociations des pairs
• Stalwart MTA (en cours d'exécution, port 25, port 10026)
• Points de terminaison des métriques Prometheus
• Utilisation du disque et de la mémoire

Pour l'inspection manuelle des logs:

Vérifier les logs (10 dernières lignes)

docker logs stargate-smimekeys-client --tail 10
docker logs stargate-policy --tail 10
docker logs stargate-irisagent --tail 10
docker logs stargate-mxengine --tail 10

Suivre les logs en temps réel

docker logs -f stargate-mxengine

Vérifier tous les états des conteneurs

docker ps -a --format 'table {{.Names}}\t{{.Status}}'

Suivre tous les logs des conteneurs en temps réel

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --timestamps -f {} 2>&1 | sed "s/^/[{}] /"'

Fournir les logs au support

Vous pouvez fournir les logs à notre support via pastebin.hin-infra.ch et la commande CLI:

Télécharger les logs de tous les conteneurs:

TousPour la dernière heure (1h)500 dernières lignes de logs

Utilisez notre script:

./scripts/send-logs-to-support.sh --all

Ou exécutez manuellement:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Tip

Cette opération peut atteindre nos limites de téléchargement - 20 Mo.

Utilisez notre script:

./scripts/send-logs-to-support.sh --since 1h

Ou exécutez manuellement:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --since 1h --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

C'est le défaut

--tail 500 est la valeur par défaut de notre script, mais vous pouvez toujours la fournir.

Utilisez notre script:

./scripts/send-logs-to-support.sh --tail 500

Ou exécutez manuellement:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --tail 500 --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Télécharger les logs de conteneurs spécifiques:

TousPour la dernière heure (1h)500 dernières lignes de logs

docker logs <NOM_CONTENEUR> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

Tip

Cette opération peut atteindre nos limites de téléchargement - 20 Mo. Si cela se produit, essayez de réduire la quantité de logs en définissant une limite de temps ou un nombre de lignes.

docker logs --since 1h <NOM_CONTENEUR> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

docker logs --tail 500 <NOM_CONTENEUR> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

Après cela, vous recevrez un lien unique au format https://pastebin.hin-infra.ch/<20 symboles> que vous pourrez fournir au support / ticket.

Warning

La durée d'expiration est fixée à 30 jours. Si certaines parties des logs ou les logs eux-mêmes doivent être conservés plus longtemps, assurez-vous d'en conserver une copie.

Déploiement Helm

Info

Bientôt disponible

Ce fichier contient les instructions pour le déploiement Helm de l'instance HIN MGW.

Déploiement VM

Déploiement Stargate sur Azure à l'aide d'une image

Déployez Stargate sur Azure

Exigences du port 25 (SMTP) d'Azure

Warning

Avant de commencer l'installation sur Microsoft Azure, examinez les exigences suivantes relatives à la connectivité SMTP sortante sur le port 25. Ignorer cette étape peut entraîner des échecs de livraison des courriels après l'installation.

La disponibilité du port 25 dépend de votre type d'abonnement Azure :

• Contrat Entreprise (EA) ou MCA-E - Le SMTP sortant sur le port 25 n'est pas bloqué. Notez que les domaines externes peuvent toujours rejeter les courriels - cela échappe au contrôle d'Azure.
• Enterprise Dev/Test - Bloqué par défaut, mais peut être débloqué. Pour demander le déblocage, allez dans Diagnostiquer et résoudre > Impossible d'envoyer un courriel (SMTP-Port 25) dans la ressource Réseau virtuel Azure du portail Azure.
• Tous les autres types d'abonnement - Bloqué et ne peut pas être débloqué.

Référence : Résoudre les problèmes de connectivité SMTP sortant dans Azure

Obtenir le fichier image

• Téléchargez le dernier fichier image VHD. Veuillez vous référer au Catalogue des VM

Télécharger le fichier image VHD Azure

• Accédez à https://portal.azure.com/#home
• Cliquez sur Comptes de stockage.
• Sélectionnez le compte de stockage à utiliser ou créez-en un nouveau.
• Cliquez sur Service Bloc puis Conteneurs.
• Sélectionnez le conteneur dans lequel télécharger le fichier ou créez-en un nouveau si vous n'avez pas de conteneur.
• Cliquez sur Télécharger et choisissez le fichier image VHD.
• Assurez-vous que le type de blob est Page Blob.

Créer l'image

• Accédez à https://portal.azure.com/#home
• Cliquez sur Images.
• Cliquez sur Créer.
• Choisissez le groupe de ressources à utiliser ou créez-en un nouveau.
• Saisissez un nom pour l'image.
• Choisissez le type de système d'exploitation Linux et Génération de VM Gen 2
• Dans Stockage blob, cliquez sur parcourir et sélectionnez le fichier image VHD nouvellement téléchargé.
• Cliquez sur Vérifier + créer.
• Cliquez sur Créer.

Créer une VM

• Accédez à https://portal.azure.com/#home
• Cliquez sur Machines virtuelles.
• Cliquez sur Créer, et choisissez Machine virtuelle dans le menu déroulant.
• Choisissez le groupe de ressources.
• Saisissez un nom pour la VM.
• Dans Image, cliquez sur "Voir toutes les images", cliquez sur "Mes images" et choisissez la nouvelle image qui a été créée.
• Choisissez la taille de la VM.
• Choisissez le type d'authentification.
• Cliquez sur Suivant : Disques
• Sélectionnez une taille de disque OS d'au moins 20 GiB. Veuillez vous référer aux Exigences du serveur.
• Cliquez sur Vérifier + créer
• Cliquez sur Créer

Trouver l'adresse IP publique de la nouvelle VM et ajouter des règles de pare-feu entrantes

• Accédez à https://portal.azure.com/#home
• Cliquez sur Machines virtuelles.
• Cliquez sur la nouvelle VM.
• Vous pouvez voir l'adresse IP publique sous "Adresse IP publique de la NIC principale"
• Faites défiler vers le bas jusqu'à Mise en réseau et cliquez dessus
• Cliquez sur + Créer une règle de port, Règle de port entrant, Plages de ports de destination 25, Protocole TCP, nommez-la SMTP. Répétez pour l'autre port entrant requis — 19818 (WireGuard). Voir Exigences du serveur → Accès réseau entrant pour la liste complète.

Attachez d'abord le disque de données

Avant le premier démarrage, attachez un second disque vierge d'au moins 30 Go. Au premier démarrage, l'appliance le formate comme disque de données (VEREIGN-DATA, monté sur /var/data) et y conserve toute la configuration et les données ; sans lui, le démarrage échoue et effectue un rollback. Voir Guide d'installation → Étape 4.

Installer HIN Gateway

Après la création réussie de la VM, procédez aux étapes d'installation et d'intégration comme décrit dans les instructions fournies.

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance Stargate, veuillez contacter le support HIN.

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.

Déploiement Stargate sur VMware ESXi à l'aide d'une image

Déployez Stargate sur VMware

Obtenir le fichier image

• Téléchargez le dernier fichier image OVA (ou OVF et VMDK si vous préférez). Veuillez vous référer au Catalogue des VM

Accéder à l'interface Web d'ESXi

• Cliquez sur Machines virtuelles
• Cliquez sur Créer/Enregistrer une VM
• Choisissez "Déployer une machine virtuelle à partir d'un fichier OVF ou OVA"
• Cliquez sur Suivant
• Saisissez un nom pour la VM
• Cliquez sur Suivant
• Cliquez pour sélectionner les fichiers et choisissez le fichier image OVA (ou OVF et VMDK si vous préférez)
• Cliquez sur Suivant
• Choisissez un stockage à utiliser
• Cliquez sur Suivant
• Choisissez le réseau et le disque pour le provisionnement
• Cliquez sur Suivant
• Cliquez sur Terminer

Disque de données inclus

L'OVA contient déjà le disque de données de l'appliance (VEREIGN-DATA, monté sur /var/data) — aucun disque supplémentaire à attacher. Voir Guide d'installation → Étape 4.

Installer HIN Gateway

Après la création réussie de la VM, procédez aux étapes d'installation et d'intégration comme décrit dans les instructions fournies.

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance Stargate, veuillez contacter le support HIN.

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.

Déploiement Proxmox à l'aide d'une image

Déployez Stargate sur Proxmox

Obtenir l'URL du fichier image

• Veuillez vous référer au Catalogue des VM pour une liste des images avec leurs URL.
• Copiez l'URL dans votre presse-papiers, par exemple https://images.hin.ch/vm-images/hingateway_v0.0.0.x86_64.qcow2

Importer le fichier image dans Proxmox

• Dans l'interface Web de Proxmox, naviguez jusqu'au menu Stockage et cliquez sur Importer
• Cliquez sur Télécharger depuis URL, collez l'URL copiée et cliquez sur "Interroger l'URL".
• Cliquez sur Télécharger et attendez que "TASK OK" apparaisse à la fin du journal de sortie.
• Fermez la fenêtre de téléchargement du Visualiseur de tâches.

Créer une VM

• Cliquez sur "Créer une VM"
• Saisissez un nom pour la VM
• Cliquez sur "Suivant"
• Choisissez "Ne pas utiliser de support"
• Cliquez sur "Suivant"
• Cliquez sur "Suivant"
• Cliquez sur "l'icône Corbeille" à côté de "scsi0" pour le supprimer.
• Cliquez sur "Importer" et sous "Sélectionner une image", choisissez le fichier image nouvellement importé.
• Cliquez sur "Suivant"
• Sélectionnez 4 cœurs CPU et choisissez votre type de CPU (ou utilisez "host"). Veuillez vous référer aux Exigences du serveur.
• Cliquez sur "Suivant"
• Sélectionnez 8192 MiB de mémoire. Veuillez vous référer aux Exigences du serveur.
• Cliquez sur "Suivant"
• Cliquez sur "Suivant"
• Attendez que le processus de création de la VM se termine, puis cliquez sur la nouvelle VM, cliquez sur "Console", cliquez sur "Démarrer maintenant"

Attachez d'abord le disque de données

Avant le premier démarrage, attachez un second disque vierge d'au moins 30 Go. Au premier démarrage, l'appliance le formate comme disque de données (VEREIGN-DATA, monté sur /var/data) et y conserve toute la configuration et les données ; sans lui, le démarrage échoue et effectue un rollback. Voir Guide d'installation → Étape 4.

Installer HIN Gateway

Après la création réussie de la VM, procédez aux étapes d'installation et d'intégration comme décrit dans les instructions fournies.

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance Stargate, veuillez contacter le support HIN.

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.

Déploiement Windows 11 Pro à l'aide d'une image

Déployez Stargate sur Windows Pro (les versions non-Pro ne prennent pas en charge Hyper-V)

Installer Hyper-V

• Cliquez sur le bouton Démarrer, puis tapez "Activer ou désactiver des fonctionnalités Windows"
• Cliquez sur ce bouton
• Cochez Hyper-V et cliquez sur "OK"
• Une fois l'installation terminée, cliquez sur "Redémarrer maintenant" et attendez que Windows redémarre

Remarque : Nous recommandons de déployer la VM en utilisant Hyper-V Génération 2

Obtenir l'image

• Téléchargez le fichier image .vhdx. Veuillez vous référer au Catalogue des VM

Importer le fichier image et créer une VM avec

• Cliquez sur le bouton "Démarrer" et tapez "Création rapide Hyper-V"
• Cliquez sur cette icône
• Choisissez "Source d'installation locale"
• Décochez "Cette machine exécutera Windows"
• Cliquez sur "Modifier la source d'installation", accédez à l'image .VHDX téléchargée et cliquez dessus
• Cliquez sur "Créer une machine virtuelle"
• Cliquez sur "Modifier les paramètres"
• Sous "Mémoire", choisissez "RAM" 8192 Mo. Veuillez vous référer aux Exigences du serveur.
• Sous "Processeur", choisissez "Nombre de processeurs virtuels" 4. Veuillez vous référer aux Exigences du serveur.
• Cliquez sur "OK"
• Cliquez sur "Connecter"
• Cliquez sur "Démarrer"

Attachez d'abord le disque de données

Avant le premier démarrage, attachez un second disque vierge d'au moins 30 Go. Au premier démarrage, l'appliance le formate comme disque de données (VEREIGN-DATA, monté sur /var/data) et y conserve toute la configuration et les données ; sans lui, le démarrage échoue et effectue un rollback. Voir Guide d'installation → Étape 4.

Installer HIN Gateway

Après la création réussie de la VM, procédez aux étapes d'installation et d'intégration comme décrit dans les instructions fournies.

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance Stargate, veuillez contacter le support HIN.

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.

Déploiement Stargate sur Cloudscale à l'aide d'une image

Obtenir l'URL du fichier image

• Référez-vous au Catalogue des VM pour les images disponibles avec leurs URL.
• Copiez l'URL qcow2 dans votre presse-papiers.

Importer le fichier image dans Cloudscale

• Dans l'interface Web de Cloudscale, naviguez jusqu'au menu "Images personnalisées" et cliquez sur "Importer une image personnalisée".
• Définissez un Nom d'image approprié.
• Définissez un Slug, par exemple "stargate".
• Collez l'URL de l'image Stargate dans le champ URL de téléchargement.
• Définissez Format source sur le format de téléchargement, recommandé : qcow2.
• Configurez les paramètres supplémentaires si nécessaire.
• Cliquez sur Importer.

Créer une VM

• Naviguez vers Serveurs et cliquez sur Lancer un nouveau serveur.
• Entrez votre FQDN ou nom d'hôte préféré.
• Sous Système d'exploitation, sélectionnez Images personnalisées et choisissez votre image importée.
• Sous Flavor de calcul, sélectionnez Flex-4-2 ou Flex-8-2 en fonction de la charge prévue (peut être ajusté ultérieurement). Voir Exigences du serveur pour plus de détails.
• Sous Capacité de stockage, définissez au moins 30 Go. Veuillez vous référer aux Exigences du serveur.
• Sous Emplacement du serveur, sélectionnez votre zone préférée.
• Sous Gestion du réseau, activez uniquement IPv4 si l'instance Stargate doit être accessible sur Internet (par exemple, pour Office 365).
• Sous Sécurité d'accès, sélectionnez votre clé SSH (utilisable avec l'utilisateur almalinux).
• Sous Mot de passe, définissez un mot de passe sécurisé de votre choix.

Sans mot de passe, l'authentification SSH par mot de passe est désactivée

Vous devez tout de même utiliser le mot de passe initial fourni par HIN lors de votre première connexion. Toutefois, si vous ne définissez pas de nouveau mot de passe, cloud-init désactivera l'authentification SSH par mot de passe pour tous les utilisateurs, de sorte que l'accès SSH ne sera possible qu'à l'aide d'une clé publique.

• Cliquez sur Lancer.

Attachez d'abord le disque de données

Avant le premier démarrage, attachez un second disque vierge d'au moins 30 Go. Au premier démarrage, l'appliance le formate comme disque de données (VEREIGN-DATA, monté sur /var/data) et y conserve toute la configuration et les données ; sans lui, le démarrage échoue et effectue un rollback. Voir Guide d'installation → Étape 4.

Installer HIN Gateway

Après la création réussie de la VM, procédez aux étapes d'installation et d'intégration comme décrit dans les instructions fournies.

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance Stargate, veuillez contacter le support HIN.

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.

Catalogue des images VM

Vous trouverez ici un catalogue VM actuel pour différentes plateformes. N'oubliez pas de vérifier le hachage SHA-256 des images téléchargées. Vous pouvez utiliser le fichier https://images.hin.ch/vm-images/SHA256SUMS pour le comparer.

Comment effectuer une vérification du hachage SHA256 localement

Vous pouvez calculer le hachage SHA256 des fichiers téléchargés avec la commande suivante, puis le comparer avec les valeurs du tableau ci-dessous.

Linux et macOSWindows

Ouvrez le Terminal et exécutez :

sha256sum <Nom du fichier>

Comme variante plus avancée, vous pouvez exécuter la commande suivante et coller la somme de contrôle prédéfinie comme SHA256_VALUE et le nom du fichier comme IMAGE_NAME :

SHA256_VALUE="" \
IMAGE_NAME="" \
echo "$SHA256_VALUE  $IMAGE_NAME" | sudo sha256sum --check --status

Ouvrez PowerShell et exécutez :

Get-FileHash "<Nom du fichier>"

Vous pouvez ajouter l'argument -Algorithm SHA256 pour forcer l'utilisation de SHA256.

Nom de l'image	Type d'image	Taille de l'image	Lien	Somme de contrôle SHA256
hingateway-v1.1.7.x86_64.mf		4.0K / 364 bytes	Download	caafd4817e8c6c397f24d3ef284b774c9282a3300e77ea33727180203a813bf3
hingateway-v1.1.7.x86_64.ova		3.3G / 3496058880 bytes	Download	6617a8fc37aba7571bad277c3d14f53885154114c08b34809102e78864188965
hingateway-v1.1.7.x86_64.ovf		12K / 9322 bytes	Download	47b1297b724ecdf575ce350175c2513d25e8daa3aa79f34f4962e43eb97f9d50
hingateway-v1.1.7.x86_64.qcow2		3.3G / 3526492160 bytes	Download	f4d4b9c2994b8e674e6f649a249fe3d6e0345593e0e02f588472c199ce67582d
hingateway-v1.1.7.x86_64.raw		30G / 32212254720 bytes	Download	583763ab21804cf312b4bffa8c25c1c1b05990be5b76f0044d9804b2c5eeec2e
hingateway-v1.1.7.x86_64.raw.gz		3.3G / 3475192756 bytes	Download	f5c37aaa231dd7951f30d13cec7a783e55adaffe4b2db2853cc98a12c381d571
hingateway-v1.1.7.x86_64.vhd		31G / 32212255232 bytes	Download	100c2f3528665ad91ba2a2915634032472c8a0292e519d923dc2a6107beebeb9
hingateway-v1.1.7.x86_64.vhd.gz		3.3G / 3475192835 bytes	Download	2aa3bc86d7c2b8b3a02d1dc462096e372abdf73452301decfd2ce44501db3ca4
hingateway-v1.1.7.x86_64.vhdx		4.7G / 5007998976 bytes	Download	71a8f84014d1ecc34c3843b5b45ec2dd67f11fafbf0eb9f83164d56bb8da098a
hingateway-v1.1.7.x86_64.vmdk		3.3G / 3491979776 bytes	Download	4a5a0fd6950cac3ed539fe2834d3b84742db01462a8f93764965932cb273237e
SHA256SUMS		4.0K / 979 bytes	Download	f0fa4b8957cc007f4a91ecd0fa02d641f79e8285b74d4884d626be9c5b2fa611

Dépannage et diagnostic

Guide structuré pour diagnostiquer une appliance Stargate depuis la ligne de commande : ce qu’il faut vérifier, où se trouvent les journaux et quelles actions de récupération sont sans risque.

Où se trouvent les scripts

Les scripts utilitaires se trouvent dans le répertoire de déploiement, sous scripts/. Les commandes ci-dessous utilisent le chemin complet des images de VM : /usr/share/stargate-deployment/docker-compose/scripts/. Si vous avez effectué l’installation ailleurs, remplacez-le par votre propre répertoire d’installation (le dossier qui contient docker-compose.yml et scripts/).

Les commandes docker compose ... doivent être exécutées depuis le répertoire de déploiement :

cd /usr/share/stargate-deployment/docker-compose   # adjust to your install path

Où se trouvent les données modifiables

L’arborescence docker-compose/ ci-dessus (scripts, docker-compose.yml, modèles de configuration) est en lecture seule à l’exécution. Toutes les données modifiables se trouvent à la place sous /var/data : .env, customer-config.sh, secrets/, la configuration TLS, Keycloak et APISIX générée, les sauvegardes ainsi que les données propres à chaque service (STARGATE_DATA_DIR remplace cette racine à des fins de test). En particulier : la configuration et les secrets se trouvent sous /var/data/vereign/ et les sauvegardes sous /var/data/backups/. Pour la description complète, voir Configuration avancée Docker. Utilisez de préférence les scripts d’encapsulation (./scripts/start.sh, ./scripts/stop.sh, ...) plutôt qu’un simple docker compose up -d, qui ne prend pas en compte /var/data/vereign/.env de lui-même.

---

1. Commencez ici : le contrôle d’état

Une seule commande donne une vue d’ensemble de l’appliance :

RapideDétaillé

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v

Elle indique un résultat réussi ou en échec pour : les conteneurs (en cours d’exécution / en bon état), les points de terminaison de disponibilité (liveness : smimekeys, policy, irisagent, mxengine), l’état de scellement de Vault, la connectivité PostgreSQL et les bases de données, SeaweedFS, le tunnel WireGuard et les handshakes avec les pairs, le MTA Stalwart (ports 25 / 10026), les points de terminaison des métriques Prometheus, ainsi que le disque et la mémoire.

Tip

Exécutez d’abord cette commande. Une seule ligne FAIL vous oriente généralement directement vers la section concernée ci-dessous.

---

2. Où trouver les journaux

Niveau	Commande	Ce qui est affiché
Démarrage / première installation / démarrage automatique	sudo journalctl -u stargate -n 200 --no-pager	Le service systemd qui exécute start.sh au démarrage, ainsi que l’installation au premier démarrage
Mises à jour (appliance VM)	hingateway-status, docker logs stargate-ops-agent --tail 100 et journalctl -u greenboot-healthcheck	Versions système démarrée, préparée et de retour arrière ; sauvegarde, téléchargement et erreurs d’une mise à jour (uniquement jusqu’au prochain redémarrage) ; résultat du contrôle de santé au démarrage
Exécutions de update.sh	cat /var/data/vereign/update.log	Sortie de toutes les exécutions de update.sh, la plus récente à la fin : mises à jour des installations Compose simples, mises à jour depuis le tableau de bord sur les anciennes VM avant bootc et exécutions après une modification de customer-config.sh
Un seul service	docker logs stargate-<service> --tail 100	p. ex. stargate-dashboard, stargate-mxengine, stargate-keycloak
Suivre un service en direct	docker logs -f stargate-mxengine	Temps réel
Tous les conteneurs en direct	docker ps -a --format '{{.Names}}' \| xargs -I{} sh -c 'docker logs --timestamps -f {} 2>&1 \| sed "s/^/[{}] /"'	Journaux fusionnés, préfixés par le nom du conteneur
Visualiseur de journaux web	Dozzle à l’adresse https://<SERVER_IP>:8190 (connexion Keycloak)	Parcourir les journaux de tous les conteneurs dans une interface web

Pour transmettre les journaux au support HIN, utilisez le script d’envoi : il collecte les N dernières lignes de journal de chaque service (avec les informations sur l’hôte et les versions), les téléverse et affiche un lien à communiquer. Voir Fournir les journaux au support :

/usr/share/stargate-deployment/docker-compose/scripts/send-logs-to-support.sh --tail 5000     # last 5000 lines from each service
# other options:  --since 1h   |   --until 5m   |   --all   (no argument = --tail 500)

L’envoi est limité à 20 MB ; sur une appliance très sollicitée, préférez donc --tail/--since à --all.

---

3. Conteneurs arrêtés ou qui redémarrent en boucle

docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'

Consultez la colonne Status :

Statut	Signification	Action
Up ... (healthy)	Fonctionne normalement	-
Up ... (sans état de santé)	En cours d’exécution ; aucun contrôle d’état défini	Consultez ses docker logs si vous soupçonnez un problème
Restarting	Redémarrages en boucle	docker logs stargate-<svc> : corrigez l’erreur d’origine (configuration, secret, dépendance)
Exited (0)	Initialisation ponctuelle terminée avec succès (p. ex. *-init, vault-data-fixer)	Normal
Exited (1+)	Échec	docker logs stargate-<svc> : les dernières lignes en indiquent la cause
Created	Jamais démarré, car une dépendance n’a pas démarré	Vérifiez de quoi il dépend (depends_on, généralement Postgres/Vault) et corrigez d’abord ce point

Redémarrer un seul service (opération sûre et non destructive) :

docker compose up -d <service>          # recreate one service
docker compose restart <service>        # just restart it

Ordre de démarrage

Les services attendent leurs dépendances (depends_on + contrôles d’état). Lors d’un redémarrage complet, de brèves lignes connection refused / database system is starting up pendant le démarrage de Postgres et de Vault sont normales et disparaissent en moins d’une minute.

---

4. Diagnostic par symptôme

Le tableau de bord ou Keycloak ne se charge pas / connexion impossible

• Tous deux sont placés derrière Caddy : le tableau de bord sur :443, Keycloak sur :8180.
• Vérifiez toute la chaîne : docker logs stargate-caddy, stargate-dashboard, stargate-keycloak, stargate-apisix.
• Keycloak doit être en bon état (healthy) pour que le tableau de bord fonctionne : docker compose ps keycloak.
• Un avertissement TLS dans le navigateur est normal (certificat auto-signé) : acceptez-le et continuez.
• L’échec des redirections de connexion signifie généralement que l’URL publique ne correspond pas à l’adresse par laquelle vous accédez à la machine. Vérifiez que KEYCLOAK_PUBLIC_URL / DASHBOARD_PUBLIC_URL dans .env pointent vers l’adresse IP ou le nom d’hôte que vous utilisez réellement.

Tunnel WireGuard indisponible / échec de l’émission des certificats

C’est le problème le plus fréquent : l’émission des certificats échoue lorsque le tunnel est indisponible. Rétablissez donc toujours le tunnel en premier.

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v      # shows WireGuard peer + handshake status
docker logs stargate-irisagent | grep -iE "handshake|peer|cert|wireguard"

• Vérifiez que le pare-feu autorise 19818 (UDP et TCP) en entrée et en sortie.
• Vérifiez que le pair est enregistré côté HIN (étape réalisée par le support). Vous fournissez pour cela la clé publique WG, DEPLOYMENT_NAME, SERVER_STATIC_IP et WG_INTERFACE_PORT.
• Dès que le tunnel affiche un handshake récent, relancez l’émission des certificats depuis le tableau de bord.

Vault scellé ou échec de l’initialisation

docker compose exec vault vault status        # look for "Sealed: false"
docker logs stargate-vault-init

• Vault doit être descellé pour que smimekeys, mxengine et policy fonctionnent. Les clés se trouvent dans /var/data/vereign/secrets/vault-keys.json.
• Si vault-init s’est terminé avec un code différent de zéro, le fichier de clés est peut-être absent ou corrompu. Consultez ses journaux ; une nouvelle exécution de /usr/share/stargate-deployment/docker-compose/scripts/init-vault.sh tente à nouveau le descellement.

Ne supprimez pas /var/data/vereign/secrets/vault-keys.json

Perdre ce fichier, c’est perdre l’accès à tous les secrets enregistrés. Conservez-en une sauvegarde.

Connectivité PostgreSQL / base de données

docker compose exec postgres pg_isready -U postgres
docker logs stargate-postgres --tail 50

• Un message temporaire the database system is starting up (57P03) juste après un redémarrage est normal : les services se reconnectent automatiquement.
• Des échecs d’authentification persistants signifient généralement que la valeur POSTGRES_PASSWORD dans .env ne correspond plus au volume de données. Consultez les remarques sur les mises à jour et les secrets, et évitez de modifier cette valeur à la main.

Les e-mails ne circulent pas

• Les e-mails entrants arrivent sur :25 (Stalwart). De nombreux fournisseurs cloud bloquent le port 25 par défaut :

  nc -zv <this-server-ip> 25          # from an external host
  docker logs stargate-stalwart --tail 100
  

  Si le port 25 est bloqué, demandez une dérogation à votre fournisseur. - Les e-mails sortants et le scellement passent par Stalwart → mxengine (:8084 HTTP, SMTP :1587) : docker logs stargate-mxengine. - Les boucles de messagerie se manifestent par un même message qui circule en boucle. Vérifiez que l’enregistrement MX de votre domaine ne renvoie pas vers l’adresse IP de cette appliance elle-même. - Le routage attendu est décrit dans Configuration du relais de messagerie et Configuration DNS.

Échec d’une mise à jour

Sur l’appliance VM, une mise à jour lancée depuis le tableau de bord est exécutée par l’ops-agent en trois phases : une sauvegarde (backup.sh), le téléchargement de l’image système cible (bootc switch) et le redémarrage sur cette image. Commencez par :

docker logs stargate-ops-agent --tail 100     # the update orchestrator: backup, download, errors
hingateway-status                             # booted, staged and rollback OS versions

Le conteneur de l’ops-agent est recréé à chaque démarrage ; son journal ne couvre donc une mise à jour que jusqu’au redémarrage de la VM. Après un redémarrage, utilisez plutôt hingateway-status et journalctl -u greenboot-healthcheck.

• Échec pendant la sauvegarde. L’ops-agent annule la mise à jour lorsque la sauvegarde préalable échoue ; rien n’a donc été modifié. Vérifiez l’erreur dans le journal de l’ops-agent et l’espace libre sur le Data Disk (df -h /var/data), puis relancez la mise à jour.
• Échec pendant le téléchargement. L’état de la mise à jour dans le tableau de bord affiche l’erreur sous la forme bootc switch: ... ; le journal de l’ops-agent n’enregistre que os select failed avec le code de sortie. En général, la VM ne peut pas joindre le registre d’images (vérifiez l’accès Internet sortant et le DNS) ou le disque système est plein (df -h /sysroot). La version en cours d’exécution n’est pas affectée ; relancez la mise à jour une fois la cause corrigée.
• Téléchargée, mais la version n’a pas changé. La nouvelle version n’est activée que par un redémarrage. Si vous avez choisi Later, redémarrez la VM (sudo systemctl reboot) et vérifiez à nouveau hingateway-status. Si la VM a bien redémarré et affiche toujours l’ancienne version comme démarrée, elle est revenue automatiquement en arrière - voir le point suivant.
• Retour arrière automatique après un démarrage en échec. Après le démarrage d’une nouvelle version, des contrôles de santé s’exécutent - entre autres, si Docker fonctionne, si le Data Disk est monté et si la pile Stargate est en bon état, ainsi que les contrôles par défaut du système d’exploitation. Si un contrôle obligatoire échoue, le démarrage est marqué RED et la VM redémarre d’elle-même sur la version précédente. journalctl -u greenboot-healthcheck indique quel contrôle a échoué. Corrigez la cause avant de relancer la mise à jour ; un simple redémarrage répète le même retour arrière. Si la nouvelle version avait déjà modifié un schéma de base de données, ou si la mise à jour en échec était la première mise à niveau vers une image prenant en charge le Data Disk (la pile affiche alors un /var/data vide, mais vos données sont intactes), lisez les avertissements sur le retour arrière avant toute autre action.
• La nouvelle version démarre mais ne fonctionne pas correctement. Vérifiez le contrôle de santé au démarrage avec journalctl -u greenboot-healthcheck et la pile avec /usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v. Pour revenir à la version précédente, utilisez Roll back dans le tableau de bord ou exécutez hingateway-rollback && sudo systemctl reboot - lisez d’abord les avertissements sur le retour arrière.
• Après une mise à jour réussie, vérifiez que les versions ont été appliquées : /usr/share/stargate-deployment/docker-compose/scripts/gather-app-versions.sh (ou les tags d’image dans docker compose ps).
• Si un service reste bloqué après une mise à jour, recréez uniquement ce service : cd /usr/share/stargate-deployment/docker-compose && sudo docker compose --env-file /var/data/vereign/.env up -d --no-deps --force-recreate <service>. sudo est nécessaire car seul root peut lire .env, et --no-deps empêche Compose de recréer aussi les dépendances du service, comme Vault, qui redémarrerait scellé. Si /var/data/vereign/docker-compose.override.yml (ou .yaml) existe, ajoutez -f docker-compose.yml -f <fichier override> après --env-file /var/data/vereign/.env pour que l’override reste appliqué. Les services qui appartiennent à un profil en ont également besoin : ajoutez --profile dozzle pour dozzle et oauth2-proxy, --profile keri-idagent pour idagent et --profile keri-watcher pour watcher.

Sur une installation Compose simple (un git clone que vous gérez vous-même), il n’y a pas de mise à jour via l’ops-agent : vous exécutez update.sh vous-même, et sa sortie est ajoutée à /var/data/vereign/update.log, l’exécution la plus récente se trouvant à la fin. Les étapes de mise à jour sont décrites dans Installation Compose simple.

Warning

N’essayez pas de réparer une mise à jour sur l’appliance VM avec git ou update.sh --release. /usr/share/stargate-deployment fait partie de l’image système en lecture seule et il n’existe aucune copie du dépôt à réinitialiser ; les versions ne changent qu’en basculant d’image système.

VM plus anciennes (avant l’image bootc)

Les VM installées à partir d’une image antérieure à l’appliance bootc ont une copie git sous /usr/share/stargate-deployment au lieu d’une image système en lecture seule. Les étapes ci-dessus pour l’appliance VM ne s’appliquent pas à elles. À terme, migrez-les vers une appliance bootc comme décrit dans le guide en anglais « Migrating a Compose Deployment to a bootc Appliance ». En attendant, ce qui suit s’applique uniquement à ces anciennes VM. Sur celles-ci, l’ops-agent exécute update.sh, dont la sortie est ajoutée à /var/data/vereign/update.log (l’exécution la plus récente à la fin) - consultez ce fichier en premier lorsqu’une mise à jour échoue.

La mise à jour démarre, mais rien ne se passe (mise à jour depuis une version antérieure). Si le journal de l’ops-agent s’arrête à pulling deployment repo ... et que la mise à jour n’avance plus, le dépôt sur la VM contient très probablement des modifications locales sur un fichier suivi (le plus souvent un docker-compose.yml modifié à la main). Le git checkout de l’ops-agent refuse alors de s’exécuter et la mise à jour reste bloquée. Réinitialisez de force le dépôt sur la dernière révision, puis relancez la mise à jour. Git est la source unique de vérité ; cette opération n’annule que les modifications locales apportées aux fichiers suivis. customer-config.sh, .env et secrets/ se trouvent sous /var/data/vereign/, en dehors de la copie du dépôt, et sont toujours préservés :

cd /usr/share/stargate-deployment
sudo git fetch origin
sudo git checkout -f main
sudo git reset --hard origin/main
cd docker-compose
sudo /usr/share/stargate-deployment/docker-compose/scripts/update.sh

update.sh régénère .env, télécharge les images et recrée les services concernés. Si la version a modifié des fichiers de configuration, exécutez ensuite sudo /usr/share/stargate-deployment/docker-compose/scripts/start.sh pour que tous les conteneurs prennent en compte les nouveaux fichiers. Une fois l’opération terminée, relancez la mise à jour depuis le tableau de bord ; elle se déroulera alors normalement.

Warning

N’utilisez pas git pull ici. Sur une copie de travail comportant des modifications locales, cette commande s’interrompt avec le message « local changes would be overwritten », ce qui oblige à passer par un git stash, un conflit de fusion ou une récupération manuelle. La séquence git checkout -f + git reset --hard ci-dessus évite entièrement ce détour : c’est la méthode sûre et reproductible pour mettre le dépôt à jour.

VM en v0.5.1

Les étapes suivantes mettent à jour une VM de la version v0.5.1 vers la version v0.5.3. En v0.5.x, .env, customer-config.sh et secrets/ se trouvent dans la copie, sous /usr/share/stargate-deployment/docker-compose/, et non sous /var/data/vereign/. Connectez-vous à la VM avec le compte administrateur Linux.

1. Modifiez /usr/share/stargate-deployment/docker-compose/.env et définissez la version de l’ops-agent sur v0.0.3.
2. Modifiez /usr/share/stargate-deployment/docker-compose/customer-config.sh et définissez-y également la version de l’ops-agent sur v0.0.3.
3. Récupérez les tags de version : cd /usr/share/stargate-deployment && sudo git fetch --tags origin
4. Extrayez la version cible : sudo git checkout v0.5.3. N’extrayez pas main : cette branche contient les scripts actuels, qui attendent la nouvelle organisation sous /var/data.
5. Mettez à jour le conteneur ops-agent : cd docker-compose && sudo docker compose up -d ops-agent
6. Connectez-vous au tableau de bord.
7. Ouvrez Settings.
8. Dans la section Update, en bas de la page, saisissez la version cible (v0.5.3) et lancez la mise à jour.

Migrez ensuite la VM vers une appliance bootc comme décrit dans le guide en anglais « Migrating a Compose Deployment to a bootc Appliance ».

Dozzle (visualiseur de journaux) inaccessible

• L’URL est https://<SERVER_IP>:8190 ; elle exige une connexion Keycloak (même realm que le tableau de bord) via oauth2-proxy.
• Dozzle ne s’exécute que si DOZZLE_ENABLED="true". Vérification : docker compose ps dozzle oauth2-proxy.
• Assurez-vous que le pare-feu autorise :8190 en entrée. Voir Surveillance et journaux.

Intégration : la saisie du code d’activation renvoie une erreur

Si le code d’activation est refusé, vérifiez dans l’ordre :

• Code erroné : il n’a pas été copié en entier (copier-coller tronqué, espace en trop ou caractère manquant). Copiez à nouveau le code complet et saisissez-le une nouvelle fois.
• Code déjà utilisé : il a déjà été consommé lors d’une intégration précédente. Demandez un nouveau code.
• WireGuard / connectivité vers HIN : le tunnel irisagent n’est pas établi, le code ne peut donc pas être validé auprès de HIN. Voir Tunnel WireGuard indisponible ci-dessus (/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v, docker logs stargate-irisagent).
• Aucun domaine associé à l’enregistrement : aucun domaine n’est associé à l’enregistrement HIN du client, il n’y a donc rien à activer. Ce point se règle du côté de HIN.

Intégration : code d’activation accepté, mais aucun domaine n’est affiché

Cause la plus probable : le tunnel WireGuard n’est pas établi, généralement à cause d’une adresse IP publique erronée ou d’un port non ouvert dans le pare-feu. Sans le tunnel, l’appliance ne peut pas récupérer la liste des domaines auprès de HIN.

• Vérifiez que SERVER_STATIC_IP dans customer-config.sh correspond à l’adresse IP publique réelle.
• Vérifiez que 19818 (UDP et TCP) est ouvert en entrée et en sortie.
• Vérifiez que le pair est enregistré côté HIN pour cette adresse IP (étape réalisée par le support).
• docker logs stargate-irisagent doit afficher un handshake récent ; sinon, rétablissez d’abord le tunnel (voir Tunnel WireGuard indisponible ci-dessus).

Modifier l’adresse IP du serveur (configuration initiale uniquement)

Si l’adresse IP du serveur était erronée ou non définie au premier démarrage, réinitialisez proprement puis réinstallez. Sauvegardez d’abord la configuration, car purge.sh supprime aussi customer-config.sh :

/usr/share/stargate-deployment/docker-compose/scripts/backup.sh --config-only  # saves customer-config.sh
/usr/share/stargate-deployment/docker-compose/scripts/purge.sh                 # destroys ALL data - see warning below
/usr/share/stargate-deployment/docker-compose/scripts/restore.sh --config-only /var/data/backups/<timestamp>_config-only.tar.gz
nano /var/data/vereign/customer-config.sh    # set SERVER_STATIC_IP=<NEW IP>
reboot                                       # installs again with the new IP

backup.sh affiche la commande de restauration exacte, et l’archive reste dans /var/data/backups, que purge.sh ne supprime pas. Le redémarrage lance l’installation et recharge aussi les images construites localement que purge.sh supprime. Sur une installation Docker classique, exécutez install.sh au lieu de redémarrer.

Le certificat TLS et plusieurs URL de services sont dérivés de l’adresse IP au premier démarrage ; une purge suivie d’une réinstallation les régénère donc pour la nouvelle adresse. Le fichier restauré conserve les mots de passe générés et la clé WireGuard. Si la passerelle est déjà enregistrée auprès de HIN, l’enregistrement doit être mis à jour avec la nouvelle adresse IP.

Uniquement avant l’intégration

purge.sh supprime définitivement toutes les données : bases de données, Vault et clés S/MIME. Cette opération n’est sûre que sur une appliance neuve, pas encore intégrée. N’exécutez jamais purge.sh pour changer l’adresse IP d’une passerelle en production ou déjà intégrée : cela entraîne une perte de données et des e-mails qui ne peuvent plus être déchiffrés. Pour un changement d’adresse IP en production, contactez le support.

---

5. Stockage et disque

df -h /                              # is the disk full?
docker system df                     # space used by images / containers / volumes
du -sh /var/lib/docker/volumes/*     # per-volume usage (Postgres, SeaweedFS, Loki, ...)

• Les journaux des conteneurs sont plafonnés (json-file, 100 MB × 5 par conteneur) et ne devraient donc pas remplir le disque, contrairement aux images et aux volumes.
• Pour libérer de l’espace sans risque : docker image prune -af (supprime uniquement les images inutilisées). Évitez docker system prune --volumes, qui supprime les volumes de données.
• Le stockage objet est assuré par SeaweedFS (stargate-seaweedfs) : docker logs stargate-seaweedfs --tail 50.

---

6. Ressources de la VM

free -h                              # memory (min 8 GB)
nproc                                # CPUs (min 4)
docker stats --no-stream             # per-container CPU/RAM
uptime                               # load average

Les métriques de l’hôte sont également exportées pour Prometheus sur :9100/metrics (voir Surveillance). Si la machine utilise massivement le swap ou tourne à pleine charge, attendez-vous à des contrôles d’état instables et à des mises à jour lentes.

---

7. Réseau et ports

Contrôle rapide de l’accessibilité des principaux ports entrants :

for p in 25 443 8180 8190 19818; do nc -zv <this-server-ip> $p; done

Port	Service	Sens
25	Stalwart SMTP (e-mails entrants)	entrant
443	Tableau de bord (HTTPS)	entrant
8180	Keycloak	entrant
8190	Dozzle (facultatif)	entrant
19818	WireGuard (UDP et TCP)	entrant/sortant

Un accès sortant est nécessaire vers le registre de conteneurs, l’autorité de certification S/MIME (via le tunnel WireGuard) et toute instance Loki distante que vous avez configurée. Le tableau complet des ports figure sur la page d’accueil et dans l’Aperçu des applications.

Le réseau Docker chevauche le réseau local

Les services communiquent entre eux sur un réseau Docker interne. Docker choisit sa plage d’adresses à la création de la pile et évite les réseaux auxquels la VM est directement connectée à ce moment-là. Si la plage contient malgré tout des adresses de votre réseau, l’appliance ne peut pas joindre ces machines (par exemple un serveur de messagerie ou DNS), et elles ne peuvent pas la joindre. Le contrôle d’état le signale sous Docker network :

[FAIL] stargate-network 172.18.0.0/16 overlaps host routes: 172.18.5.0/24 dev ens18 - see Troubleshooting: The Docker network overlaps the local network

• L’adresse IP a été modifiée après le premier démarrage : Docker a choisi la plage alors que la VM avait encore sa première adresse. Sur une passerelle pas encore intégrée, utilisez la purge et la réinstallation décrites dans Modifier l’adresse IP du serveur ci-dessus ; Docker choisit alors lui-même une plage libre. Sur une passerelle déjà intégrée, recréez le réseau comme indiqué ci-dessous.

• Le réseau en conflit se trouve derrière un routeur (une route statique ou un réseau sur un autre site) : Docker n’évite pas ces réseaux. Le contrôle d’état voit toutes les routes de l’hôte, mais pas les réseaux joints via la passerelle par défaut. Donnez d’abord à Docker une plage libre : ajoutez ceci à /etc/docker/daemon.json, en conservant les paramètres déjà présents, avec une plage que votre réseau n’utilise pas :

  {
    "default-address-pools": [
      { "base": "10.200.0.0/16", "size": 24 }
    ]
  }
  

  Exécutez ensuite systemctl restart docker et recréez le réseau comme indiqué ci-dessous.

La recréation du réseau conserve toutes les données dans /var/data. Arrêtez d’abord le service, sinon un Dozzle en cours d’exécution garde l’ancien réseau occupé :

systemctl stop stargate
cd /usr/share/stargate-deployment/docker-compose
docker compose --env-file /var/data/vereign/.env down
systemctl start stargate
/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh

---

8. Actions de récupération

De la moins à la plus perturbatrice :

docker compose up -d <service>       # recreate one stuck service
sudo systemctl restart stargate      # restart the whole stack (via start.sh)
/usr/share/stargate-deployment/docker-compose/scripts/stop.sh  &&  /usr/share/stargate-deployment/docker-compose/scripts/start.sh

Sauvegardes et récupération destructive

/usr/share/stargate-deployment/docker-compose/scripts/backup.sh et /usr/share/stargate-deployment/docker-compose/scripts/restore.sh assurent la sauvegarde et la restauration des données. /usr/share/stargate-deployment/docker-compose/scripts/purge.sh supprime toutes les données (bases de données, Vault, stockage) en vue d’une réinstallation propre : à n’utiliser qu’en dernier recours et uniquement avec une sauvegarde à jour. Détails : Configuration avancée Docker.

---

9. Quand contacter le support

Si le contrôle d’état signale toujours des échecs après les étapes ci-dessus, ouvrez un ticket via Support / Contactez-nous en joignant :

• La version de l’appliance (/usr/share/stargate-deployment/docker-compose/scripts/gather-app-versions.sh) et le nom du client.
• La sortie du contrôle d’état (/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v).
• Le lien vers le lot de journaux généré par /usr/share/stargate-deployment/docker-compose/scripts/send-logs-to-support.sh (voir Fournir les journaux au support).
• Ce que vous faisiez au moment de la panne, ainsi que d’éventuelles captures d’écran.

Configurer Keycloak après la mise à jour

Remarque : ces instructions s’appliquent si vous utilisiez l’image de VM v0.5.1 et avez ensuite effectué une mise à jour vers une version plus récente.

Depuis la dernière mise à jour de Keycloak, une modification incompatible (breaking change) redirige de manière inattendue les utilisateurs authentifiés vers la page de connexion lorsqu’ils accèdent à certaines routes de l’application (p. ex. Peers, Peer Certificates).

Pour corriger ce problème, la configuration manuelle suivante doit être effectuée dans l’interface de Keycloak.

Étapes de résolution

1. Ouvrez Keycloak dans votre navigateur à l’adresse https://<VM IP address>:8180/admin/master/console/

   • Le port :8180 est indispensable : Keycloak est servi sur le port 8180. Si vous ouvrez l’adresse IP sans port, vous arrivez sur le tableau de bord (:443), qui vous redirige vers la connexion du realm stargate, dans lequel l’utilisateur admin n’existe pas (c’est la cause habituelle des messages « invalid username or password » ou « wrong realm » à cette étape).
   • Connectez-vous au realm master (le chemin /admin/master/console/ le sélectionne) avec le nom d’utilisateur admin (la valeur de KEYCLOAK_ADMIN_USER, en minuscules) et la valeur de KEYCLOAK_ADMIN_PASSWORD figurant dans le fichier /var/data/vereign/.env de la machine (à lire depuis la console Linux).

2. Dans la console d’administration, passez du realm master au realm stargate à l’aide du sélecteur de realm (en haut à gauche).

3. Ouvrez Clients → dashboard.
4. Ouvrez l’onglet Client scopes → cliquez sur dashboard-dedicated.
5. Sélectionnez Configure a new mapper → Audience.

6. Définissez les paramètres suivants :

   • Name : apisix-audience
   • Included client audience : apisix (à sélectionner dans la liste déroulante)
   • Included custom audience : (laisser vide)
   • Add to access token : On
   • Add to token introspection : On
   • Add to ID token / lightweight token : Off

7. Cliquez sur Save.

Réinitialiser le mot de passe d’un utilisateur Stargate dans Keycloak

Suivez les étapes ci-dessous pour réinitialiser le mot de passe d’un utilisateur Stargate via la console d’administration Keycloak.

1. Se connecter à la VM HIN Gateway

   • Ouvrez la console de la VM ou connectez-vous à la VM HIN Gateway via SSH.

2. Récupérer les identifiants de l’administrateur Keycloak

   • Ouvrez le fichier /var/data/vereign/.env.
   • Repérez les variables suivantes :
     • KEYCLOAK_ADMIN_USER
     • KEYCLOAK_ADMIN_PASSWORD

3. Ouvrir la console d’administration Keycloak

   • Dans un navigateur, accédez à l’adresse suivante : http://<VM-IP>:8180/admin/master/console
   • Remplacez <VM-IP> par l’adresse IP de la VM HIN Gateway.

4. Se connecter à Keycloak

   • Saisissez le nom d’utilisateur et le mot de passe administrateur récupérés dans le fichier .env.
   • Conservez le même mot de passe administrateur. Si vous le modifiez malgré tout, vous devez conserver le nouveau mot de passe en lieu sûr.

5. Sélectionner le realm Stargate

   • Dans le sélecteur de realm de la console d’administration Keycloak, sélectionnez Stargate.

6. Trouver l’utilisateur

   • Ouvrez Users.
   • Recherchez et sélectionnez l’utilisateur Stargate dont le mot de passe doit être réinitialisé.

7. Réinitialiser le mot de passe de l’utilisateur

   • Sélectionnez l’option de réinitialisation du mot de passe de l’utilisateur.
   • Saisissez le nouveau mot de passe et confirmez la modification.

Ne modifiez pas et ne réinitialisez pas le mot de passe de l’administrateur Keycloak dans le cadre de cette procédure. Toute modification du mot de passe administrateur peut bloquer Keycloak au point que plus personne ne puisse y accéder.

Demander un code d’activation

Pour installer ou réinstaller une instance HIN Gateway, vous avez besoin d’un code d’activation, que le support HIN peut vous fournir.

La réinitialisation du code d’activation coupe la connexion avec le pair

La réinitialisation du code d’activation d’une instance active supprime la connexion du pair WireGuard du client.

Si vous demandez cette réinitialisation pour la mauvaise instance client, la connexion de cette instance active sera supprimée et interrompue. Avant de demander une réinitialisation, vérifiez soigneusement l’instance concernée et confirmez tous les domaines qui y sont hébergés.

Redémarrage sur la VM v0.6.1

Veuillez noter que si vous redémarrez (REBOOT) une instance qui fonctionne sous v0.6.1, elle reviendra à la version précédente de Stalwart <0.0.23, qui ne fonctionne pas.

Nous vous recommandons de mettre à jour l’instance vers une version plus récente depuis la section Settings->System version !

Notes de version

v1.1.7

Publiée le 14 octobre 2026.

Nouveautés et améliorations

• Les relais sortants peuvent désormais s'authentifier avec un nom d'utilisateur et un mot de passe pour chaque domaine.
• Les relais entrants peuvent désormais s'authentifier avec un nom d'utilisateur et un mot de passe pour chaque domaine.
• Étiquette de confidentialité Outlook: les e-mails marqués comme confidentiels dans le champ d'étiquette de confidentialité de Microsoft sont désormais distribués via HIN Mail avec chiffrement aux personnes qui ne sont pas membres HIN.
• Synchronisation de l'heure: HIN Gateway utilise désormais NTP pour maintenir son horloge synchronisée avec des serveurs de temps de confiance. NTP peut être configuré dans le tableau de bord.
• Transfert des logs: les logs peuvent désormais être envoyés à Loki au moyen d'un jeton d'API.
• Migration depuis v0.5.x: un script de migration exporte la clé et le certificat S/MIME lors du passage de v0.5.x à v0.6.x ou supérieure.
• Paramètres réseau par défaut: le serveur DNS par défaut est désormais 8.8.8.8 (auparavant 1.1.1.1). Le serveur DNS peut être modifié lors de la configuration.

Corrections

• Correction des redémarrages répétés (jusqu'à trois de suite) après une modification des paramètres réseau.
• Correction d'une erreur lors de l'onboarding lorsque l'importation du certificat démarrait avant la fin de la synchronisation de l'Iris Agent.
• Les domaines sont désormais nettoyés des espaces superflus et convertis en minuscules lors de leur ajout.
• Correction du message de confirmation après la mise à jour d'un pair.
• La notification de nouvelle version est désormais traduite dans toutes les langues prises en charge.

v0.6.2

Publiée le 24 septembre 2026.

Cette version corrective renforce la sécurité de HIN Gateway, corrige la version de Stalwart et désactive le filtrage anti-spam.

Nouveautés et améliorations

• Intègre Stalwart v0.16.23, compatible avec le dernier jeu de règles du filtre anti-spam.
• Désactivation du jeu de règles anti-spam et du SpamFilter, afin qu'une nouvelle version du jeu de règles en amont ne puisse pas casser une version figée.

Corrections

• Mise à jour de la gestion du filtre anti-spam dans le script de provisionnement et amélioration de la journalisation des erreurs.
• Mise à jour de l'image Stalwart vers la version v0.16.23 et ajout d'une fonction de suppression des serveurs DNSBL.

v0.6.1

Publiée le 4 septembre 2026.

Cette version de maintenance renforce la sécurité de HIN Gateway, corrige le traitement des en-têtes d'e-mail et améliore la documentation sur les mises à jour et les migrations.

Nouveautés et améliorations

• Sécurité: l'accès externe aux ports des services internes a été restreint, et les paramètres d'authentification ainsi que les autorisations ont été renforcés.
• Mises à jour et retour arrière: ajout d'instructions pour mettre à jour HIN Gateway et revenir à une version précédente, disponibles en anglais, en allemand, en français et en italien.
• Guide de migration: mise à jour des vérifications des e-mails avant et après la migration, et ajout des traductions du guide multi-domaines.

Corrections

• Correction du traitement des en-têtes d'e-mail spécifiques à HIN.
• Ajout de l'image de disque de données VMware manquante aux téléchargements de la v0.6.0.

v0.6.0

Publiée le 31 août 2026.

Cette version apporte la prise en charge des migrations multi-domaines, la configuration des relais par domaine, l'authentification des e-mails (par exemple DKIM et ARC) ainsi que des améliorations de l'installation, de la sécurité et de la stabilité.

Nouveautés et améliorations

• Configurations multi-domaines: plusieurs domaines peuvent désormais être configurés sur un seul HIN Gateway ou y être migrés. Le guide mis à jour couvre les migrations complètes et progressives, y compris les scénarios de retour arrière.
• Configuration par domaine: la configuration des relais est désormais disponible pour chaque domaine.
• Authentification des e-mails: la signature DKIM et ARC ainsi que la vérification DKIM, ARC, SPF et DMARC peuvent désormais être configurées pour chaque domaine. Les enregistrements DNS nécessaires sont affichés directement dans HIN Gateway.
• Installation et migration: la documentation mise à jour couvre désormais les nouvelles installations, les migrations mono-domaine et multi-domaines, l'intégration Exchange, le routage du courrier, le réseau et les tests TLS.
• Migration vers l'appliance: une procédure documentée permet de transférer une installation Docker Compose existante vers l'appliance HIN Gateway basée sur une image.
• Sauvegarde et restauration: les données persistantes sont désormais stockées à un emplacement uniforme, la restauration est plus sûre et des avertissements s'affichent lorsque les versions de la sauvegarde et de la cible diffèrent.
• Diagnostic et sécurité: les contrôles de santé, la journalisation et la collecte des données de diagnostic ont été améliorés. Les scripts d'installation et de restauration protègent désormais mieux les identifiants et les données de sauvegarde.

Corrections

• Amélioration de l'initialisation initiale des paramètres Vault et WireGuard.
• Amélioration du démarrage des services sur les machines virtuelles plus lentes.
• Correction de cas particuliers affectant les opérations de sauvegarde et de restauration.
• Correction de résultats inexacts des contrôles de santé et de la gestion des valeurs de repli de la configuration.

Informations importantes pour les migrations vers l'appliance

Pour transférer une installation Docker Compose existante vers l'appliance basée sur une image, suivez le guide de migration dédié. La restauration d'une sauvegarde remplace toutes les données de l'appliance cible. Si son adresse IP publique change, HIN doit mettre à jour l'enregistrement WireGuard central.

v0.5.3

Publiée le 29 juillet 2026. Correctif appliqué le 5 août 2026.

Cette version améliore la distribution des e-mails, la gestion des certificats, le tableau de bord et le dépannage. SEAL n'est pas modifié.

Correctif du 5 août 2026

Correction d'un problème dans le processus d'importation des certificats, où le domaine n'était pas correctement associé au pair HIN Gateway correspondant.

Le correctif a été appliqué aux services centraux. Les installations locales sur machine virtuelle n'étaient pas concernées et n'ont nécessité aucune mise à jour.

Nouveautés et améliorations

• Des relais distincts peuvent désormais être configurés pour les expéditeurs et les destinataires.
• Les e-mails destinés à des destinataires hors du réseau HIN peuvent être envoyés via le relais SMTP configuré.
• L'ancienne limite horaire de traitement des e-mails a été supprimée.
• La correspondance des expéditeurs et des destinataires a été améliorée pour les e-mails entrants et sortants.
• La propriété du domaine est désormais vérifiée avant l'émission d'un certificat S/MIME.
• Les certificats des pairs peuvent désormais être recherchés et triés.
• Les certificats TLS peuvent être générés directement depuis le tableau de bord.
• Une recherche et une pagination ont été ajoutées à la vue d'ensemble des pairs.
• La recherche dans les logs est désormais plus simple.
• Un avertissement s'affiche lorsque la clé privée n'a pas été importée.
• Les messages d'erreur et les informations de diagnostic ont été améliorés.

Corrections

• Amélioration de la sélection du certificat lors de l'envoi d'e-mails chiffrés.
• Correction du traitement des messages chiffrés signés avec des certificats révoqués ou non fiables.
• Correction d'un problème lié aux jetons d'actualisation de session.
• Correction de plusieurs erreurs dans les formulaires de configuration et de gestion des domaines.
• Correction de la sélection de l'indicatif de pays et de la validation des champs.
• Correction d'un problème lors de la régénération d'un code d'activation.
• Correction du traitement de certaines informations de signataire S/MIME.
• Ajout des informations de connexion manquantes dans les journaux de distribution du tunnel.
• Les paramètres réseau sont désormais correctement réinitialisés après un changement d'adresse IP de la machine virtuelle.

v0.5.1

Notre première version.

Contactez-nous

Contactez-nous par courriel

Support

Pour toute question ou problème lié au déploiement et au fonctionnement de l'appliance Stargate, veuillez contacter le support HIN par courriel ou par téléphone:

• support@hin.ch
• 0848 830 740
• Formulaire web

Vous pouvez trouver plus d'informations sur notre page Contact: https://support.hin.ch/de/kontakt.cfm

Veuillez inclure des informations pertinentes telles que le nom du client, la version de l'appliance, et des captures d'écran/logs le cas échéant, pour nous aider à traiter votre demande efficacement.