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

🖨️

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
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
Serveurs de courrier de destination	25	TCP	Livraison des courriels sortants (via recherche MX)
Serveurs DNS	53	UDP+TCP	Sortant vers les serveurs DNS publics
Serveurs NTP	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)

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

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.

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
   

Cloud-init remplace les paramètres réseau de la VM après un redémarrage

Ceci s'applique uniquement à l'image legacy. L'appliance bootc (désormais l'option par défaut) n'utilise pas cloud-init pour gérer le réseau ; elle n'est donc pas concernée et ne fournit pas les alias cloud-init-net-* utilisés ci-dessous.

Sur l'image legacy (généralement sur VMware/ESXi), cloud-init n'a pas de source de données, se rabat sur "DHCP sur la première carte réseau" et régénère la configuration réseau à chaque démarrage, une adresse statique définie avec nmtui est donc réinitialisée après un redémarrage. Un alias corrige cela en une étape en désactivant uniquement la génération du réseau par cloud-init, de sorte qu'une adresse ensuite définie sur le profil existant persiste :

1. Empêcher cloud-init de régénérer le réseau à chaque démarrage :

   cloud-init-net-disable
   

2. Exécutez nmtui, modifiez la connexion existante cloud-init <iface> et définissez-y l'IP statique, la passerelle et le DNS. N'ajoutez pas un second profil pour la même interface, celui de cloud-init a une priorité d'autoconnexion plus élevée et l'emporterait.

   nmtui
   

3. Redémarrez et vérifiez que l'adresse persiste :

   sudo reboot
   # après le redémarrage :
   nmcli device status; ip -4 addr
   

cloud-init-net-enable rétablit le réseau géré par cloud-init par défaut. Sans l'alias, l'étape 1 est le même dépôt de fichier à la main :

echo 'network: {config: disabled}' | sudo tee /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg

Tip

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

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

É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>

É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

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 pour la livraison entrante du domaine sélectionné
Outbound relay	Le relais SMTP pour la livraison sortante du domaine sélectionné. Ce paramètre correspond au paramètre Forwarding server de 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.
DNS	Le DNS de l'hôte qui sera utilisé pour résoudre les enregistrements MX et autres enregistrements DNS
Default inbound relay	Le relais SMTP par défaut pour la livraison entrante
Default outbound relay	Le relais SMTP par défaut pour la livraison sortante

É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 pour la livraison entrante du domaine sélectionné
Outbound relay	Le relais SMTP pour la livraison sortante du domaine sélectionné. Ce paramètre correspond au paramètre Forwarding server de 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.
DNS	Le DNS de l'hôte qui sera utilisé pour résoudre les enregistrements MX et autres enregistrements DNS
Default inbound relay	Le relais SMTP par défaut pour la livraison entrante
Default outbound relay	Le relais SMTP par défaut pour la livraison sortante

É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.

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

É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

Comparaison des stratégies de migration

Recommandé – Migrer tous les domaines en une seule fois

• Aucune adresse IP publique supplémentaire requise
• Aucune modification temporaire des connecteurs ou des règles de flux de messagerie
• Retour arrière simple: éteindre Stargate, puis rallumer l’ancienne VM MGW
• Fenêtre de basculement la plus courte – risque minimal de dérive de configuration

Alternative – migration progressive, domaine par domaine

• Périmètre d’impact réduit à chaque étape – un seul domaine à risque à la fois
• Nécessite une deuxième adresse IP publique ainsi que des règles et connecteurs temporaires pour répartir le trafic
• Doit gérer les en-têtes spécifiques au client pour chaque domaine
• Le retour arrière nécessite de rejouer la séquence exacte des modifications dans l’ordre inverse

---

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, 9100) doivent être accessibles depuis votre serveur Prometheus. Si vous restreignez l'accès par IP, ajoutez l'IP de votre serveur de surveillance aux règles de pare-feu.

---

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 Stargate

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

Aperçu

Stargate 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["Stargate"]
    S2["Stargate"]

Modèle B - Stargate comme MX principal:

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

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

1. Enregistrements DNS pointant vers le serveur Stargate
2. Connecteur sortant - achemine les courriels d'Exchange vers Stargate
3. Connecteur entrant - accepte les courriels de Stargate 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:

• Stargate est installé et en cours d'exécution (instructions de déploiement)
• Vous disposez de l'adresse IP publique du serveur Stargate (référencée ci-dessous comme <STARGATE_IP>)
• Vous disposez du nom d'hôte de courrier du serveur Stargate (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 <STARGATE_IP>
• Enregistrement MX: <YOUR_DOMAIN> avec Stargate à une priorité plus élevée (nombre inférieur) qu'Exchange
• Enregistrement SPF: ip4:<STARGATE_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 → Stargate)

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

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 Stargate 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 Stargate: <STARGATE_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 Stargate (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 Stargate 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 (Stargate → Office 365)

Ce connecteur accepte les courriels du serveur relais Stargate 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 Stargate 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 Stargate: <STARGATE_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 Stargate.

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 deux connecteurs, la page Connecteurs devrait afficher:

Statut	Nom	Depuis	Vers
Activé	Receive mail from Stargate relay server	Votre org	O365
Activé	From Office 365 to Stargate relay server	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 Stargate, sauf les courriels provenant de Stargate 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 Stargate 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 Stargate.

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 Stargate 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 Stargate: <STARGATE_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 Stargate arrivant dans Exchange Online seraient redirigés vers Stargate 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 Stargate relay server"

4. Sauf si: L'adresse IP de l'expéditeur se trouve dans l'une de ces plages: <STARGATE_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.

---

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 → Stargate)

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

Shell de gestion Exchange (PowerShell) :

New-SendConnector -Name "To Stargate Relay" `
  -AddressSpaces "SMTP:*;1" `
  -SmartHosts "<STARGATE_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 Stargate Relay"
4. Type: Sélectionnez "Internet"
5. Paramètres réseau: Sélectionnez "Acheminer les courriels via des hôtes intelligents", ajoutez <STARGATE_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 (Stargate → On-Premises)

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

Shell de gestion Exchange (PowerShell) :

New-ReceiveConnector -Name "From Stargate Relay" `
  -Bindings "0.0.0.0:25" `
  -RemoteIPRanges "<STARGATE_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 Stargate 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 <STARGATE_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 Stargate" `
  -SentToScope NotInOrganization `
  -RouteMessageOutboundConnector "To Stargate Relay" `
  -ExceptIfSenderIpRanges "<STARGATE_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 Stargate"
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 Stargate Relay"
6. Sauf si: "L'adresse IP de l'expéditeur est dans..." → ajoutez <STARGATE_IP>

---

Partie 4: Configuration côté Stargate

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 Stargate et Exchange
• Stargate 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 Stargate 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 à Stargate où livrer les courriels traités pour ce domaine spécifique.

Vérifier la configuration Stargate

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 Stargate
• Sans cette exception, les courriels de Stargate arrivant dans Exchange sont redirigés vers Stargate

Stargate n'accepte pas les courriels d'Exchange

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

Exchange Online rejette les courriels de Stargate

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

Erreurs de certificat TLS

Stargate 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 Stargate 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 Stargate 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 Stargate
Connecteur entrant	Centre d'administration → Flux de courrier → Connecteurs	Accepter les courriels de Stargate
Règle de transport	Centre d'administration → Flux de courrier → Règles	Déclencher le connecteur sortant pour les destinataires externes

Enregistrement DNS	Exemple	Objectif
A	mail IN A <STARGATE_IP>	Pointer le nom d'hôte vers Stargate
MX (Stargate)	@ IN MX 15 mail.<YOUR_DOMAIN>.	Les courriels entrants frappent d'abord Stargate
MX (Exchange)	@ IN MX 20 <DOMAIN>.mail.protection.outlook.com.	Secours / cible de livraison
SPF	ip4:<STARGATE_IP> et ip4:<HIN_SEALER_IP> ajoutés à l'enregistrement TXT existant	Autoriser Stargate 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 Stargate

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

Tout au long de ce guide:

• <STARGATE_IP> - l'adresse IP publique statique de votre serveur Stargate (SERVER_STATIC_IP dans customer-config.sh)
• <MAIL_HOSTNAME> - le FQDN du relais Stargate (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>	<STARGATE_IP>	Oui	Avant l'installation
MX	<YOUR_DOMAIN>	<MAIL_HOSTNAME> (priorité 15)	Oui	Avant l'installation
SPF	<YOUR_DOMAIN>	ip4:<STARGATE_IP> ajouté au TXT	Oui	Avant l'installation
PTR	<STARGATE_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 Stargate vers l'IP publique du serveur:

<MAIL_HOSTNAME>.    A    <STARGATE_IP>

Exemple:

mail.example.ch.    A    128.140.117.200

Si Stargate 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 Stargate avec une priorité plus élevée (nombre inférieur) que le serveur de courrier existant. Cela garantit que les courriels entrants atteignent d'abord Stargate 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. Stargate avec la priorité 15 reçoit les courriels avant Exchange Online avec la priorité 20.

Pourquoi: Stargate 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 Stargate 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 Stargate 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:<STARGATE_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:<STARGATE_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 Stargate produit un message SCELLÉ (chiffré) pour un destinataire non-HIN, le dernier saut sortant vers le destinataire est le scelleur HIN, pas votre Stargate 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:

Environnement	Hôte du scelleur	IP à ajouter à SPF
HIN Test (alpha/bêta)	mx3.hintest.ch	193.247.208.66
HIN Production	À déterminer - demandez la liste canonique à HIN avant la mise en production	À déterminer

Si HIN publie plus d'un hôte de scellement (ex. mx1, mx2, mx3), incluez toutes leurs IPs. Résolvez-les avec dig +short mx hintest.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 Stargate 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 Stargate 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 Stargate 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:<STARGATE_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 Stargate, pas vers des domaines individuels).

Routage de courrier par domaine

Les enregistrements MX de chaque domaine indiquent à Stargate 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 <STARGATE_IP>

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

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

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

# DNS inversé à confirmation directe (FCrDNS)
host $(host <STARGATE_IP> | awk '{print $NF}' | sed 's/\.$//')
# Attendu: résout en <STARGATE_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 Stargate - ajoutez ip4:<STARGATE_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 Stargate

Si Stargate 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.          ← Stargate (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 Stargate) et le relais sortant (Stargate 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.

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.

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, VAULT_TOKEN, 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 auto-dérivés — laissez vide sauf si vous devez les remplacer :

Paramètre	Dérivé de	Défaut
MXENGINE_PUBLIC_ADDRESS	SERVER_STATIC_IP	http://<SERVER_STATIC_IP>:8084

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) :

• VAULT_TOKEN — Généré par Vault lors de la première initialisation, sauvegardé dans customer-config.sh
• 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	Mettre à jour les images des services (préserve le jeton Vault, recrée les conteneurs)
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)
restore.sh	Restaurer à partir d'une archive de sauvegarde (fonctionne sur une nouvelle machine)
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

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

Mettre à jour les scripts de déploiement et la configuration

Le dépôt de déploiement Stargate reçoit des mises à jour des scripts (install.sh, start.sh, health-check.sh, restore.sh, etc.), des modèles de configuration et de la documentation. Pour appliquer ces mises à jour:

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

./scripts/backup.sh

2. Récupérez et appliquez les dernières modifications

Le dépôt est la source unique de vérité pour les fichiers suivis. Mettez donc à jour en réinitialisant sur la dernière révision. Cela remplace les fichiers suivis (scripts, docker-compose.yml, modèles de configuration) par les versions du dépôt:

git fetch origin
git reset --hard origin/main

3. Redémarrez les services pour prendre en compte les modifications de scripts ou de configuration

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

Note

Votre customer-config.sh, .env et le répertoire secrets/ sont dans .gitignore, donc cette opération n'y touche pas - 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: une réinitialisation matérielle - et les mises à jour automatiques déclenchées depuis le tableau de bord - annulera 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.

Si la mise à jour inclut des modifications du modèle de configuration, comparez-le avec votre configuration existante pour voir si de nouvelles variables ont été ajoutées:

diff customer-config.sh customer-config-prod.example.sh

Mettre à jour les images des services

Les versions des applications sont gérées exclusivement via le tableau de bord. Chaque version est un manifeste versionné qui fige ensemble une combinaison connue et testée de toutes les versions de services; la page de mise à jour du tableau de bord liste les versions disponibles, et l'application de l'une d'elles récupère les images correspondantes et recrée les services concernés pour vous.

Pour mettre à jour:

1. Ouvrez le tableau de bord et accédez à la page de mise à jour.
2. Sélectionnez la version cible.
3. Confirmez - le tableau de bord applique le manifeste de version et recrée les services modifiés.

Ne changez pas les versions à la main

Ne modifiez pas les valeurs *_VERSION individuelles dans customer-config.sh ou .env pour mettre à jour les applications. Les versions sont publiées et testées ensemble en tant qu'ensemble - en choisir une à la main produit une combinaison non testée, et la modification serait de toute façon annulée par la prochaine mise à jour du tableau de bord. Mettez toujours à jour depuis le tableau de bord.

Nettoyer les anciennes images

Après les mises à jour, supprimez les images inutilisées pour libérer de l'espace disque:

docker image prune -f

Retour arrière

Pour effectuer un retour arrière, sélectionnez une version antérieure sur la page de mise à jour du tableau de bord et appliquez-la - le même mécanisme s'exécute en sens inverse et fige l'ensemble testé précédent. N'effectuez pas de retour arrière en modifiant les versions à la main.

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=<auto-généré>

## 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://203.0.113.50: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.

Flux de rappel de scellement (entrant): Lorsqu'un scelleur distant doit livrer un message scellé, il appelle MXENGINE_PUBLIC_ADDRESS (par défaut: http://<SERVER_STATIC_IP>:8084). Le protocole http:// est correct - TLS n'est pas requis car la charge utile du sceau est déjà chiffrée.

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

Vérifier l'étatLister les montagesÉcrire un secret

docker exec stargate-vault vault status

docker exec -e VAULT_TOKEN=<jeton> stargate-vault vault secrets list

docker exec -e VAULT_TOKEN=<jeton> 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-v0.6.1.x86_64.mf		4.0K / 364 bytes	Download	755f7645304bc61012d5a4970a1700f033553a872cc562926fb9d9ec052e4589
hingateway-v0.6.1.x86_64.ova		3.2G / 3429335040 bytes	Download	a63cbec510511f736a5df5326c8d0528997f181220e24415a2f37cb5bfd82597
hingateway-v0.6.1.x86_64.ovf		12K / 9322 bytes	Download	878128433cdd49fd2198611fca204ff9b0ebae91dcdadc1b6e0e17cb29831b4d
hingateway-v0.6.1.x86_64.qcow2		3.3G / 3458072576 bytes	Download	c60497fb6d215df343c456a88315058c539337d50cf062d3dcc5dd0e89c0737b
hingateway-v0.6.1.x86_64.raw		30G / 32212254720 bytes	Download	ece449d140bb475910fc9d79108cb929b7e8004a0046e8de0a9019998967d57a
hingateway-v0.6.1.x86_64.raw.gz		3.2G / 3410152384 bytes	Download	6195b21b4e79c89929b1beea5f9fe8d200f339435f1f8bd69f0e14d788e411ca
hingateway-v0.6.1.x86_64.vhd		31G / 32212255232 bytes	Download	a6f030f1598e12f187be60c65ae34b1c201da8afc1351ddbead1360979269017
hingateway-v0.6.1.x86_64.vhd.gz		3.2G / 3410152459 bytes	Download	92b138f5b03c03ab4dcb8ff64769181414a00f8a82c595a269435ef661835e1c
hingateway-v0.6.1.x86_64.vhdx		4.6G / 4857004032 bytes	Download	80856d27a9d0d03ec44b4330d5357bcc4e9f857847f9103a4344d567f42c3b66
hingateway-v0.6.1.x86_64.vmdk		3.2G / 3425249280 bytes	Download	8f4de40dcf9f920275b9a37ec126a9cd4f12f22b74a0cf5b26b6f18fb2a3a936
SHA256SUMS		4.0K / 979 bytes	Download	d375123bfe3a749990b435cd6c8c89e2fa6edd099ae878b3bf107950a0c07e31

Dépannage et diagnostics

Guide structuré pour le diagnostic d'une appliance Stargate depuis la ligne de commande: éléments à vérifier, emplacement des journaux et procédures de récupération sans risque.

Où exécuter ces commandes

Exécutez toutes les commandes ci-dessous à partir du répertoire de déploiement - le dossier contenant docker-compose.yml et scripts/ (sur les images de machine virtuelle (VM), il s'agit généralement de /usr/share/stargate-deployment/docker-compose, ou du répertoire dans lequel vous avez effectué l'installation). Toutes les commandes docker compose et ./scripts/* supposent que vous vous trouvez dans ce répertoire de travail.

cd /usr/share/stargate-deployment/docker-compose   # adjust to your install path

---

1. Commencez ici: le contrôle d'état

Une seule commande permet d'obtenir une vue d'ensemble de l'appliance:

RapideDétaillé

./scripts/health-check.sh

./scripts/health-check.sh -v

Elle indique, pour chacun des éléments suivants, si le contrôle a réussi ou échoué: l'état des conteneurs (en cours d'exécution/en bon état), les points de terminaison de vivacité (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 l'espace disque et la mémoire.

Tip

Exécutez d'abord cette commande. En général, une seule ligne FAIL permet d'identifier directement la section correspondante ci-dessous.

---

2. Où trouver les journaux

Couche	Commande	Informations affichées
Démarrage / installation initiale / démarrage automatique	sudo journalctl -u stargate -n 200 --no-pager	Le service systemd qui exécute start.sh au démarrage et lors de la première installation
Exécutions des mises à jour	cat ../update.log (racine du déploiement, un niveau au-dessus de docker-compose/)	Sortie du dernier update.sh déclenché depuis le tableau de bord ou l'hôte
Un seul service	docker logs stargate-<service> --tail 100	par exemple stargate-dashboard, stargate-mxengine, stargate-keycloak
Suivre un service en temps réel	docker logs -f stargate-mxengine	Temps réel
Tous les conteneurs en temps réel	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 conteneur
Interface web de consultation des journaux	Dozzle à l'adresse https://<SERVER_IP>:8190 (connexion Keycloak)	Consultez tous les journaux des conteneurs dans une interface utilisateur

Pour transmettre les journaux au support HIN, utilisez le script d'envoi et communiquez le lien obtenu - voir Fournir des journaux au support:

./scripts/send-logs-to-support.sh --all          # or --since 1h  / --tail 500

---

3. Conteneurs non démarrés ou en cours de redémarrage

docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'

Consultez la colonne Status:

Statut	Signification	Action
Up ... (healthy)	Fonctionnement normal	-
Up ... (no health)	En cours d'exécution; aucun contrôle d'état défini	Consultez ses docker logs si vous suspectez un problème
Restarting	Redémarrages en boucle	docker logs stargate-<svc> - corrigez l'erreur à l'origine du problème (configuration, secret, dépendance)
Exited (0)	Initialisation ponctuelle terminée correctement (p. ex. *-init, vault-data-fixer)	Normal
Exited (1+)	Échec	docker logs stargate-<svc> - les dernières lignes indiquent la cause
Created	Jamais démarré - une dépendance n'a pas démarré	Vérifiez de quoi il dépend (depends_on, généralement Postgres/Vault); 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 que leurs dépendances soient disponibles (depends_on + contrôles d'état). Lors d'un redémarrage complet, il est normal que des lignes connection refused / database system is starting up apparaissent brièvement pendant le démarrage de Postgres/Vault; elles disparaissent en moins d'une minute.

---

4. Diagnostic par symptôme

Le tableau de bord ou Keycloak ne se charge pas / impossible de se connecter

• Le tableau de bord et Keycloak sont tous deux placés derrière Caddy: le tableau de bord sur :443, Keycloak sur :8180.
• Vérifiez l'ensemble de la chaîne: docker logs stargate-caddy, stargate-dashboard, stargate-keycloak, stargate-apisix.
• Keycloak doit être en bon état avant que le tableau de bord puisse fonctionner: docker compose ps keycloak.
• L'avertissement TLS dans le navigateur est normal (certificat auto-signé) - acceptez-le et poursuivez.
• Si les redirections de connexion échouent, cela signifie généralement que l'URL publique ne correspond pas à la manière dont 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

Il s'agit du problème le plus fréquent - l'émission des certificats échoue lorsque le tunnel est indisponible, donc commencez toujours par rétablir le tunnel.

./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) dans les deux sens.
• Vérifiez que le pair est enregistré côté HIN (étape effectuée par le support) - vous devez fournir la clé publique WG, DEPLOYMENT_NAME, SERVER_STATIC_IP, 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/policy fonctionnent. Les clés se trouvent dans 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 ./scripts/init-vault.sh tente à nouveau de desceller Vault.

Ne supprimez pas secrets/vault-keys.json

La perte de ce fichier entraîne la perte de l'accès à tous les secrets enregistrés. Conservez-en une sauvegarde.

Connectivité PostgreSQL / bases de données

docker compose exec postgres pg_isready -U postgres
docker logs stargate-postgres --tail 50

• L'apparition temporaire du message the database system is starting up (57P03) juste après un redémarrage est normale - les services se reconnectent automatiquement.
• Des échecs d'authentification persistants indiquent généralement que POSTGRES_PASSWORD dans .env ne correspond plus à celle du volume de données - consultez les remarques relatives aux mises à jour et aux secrets, et évitez de modifier cette valeur manuellement.

Les e-mails ne sont pas acheminés

• Les e-mails entrants arrivent sur :25 (Stalwart). De nombreux fournisseurs de services 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 25 est bloqué, demandez une exception à votre fournisseur. - Le trafic sortant et le scellement suivent le chemin Stalwart → mxengine (:8084 callback de scellement, SMTP :1587): docker logs stargate-mxengine. - Les boucles de messagerie se manifestent par le même message qui circule en continu - vérifiez que l'enregistrement MX de votre domaine ne pointe pas vers l'adresse IP propre de cette appliance. - Voir Configuration du relais de messagerie et Configuration DNS pour le routage attendu.

Échec d'une mise à jour

docker logs stargate-ops-agent --tail 40      # the update orchestrator
cat ../update.log                             # the update script output

• L'ops-agent récupère le manifeste de version, inscrit les versions dans customer-config.sh, puis exécute update.sh sur l'hôte.
• Une fois l'opération terminée, vérifiez les versions appliquées: ./scripts/gather-app-versions.sh (ou contrôlez les tags d'image avec docker compose ps).
• Si un service reste bloqué après une mise à jour, exécutez docker compose up -d <service> pour le recréer.

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 ne progresse 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é manuellement). Le git checkout de l'ops-agent refuse alors de s'exécuter, ce qui bloque la mise à jour. Réinitialisez le dépôt de force 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/ figurent dans .gitignore et sont préservés:

cd /usr/share/stargate-deployment
git fetch origin
git checkout -f main
git reset --hard origin/main
sed -i 's/^OPS_AGENT_VERSION=.*/OPS_AGENT_VERSION="v0.0.3"/' docker-compose/customer-config.sh   # v0.0.3 or newer
cd docker-compose
./scripts/update.sh

update.sh régénère .env, récupère les images et recrée les services concernés - vous n'avez pas besoin de redémarrer Stargate manuellement. Une fois l'opération terminée, relancez la mise à jour depuis le tableau de bord; elle se poursuivra alors normalement.

Warning

N'utilisez pas git pull ici. Sur une copie de travail comportant des modifications locales, cette commande échoue avec le message «local changes would be overwritten», ce qui impose de passer par un git stash, un conflit de fusion ou une récupération manuelle. La séquence git checkout -f puis git reset --hard ci-dessus évite entièrement ce problème: c'est la méthode sûre et reproductible pour remettre le dépôt à jour.

Dozzle (visualisateur de journaux) inaccessible

• L'URL est https://<SERVER_IP>:8190; une connexion Keycloak (même realm que le tableau de bord) est requise via oauth2-proxy.
• Il ne s'exécute que si DOZZLE_ENABLED="true". Vérifiez: docker compose ps dozzle oauth2-proxy.
• Assurez-vous que le pare-feu autorise :8190 en entrée. Voir Surveillance et journaux.

---

5. Stockage et espace 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 limités (json-file, 100 MB × 5 par conteneur), ils ne devraient donc pas saturer le disque, mais les images et les volumes le peuvent.
• Récupérez de l'espace sans risque avec: docker image prune -af (supprime uniquement les images inutilisées). Évitez docker system prune --volumes - cette commande 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 fortement le swap ou est saturée, les contrôles d'état risquent de devenir instables et les mises à jour de ralentir.

---

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	Direction
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 auriez configurée. Consultez le tableau complet des ports sur la page d'accueil et dans l'Aperçu des applications.

---

8. Actions de récupération

Classées 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)
./scripts/stop.sh  &&  ./scripts/start.sh

Sauvegardes et récupération destructive

./scripts/backup.sh et ./scripts/restore.sh assurent la sauvegarde et la restauration des données. ./scripts/purge.sh supprime toutes les données (bases de données, Vault, stockage) afin de permettre 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 indique toujours des échecs après les étapes ci-dessus, ouvrez un ticket via Support / Contactez-nous et joignez les éléments suivants:

• La version de l'appliance (./scripts/gather-app-versions.sh) et le nom du client.
• La sortie du contrôle d'état (./scripts/health-check.sh -v).
• Un lien vers une archive de journaux générée par ./scripts/send-logs-to-support.sh (voir Fournir des journaux au support).
• Ce que vous faisiez au moment du dysfonctionnement, ainsi que toute capture d'écran utile.

Mettre à jour une instance Verimesh

Les instructions suivantes décrivent la mise à jour d'une instance Verimesh de la version v0.5.1 vers la version v0.5.3.

Remarque: vous devez vous connecter à la VM avec le compte administrateur Linux.

Étapes de mise à jour

1. Modifiez le fichier .env et définissez la version de l'ops-agent sur v0.0.3.
2. Modifiez également la configuration du client et définissez-y la version de l'ops-agent sur v0.0.3.
3. Basculez sur la branche main: git checkout main
4. Récupérez les dernières modifications: git pull
5. Mettez à jour le conteneur ops-agent: docker compose up -d ops-agent
6. Connectez-vous au tableau de bord.
7. Accédez à Settings.
8. Dans la section Update, en bas de la page, saisissez la version cible (v0.5.3) et lancez le processus de mise à jour.

Configurer Keycloak après la mise à jour

Remarque: ces instructions s'appliquent si vous étiez sur l'image de VM v0.5.1 et que vous avez ensuite effectué une mise à jour vers une version plus récente.

À la suite de la dernière mise à jour de Keycloak, une modification incompatible entraîne la redirection inattendue des utilisateurs authentifiés vers la page de connexion lorsqu'ils accèdent à certaines routes de l'application (par exemple Peers, Peer Certificates).

Pour résoudre ce problème, la configuration manuelle suivante doit être effectuée dans l'interface de Keycloak.

Étapes de résolution

1. Ouvrez Keycloak sur l'environnement concerné et saisissez l'URL - <VM IP address>/admin/master/console/ utilisateur: Admin mot de passe: récupérez le mot de passe administrateur dans le fichier .env de la machine (vous devez pour cela vous connecter à la console Linux)

2. Console d'administration - changez de realm vers → realm stargate:

3. Allez dans 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: (laissez vide)
   • Add to access token: On
   • Add to token introspection: On
   • Add to ID token / lightweight token: Off

7. Cliquez sur Save

Release Notes

v0.6.1

Released on 4 September 2026.

This maintenance release strengthens HIN Gateway security, corrects email-header handling and improves update and migration guidance.

What’s new and improved

• Security: Restricted external access to internal service ports and strengthened authentication settings and permissions.
• Updates and rollback: Added instructions for updating HIN Gateway and returning to a previous version, available in English, German, French and Italian.
• Migration guidance: Updated email checks before and after migration and added translations of the multi-domain guidance.

Fixes

• Corrected the handling of HIN-specific email headers.
• Added the missing VMware data-disk image to the v0.6.0 downloads.

v0.6.0

Released on 31 August 2026.

This release adds multi-domain migration support, domain-level relay configuration, email authentication(such as DIKM and ARC) and improvements to installation, security and stability.

What’s new and improved

• Multi-domain setups: Multiple domains can now be configured or migrated to a single HIN Gateway. The updated guidance covers complete and phased migrations, including rollback scenarios
• Domain based configuration: Relay configuration per domain is now available
• Email authentication: DKIM and ARC signing, as well as DKIM, ARC, SPF and DMARC verification, can now be configured for each domain. The required DNS records are shown directly in the HIN Gateway
• Installation and migration: Updated guidance now covers new installations, single-domain and multi-domain migrations, Exchange integration, mail routing, networking and TLS testing
• Appliance migration: A documented process is available for moving an existing Docker Compose installation to the image-based HIN Gateway appliance
• Backup and restore: Persistent data now uses a consistent location, with safer restore handling and warnings when backup and target versions differ
• Diagnostics and security: Health checks, logging and diagnostic collection have been improved. Installation and recovery scripts now provide better protection for credentials and backup data

Fixes

• Improved first-time initialization of Vault and WireGuard settings
• Improved service startup on slower virtual machines
• Fixed edge cases affecting backup and restore operations
• Fixed inaccurate health-check results and configuration fallback handling

Important information for appliance migrations

When moving an existing Docker Compose installation to the image-based appliance, follow the dedicated migration guide. Restoring a backup replaces all data on the target appliance. If its public IP address changes, HIN must update the central WireGuard registration.

v0.5.3

Released on 29 July 2026. Hotfix applied on 5 August 2026.

This release improves email delivery, certificate handling, the dashboard and troubleshooting. There are no changes to SEAL.

Hotfix, 5 August 2026

Fixed an issue in the certificate import process where the domain was not correctly linked to the corresponding HIN Gateway peer.

The fix was applied to the central services. Local virtual machine installations were not affected and did not require an update.

What’s new and improved

• Separate relays can now be configured for senders and recipients.
• Emails to recipients outside the HIN network can be sent through the configured SMTP relay.
• The previous hourly email-processing limit has been removed.
• Sender and recipient matching has been improved for incoming and outgoing emails.
• Domain ownership is now checked before an S/MIME certificate is issued.
• Peer certificates can now be searched and sorted.
• TLS certificates can be generated directly from the dashboard.
• Search and pagination have been added to the peer overview.
• Searching through logs is now easier.
• A warning is shown when the private key has not been imported.
• Error messages and diagnostic information have been improved.

Fixes

• Improved certificate selection when sending encrypted emails.
• Fixed the handling of encrypted messages signed with revoked or untrusted certificates.
• Fixed an issue with session refresh tokens.
• Fixed several errors in the setup and domain-management forms.
• Fixed country-code selection and field validation.
• Fixed an issue when regenerating an activation code.
• Fixed the processing of certain S/MIME signer information.
• Fixed missing connection information in tunnel delivery logs.
• Network settings are now correctly reset after the virtual machine’s IP address changes.

v0.5.1

Our initial release.

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.