Stargate Bereitstellungsanleitung

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

🇩🇪🇫🇷🇮🇹🇬🇧

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

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

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

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

Was ist Stargate?

Voraussetzungen

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

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

• Zugangsdaten werden Ihnen von HIN zur Verfügung gestellt

  • VM-Zugangsdaten
  • Keycloak-Zugangsdaten
  • Aktivierungscode

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

Info

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

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

Für Kunden mit mehreren Domains

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

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

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

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

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

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

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

Info

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

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

Info

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

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

Schnellstart

Installationsoptionen

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

Zweite Festplatte erforderlich: die Data Disk

Die Appliance verwendet zwei Festplatten: die OS-Festplatte aus dem Image und eine separate Data Disk, auf der sämtliche Konfigurationen, Secrets, E-Mails und Datenbanken gespeichert sind. Dank dieser Trennung kann ein Image-Upgrade das Betriebssystem ersetzen, ohne Ihre Daten anzutasten.

Im VMware-OVA-Image ist diese Festplatte bereits enthalten. Auf allen anderen Plattformen (Proxmox, Hyper-V, Azure, Cloudscale) besteht das Image aus einer einzigen OS-Festplatte. Sie müssen deshalb vor dem ersten Start eine zweite, leere Festplatte mit mindestens 30 GB anhängen.

Formatieren oder partitionieren Sie diese Festplatte nicht selbst. Beim ersten Start formatiert die Appliance die leere Festplatte (Label VEREIGN-DATA) und bindet sie unter /var/data ein. Fehlt sie, schlägt der Health Check beim ersten Start fehl und es erfolgt ein Rollback.

🖨️

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

Exchange-Integration

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

Server-Anforderungen

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

Allgemeine Anforderungen

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

Eingehender Netzwerkzugriff (Firewall muss erlauben)

Port	Protokoll	Zweck
25	TCP	SMTP - Empfangen von E-Mails von externen Servern oder von einem MTA, der dem HIN Gateway vorgelagert ist.
19818	UDP+TCP	WireGuard – Verschlüsselter Tunnel für die Agent-zu-Agent-Kommunikation. Lesen Sie unser Sicherheitsgutachten zu WireGuard

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

Info

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

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

Ausgehender Netzwerkzugriff (Server muss erreichen können)

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

Eigenen NTP-Server verwenden

Die Appliance ist standardmässig auf ntp.metas.ch (Eidgenössisches Institut für Metrologie) eingestellt. Wenn Ihr Netzwerk ausgehendes NTP nicht zulässt, konfigurieren Sie einen eigenen Zeitserver, anstatt Port 123 ins Internet zu öffnen - ein interner Server wird vollständig unterstützt.

Erstellen Sie dazu auf der Appliance die folgende Datei und laden Sie die Konfiguration neu. Sie können beliebig viele Server angeben, einen pro Zeile:

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

Die Datei muss genau ntp.sources heissen. Unter diesem Namen ersetzt Ihre Liste die Standardeinstellung; unter jedem anderen Namen wird sie stattdessen zur Standardeinstellung hinzugefügt. Löschen Sie die Datei und laden Sie neu, um zu ntp.metas.ch zurückzukehren.

Eine korrekte Uhrzeit ist nicht optional. Weicht die Uhr ab, schlagen Zertifikatsprüfung, Nachrichtensignierung und Anmeldesitzungen auf schwer diagnostizierbare Weise fehl.

Wichtiger Hinweis zum Betrieb auf Microsoft Azure

**Betrieb auf Microsoft Azure**
Für die SMTP-Relay-Anbindung des HIN Gateways an Exchange Online muss ausgehender Datenverkehr über TCP-Port 25 möglich sein.

Microsoft Azure blockiert ausgehende Verbindungen über Port 25 bei den meisten Subscription-Modellen. HIN kann die Verfügbarkeit oder Freischaltung dieses Ports durch Microsoft nicht beeinflussen. Der Betrieb des HIN Gateways auf Azure ist deshalb **kein standardmässig unterstütztes Deployment-Szenario**. Ausnahmen bestehen insbesondere für [bestimmte Enterprise-Subscriptions von Microsoft](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-network/troubleshoot-outbound-smtp-connectivity). Prüfen Sie deshalb vor einer Installation auf Azure, ob Ihre Subscription ausgehenden SMTP-Verkehr über TCP-Port 25 erlaubt.

Bei Fragen zur geeigneten Betriebsvariante wenden Sie sich bitte frühzeitig an Ihre HIN Ansprechperson.

Firewall-Hinweis

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

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

Beispiel für eine iptables-Konfiguration:

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

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

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

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

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

# Zusätzliche Dienste, die von der VM erreichbar sein müssen
# DNS
iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT

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

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

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

Kunden mit 3 oder weniger Domains

• HIN empfiehlt, alle Domains auf einmal zu migrieren.
• HIN unterstützt den Kunden bei der erfolgreichen Migration der ersten Domain.
• Sobald die erste Domain erfolgreich migriert wurde, kann der Kunde die übrigen Domains eigenständig migrieren.
• Dieser Ansatz hält die Migration einfach und vermeidet die Notwendigkeit einer parallelen Umgebung.

Kunden mit mehr als 3 Domains

• HIN empfiehlt, eine parallele Umgebung neben dem bestehenden MGW einzurichten.
• Die Domains können anschliessend schrittweise in die neue Umgebung migriert werden.
• HIN unterstützt den Kunden bei der erfolgreichen Migration der ersten Domain.
• Nach der ersten erfolgreichen Migration kann der Kunde entscheiden, wie und wann die übrigen Domains in die neue Umgebung verschoben werden.

Kontaktieren Sie uns

Support

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

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

---

Installationsanleitungen

HIN Gateway: Technischer Leitfaden für Neuinstallation und Migration

Einleitung

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

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

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

Übersicht über den E-Mail-Fluss

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

Installations- und Migrationsablauf

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

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

Migration

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

Häufig gestellte Fragen

Kann ich die Installation oder Migration selbst durchführen?

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

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

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

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

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

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

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

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

Übersicht über die Installationsschritte

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

Detaillierte Schritte

Schritt 0 - Voraussetzungen prüfen

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

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

• Die Zugangsdaten werden Ihnen von HIN zugestellt

  • VM-Zugangsdaten
  • Keycloak-Zugangsdaten
  • Aktivierungscode

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

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

Warum WireGuard?

Der WireGuard-Port erfüllt zwei wichtige Funktionen:

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

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

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

Schritt 1.1 - Smoke-Test

Info

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

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

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

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

(Vertraulich)-Nachrichten ausserhalb der HIN Community

Wenn Sie Outlook verwenden und vertrauliche E-Mails über eine der folgenden Optionen ausserhalb der HIN Community versenden: * Verwendung einer spezifischen E-Mail-Vorlage * Verwendung des Schlosssymbols (Key Lock)

Testen Sie den E-Mail-Fluss vor der Migration, um sicherzustellen, dass die E-Mail verarbeitet und sicher zugestellt wird.

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

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

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

Schritt 1.2 - Sichern des bestehenden MGWs

Info

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

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

Aktuelle MGW-Routing-Konfiguration prüfen

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

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

MGW-Header-Prüfung

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

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

Info

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

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

Unterstützung durch HIN erforderlich

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

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

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

Schritt 1.4 - Notfallplan / Ausweichszenario

Info

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

Rollback-Szenario - Falls ein Rollback erforderlich ist:

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

Schritt 1.5 - Bestehende MGW-VM abschalten

Info

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

Fahren Sie die bestehende MGW-VM herunter.

Warning

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

Schritt 2 - WireGuard

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

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

Schritt 3 - Ziel-VM auswählen

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

Info

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

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

Schritt 4 - VM-Image laden

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

Zweite Festplatte erforderlich: die Data Disk

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

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

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

Schritt 5 - Netzwerkverbindung zur VM

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

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

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

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

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

Eine IP-Adresse unter Linux hinzufügen:

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

   nmtui
   

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

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

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

   sudo systemctl restart NetworkManager
   

Tip

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

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

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

Hinter NAT oder mit einer Floating IP?

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

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

Question

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

Klicken Sie hier, um eine E-Mail zu senden

Wichtiger Hinweis zum Betrieb auf Microsoft Azure

Für die SMTP-Relay-Anbindung des HIN Gateways an Exchange Online ist ausgehende SMTP-Kommunikation über TCP-Port 25 erforderlich.
Microsoft Azure blockiert ausgehende Verbindungen über Port 25 bei den meisten Subscription-Modellen. [Bei Standard-Enterprise-Agreement- (EA) und Microsoft-Customer-Agreement-for-Enterprise-Subscriptions (MCA-E)](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-network/troubleshoot-outbound-smtp-connectivity) ist Port 25 gemäss Microsoft grundsätzlich verfügbar. Für einzelne weitere Enterprise-Konfigurationen gelten besondere Bedingungen.

Da diese Einschränkungen und allfällige Freischaltungen ausschliesslich durch Microsoft festgelegt werden, ist der Betrieb des HIN Gateways auf Azure kein standardmässig unterstütztes Deployment-Szenario. HIN kann die Verfügbarkeit oder Freischaltung dieses Ports durch Microsoft nicht beeinflussen.

Handlungsempfehlung: Planen Sie eine Migration oder eine Infrastrukturänderung mit Azure? Prüfen Sie vor der Installation zwingend, ob Ihre Azure-Subscription ausgehende SMTP-Kommunikation über TCP-Port 25 zulässt. Kontaktieren Sie frühzeitig Ihre HIN Ansprechperson, um die für Sie geeignete Betriebsvariante abzustimmen.

Empfohlene alternative Betriebsvarianten
Falls TCP-Port 25 in Ihrer Azure-Umgebung nicht verfügbar ist, empfehlen wir:

· Betrieb des HIN Gateways auf einer lokalen bzw. On-Premises-VM (wie bisher)
· Betrieb des HIN Gateways bei einem datenschutzkonformen Hosting-Provider

**Ausblick: Gateway as a Service**

HIN plant, künftig das Gateway auch als vollständig gemanagten Service anzubieten. Möchten Sie informiert werden, sobald das HIN Gateway as a Service verfügbar ist? Wenden Sie sich an Ihre HIN Ansprechperson und lassen Sie sich unverbindlich vormerken.

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>

VM neu starten

Falls die Maschine nicht erreichbar ist, starten Sie die VM über die Konsole neu und versuchen Sie anschliessend erneut, über den Browser darauf zuzugreifen.

Schritt 7 - Aktivierungscode eingeben

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

Ich habe keinen Aktivierungscode

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

Klicken Sie hier, um eine E-Mail zu senden

Schritt 8 - Setup des Mesh-Netzwerks

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

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

Was ist eine öffentliche IP?

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

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

Schritt 9 - Sicheres Mesh-Netzwerk einrichten

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

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

Falls die Verbindung fehlschlägt

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

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

Schritt 10 - Login bei Keycloak

Warning

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

Was tun, wenn ein Verbindungsfehler angezeigt wird?

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

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

Question

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

Klicken Sie hier, um eine E-Mail zu senden

Schritt 11 - Passwort aktualisieren

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

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

Schritt 12 - Kontoinformationen aktualisieren

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

Schritt 13 - Erstkonfiguration und Einrichten der Domäne

Info

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

Konfigurieren Sie auf diesem Bildschirm Ihre Grundeinstellungen:

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

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

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

✅ Diese Domain ist verschlüsselt.

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

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

Warning

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

Importieren Sie Ihren bestehenden privaten Schlüssel

Hinweis: gilt nur für das Migrationsszenario!

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

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

Migrationsszenario für schrittweise Multi-Domain-Migration

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

Schritt 14 - E-Mail-Transport konfigurieren

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

Seite "Domains"

Info

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

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

Einstellung	Beschreibung
Inbound relay	Der SMTP-Relay, der eingehende E-Mails für die ausgewählte Domäne empfängt. Sie können Routing-Regeln auf Basis der Absenderdomäne (externe Domäne) definieren, um zu steuern, wohin eingehende Nachrichten zugestellt werden.
Outbound relay	Der SMTP-Relay für ausgehende E-Mails der ausgewählten Domäne. Nachdem das Gateway eine Nachricht verarbeitet hat, leitet es sie anhand der konfigurierten lokalen Domäne als nächsten Hop an diesen Server weiter. Hinweis zur Migration: Diese Einstellung entspricht Forwarding server im alten MGW.
Trusted networks	Zusätzliche Netzwerke, denen die Weiterleitung über dieses Gateway gestattet ist. Weitere Informationen finden Sie unter "Schritt 18 - Mailserver konfigurieren".
Configure TLS	TLS-Zertifikateinstellungen für SMTP-Verbindungen; über die Schaltfläche Generate TLS certificate können Sie ein TLS-Zertifikat erzeugen.
Email authentication	Alle Einstellungen unter dem Abschnitt Email authentication sind im Abschnitt Email authentication (DKIM ARC SPF DMARC) beschrieben.

Wie testet man eine TLS-Verbindung?

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

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

Oder direkt auf Ihrem lokalen Rechner:

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

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

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

Verwenden Sie den folgenden openssl-Befehl:

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

Z. B.:

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

Weitere Aktionen:

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

Note

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

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

Seite "Settings"

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

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

Einstellung	Beschreibung
Mail server host name	Der FQDN dieser Mail-Gateway-Instanz (z. B. mail.example.com).
Mail server IP addresses	Die öffentliche(n) IP-Adresse(n) dieses Servers. Fügen Sie weitere IP-Adressen hinzu, falls der Server über mehrere Adressen erreichbar ist.
DNS server	DNS des Hosts, der zur Auflösung von MX- und anderen DNS-Einträgen verwendet wird. Bitte stellen Sie sicher, dass der eingegebene DNS-Server von der HIN Gateway VM aus erreichbar ist.
Default inbound relay	Der SMTP-Relay, der eingehende E-Mails für die ausgewählte Domäne empfängt. Sie können Routing-Regeln auf Basis der Absenderdomäne (externe Domäne) definieren, um zu steuern, wohin eingehende Nachrichten zugestellt werden.
Default outbound relay	Der SMTP-Relay für ausgehende E-Mails der ausgewählten Domäne. Nachdem das Gateway eine Nachricht verarbeitet hat, leitet es sie anhand der konfigurierten lokalen Domäne als nächsten Hop an diesen Server weiter. Hinweis zur Migration: Diese Einstellung entspricht Forwarding server im alten MGW.

Schritt 15 - Whitelist-Header konfigurieren

Info

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

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

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

Schritt 16 - Peer-Zertifikate

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

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

Schritt 17 - Peer-Zertifikate validieren

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

Question

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

Schritt 18 - Mailserver und HIN Gateway konfigurieren

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

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

E-Mail-Server

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

Siehe Exchange-Integration für detaillierte Anweisungen.

Konfiguration HIN Gateway

Seite "Domains"

Info

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

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

Einstellung	Beschreibung
Inbound relay	Der SMTP-Relay, der eingehende E-Mails für die ausgewählte Domäne empfängt. Sie können Routing-Regeln auf Basis der Absenderdomäne (externe Domäne) definieren, um zu steuern, wohin eingehende Nachrichten zugestellt werden.
Outbound relay	Der SMTP-Relay für ausgehende E-Mails der ausgewählten Domäne. Nachdem das Gateway eine Nachricht verarbeitet hat, leitet es sie anhand der konfigurierten lokalen Domäne als nächsten Hop an diesen Server weiter. Hinweis zur Migration: Diese Einstellung entspricht Forwarding server im alten MGW.
Trusted networks	Zusätzliche Netzwerke, denen die Weiterleitung über dieses Gateway gestattet ist. Weitere Informationen finden Sie unter "Schritt 18 - Mailserver konfigurieren".
Configure TLS	TLS-Zertifikateinstellungen für SMTP-Verbindungen; über die Schaltfläche Generate TLS certificate können Sie ein TLS-Zertifikat erzeugen.
Email authentication	Alle Einstellungen unter dem Abschnitt Email authentication sind im Abschnitt Email authentication (DKIM ARC SPF DMARC) beschrieben.

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

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

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

Seite "Settings"

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

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

Einstellung	Beschreibung
Mail server host name	Der FQDN dieser Mail-Gateway-Instanz (z. B. mail.example.com).
Mail server IP addresses	Die öffentliche(n) IP-Adresse(n) dieses Servers. Fügen Sie weitere IP-Adressen hinzu, falls der Server über mehrere Adressen erreichbar ist.
DNS server	DNS des Hosts, der zur Auflösung von MX- und anderen DNS-Einträgen verwendet wird. Bitte stellen Sie sicher, dass der eingegebene DNS-Server von der HIN Gateway VM aus erreichbar ist.
Default inbound relay	Der Standard-SMTP-Relay, der eingehende E-Mails für die ausgewählte Domäne empfängt. Sie können Routing-Regeln auf Basis der Absenderdomäne (jede externe Domäne) definieren, um zu steuern, wohin eingehende Nachrichten zugestellt werden. Er dient als Fallback für alle Domänen.
Default outbound relay	Der Standard-SMTP-Relay für ausgehende E-Mails. Nachdem das Gateway eine Nachricht verarbeitet hat, leitet es sie als nächsten Hop an diesen Server weiter. Er dient als Fallback für alle Domänen.

Schritt 19 - Test und Validierung

Ausgehend:

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

(Vertraulich)-Nachrichten ausserhalb der HIN Community

Wenn Sie während des Tests und der Validierung vertrauliche E-Mails mit Outlook über eine der folgenden Methoden ausserhalb der HIN Community versenden: * Verwendung einer spezifischen E-Mail-Vorlage * Verwendung des Schlosssymbols (Key Lock)

Gehen Sie bitte wie folgt vor: * Wenn Sie eine spezifische E-Mail-Vorlage verwenden, stellen Sie sicher, dass die Vorlage angepasst ist, damit sichere E-Mails korrekt über das HIN Gateway verarbeitet werden. * Wenn Sie das Schlosssymbol (Key Lock) verwenden, tragen Sie stattdessen vorübergehend «(vertraulich)» in die Betreffzeile ein.

HIN entwickelt derzeit die Unterstützung für die Outlook-Integration. Diese Funktion soll in einer künftigen Version verfügbar sein. Testen Sie nach den erforderlichen Anpassungen den E-Mail-Fluss erneut und bestätigen Sie, dass die E-Mail nach der Migration verarbeitet und erfolgreich zugestellt wird.

Eingehender Verkehr:

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

Bestätigen:

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

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

Schritt 20 - Passwort der VM ändern

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

Schritt 21 - Bestehendes MGW ausser Betrieb nehmen

Info

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

Warning

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

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

Anhang 1 - Sichern und Wiederherstellen der Appliance-Einstellungen

Info

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

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

Einstellungen sichern

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

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

Sicherungspasswort ändern

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

Note

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

Einstellungen wiederherstellen

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

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

Sicherung über SCP

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

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

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

scp backup@192.168.1.60:/backup.tgz .

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

Note

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

Szenario für die Migration mehrerer Domains

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

Phase 1 Start – Ausgangslage (alle Domains auf MGW)

Ausgangszustand

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

Checkliste vor der Migration

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

Phase 2 Migration – schrittweise, eine Domain nach der anderen

Migrationsschritte

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

Rollback (pro Domain)

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

Achten Sie auf kundenspezifische Header

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

Phase 3 Abschluss – vollständige Migration zum HIN Gateway

Warning

Bitte behalten Sie das neue HIN Gateway nach erfolgreichen Tests auf Public IP B und ändern Sie diese IP-Adresse nicht. Eine Änderung der öffentlichen IP unterbricht den sicheren Tunnel, sodass das Gateway keine Zertifikatsaktualisierungen mehr erhält.

Endzustand

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

Checkliste für die Bereinigung

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

Empfohlener Migrationsansatz nach Anzahl der Domains

Kunden mit 3 oder weniger Domains

• HIN empfiehlt, alle Domains auf einmal zu migrieren.
• HIN unterstützt den Kunden bei der erfolgreichen Migration der ersten Domain.
• Sobald die erste Domain erfolgreich migriert wurde, kann der Kunde die übrigen Domains eigenständig migrieren.
• Dieser Ansatz hält die Migration einfach und vermeidet die Notwendigkeit einer parallelen Umgebung.

Kunden mit mehr als 3 Domains

• HIN empfiehlt, eine parallele Umgebung neben dem bestehenden MGW einzurichten.
• Die Domains können anschliessend schrittweise in die neue Umgebung migriert werden.
• HIN unterstützt den Kunden bei der erfolgreichen Migration der ersten Domain.
• Nach der ersten erfolgreichen Migration kann der Kunde entscheiden, wie und wann die übrigen Domains in die neue Umgebung verschoben werden.

---

Warning

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

Note

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

Technische Konfiguration und Integration

Anwendungsübersicht

Anwendungen

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

Infrastruktur

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

Init-Container

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

Überwachung

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

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

Architekturübersicht

VM-Architekturübersicht

Überwachung und Logs

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

Komponenten

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

---

Dozzle – Lokaler Log-Viewer

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

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

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

Note

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

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

---

Grafana Alloy – Log-Weiterleitung

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

Wie es funktioniert

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

Konfiguration der entfernten Log-Weiterleitung

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

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

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

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

Note

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

Anforderungen auf der entfernten Seite

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

---

Prometheus-Metriken

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

Verfügbare Endpunkte

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

Scrape-Konfiguration

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

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

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

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

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

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

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

Tip

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

Firewall-Anforderungen

Die Metrik-Ports (2113-2116, 9091, 9100) verfügen über keine Authentifizierung. Beschränken Sie sie so, dass sie nur von Ihrem Prometheus-Server aus erreichbar sind und niemals aus dem Internet.

Wenn Sie den Zugriff nach IP freigeben, fügen Sie nur die IP Ihres Überwachungsservers 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 HIN Gateway

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

Übersicht

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

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

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

Muster B – HIN Gateway als primärer MX:

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

In beiden Mustern benötigen Sie:

1. DNS-Einträge, die auf den HIN-Gateway-Server verweisen
2. Ausgehenden Connector – leitet E-Mails von Exchange an HIN Gateway weiter
3. Eingehenden Connector – akzeptiert E-Mails von HIN Gateway 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:

• HIN Gateway ist installiert und läuft (Bereitstellungsanleitung)
• Sie haben die öffentliche IP-Adresse des HIN-Gateway-Servers (im Folgenden als <HIN Gateway_IP> bezeichnet)
• Sie haben den Mail-Hostnamen des HIN-Gateway-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 <HIN Gateway_IP>
• MX-Eintrag: <YOUR_DOMAIN> mit HIN Gateway bei höherer Priorität (niedrigere Zahl) als Exchange
• SPF-Eintrag: ip4:<HIN Gateway_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 → HIN Gateway)

Dieser Connector leitet ausgehende E-Mails von Exchange Online an den HIN-Gateway-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 HIN-Gateway-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 HIN-Gateway-Server-IP-Adresse ein: <HIN Gateway_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 HIN Gateway (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 HIN-Gateway-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 (HIN Gateway → Office 365)

Dieser Connector akzeptiert E-Mails vom HIN-Gateway-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 HIN-Gateway-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 HIN-Gateway-Server-IP-Adresse ein: <HIN Gateway_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 HIN Gateway 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 der Connectors (einschließlich des Send-to-MX-Connectors aus Schritt D) sollte die Connectors-Seite Folgendes anzeigen:

Status	Name	Von	An
Ein	E-Mails vom HIN-Gateway-Relay-Server empfangen	Ihre Org	O365
Ein	Von Office 365 zum HIN-Gateway-Relay-Server	O365	Ihre Org
Ein	Send to MX	O365	Ihre Org

Schritt C: Die Transportregel erstellen

Die Transportregel leitet alle ausgehenden E-Mails über den HIN-Gateway-Ausgangs-Connector weiter, mit Ausnahme von E-Mails, die von HIN Gateway 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 HIN Gateway 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 HIN Gateway 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 HIN-Gateway-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 HIN-Gateway-Server-IP-Adresse ein: <HIN Gateway_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 HIN Gateway, die bei Exchange Online ankommen, in einer Endlosschleife zurück an HIN Gateway 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 HIN-Gateway-Relay-Server" umleiten

4. Außer wenn: Die Absender-IP-Adresse in einem dieser Bereiche liegt: <HIN Gateway_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.

Schritt D: Outgoing to MX (Send-to-MX-Connector und Regel)

Nachdem HIN Gateway eine ausgehende Nachricht verarbeitet (signiert oder verschlüsselt) hat, übergibt es die Nachricht über den eingehenden Connector aus Schritt B wieder an Exchange Online. Exchange Online muss sie dann an den Mailserver des Empfängers zustellen. Dafür sorgt die "Outgoing to MX"-Konfiguration: Ein eigener Connector Send to MX sendet die Nachricht an den MX des externen Empfängers, und die Transportregel outgoing_to_mx leitet die verarbeiteten Nachrichten an diesen Connector um.

Den Send-to-MX-Connector erstellen (Office 365 → Partnerorganisation)

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

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

3. Verbindung zu: Wählen Sie "Partnerorganisation"

4. Klicken Sie auf "Weiter"

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

Send to MX

• Stellen Sie sicher, dass der Connector eingeschaltet ist
• Klicken Sie auf "Weiter"

Note

Der Name des Connectors kann frei gewählt werden. Wenn Sie einen anderen Namen verwenden, wählen Sie diesen Namen in der unten beschriebenen Regel outgoing_to_mx aus.

1. Verwendung des Connectors: Wählen Sie "Nur wenn ich eine Transportregel eingerichtet habe, die Nachrichten an diesen Connector weiterleitet"
2. Klicken Sie auf "Weiter"

Tip

Wie der ausgehende Connector aus Schritt A leitet auch dieser Connector keine E-Mails von selbst weiter. Er wird nur verwendet, wenn die unten beschriebene Regel outgoing_to_mx eine Nachricht an ihn umleitet.

1. Routing: Wählen Sie "Den dieser Partnerdomäne zugeordneten MX-Eintrag verwenden"

2. Klicken Sie auf "Weiter"

3. Sicherheitseinschränkungen: Lassen Sie "Immer Transport Layer Security (TLS) zum Sichern der Verbindung verwenden" deaktiviert, damit keine Sicherheitseinschränkungen gelten

4. Klicken Sie auf "Weiter"

Note

Dieser Connector stellt E-Mails an beliebige externe Empfänger zu. Würde hier TLS oder ein bestimmtes Zertifikat verlangt, könnten E-Mails an Empfängerserver, die diese Anforderungen nicht erfüllen, nicht zugestellt werden.

1. Überprüfungs-E-Mail: Geben Sie eine externe E-Mail-Adresse ein (außerhalb Ihrer Organisation)
2. Klicken Sie auf "+" und dann auf "Überprüfen"

3. Warten Sie, bis die Überprüfung abgeschlossen ist, und klicken Sie dann auf "Weiter"

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

5. Klicken Sie auf "Fertig"

Die Zusammenfassung des Connectors sollte Folgendes anzeigen:

• E-Mail-Flussszenario: Von Office 365, an Partnerorganisation
• Name: Send to MX
• Status: Ein
• Verwendung des Connectors: Nur verwenden, wenn ich eine Transportregel eingerichtet habe, die Nachrichten an diesen Connector umleitet
• Routing: Den dieser Partnerdomäne zugeordneten MX-Eintrag verwenden
• Sicherheitseinschränkungen: Keine

Die Transportregel outgoing_to_mx erstellen

Diese Regel leitet ausgehende Nachrichten, die von HIN Gateway zurückkommen, an den Send-to-MX-Connector um. Sie erkennt diese Nachrichten am Nachrichtenheader outgoing.

1. Navigieren Sie zum Exchange Admin Center - Regeln

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

3. Regelname: Geben Sie Folgendes ein:

outgoing_to_mx

1. Diese Regel anwenden, wenn: Wählen Sie "Die Nachrichtenheader..." → "stimmen mit diesen Textmustern überein"
2. Headername: outgoing
3. Textmuster: outgoing_<YOUR_DOMAIN> (z.B. outgoing_example.com)
4. Klicken Sie auf "Speichern"

Note

Der Header outgoing muss bereits in der Nachricht vorhanden sein, wenn sie von HIN Gateway zurückkommt. In der HIN-Referenzkonfiguration wird er durch eine separate Regel (set_header) gesetzt: Sie greift, wenn sich der Absender innerhalb der Organisation befindet, und setzt den Nachrichtenheader outgoing auf den Wert outgoing_<YOUR_DOMAIN>. Ohne diesen Header greift die Regel outgoing_to_mx nie.

1. Folgendes tun: Wählen Sie "Die Nachricht umleiten an" → "den folgenden Connector" → wählen Sie "Send to MX"

2. Klicken Sie auf "Speichern"

3. Außer wenn: Leer lassen

4. Klicken Sie auf "Weiter", um die Regeleinstellungen zu öffnen:

5. Regelmodus: "Erzwingen"
6. Schweregrad: "Nicht angegeben"
7. Lassen Sie "Diese Regel aktivieren am" und "Diese Regel deaktivieren am" deaktiviert
8. Aktivieren Sie "Verarbeitung weiterer Regeln beenden"
9. Lassen Sie "Nachricht zurückstellen, wenn die Regelverarbeitung nicht abgeschlossen wird" deaktiviert

10. Absenderadresse in Nachricht abgleichen: "Header"

11. Klicken Sie auf "Weiter", dann auf "Fertig stellen" und dann auf "Fertig"

12. Priorität festlegen: Klicken Sie auf die Regel in der Liste, klicken Sie auf "Regeleinstellungen bearbeiten" und setzen Sie die Priorität höher (niedrigere Zahl) als die der Transportregel aus Schritt C, z.B. 1

13. Klicken Sie auf "Speichern"

Warning

Die Priorität und "Verarbeitung weiterer Regeln beenden" sind kritisch. Die Regel muss vor der Regel aus Schritt C ausgewertet werden und die weitere Verarbeitung beenden. Andernfalls kann eine Nachricht, die von HIN Gateway zurückkommt, erneut an HIN Gateway umgeleitet werden, statt an den Empfänger zugestellt zu werden.

1. Überprüfen Sie die Regeldetails. Sie sollten Folgendes anzeigen:

   • Regelname: outgoing_to_mx
   • Modus: Erzwingen
   • Schweregrad: Nicht angegeben
   • Datumsbereich festlegen: Kein bestimmter Datumsbereich festgelegt
   • Absenderadresse: Header abgleichen
   • Priorität: 1
   • Bei Regelverarbeitungsfehlern: Ignorieren
   • Diese Regel anwenden, wenn: Der Header 'outgoing' stimmt mit den folgenden Mustern überein: 'outgoing_<YOUR_DOMAIN>'
   • Folgendes tun: Die Nachricht über den Connector "Send to MX" weiterleiten und Verarbeitung weiterer Regeln beenden

2. Regel aktivieren: Die Regel wird im deaktivierten Zustand erstellt. Schalten Sie "Regel aktivieren oder deaktivieren" auf "Aktiviert" um.

Tip

Vergessen Sie nicht, die Regel zu aktivieren: Sie funktioniert erst, wenn 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 → HIN Gateway)

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

Exchange-Verwaltungsshell (PowerShell):

New-SendConnector -Name "To HIN Gateway Relay" `
  -AddressSpaces "SMTP:*;1" `
  -SmartHosts "<HIN Gateway_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 HIN Gateway Relay"
4. Typ: Wählen Sie "Internet"
5. Netzwerkeinstellungen: Wählen Sie "E-Mails über Smart Hosts leiten", fügen Sie <HIN Gateway_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 (HIN Gateway → On-Premises)

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

Exchange-Verwaltungsshell (PowerShell):

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

Exchange Admin Center (GUI):

1. Navigieren Sie zu Mailfluss → Receive-Connectors
2. Klicken Sie auf +, um einen neuen Connector zu erstellen
3. Name: "From HIN Gateway 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 <HIN Gateway_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 HIN Gateway" `
  -SentToScope NotInOrganization `
  -RouteMessageOutboundConnector "To HIN Gateway Relay" `
  -ExceptIfSenderIpRanges "<HIN Gateway_IP>"

Exchange Admin Center (GUI):

1. Navigieren Sie zu Mailfluss → Regeln
2. Klicken Sie auf + → "Neue Regel erstellen"
3. Name: "Relay outbound via HIN Gateway"
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 HIN Gateway Relay"
6. Außer wenn: "Die Absender-IP-Adresse in..." → fügen Sie <HIN Gateway_IP> hinzu

---

Teil 4: HIN-Gateway-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 HIN Gateway als auch auf Exchange verweisen
• HIN Gateway 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 HIN Gateway 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 HIN Gateway, wohin verarbeitete E-Mails für diese spezifische Domain zugestellt werden sollen.

HIN-Gateway-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 HIN-Gateway-IP-Adresse hat
• Ohne diese Ausnahme werden E-Mails von HIN Gateway, die bei Exchange ankommen, zurück an HIN Gateway weitergeleitet

HIN Gateway akzeptiert keine E-Mails von Exchange

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

Exchange Online lehnt E-Mails von HIN Gateway ab

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

TLS-Zertifikatsfehler

HIN Gateway 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:

• HIN-Gateway-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 HIN Gateway ist offen (keine Firewall-Blockierung)

---

Kurzreferenz

Komponente	Exchange Online-Ort	Zweck
Ausgehender Connector	Admin Center → Mailfluss → Connectors	Ausgehende E-Mails an HIN Gateway leiten
Eingehender Connector	Admin Center → Mailfluss → Connectors	E-Mails von HIN Gateway akzeptieren
Transportregel	Admin Center → Mailfluss → Regeln	Ausgehenden Connector für externe Empfänger auslösen
Send-to-MX-Connector	Admin Center → Mailfluss → Connectors	Von HIN Gateway zurückkommende E-Mails an den MX des Empfängers zustellen
Regel outgoing_to_mx	Admin Center → Mailfluss → Regeln	Von HIN Gateway zurückkommende E-Mails an den Send-to-MX-Connector leiten

DNS-Eintrag	Beispiel	Zweck
A	mail IN A <HIN Gateway_IP>	Hostnamen auf HIN Gateway verweisen
MX (HIN Gateway)	@ IN MX 15 mail.<YOUR_DOMAIN>.	Eingehende E-Mails treffen zuerst auf HIN Gateway
MX (Exchange)	@ IN MX 20 <DOMAIN>.mail.protection.outlook.com.	Fallback / Zustellziel
SPF	ip4:<HIN Gateway_IP> und ip4:<HIN_SEALER_IP> zum vorhandenen TXT-Eintrag hinzugefügt	HIN Gateway 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 HIN Gateway

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

In diesem Leitfaden:

• <HIN Gateway_IP> – die öffentliche statische IP-Adresse Ihres HIN Gateway-Servers (SERVER_STATIC_IP in customer-config.sh)
• <MAIL_HOSTNAME> – der FQDN des HIN Gateway-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>	<HIN Gateway_IP>	Ja	Vor der Installation
MX	<YOUR_DOMAIN>	<MAIL_HOSTNAME> (Priorität 15)	Ja	Vor der Installation
SPF	<YOUR_DOMAIN>	ip4:<HIN Gateway_IP> zum TXT hinzufügen	Ja	Vor der Installation
PTR	<HIN Gateway_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 HIN Gateway-Mail-Hostnamen auf die öffentliche IP des Servers verweist:

<MAIL_HOSTNAME>.    A    <HIN Gateway_IP>

Beispiel:

mail.example.ch.    A    128.140.117.200

Wenn HIN Gateway 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 HIN Gateway mit einer höheren Priorität (niedrigere Zahl) als den vorhandenen Mailserver hinzu. Dies stellt sicher, dass eingehende E-Mails zuerst HIN Gateway 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. HIN Gateway mit Priorität 15 empfängt E-Mails vor Exchange Online mit Priorität 20.

Warum: HIN Gateway 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 HIN Gateway 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 HIN Gateway-Server-IP und die HIN-Sealer-IP zum SPF-Eintrag Ihrer Domain hinzu, damit über HIN Gateway weitergeleitete ausgehende E-Mails die SPF-Prüfungen beim Empfänger bestehen.

Wenn Sie M365 / Exchange Online verwenden:

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

Wenn Sie M365 / Google Workspace nicht verwenden:

<YOUR_DOMAIN>.    TXT    "v=spf1 ip4:<HIN Gateway_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 HIN Gateway 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 HIN Gateway 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:

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 hin.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 HIN Gateway SPF verwendet: Der mtaconf-Daemon löst den SPF-Eintrag jeder Domain auf, um die Liste der IPs, die ohne Authentifizierung über HIN Gateway 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 HIN Gateway-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:<HIN Gateway_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 HIN Gateway-Server, nicht auf einzelne Domains).

Mail-Routing pro Domain

Die MX-Einträge jeder Domain sagen HIN Gateway, 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 <HIN Gateway_IP>

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

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

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

# Forward-confirmed reverse DNS (FCrDNS)
host $(host <HIN Gateway_IP> | awk '{print $NF}' | sed 's/\.$//')
# Erwartet: löst auf <HIN Gateway_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 HIN Gateway-IP – fügen Sie ip4:<HIN Gateway_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 HIN Gateway zurück

Wenn HIN Gateway 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.          ← HIN Gateway (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 HIN Gateway verbinden) als auch das ausgehende Relay (HIN Gateway, das an MX-Ziele zustellt).

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

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

---

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

Der Bereich erreichen Sie über:

Domains -> Domain auswählen -> Email authentication

Das Panel besteht aus fünf Unterabschnitten:

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

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

---

Was jedes Protokoll bewirkt

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

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

---

DKIM

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

So richten Sie DKIM für eine neue Domain ein

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

So rotieren Sie einen DKIM-Schlüssel

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

---

ARC

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

---

SPF

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

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

---

DMARC

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

Verifizierungswert

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

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

Was als "Hard Failure" für Required gilt (pro Mechanismus):

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

Zwei wichtige Hinweise:

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

---

Zu veröffentlichende DNS-Einträge

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

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

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

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

---

Änderungen speichern

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

---

Fehlerbehebung

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

Update HIN Gateway

Dieses Dokument erklärt:

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

Anwendbare Versionen

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

Wie man aktualisiert

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

1. Klicken Sie auf Other versions.

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

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

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

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

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

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

Update auf ein Major-Release

Das Update von 0.6.x auf 1.1.7 ist ein Major-Release-Update. Sie müssen vor Beginn des Updates einen Snapshot der VM als Sicherung erstellen.

Dieses Release enthält ein erforderliches Sicherheitsupdate, das Keycloak auf 26.8.0 aktualisiert. Bei diesem Upgrade ändert Keycloak das Datenbankschema und entfernt eine Spalte sowie Indizes, die die vorherige Keycloak-Version (26.7.4) benötigt. Deshalb kann die Schaltfläche Roll back keine funktionsfähige Version 0.6.x wiederherstellen. Der VM-Snapshot ist die einzige Möglichkeit, zur vorherigen Version zurückzukehren.

Wie man ein Rollback durchführt

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

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

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

Verwalten von Routed Domains in HIN Gateway

HIN Gateway kann auch den E-Mail-Verkehr für Domains abwickeln, die keine HIN Secure-Domains sind. Dies ist ein gängiges Setup für Kunden, die ihre eigene On-Premises-Mailserver-Infrastruktur betreiben. Diese Funktion ist in HIN Gateway integriert, sodass Kunden ihr Mail-Setup an ihre eigenen Anforderungen anpassen können.

In HIN Gateway werden diese Domains als Routed Domains bezeichnet. E-Mails für eine Routed Domain durchlaufen HIN Gateway ohne Verarbeitung für die sichere Nachrichtenübermittlung: Sie werden einfach an den nächsten Relay-Host weitergeleitet.

Eine Routed Domain hinzufügen

Öffnen Sie die Seite Domains, klicken Sie auf Add domain, geben Sie den Domainnamen ein und klicken Sie auf Save.

Die Routed Domain konfigurieren

Aktivieren Sie die Domain und konfigurieren Sie sie genauso wie eine HIN Secure-Domain. Die detaillierten Schritte finden Sie in der Installationsanleitung unter Schritt 14 - E-Mail-Transport konfigurieren.

NTP konfigurieren

HIN Gateway hält seine Uhrzeit mit NTP (Network Time Protocol) genau. Eine genaue Uhrzeit ist zwingend: Zertifikatsprüfung, Nachrichtensignierung und Anmeldesitzungen schlagen fehl, wenn die Uhr abweicht.

So funktioniert es:

• Standardmässig synchronisiert HIN Gateway seine Uhrzeit mit ntp.metas.ch
• Wenn Ihr Netzwerk kein ausgehendes NTP ins Internet zulässt oder Ihre Organisation eigene Zeitserver betreibt, können Sie den Standard durch einen oder mehrere eigene Zeitserver ersetzen
• Sie können mehrere Zeitserver hinzufügen. Ist einer nicht erreichbar, verwendet HIN Gateway den nächsten

Bevor Sie beginnen

• Sie benötigen Zugriff auf das HIN Gateway Dashboard
• Erfragen Sie den Hostnamen des Zeitservers (bzw. der Zeitserver) bei Ihrer Netzwerkadministration
• Stellen Sie sicher, dass HIN Gateway den Zeitserver (bzw. die Zeitserver) über UDP-Port 123 erreichen kann

Aktuelle Zeitsynchronisation prüfen

1. Melden Sie sich beim HIN Gateway Dashboard an.

2. Öffnen Sie Settings und scrollen Sie nach unten zum Abschnitt Time synchronisation.

   

   Die Statuszeile zeigt, ob die Uhr synchron ist (In sync), zusammen mit der IP-Adresse des verwendeten Zeitservers, dem Offset und dem Stratum. Time servers zeigt, welche Server konfiguriert sind. Ohne eigene Server steht dort Using the default time server (ntp.metas.ch).

Eigene Zeitserver hinzufügen

1. Klicken Sie im Abschnitt Time synchronisation auf Edit. Ein leeres Feld für den ersten Zeitserver erscheint.

   

2. Geben Sie den Hostnamen des Zeitservers ein (zum Beispiel ntp.example.com).

3. Wählen Sie mit dem Schalter neben dem Feld die Art des Eintrags:
   • Server: ein einzelner NTP-Server
   • Pool: ein NTP-Pool, also ein Hostname, der auf mehrere Server auflöst (zum Beispiel ch.pool.ntp.org). HIN Gateway verwendet mehrere Server aus dem Pool

4. Um einen weiteren Zeitserver hinzuzufügen, klicken Sie auf Add server und wiederholen Sie die Schritte 2 und 3. Sie können Pools und Server kombinieren.

   

   Um einen Eintrag zu entfernen, klicken Sie auf das Minus-Symbol daneben.

5. Klicken Sie auf Save.

HIN Gateway synchronisiert seine Uhrzeit nun mit den konfigurierten Zeitservern statt mit dem Standard-Zeitserver.

Konfiguration überprüfen

Prüfen Sie die Statuszeile im Abschnitt Time synchronisation. Sie sollte In sync und die IP-Adresse eines Ihrer Zeitserver anzeigen. Um sofort zu synchronisieren, klicken Sie auf Sync now.

Zum Standard-Zeitserver zurückkehren

Klicken Sie auf Edit, entfernen Sie alle Einträge mit dem Minus-Symbol und klicken Sie auf Save. HIN Gateway verwendet dann wieder ntp.metas.ch.

Authentifizierung eingehender Verbindungen

Mit der Authentifizierung eingehender Verbindungen kann ein externes System, etwa ein Mail-Relay, eine Anwendung oder ein Mail-Client, E-Mails für eine Ihrer Domains über HIN Gateway versenden, indem es sich mit Benutzername und Passwort anmeldet. Das ist nützlich, wenn der Absender nicht allein über seine IP-Adresse zugelassen werden kann.

So funktioniert es:

• Der Absender verbindet sich mit HIN Gateway über den Submission-Port 587 und authentifiziert sich mit SMTP AUTH
• Zugangsdaten werden pro Domain im HIN Gateway Dashboard erstellt

Bevor Sie beginnen

• Sie benötigen Zugriff auf das HIN Gateway Dashboard
• Die Domain, von der Sie senden möchten, muss bereits in HIN Gateway hinzugefügt und aktiviert (onboarded) sein
• TLS muss für die Domain aktiviert sein. Passwörter werden nur über TLS akzeptiert, ohne TLS-Zertifikat funktionieren die Zugangsdaten daher nicht
• Sie benötigen Zugriff auf die Konfiguration des sendenden Systems (MTA / Anwendung), da Sie dort die neuen Zugangsdaten eintragen

Zugangsdaten erstellen

1. Melden Sie sich beim HIN Gateway Dashboard an.
2. Öffnen Sie Domains und wählen Sie die Domain aus, von der Sie senden möchten.

3. Scrollen Sie nach unten zum Abschnitt SMTP authentication (port 587).

   

   Hier werden alle Zugangsdaten aufgelistet, die für die Domain bereits bestehen.

   TLS muss aktiviert sein

   Hat die Domain noch kein TLS-Zertifikat, zeigt der Abschnitt die Meldung No TLS certificate yet. Die Zugangsdaten funktionieren erst, wenn TLS aktiviert ist, da Passwörter nur über TLS akzeptiert werden.

   

   Um TLS zu aktivieren, öffnen Sie auf derselben Domain-Seite den Abschnitt Configure TLS und fügen Sie ein Zertifikat hinzu, oder klicken Sie auf Generate TLS certificate, um eines zu erzeugen. Kehren Sie danach zu diesem Abschnitt zurück.

   Der Schalter Verify a trusted network legt fest, von wo aus die Zugangsdaten verwendet werden können. Steht er auf Off, funktionieren die Zugangsdaten von jeder IP-Adresse aus. Aktivieren Sie ihn, wenn Sie Anmeldungen auf Trusted networks beschränken möchten.

4. Klicken Sie auf Add credential. Ein Formular mit zwei Feldern öffnet sich:

   

   Wählen Sie eine der folgenden Möglichkeiten:

   • Zugangsdaten automatisch erzeugen (empfohlen): Lassen Sie Username und Password leer. HIN Gateway erzeugt einen Benutzernamen und ein starkes Zufallspasswort
   • Eigene Zugangsdaten festlegen: Geben Sie Username und Password ein. Das Passwort muss mindestens 16 Zeichen lang sein.

5. Klicken Sie auf Create.

6. Kopieren Sie Benutzername und Passwort.

   

   Warning

   Das Passwort wird nur einmal angezeigt. Klicken Sie auf Copy und bewahren Sie es an einem sicheren Ort auf (zum Beispiel in einem Passwort-Manager), bevor Sie fortfahren. Geht das Passwort verloren, erzeugen Sie mit Rotate password ein neues.

7. Klicken Sie auf Done. Die neuen Zugangsdaten erscheinen nun in der Liste.

Sendendes System konfigurieren

Tragen Sie die Zugangsdaten im sendenden MTA bzw. in der Anwendung ein:

Einstellung	Wert
SMTP-Server	Die IP-Adresse Ihres HIN Gateway
Port	587
Verschlüsselung	STARTTLS
Authentifizierung	Benutzername und Passwort (SMTP AUTH)
Benutzername	Der Benutzername aus Schritt 6
Passwort	Das Passwort aus Schritt 6

Die Absenderadresse (MAIL FROM) muss zur Domain gehören, für die die Zugangsdaten erstellt wurden, sonst wird die Nachricht abgewiesen.

Bestehende Zugangsdaten verwalten

Für alle Zugangsdaten im Abschnitt SMTP authentication (port 587) stehen zwei Aktionen zur Verfügung:

• Rotate password: erzeugt ein neues Passwort für die Zugangsdaten. Das alte Passwort funktioniert danach nicht mehr, aktualisieren Sie das sendende System also sofort.
• Delete: löscht die Zugangsdaten. Systeme, die sie noch verwenden, können nicht mehr über HIN Gateway senden.

Tip

Erstellen Sie für jedes sendende System eigene Zugangsdaten. So können Sie den Zugriff für ein System erneuern oder widerrufen, ohne die anderen zu beeinträchtigen.

Authentifizierung ausgehender Verbindungen

Wenn HIN Gateway Nachrichten für eine Domain an den nächsten Hop weiterleitet (zum Beispiel an ein Mail-Relay oder einen Mailserver), kann dieser verlangen, dass sich der Absender anmeldet, bevor er E-Mails annimmt. Mit der Authentifizierung ausgehender Verbindungen meldet sich HIN Gateway beim nächsten Hop mit Benutzername und Passwort an (SMTP AUTH).

So funktioniert es:

• Jede Domain hat im HIN Gateway Dashboard ein eigenes Outbound relay (Host und Port)
• Ist Require authentication aktiv, meldet sich HIN Gateway mit den von Ihnen eingegebenen Zugangsdaten beim Outbound Relay an, bevor es eine Nachricht weiterleitet

Bevor Sie beginnen

• Sie benötigen Zugriff auf das HIN Gateway Dashboard
• Die Domain muss bereits in HIN Gateway hinzugefügt und aktiviert (onboarded) sein
• Erfragen Sie Benutzername und Passwort bei der Administration der empfangenden Seite (des Relays oder Mailservers, der die Authentifizierung verlangt)

Zugangsdaten konfigurieren

1. Melden Sie sich beim HIN Gateway Dashboard an.
2. Öffnen Sie Domains und wählen Sie die Domain aus.

3. Scrollen Sie nach unten zu Mail routing und suchen Sie den Abschnitt Outbound.

   

   Prüfen Sie, ob Outbound relay den richtigen Host und Port des nächsten Hops anzeigt (zum Beispiel relay.example.com:25). Diese Zugangsdaten werden nur für dieses Relay verwendet.

4. Klicken Sie auf den Schalter Require authentication, sodass er Active anzeigt. Die Felder Username und Password erscheinen.

   

5. Geben Sie den auf der empfangenden Seite konfigurierten Username und das Password ein. Klicken Sie auf das Augen-Symbol, um das Passwort anzuzeigen und auf Tippfehler zu prüfen.

6. Scrollen Sie nach unten und klicken Sie auf Save.

Ab sofort meldet sich HIN Gateway bei jeder Weiterleitung einer Nachricht für diese Domain beim Outbound Relay an.

Konfiguration überprüfen

Senden Sie über HIN Gateway eine Testnachricht an einen Empfänger hinter dem Outbound Relay und prüfen Sie, ob sie ankommt. Falls nicht, öffnen Sie im Dashboard Logs und suchen Sie nach Authentifizierungsfehlern des Relays. Die häufigsten Ursachen sind:

• Falscher Benutzername oder falsches Passwort
• Das Relay unterstützt SMTP AUTH auf dem konfigurierten Port nicht oder lässt es nicht zu
• Host oder Port des Outbound relay ist falsch

Zugangsdaten ändern oder entfernen

• Passwort ändern: Wenn die empfangende Seite das Passwort ändert, geben Sie das neue im Feld Password ein und klicken Sie auf Save. Bis dahin schlägt die Authentifizierung für Nachrichten an das Relay fehl.
• Authentifizierung ausschalten: Klicken Sie auf Require authentication, sodass Inactive angezeigt wird, und klicken Sie auf Save. HIN Gateway verbindet sich dann ohne Anmeldung mit dem Relay.

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

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

• WG_PRIVATE_KEY — Wird von IRISAgent beim ersten Start generiert und in customer-config.sh gespeichert

Schritt 2: Auf einem Server bereitstellen

Tip

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

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

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

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

Kopieren Sie die Dateien manuell auf den Server

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

SSH zum Server

ssh your-server
cd /path/to/stargate

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

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

Installation ausführen

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

Schritt 3: Was die Installation bewirkt

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

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

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

Schritt 4: Onboarding über das Dashboard

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

/installation — WireGuard-Peer-Einrichtung

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

/onboarding — S/MIME-Zertifikat

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

/mail — Mail-Domains und Relay-Konfiguration

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

Domains später hinzufügen oder ändern

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

Schritt 5: WireGuard-Peer-Registrierung

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

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

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

docker compose logs irisagent | grep "public key"

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

Nach Bestätigung der Peer-Registrierung:

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

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

Starten Sie nur irisagent neu

docker compose restart irisagent

Prüfen Sie auf erfolgreichen WireGuard-Handshake

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

Tip

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

Schritt 6: Empfehlungen nach dem Onboarding

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

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

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

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

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

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

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

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

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

Stargate-Seite – pro-Domain-Relay

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

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

M365 / Exchange Online-Seite

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

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

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

Warum dieses Muster wichtig ist

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

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

Nachfolgende Starts (nach Neustart)

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

sudo systemctl start stargate

Dies führt start.sh aus, das:

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

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

Dienste anhalten

sudo systemctl stop stargate

(oder direkt ./scripts/stop.sh)

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

Datenpersistenz

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

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

Sichere Operationen (Daten bleiben erhalten)

Anhalten und starten:

sudo systemctl stop stargate
sudo systemctl start stargate

Oder direkt mit den Skripten:

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

Verwenden Sie keine docker compose-Befehle direkt

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

Vault-Siegelverhalten

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

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

Zerstörerische Operationen (Daten gelöscht)

Warning

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

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

Danger

Alles löschen (Volumes, Secrets, Konfiguration)

./scripts/purge.sh

Skriptübersicht

Skript	Zweck
install.sh	Erstinstallation (Docker, Vault). Domain-/Zertifikats-/Peer-Setup erfolgt anschließend im Dashboard.
update.sh	.env aus customer-config.sh neu erzeugen (neue Vorlagenvariablen werden ergänzt), die festgelegten Images herunterladen und Container neu erstellen (Vault-Token bleibt erhalten). Auf VM-Appliances werden Versionen stattdessen über das Dashboard gewechselt - siehe HIN Gateway aktualisieren
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); --config-only sichert nur customer-config.sh
restore.sh	Aus einem Backup-Archiv wiederherstellen (funktioniert auf neuem System); --config-only stellt nur customer-config.sh wieder her
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

Nur die Konfiguration sichern und wiederherstellen

Um nur customer-config.sh über eine Bereinigung und Neuinstallation hinweg zu behalten, zum Beispiel um die Server-IP vor dem Onboarding zu ändern (siehe Troubleshooting und Diagnose):

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

• backup.sh --config-only sichert customer-config.sh und eigene NTP-Server (ntp.sources) nach /var/data/backups/<timestamp>_config-only.tar.gz. Es benötigt keine laufenden Dienste, lässt .env, die Vault-Schlüssel und die Datenbanken weg und löscht keine älteren Backups.
• restore.sh --config-only stellt nur diese beiden Dateien wieder her, aus einem Nur-Konfigurations-Archiv oder aus einem vollständigen Backup. Es fragt nicht nach einer Bestätigung, behält eine vorhandene Datei als customer-config.sh.bak.<timestamp> und zeigt die nächsten Schritte an.
• Eine vollständige Wiederherstellung aus einem Nur-Konfigurations-Archiv wird abgelehnt.

Das Archiv enthält die generierten Passwörter und den privaten WireGuard-Schlüssel. Behandeln Sie es als vertraulich.

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

Wie Sie aktualisieren, hängt von der Installationsart ab:

• VM-Appliance (bootc-Image) - die VM-Images des HIN Gateway. Das gesamte Betriebssystem einschliesslich Docker, der Bereitstellungsskripte, docker-compose.yml und der festgelegten Service-Image-Versionen wird als ein versioniertes Image ausgeliefert. Sie aktualisieren, indem Sie auf ein neueres Image wechseln und neu starten.
• Reine Compose-Installation - ein git clone dieses Repositorys auf einer Maschine, die Sie selbst verwalten. Sie aktualisieren, indem Sie einen neueren Release-Tag auschecken.

VM-Appliance (bootc)

Auf der Appliance ist /usr/share/stargate-deployment Teil des schreibgeschützten Betriebssystem-Images. Es gibt keinen Git-Checkout, der aktualisiert oder zurückgesetzt werden könnte; führen Sie dort daher weder git noch update.sh --release aus. Alle Daten - Konfiguration, Secrets, E-Mails und Datenbanken - liegen auf dem Data Disk unter /var/data und werden von einem Update nicht verändert.

Update über das Dashboard

Verwenden Sie den Abschnitt System version auf der Seite Settings des Dashboards - die Schritt-für-Schritt-Anleitung finden Sie unter HIN Gateway aktualisieren. Wenn Sie den Download starten, führt der Ops-Agent Folgendes aus:

1. Er erstellt mit backup.sh ein vollständiges Backup mit der Bezeichnung <aktuelle Version>-pre_update_to_<Zielversion> in /var/data/backups/. Schlägt das Backup fehl, wird das Update abgebrochen und nichts verändert. Einzige Ausnahme ist ein Backup, dessen Vault-Teil unvollständig ist: Das Update läuft weiter, und der Ops-Agent protokolliert die Warnung pre-update backup is missing Vault secrets; continuing.
2. Er lädt das Ziel-Betriebssystem-Image herunter und stellt es bereit (bootc switch). Das laufende System wird dabei noch nicht verändert.
3. Die neue Version wird beim nächsten Neustart aktiv - sofort mit Restart now oder beim nächsten Neustart der Maschine mit Later.

Update über die Kommandozeile

Melden Sie sich als hinadmin an der VM an (ssh hinadmin@<VM-IP-Adresse>) und verwenden Sie die mit dem Image ausgelieferten Kurzbefehle:

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

Note

Anders als das Dashboard erstellt hingateway-switch vorher kein Backup. Führen Sie vor dem Wechsel sudo /usr/share/stargate-deployment/docker-compose/scripts/backup.sh --label <aktuelle Version>-pre_update_to_vX.Y.Z aus, damit das Archiv so benannt ist wie das vom Dashboard erstellte. Die aktuelle Version ist die, die hingateway-status als gestartet anzeigt.

Rollback

Die Appliance behält zwei Betriebssystem-Deployments auf der Festplatte: das laufende und das vorherige. Um zum vorherigen zurückzukehren, verwenden Sie die Schaltfläche Roll back im Dashboard (siehe HIN Gateway aktualisieren) oder führen Sie Folgendes aus:

hingateway-rollback && sudo systemctl reboot

Für das Rollback ist kein Download nötig. Um weiter als bis zur vorherigen Version zurückzugehen, wechseln Sie mit hingateway-switch <tag> explizit auf diese Version.

Ein Rollback stellt das Betriebssystem-Image wieder her, nicht die Daten

Ein Rollback tauscht nur das Betriebssystem-Image aus; die Daten unter /var/data bleiben so, wie die neuere Version sie hinterlassen hat. Hat die neuere Version ein Datenbankschema geändert (zum Beispiel das Keycloak-Upgrade in 1.1.7), kann die ältere Version damit nicht laufen. Führen Sie in diesem Fall das Rollback des Betriebssystem-Images durch und stellen Sie danach das vor dem Update erstellte Backup wieder her - das Archiv in /var/data/backups/, dessen Name auf pre_update_to_<Zielversion>.tar.gz endet - mit sudo /usr/share/stargate-deployment/docker-compose/scripts/restore.sh <archive>. Das nächtliche Backup löscht Archive, die älter als 7 Tage sind, auch dieses; kopieren Sie es daher von der VM weg, wenn Sie es später brauchen könnten. Ausnahme ist das Update von 0.6.x auf 1.1.7: Dort führt der einzige Weg zurück über den VM-Snapshot (siehe HIN Gateway aktualisieren).

Kein Rollback über das erste Data-Disk-Image hinweg

Das erste Upgrade auf ein Image mit Data-Disk-Unterstützung ist eine Einbahnstrasse. Ein älteres Image ohne Data-Disk-Unterstützung bindet den Data Disk nicht ein: Der Stack startet mit einem leeren /var/data, während Ihre echten Daten unverändert auf dem nicht eingebundenen Datenträger liegen. Das sieht wie ein vollständiger Datenverlust aus, ist aber keiner - ein erneutes Upgrade auf die neuere Version bindet den Datenträger wieder ein.

Was ein Update beibehält

/etc wird mit dem neuen Image zusammengeführt (lokale Änderungen haben Vorrang), und /var - einschliesslich /home, Docker-Daten und Benutzerkonten - bleibt erhalten. Mit rpm-ostree install nachinstallierte Pakete überstehen Neustarts, werden aber beim nächsten Wechsel entfernt; dauerhaft ist nur, was Teil des Images ist.

Reine Compose-Installation

Dieser Abschnitt gilt nur für einen selbst verwalteten git clone dieses Repositorys, nicht für die VM-Appliance. Führen Sie alle Befehle im Verzeichnis docker-compose/ Ihres Checkouts aus. Die Skripte lesen und schreiben Dateien unter /var/data/vereign/, die nur root lesen kann; führen Sie sie daher als root oder mit sudo aus. Der Checkout sollte ebenfalls root gehören (klonen Sie ihn als root): Laufen die Skripte als root in einem Checkout, der einem anderen Benutzer gehört, verweigert git den Zugriff, und die Version der Bereitstellung wird als unknown angezeigt. Gehört der Checkout einem anderen Benutzer, erlauben Sie ihn einmalig mit sudo git config --global --add safe.directory <path to the checkout> und führen Sie die git-Befehle unten als dieser Benutzer ohne sudo aus.

1. Erstellen Sie ein Backup vor der Aktualisierung

sudo ./scripts/backup.sh

Kopieren Sie das Archiv von der Maschine weg, wenn Sie es später brauchen könnten: Das nächtliche Backup löscht Archive, die älter als 7 Tage sind.

2. Das Ziel-Release auschecken

Das Repository ist die alleinige Quelle der Wahrheit für nachverfolgte Dateien. Aktualisieren Sie daher, indem Sie einen Release-Tag auschecken. Dadurch werden nachverfolgte Dateien (Skripte, docker-compose.yml mit den festgelegten Image-Versionen, Konfigurationsvorlagen) durch die Versionen dieses Releases ersetzt:

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

3. Auf neue Konfigurationsvariablen prüfen

Vergleichen Sie die Variablennamen der Konfigurationsvorlage des Releases mit Ihrer vorhandenen Konfiguration, um zu sehen, ob neue Variablen hinzugefügt wurden. Es werden nur die Namen verglichen, Ihre Werte und Anmeldedaten werden also nicht ausgegeben; Zeilen, die mit > beginnen, sind neue Variablen:

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

Tun Sie dies vor dem nächsten Schritt: update.sh ergänzt jede fehlende Variable mit dem Standardwert der Vorlage in Ihrer customer-config.sh, sodass die neuen Variablen danach nicht mehr als Unterschied erscheinen. Setzen Sie jede neue Variable, die einen anderen als den Standardwert braucht, jetzt in customer-config.sh.

4. Das Release anwenden

sudo ./scripts/update.sh

update.sh erzeugt .env aus customer-config.sh neu, lädt die in docker-compose.yml festgelegten Images herunter und erstellt die betroffenen Dienste neu. Die Ausgabe wird an /var/data/vereign/update.log angehängt; der neueste Lauf steht am Ende.

5. Den Stack neu starten

sudo ./scripts/start.sh

update.sh erstellt Vault (und Dozzle, falls aktiviert) zwingend neu, die übrigen Dienste aber nur, wenn sich ihre Definition geändert hat. Ein Dienst, dessen Konfigurationsdatei sich im Release geändert hat (zum Beispiel die Caddy-, APISIX- oder Loki-Konfiguration), kann daher mit der alten Datei weiterlaufen. start.sh erstellt alle Container neu, sodass alle die neuen Dateien übernehmen. Dabei wird der Stack ein zweites Mal neu gestartet; planen Sie das Update daher in einem Wartungsfenster.

Note

Ihre customer-config.sh, .env und das secrets/-Verzeichnis liegen unter /var/data/vereign/, vollständig ausserhalb des Repository-Checkouts, und werden von git checkout -f daher nie 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: Der nächste Checkout 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.

Für ein Rollback checken Sie den vorherigen Release-Tag aus und führen die Schritte 4 und 5 erneut aus. Hat das neuere Release ein Datenbankschema geändert, führen Sie die Schritte 4 und 5 nicht aus: Stellen Sie nach dem Auschecken des vorherigen Tags stattdessen das Backup vor dem Update mit sudo ./scripts/restore.sh <archive> wieder her (siehe Wiederherstellung aus einem Backup). restore.sh stoppt den Stack, stellt die Daten wieder her und startet die Dienste des ausgecheckten Releases.

update.sh entfernt bereits nicht verwendete Images, die älter als 24 Stunden sind. Um sofort Speicherplatz freizugeben, führen Sie sudo docker image prune -af aus.

Versionen nicht von Hand ändern

Warning

Image-Versionen sind in docker-compose.yml festgelegt, nicht in customer-config.sh oder .env - diese enthalten keine *_VERSION-Werte mehr. Bearbeiten Sie keinen Image-Tag von Hand: Versionen werden als Satz gemeinsam veröffentlicht und getestet, und eine einzelne von Hand auszuwählen ergibt eine ungetestete Kombination. Auf der VM-Appliance ist die Datei ohnehin schreibgeschützt. Wechseln Sie Releases immer wie oben beschrieben.

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_<SERVICE>=<automatisch generiert, eines pro Dienst>

## 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://localhost:8084
OUTBOUND_SEALER_MX_DOMAIN=hintest.ch

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

Warning

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.

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

Jeder Dienst hat ein eigenes Token in /var/data/vereign/secrets/service-tokens.env, das auf den Mount dieses Dienstes beschränkt ist. Administrative Befehle wie das Auflisten der Mounts benötigen das Root-Token aus vault-keys.json im selben Verzeichnis. Die Beispiele lesen das Token aus der Datei, sodass es weder in der Befehlszeile noch im Shell-Verlauf erscheint.

Status prüfenMounts auflistenEin Secret schreiben

docker exec stargate-vault vault status

VAULT_TOKEN=$(jq -r .root_token /var/data/vereign/secrets/vault-keys.json) \
  docker exec -e VAULT_TOKEN stargate-vault vault secrets list

VAULT_TOKEN=$(sed -n 's/^VAULT_TOKEN_SMIMEKEYS_CLIENT="\(.*\)"$/\1/p' /var/data/vereign/secrets/service-tokens.env) \
  docker exec -e VAULT_TOKEN stargate-vault vault kv put secret-smimekeys-client/test key=value

Datenbanken

Erstellte PostgreSQL-Datenbanken:

• smimekeys_client
• policy
• irisagent
• mxengine

Mit PostgreSQL verbinden

docker exec -it stargate-postgres psql -U postgres

Oder extern verbinden

psql -h localhost -U postgres -d smimekeys_client

Richtlinien (Rego)

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

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

Aktuelle Richtlinie anzeigen

Alle Richtlinien auflistenRichtlinieninhalt anzeigen

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT id, name, policy_group, filename, to_timestamp(updated_at) as updated FROM policies;"

docker exec stargate-postgres psql -U postgres -d policy \
  -c "SELECT rego FROM policies WHERE name='deliveryStrategy';"

Richtlinien-Speicherort

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

Logs

Alle DiensteBestimmter Dienst

docker compose logs -f

docker compose logs -f <service>

Z.B.:

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

Fehlerbehebung

Zertifikatsausstellung fehlgeschlagen / WireGuard-Tunnel nicht eingerichtet

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

Symptome:

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

Ursachen (in dieser Reihenfolge prüfen):

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

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

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

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

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

Nachdem das Problem behoben ist:

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

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

Vault ist nach dem Neustart versiegelt

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

./scripts/start.sh

Images können nicht gepullt werden

Melden Sie sich bei der Registry an:

docker login hub.docker.com

Dienst startet nicht

Logs prüfen:

docker compose logs <service-name>

Alles zurücksetzen

Warning

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

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

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

Dateistruktur

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

Schnelle Gesundheits- und Logprüfungen

Führen Sie die umfassende Gesundheitsprüfung durch

Schnelle GesundheitsprüfungAusführliche Ausgabe

./scripts/health-check.sh

./scripts/health-check.sh -v

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

Diese Prüfung umfasst:

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

Für manuelle Log-Inspektion:

Logs prüfen (letzte 10 Zeilen)

docker logs stargate-smimekeys-client --tail 10
docker logs stargate-policy --tail 10
docker logs stargate-irisagent --tail 10
docker logs stargate-mxengine --tail 10

Logs in Echtzeit verfolgen

docker logs -f stargate-mxengine

Alle Container-Status prüfen

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

Logs aller Container in Echtzeit verfolgen

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

Logs an den Support senden

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

Logs aller Container hochladen:

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

Verwenden Sie unser Skript:

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

Oder manuell ausführen:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Tip

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

Verwenden Sie unser Skript:

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

Oder manuell ausführen:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --since 1h --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Dies ist der Standard

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

Verwenden Sie unser Skript:

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

Oder manuell ausführen:

docker ps -a --format '{{.Names}}' | xargs -I {} sh -c 'docker logs --tail 500 --timestamps {} 2>&1 | sed "s/^/[{}] /"' | curl https://pastebin.hin-infra.ch/ --data-binary @-

Logs bestimmter Container hochladen:

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

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

Tip

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

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

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

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

Warning

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

Helm-Bereitstellung

Info

Demnächst verfügbar

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

VM-Bereitstellung

Stargate Azure Deployment mittels eines Images

Stargate auf Azure bereitstellen

Azure Port 25 (SMTP) Anforderungen

Warning

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

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

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

Referenz: Troubleshoot outbound SMTP connectivity in Azure

Image-Datei herunterladen

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

Azure VHD-Image-Datei hochladen

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

Image erstellen

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

VM erstellen

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

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

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

Zuerst die Data Disk anhängen

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

HIN Gateway installieren

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

Support

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

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

Stargate VMware ESXi-Bereitstellung mittels eines Images

Stargate auf VMware bereitstellen

Image-Datei herunterladen

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

Navigieren Sie zur ESXi-Web-Benutzeroberfläche

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

Data Disk enthalten

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

HIN Gateway installieren

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

Support

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

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

Proxmox-Bereitstellung mittels eines Images

Stargate auf Proxmox bereitstellen

URL der Image-Datei abrufen

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

Image-Datei in Proxmox importieren

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

VM erstellen

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

Zuerst die Data Disk anhängen

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

HIN Gateway installieren

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

Support

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

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

Windows 11 Pro-Bereitstellung mittels eines Images

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

Hyper-V installieren

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

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

Image abrufen

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

Image-Datei importieren und VM damit erstellen

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

Zuerst die Data Disk anhängen

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

HIN Gateway installieren

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

Support

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

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

Stargate-Bereitstellung auf Cloudscale mittels eines Images

URL der Image-Datei abrufen

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

Image-Datei in Cloudscale importieren

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

VM erstellen

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

Ohne Passwort ist die SSH-Passwortauthentifizierung deaktiviert

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

• Klicken Sie auf Launch.

Zuerst die Data Disk anhängen

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

HIN Gateway installieren

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

Support

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

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

VM-Images Katalog

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

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

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

Linux und macOSWindows

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

sha256sum <Dateiname>

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

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

Öffnen Sie PowerShell und führen Sie aus:

Get-FileHash "<Dateiname>"

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

Image Name	Image Typ	Image Größe	Link	SHA256 Prüfsumme
hingateway-v1.1.7.x86_64.mf		4.0K / 364 bytes	Download	caafd4817e8c6c397f24d3ef284b774c9282a3300e77ea33727180203a813bf3
hingateway-v1.1.7.x86_64.ova		3.3G / 3496058880 bytes	Download	6617a8fc37aba7571bad277c3d14f53885154114c08b34809102e78864188965
hingateway-v1.1.7.x86_64.ovf		12K / 9322 bytes	Download	47b1297b724ecdf575ce350175c2513d25e8daa3aa79f34f4962e43eb97f9d50
hingateway-v1.1.7.x86_64.qcow2		3.3G / 3526492160 bytes	Download	f4d4b9c2994b8e674e6f649a249fe3d6e0345593e0e02f588472c199ce67582d
hingateway-v1.1.7.x86_64.raw		30G / 32212254720 bytes	Download	583763ab21804cf312b4bffa8c25c1c1b05990be5b76f0044d9804b2c5eeec2e
hingateway-v1.1.7.x86_64.raw.gz		3.3G / 3475192756 bytes	Download	f5c37aaa231dd7951f30d13cec7a783e55adaffe4b2db2853cc98a12c381d571
hingateway-v1.1.7.x86_64.vhd		31G / 32212255232 bytes	Download	100c2f3528665ad91ba2a2915634032472c8a0292e519d923dc2a6107beebeb9
hingateway-v1.1.7.x86_64.vhd.gz		3.3G / 3475192835 bytes	Download	2aa3bc86d7c2b8b3a02d1dc462096e372abdf73452301decfd2ce44501db3ca4
hingateway-v1.1.7.x86_64.vhdx		4.7G / 5007998976 bytes	Download	71a8f84014d1ecc34c3843b5b45ec2dd67f11fafbf0eb9f83164d56bb8da098a
hingateway-v1.1.7.x86_64.vmdk		3.3G / 3491979776 bytes	Download	4a5a0fd6950cac3ed539fe2834d3b84742db01462a8f93764965932cb273237e
SHA256SUMS		4.0K / 979 bytes	Download	f0fa4b8957cc007f4a91ecd0fa02d641f79e8285b74d4884d626be9c5b2fa611

Troubleshooting und Diagnose

Eine strukturierte Anleitung zur Diagnose einer Stargate-Appliance über die Befehlszeile: was Sie prüfen sollten, wo sich die Logs befinden und welche Wiederherstellungsmassnahmen sicher sind.

Wo sich die Skripte befinden

Die Hilfsskripte liegen im Bereitstellungsverzeichnis unter scripts/. Die folgenden Befehle verwenden den vollständigen Pfad für VM-Images: /usr/share/stargate-deployment/docker-compose/scripts/. Wenn Sie an einem anderen Ort installiert haben, ersetzen Sie ihn durch Ihr eigenes Installationsverzeichnis (den Ordner, der docker-compose.yml und scripts/ enthält).

docker compose ...-Befehle müssen aus dem Bereitstellungsverzeichnis ausgeführt werden:

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

Wo sich die beschreibbaren Daten befinden

Der obige docker-compose/-Verzeichnisbaum (Skripte, docker-compose.yml, Konfigurationsvorlagen) ist zur Laufzeit schreibgeschützt. Alle beschreibbaren Daten liegen stattdessen unter /var/data: .env, customer-config.sh, secrets/, die generierte TLS-, Keycloak- und APISIX-Konfiguration, Backups sowie die eigenen Daten jedes Dienstes (STARGATE_DATA_DIR überschreibt dieses Stammverzeichnis für Tests). Im Einzelnen: Konfiguration und Secrets liegen unter /var/data/vereign/ und Backups unter /var/data/backups/. Die vollständige Übersicht finden Sie unter Docker erweiterte Konfiguration. Verwenden Sie bevorzugt die Wrapper-Skripte (./scripts/start.sh, ./scripts/stop.sh, ...) statt eines blossen docker compose up -d, das /var/data/vereign/.env nicht von selbst einliest.

---

1. Erster Schritt: der Health Check

Ein einziger Befehl gibt einen Überblick über die gesamte Appliance:

QuickVerbose

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v

Er meldet «bestanden» oder «fehlgeschlagen» für: Container (running/healthy), Liveness-Endpunkte (smimekeys, policy, irisagent, mxengine), den Vault-Siegelstatus, die PostgreSQL-Verbindung und -Datenbanken, SeaweedFS, den WireGuard-Tunnel und die Peer-Handshakes, den Stalwart-MTA (Ports 25 / 10026), die Prometheus-Metrik-Endpunkte sowie Festplatte und Arbeitsspeicher.

Tip

Führen Sie diesen Befehl zuerst aus. Eine einzelne FAIL-Zeile führt Sie in der Regel direkt zum passenden Abschnitt weiter unten.

---

2. Wo sich die Logs befinden

Ebene	Befehl	Was angezeigt wird
Systemstart / Erstinstallation / Autostart	sudo journalctl -u stargate -n 200 --no-pager	Der systemd-Dienst, der start.sh beim Systemstart ausführt, sowie die Installation beim ersten Start
Updates (VM-Appliance)	hingateway-status, docker logs stargate-ops-agent --tail 100 und journalctl -u greenboot-healthcheck	Gestartete, bereitgestellte und Rollback-Betriebssystemversion; Backup, Download und Fehler eines Updates (nur bis zum nächsten Neustart); Ergebnis des Boot-Health-Checks
update.sh-Läufe	cat /var/data/vereign/update.log	Ausgabe aller update.sh-Läufe, der neueste steht am Ende: Updates reiner Compose-Installationen, Dashboard-Updates auf älteren VMs vor bootc und Läufe nach Änderungen an customer-config.sh
Ein einzelner Dienst	docker logs stargate-<service> --tail 100	z. B. stargate-dashboard, stargate-mxengine, stargate-keycloak
Einen Dienst live verfolgen	docker logs -f stargate-mxengine	Echtzeit
Alle Container live	docker ps -a --format '{{.Names}}' \| xargs -I{} sh -c 'docker logs --timestamps -f {} 2>&1 \| sed "s/^/[{}] /"'	Zusammengeführt, mit dem Containernamen als Präfix
Web-Log-Viewer	Dozzle unter https://<SERVER_IP>:8190 (Keycloak-Anmeldung)	Alle Container-Logs in einer Weboberfläche durchsuchen

Um Logs an den HIN-Support zu übermitteln, verwenden Sie das Upload-Skript: Es sammelt die letzten N Log-Zeilen aller Dienste (zusammen mit Host- und Versionsinformationen), lädt sie hoch und gibt einen Link aus, den Sie weitergeben können. Siehe Logs an den Support senden:

/usr/share/stargate-deployment/docker-compose/scripts/send-logs-to-support.sh --tail 5000     # last 5000 lines from each service
# other options:  --since 1h   |   --until 5m   |   --all   (no argument = --tail 500)

Der Upload ist auf 20 MB begrenzt. Verwenden Sie auf einer stark ausgelasteten Appliance daher besser --tail/--since statt --all.

---

3. Container laufen nicht oder starten ständig neu

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

Prüfen Sie die Spalte Status:

Status	Bedeutung	Massnahme
Up ... (healthy)	Läuft einwandfrei	-
Up ... (ohne Health-Status)	Läuft; kein Health Check definiert	Prüfen Sie die docker logs, wenn Sie ein Problem vermuten
Restarting	Absturzschleife	docker logs stargate-<svc>: Beheben Sie die eigentliche Fehlerursache (Konfiguration, Secret, Abhängigkeit)
Exited (0)	Einmalige Initialisierung erfolgreich abgeschlossen (z. B. *-init, vault-data-fixer)	Normal
Exited (1+)	Fehlgeschlagen	docker logs stargate-<svc>: Die letzten Zeilen zeigen den Grund
Created	Nie gestartet, da eine Abhängigkeit nicht hochgefahren ist	Prüfen Sie, wovon der Dienst abhängt (depends_on, in der Regel Postgres/Vault), und beheben Sie zuerst dieses Problem

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

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

Startreihenfolge

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

---

4. Diagnose anhand der Symptome

Dashboard oder Keycloak lädt nicht / Anmeldung nicht möglich

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

WireGuard-Tunnel ausgefallen / Zertifikatsausstellung schlägt fehl

Dies ist das häufigste Problem: Zertifikate lassen sich nicht ausstellen, wenn der Tunnel ausgefallen ist. Beheben Sie deshalb immer zuerst das Tunnelproblem.

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

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

Vault versiegelt oder Initialisierung fehlgeschlagen

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

• Vault muss entsiegelt sein, damit smimekeys, mxengine und policy funktionieren. Die Schlüssel liegen in /var/data/vereign/secrets/vault-keys.json.
• Wenn vault-init mit einem Exit-Code ungleich null beendet wurde, fehlt die Schlüsseldatei möglicherweise oder ist beschädigt. Prüfen Sie die Logs dieses Containers; ein erneuter Aufruf von /usr/share/stargate-deployment/docker-compose/scripts/init-vault.sh versucht die Entsiegelung erneut.

/var/data/vereign/secrets/vault-keys.json nicht löschen

Geht diese Datei verloren, verlieren Sie den Zugriff auf alle gespeicherten Secrets. Bewahren Sie ein Backup auf.

PostgreSQL / Datenbankverbindung

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

• Eine vorübergehende Meldung the database system is starting up (57P03) unmittelbar nach einem Neustart ist normal: Die Dienste verbinden sich automatisch neu.
• Anhaltende Authentifizierungsfehler bedeuten in der Regel, dass POSTGRES_PASSWORD in .env nicht mehr mit dem Datenvolume übereinstimmt. Beachten Sie die Hinweise zu Updates und Secrets und bearbeiten Sie diesen Wert nicht von Hand.

E-Mails werden nicht zugestellt

• Eingehende E-Mails kommen auf :25 (Stalwart) an. Viele Cloud-Anbieter sperren Port 25 standardmässig:

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

  Wenn 25 gesperrt ist, beantragen Sie bei Ihrem Anbieter eine Freigabe. - Ausgehende E-Mails und Sealing laufen über Stalwart → mxengine (:8084 HTTP, SMTP :1587): docker logs stargate-mxengine. - Mail-Schleifen erkennen Sie daran, dass dieselbe Nachricht immer wieder zirkuliert. Prüfen Sie, ob der MX-Eintrag Ihrer Domain nicht auf die IP-Adresse dieser Appliance selbst zurückverweist. - Das vorgesehene Routing ist unter Mail-Relay-Einrichtung und DNS-Einrichtung beschrieben.

Ein Update ist fehlgeschlagen

Auf der VM-Appliance führt der Ops-Agent ein Update aus dem Dashboard in drei Phasen aus: ein Backup (backup.sh), der Download des Ziel-Betriebssystem-Images (bootc switch) und der Neustart in dieses Image. Beginnen Sie mit:

docker logs stargate-ops-agent --tail 100     # the update orchestrator: backup, download, errors
hingateway-status                             # booted, staged and rollback OS versions

Der Ops-Agent-Container wird bei jedem Start neu erstellt; sein Log deckt ein Update daher nur bis zum Neustart der VM ab. Verwenden Sie nach einem Neustart stattdessen hingateway-status und journalctl -u greenboot-healthcheck.

• Fehler beim Backup. Schlägt das Backup vor dem Update fehl, bricht der Ops-Agent das Update ab; es wurde also nichts verändert. Prüfen Sie die Fehlermeldung im Ops-Agent-Log und den freien Speicherplatz auf dem Data Disk (df -h /var/data) und starten Sie das Update anschliessend erneut.
• Fehler beim Download. Der Update-Status im Dashboard zeigt den Fehler als bootc switch: ... an; das Ops-Agent-Log enthält nur os select failed mit dem Exit-Status. Meist erreicht die VM die Image-Registry nicht (prüfen Sie den ausgehenden Internetzugang und DNS) oder die Betriebssystem-Festplatte ist voll (df -h /sysroot). Die laufende Version ist davon nicht betroffen; starten Sie das Update erneut, sobald die Ursache behoben ist.
• Heruntergeladen, aber die Version hat sich nicht geändert. Die neue Version wird erst durch einen Neustart aktiv. Haben Sie Later gewählt, starten Sie die VM neu (sudo systemctl reboot) und prüfen Sie erneut hingateway-status. Wurde die VM neu gestartet und zeigt trotzdem die alte Version als gestartet an, hat sie automatisch ein Rollback durchgeführt - siehe nächster Punkt.
• Automatisches Rollback nach einem fehlgeschlagenen Start. Nach dem Start einer neuen Version laufen Health-Checks - unter anderem, ob Docker läuft, der Data Disk eingebunden ist und der Stargate-Stack funktioniert, dazu die Standard-Checks des Betriebssystems. Schlägt ein erforderlicher Check fehl, wird der Start als RED markiert und die VM startet selbstständig wieder die vorherige Version. journalctl -u greenboot-healthcheck zeigt, welcher Check fehlgeschlagen ist. Beheben Sie die Ursache, bevor Sie das Update erneut versuchen; ein blosser Neustart wiederholt dasselbe Rollback. Hat die neue Version bereits ein Datenbankschema geändert oder war das fehlgeschlagene Update das erste Upgrade auf ein Image mit Data-Disk-Unterstützung (der Stack zeigt dann ein leeres /var/data, Ihre Daten sind aber unverändert), lesen Sie die Rollback-Hinweise, bevor Sie etwas anderes tun.
• Die neue Version startet, ist aber nicht funktionsfähig. Prüfen Sie den Boot-Health-Check mit journalctl -u greenboot-healthcheck und den Stack mit /usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v. Um zur vorherigen Version zurückzukehren, verwenden Sie Roll back im Dashboard oder führen Sie hingateway-rollback && sudo systemctl reboot aus - lesen Sie vorher die Rollback-Hinweise.
• Prüfen Sie nach einem erfolgreichen Update, ob die Versionen übernommen wurden: /usr/share/stargate-deployment/docker-compose/scripts/gather-app-versions.sh (oder die Image-Tags in docker compose ps).
• Hängt ein einzelner Dienst nach einem Update, erstellen Sie nur diesen Dienst neu: cd /usr/share/stargate-deployment/docker-compose && sudo docker compose --env-file /var/data/vereign/.env up -d --no-deps --force-recreate <service>. sudo ist nötig, weil nur root .env lesen kann, und --no-deps verhindert, dass Compose auch die Abhängigkeiten des Dienstes neu erstellt, etwa Vault, das danach versiegelt wäre. Existiert /var/data/vereign/docker-compose.override.yml (oder .yaml), fügen Sie nach --env-file /var/data/vereign/.env die Optionen -f docker-compose.yml -f <Override-Datei> hinzu, damit der Override weiterhin angewendet wird. Dienste, die zu einem Profil gehören, benötigen dieses ebenfalls: --profile dozzle für dozzle und oauth2-proxy, --profile keri-idagent für idagent und --profile keri-watcher für watcher.

Bei einer reinen Compose-Installation (einem selbst verwalteten git clone) gibt es kein Update über den Ops-Agent: Sie führen update.sh selbst aus, und die Ausgabe wird an /var/data/vereign/update.log angehängt; der neueste Lauf steht am Ende. Die Update-Schritte finden Sie unter Reine Compose-Installation.

Warning

Versuchen Sie nicht, ein Update auf der VM-Appliance mit git oder update.sh --release zu reparieren. /usr/share/stargate-deployment ist Teil des schreibgeschützten Betriebssystem-Images, und es gibt keinen Repository-Checkout, der zurückgesetzt werden könnte; Versionen ändern sich nur durch den Wechsel des Betriebssystem-Images.

Ältere VMs (vor dem bootc-Image)

VMs, die aus einem Image vor der bootc-Appliance installiert wurden, haben unter /usr/share/stargate-deployment einen Git-Checkout statt eines schreibgeschützten Betriebssystem-Images. Die obigen Schritte für die VM-Appliance gelten für sie nicht. Langfristig sollten sie auf eine bootc-Appliance migriert werden, wie im englischsprachigen Leitfaden «Migrating a Compose Deployment to a bootc Appliance» beschrieben. Bis dahin gilt das Folgende nur für diese älteren VMs. Auf ihnen führt der Ops-Agent update.sh aus, dessen Ausgabe an /var/data/vereign/update.log angehängt wird (der neueste Lauf steht am Ende) - prüfen Sie diese Datei zuerst, wenn ein Update fehlschlägt.

Das Update startet, aber nichts passiert (Update von einer älteren Version). Bleibt das Ops-Agent-Log bei pulling deployment repo ... stehen und geht das Update nicht weiter, enthält das Repository auf der VM höchstwahrscheinlich lokale Änderungen an einer versionierten Datei (meist eine von Hand angepasste docker-compose.yml). Dadurch verweigert der git checkout des Ops-Agents die Ausführung, und das Update bleibt stehen. Setzen Sie das Repository zwangsweise auf den neuesten Stand zurück und führen Sie das Update anschliessend erneut aus. Git ist die einzige verbindliche Quelle; dabei gehen ausschliesslich lokale Änderungen an versionierten Dateien verloren. customer-config.sh, .env und secrets/ liegen unter /var/data/vereign/, also ausserhalb des Repository-Checkouts, und bleiben immer erhalten:

cd /usr/share/stargate-deployment
sudo git fetch origin
sudo git checkout -f main
sudo git reset --hard origin/main
cd docker-compose
sudo /usr/share/stargate-deployment/docker-compose/scripts/update.sh

update.sh erzeugt .env neu, lädt die Images herunter und erstellt die betroffenen Dienste neu. Hat das Release Konfigurationsdateien geändert, führen Sie anschliessend sudo /usr/share/stargate-deployment/docker-compose/scripts/start.sh aus, damit alle Container die neuen Dateien übernehmen. Starten Sie nach Abschluss das Update erneut über das Dashboard; es läuft nun durch.

Warning

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

VMs mit v0.5.1

Die folgenden Schritte aktualisieren eine VM von v0.5.1 auf v0.5.3. Unter v0.5.x liegen .env, customer-config.sh und secrets/ im Checkout unter /usr/share/stargate-deployment/docker-compose/, nicht unter /var/data/vereign/. Melden Sie sich mit dem Linux-Administratorkonto an der VM an.

1. Bearbeiten Sie /usr/share/stargate-deployment/docker-compose/.env und setzen Sie die Ops-Agent-Version auf v0.0.3.
2. Bearbeiten Sie /usr/share/stargate-deployment/docker-compose/customer-config.sh und setzen Sie auch dort die Ops-Agent-Version auf v0.0.3.
3. Laden Sie die Release-Tags herunter: cd /usr/share/stargate-deployment && sudo git fetch --tags origin
4. Checken Sie das Ziel-Release aus: sudo git checkout v0.5.3. Checken Sie nicht main aus: Dieser Branch enthält die aktuellen Skripte, die das neuere /var/data-Layout erwarten.
5. Aktualisieren Sie den Ops-Agent-Container: cd docker-compose && sudo docker compose up -d ops-agent
6. Melden Sie sich im Dashboard an.
7. Öffnen Sie Settings.
8. Geben Sie im Abschnitt Update am Seitenende die Zielversion (v0.5.3) ein und starten Sie den Update-Vorgang.

Migrieren Sie die VM danach auf eine bootc-Appliance, wie im englischsprachigen Leitfaden «Migrating a Compose Deployment to a bootc Appliance» beschrieben.

Dozzle (Log-Viewer) nicht erreichbar

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

Onboarding: Die Eingabe des Aktivierungscodes führt zu einem Fehler

Wird der Aktivierungscode abgelehnt, prüfen Sie der Reihe nach:

• Falscher Code: Der Code wurde nicht vollständig kopiert (abgeschnitten beim Kopieren, ein zusätzliches Leerzeichen oder ein fehlendes Zeichen). Kopieren Sie den vollständigen Code erneut und geben Sie ihn nochmals ein.
• Code bereits verwendet: Der Code wurde bereits bei einem früheren Onboarding eingelöst. Fordern Sie einen neuen Code an.
• WireGuard / Verbindung zu HIN: Der irisagent-Tunnel steht nicht, deshalb kann der Code nicht bei HIN validiert werden. Siehe oben WireGuard-Tunnel ausgefallen (/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v, docker logs stargate-irisagent).
• Keine Domain mit der Registrierung verknüpft: Mit der HIN-Registrierung des Kunden ist keine Domain verknüpft, es gibt also nichts zu aktivieren. Dies wird auf HIN-Seite behoben.

Onboarding: Aktivierungscode akzeptiert, aber es werden keine Domains angezeigt

Wahrscheinlichste Ursache: Der WireGuard-Tunnel ist nicht aufgebaut, meist wegen einer falschen öffentlichen IP-Adresse oder eines nicht geöffneten Firewall-Ports. Ohne Tunnel kann die Appliance die Domainliste nicht von HIN abrufen.

• Prüfen Sie, ob SERVER_STATIC_IP in customer-config.sh mit der tatsächlichen öffentlichen IP-Adresse übereinstimmt.
• Stellen Sie sicher, dass 19818 (UDP und TCP) eingehend und ausgehend offen ist.
• Stellen Sie sicher, dass der Peer auf HIN-Seite für diese IP-Adresse registriert ist (Schritt durch den Support).
• docker logs stargate-irisagent sollte einen aktuellen Handshake zeigen. Falls nicht, beheben Sie zuerst das Tunnelproblem (siehe oben WireGuard-Tunnel ausgefallen).

Server-IP-Adresse ändern (nur bei der Ersteinrichtung)

War die Server-IP-Adresse beim ersten Start falsch oder nicht gesetzt, setzen Sie das System sauber zurück und installieren Sie es neu. Sichern Sie zuerst die Konfiguration, denn purge.sh löscht auch customer-config.sh:

/usr/share/stargate-deployment/docker-compose/scripts/backup.sh --config-only  # saves customer-config.sh
/usr/share/stargate-deployment/docker-compose/scripts/purge.sh                 # destroys ALL data - see warning below
/usr/share/stargate-deployment/docker-compose/scripts/restore.sh --config-only /var/data/backups/<timestamp>_config-only.tar.gz
nano /var/data/vereign/customer-config.sh    # set SERVER_STATIC_IP=<NEW IP>
reboot                                       # installs again with the new IP

backup.sh gibt den genauen Befehl für die Wiederherstellung aus, und das Archiv bleibt in /var/data/backups, das purge.sh nicht löscht. Der Neustart führt die Installation aus und lädt auch die lokal gebauten Images neu, die purge.sh entfernt. Bei einer reinen Docker-Installation führen Sie statt des Neustarts install.sh aus.

Das TLS-Zertifikat und mehrere Dienst-URLs werden beim ersten Start aus der IP-Adresse abgeleitet. Purge und Neuinstallation erzeugen sie daher für die neue Adresse neu. Die wiederhergestellte Datei behält die generierten Passwörter und den WireGuard-Schlüssel. Ist das Gateway bereits bei HIN registriert, muss die Registrierung mit der neuen IP-Adresse aktualisiert werden.

Nur vor dem Onboarding

purge.sh löscht alle Daten unwiderruflich: Datenbanken, Vault und die S/MIME-Schlüssel. Dies ist nur auf einer neuen, noch nicht onboardeten Appliance sicher. Führen Sie purge.sh niemals aus, um die IP-Adresse eines produktiven oder bereits onboardeten Gateways zu ändern: Das führt zu Datenverlust und zu E-Mails, die sich nicht mehr entschlüsseln lassen. Für eine IP-Änderung im Produktivbetrieb wenden Sie sich an den Support.

---

5. Speicher und Festplatte

df -h /                              # is the disk full?
docker system df                     # space used by images / containers / volumes
du -sh /var/lib/docker/volumes/*     # per-volume usage (Postgres, SeaweedFS, Loki, ...)

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

---

6. VM-Ressourcen

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

Host-Metriken werden zudem für Prometheus unter :9100/metrics exportiert (siehe Überwachung). Wenn der Host swappt oder voll ausgelastet ist, müssen Sie mit schwankenden Health Checks und langsamen Updates rechnen.

---

7. Netzwerk und Ports

Schnelle Erreichbarkeitsprüfung der wichtigsten eingehenden Ports:

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

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

Ausgehender Zugriff ist erforderlich auf die Container-Registry, die S/MIME-Zertifizierungsstelle (über den WireGuard-Tunnel) und jede von Ihnen konfigurierte Remote-Loki-Instanz. Die vollständige Port-Tabelle finden Sie auf der Startseite und in der Anwendungsübersicht.

Das Docker-Netzwerk überschneidet sich mit dem lokalen Netzwerk

Die Dienste kommunizieren über ein internes Docker-Netzwerk. Docker wählt dessen Adressbereich beim Erstellen des Stacks und meidet dabei die Netzwerke, mit denen die VM in diesem Moment direkt verbunden ist. Enthält der Bereich trotzdem Adressen aus Ihrem Netzwerk, kann die Appliance diese Rechner nicht erreichen (zum Beispiel einen Mail- oder DNS-Server), und diese erreichen die Appliance nicht. Der Health Check meldet das unter Docker network:

[FAIL] stargate-network 172.18.0.0/16 overlaps host routes: 172.18.5.0/24 dev ens18 - see Troubleshooting: The Docker network overlaps the local network

• Die IP-Adresse wurde nach dem ersten Start geändert: Docker hat den Bereich gewählt, als die VM noch ihre erste Adresse hatte. Auf einem Gateway ohne Onboarding verwenden Sie Purge und Neuinstallation aus Server-IP-Adresse ändern oben; Docker wählt dann selbst einen freien Bereich. Auf einem Gateway mit abgeschlossenem Onboarding erstellen Sie das Netzwerk wie unten beschrieben neu.

• Das überschneidende Netzwerk liegt hinter einem Router (eine statische Route oder ein Netzwerk an einem anderen Standort): Docker meidet solche Netzwerke nicht. Der Health Check sieht jede Route auf dem Host, aber keine Netzwerke, die über das Standard-Gateway erreicht werden. Geben Sie Docker zuerst einen freien Bereich: Ergänzen Sie /etc/docker/daemon.json wie folgt, behalten Sie vorhandene Einstellungen bei und verwenden Sie einen Bereich, den Ihr Netzwerk nicht nutzt:

  {
    "default-address-pools": [
      { "base": "10.200.0.0/16", "size": 24 }
    ]
  }
  

  Führen Sie danach systemctl restart docker aus und erstellen Sie das Netzwerk wie unten beschrieben neu.

Beim Neuerstellen des Netzwerks bleiben alle Daten in /var/data erhalten. Stoppen Sie zuerst den Dienst, sonst hält ein laufendes Dozzle das alte Netzwerk belegt:

systemctl stop stargate
cd /usr/share/stargate-deployment/docker-compose
docker compose --env-file /var/data/vereign/.env down
systemctl start stargate
/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh

---

8. Wiederherstellungsmassnahmen

Geordnet vom geringsten bis zum stärksten Eingriff:

docker compose up -d <service>       # recreate one stuck service
sudo systemctl restart stargate      # restart the whole stack (via start.sh)
/usr/share/stargate-deployment/docker-compose/scripts/stop.sh  &&  /usr/share/stargate-deployment/docker-compose/scripts/start.sh

Backups und destruktive Wiederherstellung

/usr/share/stargate-deployment/docker-compose/scripts/backup.sh und /usr/share/stargate-deployment/docker-compose/scripts/restore.sh übernehmen die Datensicherung und -wiederherstellung. /usr/share/stargate-deployment/docker-compose/scripts/purge.sh löscht alle Daten (Datenbanken, Vault, Speicher) für eine saubere Neuinstallation. Verwenden Sie das Skript nur als letztes Mittel und nur mit einem aktuellen Backup. Details: Docker erweiterte Konfiguration.

---

9. Wann Sie sich an den Support wenden sollten

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

• Die Appliance-Version (/usr/share/stargate-deployment/docker-compose/scripts/gather-app-versions.sh) und den Kundennamen.
• Die Ausgabe des Health Checks (/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v).
• Einen Link zum Log-Paket aus /usr/share/stargate-deployment/docker-compose/scripts/send-logs-to-support.sh (siehe Logs an den Support senden).
• Was Sie gerade getan haben, als das Problem auftrat, sowie allfällige Screenshots.

Keycloak nach dem Update einrichten

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

Nach dem letzten Keycloak-Update führt eine inkompatible Änderung (Breaking Change) dazu, dass authentifizierte Benutzerinnen und Benutzer beim Aufrufen bestimmter Anwendungsrouten (z. B. Peers, Peer Certificates) unerwartet auf die Anmeldeseite umgeleitet werden.

Zur Behebung muss die folgende manuelle Konfiguration in der Keycloak-Oberfläche vorgenommen werden.

Lösungsschritte

1. Öffnen Sie Keycloak im Browser unter https://<VM IP address>:8180/admin/master/console/

   • Der Port :8180 ist zwingend: Keycloak wird auf Port 8180 bereitgestellt. Wenn Sie die IP-Adresse ohne Port öffnen, landen Sie stattdessen beim Dashboard (:443), das Sie zur Anmeldung im Realm stargate weiterleitet, in dem der Admin-Benutzer nicht existiert (die übliche Ursache für «invalid username or password» bzw. «falscher Realm» an dieser Stelle).
   • Melden Sie sich im Realm master an (der Pfad /admin/master/console/ wählt ihn aus), mit dem Benutzernamen admin (dem Wert von KEYCLOAK_ADMIN_USER, in Kleinbuchstaben) und dem Wert von KEYCLOAK_ADMIN_PASSWORD aus der Datei /var/data/vereign/.env der Maschine (auslesbar über die Linux-Konsole).

2. Wechseln Sie in der Admin-Konsole über die Realm-Auswahl (oben links) von master zu stargate.

3. Öffnen Sie Clients → dashboard.
4. Wechseln Sie zur Registerkarte Client scopes → klicken Sie auf dashboard-dedicated.
5. Wählen Sie Configure a new mapper → Audience.

6. Nehmen Sie folgende Einstellungen vor:

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

7. Klicken Sie auf Save.

Passwort eines Stargate-Benutzers in Keycloak zurücksetzen

Mit den folgenden Schritten setzen Sie das Passwort eines Stargate-Benutzers über die Keycloak-Administrationskonsole zurück.

1. Mit der HIN Gateway-VM verbinden

   • Öffnen Sie die VM-Konsole oder verbinden Sie sich per SSH mit der HIN Gateway-VM.

2. Zugangsdaten des Keycloak-Administrators abrufen

   • Öffnen Sie die Datei /var/data/vereign/.env.
   • Suchen Sie die folgenden Variablen:
     • KEYCLOAK_ADMIN_USER
     • KEYCLOAK_ADMIN_PASSWORD

3. Keycloak-Administrationskonsole öffnen

   • Rufen Sie im Browser folgende Adresse auf: http://<VM-IP>:8180/admin/master/console
   • Ersetzen Sie <VM-IP> durch die IP-Adresse der HIN Gateway-VM.

4. Bei Keycloak anmelden

   • Geben Sie den Benutzernamen und das Passwort des Administrators aus der .env-Datei ein.
   • Behalten Sie das Administratorpasswort unverändert bei. Wenn Sie es dennoch ändern, müssen Sie das neue Passwort sicher aufbewahren.

5. Realm Stargate auswählen

   • Wählen Sie in der Realm-Auswahl der Keycloak-Administrationskonsole Stargate aus.

6. Benutzer suchen

   • Öffnen Sie Users.
   • Suchen Sie den Stargate-Benutzer, dessen Passwort zurückgesetzt werden soll, und wählen Sie ihn aus.

7. Passwort des Benutzers zurücksetzen

   • Wählen Sie die Option zum Zurücksetzen des Passworts.
   • Geben Sie das neue Passwort ein und bestätigen Sie die Änderung.

Ändern oder setzen Sie im Rahmen dieses Vorgangs nicht das Passwort des Keycloak-Administrators zurück. Jede Änderung des Admin-Passworts kann dazu führen, dass Keycloak gesperrt wird und niemand mehr darauf zugreifen kann.

Aktivierungscode anfordern

Wenn Sie eine HIN Gateway-Instanz installieren oder neu installieren möchten, benötigen Sie einen Aktivierungscode, den Sie beim HIN Support erhalten.

Das Zurücksetzen des Aktivierungscodes trennt die Peer-Verbindung

Wird der Aktivierungscode einer aktiven Instanz zurückgesetzt, wird die WireGuard-Peer-Verbindung des Kunden gelöscht.

Beantragen Sie das Zurücksetzen für die falsche Kundeninstanz, wird die Verbindung dieser aktiven Instanz gelöscht und unterbrochen. Prüfen Sie deshalb vor der Anfrage genau, um welche Instanz es sich handelt, und bestätigen Sie alle darauf gehosteten Domains.

Neustart auf VM v0.6.1

Bitte beachten Sie: Wenn Sie eine Instanz, die auf v0.6.1 läuft, neu starten (REBOOT), wird sie auf die vorherige, nicht funktionierende Stalwart-Version <0.0.23 zurückgesetzt.

Wir empfehlen, die Instanz im Bereich Settings->System version auf eine neuere Version zu aktualisieren!

Versionshinweise

v1.1.7

Veröffentlicht am 14. Oktober 2026.

Neuerungen und Verbesserungen

• Ausgehende Relays können sich jetzt pro Domain mit Benutzername und Passwort authentifizieren.
• Eingehende Relays können sich jetzt pro Domain mit Benutzername und Passwort authentifizieren.
• Outlook-Vertraulichkeitskennzeichnung: E-Mails, die im Feld für Microsoft-Vertraulichkeitsbezeichnungen als vertraulich markiert sind, werden jetzt über HIN Mail verschlüsselt an Nicht-HIN-Mitglieder zugestellt.
• Zeitsynchronisierung: HIN Gateway verwendet jetzt NTP, um seine Uhr mit vertrauenswürdigen Zeitservern synchron zu halten. NTP kann im Dashboard konfiguriert werden.
• Log-Weiterleitung: Logs können jetzt mit einem API-Token an Loki gesendet werden.
• Migration von v0.5.x: Ein Migrationsskript exportiert den S/MIME-Schlüssel und das Zertifikat beim Wechsel von v0.5.x auf v0.6.x oder höher.
• Netzwerk-Standardwerte: Der Standard-DNS-Server ist jetzt 8.8.8.8 (bisher 1.1.1.1). Der DNS-Server kann während der Konfiguration geändert werden.

Fehlerbehebungen

• Wiederholte Neustarts (bis zu drei hintereinander) nach einer Änderung der Netzwerkeinstellungen behoben.
• Fehler beim Onboarding behoben, wenn der Zertifikatsimport startete, bevor die Synchronisierung des Iris Agent abgeschlossen war.
• Domains werden beim Hinzufügen jetzt von Leerzeichen bereinigt und in Kleinbuchstaben umgewandelt.
• Bestätigungsmeldung nach dem Aktualisieren eines Peers korrigiert.
• Die Benachrichtigung über eine neue Version ist jetzt in alle unterstützten Sprachen übersetzt.

v0.6.2

Veröffentlicht am 24. September 2026.

Dieses Hotfix-Release stärkt die Sicherheit von HIN Gateway, korrigiert die Stalwart-Version und deaktiviert die Spam-Filterung.

Neuerungen und Verbesserungen

• Enthält Stalwart v0.16.23, das mit dem aktuellen Regelsatz für den Spamfilter funktioniert.
• Der Spam-Regelsatz und der SpamFilter sind deaktiviert, damit ein Upstream-Release des Regelsatzes eine fixierte Version nicht beschädigen kann.

Fehlerbehebungen

• Behandlung des Spamfilters im Provisionierungsskript angepasst und Fehlerprotokollierung verbessert.
• Stalwart-Image auf Version v0.16.23 aktualisiert und eine Funktion zum Entfernen von DNSBL-Servern hinzugefügt.

v0.6.1

Veröffentlicht am 4. September 2026.

Dieses Wartungsrelease stärkt die Sicherheit von HIN Gateway, korrigiert die Verarbeitung von E-Mail-Headern und verbessert die Anleitungen für Updates und Migrationen.

Neuerungen und Verbesserungen

• Sicherheit: Der externe Zugriff auf interne Service-Ports wurde eingeschränkt, Authentifizierungseinstellungen und Berechtigungen wurden verschärft.
• Updates und Rollback: Anleitungen zum Aktualisieren von HIN Gateway und zur Rückkehr zu einer früheren Version wurden hinzugefügt, verfügbar auf Englisch, Deutsch, Französisch und Italienisch.
• Migrationsanleitung: Die E-Mail-Prüfungen vor und nach der Migration wurden aktualisiert und die Multi-Domain-Anleitung wurde übersetzt.

Fehlerbehebungen

• Verarbeitung HIN-spezifischer E-Mail-Header korrigiert.
• Das fehlende VMware-Datenträger-Image wurde zu den Downloads von v0.6.0 hinzugefügt.

v0.6.0

Veröffentlicht am 31. August 2026.

Dieses Release bringt Unterstützung für Multi-Domain-Migrationen, Relay-Konfiguration auf Domain-Ebene, E-Mail-Authentifizierung (etwa DKIM und ARC) sowie Verbesserungen bei Installation, Sicherheit und Stabilität.

Neuerungen und Verbesserungen

• Multi-Domain-Setups: Mehrere Domains können jetzt auf einem einzelnen HIN Gateway konfiguriert oder dorthin migriert werden. Die aktualisierte Anleitung deckt vollständige und schrittweise Migrationen ab, einschließlich Rollback-Szenarien.
• Domain-basierte Konfiguration: Die Relay-Konfiguration ist jetzt pro Domain verfügbar.
• E-Mail-Authentifizierung: DKIM- und ARC-Signierung sowie DKIM-, ARC-, SPF- und DMARC-Prüfung können jetzt pro Domain konfiguriert werden. Die erforderlichen DNS-Einträge werden direkt im HIN Gateway angezeigt.
• Installation und Migration: Die aktualisierten Anleitungen umfassen jetzt Neuinstallationen, Single-Domain- und Multi-Domain-Migrationen, Exchange-Integration, Mail-Routing, Netzwerk und TLS-Tests.
• Appliance-Migration: Für den Umzug einer bestehenden Docker-Compose-Installation auf die Image-basierte HIN Gateway Appliance steht ein dokumentiertes Verfahren zur Verfügung.
• Backup und Wiederherstellung: Persistente Daten liegen jetzt an einem einheitlichen Ort. Die Wiederherstellung ist sicherer und es erscheinen Warnungen, wenn sich die Versionen von Backup und Ziel unterscheiden.
• Diagnose und Sicherheit: Health-Checks, Protokollierung und die Erfassung von Diagnosedaten wurden verbessert. Installations- und Wiederherstellungsskripte schützen Zugangsdaten und Backup-Daten jetzt besser.

Fehlerbehebungen

• Erstinitialisierung der Vault- und WireGuard-Einstellungen verbessert.
• Start der Dienste auf langsameren virtuellen Maschinen verbessert.
• Sonderfälle bei Backup- und Wiederherstellungsvorgängen behoben.
• Ungenaue Health-Check-Ergebnisse und fehlerhafte Konfigurations-Fallbacks behoben.

Wichtige Informationen zu Appliance-Migrationen

Folgen Sie beim Umzug einer bestehenden Docker-Compose-Installation auf die Image-basierte Appliance der entsprechenden Migrationsanleitung. Beim Wiederherstellen eines Backups werden alle Daten auf der Ziel-Appliance ersetzt. Ändert sich deren öffentliche IP-Adresse, muss HIN die zentrale WireGuard-Registrierung aktualisieren.

v0.5.3

Veröffentlicht am 29. Juli 2026. Hotfix angewendet am 5. August 2026.

Dieses Release verbessert die E-Mail-Zustellung, die Zertifikatsverwaltung, das Dashboard und die Fehlerbehebung. An SEAL gibt es keine Änderungen.

Hotfix, 5. August 2026

Im Zertifikatsimport wurde ein Problem behoben, bei dem die Domain nicht korrekt mit dem zugehörigen HIN Gateway Peer verknüpft wurde.

Der Fix wurde auf die zentralen Dienste angewendet. Lokale Installationen auf virtuellen Maschinen waren nicht betroffen und benötigten kein Update.

Neuerungen und Verbesserungen

• Für Absender und Empfänger können jetzt getrennte Relays konfiguriert werden.
• E-Mails an Empfänger außerhalb des HIN-Netzwerks können über das konfigurierte SMTP-Relay gesendet werden.
• Das bisherige stündliche Limit für die E-Mail-Verarbeitung wurde aufgehoben.
• Die Zuordnung von Absendern und Empfängern bei ein- und ausgehenden E-Mails wurde verbessert.
• Vor der Ausstellung eines S/MIME-Zertifikats wird jetzt die Inhaberschaft der Domain geprüft.
• Peer-Zertifikate können jetzt durchsucht und sortiert werden.
• TLS-Zertifikate können direkt im Dashboard erzeugt werden.
• Die Peer-Übersicht hat eine Suche und eine Seitennavigation erhalten.
• Die Suche in Logs ist jetzt einfacher.
• Wenn der private Schlüssel nicht importiert wurde, wird eine Warnung angezeigt.
• Fehlermeldungen und Diagnoseinformationen wurden verbessert.

Fehlerbehebungen

• Auswahl des Zertifikats beim Senden verschlüsselter E-Mails verbessert.
• Verarbeitung verschlüsselter Nachrichten, die mit widerrufenen oder nicht vertrauenswürdigen Zertifikaten signiert sind, korrigiert.
• Problem mit Session-Refresh-Tokens behoben.
• Mehrere Fehler in den Formularen für Einrichtung und Domain-Verwaltung behoben.
• Auswahl der Ländervorwahl und Feldvalidierung korrigiert.
• Problem beim erneuten Erzeugen eines Aktivierungscodes behoben.
• Verarbeitung bestimmter S/MIME-Signaturinformationen korrigiert.
• Fehlende Verbindungsinformationen in den Zustellprotokollen des Tunnels ergänzt.
• Die Netzwerkeinstellungen werden nach einer Änderung der IP-Adresse der virtuellen Maschine jetzt korrekt zurückgesetzt.

v0.5.1

Unser erstes 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.