Stargate Bereitstellungsanleitung

Was ist Stargate?

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)

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,8084,19818 -j ACCEPT

# Ausgehende TCP-Verbindungen zu den offenen Ports zulassen
iptables -A OUTPUT -p tcp -m multiport --dports 25,8084,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

Port	Protokoll	Zweck
25	TCP	SMTP – Empfangen von E-Mails von externen Servern
8084	TCP	HTTP – Seal-Callback von einem entfernten Sealer-Dienst
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
hub.docker.com	443	TCP	Docker-Image-Registry
mxengine-dev.k8s.vereign-cdn.com	443	TCP	Entfernter Sealer-Dienst
smimekeys-ca-dev.k8s.vereign-cdn.com	443	TCP	S/MIME-CA-Dienst
loki.example.com	443	TCP	Log-Versand (Alloy → Loki, optional)
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

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

Tip

Technischer Installationsablauf für eine Single-Domain-Mail-Architektur mit Microsoft 365

Einleitung

Dieses Dokument bietet eine umfassende Anleitung zum technischen Installations- und Migrationsprozess auf das neue HIN Gateway ("Stargate Appliance"). Es gilt für Microsoft 365-Mail-Architekturen, die eine einzige vertrauenswürdige Domäne verwenden.

Die Anleitung richtet sich an HIN Kunden, IT-Administratoren und Systemingenieure, die für die Bereitstellung und Konfiguration des neuen HIN Gateways sowie 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 mit dem HIN Gateway

• 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 umfasst folgende Punkte:

1. Vorbereitung und Ausweichplanung
2. Installation und Konfiguration des HIN Gateways
3. Domänenaktivierung und Zertifikatsvalidierung
4. Integration des Mail-Servers und Konfiguration des Routings
5. Testen, Übergang in den Produktivbetrieb und Validierung nach der Migration
6. Ausserbetriebnahme des bestehenden MGW

Das Ziel von HIN bei diesem Prozess ist es, eine sichere, reibungslose und vollständig validierte Migration zu gewährleisten, die den Betrieb nur minimal beeinträchtigt und die unterbrechungsfreie Kontinuität der E-Mail-Dienste garantiert.

Häufig gestellte Fragen

Kann ich die Installation und Migration selbst durchführen?

Ja, die Installation und Migration können vollständig vom Kunden durchgeführt werden, mit Ausnahme von "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 den derzeit in Betrieb befindlichen Mail-Gateways erforderlich ist.

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

Wird es während der Migration zu Unterbrüchen bei der E-Mail-Zustellung kommen?

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.

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

Nein, während der Installation und Migration gehen keine E-Mails verloren.

Übersicht über die Installationsschritte

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

Detaillierte Schritte

Schritt 0 - Voraussetzungen prüfen

Bitte lesen Sie die "Stargate-Bereitstellungsanweisungen" durch und 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 Migration verfügbar sein oder bestätigt werden:

• Die Zugangsdaten werden Ihnen von HIN zugestellt:
  • VM-Zugangsdaten
  • Keycloak-Zugangsdaten
  • Aktivierungscode
• Export des privaten Schlüssels
  • 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.
• Lade 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".
• 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.

Weitere Informationen: Security Assessment WireGuard EN

Export des privaten Schlüssels

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.

• 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".
• Bestätigung, dass das bestehende MGW erst nach Abschluss der Abnahme gelöscht wird.
• Zugriff auf DNS, Mailserver-Konnektoren, Transportregeln und Relay-Einstellungen.

Schritt 1.1 - Smoke-Test

Senden Sie eine Test-E-Mail an die folgenden Empfänger, wobei Sie Zugriff auf das Postfach haben, um den korrekten Empfang zu überprüfen:

• eine HIN E-Mail-Adresse oder eine HIN Community-Domain von Ihnen, zum Beispiel: user@hin.ch
• eine E-Mail-Adresse ausserhalb der HIN Community, zum Beispiel: user@bluewin.ch

Überprüfen Sie, ob beide E-Mails erfolgreich zugestellt wurden, einschliesslich Betreff, Inhalt und allfälliger Anhänge.

Schritt 1.2 - Sichern des bestehenden MGWs

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

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

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

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.

Schritt 1.5 - Bestehende MGW-VM abschalten

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 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
• Konfiguration von Microsoft Exchange

Schritt 4 - VM-Image laden

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

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
   

Netzwerk muss vor dem ersten Start konfiguriert sein

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.

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

cd /root/stargate-deployment/docker-compose
./scripts/purge.sh
# Update configuration with a new ip, by editing it with nano
# SERVER_STATIC_IP=<NEW IP>
nano customer-config.sh
# OR use sed
# sed -i 's/old IP/new IP/g' customer-config.sh
./scripts/install.sh

Das Installationsskript ermittelt die IP-Adresse des Servers automatisch anhand der Standardroute. Eine beliebige erreichbare IP-Adresse, egal ob öffentlich oder privat, ist ausreichend. Der eigentliche öffentliche Endpunkt wird später über das Dashboard konfiguriert.

Tip

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

cd /root/stargate-deployment/docker-compose
./scripts/purge.sh
# Update configuration with a new ip, by editing it with nano
# SERVER_STATIC_IP=<NEW IP>
nano customer-config.sh
# OR use sed
# sed -i 's/old IP/new IP/g' customer-config.sh
./scripts/install.sh

Das Installationsskript ermittelt die IP-Adresse des Servers automatisch anhand der Standardroute. Eine beliebige erreichbare IP-Adresse, egal ob öffentlich oder privat, ist ausreichend. Der eigentliche öffentliche Endpunkt wird später über das Dashboard konfiguriert.

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

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 Verbindung zum sicheren Mesh-Netzwerk auf. In diesem Schritt wird das HIN Gateway mit dem Iris-Agent verbunden und die Zertifikate werden synchronisiert.

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

Falls die Verbindung fehlschlägt oder der Status des Iris-Agents 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).

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.

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

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-Datei".
  2. Falls für die Zertifikatsdatei kein Passwort festgelegt wurde, lassen Sie das Passwortfeld leer.
  3. Klicken Sie auf "Importieren".
  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

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.

Schritt 14 - E-Mail-Transport konfigurieren

Konfigurieren Sie auf diesem Bildschirm Ihre E-Mail-Transport-Einstellungen für die Einrichtung des sicheren E-Mail-Relays.

Die folgenden Einstellungen stehen zur Verfügung:

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üge weitere IP-Adressen hinzu, falls der Server über mehrere Adressen erreichbar ist.
Domänen	Jede Domain, die dieses Gateway verarbeitet, zusammen mit ihrem Relay-Host (dem internen Mailserver, an den eingehende E-Mails zugestellt werden).
Standard-Relay-Host	Der Standard-SMTP-Relay für den ausgehenden Versand.

Im Abschnitt "Erweitert" können Sie optional Folgendes konfigurieren:

Einstellung	Beschreibung
Konfigurieren der TLS	TLS-Zertifikateinstellungen für SMTP-Verbindungen.
Inhaltsfilter	Der interne Endpunkt des Inhaltsfilters (Standard: mxengine:1587).
Vertrauenswürdige Netzwerke	Zusätzliche Netzwerke, denen die Weiterleitung über dieses Gateway gestattet ist.

Weitere Aktionen:

• Fügen Sie bei Bedarf weitere Domains hinzu, indem Sie auf "Add domain" klicken.
• Erweitern Sie den Abschnitt "Advanced", um die E-Mail-Transportparameter fein abzustimmen.

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 "Konfiguration übernehmen", um fortzufahren.

Schritt 15 - Whitelist-Header konfigurieren

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 konfigurieren

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

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

• SMTP-Relay / Smart Host
• Konnektoren
• Transportregeln
• Routing-Domains

Ausführliche Anweisungen finden Sie unter Exchange-Integration.

Schritt 19 - Test vor der Umstellung

Wiederholen Sie den "Schritt 1.1 - Smoke-Test". Zusätzlich zum Smoke-Test testen und bestätigen Sie bitte die folgenden Schritte:

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.

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.

Schritt 20 - Validieren nach der Umstellung

Bestätigen:

• E-Mails zugestellt
• Verschlüsselung angewendet
• Keine Delays oder Bounces
• Protokollierung erfolgreich

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

Schritt 21 - Bestehendes MGW ausser Betrieb nehmen

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:
   • E-Mail-Protokolle
   • Sicherheits-/Audit-Protokolle (erforderlich für Compliance und Fehlerbehebung)
3. Bereinigung (optional) - Entfernen:
   • Firewall-Regeln
   • DNS-Einträge
   • Routing-Konfigurationen, die auf das bestehende MGW verweisen

Schritt 22 - 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 Ort auf.

Anhang 1 - Sichern und Wiederherstellen der Appliance-Einstellungen

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.

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 – Stargate als primärer MX (empfohlen für eingehende S/MIME-Verarbeitung):

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

Muster B – 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"]

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

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

Oder Volumes manuell entfernen. Die Option -v entfernt Volumes

docker compose down -v

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). Deshalb muss Port 8084 für eingehenden Datenverkehr geöffnet sein. 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 den gleichen Schritt mit Destination port range 1587 und benennen Sie es mxengine

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

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/Verimesh-HINGateway.v0.5.1.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"

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

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.

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.5.3.x86_64.ova		981M / 1028392960 bytes	Download	332e81d4a3c7bca0da94fb337793bbd5a30e204d2d524086ff7aad9945dc78a6
hingateway-v0.5.3.x86_64.mf		4.0K / 227 bytes	Download	dfcbba5bcf4066732e32a7753388ce27d1b04e01528d9103934992273b97dbd5
hingateway-v0.5.3.x86_64.ovf		8.0K / 7670 bytes	Download	44c5343e2dd5bb8b371b1aaf2e98e60fd4d4cf42f0989b596144f68be9dd2e1e
hingateway-v0.5.3.x86_64.qcow2		1.6G / 1686503424 bytes	Download	c25cfdc497af7ac49caf04d62c8f4b0adcbeb1f0c55a29b74e67b70c4770f81d
hingateway-v0.5.3.x86_64.raw		30G / 32212254720 bytes	Download	6de4925c8502d0dff690d7c74e2a6004e53e3c54444eb128db788c2aff754828
hingateway-v0.5.3.x86_64.raw.gz		989M / 1036406461 bytes	Download	9ec2815ee6a575018630a6c6abfa44df2291594562e53fe7b0f4f74c5ffa5f0c
hingateway-v0.5.3.x86_64.vhd		31G / 32212255232 bytes	Download	f1bdc4afebb6b8c7234bc4dc915803ce0d4939539c761f1eaea2da4f27833fcd
hingateway-v0.5.3.x86_64.vhd.gz		1004M / 1052039565 bytes	Download	0a011435938e727fac7039c9384a7be6abc8f32d361f36733943fa4b89c3a882
hingateway-v0.5.3.x86_64.vhdx		2.2G / 2256535552 bytes	Download	958da9752f3c06856d25ecf917852e003ba55ae21f244c4f2e1ee76646ec20f0
hingateway-v0.5.3.x86_64.vmdk		981M / 1028378624 bytes	Download	1954651e722f0aa9280fa85902e64af6a255dc63b63111904c023c0518bc9ff3
SHA256SUMS		4.0K / 979 bytes	Download	9514d4671a7e33e9e924029752a6f6bb31a4209a7999ba3f72e119215f4e03b9

Release Notes

v0.5.3

...

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.