Stargate Bereitstellungsanleitung

🇩🇪 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.

Was ist Stargate?

Voraussetzungen

Bitte stellen Sie sicher, dass alle notwendigen vorbereitenden Schritte abgeschlossen sind, bevor die Migration oder Neuinstallation des HIN Gateway beginnt.

Die folgenden Punkte müssen vor der Installation verfügbar oder bestätigt sein:

• Zugangsdaten werden Ihnen von HIN zur Verfügung gestellt

  • VM-Zugangsdaten
  • Keycloak-Zugangsdaten
  • Aktivierungscode

• Export des/der privaten Schlüssel(s)

Info

Der Export privater Schlüssel ist nur für Kunden relevant, die von einem bestehenden MGW zu einem neuen HIN Gateway wechseln

• Wenn Sie an einem Windows-Rechner arbeiten, der über Port 22 Zugriff auf die Mail Gateway VM hat, können wir Sie während des Calls bei der Aktivierung des Exports des privaten Schlüssels vom MGW unterstützen.
• Falls Sie keinen Zugriff auf einen solchen Rechner haben, wenden Sie sich bitte per E-Mail oder Telefon an den HIN Support (support@hin.ch / 0848 830 740), um eine Support-Verbindung über System Administration → Support Connection → Connect herzustellen.

Für Kunden mit mehreren Domains

Hinweis: gilt für alle Multi-Domain-Migrationsszenarien!

Um den für die Migration benötigten Zeitaufwand zu reduzieren, empfehlen wir Kunden, die folgenden Schritte bereits vor dem geplanten Migrationstermin und der Sitzung durchzuführen:

• Exportieren Sie den privaten Schlüssel für jede Domain.
• Identifizieren und dokumentieren Sie den eingehenden und ausgehenden Mailfluss für jede Domain.

Bitte wenden Sie sich an den HIN Support, um den Freischaltcode zu erhalten, der für den Export der privaten Schlüssel benötigt wird.

• Neueste Version herunterladen des VM-Images
• Firewall-Anforderungen für WireGuard. Konfigurieren Sie den WireGuard-Port 19818 (TCP/UDP) in Ihrer Firewall:
  • Eingehender und ausgehender Datenverkehr
  • Datenverkehr zulassen: any-to-HIN Gateway und HIN Gateway-to-any

• DHCP-Zugriff sollte verfügbar sein. Weitere Informationen finden Sie in den "Installation Guidelines".

• Backup-Anforderungen - siehe "Anhang 1 - Sichern und Wiederherstellen der Appliance-Einstellungen".

Info

Backup-Anforderungen gelten nur für Kunden, die von einem bestehenden MGW zu einem neuen HIN Gateway wechseln

• Bestätigung, dass das bestehende MGW erst nach Abschluss der Abnahme gelöscht wird.

Info

Das Verfügbarhalten des bestehenden MGW bis zum Abschluss des Abnahmeberichts gilt nur für Kunden, die von einem bestehenden MGW zu einem neuen HIN Gateway wechseln

• Zugriff auf DNS, Mail-Server-Connectors, Transportregeln und Relay-Einstellungen.

Schnellstart

Installationsoptionen

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

🖨️

Sie können diese Dokumentation ausdrucken oder als PDF speichern. Besuchen Sie unsere Druckseitenansicht.

Exchange-Integration

• Exchange-Integration – Konfigurieren Sie Microsoft Exchange (Online und On-Premises)-Connectors und Transportregeln, um E-Mails über Stargate zu leiten

Server-Anforderungen

	Minimum	Empfohlen
CPU, Kerne	4	6
RAM, GB	8	12
SSD, GB	60	60

Allgemeine Anforderungen

• Root-Zugriff: Muss als Root oder mit sudo ausgeführt werden
• Unterstützte Distributionen:
  • RHEL 8, 9 und 10 kompatible Distributionen wie Alma Linux, Rocky Linux, CentOS Stream
  • Ubuntu 22 und 24
  • Debian 11, 12 und 13
• Reale IPv4-Adresse
• Gültige DNS-Einträge. Ihre Domain muss Folgendes haben:
  • MX-Einträge, die auf Ihre Mailserver verweisen
  • SPF-Eintrag, der die erlaubten sendenden Netzwerke definiert
  • Der Server muss in der Lage sein, DNS aufzulösen (MX, SPF, A-Einträge)
  • Wird für das Mail-Routing und die SPF-basierte Netzwerk-Allowlist verwendet

Eingehender Netzwerkzugriff (Firewall muss erlauben)

Port	Protokoll	Zweck
25	TCP	SMTP – Empfangen von E-Mails von externen Servern
19818	UDP+TCP	WireGuard – Verschlüsselter Tunnel für die Agent-zu-Agent-Kommunikation. Lesen Sie unser Sicherheitsgutachten zu WireGuard

Eingehender VM-Zugriff (von Ihrem Administrationsrechner zur HIN Gateway VM)

Info

Diese Firewall-Regeln sollten nur zwischen Ihrem Administrationsrechner und der HIN Gateway VM angewendet werden. Es ist nicht erforderlich, diese Ports für das Internet freizugeben.

Port	Protokoll	Zweck
80	TCP	Leitet HTTP-Datenverkehr auf HTTPS um
443	TCP	Dient zur Verwaltung des HIN Gateway über das Web-Dashboard
8180	TCP	Wird von Keycloak zur Authentifizierung von Benutzern für das HIN Gateway Dashboard verwendet
8190	TCP	Optional. Erforderlich für die Fehlerbehebung und das Anzeigen von Protokollen
22	TCP	Optional. Erforderlich für die Fehlerbehebung und das Ändern der Konfiguration

Ausgehender Netzwerkzugriff (Server muss erreichen können)

Ziel	Port	Protokoll	Zweck
registry-1.docker.io, auth.docker.io, production.cloudflare.docker.com	443	TCP	Docker-Hub-Image-Registry
quay.io	443	TCP	Container-Registry (Keycloak, oauth2-proxy)
github.com	443	TCP	Richtlinien-Repository (policy-sync)
Ihr eigener Loki-Endpunkt (z. B. loki.example.com)	443	TCP	Optional. Nur erforderlich, wenn Sie eine eigene Loki-Instanz bereitstellen, an die der Stack Logs senden soll (Alloy → Loki)
Update-Server von Alpine, AlmaLinux usw.	80	TCP	Verschiedene Update-Server
Ziel-Mailserver	25	TCP	Zustellung ausgehender E-Mails (via MX-Lookup)
DNS-Server	53	UDP+TCP	Ausgehend an öffentliche DNS-Server
NTP-Server	123	UDP	NTP synchronisiert die Uhren von Computern, Servern, Netzwerkgeräten und virtuellen Maschinen mit präzisen Zeitquellen
WireGuard-Peers (HIN-Netzwerk)	19818	UDP+TCP	WireGuard – Verschlüsselter Tunnel für die Agent-zu-Agent-Kommunikation
witness-{1,2,3}.verify-mail.hin-infra.ch	443	TCP	HIN KERI-Witness-Pool - erforderlich für die Verifizierung von Agent-Identitäten (idagent / watcher)
app.hin.ch	443	TCP	HIN Mitglieder- / Maildomain-Liste (mxengine)
apisix.verify-mail.hin-infra.ch	443	TCP	Registrierung des HIN Gateways beim Onboarding (Dashboard)

Firewall-Hinweis

Abhängig von Ihrer Firewall- oder NAT-Konfiguration müssen Sie den Datenverkehr für die erforderlichen Ports möglicherweise explizit zulassen. Weitere Informationen finden Sie in der Dokumentation Ihrer Firewall bzw. NAT-Konfiguration.

Die VM muss eingehende Verbindungen auf den erforderlichen Dienstports akzeptieren und Antworten zurück an den Anfragenden senden können. Bei einer zustandsbehafteten Firewall (z. B. iptables mit conntrack) wird der Rückverkehr durch die ESTABLISHED,RELATED-Regeln automatisch zugelassen.

Beispiel für eine iptables-Konfiguration:

# Rückverkehr für bestehende Verbindungen zulassen
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Eingehende TCP-Verbindungen zu den offenen Ports zulassen
iptables -A INPUT -p tcp -m multiport --dports 25,19818 -j ACCEPT

# Ausgehende TCP-Verbindungen zu den offenen Ports zulassen
iptables -A OUTPUT -p tcp -m multiport --dports 25,19818 -j ACCEPT

# Eingehenden UDP-Port 19818 für WireGuard zulassen
iptables -A INPUT -p udp --dport 19818 -j ACCEPT

# Ausgehenden UDP-Port 19818 für WireGuard zulassen
iptables -A OUTPUT -p udp --dport 19818 -j ACCEPT

# Zusätzliche Dienste, die von der VM erreichbar sein müssen
# 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

Kontaktieren Sie uns

Support

Bei Fragen oder Problemen im Zusammenhang mit der Bereitstellung und dem Betrieb der HIN Mail (Stargate)-Appliance wenden Sie sich bitte an den HIN-Support.

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs hinzu, um die Bearbeitung Ihres Anliegens zu beschleunigen.

---

Installationsanleitungen

HIN Gateway: Technischer Leitfaden für Neuinstallation und Migration

Einleitung

Dieses Dokument bietet einen umfassenden Leitfaden für die technische Installation und Migration auf das neue HIN Gateway ("Stargate Appliance").

Die Anleitung richtet sich an HIN Kunden, IT-Administratoren und Systemingenieure, die für die Bereitstellung und Konfiguration des neuen HIN Gateways sowie, sofern zutreffend, für die Migration vom bestehenden Mail-Gateway (MGW) zur neuen Lösung verantwortlich sind.

Das HIN Gateway ist eine sichere E-Mail-Gateway-Lösung, die eine vertrauenswürdige, verschlüsselte und richtliniengesteuerte Kommunikation innerhalb des HIN Trust Circle ermöglicht. Es fungiert als zentraler Vermittler zwischen internen E-Mail-Infrastrukturen und externen Kommunikationspartnern und stellt sicher, dass der gesamte E-Mail-Verkehr sicher übertragen wird, den Richtlinien der Organisation entspricht und die Sicherheitsstandards von HIN erfüllt.

Übersicht über den E-Mail-Fluss

• Eingehende E-Mails werden über das HIN Gateway geleitet, wo sie validiert, (falls erforderlich) entschlüsselt und anhand von Vertrauens- und Sicherheitsrichtlinien überprüft werden, bevor sie an den internen Mailserver weitergeleitet werden.
• Ausgehende E-Mails werden von internen Systemen an das HIN Gateway gesendet, wo Verschlüsselung, Weiterleitung und die Durchsetzung der Richtlinien erfolgen, bevor sie an externe Empfänger übermittelt werden.
• Die Kommunikation zwischen den HIN Gateways wird durch Peer-Zertifikate und WireGuard-Tunnel gesichert, wodurch eine vertrauenswürdige Kommunikation zwischen den Domänen gewährleistet wird.

Installations- und Migrationsablauf

Die in diesem Dokument beschriebene strukturierte Schritt-für-Schritt-Anleitung deckt sowohl Neuinstallationen des HIN Gateways als auch Migrationen von einem bestehenden HIN Mail Gateway (MGW) ab. Je nach Bereitstellungsszenario gelten einzelne Schritte möglicherweise nur für Migrationen.

1. Vorbereitung und Bereitstellungsplanung, einschliesslich Ausweichplanung, sofern zutreffend
2. Installation und Konfiguration des HIN Gateways
3. Domänenaktivierung und Zertifikatsvalidierung
4. Integration in die bestehende Mail-Umgebung und Konfiguration des Routings
5. Testen, Übergang in den Produktivbetrieb und Validierung nach der Bereitstellung
6. Bei Migrationen: Ausserbetriebnahme des bestehenden MGW nach erfolgreicher Validierung

Migration

Das Ziel von HIN ist es, eine sichere, reibungslose und vollständig validierte Bereitstellung mit minimaler Beeinträchtigung des Betriebs und unterbrechungsfreier Kontinuität der E-Mail-Dienste zu gewährleisten. In Migrationsszenarien sollte das bestehende MGW als Ausweichoption verfügbar bleiben, bis das HIN Gateway im Produktivbetrieb erfolgreich validiert wurde. Es sollte erst ausser Betrieb genommen werden, nachdem die Migration abgeschlossen und der stabile Betrieb bestätigt wurde.

Häufig gestellte Fragen

Kann ich die Installation oder Migration selbst durchführen?

Ja, die Installation oder Migration kann vollständig vom Kunden durchgeführt werden.

Für das Migrationsszenario besteht die einzige Ausnahme bei "Schritt 1.3 - Exportieren der/des privaten Schlüssel(s)". Aus Sicherheitsgründen und um Ihren privaten Schlüssel zu schützen, müssen Sie sich an den HIN Support wenden oder an der geplanten Migrationsbesprechung teilnehmen, um den Code zu erhalten, der für den Export des privaten Schlüssels aus dem derzeit in Betrieb befindlichen Mail-Gateway erforderlich ist.

Sollten die Installation oder die Migration nicht erfolgreich abgeschlossen werden können, nehmen Sie bitte am geplanten Support-Gespräch mit unseren Technikern teil.

Kommt es während des Einrichtungsprozesses zu einer Unterbrechung der E-Mail-Zustellung?

Migration: Zwischen "Schritt 1.5 - Bestehende MGW-VM abschalten" und "Schritt 18 - Mailserver konfigurieren" werden alle E-Mails auf dem Mailserver in die Warteschlange gestellt. Sobald "Schritt 18 - Mailserver konfigurieren" abgeschlossen ist, werden die in der Warteschlange befindlichen E-Mails versendet oder in das Postfach zugestellt.

Neuinstallation: Während Sie die E-Mail-Flussregeln konfigurieren, werden alle E-Mails auf dem Mailserver in die Warteschlange gestellt. Sobald "Schritt 18 - Mailserver konfigurieren" abgeschlossen ist, werden die in der Warteschlange befindlichen E-Mails versendet oder in das Postfach zugestellt.

Gehen während der Installation und Migration E-Mails verloren?

Nein, während der Installation und Migration gehen keine E-Mails verloren. Einige E-Mails können sich verzögern.

Übersicht über die Installationsschritte

Schritt	Thema	Verantwortung	Migration	Neuinstallation
0	Voraussetzungen prüfen	Kunde	Ja	Ja
1.1	Smoke-Test	Kunde	Ja	N/A
1.2	Sichern des bestehenden MGWs	Kunde	Ja	N/A
1.3	Exportieren der/des privaten Schlüssel(s)	Kunde / HIN	Ja	N/A
1.4	Notfallplan / Ausweichszenario	Kunde	Ja	N/A
1.5	Bestehende MGW-VM abschalten	Kunde	Ja	N/A
2	WireGuard	Kunde	Ja	Ja
3	Ziel-VM auswählen	Kunde	Ja	Ja
4	VM-Image laden	Kunde	Ja	Ja
5	Netzwerkverbindung zur VM	Kunde	Ja	Ja
6	Zugriff über den Browser	Kunde	Ja	Ja
7	Aktivierungscode eingeben	Kunde	Ja	Ja
8	Setup des Mesh-Netzwerks	Kunde	Ja	Ja
9	Sicheres Mesh-Netzwerk einrichten	Kunde	Ja	Ja
10	Login bei Keycloak	Kunde	Ja	Ja
11	Passwort aktualisieren	Kunde	Ja	Ja
12	Kontoinformationen aktualisieren	Kunde	Ja	Ja
13	Erstkonfiguration und Einrichten der Domäne	Kunde	Ja	Ja
14	E-Mail-Transport konfigurieren	Kunde	Ja	Ja
15	Whitelist-Header konfigurieren	Kunde	Ja	Ja
16	Peer-Zertifikate	HIN	Ja	Ja
17	Peer-Zertifikate validieren	Kunde	Ja	Ja
18	Mailserver konfigurieren	Kunde	Ja	Ja
19	Test und Validierung	Kunde	Ja	Ja
20	Passwort der VM ändern	Kunde	Ja	Ja
21	Bestehendes MGW ausser Betrieb nehmen	Kunde	Ja	N/A
Anhang 1	Sichern und Wiederherstellen der Appliance-Einstellungen	Kunde	Ja	N/A

Detaillierte Schritte

Schritt 0 - Voraussetzungen prüfen

Bitte stellen Sie sicher, dass alle notwendigen Vorbereitungsschritte abgeschlossen sind, bevor die Migrationsarbeiten für das HIN Gateway beginnen.

Die folgenden Punkte müssen vor der Installation verfügbar sein oder bestätigt werden:

• Die Zugangsdaten werden Ihnen von HIN zugestellt

  • VM-Zugangsdaten
  • Keycloak-Zugangsdaten
  • Aktivierungscode

• Export des privaten Schlüssels Hinweis: Gilt nur für Migrationsfälle

  • Wenn Sie an einem Windows-Rechner arbeiten, der über Port 22 Zugriff auf die Mail-Gateway-VM hat, können wir Sie während des Gesprächs dabei unterstützen, den Export des privaten Schlüssels aus dem MGW zu aktivieren.
  • Falls Sie keinen Zugriff auf einen solchen Rechner haben, wenden Sie sich bitte per E-Mail oder Telefon (support@hin.ch / 0848 830 740) an den HIN Support, damit wir Ihnen helfen können, eine Supportverbindung über "Systemadministration" -> "Supportverbindung" -> "Verbinden" herzustellen.
• Laden Sie die neueste Version des VM-Images herunter.
• Firewall:
  • Erlauben Sie den Datenverkehr: beliebig → HIN Gateway und HIN Gateway → beliebig
    • WireGuard: Siehe Serveranforderungen: Eingehender Netzwerkzugriff:
      • Konfigurieren Sie den WireGuard-Port 19818 (TCP/UDP) in Ihrer Firewall.
        • Eingehender und ausgehender Datenverkehr
  • Erlauben Sie den Datenverkehr: Administrationsrechner → HIN Gateway-VM
    • Anforderungen für die Installation:
      • HTTPS-Port 443
        • Eingehender und ausgehender Datenverkehr
      • Keycloak-Port 8180
        • Eingehender und ausgehender Datenverkehr
    • Anforderungen für die Fehlerbehebung (optional, um Protokolle einzusehen und alle Parameter zu ändern):
      • SSH-Port 22
        • Eingehender und ausgehender Datenverkehr
      • Dozzle-Port 8190
        • Eingehender und ausgehender Datenverkehr
• Für "Schritt 5 - Netzwerkverbindung zur VM" sollte ein DHCP-Zugang verfügbar sein (empfohlen).
• Anforderungen an die Datensicherung, siehe "Anhang 1 - Sichern und Wiederherstellen der Appliance-Einstellungen". Hinweis: Gilt nur für Migrationsfälle
• Hinweis: gilt nur für Migrationsfälle. Bestätigung, dass das bestehende MGW erst nach Abschluss der Abnahme gelöscht wird.
• Zugriff auf DNS, Mailserver-Konnektoren, Transportregeln und Relay-Einstellungen.

Warum WireGuard?

Der WireGuard-Port erfüllt zwei wichtige Funktionen:

1. Das HIN Gateway nutzt diesen Port, um Peer-Zertifikate von der HIN CA zu beziehen.
2. Es nutzt diesen Port, um einen sicheren Tunnel zu anderen HIN Gateways aufzubauen, über den der sichere Datenaustausch (z.B. E-Mail-Verkehr) stattfindet.

!!! tip "Export des privaten Schlüssels" - Gilt nur für Migrationsfälle Falls Sie an einem Windows-Rechner arbeiten, der über Port 22 Zugriff auf die Mail Gateway-VM hat, können wir Sie während des Anrufs unterstützen, um den Export des privaten Schlüssels vom MGW zu aktivieren.

Falls Sie keinen Zugriff auf einen solchen Rechner haben, wenden Sie sich bitte an den HIN Support per E-Mail oder Telefon (**support@hin.ch** / **0848 830 740**), um eine Support-Verbindung über **Systemverwaltung → Support-Verbindung → Verbinden** herzustellen.

Schritt 1.1 - Smoke-Test

Info

Dieser Schritt gilt nur für Einzel- und Multi-Domain-Migrationen

Senden Sie Test-E-Mails an die folgenden Empfänger und verwenden Sie dabei Postfächer, auf die Sie Zugriff haben, damit die erfolgreiche Zustellung überprüft werden kann:

• eine HIN E-Mail-Adresse oder eine E-Mail-Adresse innerhalb Ihrer HIN Community-Domain, zum Beispiel: user@hin.ch
• eine externe E-Mail-Adresse ausserhalb der HIN Community, zum Beispiel: Bluewin, Gmail, Yahoo oder GMX

Senden Sie für den externen Empfänger eine E-Mail aus der HIN Community mit dem Vermerk (vertraulich) in der Betreffzeile.

Testen Sie den E-Mail-Fluss in beide Richtungen:

• von der vertrauenswürdigen HIN-Domain zur externen E-Mail-Adresse
• von der externen E-Mail-Adresse zur HIN Community

Überprüfen Sie, ob alle Test-E-Mails erfolgreich zugestellt wurden und Betreff, Inhalt und allfällige Anhänge korrekt empfangen wurden.

Schritt 1.2 - Sichern des bestehenden MGWs

Info

Dieser Schritt gilt nur für Einzel- und Multi-Domain-Migrationen

Erstellen Sie ein Backup der bestehenden MGW-Appliance und stellen Sie sicher, dass die VM so lange bestehen bleibt, bis die Migration erfolgreich abgeschlossen und formell abgenommen wurde. Weitere Informationen finden Sie unter "Anhang 1 - Sichern und Wiederherstellen der Appliance-Einstellungen".

Aktuelle MGW-Routing-Konfiguration prüfen

Bevor Sie das bestehende MGW abschalten, überprüfen Sie die folgenden Konfigurationswerte und notieren Sie sie. Sie werden diese wahrscheinlich später bei der Konfiguration des HIN Gateways benötigen:

1. Melden Sie sich beim MGW an und gehen Sie zu "Mail System → Outgoing server" und prüfen Sie, ob dort etwas konfiguriert ist.
2. Gehen Sie für jede auf dem MGW gehostete Domäne zu Mail System → <Domäne> → Forwarding server und Mail System → <Domäne> → Send ALL outgoing mails from this domain to the following SMTP server und notieren Sie die aktuellen Werte.
   

MGW-Header-Prüfung

Wenn Sie im MGW die Option Header check verwenden, notieren Sie sich auch den konfigurierten Wert. Sie können dieselbe Header-Prüfung später im HIN Gateway einrichten.

Schritt 1.3 - Exportieren der/des privaten Schlüssel(s)

Info

Dieser Schritt gilt nur für Einzel- und Multi-Domain-Migrationen

Führen Sie den Vorgang bei einer Multi-Domain-Migration für jede Domäne durch

Unterstützung durch HIN erforderlich

Für diesen Schritt ist ein Freischaltcode erforderlich. Der Code wird von einem HIN Support Engineer bereitgestellt.

Wenn Sie die Installation selbstständig fortsetzen möchten, kontaktieren Sie bitte den HIN Support, um den Freischaltcode anzufordern. Andernfalls wird Ihnen der Freischaltcode während des geplanten Migrationstermins zur Verfügung gestellt.

1. Melden Sie sich bei der bestehenden MGW-Web-GUI an.
2. Öffnen Sie „Mail System“.
   
3. Starten Sie die Anwendung, indem Sie auf HIN_Migration-Tool_v*.exe klicken, wenn Sie die Installation selbst durchführen möchten. Alternativ können Sie bis zum Migrationstermin warten, bei dem der Support Engineer Sie bei der Installation unterstützt.
   
4. Geben Sie den Freischaltcode ein, den Ihnen der Support-Mitarbeiter mitteilt.
   
5. Wählen Sie „Export aktivieren“.
   
6. Geben Sie die MGW-IP-Adresse ein.
   
7. Warten Sie auf die Bestätigung.
   
8. Wählen Sie die vertrauenswürdige Domäne in der MGW-WebGUI aus.
   
9. Scrollen Sie nach unten und wählen Sie den verwalteten Fingerabdruck aus.
   
10. Scrollen Sie nach unten zum Abschnitt „PKCS12 download“ (optional können Sie ein Passwort zum Verschlüsseln des Schlüssels eingeben). Klicken Sie auf „Download PKCS12“ und speichern Sie die Datei *.p12 auf dem Computer.
    
11. Kehren Sie zur Anwendung HIN_Migration-Tool_v*.exe zurück und deaktivieren Sie die Schaltfläche Export.
    

Schritt 1.4 - Notfallplan / Ausweichszenario

Info

Dieser Schritt gilt nur für Einzel- und Multi-Domain-Migrationen

Rollback-Szenario - Falls ein Rollback erforderlich ist:

1. Das neue HIN Gateway anhalten.
2. Schalten Sie das bestehende MGW ein.
3. Überprüfen Sie, ob der eingehende und ausgehende E-Mail-Verkehr über das bestehende MGW korrekt funktioniert.
   • Führen Sie die Überprüfung bei einer Multi-Domain-Migration für jede Domäne durch

Schritt 1.5 - Bestehende MGW-VM abschalten

Info

Dieser Schritt gilt nur für Einzel- und Multi-Domain-Migrationen

Fahren Sie die bestehende MGW-VM herunter.

Warning

Dieser Schritt unterbricht den E-Mail-Verkehr. Während der Unterbrechung werden E-Mails auf dem Mailserver in die Warteschlange gestellt und erst nach Abschluss der Installation zugestellt (siehe „Schritt 18 - Mailserver und HIN Gateway konfigurieren“).

Schritt 2 - WireGuard

Stellen Sie sicher, dass Sie den WireGuard-Port 19818 (TCP/UDP) in Ihrer Firewall konfiguriert haben:

• Eingehender und ausgehender Datenverkehr
• Verkehr zulassen: "any-to-HIN Gateway" und "HIN Gateway-to-any"

Schritt 3 - Ziel-VM auswählen

Wählen Sie eines der verfügbaren virtuellen Images aus und richten Sie es gemäss der Installationsanleitung auf der HIN Gateway Service-Seite ein.

Info

Aus Security- und Kompatibilitätsgründen sollten Sie sicherstellen, dass Ihr Hypervisor nicht auf einer veralteten Version läuft. Die HIN Gateway Appliance wird auf der neuesten Hypervisor-Version sowie der unmittelbar vorhergehenden Major-Version unterstützt.

• Installation des VM-Images:
  • Azure-VM-Image
  • Windows 11 Pro (Hyper-V)-Image
  • VMware-Image
  • Proxmox-Image
  • Cloudscale
• Konfiguration von Microsoft Exchange

Schritt 4 - VM-Image laden

Laden Sie die ausgewählte VM auf Ihren Hypervisor hoch.

Zweite Festplatte erforderlich: die Data Disk

Die Appliance nutzt zwei Festplatten: die OS-Festplatte aus dem Image und eine separate Data Disk, die die gesamte Konfiguration, Secrets, E-Mails und Datenbanken enthält. Diese Trennung erlaubt es, das OS bei einem Image-Update zu ersetzen, ohne Ihre Daten anzurühren.

Die VMware-OVA enthält diese Festplatte bereits. Auf allen anderen Plattformen (Proxmox, Hyper-V, Azure, Cloudscale) ist das Image eine einzelne OS-Festplatte. Hängen Sie daher vor dem ersten Start eine zweite, leere Festplatte mit mindestens 30 GB an.

Formatieren oder partitionieren Sie sie nicht selbst. Beim ersten Start formatiert die Appliance die leere Festplatte (Label VEREIGN-DATA) und mountet sie unter /var/data. Ohne sie schlägt der erste Start seine Health-Prüfung fehl und wird zurückgerollt.

Schritt 5 - Netzwerkverbindung zur VM

Stellen Sie sicher, dass die VM über eine Netzwerkverbindung verfügt und ihr eine statische IP-Adresse zugewiesen wurde.

Option A: Konfigurieren Sie die IP-Adresse der VM direkt im von Ihnen verwendeten Hypervisor.

Option B: Konfigurieren Sie den DHCP-Server Ihres Routers so, dass er anhand der MAC-Adresse der VM stets dieselbe IP-Adresse zuweist.

Option C: Melden Sie sich lokal über die VM-Konsole an und konfigurieren Sie manuell eine statische IP-Adresse.

HINWEIS: Das VM-Image führt beim ersten Start eine automatische Installation durch. Wenn das Netzwerk zu diesem Zeitpunkt nicht konfiguriert ist, schlägt die Installation fehl, da die IP-Adresse des Servers nicht ermittelt werden kann.

Eine IP-Adresse unter Linux hinzufügen:

1. Führen Sie den Befehl "nmtui" in der Konsole aus.

   nmtui
   

2. Navigieren Sie mit den Pfeiltasten und drücken Sie dann "Enter", um die "Ethernet-Verbindung" auszuwählen, deren IP-Adresse Sie ändern möchten.
   

3. Navigieren Sie zu "IPv4-Konfiguration" und ändern Sie die Einstellung von "Automatisch" auf "Manuell".
   
4. Navigieren Sie mit den Pfeiltasten zu den Feldern, in denen Sie die IP-Adresse, das Gateway und den DNS-Server eingeben können. Wählen Sie anschliessend "OK".
   

5. Führen Sie nach dem Speichern der IP-Adresskonfiguration den folgenden Befehl in der Konsole aus:

   sudo systemctl restart NetworkManager
   

Cloud-init überschreibt VM-Netzwerkeinstellungen nach einem Neustart

Dies betrifft nur das Legacy-Image. Die bootc-Appliance, jetzt der Standard, verwendet kein cloud-init für die Netzwerkverwaltung, ist daher nicht betroffen und enthält die unten verwendeten cloud-init-net-*-Aliase nicht.

Auf dem Legacy-Image (typischerweise auf VMware/ESXi) hat cloud-init keine Datenquelle, fällt auf „DHCP für die erste NIC" zurück und rendert die Netzwerkkonfiguration bei jedem Boot neu, weshalb eine mit nmtui gesetzte statische Adresse nach einem Neustart zurückgesetzt wird. Ein Alias behebt dies in einem Schritt, indem er nur das Netzwerk-Rendering von cloud-init deaktiviert, sodass eine anschliessend am bestehenden Profil gesetzte Adresse erhalten bleibt:

1. Cloud-init daran hindern, das Netzwerk bei jedem Boot neu zu rendern:

   cloud-init-net-disable
   

2. Führen Sie nmtui aus, bearbeiten Sie die bestehende Verbindung cloud-init <iface> und setzen Sie dort die statische IP, das Gateway und den DNS. Fügen Sie kein zweites Profil für dieselbe Schnittstelle hinzu. Das von cloud-init hat eine höhere Autoconnect-Priorität und würde gewinnen.

   nmtui
   

3. Starten Sie neu und prüfen Sie, ob die Adresse erhalten bleibt:

   sudo reboot
   # nach dem Neustart:
   nmcli device status; ip -4 addr
   

cloud-init-net-enable stellt das standardmässige, von cloud-init verwaltete Netzwerk wieder her. Ohne den Alias ist Schritt 1 dasselbe Drop-in von Hand:

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

Tip

Wenn Sie Option C verwendet und das Netzwerk manuell konfiguriert haben, müssen Sie die folgenden Befehle ausführen:

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

Das Installationsskript ermittelt bei jedem Durchlauf automatisch die IP-Adresse des Servers anhand der Standardroute; eine manuelle Anpassung von customer-config.sh ist nicht erforderlich. Jede erreichbare IP-Adresse, ob öffentlich oder privat, ist ausreichend. Der eigentliche öffentliche Endpunkt wird später über das Dashboard konfiguriert.

Hinter NAT oder mit einer Floating IP?

Wenn Ihr Server über eine andere öffentliche oder Floating-IP erreichbar ist als über die IP seiner eigenen Netzwerkschnittstelle (häufig bei NAT), setzen Sie SERVER_STATIC_IP in customer-config.sh auf diese erreichbare IP, bevor Sie install.sh ausführen. Andernfalls lassen Sie das Feld leer, damit die IP-Adresse automatisch erkannt wird.

Nachdem die Skripte erfolgreich ausgeführt wurden, fahren Sie mit "Schritt 6 - Zugriff über den Browser" fort.

Question

Falls Sie nicht über die HIN-Admin-Zugangsdaten verfügen, wenden Sie sich bitte an den HIN Support per E-Mail oder Telefon (support@hin.ch / 0848 830 740). Siehe Support-Bereich.

Klicken Sie hier, um eine E-Mail zu senden

Schritt 6 - Zugriff über den Browser

Öffnen Sie einen Browser und geben Sie die für die VM konfigurierte IP-Adresse ein. Es sollte der Bildschirm für die Ersteinrichtung angezeigt werden.

https://<IP-Adresse der VM>

Schritt 7 - Aktivierungscode eingeben

Wählen Sie Ihre bevorzugte Sprache aus und geben Sie den Aktivierungscode ein, den Sie per E-Mail von HIN erhalten haben. Klicken Sie auf "Next".

Ich habe keinen Aktivierungscode

Falls Sie den Aktivationscode nicht haben, wenden Sie sich bitte per E-Mail oder Telefon an den HIN Support (support@hin.ch / 0848 830 740). Siehe Support-Bereich.

Klicken Sie hier, um eine E-Mail zu senden

Schritt 8 - Setup des Mesh-Netzwerks

Überprüfen Sie die Konfiguration des Mesh-Netzwerks:

• IP-Adresse - Die öffentliche IP-Adresse des ausgehenden Datenverkehrs (wird automatisch erkannt).
• Transport - Das Transportprotokoll (Standard: tcp).
• Port - Der WireGuard-Port (Standard: 19818).

Was ist eine öffentliche IP?

Dies ist eine IP-Adresse, die der Rechner verwenden wird, um über das Internet erreichbar zu sein. Es handelt sich nicht um die interne IP-Adresse des Rechners hinter einer Firewall oder NAT, z. B. 10.0.0.0/8, 172.16.0.0/12 oder 192.168.0.0/16.

Überprüfen Sie, ob die Werte korrekt sind, und klicken Sie auf "Next".

Schritt 9 - Sicheres Mesh-Netzwerk einrichten

Das System baut nun die sichere Mesh-Netzwerk-Verbindung auf. Dieser Schritt verbindet das HIN Gateway mit dem Mesh-Netzwerk und synchronisiert die Zertifikate.

Warten Sie, bis der Vorgang abgeschlossen ist. Die Statusanzeigen zeigen "Up" an, sobald die Verbindung erfolgreich hergestellt wurde. Klicken Sie auf "Finish".

Falls die Verbindung fehlschlägt

Wenn der Status von Iris Agent oder der Zertifikatssynchronisation weiterhin "Down" lautet:

• Stellen Sie sicher, dass Port 19818 (TCP/UDP) in Ihrer Firewall offen ist (siehe "Schritt 2 - WireGuard").
• Überprüfen Sie, ob die IP-Adresse unter "Schritt 8 - Setup des Mesh-Netzwerks" korrekt ist und über das Internet erreichbar ist.
• Starten Sie den Vorgang neu oder wenden Sie sich per E-Mail oder Telefon an den HIN Support (support@hin.ch / 0848 830 740).

Schritt 10 - Login bei Keycloak

Warning

Port 8180 muss für Keycloak geöffnet sein. Er muss nicht aus dem gesamten Internet erreichbar sein. Er sollte jedoch zwischen Ihrem Administrationsrechner und der VM, die Sie installieren, erreichbar sein. Andernfalls können Sie keine Verbindung zu Keycloak herstellen und die Installation nicht fortsetzen.

Was tun, wenn ein Verbindungsfehler angezeigt wird?

Bitte prüfen Sie, ob Port 8180 von Ihrem Rechner zur VM erreichbar ist. Nachdem Sie die Konfiguration aktualisiert haben, kehren Sie zur Benutzeroberfläche unter https://<VM IP address> zurück und klicken Sie auf die Schaltfläche „Login“.

Sobald das Mesh-Netzwerk eingerichtet ist, werden Sie zur Keycloak-Anmeldeseite weitergeleitet. Geben Sie den Benutzernamen und das Passwort ein, die Sie von HIN erhalten haben.

Question

Falls Sie diese Anmeldedaten nicht haben, wenden Sie sich bitte per E-Mail oder Telefon an den HIN Support (support@hin.ch / 0848 830 740). Siehe Support-Bereich.

Klicken Sie hier, um eine E-Mail zu senden

Schritt 11 - Passwort aktualisieren

Bei der ersten Anmeldung werden Sie aufgefordert, Ihr Passwort zu ändern. Geben Sie ein neues sicheres Passwort ein und bestätigen Sie es.

Bitte stellen Sie sicher, dass Sie sich das Passwort merken!

Schritt 12 - Kontoinformationen aktualisieren

Vervollständigen Sie Ihr Kontoprofil, indem Sie Ihren Vornamen und Nachnamen eingeben. Die E-Mail-Adresse ist bereits vorausgefüllt. Klicken Sie auf "Submit", um fortzufahren.

Schritt 13 - Erstkonfiguration und Einrichten der Domäne

Info

Führen Sie den Vorgang bei einer Multi-Domain-Migration für jede Domäne durch, die Sie gerade aktivieren.

Konfigurieren Sie auf diesem Bildschirm Ihre Grundeinstellungen:

• Überprüfen Sie, ob alle Ihre aktuellen vertrauenswürdigen Domänen innerhalb der HIN Community korrekt angezeigt werden.
• Wählen Sie aus, welche vertrauenswürdigen Domänen "Enabled" sein sollen, um Peer-Zertifikate von der HIN Zertifizierungsstelle (HIN CA) zu erhalten.
• Geben Sie an, für welche Domäne(n) das Präfix "sec.\<domain>" bereits konfiguriert ist ("Use sec-prefix").

Wie kann ich prüfen, ob meine Domain mit einem Security Prefix eingerichtet ist?

Öffnen Sie unser Online-Tool im Browser: https://trust.hin.ls-infra.me/, geben Sie sec.<domain> ein und klicken Sie auf die Schaltfläche Check. Wenn folgende Meldung angezeigt wird:

✅ Diese Domain ist verschlüsselt.

Dann ist Ihre Domain mit einem Security Prefix eingerichtet und Sie müssen die Option Use sec-prefix aktivieren.

• Überprüfen Sie, ob der Organisationsname und die Domain-Inhaber korrekt sind.
  
  
• Importieren Sie die vorhandene S/MIME-Zertifikatsdatei (.p12/.pfx) vom bestehenden MGW:
  1. Erweitern Sie die Domäne und wählen Sie die Option P12/PFX File.
  2. Falls für die Zertifikatsdatei kein Passwort festgelegt wurde, lassen Sie das Passwortfeld leer.
  3. Klicken Sie auf "Import Certificate".
  4. Nachdem das Zertifikat importiert wurde, wird die Meldung Certificate imported successfully angezeigt.
• Klicken Sie am Ende der Seite auf "Save Configuration", um die Änderungen zu speichern.

Warning

• Mindestens eine Domain muss Enabled sein, um mit dem Onboarding-Prozess fortzufahren. Die Schaltfläche "Save configuration" wird erst aktiv, wenn diese Voraussetzung erfüllt ist.
• Sollten Sie feststellen, dass nicht alle vertrauenswürdigen Domains angezeigt werden oder die Organisationsangaben falsch sind, wenden Sie sich bitte per E-Mail oder Telefon an den HIN Support (support@hin.ch / 0848 830 740).

Importieren Sie Ihren bestehenden privaten Schlüssel

Hinweis: gilt nur für das Migrationsszenario!

Wenn Sie den privaten Schlüssel nicht von Ihrem bestehenden MGW importieren, wird ein neuer Schlüssel ausgestellt. Dies kann dazu führen, dass Nachrichten bis zu 6 Stunden lang nicht entschlüsselt werden können, was zu Datenverlust führen könnte.

Einstellung	Beschreibung
Hostname des Mail-Servers	Der FQDN dieser Mail-Gateway-Instanz (z. B. mail.example.com).
IP-Adressen des Mail-Servers	Die öffentliche(n) IP-Adresse(n) dieses Servers. Fügen Sie weitere IP-Adressen hinzu, falls der Server über mehrere Adressen erreichbar ist.
DNS	DNS des Hosts, der zur Auflösung von MX- und anderen DNS-Einträgen verwendet wird.

Migrationsszenario für schrittweise Multi-Domain-Migration

Während der Migrations-Support-Sitzung unterstützen HIN-Ingenieure den Kunden bei der Migration einer Domain. Sobald die erste Domain erfolgreich migriert wurde, ist der Kunde selbst dafür verantwortlich, alle verbleibenden Domains eigenständig zu migrieren.

Schritt 14 - E-Mail-Transport konfigurieren

Sie werden zum HIN-Gateway-Dashboard auf der Seite Domains angemeldet.

Seite "Domains"

Info

Führen Sie den Vorgang bei einer Multi-Domain-Migration für jede aktive Domäne durch.

Im Menü Domains können Sie für jede verfügbare Domäne eine spezifische Transportroute konfigurieren:

Einstellung	Beschreibung
Inbound relay	Der SMTP-Relay für die eingehende Zustellung der ausgewählten Domäne.
Outbound relay	Der SMTP-Relay für die ausgehende Zustellung der ausgewählten Domäne. Diese Einstellung entspricht der Einstellung Forwarding server des alten MGW.
Trusted networks	Zusätzliche Netzwerke, denen die Weiterleitung über dieses Gateway gestattet ist. Weitere Informationen finden Sie unter "Schritt 18 - Mailserver konfigurieren".
Configure TLS	TLS-Zertifikateinstellungen für SMTP-Verbindungen; über die Schaltfläche Generate TLS certificate können Sie ein TLS-Zertifikat erzeugen.
Email authentication	Alle Einstellungen unter dem Abschnitt Email authentication sind im Abschnitt Email authentication (DKIM ARC SPF DMARC) beschrieben.

Wie testet man eine TLS-Verbindung?

Sie können jederzeit testen, ob das konfigurierte TLS-Zertifikat auf Ihre Verbindung zum HIN Gateway angewendet wurde. Führen Sie den folgenden Befehl direkt im Terminal des HIN Gateways aus:

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

Oder direkt auf Ihrem lokalen Rechner:

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

In der Ausgabe sehen Sie alle Daten zu Ihrer TLS-Verbindung und zum verwendeten Zertifikat.

Wie konvertiert man ein pfx- in ein pem-TLS-Zertifikat?

Verwenden Sie den folgenden openssl-Befehl:

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

Z. B.:

openssl pkcs12 -in certificate.pfx -out keyStore.pem -nodes
# Manchmal müssen Sie bei Systemen mit älteren Zertifikatsgeneratoren das Argument -legacy hinzufügen
openssl pkcs12 -in certificate.pfx -out keyStore.pem -nodes -legacy

Weitere Aktionen:

• Fügen Sie bei Bedarf weitere Domains hinzu, indem Sie auf "Add domain" klicken.
  • Ist eine Domäne nicht HIN-gesichert, erscheint sie in der Liste Domains mit dem Typ "Routed", das heisst, sie kann nur lokal verwaltet werden.

Note

Stellen Sie sicher, dass alle Konfigurationen für Relay-Hosts und Domains korrekt sind, bevor Sie fortfahren.

Sobald die Konfiguration überprüft und abgeschlossen ist, klicken Sie auf "Save", um fortzufahren.

Seite "Settings"

Konfigurieren Sie auf dieser Seite im Menü Settings Ihre globalen E-Mail-Transporteinstellungen für die sichere Mail-Relay-Einrichtung, die für die gesamte Instanz gelten. Die detaillierte Konfiguration für jede Domäne erfolgt unter Domains → $domain.

Die folgenden Einstellungen stehen im Menü Settings zur Verfügung:

Einstellung	Beschreibung
Mail server host name	Der FQDN dieser Mail-Gateway-Instanz (z. B. mail.example.com).
Mail server IP addresses	Die öffentliche(n) IP-Adresse(n) dieses Servers. Fügen Sie weitere IP-Adressen hinzu, falls der Server über mehrere Adressen erreichbar ist.
DNS	DNS des Hosts, der zur Auflösung von MX- und anderen DNS-Einträgen verwendet wird.
Default inbound relay	Der Standard-SMTP-Relay für die eingehende Zustellung.
Default outbound relay	Der Standard-SMTP-Relay für die ausgehende Zustellung.

Schritt 15 - Whitelist-Header konfigurieren

Info

Führen Sie den Vorgang bei Multi-Domain-Konfigurationen für jede aktive Domäne durch.

Klicken Sie auf "Domains" und wählen Sie anschliessend "Whitelist headers" aus.

Geben Sie den Schlüssel genau so ein, wie er auf dem Mailserver konfiguriert ist.

Schritt 16 - Peer-Zertifikate

Peer-Zertifikate werden von der HIN Zertifizierungsstelle (HIN CA) für aktivierte Domains ausgestellt.

Sobald das Onboarding abgeschlossen ist, navigieren Sie im Dashboard zum Abschnitt "Peer certificates" und klicken Sie auf die Schaltfläche "Sync certificates", um Ihre Peer-Zertifikate von der HIN CA zu synchronisieren.

Schritt 17 - Peer-Zertifikate validieren

Stellen Sie sicher, dass Ihre Domain ihr richtlinienbasiertes Peer-Zertifikat unter "Domains" erhalten hat. Der Status jeder Domäne muss "Good" lauten.

Question

Wenden Sie sich bei Problemen per E-Mail oder Telefon an den HIN Support (support@hin.ch / 0848 830 740).

Schritt 18 - Mailserver und HIN Gateway konfigurieren

Wenn Sie die empfohlene Vorgehensweise befolgt haben, d. h. den privaten Schlüssel exportiert, ihn in das HIN Gateway importiert und dieselbe IP-Adresse wie beim bestehenden MGW beibehalten haben, sind auf dem E-Mail-Server keine Änderungen erforderlich.

Andernfalls konfigurieren Sie Ihren Mailserver oder die zugehörigen Komponenten so, dass der Datenverkehr über das neue HIN Gateway geleitet wird. Überprüfen Sie die folgenden Einstellungen und passen Sie diese gegebenenfalls an:

E-Mail-Server

• SMTP-Relay / Smart Host
• Konnektoren
• Transportregeln
• Routing-Domänen

Siehe Exchange-Integration für detaillierte Anweisungen.

Konfiguration HIN Gateway

Seite "Domains"

Info

Führen Sie den Vorgang bei einer Multi-Domain-Migration für jede aktive Domäne durch.

Im Menü Domains können Sie für jede verfügbare Domäne eine spezifische Transportroute konfigurieren:

Einstellung	Beschreibung
Inbound relay	Der SMTP-Relay für die eingehende Zustellung der ausgewählten Domäne.
Outbound relay	Der SMTP-Relay für die ausgehende Zustellung der ausgewählten Domäne. Diese Einstellung entspricht der Einstellung Forwarding server des alten MGW.
Trusted networks	Zusätzliche Netzwerke, denen die Weiterleitung über dieses Gateway gestattet ist. Weitere Informationen finden Sie unter "Schritt 18 - Mailserver konfigurieren".
Configure TLS	TLS-Zertifikateinstellungen für SMTP-Verbindungen; über die Schaltfläche Generate TLS certificate können Sie ein TLS-Zertifikat erzeugen.
Email authentication	Alle Einstellungen unter dem Abschnitt Email authentication sind im Abschnitt Email authentication (DKIM ARC SPF DMARC) beschrieben.

• Hinweis für das Migrationsszenario: Gehen Sie auf die Seite jeder Domäne und fügen Sie einen Outbound host hinzu, wobei Sie den Wert verwenden, den Sie vom MGW unter Forwarding server in "Schritt 1.2 - Sichern des bestehenden MGWs" notiert haben.

• Wenn Sie Microsoft 365 / Exchange Online verwenden, fügen Sie die veröffentlichten ausgehenden IP-Adressbereiche unter Trusted networks hinzu, damit das HIN Gateway E-Mails aus Exchange Online als vertrauenswürdig einstuft und weiterleitet:

  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
  

Seite "Settings"

Konfigurieren Sie auf dieser Seite im Menü Settings Ihre globalen E-Mail-Transporteinstellungen für die sichere Mail-Relay-Einrichtung, die für die gesamte Instanz gelten. Die detaillierte Konfiguration für jede Domäne erfolgt unter Domains → $domain.

Die folgenden Einstellungen stehen im Menü Settings zur Verfügung:

Einstellung	Beschreibung
Mail server host name	Der FQDN dieser Mail-Gateway-Instanz (z. B. mail.example.com).
Mail server IP addresses	Die öffentliche(n) IP-Adresse(n) dieses Servers. Fügen Sie weitere IP-Adressen hinzu, falls der Server über mehrere Adressen erreichbar ist.
DNS	DNS des Hosts, der zur Auflösung von MX- und anderen DNS-Einträgen verwendet wird.
Default inbound relay	Der Standard-SMTP-Relay für die eingehende Zustellung.
Default outbound relay	Der Standard-SMTP-Relay für die ausgehende Zustellung.

Schritt 19 - Test und Validierung

Ausgehend:

• Stellen Sie sicher, dass der Mailserver so konfiguriert ist, dass er E-Mails über ein SMTP-Relay oder einen Exchange-Konnektor an das HIN Gateway versendet.
• Stellen Sie sicher, dass das HIN Gateway E-Mails an Empfänger ausserhalb der HIN Community versenden kann.
• Stellen Sie sicher, dass das HIN Gateway E-Mails über WireGuard an Empfänger innerhalb der HIN Community senden kann.
• Senden Sie eine E-Mail aus der HIN Community an eine externe E-Mail-Adresse (zum Beispiel Bluewin, Gmail, Yahoo oder GMX) mit dem Vermerk (vertraulich) in der Betreffzeile und überprüfen Sie, ob sie erfolgreich zugestellt wird.

Eingehender Verkehr:

• Stellen Sie sicher, dass verschlüsselte E-Mails aus der HIN Community über WireGuard empfangen werden können. Ein Absender aus der Domäne hin.ch ist der einfachste Testweg.
• Stellen Sie sicher, dass verschlüsselte E-Mails aus der HIN Community über SMTP unter Verwendung von S/MIME empfangen werden können.
• Stellen Sie sicher, dass Antworten von Absendern ausserhalb der HIN Community auf eine erste sichere E-Mail (HIN Mail-SEAL) das HIN Gateway erreichen können.
• Stellen Sie sicher, dass unverschlüsselte E-Mails von externen Absendern ausserhalb der HIN Community empfangen werden können.
• Senden Sie eine E-Mail von einer externen E-Mail-Adresse an die HIN Community und überprüfen Sie, ob sie erfolgreich empfangen wird.

Bestätigen:

• E-Mails werden in beide Richtungen zwischen der vertrauenswürdigen HIN-Domain und externen E-Mail-Adressen erfolgreich zugestellt.
• Verschlüsselung wird angewendet, wo erforderlich.
• Es treten keine unerwarteten Verzögerungen oder Bounces auf.
• Die Protokollierung ist erfolgreich.

Füllen Sie das Abnahmeprotokoll aus und senden Sie es an Ihren HIN Ansprechpartner zurück.

Schritt 20 - Passwort der VM ändern

Bitte stellen Sie sicher, dass die Ihnen ursprünglich zur Verfügung gestellten Zugangsdaten für die VM in ein von Ihnen selbst festgelegtes Passwort geändert werden, und bewahren Sie dieses an einem sicheren und geschützten Ort auf.

Schritt 21 - Bestehendes MGW ausser Betrieb nehmen

Info

Dieser Schritt gilt nur für Einzel- und Multi-Domain-Migrationen

Warning

Löschen Sie die bestehende MGW-VM nicht sofort, sondern bewahren Sie sie sicher auf, bis alles betriebsbereit ist.

1. Stellen Sie sicher, dass kein aktiver Datenverkehr vorhanden ist: Überprüfen Sie:
   • Es verweisen keine Domains auf das MGW (DNS, SMTP, Konnektoren).
   • Es werden keine E-Mails über die alte Appliance weitergeleitet.
2. Protokolle archivieren: Exportieren und speichern Sie:
   • E-Mail-Protokolle
   • Sicherheits-/Audit-Protokolle
   • erforderlich für Compliance und Fehlerbehebung
3. Bereinigung (optional): Entfernen Sie:
   • Firewall-Regeln
   • DNS-Einträge
   • Routing-Konfigurationen, die auf das bestehende MGW verweisen

Anhang 1 - Sichern und Wiederherstellen der Appliance-Einstellungen

Info

Dieser Schritt gilt nur für Einzel- und Multi-Domain-Migrationen

Um die Einstellungen Ihrer HIN Appliance zu sichern oder wiederherzustellen, klicken Sie im Web-Verwaltungsportal auf das Menü "Administration".

Einstellungen sichern

Bevor Sie ein Backup der aktuellen HIN Geräteeinstellungen erstellen, müssen Sie ein Backup-Passwort festlegen. Dieses Passwort wird benötigt, falls Sie das Backup später wiederherstellen müssen.

• Um das Sicherungskennwort festzulegen oder zu ändern, klicken Sie auf "Change Password".
• Um eine Sicherungsdatei zu erstellen und herunterzuladen, klicken Sie auf "Download".

Sicherungspasswort ändern

Um das Passwort für zukünftige Sicherungen zu ändern, klicken Sie auf "Change Password".

Note

Bitte beachten Sie, dass das neue Passwort nur für Sicherungen gilt, die nach der Passwortänderung erstellt werden. Bestehende Sicherungsdateien bleiben durch das Passwort geschützt, das bei ihrer Erstellung festgelegt wurde.

Einstellungen wiederherstellen

Um die Geräteeinstellungen aus einer Sicherungsdatei wiederherzustellen, klicken Sie auf "Importieren Backup File...".

Wählen Sie im Dialogfenster die gewünschte Sicherungsdatei aus und geben Sie das zu dieser Sicherung gehörige Passwort ein. Die Geräteeinstellungen werden anschliessend aus der ausgewählten Sicherungsdatei wiederhergestellt.

Sicherung über SCP

Das MGW unterstützt die Sicherung des Geräts über SCP.

Um diese Option zu nutzen, muss der öffentliche Schlüssel des Systems, das auf den MGW zugreifen soll, unter "Backup using SCP" hinterlegt sein. Die Sicherungsdatei wird täglich um Mitternacht automatisch erstellt und auf dem MGW als backup.tgz gespeichert.

Mit dem konfigurierten öffentlichen Schlüssel kann die Sicherungsdatei über SCP mit dem Betriebssystembenutzer backup abgerufen werden. Ein typischer SCP-Befehl zum Abrufen der Sicherungsdatei lautet:

scp backup@192.168.1.60:/backup.tgz .

Dieser Befehl lädt die Datei backup.tgz vom MGW in das aktuelle lokale Verzeichnis herunter.

Note

Wenn Sie einen neuen öffentlichen Schlüssel eingeben, wird der bestehende Schlüssel ersetzt.

Szenario für die Migration mehrerer Domains

MGW → HIN Gateway – Architektur des E-Mail-Flusses, schrittweiser Umzug und Rollback-Plan

Phase 1 Start – Ausgangslage (alle Domains auf MGW)

Ausgangszustand

• Alle Domains werden über das MGW weitergeleitet. Beispiel: domain1.ch, domain2.ch, domain3.ch, un-domain1.ch, un-domain2.ch
• Vorbereitungen für die Inbetriebnahme des HIN Gateways – noch kein Live-Verkehr
• DNS-MX-/SPF-Einträge werden weiterhin auf Public IP A (MGW) aufgelöst – dies gilt für den Fall, dass das MGW der nach aussen gerichtete Datenverkehr oder der letzte MTA ist

Checkliste vor der Migration

• Baseline: aktuelle MGW-Kapazität und E-Mail-Verlaufsprotokolle
• Verbindung von Stargate Lab zu Online Protect / Exchange Online / dem lokalen E-Mail-Server überprüfen
• Beteiligte über Migrationszeitplan und Kommunikationsplan informieren
• Dokumentation zu Firewall und Ports vor der Bereitstellung der öffentlichen IP B (Phase 2, Schritt 1) überprüfen

Phase 2 Migration – schrittweise, eine Domain nach der anderen

Migrationsschritte

1. Einrichtung des HIN Gateways – Public IP B zuweisen und Firewall-Regeln anpassen (die erforderlichen Ports sind der Netzwerkdokumentation zu entnehmen)
2. Erstellen Sie zwei Konnektoren in Exchange Online – einen für eingehenden und einen für ausgehenden Datenverkehr –, die auf Stargate verweisen
3. Fügen Sie eine E-Mail-Fluss-Regel hinzu, die nach Domain weiterleitet: domain1.ch → HIN Gateway, alle übrigen Domains bleiben auf dem MGW
4. Schrittweise wiederholen – jeweils eine weitere Domain umstellen, bis alle Domains auf dem HIN Gateway laufen

Rollback (pro Domain)

• E-Mail-Fluss-Regel der betroffenen Domain wieder auf das MGW richten
• Stargate-Konnektoren für den nächsten Versuch belassen
• Chronologisches Änderungsprotokoll über jede Änderung an Konnektoren und Regeln führen – beim Rollback muss der Prozess in umgekehrter Reihenfolge wiederholt werden

Achten Sie auf kundenspezifische Header

Einige Domains nutzen benutzerdefinierte X-Header (Routing, Anti-Spam-Whitelists, Compliance-Tags). Vergewissern Sie sich, dass die Stargate-Konnektoren diese Header beibehalten bzw. replizieren, bevor Sie eine Domain umstellen – fehlende Header können zu Fehlweiterleitungen oder abgelehnten E-Mails führen.

Phase 3 Abschluss – vollständige Migration zum HIN Gateway

Endzustand

• Alle Domains werden nun über das HIN Gateway geleitet
• MGW überträgt keinen Produktionsverkehr
• DNS/SPF verweisen nun auf Public IP B (für den Fall, dass das HIN Gateway der nach aussen gerichtete Verkehr oder der letzte MTA ist)

Checkliste für die Bereinigung

• Alte MGW-Konnektoren und E-Mail-Fluss-Regeln entfernen
• MGW-VM ausser Betrieb nehmen, sobald die Überwachung bestätigt, dass kein Datenverkehr mehr vorhanden ist und der E-Mail-Fluss ordnungsgemäss funktioniert
• Public IP A freigeben, falls sie nicht mehr benötigt wird
• Runbooks und DNS-Dokumentation aktualisieren

Vergleich von Migrationsstrategien

Empfohlen – alle Domains auf einmal umziehen

• Keine zusätzliche Public IP erforderlich
• Keine vorübergehenden Änderungen an Konnektoren oder E-Mail-Fluss-Regeln
• Einfaches Rollback: Stargate ausschalten, alte MGW-VM wieder einschalten
• Kürzestes Umstellungsfenster – geringste Wahrscheinlichkeit von Konfigurationsabweichungen

Alternative – schrittweise, eine Domain nach der anderen

• Geringere Auswirkungen pro Schritt – jeweils nur eine Domain ist gefährdet
• Erfordert eine zweite Public IP sowie temporäre Aufteilungsregeln und Konnektoren
• Kundenspezifische Header müssen pro Domain berücksichtigt werden
• Für ein Rollback muss die genaue Änderungssequenz in umgekehrter Reihenfolge wiederholt werden

---

Warning

Überprüfen Sie vor der Durchführung jeglicher Installationsschritte die genauen Firewall-Ports und Konnektoren-Einstellungen anhand der aktuellen Netzwerkdokumentation.

Note

Beachten Sie die spezifischen Anmerkungen zur Migration mehrerer Domains im Installationshandbuch für Domains.

Technische Konfiguration und Integration

Anwendungsübersicht

Anwendungen

• smimekeys-client – S/MIME-Schlüssel-Client-Dienst (Port 8081)
• policy – Policy-Dienst (Port 8082)
• irisagent – IRIS-Agent-Dienst (Port 8083, WireGuard: 19818/udp, 19818/tcp)
• mxengine – MX-Engine-Dienst (Port 8084, SMTP: 1587)
• stalwart – Stalwart-MTA-Mailserver (Port 25, 10026)
• clamav – ClamAV-Antivirus; scannt E-Mails in der SMTP-DATA-Phase von Stalwart über das Milter-Protokoll (Port 7357)
• mtaconf – MTA-Konfigurations-Daemon (API: 8080)
• dashboard – Webbasierte Admin-UI für Onboarding, Domainverwaltung und Überwachung (Port 443)
• policy-sync – Synchronisiert OPA/Rego-Richtlinien aus dem Git-Repository mit der Datenbank (läuft kontinuierlich)

Infrastruktur

• PostgreSQL – Datenbank (Port 5432)
• Vault – Secrets-Verwaltung (interner Port 8200, nicht an den Host veröffentlicht)
• MinIO – S3-kompatibler Speicher (API auf Host-Port 9000; Konsole nicht an den Host veröffentlicht)
• Keycloak – Identitätsanbieter und OIDC-Authentifizierung (Port 8180)
• APISIX – API-Gateway mit OIDC-Bearer-Authentifizierung (Port 9080)
• NATS – Inter-Service-Messaging (löst Stalwart-Neuladungen vom Dashboard aus)

Init-Container

• vault-init – Initialisiert und entsiegelt Vault beim ersten Start
• seaweedfs-init – Erstellt den S3-Bucket
• apisix-init – Generiert die APISIX-Konfiguration aus der Vorlage
• keycloak-init – Setzt das anfängliche Admin-Passwort

Überwachung

• node-exporter – Host-Metriken für Prometheus (Port 9100)
• version-collector – Sammelt App-Versionen von /liveness-Endpunkten für node-exporter
• Alloy – Log-Sammler für Loki (sendet App-Logs)
• Dozzle – Echtzeit-Container-Log-Viewer (Port 8190, HTTPS, hinter Keycloak-SSO via oauth2-proxy; optional, aktiviert mit DOZZLE_ENABLED)
• oauth2-proxy – OIDC-Relying-Party, die den Dozzle-Zugriff gegen Keycloak authentifiziert (startet zusammen mit Dozzle)

Siehe Überwachung und Logs für detaillierte Konfiguration und Nutzung.

Architekturübersicht

VM-Architekturübersicht

Überwachung und Logs

Stargate enthält integrierte Überwachungs- und Log-Sammeldienste, die neben den Anwendungscontainern laufen.

Komponenten

Dienst	Port	Zweck
node-exporter	9100	Host-Metriken (CPU, Speicher, Festplatte, Netzwerk) für Prometheus
version-collector	-	Sammelt App-Versionen von /liveness-Endpunkten
Alloy	12345	Docker-Log-Sammler – sendet Container-Logs an Loki
Loki	3100 (intern)	Lokales Log-Aggregations-Backend
Dozzle	8190	Webbasierter Container-Log-Viewer (HTTPS, Keycloak-SSO; optional)
oauth2-proxy	8190	OIDC-Relying-Party, die den Dozzle-Zugriff authentifiziert (mit Dozzle)

---

Dozzle – Lokaler Log-Viewer

Dozzle bietet eine webbasierte Benutzeroberfläche zum Anzeigen von Echtzeit-Logs aller Stargate-Container. Es ist optional und wird durch Setzen von DOZZLE_ENABLED="true" in customer-config.sh aktiviert.

Der Zugriff wird durch Keycloak geschützt: Ein oauth2-proxy sitzt vor Dozzle und erfordert dieselbe Anmeldung wie das Dashboard (die stargate-Realm). Dozzle selbst wird nicht direkt exponiert.

Zugriff: Öffnen Sie https://<SERVER_IP>:8190 in einem Browser und melden Sie sich mit Ihren HIN-Gateway (Keycloak)-Anmeldeinformationen an.

Note

Port 8190 (HTTPS) muss von Ihrem Netzwerk aus erreichbar sein. Wenn Sie den Zugriff nach IP oder Firewall einschränken, erlauben Sie 8190/tcp wie für das Dashboard und Keycloak.

Logs sind nach Dienst organisiert. Durch Auswahl eines bestimmten Dienstes können Sie die entsprechenden Logeinträge und Details anzeigen.

---

Grafana Alloy – Log-Weiterleitung

Grafana Alloy sammelt Logs von allen Stargate-Anwendungscontainern und schreibt sie in die lokale Loki-Instanz. Optional können Logs auch an einen entfernten Loki-kompatiblen Endpunkt für die zentralisierte Überwachung weitergeleitet werden.

Wie es funktioniert

1. Alloy entdeckt Stargate-Container über den Docker-Socket
2. Logs werden immer in die lokale Loki-Instanz geschrieben (vom Dashboard für den Log-Export verwendet)
3. Wenn eine entfernte Loki-URL konfiguriert ist, werden Logs zusätzlich an diesen Endpunkt weitergeleitet

Konfiguration der entfernten Log-Weiterleitung

Navigieren Sie im HIN-Gateway-Dashboard zur Seite Einstellungen. Geben Sie im Abschnitt Grafana Alloy die Loki-Push-URL Ihres entfernten Log-Sammlerservers ein:

Die URL sollte dem Standard-Loki-Push-API-Format folgen:

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

Lassen Sie das Feld leer, um die entfernte Log-Weiterleitung zu deaktivieren.

Note

Änderungen werden innerhalb von 1 Minute wirksam (Alloy fragt die Dashboard-Konfiguration in diesem Intervall ab). Kein Container-Neustart ist erforderlich.

Anforderungen auf der entfernten Seite

Ihr entfernter Loki-Endpunkt muss vom Stargate-Server über HTTPS (Port 443) erreichbar sein. Wenn Sie IP-basierte Allowlists auf Ihrem Ingress verwenden, fügen Sie die öffentliche IP des Stargate-Servers hinzu.

---

Prometheus-Metriken

Stargate stellt Prometheus-kompatible Metrik-Endpunkte von seinen Anwendungscontainern bereit. Diese können von jedem Prometheus-kompatiblen Server für die zentralisierte Metrik-Sammlung abgerufen werden.

Verfügbare Endpunkte

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

Scrape-Konfiguration

Fügen Sie den Stargate-Server als Ziel in Ihrer Prometheus-Konfiguration hinzu. Beispiel für eine einzelne Instanz:

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

Ersetzen Sie <STARGATE_IP> durch die öffentliche oder private IP des Servers und <name> durch einen Bereitstellungsbezeichner (z.B. prod, customer-name).

Tip

Die Labels environment und service ermöglichen das Filtern in Grafana-Dashboards über mehrere Stargate-Instanzen hinweg.

Firewall-Anforderungen

Die Metrik-Ports (2113-2116, 9100) müssen von Ihrem Prometheus-Server aus erreichbar sein. Wenn Sie den Zugriff nach IP einschränken, fügen Sie die IP Ihres Überwachungsservers zu den Firewall-Regeln hinzu.

---

Node Exporter

Der node-exporter-Dienst stellt standardmäßige Host-Metriken (CPU, Speicher, Festplatten-I/O, Netzwerk) auf Port 9100 bereit. Er enthält auch einen Textfile-Collector, der benutzerdefinierte Metriken vom version-collector-Sidecar (Anwendungsversionsinformationen) bereitstellt.

---

Zusammenfassung der exponierten Ports

Port	Dienst	Protokoll	Zweck
8190	Dozzle (via oauth2-proxy)	HTTPS	Authentifizierter Log-Viewer-UI (Keycloak-SSO)
9100	node-exporter	HTTP	Host-Metriken (Prometheus)
2113	smimekeys-client	HTTP	App-Metriken (Prometheus)
2114	irisagent	HTTP	App-Metriken (Prometheus)
2115	policy	HTTP	App-Metriken (Prometheus)
2116	mxengine	HTTP	App-Metriken (Prometheus)
9091	APISIX	HTTP	Gateway-Metriken (Prometheus)

Exchange-Integration mit Stargate

Dieser Leitfaden erklärt, wie Sie Microsoft Exchange (Online und On-Premises) konfigurieren, um E-Mails über das Stargate-Gateway für S/MIME-Signatur und -Verschlüsselung zu leiten.

Übersicht

Stargate fungiert als Mail-Relay zwischen externen Mailservern und Ihrer Exchange-Umgebung. Es werden zwei Integrationsmuster unterstützt:

Muster A – Exchange Online als primärer MX mit Transportregeln:

flowchart LR
    I1 --> EO --> TR --> C --> S1 --> EO
    E2 --> TR2 --> OC --> S2 --> I2
    I1["Internet"]
    I2["Internet"]
    EO["Exchange Online"]
    E2["Exchange Online"]
    TR["Transportregel"]
    TR2["Transportregel"]
    OC["Ausgehender Connector"]
    C["Connector"]
    S1["Stargate"]
    S2["Stargate"]

Muster B – Stargate als primärer MX:

flowchart LR
    I1 --> mx15 --> mx20
    EO --> TR --> OC --> Stargate --> I2
    I1["Internet"]
    I2["Internet"]
    mx15["Stargate (MX-Priorität 15)"]
    mx20["Exchange Online (MX-Priorität 20)"]
    EO["Exchange Online"]
    TR["Transportregel"]
    OC["Ausgehender Connector"]
    Stargate

In beiden Mustern benötigen Sie:

1. DNS-Einträge, die auf den Stargate-Server verweisen
2. Ausgehenden Connector – leitet E-Mails von Exchange an Stargate weiter
3. Eingehenden Connector – akzeptiert E-Mails von Stargate in Exchange
4. Transportregel – löst den ausgehenden Connector für externe Empfänger aus

Voraussetzungen

Stellen Sie vor der Konfiguration von Exchange Folgendes sicher:

• Stargate ist installiert und läuft (Bereitstellungsanleitung)
• Sie haben die öffentliche IP-Adresse des Stargate-Servers (im Folgenden als <STARGATE_IP> bezeichnet)
• Sie haben den Mail-Hostnamen des Stargate-Servers (im Folgenden als <MAIL_HOSTNAME> bezeichnet, z.B. mail.example.com)
• Sie kennen Ihre Mail-Domain (im Folgenden als <YOUR_DOMAIN> bezeichnet, z.B. example.com)
• Sie haben Exchange-Admin-Zugriff (Exchange Admin Center oder On-Premises Exchange Management Shell)
• DNS-Einträge sind gemäß dem DNS-Einrichtungsleitfaden konfiguriert (A, MX, SPF mindestens)

---

Teil 1: DNS-Einrichtung

Siehe den DNS-Einrichtungsleitfaden für vollständige Anweisungen zur Konfiguration von A-, MX-, SPF-, PTR-, DMARC- und DKIM-Einträgen.

Vor der Fortsetzung mit der untenstehenden Exchange-Konfiguration benötigen Sie mindestens:

• A-Eintrag: <MAIL_HOSTNAME> verweist auf <STARGATE_IP>
• MX-Eintrag: <YOUR_DOMAIN> mit Stargate bei höherer Priorität (niedrigere Zahl) als Exchange
• SPF-Eintrag: ip4:<STARGATE_IP> und ip4:<HIN_SEALER_IP> wurden zum TXT-Eintrag Ihrer Domain hinzugefügt (siehe DNS-Einrichtungsleitfaden - SPF für Sealer-IPs)

---

Teil 2: Exchange Online-Konfiguration

Schritt A: Den ausgehenden Connector erstellen (Office 365 → Stargate)

Dieser Connector leitet ausgehende E-Mails von Exchange Online an den Stargate-Relay-Server weiter.

1. Navigieren Sie zum Exchange Admin Center - Connectors

2. Klicken Sie auf "+ Connector hinzufügen"

3. Verbindung von: Wählen Sie "Office 365"

4. Verbindung zu: Wählen Sie "E-Mail-Server Ihrer Organisation"

5. Klicken Sie auf "Weiter"

6. Connectorname: Geben Sie einen beschreibenden Namen ein, z.B.:

Von Office 365 zum Stargate-Relay-Server

• Aktivieren Sie "Interne Exchange-E-Mail-Header beibehalten"

• Klicken Sie auf "Weiter"

• Verwendung des Connectors: Wählen Sie "Nur wenn ich eine Transportregel eingerichtet habe, die Nachrichten an diesen Connector weiterleitet"

• Klicken Sie auf "Weiter"

Tip

Dies ist wichtig – der Connector leitet keine E-Mails von selbst weiter. Er wird nur verwendet, wenn er durch die in Schritt C erstellte Transportregel ausgelöst wird.

1. Routing: Wählen Sie "E-Mails über diese Smart Hosts leiten"
2. Geben Sie die Stargate-Server-IP-Adresse ein: <STARGATE_IP>

3. Klicken Sie auf "+" zum Hinzufügen und dann auf "Weiter"

4. Sicherheitseinschränkungen: Wählen Sie "Beliebiges digitales Zertifikat, einschließlich selbstsignierter Zertifikate"

5. Klicken Sie auf "Weiter"

Note

Der MTA von Stargate (Stalwart) akzeptiert opportunistisches TLS bei eingehenden Verbindungen. Die Auswahl von "beliebigem digitalen Zertifikat" stellt die Konnektivität auch mit selbstsignierten Zertifikaten sicher.

1. Überprüfungs-E-Mail: Geben Sie eine gültige E-Mail-Adresse für Ihre Domain ein (z.B. user@<YOUR_DOMAIN>)
2. Klicken Sie auf "+" und dann auf "Überprüfen"
3. Warten Sie, bis die Überprüfung abgeschlossen ist, und klicken Sie dann auf "Weiter"

Tip

Damit die Überprüfung erfolgreich ist, muss der Stargate-Server laufen und E-Mails auf Port 25 annehmen.

1. Überprüfen Sie die Einstellungen und klicken Sie auf "Connector erstellen"

2. Klicken Sie auf dem Bestätigungsbildschirm auf "Fertig"

Schritt B: Den eingehenden Connector erstellen (Stargate → Office 365)

Dieser Connector akzeptiert E-Mails vom Stargate-Relay-Server in Exchange Online.

1. Klicken Sie auf der Connectors-Seite auf "+ Connector hinzufügen"

2. Verbindung von: Wählen Sie "E-Mail-Server Ihrer Organisation"

3. Verbindung zu: Zeigt "Office 365" an (automatisch)

4. Klicken Sie auf "Weiter"

5. Connectorname: Geben Sie einen beschreibenden Namen ein, z.B.:

E-Mails vom Stargate-Relay-Server empfangen

• Aktivieren Sie "Interne Exchange-E-Mail-Header beibehalten"

• Klicken Sie auf "Weiter"

• Authentifizierung gesendeter E-Mails: Wählen Sie "Durch Überprüfen, ob die IP-Adresse des sendenden Servers mit einer der folgenden IP-Adressen übereinstimmt, die ausschließlich Ihrer Organisation gehören"

• Geben Sie die Stargate-Server-IP-Adresse ein: <STARGATE_IP>
• Klicken Sie auf "+" zum Hinzufügen und dann auf "Weiter"

Note

Dies teilt Exchange Online mit, dass E-Mails von dieser spezifischen IP-Adresse vertrauenswürdig sind, und umgeht zusätzliche Spam-/Authentifizierungsprüfungen für E-Mails, die bereits von Stargate verarbeitet wurden.

1. Überprüfen Sie die Einstellungen und klicken Sie auf "Connector erstellen"

2. Klicken Sie auf "Fertig"

Connectors überprüfen

Nach der Erstellung beider Connectors sollte die Connectors-Seite Folgendes anzeigen:

Status	Name	Von	An
Ein	E-Mails vom Stargate-Relay-Server empfangen	Ihre Org	O365
Ein	Von Office 365 zum Stargate-Relay-Server	O365	Ihre Org

Schritt C: Die Transportregel erstellen

Die Transportregel leitet alle ausgehenden E-Mails über den Stargate-Ausgangs-Connector weiter, mit Ausnahme von E-Mails, die von Stargate selbst stammen (um E-Mail-Schleifen zu vermeiden).

1. Navigieren Sie zum Exchange Admin Center - Regeln

2. Klicken Sie auf "+ Regel hinzufügen" → "Neue Regel erstellen"

3. Regelname: Geben Sie einen beschreibenden Namen ein, z.B.:

Alle E-Mails an Stargate weiterleiten, außer E-Mails von diesem

1. Diese Regel anwenden, wenn: Wählen Sie "Der Empfänger..." → "ist extern/intern" → "Außerhalb der Organisation"
2. Klicken Sie auf "Speichern"

Note

Diese Bedingung stellt sicher, dass nur ausgehende E-Mails (an externe Empfänger) über Stargate weitergeleitet werden.

1. Folgendes tun: Wählen Sie "Die Nachricht umleiten an..." → "den folgenden Connector" → wählen Sie den in Schritt A erstellten ausgehenden Connector (z.B. "Von Office 365 zum Stargate-Relay-Server")

2. Klicken Sie auf "Speichern"

3. Außer wenn: Klicken Sie auf "+", um eine Ausnahme hinzuzufügen

4. Wählen Sie "Der Absender..." → "IP-Adresse in einem dieser Bereiche"
5. Geben Sie die Stargate-Server-IP-Adresse ein: <STARGATE_IP>
6. Klicken Sie auf "Hinzufügen", überprüfen Sie, ob die IP aufgeführt ist, und klicken Sie dann auf "Speichern"

Warning

Diese Ausnahme ist kritisch – sie verhindert E-Mail-Schleifen. Ohne sie würden E-Mails von Stargate, die bei Exchange Online ankommen, in einer Endlosschleife zurück an Stargate weitergeleitet.

1. Überprüfen Sie die Regelzusammenfassung. Sie sollte Folgendes anzeigen:
2. Diese Regel anwenden, wenn: Der Empfänger befindet sich Außerhalb der Organisation
3. Folgendes tun: Die Nachricht an den Connector "Von Office 365 zum Stargate-Relay-Server" umleiten

4. Außer wenn: Die Absender-IP-Adresse in einem dieser Bereiche liegt: <STARGATE_IP>

5. Klicken Sie auf "Weiter", dann erneut auf "Weiter", dann auf "Fertig" und dann auf "Fertig"

6. Regel aktivieren: Die Regel wird im deaktivierten Zustand erstellt. Klicken Sie auf die Regel in der Liste und schalten Sie "Regel aktivieren oder deaktivieren" auf "Aktiviert" um.

Tip

Vergessen Sie nicht, die Regel zu aktivieren – sie funktioniert nicht, bis sie aktiviert ist.

---

Teil 3: Konfiguration des On-Premises Exchange-Servers

Für On-Premises Exchange Server (2016, 2019) ist die Einrichtung ähnlich, wird jedoch über die Exchange-Verwaltungskonsole (EAC) oder die Exchange-Verwaltungsshell (PowerShell) konfiguriert.

Send Connector (On-Premises → Stargate)

Erstellen Sie einen Send-Connector, um ausgehende E-Mails über Stargate zu leiten:

Exchange-Verwaltungsshell (PowerShell):

New-SendConnector -Name "To Stargate Relay" `
  -AddressSpaces "SMTP:*;1" `
  -SmartHosts "<STARGATE_IP>" `
  -SmartHostAuthMechanism None `
  -DNSRoutingEnabled $false `
  -SourceTransportServers "<YOUR_EXCHANGE_SERVER>"

Exchange Admin Center (GUI):

1. Navigieren Sie zu Mailfluss → Send-Connectors
2. Klicken Sie auf +, um einen neuen Connector zu erstellen
3. Name: "To Stargate Relay"
4. Typ: Wählen Sie "Internet"
5. Netzwerkeinstellungen: Wählen Sie "E-Mails über Smart Hosts leiten", fügen Sie <STARGATE_IP> hinzu
6. Smart Host-Authentifizierung: Wählen Sie "Keine"
7. Adressraum: Fügen Sie * (alle Domains) oder bestimmte externe Domains hinzu
8. Quellserver: Wählen Sie Ihre Exchange-Transportserver

Receive Connector (Stargate → On-Premises)

Erstellen oder ändern Sie einen Receive-Connector, um E-Mails von Stargate zu akzeptieren:

Exchange-Verwaltungsshell (PowerShell):

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

Exchange Admin Center (GUI):

1. Navigieren Sie zu Mailfluss → Receive-Connectors
2. Klicken Sie auf +, um einen neuen Connector zu erstellen
3. Name: "From Stargate Relay"
4. Typ: Wählen Sie "Frontend Transport"
5. Netzwerkadapterbindungen: Standard belassen oder an bestimmte IP binden
6. Remote-Netzwerkeinstellungen: Entfernen Sie den Standardbereich 0.0.0.0-255.255.255.255 und fügen Sie nur <STARGATE_IP> hinzu
7. Authentifizierung: Aktivieren Sie "Extern gesichert"
8. Berechtigungsgruppen: Aktivieren Sie "Exchange-Server"

Transportregel (On-Premises)

Erstellen Sie eine Transportregel, um ausgehende E-Mails über den Send-Connector weiterzuleiten:

Exchange-Verwaltungsshell (PowerShell):

New-TransportRule -Name "Relay outbound via Stargate" `
  -SentToScope NotInOrganization `
  -RouteMessageOutboundConnector "To Stargate Relay" `
  -ExceptIfSenderIpRanges "<STARGATE_IP>"

Exchange Admin Center (GUI):

1. Navigieren Sie zu Mailfluss → Regeln
2. Klicken Sie auf + → "Neue Regel erstellen"
3. Name: "Relay outbound via Stargate"
4. Diese Regel anwenden, wenn: "Der Empfänger befindet sich..." → "Außerhalb der Organisation"
5. Folgendes tun: "Die Nachricht umleiten an..." → "den folgenden Connector" → "To Stargate Relay"
6. Außer wenn: "Die Absender-IP-Adresse in..." → fügen Sie <STARGATE_IP> hinzu

---

Teil 4: Stargate-seitige Konfiguration

Automatische Konfiguration (Standard)

Standardmäßig ermittelt Stalwart automatisch, wohin verarbeitete E-Mails zugestellt werden sollen, indem es die MX-Einträge für jede über die /mail-Seite des Dashboards konfigurierte Domain nachschlägt. Es filtert seinen eigenen Hostnamen heraus und verwendet die verbleibenden MX-Einträge als Zustellziele.

Dies funktioniert, wenn:

• Ihre Domain MX-Einträge hat, die sowohl auf Stargate als auch auf Exchange verweisen
• Stargate einen MX-Eintrag mit höherer Priorität (niedrigere Zahl) als Exchange hat

Manuelle Überschreibung über das Dashboard

Wenn Sie alle ausgehenden E-Mails von Stargate an einen einzigen Exchange-Endpunkt senden möchten (z.B. Exchange Online Protection), setzen Sie den Relay-Host über die /mail-Seite des Dashboards (z.B. [smtp.office365.com]). Das Dashboard sendet den Wert an die REST-API von mtaconf und der Daemon wendet ihn auf Stalwart an.

Note

Ein einzelner Relay-Host sendet alle E-Mails über einen Server und unterstützt kein pro-Domain-Routing. Für mehrere Domains, die über verschiedene Exchange-Server geroutet werden, verwenden Sie die pro-Domain-Relay-Map auf derselben Dashboard-Seite (konfiguriert intern sender_dependent_relayhost_maps) – siehe Multi-Domain-Setup unten.

Multi-Domain-Setup

Für Setups mit mehreren Domains und verschiedenen Exchange-Servern (z.B. BALZ Informatik AG mit 26 Domains) verwenden Sie MX-Einträge für das pro-Domain-Routing:

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

Die MX-Einträge jeder Domain sagen Stargate, wohin verarbeitete E-Mails für diese spezifische Domain zugestellt werden sollen.

Stargate-Konfiguration überprüfen

Überprüfen Sie nach der Einrichtung die Stalwart-Konfiguration:

Relay-Konfiguration prüfen

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

Mail-Warteschlange prüfen (sollte leer sein, wenn alles funktioniert)

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

Test-E-Mail senden und Logs prüfen

docker logs stargate-stalwart --tail 50

Fehlerbehebung

E-Mails verlassen Exchange Online nicht

• Überprüfen Sie, ob die Transportregel aktiviert ist (sie wird im deaktivierten Zustand erstellt)
• Überprüfen Sie die Regelbedingungen – sie sollte für Empfänger "Außerhalb der Organisation" gelten
• Überprüfen Sie, ob die Validierung des ausgehenden Connectors bestanden wurde
• Überprüfen Sie die Exchange-Nachrichtenverfolgung im Admin Center auf den Zustellungsstatus

E-Mail-Schleifen (doppelte Nachrichten)

• Stellen Sie sicher, dass die Transportregel die Ausnahme für die Stargate-IP-Adresse hat
• Ohne diese Ausnahme werden E-Mails von Stargate, die bei Exchange ankommen, zurück an Stargate weitergeleitet

Stargate akzeptiert keine E-Mails von Exchange

• Überprüfen Sie, ob Port 25 in der Firewall des Stargate-Servers geöffnet ist
• Überprüfen Sie, ob der SPF-Eintrag die Stargate-IP enthält
• Überprüfen Sie die Stalwart-Logs: docker logs stargate-stalwart

Exchange Online lehnt E-Mails von Stargate ab

• Überprüfen Sie, ob der eingehende Connector mit der richtigen Stargate-IP konfiguriert ist
• Überprüfen Sie, ob sich die Stargate-IP nicht geändert hat
• Überprüfen Sie, ob der Connector aktiviert ist (Status: Ein)

TLS-Zertifikatsfehler

Stargate verwendet opportunistisches TLS mit einem selbstsignierten Zertifikat. Der ausgehende Connector in Exchange sollte so konfiguriert sein, dass er "Beliebige digitale Zertifikate, einschließlich selbstsignierter Zertifikate" akzeptiert. Wenn Sie TLS-bezogene Fehler sehen:

• Überprüfen Sie, ob die Sicherheitseinstellung des ausgehenden Connectors selbstsignierte Zertifikate erlaubt
• Stellen Sie für On-Premises Exchange sicher, dass der Send-Connector kein TLS erfordert (-RequireTLS $false)

Validierung schlägt bei der Connector-Erstellung fehl

Die Validierung des ausgehenden Connectors erfordert:

• Stargate-Server läuft und akzeptiert Verbindungen auf Port 25
• Die Validierungs-E-Mail-Adresse ist für Ihre Domain gültig
• Der Netzwerkpfad zwischen Exchange Online und Stargate ist offen (keine Firewall-Blockierung)

---

Kurzreferenz

Komponente	Exchange Online-Ort	Zweck
Ausgehender Connector	Admin Center → Mailfluss → Connectors	Ausgehende E-Mails an Stargate leiten
Eingehender Connector	Admin Center → Mailfluss → Connectors	E-Mails von Stargate akzeptieren
Transportregel	Admin Center → Mailfluss → Regeln	Ausgehenden Connector für externe Empfänger auslösen

DNS-Eintrag	Beispiel	Zweck
A	mail IN A <STARGATE_IP>	Hostnamen auf Stargate verweisen
MX (Stargate)	@ IN MX 15 mail.<YOUR_DOMAIN>.	Eingehende E-Mails treffen zuerst auf Stargate
MX (Exchange)	@ IN MX 20 <DOMAIN>.mail.protection.outlook.com.	Fallback / Zustellziel
SPF	ip4:<STARGATE_IP> und ip4:<HIN_SEALER_IP> zum vorhandenen TXT-Eintrag hinzugefügt	Stargate und HIN-Sealer autorisieren, E-Mails zu senden

Die vollständige DNS-Einrichtung (einschließlich PTR, DMARC, DKIM und Multi-Domain) finden Sie im DNS-Einrichtungsleitfaden.

Stargate-Mail-Relay-Einrichtung

Erstellen Sie ein Stargate-Relay für eine in Microsoft Office 365 gehostete Mail-Domain

Für das Relay benötigen wir eine VM oder einen Server mit einer echten statischen IP-Adresse.

In diesem Beispiel verwenden wir eine VM mit der IP-Adresse 128.140.117.200 und dem Hostnamen mail.vrgnservices.eu, um E-Mails für die Domain vrgnservices.eu weiterzuleiten.

DNS-Einträge einrichten

Siehe den DNS-Einrichtungsleitfaden für vollständige Anweisungen zu allen erforderlichen Einträgen (A, MX, SPF, PTR, DMARC, DKIM).

Schnellbeispiel für die Domain vrgnservices.eu mit Stargate-IP 128.140.117.200:

• A-Eintrag: mail.vrgnservices.eu → 128.140.117.200
• MX-Eintrag: MX @ 15 mail.vrgnservices.eu. (höhere Priorität als der vorhandene Exchange-MX mit 20)
• SPF-Eintrag: v=spf1 ip4:128.140.117.200 include:spf.protection.outlook.com -all

Überprüfen:

# host mail.vrgnservices.eu
mail.vrgnservices.eu hat die Adresse 128.140.117.200

# host -t mx vrgnservices.eu
vrgnservices.eu Mail wird bearbeitet von 20 vrgnservices-eu.mail.protection.outlook.com.
vrgnservices.eu Mail wird bearbeitet von 15 mail.vrgnservices.eu.

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

Die Stargate-Docker-Compose-Container installieren

Stargate-Bereitstellung

Anforderungen

• 2 CPU-Kerne (Minimum)
• 4 GB RAM (Minimum)
• 20 GB Speicher (Minimum)
• Root-Zugriff: Muss als Root oder mit sudo ausgeführt werden
• Unterstützte Distributionen:
  • RHEL 8, 9 und 10 kompatible Distributionen wie Alma Linux, Rocky Linux, CentOS Stream
  • Ubuntu 22 und 24
  • Debian 11, 12 und 13
• Reale IPv4-Adresse
• Gültige DNS-Einträge: Ihre Domain muss Folgendes haben:
  • MX-Einträge, die auf Ihre Mailserver verweisen
  • SPF-Eintrag, der die erlaubten sendenden Netzwerke definiert

Das Skript installiert alle Komponenten und startet sie. Mail-Domains und der Stalwart-Hostname werden dann zur Laufzeit über die /mail-Seite des Dashboards konfiguriert (der mtaconf-Daemon extrahiert die erforderlichen Mail-Relay-Einstellungen basierend auf diesen Domains aus DNS).

Exchange einrichten

Wir müssen Connectors und eine Transportregel in Exchange konfigurieren, um alle ausgehenden E-Mails an das Stargate-Relay weiterzuleiten und eingehende E-Mails von diesem zu erlauben.

Navigieren Sie zu https://admin.exchange.microsoft.com/#/connectors

Ausgehender Connector

Erstellen Sie einen ausgehenden Mail-Connector, klicken Sie auf "Hinzufügen":

Wählen Sie "Verbindung von": "Office 365" "Verbindung zu": "E-Mail-Server Ihrer Organisation", klicken Sie auf "Weiter".

Benennen Sie ihn z.B. "Von Office 365 zum Stargate-Relay-Server" und aktivieren Sie "Interne Exchange-E-Mail-Header beibehalten", klicken Sie auf "Weiter".

Wählen Sie "Nur wenn ich eine Transportregel eingerichtet habe, die Nachrichten an diesen Connector weiterleitet", klicken Sie auf "Weiter".

Geben Sie die IP-Adresse des Stargate-Relay-Servers ein, klicken Sie auf "+", klicken Sie auf "Weiter".

Wählen Sie "Beliebiges digitales Zertifikat, einschließlich selbstsignierter Zertifikate", klicken Sie auf "Weiter".

Geben Sie eine gültige E-Mail-Adresse für Ihre Domain ein, klicken Sie auf "+", klicken Sie auf "Validieren", klicken Sie auf "Weiter".

Klicken Sie auf "Connector erstellen".

Klicken Sie auf "Einen weiteren Connector hinzufügen".

Eingehender Connector

Erstellen Sie einen eingehenden Mail-Connector, wählen Sie "Verbindung von": "E-Mail-Server Ihrer Organisation", klicken Sie auf "Weiter".

Benennen Sie ihn z.B. "E-Mails vom Stargate-Relay-Server empfangen" und aktivieren Sie "Interne Exchange-E-Mail-Header beibehalten", klicken Sie auf "Weiter".

Wählen Sie "Durch Überprüfen, ob die IP-Adresse des sendenden Servers mit einer der folgenden IP-Adressen übereinstimmt", geben Sie die IP-Adresse des Stargate-Servers ein, klicken Sie auf "+", klicken Sie auf "Weiter".

Klicken Sie auf "Connector erstellen".

Klicken Sie auf "Fertig".

So sieht es aus, wenn es fertig ist:

Transportregel

Erstellen Sie die Transportregel. Navigieren Sie zu https://admin.exchange.microsoft.com/#/transportrules

Klicken Sie auf "+Regel hinzufügen" → "Neue Regel erstellen".

Benennen Sie sie z.B. "Alle E-Mails an Stargate weiterleiten, außer E-Mails von diesem", wählen Sie "Regel anwenden, wenn" "Der Empfänger:" "ist extern/intern" "Außerhalb der Organisation", klicken Sie auf "Speichern".

Wählen Sie "Folgendes tun" "Nachricht an folgenden Connector umleiten" "Von Office 365 zum Stargate-Relay-Server", klicken Sie auf "Speichern".

Wählen Sie "Außer wenn Die Absender-IP-Adresse in einem dieser Bereiche liegt" geben Sie die IP-Adresse des Stargate-Servers ein, klicken Sie auf "Hinzufügen", überprüfen Sie die IP-Adresse und klicken Sie auf "Speichern".

Dies ist notwendig, um E-Mail-Schleifen zu vermeiden, da diese Regel auch für andere in Office 365 gehostete Domains gilt.

Jetzt sollte es so aussehen, klicken Sie auf "Weiter":

Klicken Sie auf "Weiter".

Klicken Sie auf "Fertig".

Klicken Sie auf "Fertig".

Klicken Sie auf die Regel und setzen Sie die Option "Regel aktivieren oder deaktivieren" auf "Aktiviert"

DNS-Einrichtung für Stargate

Dieser Leitfaden deckt alle DNS-Einträge ab, die für eine funktionierende Stargate-Bereitstellung erforderlich sind. Konfigurieren Sie diese Einträge vor der Installation von Stargate oder unmittelbar danach, je nach Eintragstyp.

In diesem Leitfaden:

• <STARGATE_IP> – die öffentliche statische IP-Adresse Ihres Stargate-Servers (SERVER_STATIC_IP in customer-config.sh)
• <MAIL_HOSTNAME> – der FQDN des Stargate-Relays (z.B. mail.example.ch; konfiguriert über die /mail-Seite des Dashboards)
• <YOUR_DOMAIN> – Ihre Mail-Domain (z.B. example.ch; konfiguriert über die /mail-Seite des Dashboards)

---

Eintragsübersicht

Eintrag	Name	Wert	Erforderlich	Wann
A	<MAIL_HOSTNAME>	<STARGATE_IP>	Ja	Vor der Installation
MX	<YOUR_DOMAIN>	<MAIL_HOSTNAME> (Priorität 15)	Ja	Vor der Installation
SPF	<YOUR_DOMAIN>	ip4:<STARGATE_IP> zum TXT hinzufügen	Ja	Vor der Installation
PTR	<STARGATE_IP>	<MAIL_HOSTNAME>	Empfohlen	Vor der Installation
DMARC	_dmarc.<YOUR_DOMAIN>	v=DMARC1; p=none; ...	Empfohlen	Nach der Installation
DKIM	selector._domainkey.<YOUR_DOMAIN>	Von M365/Anbieter	Empfohlen	Nach der Installation

Für Multi-Domain-Bereitstellungen wiederholen Sie die MX-, SPF-, DMARC- und DKIM-Einträge für jede in MAIL_DOMAINS aufgeführte Domain.

---

Erforderliche Einträge

A-Eintrag

Erstellen Sie einen A-Eintrag, der den Stargate-Mail-Hostnamen auf die öffentliche IP des Servers verweist:

<MAIL_HOSTNAME>.    A    <STARGATE_IP>

Beispiel:

mail.example.ch.    A    128.140.117.200

Wenn Stargate eine IPv6-Adresse hat, fügen Sie auch einen AAAA-Eintrag hinzu:

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

Warum: Externe Mailserver verbinden sich mit diesem Hostnamen, um E-Mails zuzustellen. Ohne den A-Eintrag ist der unten stehende MX-Eintrag nicht auflösbar.

MX-Einträge

Fügen Sie einen MX-Eintrag für Stargate mit einer höheren Priorität (niedrigere Zahl) als den vorhandenen Mailserver hinzu. Dies stellt sicher, dass eingehende E-Mails zuerst Stargate zur S/MIME-Verarbeitung erreichen, bevor sie an Exchange oder Ihre Mail-Plattform weitergeleitet werden.

<YOUR_DOMAIN>.    MX    15    <MAIL_HOSTNAME>.

Behalten Sie den vorhandenen Exchange/Mailserver-MX-Eintrag mit einer niedrigeren Priorität (höhere Zahl):

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

Beispiel (vollständiger MX-Satz):

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

Info

Die niedrigere MX-Zahl bedeutet höhere Priorität. Stargate mit Priorität 15 empfängt E-Mails vor Exchange Online mit Priorität 20.

Warum: Stargate fängt eingehende E-Mails ab, verarbeitet S/MIME und leitet sie dann an den nächsten MX (Exchange) weiter. Der zweite MX-Eintrag wird auch von Stalwart verwendet, um zu wissen, wohin verarbeitete E-Mails weitergeleitet werden sollen.

Wichtig: Wenn Stargate der einzige MX-Eintrag für eine Domain ist, filtert Stalwart seinen eigenen Hostnamen heraus und hat kein Zustellziel. Behalten Sie immer einen zweiten MX bei, der auf Ihren tatsächlichen Mailserver verweist.

SPF-Eintrag

Fügen Sie die Stargate-Server-IP und die HIN-Sealer-IP zum SPF-Eintrag Ihrer Domain hinzu, damit über Stargate weitergeleitete ausgehende E-Mails die SPF-Prüfungen beim Empfänger bestehen.

Wenn Sie M365 / Exchange Online verwenden:

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

Wenn Sie M365 / Google Workspace nicht verwenden:

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

Beispiel:

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

Warum die HIN-Sealer-IP erforderlich ist

Wenn Stargate eine SEAL'd (verschlüsselte) Nachricht für einen Nicht-HIN-Empfänger erzeugt, ist der letzte ausgehende Hop zum Empfänger der HIN-Sealer, nicht Ihr Stargate oder M365. Ohne die Sealer-IP in Ihrem SPF-Eintrag wird jede SEAL'd ausgehende Nachricht beim Empfänger die SPF-Prüfung nicht bestehen, und – da es keine DKIM-Signatur auf der SEAL'd-Nutzlast gibt – wird auch DMARC fehlschlagen. Strenge DMARC-Empfänger (Gmail, Outlook mit p=reject-Durchsetzung, Proofpoint) werden die Nachricht ablehnen oder im Spam-Ordner ablegen.

Sealer-IPs, die in SPF aufgenommen werden müssen:

Umgebung	Sealer-Host	In SPF aufzunehmende IP
HIN Test (alpha/beta)	mx3.hintest.ch	193.247.208.66
HIN Produktion	TBD – vor dem Produktivstart die kanonische Liste von HIN anfordern	TBD

Wenn HIN mehr als einen Sealer-Host veröffentlicht (z.B. mx1, mx2, mx3), nehmen Sie alle deren IPs auf. Lösen Sie sie mit dig +short mx hintest.ch auf, gefolgt von dig +short A <jeder-mx>. Bis Sie die vollständige Liste haben, belassen Sie die SPF-Richtlinie auf ~all (Softfail) anstelle von -all (Hardfail), damit legitime SEAL-E-Mails über eine nicht aufgeführte Sealer-IP nicht sofort abgewiesen werden.

SPF-Lookup-Limit

Die gesamte include:-Kette in einem SPF-Eintrag darf 10 DNS-Lookups nicht überschreiten. Das Hinzufügen von ip4:-Einträgen zählt nicht zu diesem Limit. Überprüfen Sie Ihre Anzahl mit MXToolbox SPF-Lookup.

Wie Stargate SPF verwendet: Der mtaconf-Daemon löst den SPF-Eintrag jeder Domain auf, um die Liste der IPs, die ohne Authentifizierung über Stargate weiterleiten dürfen, automatisch zu befüllen. So werden die ausgehenden IPs von Microsoft 365 automatisch auf die Whitelist gesetzt – sie erscheinen in der include:spf.protection.outlook.com-Kette.

---

Empfohlene Einträge

PTR (Reverse DNS)

Konfigurieren Sie den Reverse-DNS (PTR)-Eintrag für die Stargate-IP so, dass er mit <MAIL_HOSTNAME> übereinstimmt:

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

Dies wird bei Ihrem Hosting-Anbieter (Hetzner, Azure, AWS usw.) konfiguriert, nicht im DNS-Panel Ihres Domain-Registrars. Die meisten Anbieter haben eine Einstellung "Reverse DNS" oder "rDNS" in der Server/IP-Verwaltungsseite.

Warum: Viele empfangende Mailserver (einschließlich Gmail und Outlook) prüfen, ob der PTR-Eintrag der verbindenden IP zu einem Hostnamen aufgelöst wird und ob dieser Hostname wiederum auf dieselbe IP aufgelöst wird (forward-confirmed reverse DNS / FCrDNS). Ein fehlender oder nicht übereinstimmender PTR ist ein starkes Spam-Signal und kann zu Zustellfehlern führen.

DMARC-Eintrag

Veröffentlichen Sie eine DMARC-Richtlinie für jede sendende Domain. Beginnen Sie mit p=none (nur Überwachung), dann verschärfen Sie nach Bestätigung der Ausrichtung:

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

Beispiel:

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

Sobald die DMARC-Aggregatberichte bestätigen, dass SPF und/oder DKIM durchgängig erfolgreich sind, verschärfen Sie die Richtlinie:

1. p=none – nur Überwachung (hier beginnen)
2. p=quarantine – verdächtige E-Mails gehen in den Spam-Ordner
3. p=reject – nicht autorisierte E-Mails werden abgewiesen

Warum: DMARC verbindet SPF und DKIM und teilt Empfängern mit, was mit E-Mails geschehen soll, die beide Prüfungen nicht bestehen. Selbst p=none reicht aus, um die Outlook-Warnung "Wir können diesen Absender nicht überprüfen" zu beseitigen, solange SPF erfolgreich ist.

Überprüfen Sie Ihren DMARC-Eintrag: MXToolbox DMARC-Lookup

DKIM-Einträge

Wenn Ihre Domain eine akzeptierte Domain in M365 oder Google Workspace ist, aktivieren Sie die DKIM-Signatur im Admin-Center und veröffentlichen Sie die CNAME-Einträge wie angewiesen:

M365-Beispiel:

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

Das Veröffentlichen der CNAME-Einträge allein reicht nicht aus – die DKIM-Signatur muss auch im M365-Admin-Center aktiviert werden (Defender-Portal > E-Mail-Authentifizierung > DKIM).

Warum: DKIM beweist, dass der Nachrichtentext während des Transports nicht manipuliert wurde. In Kombination mit SPF und DMARC bietet es die stärkste Sender-Authentifizierung.

---

Multi-Domain-Setup

Für Bereitstellungen, die mehrere Mail-Domains verwalten (konfiguriert über die /mail-Seite des Dashboards), benötigt jede Domain ihren eigenen Satz von DNS-Einträgen.

Einträge pro Domain

Für jede konfigurierte Domain:

Eintrag	Erforderlich
MX, der auf <MAIL_HOSTNAME> verweist	Ja
SPF mit ip4:<STARGATE_IP>	Ja
DMARC (_dmarc.<domain>)	Empfohlen
DKIM (von Ihrem Mail-Anbieter)	Empfohlen

Der A-Eintrag und der PTR-Eintrag werden gemeinsam genutzt (sie verweisen auf den Stargate-Server, nicht auf einzelne Domains).

Mail-Routing pro Domain

Die MX-Einträge jeder Domain sagen Stargate, wohin verarbeitete E-Mails zugestellt werden sollen. Wenn verschiedene Domains unterschiedliche Exchange-Server verwenden:

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.

Alternativ konfigurieren Sie explizite pro-Domain-Relay-Ziele über die /mail-Seite des Dashboards (Relay-Host-Feld pro Domain), um das MX-basierte Routing zu überschreiben.

---

Überprüfung

Nach der Konfiguration aller Einträge überprüfen Sie diese:

# A-Eintrag
host <MAIL_HOSTNAME>
# Erwartet: <MAIL_HOSTNAME> has address <STARGATE_IP>

# MX-Einträge
host -t mx <YOUR_DOMAIN>
# Erwartet: Sowohl Stargate- als auch Exchange-MX-Einträge aufgelistet

# SPF-Eintrag
host -t txt <YOUR_DOMAIN> | grep v=spf1
# Erwartet: SPF-Eintrag enthält ip4:<STARGATE_IP>

# PTR (Reverse DNS)
host <STARGATE_IP>
# Erwartet: <STARGATE_IP> → <MAIL_HOSTNAME>

# Forward-confirmed reverse DNS (FCrDNS)
host $(host <STARGATE_IP> | awk '{print $NF}' | sed 's/\.$//')
# Erwartet: löst auf <STARGATE_IP> auf

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

# DKIM (M365)
host -t cname selector1._domainkey.<YOUR_DOMAIN>
# Erwartet: CNAME zu Ihrer Tenant-onmicrosoft.com

Beispielausgabe:

$ host mail.example.ch
mail.example.ch has address 128.140.117.200

$ host -t mx example.ch
example.ch mail is handled by 15 mail.example.ch.
example.ch mail is handled by 20 example-ch.mail.protection.outlook.com.

$ host -t txt example.ch | grep v=spf1
example.ch descriptive text "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 domain name pointer mail.example.ch.

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

Online-Tools:

• MXToolbox MX-Lookup
• MXToolbox SPF-Prüfung (beinhaltet Lookup-Zählung)
• MXToolbox DMARC-Prüfung
• Mail-Tester (senden Sie eine Test-E-Mail, um einen Zustellbarkeits-Score zu erhalten)

---

Fehlerbehebung

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

Stalwart lehnt den sendenden Server ab, weil seine IP nicht in der erlaubten Relay-Liste ist. Dies bedeutet normalerweise:

• Der SPF-Eintrag für Ihre Domain enthält nicht den IP-Bereich des sendenden Servers
• Die Mail-Konfiguration wurde seit der SPF-Eintragsaktualisierung nicht neu geladen

Laden Sie die Mail-Konfiguration über die /mail-Seite des Dashboards neu (Konfiguration erneut übermitteln) oder starten Sie den Container neu: docker compose restart stalwart

E-Mail als Spam markiert / "Absender kann nicht überprüft werden"

• SPF fehlt oder enthält nicht die Stargate-IP – fügen Sie ip4:<STARGATE_IP> zu Ihrem SPF-Eintrag hinzu
• DMARC ist nicht veröffentlicht – fügen Sie mindestens v=DMARC1; p=none hinzu
• PTR-Eintrag fehlt oder stimmt nicht überein – konfigurieren Sie Reverse DNS bei Ihrem Hosting-Anbieter
• DKIM ist in Ihrem M365/Anbieter-Mandanten nicht aktiviert

MX-Lookup gibt nur Stargate zurück

Wenn Stargate der einzige MX für eine Domain ist, filtert Stalwart seinen eigenen Hostnamen heraus und hat kein Relay-Ziel. Fügen Sie einen zweiten MX-Eintrag hinzu, der auf Ihren Mailserver verweist:

example.ch.    MX    15    mail.example.ch.          ← Stargate (eingehend)
example.ch.    MX    20    example-ch.mail.protection.outlook.com.  ← Exchange (Relay-Ziel)

SPF-Lookup-Limit überschritten (> 10)

Jedes include: im SPF-Eintrag löst zusätzliche DNS-Lookups aus. Die gesamte Kette muss unter 10 bleiben. Lösungen:

• Verwenden Sie ip4: / ip6:-Einträge anstelle von include:, wo möglich (sie zählen nicht)
• Flatten Sie verschachtelte Includes mit einem Tool wie SPF Flattener
• Entfernen Sie nicht verwendete include:-Einträge von alten Anbietern

Port 25 wird vom Hosting-Anbieter blockiert

Einige Cloud-Anbieter (Azure, bestimmte Hetzner-Tarife) blockieren ausgehenden Port 25 standardmäßig. Überprüfen Sie dies bei Ihrem Anbieter und beantragen Sie eine Ausnahme. Dies betrifft sowohl die eingehende Zustellung (externe Server, die sich mit Ihrem Stargate verbinden) als auch das ausgehende Relay (Stargate, das an MX-Ziele zustellt).

E-Mail-Authentifizierung (DKIM / ARC / SPF / DMARC)

Modul: HIN Mail Gateway -> Domains -> [Domain] -> Email authentication Gilt für: Domain-Administratoren, die das ausgehende Signieren und die eingehende Verifizierung für eine Mail-Domain konfigurieren

---

Der Bereich Email authentication steuert, wie die Echtheit von E-Mails nachgewiesen wird und wie streng deren Echtheit bei eingehender Mail geprüft wird, also die DKIM-/ARC-/SPF-/DMARC-Verifizierung. Außerdem werden hier die DNS-TXT-Einträge erzeugt, die veröffentlicht werden müssen, damit externe Mailserver die Mail Ihrer Domain verifizieren können.

Der Bereich erreichen Sie über:

Domains -> Domain auswählen -> Email authentication

Das Panel besteht aus fünf Unterabschnitten:

1. DKIM
2. ARC
3. SPF
4. DMARC
5. Zu veröffentlichende DNS-Einträge

Änderungen werden erst übernommen, nachdem Sie unten auf der Seite auf die Schaltfläche Save geklickt haben.

---

Was jedes Protokoll bewirkt

Protokoll	Richtung	Zweck
DKIM (DomainKeys Identified Mail)	Ausgehende Signierung / Eingehende Verifizierung	Signiert ausgehende Nachrichten kryptografisch mit einem privaten Schlüssel, der einem öffentlich in DNS veröffentlichten Schlüssel zugeordnet ist, sodass Empfänger bestätigen können, dass die Nachricht während der Übertragung nicht verändert wurde und tatsächlich von dieser Domain stammt
ARC (Authenticated Received Chain)	Signierung der eingehenden Verifizierung für den nächsten Relay-Schritt	Bewahrt die ursprünglichen DKIM-/SPF-Authentifizierungsergebnisse, während eine Nachricht durch Zwischenstationen (z.B. Mailinglisten, Weiterleitungsdienste) läuft, die DKIM-Signaturen sonst zerstören würden
SPF (Sender Policy Framework)	Eingehende Verifizierung	Prüft anhand eines von der Absenderdomain veröffentlichten DNS-Eintrags, ob die IP-Adresse des sendenden Mailservers berechtigt ist, Mail für diese Domain zu versenden
DMARC (Domain-based Message Authentication, Reporting & Conformance)	Eingehende Verifizierung	Verknüpft die Ergebnisse von DKIM und SPF und teilt empfangenden Servern mit, wie zu verfahren ist

Wenn DKIM und DMARC für Ihre eigene Domain korrekt eingerichtet sind, schützt das Ihre Zustellbarkeit und Ihre Marke vor Spoofing. Die Verifizierungs-Einstellungen (DKIM-, ARC-, SPF-, DMARC-Verifizierungs-Dropdowns) steuern dagegen, wie streng das Gateway diesen Signalen bei eingehender Mail von anderen Domains vertraut.

---

DKIM

Feld	Beschreibung
Enable DKIM signing	Wenn aktiv, signiert das Gateway alle ausgehende Mail dieser Domain mit dem konfigurierten privaten Schlüssel. Aktivieren Sie dies, bevor Sie den DKIM-DNS-Eintrag veröffentlichen
Generate DKIM key (Schaltfläche, oben rechts)	Erzeugt ein neues RSA-2048-Schlüsselpaar für diese Domain und füllt das Feld Private key (PEM)
DKIM verification	Steuert, wie streng eine E-Mail gegen den veröffentlichten DKIM-Eintrag des Absenders geprüft wird
Selector	Der DKIM-Selector (z.B. s1), der zum Veröffentlichen und Nachschlagen des öffentlichen Schlüssels unter <selector>._domainkey.<domain> verwendet wird. Ändern Sie dies nur, wenn Sie mehrere Schlüssel parallel benötigen (z.B. während einer Schlüsselrotation): jeder Selector benötigt seinen eigenen DNS-TXT-Eintrag
Private key (PEM)	Der private RSA-Schlüssel, mit dem ausgehende Mail signiert wird. Klicken Sie entweder auf Generate DKIM key, um einen zu erzeugen, oder fügen Sie Ihren eigenen privaten RSA-2048-Schlüssel im PEM-Format ein

So richten Sie DKIM für eine neue Domain ein

1. Klicken Sie auf Generate DKIM key (oder fügen Sie einen vorhandenen, extern verwalteten RSA-2048-PEM-Schlüssel ein)
2. Belassen Sie Selector auf dem Standardwert (s1), sofern es keinen Grund zur Änderung gibt
3. Setzen Sie Enable DKIM signing auf Active
4. Klicken Sie auf Save
5. Kopieren Sie den erzeugten s1._domainkey.<domain>-TXT-Eintrag aus dem Feld DNS records to publish (siehe §7) und tragen Sie ihn bei Ihrem DNS-Anbieter ein
6. Sobald sich der DNS-Eintrag verbreitet hat, trägt die von dieser Domain signierte Mail eine gültige DKIM-Signatur

So rotieren Sie einen DKIM-Schlüssel

1. Klicken Sie neben Private key (PEM) auf Replace key
2. Erzeugen Sie einen neuen Schlüssel (oder fügen Sie einen neuen ein)
3. Veröffentlichen Sie den TXT-Eintrag des neuen Selectors im DNS bevor Sie ihn in Produktion speichern/aktivieren, um ein Zeitfenster zu vermeiden, in dem signierte Mail nicht verifiziert werden kann
4. Speichern Sie und entfernen Sie den DNS-Eintrag des alten Selectors, sobald Sie bestätigt haben, dass der neue Schlüssel korrekt signiert

---

ARC

Feld	Beschreibung
ARC verification (Dropdown)	Steuert, wie streng eingehende ARC-Ketten validiert werden
Enable ARC signing	Wenn aktiv, fügt das Gateway weitergeleiteter Mail ein ARC-Seal hinzu und bewahrt so die Authentifizierungsergebnisse, falls die Nachricht später über ein anderes System weitergeleitet wird
Reuse DKIM key (Umschalter)	Wenn aktiv, verwendet die ARC-Signierung denselben RSA-Schlüssel, der oben im DKIM-Bereich konfiguriert ist, statt einen separaten Schlüssel zu benötigen. Empfohlen, sofern Sie keinen besonderen Grund haben, die beiden Signaturen kryptografisch getrennt zu halten

---

SPF

Feld	Beschreibung
SPF verification	Steuert, wie streng eingehende Mail gegen den veröffentlichten SPF-Eintrag der Absenderdomain geprüft wird

Hinweis: Dieses Panel steuert nur die Verifizierung eingehender SPF-Prüfungen. Es erzeugt keinen ausgehenden SPF-TXT-Eintrag für Ihre eigene Domain (in §7 "DNS records to publish" erscheint kein SPF-Eintrag). Wenn diese Domain Mail über ein externes Relay versendet (z.B. Microsoft 365, konfiguriert unter Mail routing -> Outbound relay), stellen Sie sicher, dass der include:-Mechanismus dieses Anbieters bereits unabhängig von diesem Gateway im eigenen SPF-Eintrag Ihrer Domain bei Ihrem DNS-Anbieter veröffentlicht ist.

---

DMARC

Feld	Beschreibung
DMARC verification	Steuert, wie streng eingehende Mail gegen die DMARC-Richtlinie des Absenders geprüft wird

Verifizierungswert

UI-Bezeichnung	Wert	Verhalten
Disabled	disable	Wird überhaupt nicht geprüft. Mechanismus läuft nicht
Optional	relaxed	Wird verifiziert und im Authentication-Results gemeldet. Die Nachricht wird immer angenommen, ob bestanden oder nicht
Required	strict	Wird verifiziert und gemeldet, und die Nachricht wird bei einem Hard-Fail abgelehnt. Andernfalls wird sie angenommen

Kurz gesagt: Disabled bedeutet, es wird nicht geprüft; Optional und Required prüfen beide und vermerken das Ergebnis. Der einzige Unterschied zwischen beiden ist die Durchsetzung: Optional lehnt nie ab, Required lehnt bei einem Hard-Fail ab.

Was als "Hard Failure" für Required gilt (pro Mechanismus): - DKIM: Die Nachricht enthält Signaturen und alle schlagen fehl. Gar keine Signatur ergibt none, keinen Fehlschlag, also keine Ablehnung. - SPF: Ein harter -all-Fehlschlag. SoftFail/neutral/none/temp-error werden gemeldet, führen aber nicht zur Ablehnung. - DMARC: Weder DKIM noch SPF richtet sich aus, und es liegt ein tatsächliches Fail-Ergebnis vor. Kein veröffentlichter DMARC-Eintrag ergibt none, also keine Ablehnung. - ARC: Die ARC-Kette schlägt bei der Validierung fehl. Keine Kette ergibt none, also keine Ablehnung.

Zwei wichtige Hinweise: - DKIM läuft intern immer, weil DMARC es benötigt. Die DKIM-Einstellung steuert nur, ob ein dkim=-Ergebnis vermerkt wird und ob ein DKIM-Fehlschlag zur Ablehnung führen kann; sie ändert nie das DMARC-Ergebnis. - Jeder Mechanismus ist unabhängig, sodass Sie z.B. DMARC = Required bei DKIM/SPF = Optional ausführen können: Schlechte Mail wird anhand des DMARC-Ergebnisses abgelehnt, und Sie erhalten trotzdem einzelne dkim=/spf=-Zeilen im Header zur besseren Nachvollziehbarkeit.

---

Zu veröffentlichende DNS-Einträge

Dieser Bereich zeigt die exakten TXT-Einträge, die Sie beim DNS-Anbieter Ihrer Domain anlegen müssen, damit externe Mailserver Mail von dieser Domain verifizieren können. Die angezeigten Einträge werden automatisch anhand Ihres DKIM-Selectors und der DMARC-Richtlinie oben aktualisiert.

Eintrag	Host	Typ	Wert
DKIM-Öffentlicher Schlüssel	<selector>._domainkey.<domain> (z.B. s1._domainkey.vrgnservices.eu)	TXT	v=DKIM1; k=rsa; p=<public key>
DMARC-Richtlinie	_dmarc.<domain> (z.B. _dmarc.vrgnservices.eu)	TXT	v=DMARC1; p=<policy> (z.B. p=none)

Verwenden Sie das Kopiersymbol oben rechts in jedem Eintragsfeld, um dessen exakten Wert zu kopieren. Fügen Sie jeden Eintrag als neuen TXT-Eintrag bei Ihrem DNS-Registrar/-Anbieter ein, indem Sie Host/Name und Value wie angezeigt verwenden.

DNS-Änderungen können je nach TTL-Einstellung Ihres Anbieters zwischen wenigen Minuten und 48 Stunden zur Verbreitung benötigen. Die DKIM-/DMARC-Durchsetzung sollte erst verschärft werden (z.B. Signieren aktivieren oder die DMARC-Richtlinie über none hinaus verschärfen), nachdem Sie bestätigt haben, dass sich die Einträge verbreitet haben und korrekt aufgelöst werden.

---

Änderungen speichern

Keine der oben genannten Einstellungen wird wirksam, bevor Sie unten auf der Seite auf die orangefarbene Schaltfläche Save klicken. Save übernimmt alle Änderungen an DKIM, ARC, SPF und DMARC gemeinsam; es gibt kein Speichern pro Abschnitt.

---

Fehlerbehebung

Symptom	Wahrscheinliche Ursache
Ausgehende Mail besteht DKIM bei empfangenden Servern nicht	DKIM-Signierung aktiviert, aber der DNS-TXT-Eintrag noch nicht veröffentlicht/verbreitet, oder Selector-Mismatch zwischen Gateway und DNS.
ARC-Seal fehlt bei weitergeleiteter Mail	Enable ARC signing ist deaktiviert, oder Reuse DKIM key ist deaktiviert, ohne dass ein separater ARC-Schlüssel konfiguriert ist.
Der private DKIM-Schlüssel kann nicht eingesehen werden, um ihn andernorts zu kopieren	So gewollt: Nach dem Speichern ist der Schlüssel maskiert (<hidden>) und kann nicht erneut angezeigt werden. Verwenden Sie Replace key, um einen neuen auszustellen, wenn Sie ihn auf ein System übertragen müssen, das noch keine Kopie besitzt.
Legitime Mail wird nach einer Änderung der DMARC-Richtlinie plötzlich unter Quarantäne gestellt/abgelehnt	Eine legitime Versandquelle ist noch nicht DKIM-/SPF-ausgerichtet. Setzen Sie die Richtlinie auf none zurück, identifizieren Sie die fehlerhafte Quelle, beheben Sie die Ausrichtung und verschärfen Sie die Richtlinie danach erneut.

Update HIN Gateway

Dieses Dokument erklärt:

• Wie Sie eine HIN Gateway Instanz auf eine neuere Version aktualisieren.
• Wie Sie ein Rollback auf eine vorherige Version durchführen.

Anwendbare Versionen

Dieses Verfahren gilt nur für Version 0.6.x und höher.

Wie man aktualisiert

1. Gehen Sie zur Seite Settings und scrollen Sie zum Abschnitt System version.

1. Klicken Sie auf Other versions.

2. Wählen Sie aus der Liste der verfügbaren Versionen die Zielversion aus.

3. Neuere Versionen verwenden eine fortlaufende Nummerierung, daher hat die Zielversion eine höhere Nummer als die aktuelle.

4. Klicken Sie auf die Schaltfläche Download. Dadurch wird nur der Download gestartet, das Update wird noch nicht installiert.

1. Nach Abschluss des Downloads erscheint ein Bestätigungsdialog mit zwei Optionen:

2. Restart now: startet die Maschine sofort neu und installiert die neue Version.

3. Later: verschiebt das Update. Die neue Version wird beim nächsten Neustart der Maschine installiert.

Wie man ein Rollback durchführt

1. Gehen Sie zur Seite Settings und scrollen Sie zum Abschnitt System version.

1. Klicken Sie auf die Schaltfläche Roll back to vX.X.X.

2. Bestätigen Sie die Aktion auf dem Bestätigungsbildschirm. Das System startet neu und installiert die vorherige stabile Version.

Server-Installation

Container

Stargate Docker-Bereitstellung

Voraussetzungen

Server-Anforderungen:

Bitte beachten Sie die Empfohlenen Anforderungen

• Docker wird bei Bedarf automatisch installiert
• Stellen Sie sicher, dass auf dem System, auf dem Sie Stargate-Dienste installieren, eine Internetverbindung besteht
• Stellen Sie sicher, dass der Datenverkehr ordnungsgemäß konfiguriert ist, um die Stargate-Instanz zu erreichen

Schritt 1: Kundeneinstellungen konfigurieren

Tip

Sie können unser Repository mit allen Daten und Beispielkonfigurationen mit folgendem Befehl klonen:

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

Wenn Sie git nicht installiert haben, können Sie jederzeit ein Archiv mit allen Dateien herunterladen. Laden Sie es über den folgenden Link herunter.

Als ZIP herunterladen

Das Installationsskript erstellt customer-config.sh beim ersten Start automatisch aus der mitgelieferten Vorlage, sodass eine Neuinstallation keine manuelle Konfiguration benötigt. Wenn Sie sie lieber selbst erstellen möchten, kopieren Sie die Vorlage:

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

Sie müssen darin nichts bearbeiten - jeder Wert wird entweder automatisch erkannt oder später über das Dashboard konfiguriert:

Einstellung	Wie sie gesetzt wird
SERVER_STATIC_IP	Automatisch von der primären Netzwerkschnittstelle des Servers erkannt.
CUSTOMER_NAME	Standardmäßig der System-Hostname.
DEPLOYMENT_NAME	Von CUSTOMER_NAME abgeleitet (wird in Log-Labels und im Alloy-Hostname verwendet).
Passwörter & Schlüssel (POSTGRES_PASSWORD, S3_SECRET_KEY, VAULT_TOKEN, WG_PRIVATE_KEY)	Werden beim ersten Start sicher generiert und in customer-config.sh zurückgeschrieben.

Mail-Domains, der Mail-Hostname, S/MIME-Zertifikate und WireGuard-Peers werden alle zur Laufzeit über das Dashboard konfiguriert, nachdem der Stack läuft - sie sind nicht Teil von customer-config.sh.

Hinter NAT oder einer Floating IP?

Die automatische Erkennung verwendet die IP der primären Schnittstelle des Servers. Wenn Ihr Server über eine andere öffentliche oder Floating IP erreicht wird (üblich bei NAT), setzen Sie SERVER_STATIC_IP vor der Installation auf diese öffentliche IP in customer-config.sh, damit die Dashboard- und Keycloak-Login-URLs auf die erreichbare Adresse zeigen. Lassen Sie es andernfalls leer.

Mail-Domains und der Stalwart-Hostname werden zur Laufzeit über die /mail-Seite des Dashboards konfiguriert; sie sind nicht Teil von customer-config.sh.

Automatisch abgeleitete Einstellungen – leer lassen, es sei denn, Sie müssen sie überschreiben:

Einstellung	Abgeleitet von	Standard
MXENGINE_PUBLIC_ADDRESS	SERVER_STATIC_IP	http://<SERVER_STATIC_IP>:8084

S/MIME-Zertifikatseinstellungen:

Einstellung	Beschreibung	Standard
CERT_CA_IRISAGENT_DOMAIN	CA-Domain für die Zertifikatsausstellung über den WireGuard-Tunnel	hintest.ch

Note

Die WireGuard-Peer-Einrichtung wird zur Laufzeit über das Dashboard (/installation-Seite) durchgeführt. Peer-Details werden pro Bereitstellung nach dem Start des Stacks konfiguriert – sie sind nicht Teil von customer-config.sh.

WireGuard lokale Einstellungen (normalerweise bei Standardwerten belassen):

Einstellung	Standard	Beschreibung
WG_PRIVATE_KEY	(automatisch generiert)	Wird von IRISAgent beim ersten Start generiert und dann in customer-config.sh gespeichert
WG_LOCAL_IP	SERVER_STATIC_IP	Automatisch abgeleitet. Nur überschreiben, wenn Sie eine andere Tunneladresse benötigen.
WG_INTERFACE_PORT	19818	WireGuard-Tunnelport (sowohl TCP als auch UDP werden freigegeben)
WG_TRANSPORT_MODE	tcp	Transportprotokoll: tcp (Standard, funktioniert durch die meisten Firewalls) oder udp

Optionale Einstellungen (haben sinnvolle Standardwerte):

Einstellung	Standard	Beschreibung
POSTGRES_PASSWORD	(automatisch generiert)	Automatisch generiertes 24-stelliges Zufallspasswort, falls leer
S3_SECRET_KEY	(automatisch generiert)	S3-Secret-Key für den Objektspeicher
OUTBOUND_SEALER_MX_DOMAIN	hintest.ch	Sealer-MX-Domain für die Zustellung ausgehender Siegel
POLICY_SYNC_REPO_URL	GitHub HIN Stargate-Richtlinien	Git-Repository-URL für die OPA/Rego-Richtlinien-Synchronisierung
LOKI_URL	(nicht gesetzt)	Loki-Endpunkt für den zentralisierten Logversand (z.B. https://loki.example.com)

Automatisch generiert (nicht manuell setzen):

• VAULT_TOKEN — Wird von Vault während der ersten Initialisierung generiert und in customer-config.sh gespeichert
• WG_PRIVATE_KEY — Wird von IRISAgent beim ersten Start generiert und in customer-config.sh gespeichert

Schritt 2: Auf einem Server bereitstellen

Tip

Sie können unser Repository mit allen Daten und Beispielkonfigurationen mit folgendem Befehl klonen:

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

Wenn Sie git nicht installiert haben, können Sie jederzeit ein Archiv mit allen Dateien herunterladen und es extrahieren:

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

Kopieren Sie die Dateien manuell auf den Server

scp -r docker-compose/* your-server:/path/to/stargate/

SSH zum Server

ssh your-server
cd /path/to/stargate

Erstellen Sie die Kundenkonfiguration aus der Vorlage und füllen Sie die erforderlichen Einstellungen aus (siehe Schritt 1)

cp customer-config-prod.example.sh customer-config.sh
nano customer-config.sh   # Erforderliche Einstellungen ausfüllen (siehe Schritt 1)

Installation ausführen

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

Schritt 3: Was die Installation bewirkt

Das Installationsskript (install.sh) führt die folgenden Schritte durch:

1. Abhängigkeiten prüfen — Erkennt Docker, Docker Compose und jq. Wenn diese fehlen, werden sie automatisch installiert (unterstützt Ubuntu/Debian, RHEL/AlmaLinux/Rocky).
2. customer-config.sh laden und validieren — Prüft erforderliche Felder (SERVER_STATIC_IP, CUSTOMER_NAME, DEPLOYMENT_NAME). Leitet optionale Felder automatisch ab (MXEngine-URL usw.).
3. .env aus der Kundenkonfiguration generieren — Generiert automatisch Passwörter, falls nicht gesetzt.
4. Alle Dienste über Docker Compose starten (Infrastruktur + Anwendungen).
5. Vault initialisieren — Der vault-init-Container initialisiert, entsiegelt und erstellt KV-v2-Secret-Mounts. Schreib den WireGuard-Private-Key optional in Vault.
6. Vault-Schlüssel in secrets/vault-keys.json speichern und .env mit dem Root-Token aktualisieren. Das Token wird auch in customer-config.sh gespeichert, um es über VM-Neuerstellungen hinweg zu erhalten.
7. Anwendungsdienste neu starten, um das Vault-Token zu übernehmen.
8. WireGuard-Private-Key in customer-config.sh speichern — wird nach der Generierung durch IRISAgent aus Vault extrahiert.
9. Täglichen Backup-Cron-Job einrichten (wird um 2:00 Uhr ausgeführt).

Nach Abschluss der Installation läuft der Stack, aber es sind noch keine Mail-Domains, S/MIME-Zertifikate oder WireGuard-Peers eingerichtet. Fahren Sie mit Schritt 4: Onboarding über das Dashboard fort.

Schritt 4: Onboarding über das Dashboard

Nach der Installation schließen Sie das Onboarding über das Dashboard unter https://<SERVER_STATIC_IP> ab. Das Dashboard führt Sie der Reihe nach durch drei Seiten:

/installation — WireGuard-Peer-Einrichtung

Führt den Nonce/HIN-Handshake durch, um eine WireGuard-Peer-Verbindung herzustellen, und speichert die resultierende WireGuard-Konfiguration im IRISAgent-Dienst.

/onboarding — S/MIME-Zertifikat

Generiert den S/MIME-Signaturschlüssel und den CSR über den smimekeys-Dienst und übermittelt den CSR über den nun eingerichteten WireGuard-Tunnel an die CA. (Dies ersetzt den früheren skriptbasierten Zertifikatsfluss.)

/mail — Mail-Domains und Relay-Konfiguration

Übermittelt Hostname und die Liste der Relay-Domains über die REST-API an den mtaconf-Dienst. Der Daemon wendet die Konfiguration auf Stalwart an, ohne den Container neu starten zu müssen.

Domains später hinzufügen oder ändern

Öffnen Sie die /mail-Seite im Dashboard erneut, bearbeiten Sie die Domain-Liste und übermitteln Sie sie. Der Daemon wendet die Änderung zur Laufzeit an – kein Skriptaufruf, keine .env-Bearbeitung, kein Dienstneustart erforderlich.

Schritt 5: WireGuard-Peer-Registrierung

Die CSR-Übermittlung auf /onboarding schlägt fehl, wenn Ihre Stargate-Instanz auf der HIN-CA-Seite noch nicht als WireGuard-Peer registriert ist. Dies ist das häufigste Problem während der Erstinstallation.

Die /installation-Seite des Dashboards übernimmt die WireGuard-Peer-Registrierung automatisch über den Nonce/HIN-Handshake. Wenn die automatische Registrierung fehlschlägt, kann eine manuelle Registrierung durchgeführt werden, indem Sie die folgenden Werte an HIN übermitteln:

1. WireGuard-öffentlicher Schlüssel — aus den Irisagent-Logs extrahieren:

docker compose logs irisagent | grep "public key"

1. DEPLOYMENT_NAME — aus Ihrer customer-config.sh
2. SERVER_STATIC_IP — die öffentliche IP Ihres Stargate-Servers
3. WG_INTERFACE_PORT — nur wenn Sie ihn vom Standard 19818 geändert haben

Nach Bestätigung der Peer-Registrierung:

Führen Sie die /onboarding-Seite im Dashboard erneut aus, um den CSR neu zu generieren und über den nun aktiven Tunnel zu übermitteln.

Um den Tunnel vor der Zertifikatsanforderung zu überprüfen:

Starten Sie nur irisagent neu

docker compose restart irisagent

Prüfen Sie auf erfolgreichen WireGuard-Handshake

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

Tip

Überprüfen Sie Ihre Firewall: Port 19818/TCP muss sowohl eingehend als auch ausgehend auf dem Stargate-Server geöffnet sein.

Schritt 6: Empfehlungen nach dem Onboarding

Sobald das Zertifikat ausgestellt ist und E-Mails fließen, werden zwei Konfigurationspunkte für jede Produktionsbereitstellung dringend empfohlen. Wenn Sie diese überspringen, wird die Verschlüsselung nicht beeinträchtigt, aber Ihr Absender-Ruf leidet, Outlook/Gmail zeigen "Wir können den Absender nicht überprüfen"-Warnungen an und dies kann letztendlich dazu führen, dass ausgehende E-Mails auf Blocklisten gesetzt werden.

Schritt 6.1 SPF / DKIM / DMARC für Absender-Domains

Stargate sendet E-Mails von seiner eigenen öffentlichen IP im Namen Ihrer Benutzer. Ohne korrekte DNS-Authentifizierungsdatensätze sehen Empfänger Warnungen wie "wir können diesen Absender nicht überprüfen" und können die E-Mail ablehnen.

Vollständige Anweisungen zur Konfiguration von SPF, DKIM, DMARC und PTR-Einträgen finden Sie im DNS-Einrichtungsleitfaden.

Mindestens für jede Domain, die Sie über Stargate routen:

• SPF: Fügen Sie ip4:<STARGATE_IP> zum TXT-Eintrag der Domain hinzu
• DMARC: Veröffentlichen Sie v=DMARC1; p=none unter _dmarc.<IHRER_DOMAIN>
• PTR: Setzen Sie das reverse DNS für die Stargate-IP so, dass es mit MAIL_HOSTNAME übereinstimmt

Schritt 6.2 Ausgehende E-Mails zurück über Ihre Mail-Plattform leiten (empfohlen für M365 / Exchange Online)

Standardmäßig liefert Stargate nach dem Signieren/Verschlüsseln einer ausgehenden E-Mail direkt an den MX des Empfängers. Das funktioniert, aber die verbindende IP ist die Ihres Stargate – und es sei denn, diese IP hat jahrelang einen guten Ruf aufgebaut, kann sie auf Blocklisten von Drittanbietern (z.B. Barracuda, Abusix) landen, was zu gelegentlichen Zustellfehlern führt.

Das empfohlene Muster ist, die signierte E-Mail zurück über Ihren M365-/Exchange-Mandanten zu senden, sodass der letzte Hop ins Internet die gut beleumundete Infrastruktur von Microsoft ist. Stargate signiert und prüft weiterhin jede Nachricht policy-gemäß; nur der letzte Hop ändert sich. Dies spiegelt das ursprüngliche "An MX senden"-Connector-Muster des HIN-MGW wider.

Stargate-Seite – pro-Domain-Relay

Konfigurieren Sie das pro-Domain-Relay über die /mail-Seite des Dashboards. Jede Domain kann ihrem eigenen M365-/Exchange-Eingangs-Endpunkt zugeordnet werden; das Dashboard sendet die Zuordnung an die REST-API von mtaconf und Stalwart wird zur Laufzeit neu konfiguriert.

Nachdem mxengine die E-Mail signiert hat, übergibt Stalwart sie an Ihren Mandanten auf Port 25 mit TLS, anstatt sie direkt an den MX des Empfängers zuzustellen. Siehe Exchange-integration.md für die vollständige pro-Domain-Syntax.

M365 / Exchange Online-Seite

Sie erstellen im Wesentlichen denselben Connector + Transportregeln-Satz wie beim alten HIN-MGW (das ursprüngliche HIN-MGW-O365-Handbuch ist die Referenz – die gleichen fünf Regeln gelten). Das Minimum ist:

1. Eingehender Connector – akzeptiert E-Mails von Stargate, identifiziert durch das TLS-Zertifikat (der Zertifikatsgegenstand muss mit einer in Ihrem Mandanten akzeptierten Domain übereinstimmen). Ein selbstsigniertes Zertifikat auf Stargate wird von diesem Connector abgelehnt – verwenden Sie ein gültiges, von einer CA ausgestelltes Zertifikat (Let's Encrypt ist in Ordnung).
2. Ausgehender Connector "An MX senden" – stellt an den MX des Empfängers zu, wird nur durch eine Transportregel aktiviert.
3. Transportregel set_header – kennzeichnet ausgehende E-Mails mit einem Header wie outgoing: outgoing_<domain>, bevor sie das erste Mal O365 verlassen, damit der Rückweg sie erkennen kann.
4. Transportregel outgoing_to_mx – erkennt den outgoing_<domain>-Header auf E-Mails, die von Stargate zurückkommen, und leitet sie über den "An MX senden"-Connector.
5. Transportregel mgw_bypass_antispam – umgeht die Spam-Filterung bei E-Mails, die von Stargate zurückkommen.

mxengine entfernt keine beliebigen Header, daher überlebt das von set_header gesetzte outgoing_<domain>-Tag den Rundlauf und löst outgoing_to_mx korrekt aus.

Warum dieses Muster wichtig ist

Bei der Relay-back-Konfiguration ist der öffentliche Absender für das Internet Microsoft. Kombiniert mit korrektem SPF/DKIM/DMARC (Abschnitt 6.1) sehen Empfänger eine Microsoft-IP mit spf=pass und dkim=pass, die auf Ihre Domain ausgerichtet sind – das beste Rufprofil, das Sie ihnen bieten können.

Vollständige Schritt-für-Schritt-Anleitung inklusive Screenshots finden Sie in Exchange-integration.md.

Nachfolgende Starts (nach Neustart)

Der Installer aktiviert eine stargate-Systemd-Einheit, sodass der Stack beim Booten automatisch startet. Um ihn manuell zu starten:

sudo systemctl start stargate

Dies führt start.sh aus, das:

1. Infrastrukturdienste startet
2. Vault mit den gespeicherten Schlüsseln entsiegelt
3. Anwendungsdienste startet

(./scripts/start.sh funktioniert weiterhin direkt, wenn Sie das bevorzugen.)

Dienste anhalten

sudo systemctl stop stargate

(oder direkt ./scripts/stop.sh)

Dies hält Container an, bewahrt aber alle Daten.

Datenpersistenz

Alle Daten werden in Docker-Volumes gespeichert und bleiben über Neustarts hinweg erhalten.

Dienst	Volume	Daten
PostgreSQL	postgres_data	Alle Datenbanken (smimekeys, policy, irisagent, mxengine)
Vault	vault_data	Verschlüsselungsschlüssel, Secrets, S/MIME-Schlüssel
SeaweedFS	seaweedfs_data	Objektspeicher (Nachrichten, Anhänge)
Stalwart	stalwart_data	Mail-Server-Zustand

Sichere Operationen (Daten bleiben erhalten)

Anhalten und starten:

sudo systemctl stop stargate
sudo systemctl start stargate

Oder direkt mit den Skripten:

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

Verwenden Sie keine docker compose-Befehle direkt

Verwenden Sie immer systemctl oder die bereitgestellten Skripte (start.sh / stop.sh), um die Bereitstellung zu verwalten. Die direkte Ausführung von docker compose up, docker compose down oder docker compose restart entsiegelt Vault nicht, sodass abhängige Dienste nicht starten können. Das start.sh-Skript übernimmt die Vault-Entsiegelung automatisch.

Vault-Siegelverhalten

Vault wird versiegelt, wenn sein Container neu startet. Dies ist ein Sicherheitsmerkmal.

Das start.sh-Skript (und der Systemd-Dienst) entsiegeln Vault automatisch mit den in secrets/vault-keys.json gespeicherten Schlüsseln. Deshalb müssen Sie immer die bereitgestellten Skripte oder den Systemd-Dienst zur Verwaltung des Stacks verwenden.

Zerstörerische Operationen (Daten gelöscht)

Warning

Diese Befehle LÖSCHEN ALLE DATEN – mit Vorsicht verwenden!

Sie können Daten nur wiederherstellen, wenn Sie vorher Backup-Operationen durchführen und das Backup an einem sicheren Ort aufbewahren.

Danger

Alles löschen (Volumes, Secrets, Konfiguration)

./scripts/purge.sh

Skriptübersicht

Skript	Zweck
install.sh	Erstinstallation (Docker, Vault). Domain-/Zertifikats-/Peer-Setup erfolgt anschließend im Dashboard.
update.sh	Service-Images aktualisieren (Vault-Token bleibt erhalten, Container werden neu erstellt)
start.sh	Dienste starten und Vault entsiegeln
stop.sh	Container anhalten (Daten bleiben erhalten)
backup.sh	Vollständiges Backup (Datenbank, Vault-Schlüssel, Konfiguration, Zertifikate)
restore.sh	Aus einem Backup-Archiv wiederherstellen (funktioniert auf neuem System)
purge.sh	ALLE Daten löschen (erfordert Bestätigung)
health-check.sh	Umfassende Gesundheitsprüfung aller Dienste (Exit 0 = gesund, 1 = Fehler)
init-vault.sh	Vault-Initialisierung (wird vom vault-init-Container verwendet, nicht direkt aufrufen)
init-keycloak.sh	Keycloak-Admin-Passwort-Setup (wird vom keycloak-init-Container verwendet, nicht direkt aufrufen)
gather-app-versions.sh	Sammelt App-Versionen von /liveness-Endpunkten für node-exporter (läuft im version-collector-Container)

Konfigurationsdateien

Datei	Zweck
customer-config-prod.example.sh	Vorlage für Kundeneinstellungen (kopieren nach customer-config.sh)
customer-config.sh	Kundenspezifische Einstellungen (aus Vorlage erstellt, vor der Installation ausfüllen)
.env	Generierte Umgebungsdatei (wird von install.sh erstellt)
secrets/vault-keys.json	Vault-Entsiegelungsschlüssel und Root-Token (sicher sichern!)
secrets/signing-key.csr	Generierter CSR für das S/MIME-Zertifikat

Support

Support

Bei Fragen oder Problemen im Zusammenhang mit der Bereitstellung und dem Betrieb der Stargate-Appliance wenden Sie sich bitte an den HIN-Support.

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs hinzu, um die Bearbeitung Ihres Anliegens zu beschleunigen.

Stargate Docker erweiterte Konfiguration

Backups

Automatische Backups

• Tägliche Backups um 2:00 Uhr morgens via Cron (während der Installation eingerichtet)
• Backups werden in ./backups/ als mit Zeitstempel versehene .tar.gz-Dateien gespeichert
• Alte Backups (>7 Tage) werden automatisch bereinigt

Was in Backups enthalten ist

• Vollständiger PostgreSQL-Dump (alle Datenbanken mit Benutzern und Berechtigungen)
• Individuelle Datenbank-Dumps (für eine teilweise Wiederherstellung, falls erforderlich)
• Vault-Schlüssel (vault-keys.json zum Entsiegeln)
• Kundenkonfiguration (customer-config.sh mit WireGuard-Schlüssel)
• S/MIME-CSR und Zertifikate (alle .crt, .pem, .cer-Dateien)
• Backup-Manifest (manifest.json mit Metadaten)

Manuelles Backup

./scripts/backup.sh

Erstellt ein komprimiertes Archiv in ./backups/YYYYMMDD_HHMMSS.tar.gz.

Wiederherstellung aus einem Backup

Zur Wiederherstellung auf einem neuen System oder nach einer Bereinigung. Kopieren Sie das Backup-Archiv auf das neue System und führen Sie es aus:

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

Das Wiederherstellungsskript wird:

1. Alle laufenden Dienste anhalten
2. Das Backup extrahieren und validieren
3. Docker installieren, falls erforderlich
4. Die Kundenkonfiguration wiederherstellen
5. Die Infrastrukturdienste starten (PostgreSQL, Vault, MinIO)
6. Die Datenbank wiederherstellen
7. Vault mit den gesicherten Schlüsseln entsiegeln
8. Die Anwendungsdienste starten

Teilweise Wiederherstellung (einzelne Datenbank)

Wenn Sie nur eine Datenbank wiederherstellen müssen:

Backup extrahieren

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

Eine bestimmte Datenbank wiederherstellen

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

Stargate aktualisieren

Bereitstellungsskripte und Konfiguration aktualisieren

Das Stargate-Bereitstellungs-Repository erhält Aktualisierungen für Skripte (install.sh, start.sh, health-check.sh, restore.sh, usw.), Konfigurationsvorlagen und Dokumentation. Um diese Aktualisierungen zu übernehmen:

1. Erstellen Sie ein Backup vor der Aktualisierung

./scripts/backup.sh

2. Die neuesten Änderungen abrufen und anwenden

Das Repository ist die alleinige Quelle der Wahrheit für nachverfolgte Dateien. Aktualisieren Sie daher, indem Sie auf die neueste Revision zurücksetzen. Dadurch werden nachverfolgte Dateien (Skripte, docker-compose.yml, Konfigurationsvorlagen) durch die Versionen aus dem Repository ersetzt:

git fetch origin
git reset --hard origin/main

3. Dienste neu starten, um Skript- oder Konfigurationsänderungen zu übernehmen

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

Note

Ihre customer-config.sh, .env und das secrets/-Verzeichnis befinden sich in .gitignore und werden dadurch nicht verändert - Ihre Konfiguration und Anmeldedaten bleiben erhalten. Nehmen Sie Anpassungen immer in customer-config.sh vor, niemals durch Bearbeiten nachverfolgter Dateien wie docker-compose.yml: Ein Hard-Reset - und die vom Dashboard ausgelösten automatischen Updates - setzt jede Änderung an nachverfolgten Dateien zurück. Das ist beabsichtigt; dass jede Bereitstellung mit dem Repository identisch bleibt, ist die Voraussetzung dafür, dass Updates zuverlässig und ohne manuelle Konfliktlösung angewendet werden.

Wenn das Update Änderungen an der Konfigurationsvorlage enthält, vergleichen Sie diese mit Ihrer vorhandenen Konfiguration, um zu sehen, ob neue Variablen hinzugefügt wurden:

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

Service-Images aktualisieren

Anwendungsversionen werden ausschließlich über das Dashboard verwaltet. Jede Version ist ein versioniertes Manifest, das eine bekannte, getestete Kombination aller Dienstversionen zusammen festlegt; die Update-Seite des Dashboards listet die verfügbaren Releases auf, und beim Anwenden eines Releases werden die passenden Images gepullt und die betroffenen Dienste für Sie neu erstellt.

So aktualisieren Sie:

1. Öffnen Sie das Dashboard und gehen Sie zur Update-Seite.
2. Wählen Sie das gewünschte Release aus.
3. Bestätigen Sie - das Dashboard wendet das Release-Manifest an und erstellt die geänderten Dienste neu.

Ändern Sie Versionen nicht von Hand

Bearbeiten Sie einzelne *_VERSION-Werte in customer-config.sh oder .env nicht, um Anwendungen zu aktualisieren. Versionen werden als Satz gemeinsam veröffentlicht und getestet - eine einzelne von Hand auszuwählen ergibt eine ungetestete Kombination, und die Änderung würde beim nächsten Dashboard-Update ohnehin zurückgesetzt. Aktualisieren Sie immer über das Dashboard.

Alte Images bereinigen

Nach den Updates entfernen Sie nicht verwendete Images, um Speicherplatz freizugeben:

docker image prune -f

Rollback

Um ein Rollback durchzuführen, wählen Sie auf der Update-Seite des Dashboards ein früheres Release aus und wenden Sie es an - derselbe Mechanismus läuft rückwärts und legt den vorherigen getesteten Satz fest. Führen Sie kein Rollback durch, indem Sie Versionen von Hand bearbeiten.

Konfiguration

Die .env-Datei wird von install.sh aus customer-config.sh generiert. Domain-, Zertifikats- und WireGuard-Einstellungen werden zur Laufzeit über das Dashboard (/installation, /onboarding, /mail) verwaltet – sie werden nicht in .env gespeichert. Um die Installationszeiteinstellungen anzupassen, bearbeiten Sie customer-config.sh und führen Sie install.sh erneut aus.

Wichtige Abschnitte in der generierten .env:

## PostgreSQL (automatisch generiert, falls in customer-config.sh leer)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<automatisch-generiert>

## Vault (nach der Initialisierung automatisch ausgefüllt)
VAULT_TOKEN=<automatisch-generiert>

## S3 Object Storage (SeaweedFS)
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=<automatisch-generiert>

## Anwendungsversionen
SMIMEKEYS_VERSION=v0.0.5
POLICY_VERSION=v0.0.5
IRISAGENT_VERSION=v0.0.6-branch
MXENGINE_VERSION=v0.0.35
MTACONF_VERSION=dev

## Mail Outbound Pfad
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

Bearbeiten Sie .env nicht direkt. Änderungen werden bei erneuter Ausführung von install.sh überschrieben. Für die Laufzeitkonfiguration (Domains, Hostname, Peers, S/MIME) verwenden Sie das Dashboard.

Service-URLs

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

Health Checks

Alle Dienste machen einen /liveness-Endpunkt verfügbar:

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

Überwachung

Prometheus-Metriken

Alle Anwendungsdienste machen Prometheus-Metriken intern auf Port 2112 verfügbar, die verschiedenen Host-Ports zugeordnet sind:

Service	Metrik-Port	Metrik-URL
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

Prometheus Scrape Konfigurationsbeispiel

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

Schnelle Metrik-Überprüfung

## Alle Metrik-Endpunkte prüfen
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

Log-Sammlung (Alloy → Loki)

Alloy sammelt Logs von Anwendungscontainern und sendet sie an Loki.

Überwachte Container:

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

Konfiguration in .env:

## Loki Push-URL
LOKI_URL=https://loki.example.com

## Hostname-Label für Logs (automatisch auf DEPLOYMENT_NAME gesetzt)
ALLOY_HOSTNAME=stargate-acme

Zu Logs hinzugefügte Labels:

• environment=<DEPLOYMENT_NAME> - Identifiziert die Bereitstellung
• host=<ALLOY_HOSTNAME> - Identifiziert den Host (gleich wie Bereitstellungsname)
• container=<container-name> - Containername
• service=<service-name> - Dienstname (z.B. smimekeys-client, policy)
• level=<log-level> - Aus JSON-Logs extrahiert, falls verfügbar

Logs in Grafana abfragen:

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

Überprüfen, ob Alloy funktioniert:

Alloy-Status und letzte Aktivität prüfenHealth-Probe (aus dem Docker-Netzwerk)

docker logs stargate-alloy

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

Hinweis: Die öffentliche IP der VM muss in der Ingress-Konfiguration von Loki auf die Whitelist gesetzt werden.

Stalwart MTA + mtaconf

Stargate verwendet Stalwart als Mail Transfer Agent und mtaconf als Konfigurations-Daemon. Das Dashboard sendet Domain- und Relay-Konfiguration an die REST-API von mtaconf, die diese dann über die Verwaltungs-CLI an Stalwart weitergibt.

Mail-Fluss-Architektur

Externer Mail-Server
         │
         ▼ (Port 25)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Port 25 (smtp listener)                            │
│    │                                                │
│    ▼                                                │
│  content_filter → smtp:[mxengine]:1587              │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (Port 1587)
┌─────────────────────────────────────────────────────┐
│ MXEngine (stargate-mxengine)                        │
│                                                     │
│  Port 1587 (SMTP input)                             │
│    │                                                │
│    ▼                                                │
│  E-Mail signieren/verschlüsseln/verarbeiten         │
│    │                                                │
│    ▼                                                │
│  Zurück an stalwart zur Weiterleitung               │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (Port 10026)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Port 10026 (reinject listener)                     │
│    │                                                │
│    ▼                                                │
│  transport → relay to destination MX                │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (Port 25)
Ziel-Mail-Server (via MX-Lookup)

Antiviren-Scan: Eingehende E-Mails werden von ClamAV (stargate-clamav) gescannt, das als Milter in die SMTP-DATA-Phase sowohl beim öffentlichen (:25) als auch beim Reinjektions- (:10026) Listener eingebunden ist. Infizierte E-Mails werden auf SMTP-Ebene abgewiesen; wenn ClamAV nicht erreichbar ist, wird die Nachricht zurückgestellt anstatt ungescannt zugestellt (Fail-Closed). Die Signaturdatenbank von ClamAV befindet sich im clamav_data-Volume und wird von freshclam im Hintergrund aktuell gehalten.

Seal-Callback-Fluss (eingehend): Wenn ein entferntes Sealer-Gerät eine versiegelte Nachricht zustellen muss, ruft es MXENGINE_PUBLIC_ADDRESS auf (Standard: http://<SERVER_STATIC_IP>:8084). Das http://-Protokoll ist korrekt – TLS ist nicht erforderlich, da die Seal-Nutzlast bereits verschlüsselt ist.

Mail-Relay-Konfiguration

Die gesamte Mail-Konfiguration, die pro Bereitstellung variiert (Mail-Domains, Hostname, Relay-Host, pro-Domain-Relay-Maps, erlaubte Netzwerke), wird zur Laufzeit über die /mail-Seite des Dashboards festgelegt. Das Dashboard sendet die Konfiguration per POST an die REST-API von mtaconf, die sie auf Stalwart anwendet, ohne den Container neu starten zu müssen.

Es gibt keine pro-Domain-Konfiguration in customer-config.sh oder .env – Betreiber fügen Domains über die Benutzeroberfläche hinzu oder ändern sie.

Mail-Routing (Migration von altem MGW)

Wichtiger Unterschied zum alten HIN-MGW

Im alten MGW mussten Sie manuell einen Zielserver pro Domain konfigurieren. In Stargate wird das Mail-Routing standardmäßig durch DNS-MX-Einträge entschieden – Stalwart löst zur Zustellzeit die MX jeder Domain auf. Die /mail-Seite des Dashboards ermöglicht es Ihnen, dies pro Domain zu überschreiben (z.B. um zurück zu Ihrem M365-/Exchange-Mandanten weiterzuleiten), ohne DNS ändern zu müssen.

Standard – automatisch via DNS MX:

Stellen Sie für jede Ihrer Domains sicher, dass es einen MX-Eintrag im DNS gibt, der auf den entsprechenden Exchange- (oder anderen Mail-) Server verweist:

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

Dies funktioniert für beliebig viele Domains – jede Domain kann auf einen anderen Mail-Server verweisen, und Stalwart leitet entsprechend weiter.

Wenn Stargate der einzige MX-Eintrag für eine Domain ist, filtert Stalwart diesen heraus und hat kein Zustellziel. Fügen Sie einen zweiten MX-Eintrag hinzu, der auf Ihren Mail-Server verweist, mit einer höheren Priorität (= niedrigere Zahl), damit Stalwart ihn als Zustellziel verwendet:

example.com    MX 10  exchange.example.com      ← Zustellziel (Mail-Server)
example.com    MX 20  stargate.example.com      ← Eingangs-Gateway (Stargate)

Alternative – explizites pro-Domain-Relay (senderbasiert):

Für die Weiterleitung zurück über M365 / Exchange Online konfigurieren Sie pro-Domain-Relay-Ziele über die /mail-Seite des Dashboards. E-Mails von Absendern, die nicht in der Map enthalten sind, fallen auf die MX-Lookup zurück.

Ports

Port	Zweck
25	Haupt-SMTP-Listener (externe Verbindungen)
10026	Reinjektionsport (mxengine → stalwart, nur intern)
1587	MXEngine SMTP-Eingang (stalwart → mxengine, nur intern)
8080	Stalwart-Verwaltungs-API + mtaconf-REST-API (nur intern)

Verwenden Sie Exchange?

Siehe Exchange-Integration für die vollständige Einrichtung von Exchange Online / On-Premises-Connectoren und Transportregeln.

Überprüfung

Stalwart-Status prüfen

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

Logs prüfen

docker logs stargate-stalwart

Verbindung zu Port 25 testen

telnet localhost 25

Internen Port 10026 testen (vom mxengine-Container aus)

docker exec stargate-mxengine nc -zv stalwart 10026

Das mtaconf-Image aktualisieren

Wie jeder Dienst ist die mtaconf-Image-Version Teil eines Releases und wird über das Dashboard aktualisiert - nicht durch manuelles Bearbeiten des Tags. Wählen Sie auf der Update-Seite des Dashboards das gewünschte Release aus, um es anzuwenden.

Stargate-Fehlerbehebung

E-Mail wird nicht von mxengine verarbeitet:

• Prüfen Sie, ob content_filter konfiguriert ist: Überprüfen Sie die mtaconf-Logs auf erfolgreichen Push
• Stellen Sie sicher, dass mxengine erreichbar ist: docker exec stargate-stalwart nc -zv mxengine 1587

E-Mail bleibt nach der mxengine-Verarbeitung hängen:

• Prüfen Sie die mxengine-Outbound-Konfiguration: OUTBOUND_SMTP_HOST=stalwart, OUTBOUND_SMTP_PORT=10026
• Stellen Sie sicher, dass der Port-10026-Listener in Stalwart aktiv ist
• Prüfen Sie die erlaubten Relay-Netzwerke, ob sie das Docker-Netzwerk (172.x.x.x/16) enthalten

Greylisting-Fehler (450 4.7.1):

• Das ist normal! Der Zielserver lehnt die E-Mail vorübergehend ab
• Stalwart wiederholt den Vorgang automatisch nach einer konfigurierbaren Verzögerung
• Prüfen Sie die Warteschlange über die Verwaltungs-API

Microsoft blockiert IP (S3140):

• Die IP Ihres Servers hat einen schlechten Ruf bei Microsoft
• Fordern Sie die Delistung an unter: https://sender.office.com
• Kann 24-48 Stunden dauern, bis sie wirksam wird

DNS-Lookup-Fehler:

• Verwenden Sie die /mail-Seite des Dashboards, um einen expliziten Relay-Host oder eine pro-Domain-Relay-Map festzulegen (überspringt die MX-basierte Erkennung)

Verbindungsverweigerung auf Port 25:

• Stellen Sie sicher, dass Port 25 nicht durch die Firewall blockiert wird
• Prüfen Sie, ob ein anderer Dienst Port 25 verwendet: ss -tlnp | grep :25

WireGuard (Agent-zu-Agent-Kommunikation)

IRISAgent verwendet WireGuard, um sichere verschlüsselte Tunnel zwischen Stargate-Instanzen für die Zustellung versiegelter Nachrichten einzurichten.

Wie es funktioniert

Jede Stargate-Instanz verwendet die reale statische öffentliche IP des Servers als WireGuard-Tunneladresse. Dies garantiert Eindeutigkeit über alle Bereitstellungen hinweg ohne manuelle Koordination.

block
columns 5
  block:Stargate["Ihr Stargate (203.0.113.50)"]:2
    columns 1
    A
    space
    A --> B
    A["IRISAgent (203.0.113.50:19818)"]
    B["Zustellung versiegelter Nachrichten über WG-Tunnel"]
  end

  blockArrowId1<["WG Tunnel (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["Versiegelte Nachricht empfangen"]
  end

WireGuard-Konfiguration

WireGuard-Einstellungen in customer-config.sh:

## ==============================================================================
## Server-IP – wird als WireGuard-Tunneladresse und MXEngine-Callback-URL verwendet
## ==============================================================================
SERVER_STATIC_IP="203.0.113.50"       # Die reale statische öffentliche IP Ihres Servers

## ==============================================================================
## WireGuard lokale Einstellungen (normalerweise bei Standardwerten belassen)
## ==============================================================================
WG_PRIVATE_KEY=""                     # Wird von IRISAgent automatisch generiert und dann zurück in die Konfiguration gespeichert
WG_INTERFACE_PORT="19818"             # Standard-WireGuard-Port
WG_TRANSPORT_MODE="tcp"               # "tcp" (Standard) oder "udp"

Info

WG_LOCAL_IP wird automatisch von SERVER_STATIC_IP abgeleitet. Sie müssen es nicht separat festlegen.

Peer-Verbindung einrichten

WireGuard-Peer-Details (öffentlicher Schlüssel, Endpunkt, erlaubte IPs usw.) werden zur Laufzeit über die /installation-Seite des Dashboards konfiguriert. Es gibt keinen WG_PEER_*-Block mehr in customer-config.sh – der Peer wird eingerichtet, nachdem der Stack gestartet ist.

Für die erstmalige Einrichtung mit der HIN-Testumgebung:

1. Starten Sie den Stack mit ./scripts/install.sh.
2. Öffnen Sie das Dashboard, folgen Sie /installation, um den Nonce/HIN-Handshake zu starten.
3. Öffnen Sie die IRISAgent-Logs (docker compose logs irisagent) und kopieren Sie die Zeile wireguard public key:. Senden Sie sie zusammen mit DEPLOYMENT_NAME und SERVER_STATIC_IP an Vereign (kalin.canov@vereign.com), damit sie Ihren Peer auf der CA-Seite registrieren können.
4. Nachdem Vereign die Registrierung bestätigt hat, schließen Sie /onboarding im Dashboard ab, um das S/MIME-Zertifikat auszustellen.

Für jeden zusätzlichen Peer (Peer-to-Peer zwischen zwei Stargates) tauschen Sie öffentliche Schlüssel + Endpunkte mit der anderen Partei aus und fügen die Verbindung über die IRISAgent-API hinzu:

curl --location 'localhost:8083/v1/connections' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "allowedIps": "<IP des neuen Peers>/32",
  "description": "<kurze Beschreibung>",
  "endpoint": "<IP des neuen Peers>:19818",
  "externalId": [
    "<Domain des neuen Peers>"
  ],
  "name": "<Name des neuen Peers>",
  "presharedKey": "",
  "publicKey": "<öffentlicher Schlüssel des neuen Peers>",
  "status": "completed",
  "transport": "tcp",
  "wireguardIp": "<IP des neuen Peers>",
  "wireguardPort": 10080
}'

WireGuard-Überprüfung

IRISAgent-WireGuard-Schnittstelle prüfen

docker exec stargate-irisagent wg show

Verbindung in der Datenbank prüfen

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

Verbindungs-Externe-IDs prüfen (für Routing verwendet)

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

WireGuard-Konnektivität testen (Tunnelstatus vom Host aus prüfen)

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

IRISAgent-Logs auf Tunnelaktivität prüfen

docker logs stargate-irisagent | grep -i wireguard

WireGuard-Fehlerbehebung

Keine WireGuard-Schnittstelle:

• IRISAgent-Logs prüfen: docker logs stargate-irisagent
• Stellen Sie sicher, dass WG_LOCAL_IP in .env gesetzt ist (automatisch von SERVER_STATIC_IP abgeleitet – sollte die statische öffentliche IP dieses Servers sein)

Peer nicht erreichbar:

• Stellen Sie sicher, dass der entfernte Endpunkt erreichbar ist: nc -zv <endpoint_host> <endpoint_port>
• Prüfen Sie, ob die Firewall TCP+UDP Port 19818 erlaubt
• Stellen Sie sicher, dass die öffentlichen Schlüssel auf beiden Seiten übereinstimmen
• Wenn TCP Probleme bereitet, versuchen Sie, WG_TRANSPORT_MODE="udp" in customer-config.sh zu setzen

Verbindung nicht in der Datenbank:

• Führen Sie die /installation-Seite des Dashboards erneut aus, um die Peer-Verbindung neu herzustellen
• Prüfen Sie die Irisagent-Logs: docker logs stargate-irisagent

Policy Sync

Der policy-sync-Dienst synchronisiert automatisch OPA/Rego-Richtlinien aus einem Git-Repository in die PostgreSQL-Datenbank.

Wie Policy Sync funktioniert

block
columns 8
  A:2 space B:2 space C:2
  A["Git Repository

      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"]

Policy-Sync-Konfiguration

Einstellungen in customer-config.sh:

## Git-Repository mit Richtlinien (vorkonfiguriert mit HIN Stargate-Richtlinien)
POLICY_SYNC_REPO_URL="https://github.com/Health-Info-Net-AG/Stargate-policies.git"

## Optional: Authentifizierung für private Repositories
POLICY_SYNC_REPO_USER=""
POLICY_SYNC_REPO_PASS=""

## Optional: Bestimmter Branch (Standard: main)
POLICY_SYNC_REPO_BRANCH=""

## Optional: Unterordner im Repository, der die Richtlinien enthält
POLICY_SYNC_REPO_FOLDER=""

## Synchronisierungsintervall (Standard: 1h)
POLICY_SYNC_INTERVAL="1h"

Policy-Sync-Überprüfung

Policy-Sync-Status prüfenSynchronisierte Richtlinien anzeigenInhalt einer bestimmten Richtlinie anzeigen

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';"

Manueller Auslöser

Um eine sofortige Synchronisierung zu erzwingen:

docker restart stargate-policy-sync

Vault

Vault-Mounts

Der Vault-API/UI-Port (8200) wird nicht an den Host veröffentlicht; greifen Sie über die CLI innerhalb des Containers auf Vault zu (siehe Manuelle Vault-Operationen unten).

Die folgenden KV-v2-Secret-Engines werden erstellt:

• secret-smimekeys-client
• secret-policy
• secret-irisagent
• secret-mxengine
• secret-mtaconf

Manuelle Vault-Operationen

Status prüfenMounts auflistenEin Secret schreiben

docker exec stargate-vault vault status

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

docker exec -e VAULT_TOKEN=<token> stargate-vault vault kv put secret-smimekeys-client/test key=value

Datenbanken

Erstellte PostgreSQL-Datenbanken:

• smimekeys_client
• policy
• irisagent
• mxengine

Mit PostgreSQL verbinden

docker exec -it stargate-postgres psql -U postgres

Oder extern verbinden

psql -h localhost -U postgres -d smimekeys_client

Richtlinien (Rego)

MXEngine verwendet OPA/Rego-Richtlinien, die in PostgreSQL gespeichert sind, um die Mail-Zustellungsstrategie zu bestimmen.

Empfohlen: Verwenden Sie policy-sync, um Richtlinien automatisch aus einem Git-Repository zu synchronisieren. Siehe Abschnitt Policy Sync.

Aktuelle Richtlinie anzeigen

Alle Richtlinien auflistenRichtlinieninhalt anzeigen

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';"

Richtlinien-Speicherort

• MXEngine-Konfiguration: POLICY_OUTBOUND: "outbound/delivery"
• Datenbank: policy-Datenbank, policies-Tabelle
• Verwaltet durch: policy-sync-Dienst (synchronisiert aus Git-Repository)

Logs

Alle DiensteBestimmter Dienst

docker compose logs -f

docker compose logs -f <service>

Z.B.:

docker compose logs -f smimekeys-client
docker compose logs -f vault

Fehlerbehebung

Zertifikatsausstellung fehlgeschlagen / WireGuard-Tunnel nicht eingerichtet

Dies ist das häufigste Problem nach der ersten Installation. Das S/MIME-Zertifikat kann nicht ausgestellt werden, weil der WireGuard-Tunnel zur HIN-CA nicht eingerichtet ist.

Symptome:

• Die /onboarding-Seite des Dashboards meldet einen Fehler bei der CSR-Übermittlung
• smimekeys-client-Logs zeigen: issue certificate error: certcatunnel: error sending request: irisagent: ... context deadline exceeded

Ursachen (in dieser Reihenfolge prüfen):

1. Peer nicht auf der HIN-CA registriert – Ihr öffentlicher WireGuard-Schlüssel muss auf der HIN-Seite registriert sein. Geben Sie HIN Folgendes:

# Ihren öffentlichen WireGuard-Schlüssel abrufen
docker compose logs irisagent | grep "public key"

Zusammen mit Ihrem DEPLOYMENT_NAME, SERVER_STATIC_IP und WG_INTERFACE_PORT (falls von 19818 abweichend).

1. Firewall blockiert Port 19818 – Stellen Sie sicher, dass 19818/TCP sowohl eingehend als auch ausgehend auf dem Stargate-Server geöffnet ist.

2. Falscher Hostname – Wenn der Stalwart-Hostname noch auf den Vorlagenstandard (mail.example.com) gesetzt ist, aktualisieren Sie ihn über die /mail-Seite des Dashboards.

Nachdem das Problem behoben ist:

Öffnen Sie die /onboarding-Seite des Dashboards erneut, um den CSR neu zu generieren und über den nun aktiven Tunnel erneut zu übermitteln.

Siehe Schritt 5: WireGuard-Peer-Registrierung für den vollständigen Ablauf.

Vault ist nach dem Neustart versiegelt

Führen Sie das Startskript aus, das die Entsiegelung übernimmt:

./scripts/start.sh

Images können nicht gepullt werden

Melden Sie sich bei der Registry an:

docker login hub.docker.com

Dienst startet nicht

Logs prüfen:

docker compose logs <service-name>

Alles zurücksetzen

Warning

Diese Befehle LÖSCHEN ALLE DATEN – mit Vorsicht verwenden!

Sie können Daten nur wiederherstellen, wenn Sie vorher Backup-Operationen durchführen und das Backup an einem sicheren Ort aufbewahren.

./scripts/purge.sh
./scripts/install.sh

Dateistruktur

stargate/
├── backups/                      # Vollständige Backups (gitignoriert)
│   └── *.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          # Alloy-Logversand-Konfiguration
│   └── vault
│       └── vault.hcl             # Vault-Konfiguration
├── customer-config-prod.example.sh     # Konfigurationsvorlage (kopieren nach customer-config.sh)
├── customer-config.sh            # Kundenspezifische Einstellungen (aus der Vorlage kopiert)
├── docker-compose.yml            # Haupt-Compose-Datei
├── .env                          # Umgebungsvariablen (von install.sh generiert)
├── init
│   └── postgres
│       └── 01-create-databases.sql
├── scripts
│   ├── backup.sh                 # Vollständiges Backup (DB, Vault, Konfiguration, Zertifikate)
│   ├── gather-app-versions.sh    # Sammelt App-Versionen für node-exporter-Metriken
│   ├── health-check.sh           # Umfassende Gesundheitsprüfung aller Dienste
│   ├── init-keycloak.sh
│   ├── init-vault.sh             # Vault-Initialisierung (vom vault-init-Container verwendet)
│   ├── install.sh                # Erstinstallation (Docker, Vault). Domain-/Zertifikats-/Peer-Setup erfolgt anschließend im Dashboard.
│   ├── purge.sh                  # Alle Daten löschen (zerstörerisch!)
│   ├── restore.sh                # Aus einem Backup-Archiv wiederherstellen
│   ├── send-logs-to-support.sh   # Logs online einfügen und einen Link erhalten, den Sie dem Support bereitstellen
│   ├── start.sh                  # Dienste starten + Vault entsiegeln
│   ├── stop.sh                   # Container anhalten (Daten bleiben erhalten)
│   └── update.sh
└── secrets/                      # Bei der ersten Ausführung erstellt (gitignoriert)
    ├── vault-keys.json           # Vault-Entsiegelungsschlüssel (BACKUP DIESER DATEI!)
    └── signing-key.csr           # S/MIME-Zertifikatsignieranfrage

Schnelle Gesundheits- und Logprüfungen

Führen Sie die umfassende Gesundheitsprüfung durch

Schnelle GesundheitsprüfungAusführliche Ausgabe

./scripts/health-check.sh

./scripts/health-check.sh -v

Mit ausführlicher Ausgabe (zeigt WireGuard-Details, Liveness-Antworten).

Diese Prüfung umfasst:

• Alle Container-Status (laufend, gesund)
• Liveness-Endpunkte (smimekeys-client, policy, irisagent, mxengine)
• Vault-Siegelstatus
• PostgreSQL-Konnektivität und alle 4 Datenbanken
• MinIO-Gesundheit
• WireGuard-Tunnelstatus und Peer-Handshakes
• Stalwart MTA (läuft, Port 25, Port 10026)
• Prometheus-Metriken-Endpunkte
• Festplatten- und Speichernutzung

Für manuelle Log-Inspektion:

Logs prüfen (letzte 10 Zeilen)

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

Logs in Echtzeit verfolgen

docker logs -f stargate-mxengine

Alle Container-Status prüfen

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

Logs aller Container in Echtzeit verfolgen

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --timestamps -f {} 2>&1 | sed "s/^/[{}] /"'

Logs an den Support senden

Sie können Logs an unseren Support über pastebin.hin-infra.ch und den CLI-Befehl senden:

Logs aller Container hochladen:

AlleFür die letzte Stunde (1h)Letzte 500 Zeilen der Logs

Verwenden Sie unser Skript:

./scripts/send-logs-to-support.sh --all

Oder manuell ausführen:

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

Dieser Vorgang kann unsere Upload-Limits überschreiten – 20 Mb.

Verwenden Sie unser Skript:

./scripts/send-logs-to-support.sh --since 1h

Oder manuell ausführen:

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

Dies ist der Standard

--tail 500 ist der Standardwert für unser Skript, Sie können es aber trotzdem angeben.

Verwenden Sie unser Skript:

./scripts/send-logs-to-support.sh --tail 500

Oder manuell ausführen:

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

Logs bestimmter Container hochladen:

AlleFür die letzte Stunde (1h)Letzte 500 Zeilen der Logs

docker logs <CONTAINER_NAME> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

Tip

Dieser Vorgang kann unsere Upload-Limits überschreiten – 20 Mb. Falls dies passiert, versuchen Sie, die Logmenge durch Festlegen einer Zeitbegrenzung oder Zeilenanzahl zu reduzieren.

docker logs --since 1h <CONTAINER_NAME> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

docker logs --tail 500 <CONTAINER_NAME> 2>&1 | curl https://pastebin.hin-infra.ch/ --data-binary @-

Danach erhalten Sie einen eindeutigen Link im Format https://pastebin.hin-infra.ch/<20 Symbole>, den Sie dem Support / Ticket bereitstellen können.

Warning

Die Ablaufzeit ist auf 30 Tage eingestellt. Wenn Teile der Logs oder die Logs selbst für einen längeren Zeitraum aufbewahrt werden müssen, bewahren Sie bitte eine Kopie davon auf.

Helm-Bereitstellung

Info

Demnächst verfügbar

Diese Datei enthält Anweisungen für die Helm-Bereitstellung der HIN-MGW-Instanz.

VM-Bereitstellung

Stargate Azure Deployment mittels eines Images

Stargate auf Azure bereitstellen

Azure Port 25 (SMTP) Anforderungen

Warning

Bevor Sie mit der Installation auf Microsoft Azure beginnen, überprüfen Sie die folgenden Anforderungen in Bezug auf ausgehende SMTP-Konnektivität auf Port 25. Das Überspringen dieses Schritts kann nach der Installation zu E-Mail-Zustellungsfehlern führen.

Ob Port 25 verfügbar ist, hängt von Ihrem Azure-Abonnementtyp ab:

• Enterprise Agreement (EA) oder MCA-E – Ausgehender SMTP auf Port 25 ist nicht blockiert. Beachten Sie, dass externe Domänen E-Mails dennoch ablehnen können – dies liegt ausserhalb der Kontrolle von Azure.
• Enterprise Dev/Test – Standardmässig blockiert, kann aber entfernt werden. Um die Entfernung zu beantragen, gehen Sie zu Diagnose und Behebung > E-Mails können nicht gesendet werden (SMTP-Port 25) in der Azure Virtual Network-Ressource im Azure-Portal.
• Alle anderen Abonnementtypen – Blockiert und kann nicht entsperrt werden.

Referenz: Troubleshoot outbound SMTP connectivity in Azure

Image-Datei herunterladen

• Laden Sie die neueste VHD-Image-Datei herunter. Bitte beachten Sie VM Catalog

Azure VHD-Image-Datei hochladen

• Navigieren Sie zu https://portal.azure.com/#home
• Klicken Sie auf Storage accounts
• Wählen Sie das zu verwendende Speicherkonto aus oder erstellen Sie ein neues.
• Klicken Sie auf Block service und dann auf Containers
• Wählen Sie den Container aus, in den die Datei hochgeladen werden soll, oder erstellen Sie einen neuen, falls Sie keinen Container haben.
• Klicken Sie auf Upload und wählen Sie die VHD-Image-Datei aus.
• Stellen Sie sicher, dass der Blob-Typ Page Blob ist.

Image erstellen

• Navigieren Sie zu https://portal.azure.com/#home
• Klicken Sie auf Images
• Klicken Sie auf Create
• Wählen Sie die zu verwendende Ressourcengruppe oder erstellen Sie eine neue.
• Geben Sie einen Namen für das Image ein.
• Wählen Sie den OS-Typ Linux und VM-Generation Gen 2
• Bei Storage blob klicken Sie auf Browse und wählen Sie das neu hochgeladene VHD-Image aus.
• Klicken Sie auf Review and create
• Klicken Sie auf Create

VM erstellen

• Navigieren Sie zu https://portal.azure.com/#home
• Klicken Sie auf Virtual Machines
• Klicken Sie auf Create und wählen Sie Virtual Machine aus dem Dropdown-Menü.
• Wählen Sie die Ressourcengruppe
• Geben Sie einen Namen für die VM ein.
• Bei Image, klicken Sie auf "See all images", dann auf "My Images" und wählen Sie das neu erstellte Image aus.
• Wählen Sie die VM-Grösse.
• Wählen Sie den Authentifizierungstyp.
• Klicken Sie auf Next: Disks
• Wählen Sie eine OS-Disk-Grösse von mindestens 20 GiB. Bitte beachten Sie Server Requirements
• Klicken Sie auf Review + create
• Klicken Sie auf Create

Öffentliche IP-Adresse der neuen VM finden und eingehende Firewall-Regeln hinzufügen

• Navigieren Sie zu https://portal.azure.com/#home
• Klicken Sie auf Virtual Machines
• Klicken Sie auf die neue VM.
• Sie können die öffentliche IP-Adresse unter "Primary NIC public IP" sehen.
• Scrollen Sie nach unten zu Networking und klicken Sie darauf.
• Klicken Sie auf + Create port rule, Inbound port rule, Destination port ranges 25, Protocol TCP, benennen Sie es SMTP. Wiederholen Sie dies für den weiteren erforderlichen eingehenden Port — 19818 (WireGuard). Die vollständige Liste finden Sie unter Server-Anforderungen → Eingehender Netzwerkzugriff.

Zuerst die Data Disk anhängen

Hängen Sie vor dem ersten Start eine zweite, leere Festplatte mit mindestens 30 GB an. Beim ersten Start formatiert die Appliance sie als Data Disk (VEREIGN-DATA, gemountet unter /var/data) und speichert dort die gesamte Konfiguration und alle Daten; ohne sie schlägt der Start fehl und wird zurückgerollt. Siehe Installationsanleitung → Schritt 4.

HIN Gateway installieren

Nach erfolgreicher Erstellung der VM fahren Sie mit den Installations- und Onboarding-Schritten fort, wie in den bereitgestellten Anweisungen beschrieben.

Support

Für Fragen oder Probleme im Zusammenhang mit der Bereitstellung und dem Betrieb der Stargate-Appliance wenden Sie sich bitte an den HIN-Support.

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs bei, um uns bei der effizienten Bearbeitung Ihrer Anfrage zu unterstützen.

Stargate VMware ESXi-Bereitstellung mittels eines Images

Stargate auf VMware bereitstellen

Image-Datei herunterladen

• Laden Sie die neueste OVA-(oder OVF- und VMDK-Datei, falls bevorzugt) Image-Datei herunter. Bitte beachten Sie VM Catalog

Navigieren Sie zur ESXi-Web-Benutzeroberfläche

• Klicken Sie auf Virtual Machines
• Klicken Sie auf Create/Register VM
• Wählen Sie "Deploy a virtual machine from an OVF or OVA file"
• Klicken Sie auf Next
• Geben Sie einen Namen für die VM ein.
• Klicken Sie auf Next
• Klicken Sie auf Select files und wählen Sie die OVA-Image-Datei (oder OVF und VMDK, falls bevorzugt)
• Klicken Sie auf Next
• Wählen Sie den zu verwendenden Speicher aus.
• Klicken Sie auf Next
• Wählen Sie Netzwerk und Disk für die Bereitstellung.
• Klicken Sie auf Next
• Klicken Sie auf Finish

Data Disk enthalten

Die OVA enthält bereits die Data Disk der Appliance (VEREIGN-DATA, gemountet unter /var/data) — es muss keine zusätzliche Festplatte angehängt werden. Siehe Installationsanleitung → Schritt 4.

HIN Gateway installieren

Nach erfolgreicher Erstellung der VM fahren Sie mit den Installations- und Onboarding-Schritten fort, wie in den bereitgestellten Anweisungen beschrieben.

Support

Für Fragen oder Probleme im Zusammenhang mit der Bereitstellung und dem Betrieb der Stargate-Appliance wenden Sie sich bitte an den HIN-Support.

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs bei, um uns bei der effizienten Bearbeitung Ihrer Anfrage zu unterstützen.

Proxmox-Bereitstellung mittels eines Images

Stargate auf Proxmox bereitstellen

URL der Image-Datei abrufen

• Bitte beachten Sie VM Catalog für eine Liste der Images mit URLs.
• Kopieren Sie die URL in die Zwischenablage, z. B. https://images.hin.ch/vm-images/hingateway_v0.0.0.x86_64.qcow2

Image-Datei in Proxmox importieren

• Navigieren Sie im Proxmox-WebUI zum Menü Storage und klicken Sie auf Import
• Klicken Sie auf Download from URL, fügen Sie die kopierte URL ein und klicken Sie auf "Query URL".
• Klicken Sie auf Download und warten Sie, bis "TASK OK" am Ende des Ausgabelogs erscheint.
• Schliessen Sie das Task Viewer Download-Fenster.

VM erstellen

• Klicken Sie auf "Create VM"
• Geben Sie einen Namen für die VM ein.
• Klicken Sie auf "Next"
• Wählen Sie "Do not use any media"
• Klicken Sie auf "Next"
• Klicken Sie auf "Next"
• Klicken Sie auf das "Trash icon" neben "scsi0", um es zu entfernen.
• Klicken Sie auf "Import" und wählen Sie unter "Select Image" die neu importierte Image-Datei aus.
• Klicken Sie auf "Next"
• Wählen Sie 4 CPU-Kerne und den CPU-Typ (oder verwenden Sie "host"). Bitte beachten Sie Server Requirements.
• Klicken Sie auf "Next"
• Wählen Sie 8192 MiB Memory. Bitte beachten Sie Server Requirements.
• Klicken Sie auf "Next"
• Klicken Sie auf "Next"
• Warten Sie, bis der VM-Erstellungsprozess abgeschlossen ist, klicken Sie dann auf die neue VM, klicken Sie auf "Console", dann auf "Start Now"

Zuerst die Data Disk anhängen

Hängen Sie vor dem ersten Start eine zweite, leere Festplatte mit mindestens 30 GB an. Beim ersten Start formatiert die Appliance sie als Data Disk (VEREIGN-DATA, gemountet unter /var/data) und speichert dort die gesamte Konfiguration und alle Daten; ohne sie schlägt der Start fehl und wird zurückgerollt. Siehe Installationsanleitung → Schritt 4.

HIN Gateway installieren

Nach erfolgreicher Erstellung der VM fahren Sie mit den Installations- und Onboarding-Schritten fort, wie in den bereitgestellten Anweisungen beschrieben.

Support

Für Fragen oder Probleme im Zusammenhang mit der Bereitstellung und dem Betrieb der Stargate-Appliance wenden Sie sich bitte an den HIN-Support.

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs bei, um uns bei der effizienten Bearbeitung Ihrer Anfrage zu unterstützen.

Windows 11 Pro-Bereitstellung mittels eines Images

Stargate auf Windows Pro bereitstellen (Nicht-Pro-Versionen unterstützen Hyper-V nicht)

Hyper-V installieren

• Klicken Sie auf den Start-Button und geben Sie "Windows-Features aktivieren oder deaktivieren" ein.
• Klicken Sie auf diesen Button.
• Aktivieren Sie Hyper-V und klicken Sie auf "OK".
• Nach Abschluss der Installation klicken Sie auf "Jetzt neu starten" und warten Sie, bis Windows neu startet.

Hinweis: Wir empfehlen, die VM mit Hyper-V Generation 2 bereitzustellen.

Image abrufen

• Laden Sie die .vhdx-Image-Datei herunter. Bitte beachten Sie VM Catalog

Image-Datei importieren und VM damit erstellen

• Klicken Sie auf den Start-Button und geben Sie "Hyper-V Quick Create" ein.
• Klicken Sie auf dieses Symbol.
• Wählen Sie "Lokale Installationsquelle".
• Deaktivieren Sie "Dieser Computer wird Windows ausführen".
• Klicken Sie auf "Installationsquelle ändern", navigieren Sie zur heruntergeladenen .VHDX-Image-Datei und klicken Sie darauf.
• Klicken Sie auf "Virtuellen Computer erstellen".
• Klicken Sie auf "Einstellungen bearbeiten".
• Unter "Speicher" wählen Sie "RAM" 8192 MB. Bitte beachten Sie Server Requirements.
• Unter "Prozessor" wählen Sie "Anzahl der virtuellen Prozessoren" 4. Bitte beachten Sie Server Requirements.
• Klicken Sie auf "OK".
• Klicken Sie auf "Verbinden".
• Klicken Sie auf "Starten".

Zuerst die Data Disk anhängen

Hängen Sie vor dem ersten Start eine zweite, leere Festplatte mit mindestens 30 GB an. Beim ersten Start formatiert die Appliance sie als Data Disk (VEREIGN-DATA, gemountet unter /var/data) und speichert dort die gesamte Konfiguration und alle Daten; ohne sie schlägt der Start fehl und wird zurückgerollt. Siehe Installationsanleitung → Schritt 4.

HIN Gateway installieren

Nach erfolgreicher Erstellung der VM fahren Sie mit den Installations- und Onboarding-Schritten fort, wie in den bereitgestellten Anweisungen beschrieben.

Support

Für Fragen oder Probleme im Zusammenhang mit der Bereitstellung und dem Betrieb der Stargate-Appliance wenden Sie sich bitte an den HIN-Support.

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs bei, um uns bei der effizienten Bearbeitung Ihrer Anfrage zu unterstützen.

Stargate-Bereitstellung auf Cloudscale mittels eines Images

URL der Image-Datei abrufen

• Informationen zu den verfügbaren Images mit URLs finden Sie im VM Catalog.
• Kopieren Sie die qcow2-URL in Ihre Zwischenablage.

Image-Datei in Cloudscale importieren

• Navigieren Sie im Cloudscale-WebUI zum Menü "Custom Images" und klicken Sie auf "Import a Custom Image".
• Geben Sie einen geeigneten Image-Namen ein.
• Definieren Sie einen Slug, z. B. "stargate".
• Fügen Sie die Stargate-Image-URL in das Feld Download URL ein.
• Setzen Sie Source Format auf das Upload-Format, empfohlen: qcow2.
• Konfigurieren Sie zusätzliche Einstellungen nach Bedarf.
• Klicken Sie auf Import.

VM erstellen

• Navigieren Sie zu Servers und klicken Sie auf Launch a new Server.
• Geben Sie Ihren bevorzugten FQDN oder Hostnamen ein.
• Unter Operating System wählen Sie Custom Images und das importierte Image aus.
• Unter Compute Flavor wählen Sie Flex-4-2 oder Flex-8-2 abhängig von der erwarteten Last (kann später angepasst werden). Siehe Server Requirements für Details.
• Unter Storage Capacity stellen Sie mindestens 30 GB ein. Bitte beachten Sie Server Requirements.
• Unter Server Location wählen Sie Ihre bevorzugte Zone.
• Unter Network Management aktivieren Sie nur IPv4, falls die Stargate-Instanz internetzugänglich sein muss (z. B. für Office 365).
• Unter Access Security wählen Sie Ihren SSH-Schlüssel (benutzbar mit dem almalinux-Benutzer).
• Legen Sie unter Passwort ein sicheres Passwort Ihrer Wahl fest.

Ohne Passwort ist die SSH-Passwortauthentifizierung deaktiviert

Für die erste Anmeldung müssen Sie weiterhin das von HIN bereitgestellte Initialpasswort verwenden. Wenn Sie jedoch kein neues Passwort festlegen, deaktiviert cloud-init die SSH-Passwortauthentifizierung für alle Benutzer, sodass der SSH-Zugriff nur noch mit einem öffentlichen Schlüssel möglich ist.

• Klicken Sie auf Launch.

Zuerst die Data Disk anhängen

Hängen Sie vor dem ersten Start eine zweite, leere Festplatte mit mindestens 30 GB an. Beim ersten Start formatiert die Appliance sie als Data Disk (VEREIGN-DATA, gemountet unter /var/data) und speichert dort die gesamte Konfiguration und alle Daten; ohne sie schlägt der Start fehl und wird zurückgerollt. Siehe Installationsanleitung → Schritt 4.

HIN Gateway installieren

Nach erfolgreicher Erstellung der VM fahren Sie mit den Installations- und Onboarding-Schritten fort, wie in den bereitgestellten Anweisungen beschrieben.

Support

Für Fragen oder Probleme im Zusammenhang mit der Bereitstellung und dem Betrieb der Stargate-Appliance wenden Sie sich bitte an den HIN-Support.

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs bei, um uns bei der effizienten Bearbeitung Ihrer Anfrage zu unterstützen.

VM-Images Katalog

Hier finden Sie einen aktuellen VM-Katalog für verschiedene Plattformen. Vergessen Sie bitte nicht, den SHA-256-Hash der heruntergeladenen Images zu überprüfen. Sie können die Datei https://images.hin.ch/vm-images/SHA256SUMS verwenden, um ihn zu vergleichen.

So führen Sie die SHA256-Hash-Prüfung lokal durch

Sie können den SHA256-Hash heruntergeladener Dateien mit dem folgenden Befehl berechnen und ihn dann mit den Werten in der Tabelle unten vergleichen.

Linux und macOSWindows

Öffnen Sie das Terminal und führen Sie aus:

sha256sum <Dateiname>

Als erweiterte Variante können Sie den folgenden Befehl ausführen und die vordefinierte Prüfsumme als SHA256_VALUE und den Dateinamen als IMAGE_NAME einfügen:

SHA256_VALUE="" \
IMAGE_NAME="" \
echo "$SHA256_VALUE  $IMAGE_NAME" | sudo sha256sum --check --status

Öffnen Sie PowerShell und führen Sie aus:

Get-FileHash "<Dateiname>"

Sie können das Argument -Algorithm SHA256 hinzufügen, um die Verwendung von SHA256 zu erzwingen.

Image Name	Image Typ	Image Größe	Link	SHA256 Prüfsumme
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

Troubleshooting und Diagnose

Eine strukturierte Anleitung zur Diagnose einer Stargate-Appliance über die Befehlszeile: Was überprüft werden muss, wo sich die Logs befinden und welche Massnahmen zur sicheren Wiederherstellung ergriffen werden können.

Wo diese Befehle ausgeführt werden sollen

Führen Sie alle folgenden Befehle aus dem Bereitstellungsverzeichnis aus - dem Ordner, der docker-compose.yml und scripts/ enthält (bei VM-Images ist dies in der Regel /usr/share/stargate-deployment/docker-compose, oder das Verzeichnis, in dem Sie die Installation vorgenommen haben). Alle docker compose- und ./scripts/*-Befehle gehen von diesem Arbeitsverzeichnis aus.

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

---

1. Erster Schritt: der Health Check

Ein Befehl fasst die gesamte Appliance zusammen:

QuickVerbose

./scripts/health-check.sh

./scripts/health-check.sh -v

Dieser meldet den Status «bestanden»/«nicht bestanden» (pass/fail) für: Container (running/healthy), Liveness-Endpunkte (smimekeys, policy, irisagent, mxengine), den Vault-Siegelstatus, die PostgreSQL-Konnektivität und -Datenbanken, SeaweedFS, den WireGuard-Tunnel und Peer-Handshakes, Stalwart-MTA (Ports 25 / 10026), Prometheus-Metrik-Endpunkte sowie Festplatte/Arbeitsspeicher.

Tip

Führen Sie dies zuerst aus. Eine einzelne FAIL-Zeile führt Sie in der Regel direkt zum folgenden Abschnitt.

---

2. Wo sich die Logs befinden

Ebene	Befehl	Was es anzeigt
Start / Erstinstallation / Autostart	sudo journalctl -u stargate -n 200 --no-pager	Den systemd-Dienst, der start.sh beim Start und bei der Erstinstallation ausführt
Updates	cat ../update.log (Bereitstellungsstammverzeichnis, eine Ebene über docker-compose/)	Ausgabe des letzten Dashboard-/Host-ausgelösten update.sh
Ein einzelner Dienst	docker logs stargate-<service> --tail 100	z. B. stargate-dashboard, stargate-mxengine, stargate-keycloak
Einen Dienst live verfolgen	docker logs -f stargate-mxengine	Echtzeit
Alle Container live	docker ps -a --format '{{.Names}}' \| xargs -I{} sh -c 'docker logs --timestamps -f {} 2>&1 \| sed "s/^/[{}] /"'	Zusammengeführt, mit Container als Präfix
Weblog-Viewer	Dozzle unter https://<SERVER_IP>:8190 (Keycloak-Anmeldung)	Alle Container-Logs in einer Benutzeroberfläche anzeigen

Um Logs an den HIN-Support zu übermitteln, verwenden Sie das Upload-Skript und leiten Sie den zurückgegebenen Link weiter - siehe Logs an den Support senden:

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

---

3. Container werden nicht ausgeführt oder starten neu

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

Lesen Sie die Spalte Status:

Status	Bedeutung	Massnahme
Up ... (healthy)	Läuft einwandfrei	-
Up ... (no health)	Läuft; kein Health Check definiert	Überprüfen Sie die docker logs, wenn Sie Probleme vermuten
Restarting	Crash-Looping	docker logs stargate-<svc> - beheben Sie den Root-Fehler (config, secret, dependency)
Exited (0)	Die einmalige Initialisierung wurde erfolgreich abgeschlossen (z. B. *-init, vault-data-fixer)	Normal
Exited (1+)	Fehlgeschlagen	docker logs stargate-<svc> - die letzten Zeilen zeigen, warum
Created	Wurde nie gestartet - eine Abhängigkeit ist nicht hochgekommen	Überprüfen Sie, wovon es abhängt (depends_on, in der Regel Postgres/Vault); das zuerst beheben

Einen einzelnen Dienst neu starten (sicher, ohne Datenverlust):

docker compose up -d <service>          # recreate one service
docker compose restart <service>        # just restart it

Startreihenfolge

Dienste warten auf ihre Abhängigkeiten (depends_on + Health Checks). Bei einem vollständigen Neustart sind kurze Zeilen wie connection refused / database system is starting up während des Hochfahrens von Postgres/Vault normal und verschwinden innerhalb einer Minute.

---

4. Diagnose anhand der Symptome

Dashboard oder Keycloak wird nicht geladen / Anmeldung nicht möglich

• Beide laufen über Caddy: Dashboard auf :443, Keycloak auf :8180.
• Überprüfen Sie die Kette: docker logs stargate-caddy, stargate-dashboard, stargate-keycloak, stargate-apisix.
• Keycloak muss betriebsbereit (healthy) sein, bevor das Dashboard funktioniert: docker compose ps keycloak.
• Eine TLS-Warnung im Browser ist zu erwarten (selbstsigniertes Zertifikat) - akzeptieren Sie diese und fahren Sie fort.
• Fehlgeschlagene Weiterleitungen bei der Anmeldung deuten in der Regel darauf hin, dass die öffentliche URL nicht mit der Adresse übereinstimmt, über die Sie auf den Host zugreifen - überprüfen Sie, dass KEYCLOAK_PUBLIC_URL / DASHBOARD_PUBLIC_URL in .env auf die IP-Adresse bzw. den Host verweisen, die bzw. den Sie tatsächlich verwenden.

WireGuard-Tunnel ausgefallen / Zertifikatsausstellung fehlgeschlagen

Das ist das häufigste Problem - Zertifikate schlagen fehl, wenn der Tunnel nicht verfügbar ist, daher sollten Sie immer zuerst das Problem mit dem Tunnel beheben.

./scripts/health-check.sh -v      # shows WireGuard peer + handshake status
docker logs stargate-irisagent | grep -iE "handshake|peer|cert|wireguard"

• Stellen Sie sicher, dass die Firewall 19818 (UDP und TCP) eingehend/ausgehend zulässt.
• Überprüfen Sie, dass der Peer auf HIN-Seite registriert ist (Support-Schritt) - Sie stellen den öffentlichen WG-Schlüssel, DEPLOYMENT_NAME, SERVER_STATIC_IP, WG_INTERFACE_PORT bereit.
• Sobald der Tunnel einen aktuellen Handshake anzeigt, versuchen Sie die Zertifikatsausstellung erneut über das Dashboard.

Vault versiegelt oder Initialisierung fehlgeschlagen

docker compose exec vault vault status        # look for "Sealed: false"
docker logs stargate-vault-init

• Der Vault muss entsiegelt sein, damit smimekeys/mxengine/policy funktionieren. Die Schlüssel befinden sich in secrets/vault-keys.json.
• Falls vault-init mit einem Ergebnis ungleich Null beendet wurde, fehlt die Schlüsseldatei möglicherweise oder ist beschädigt - überprüfen Sie deren Logs; ein erneuter Aufruf von ./scripts/init-vault.sh versucht die Entsiegelung erneut.

secrets/vault-keys.json nicht löschen

Dieses zu verlieren, bedeutet, den Zugriff auf alle gespeicherten Secrets zu verlieren. Erstellen Sie ein Backup.

PostgreSQL / Datenbankanbindung

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

• Eine vorübergehende Meldung the database system is starting up (57P03) unmittelbar nach einem Neustart ist normal - die Dienste stellen die Verbindung automatisch wieder her.
• Anhaltende Authentifizierungsfehler deuten in der Regel darauf hin, dass POSTGRES_PASSWORD in .env vom Datenvolumen abgewichen ist - siehe die Hinweise zu Update/Secrets, und vermeiden Sie es, diese Datei manuell zu bearbeiten.

E-Mails werden nicht zugestellt

• Eingehende E-Mails treffen auf :25 (Stalwart) ein. Viele Cloud-Anbieter blockieren Port 25 standardmässig:

  nc -zv <this-server-ip> 25          # from an external host
  docker logs stargate-stalwart --tail 100
  

  Falls 25 blockiert ist, beantragen Sie eine Ausnahmegenehmigung bei Ihrem Anbieter. - Ausgehend/Sealing läuft über Stalwart → mxengine (:8084 Seal-Callback, SMTP :1587): docker logs stargate-mxengine. - Mail-Schleifen zeigen sich als dieselbe, immer wiederkehrende Nachricht - stellen Sie sicher, dass der MX-Eintrag Ihrer Domain nicht auf die eigene IP-Adresse dieser Appliance verweist. - Siehe Mail-Relay-Einrichtung und DNS-Einrichtung für das vorgesehene Routing.

Ein Update ist fehlgeschlagen

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

• Der Ops-Agent ruft das Release-Manifest ab, schreibt die Versionen in customer-config.sh und führt anschliessend update.sh auf dem Host aus.
• Bestätigen Sie nach Abschluss die angewendeten Versionen: ./scripts/gather-app-versions.sh (oder überprüfen Sie die Image-Tags mit docker compose ps).
• Wenn ein Dienst nach einem Update hängen bleibt: docker compose up -d <service>, um ihn neu zu erstellen.

Das Update startet, aber es passiert nichts (Update von einer älteren Version). Wenn das Ops-Agent-Log bei pulling deployment repo ... stehen bleibt und das Update nicht fortgesetzt wird, enthält das Repository auf der VM höchstwahrscheinlich lokale Änderungen an einer versionierten Datei (meist eine manuell bearbeitete docker-compose.yml). Dadurch verweigert der git checkout des Ops-Agent die Ausführung, sodass das Update stehen bleibt. Setzen Sie das Repository zwangsweise auf den neuesten Stand zurück und führen Sie das Update anschliessend erneut aus. Git ist die einzige verbindliche Quelle; dabei gehen ausschliesslich lokale Änderungen an versionierten Dateien verloren - customer-config.sh, .env und secrets/ stehen in der .gitignore und bleiben erhalten:

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 erzeugt die .env neu, lädt die Images und erstellt die betroffenen Dienste neu - Sie müssen Stargate nicht manuell neu starten. Sobald der Vorgang abgeschlossen ist, starten Sie das Update erneut über das Dashboard; es wird nun fortgesetzt.

Warning

Verwenden Sie hier nicht git pull. Bei einem Arbeitsverzeichnis mit lokalen Änderungen bricht dieser Befehl mit der Meldung "local changes would be overwritten" ab, was einen Umweg über git stash, Merge-Konflikte oder eine manuelle Wiederherstellung erzwingt. Die obige Abfolge aus git checkout -f und git reset --hard vermeidet das vollständig und ist die sichere, wiederholbare Methode, um das Repository auf den aktuellen Stand zu bringen.

Dozzle (Log-Viewer) nicht erreichbar

• Die URL lautet https://<SERVER_IP>:8190; erforderlich ist eine Keycloak-Anmeldung (derselbe Realm wie das Dashboard) über oauth2-proxy.
• Läuft nur, wenn DOZZLE_ENABLED="true". Überprüfen: docker compose ps dozzle oauth2-proxy.
• Stellen Sie sicher, dass die Firewall :8190 eingehend zulässt. Siehe Überwachung und Logs.

---

5. Speicher und Festplatte

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, ...)

• Container-Logs sind begrenzt (json-file, 100 MB × 5 pro Container) und sollten die Festplatte daher nicht füllen, Images und Volumes hingegen können das.
• Speicherplatz sicher zurückgewinnen: docker image prune -af (entfernt nur nicht verwendete Images). Vermeiden Sie docker system prune --volumes - dadurch werden Daten-Volumes gelöscht.
• Objektspeicher ist SeaweedFS (stargate-seaweedfs): docker logs stargate-seaweedfs --tail 50.

---

6. VM-Ressourcen

free -h                              # memory (min 8 GB)
nproc                                # CPUs (min 4)
docker stats --no-stream             # per-container CPU/RAM
uptime                               # load average

Host-Metriken werden zudem für Prometheus unter :9100/metrics exportiert (siehe Überwachung). Wenn der Host swappt oder ausgelastet ist, ist damit zu rechnen, dass Health Checks instabil werden und Updates sich verlangsamen.

---

7. Netzwerk und Ports

Schnelle Erreichbarkeitsprüfung für die wichtigsten eingehenden Ports:

for p in 25 443 8180 8190 19818; do nc -zv <this-server-ip> $p; done

Port	Dienst	Richtung
25	Stalwart SMTP (eingehende E-Mails)	eingehend
443	Dashboard (HTTPS)	eingehend
8180	Keycloak	eingehend
8190	Dozzle (optional)	eingehend
19818	WireGuard (UDP und TCP)	ein-/ausgehend

Ausgehender Zugriff wird benötigt auf die Container-Registry, die S/MIME-Zertifizierungsstelle (über den WireGuard-Tunnel) und jedes konfigurierte Remote-Loki. Die vollständige Port-Tabelle finden Sie auf der Startseite und in der Anwendungsübersicht.

---

8. Wiederherstellungsmassnahmen

Geordnet vom am wenigsten bis zum stärksten störenden Eingriff:

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

Backups & destruktive Wiederherstellung

./scripts/backup.sh und ./scripts/restore.sh übernehmen Datensicherung/-wiederherstellung. ./scripts/purge.sh löscht alle Daten (Datenbanken, Vault, Storage) für eine saubere Neuinstallation - nur als letztes Mittel und nur mit einem aktuellen Backup verwenden. Details: Docker erweiterte Konfiguration.

---

9. Wann Sie sich an den Support wenden sollten

Zeigt der Health Check nach den obigen Schritten weiterhin Fehler an, eröffnen Sie ein Ticket über Support / Kontakt und geben Sie Folgendes an:

• Die Appliance-Version (./scripts/gather-app-versions.sh) und den Kundennamen.
• Die Health-Check-Ausgabe (./scripts/health-check.sh -v).
• Einen Log-Bundle-Link von ./scripts/send-logs-to-support.sh (siehe Logs an den Support senden).
• Was Sie taten, als das Problem auftrat, sowie etwaige Screenshots.

Verimesh-Instanz aktualisieren

Die folgenden Anweisungen beschreiben, wie Sie eine Verimesh-Instanz von v0.5.1 auf v0.5.3 aktualisieren.

Hinweis: Sie müssen sich mit dem Linux-Administratorkonto auf der VM anmelden.

Update-Schritte

1. Bearbeiten Sie die .env-Datei und aktualisieren Sie die Ops-Agent-Version auf v0.0.3.
2. Bearbeiten Sie die Kundenkonfiguration und aktualisieren Sie dort ebenfalls die Ops-Agent-Version auf v0.0.3.
3. Wechseln Sie zum Main-Branch: git checkout main
4. Rufen Sie die neuesten Änderungen ab: git pull
5. Aktualisieren Sie den Ops-Agent-Container: docker compose up -d ops-agent
6. Melden Sie sich im Dashboard an.
7. Navigieren Sie zu Settings.
8. Geben Sie im Abschnitt Update am Seitenende die Zielversion (v0.5.3) ein und starten Sie den Update-Vorgang.

Aktualisierte Keycloak einrichten

Hinweis: Diese Anleitung gilt, wenn Sie auf VM-Image v0.5.1 laufen und dann auf eine neuere Version aktualisiert haben.

Nach dem letzten Keycloak-Update führt eine breaking change dazu, dass authentifizierte Benutzer beim Aufrufen bestimmter Anwendungsrouten (z. B. Peers, Peer Certificates) unerwartet auf die Anmeldeseite umgeleitet werden.

Zur Behebung muss die folgende manuelle Konfiguration in der Keycloak-UI vorgenommen werden.

Lösungsschritte

1. Öffnen Sie Keycloak in der Umgebung und geben Sie die URL ein - <VM IP address>/admin/master/console/ Benutzer: Admin Passwort: das Admin-Passwort aus der .env der Maschine entnehmen (dazu müssen Sie sich an der Linux-Konsole anmelden)

2. Admin-Konsole - Realm wechseln zu → Realm stargate:

3. Zu Clients → dashboard wechseln
4. Zur Registerkarte Client scopes wechseln → auf dashboard-dedicated klicken
5. Configure a new mapper wählen → Audience

6. Folgende Einstellungen vornehmen:

   • Name: apisix-audience
   • Included client audience: apisix (aus dem Dropdown auswählen)
   • Included custom audience: (leer lassen)
   • Add to access token: On
   • Add to token introspection: On
   • Add to ID token / lightweight token: Off

7. Auf Save klicken

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.

Kontaktieren Sie uns

Kontaktieren Sie uns per E-Mail

Support

Bei Fragen oder Problemen im Zusammenhang mit der Bereitstellung und dem Betrieb der Stargate-Appliance wenden Sie sich bitte an den HIN-Support per E-Mail oder Telefon:

• support@hin.ch
• 0848 830 740
• Webformular

Weitere Informationen finden Sie auf unserer Kontaktseite: https://support.hin.ch/de/kontakt.cfm

Bitte fügen Sie relevante Informationen wie den Kundennamen, die Appliance-Version und Screenshots/Logs hinzu, um die Bearbeitung Ihres Anliegens zu beschleunigen.