Istruzioni di deployment Stargate

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

🇩🇪🇫🇷🇮🇹🇬🇧

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

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

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

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

Cos'è Stargate?

Prerequisiti

Assicurati che tutti i passaggi preparatori necessari siano stati completati prima dell'inizio delle attività di migrazione o di nuova installazione dell'HIN Gateway.

I seguenti elementi devono essere disponibili o confermati prima dell'installazione:

• Le credenziali ti verranno fornite da HIN

  • Credenziali VM
  • Credenziali Keycloak
  • Codice di attivazione

• Esportazione della/e chiave/i privata/e

Info

L'esportazione delle chiavi private è prevista solo per i clienti che passano da un MGW esistente a un nuovo HIN Gateway

• Se stai lavorando su una macchina Windows che ha accesso alla VM del Mail Gateway tramite la porta 22, possiamo assisterti durante la chiamata per abilitare l'esportazione della chiave privata dal MGW.
• Se non disponi di una macchina di questo tipo, contatta il Supporto HIN via e-mail o telefono (support@hin.ch / 0848 830 740) per aiutarti a stabilire una connessione di supporto tramite System Administration → Support Connection → Connect.

Per i clienti con più domini

Nota: applicabile a tutti gli scenari di migrazione multi-dominio!

Per ridurre il tempo necessario a eseguire la migrazione, incoraggiamo i clienti a completare i seguenti passaggi prima della data e della sessione di migrazione pianificate:

• Esporta la chiave privata per ciascun dominio.
• Identifica e documenta il flusso di posta in entrata e in uscita per ciascun dominio.

Contatta il Supporto HIN per ottenere il codice di sblocco necessario per esportare le chiavi private.

• Scarica l'ultima versione dell'immagine VM
• Requisiti firewall per WireGuard. Configura la porta WireGuard 19818 (TCP/UDP) nel tuo firewall:
  • Traffico in entrata e in uscita
  • Consenti il traffico: any-to-HIN Gateway e HIN Gateway-to-any

• L'accesso DHCP dovrebbe essere disponibile. Per maggiori informazioni consulta le "Installation Guidelines".

• Requisiti di backup - vedi "Allegato 1 - Backup e ripristino delle impostazioni dell'appliance".

Info

I requisiti di backup sono previsti solo per i clienti che passano da un MGW esistente a un nuovo HIN Gateway

• Conferma che l'MGW esistente non verrà eliminato fino al completamento dell'accettazione.

Info

Mantenere disponibile l'MGW esistente fino al completamento del report di accettazione è previsto solo per i clienti che passano da un MGW esistente a un nuovo HIN Gateway

• Accesso a DNS, connettori del server di posta, regole di trasporto e impostazioni di relay.

Guida rapida

Opzioni di installazione

• Installazione tramite immagine VM:
  • Installazione tramite immagine VM Azure
  • Installazione tramite immagine VM Windows 11 Pro (Hyper-V)
  • Installazione tramite immagine VM VMware
  • Installazione tramite immagine VM Proxmox
  • Cloudscale.ch

🖨️

Puoi ottenere questa documentazione stampata o salvata come PDF, visita la nostra Visualizzazione pagina stampa.

Integrazione con Exchange

• Integrazione con Exchange - Configura i connettori e le regole di trasporto di Microsoft Exchange (Online e On-Premises) per instradare la posta attraverso Stargate

Requisiti del server

	Minimo	Consigliato
CPU, Core	4	6
RAM, GB	8	12
SSD, GB	60	60

Requisiti comuni

• Accesso root: Deve essere eseguito come root o con sudo
• Distribuzioni supportate:
  • Distribuzioni compatibili con RHEL 8, 9 e 10 come Alma Linux, Rocky Linux, CentOS Stream
  • Ubuntu 22 e 24
  • Debian 11, 12 e 13
• Indirizzo IPv4 reale
• Record DNS validi. Il dominio deve avere:
  • Record MX che puntano ai server di posta
  • Record SPF che definisce le reti di invio consentite
  • Il server deve essere in grado di risolvere il DNS (record MX, SPF, A)
  • Utilizzato per il routing della posta e l'inserimento nella whitelist delle reti basato su SPF

Accesso di rete in entrata (il firewall deve consentire)

Porta	Protocollo	Scopo
25	TCP	SMTP - ricezione di posta da server esterni
19818	UDP+TCP	WireGuard - tunnel crittografato per la comunicazione agente-agente. Leggi la nostra Valutazione di sicurezza WireGuard

Accesso in ingresso alla VM (dal computer di amministrazione alla VM HIN Gateway)

Info

Queste regole del firewall devono essere applicate solo tra il computer di amministrazione e la VM HIN Gateway. Non è necessario esporre queste porte a Internet.

Porta	Protocollo	Scopo
80	TCP	Reindirizza il traffico HTTP a HTTPS
443	TCP	Utilizzata per gestire HIN Gateway tramite il dashboard web
8180	TCP	Utilizzata da Keycloak per autenticare gli utenti del dashboard di HIN Gateway
8190	TCP	Opzionale. Necessaria per la risoluzione dei problemi e la visualizzazione dei log
22	TCP	Opzionale. Necessaria per la risoluzione dei problemi e la modifica della configurazione

Accesso di rete in uscita (il server deve raggiungere)

Destinazione	Porta	Protocollo	Scopo
registry-1.docker.io, auth.docker.io, production.cloudflare.docker.com	443	TCP	Registry delle immagini Docker Hub
quay.io	443	TCP	Registry dei container (Keycloak, oauth2-proxy)
github.com	443	TCP	Repository delle policy (policy-sync)
Il proprio endpoint Loki (es. loki.example.com)	443	TCP	Opzionale. Necessario solo se si fornisce una propria istanza Loki a cui lo stack deve inviare i log (Alloy → Loki)
Server di aggiornamento di Alpine, AlmaLinux, ecc.	80	TCP	Vari server di aggiornamento
Server di posta di destinazione	25	TCP	Consegna posta in uscita (tramite ricerca MX)
Server DNS	53	UDP+TCP	In uscita verso server DNS pubblici
Server NTP	123	UDP	NTP sincronizza gli orologi di computer, server, dispositivi di rete e macchine virtuali con fonti di tempo precise
Peer WireGuard (rete HIN)	19818	UDP+TCP	WireGuard - tunnel crittografato per la comunicazione agente-agente
witness-{1,2,3}.verify-mail.hin-infra.ch	443	TCP	Pool di witness KERI di HIN - richiesto per la verifica delle identità degli agenti (idagent / watcher)
app.hin.ch	443	TCP	Elenco membri / domini di posta HIN (mxengine)
apisix.verify-mail.hin-infra.ch	443	TCP	Registrazione del gateway HIN durante l'onboarding (dashboard)

Nota sul firewall

A seconda della configurazione del firewall o del NAT, potrebbe essere necessario consentire esplicitamente il traffico sulle porte richieste. Per maggiori dettagli, consultare la documentazione del firewall o della configurazione NAT.

La VM deve poter accettare connessioni in ingresso sulle porte di servizio richieste e inviare le risposte al richiedente. Con un firewall stateful (ad esempio iptables con conntrack), il traffico di ritorno viene consentito automaticamente dalle regole ESTABLISHED,RELATED.

Esempio di configurazione iptables:

# Consenti il traffico di ritorno per le connessioni stabilite
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Consenti le connessioni TCP in ingresso verso le porte aperte
iptables -A INPUT -p tcp -m multiport --dports 25,19818 -j ACCEPT

# Consenti le connessioni TCP in uscita verso le porte aperte
iptables -A OUTPUT -p tcp -m multiport --dports 25,19818 -j ACCEPT

# Consenti la porta UDP 19818 in ingresso per WireGuard
iptables -A INPUT -p udp --dport 19818 -j ACCEPT

# Consenti la porta UDP 19818 in uscita per WireGuard
iptables -A OUTPUT -p udp --dport 19818 -j ACCEPT

# Servizi aggiuntivi che la VM deve poter raggiungere
# 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

Contattaci

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance HIN Mail (Stargate), contatta il supporto HIN.

Includi informazioni rilevanti come il nome del cliente, la versione dell'appliance e screenshot/log dove applicabile, per aiutarci a elaborare la tua richiesta in modo efficiente.

---

Guide di installazione

HIN Gateway: Guida tecnica per la nuova installazione e la migrazione

Introduzione

Questo documento fornisce una guida completa al processo di installazione tecnica e di migrazione verso il nuovo HIN Gateway ("Stargate Appliance").

La guida è destinata ai clienti HIN, agli amministratori IT e agli ingegneri di sistema responsabili del deployment e della configurazione del nuovo HIN Gateway e, ove applicabile, della migrazione dal Mail Gateway (MGW) esistente alla nuova soluzione.

L'HIN Gateway è una soluzione di gateway email sicuro che consente una comunicazione affidabile, crittografata e basata su policy all'interno del HIN Trust Circle. Agisce come intermediario centrale tra le infrastrutture email interne e i partner di comunicazione esterni, garantendo che tutto il traffico email venga trasmesso in modo sicuro, sia conforme alle policy dell'organizzazione e soddisfi gli standard di sicurezza HIN.

Panoramica del flusso di posta

• Le email in entrata vengono instradate tramite l'HIN Gateway, dove vengono validate, decriptate (se necessario) e verificate rispetto alle policy di fiducia e sicurezza prima di essere inoltrate al server di posta interno.
• Le email in uscita vengono inviate dai sistemi interni all'HIN Gateway, dove vengono applicati crittografia, routing e applicazione delle policy prima di essere trasmesse ai destinatari esterni.
• La comunicazione tra gateway HIN è protetta da certificati peer e tunnel WireGuard, garantendo una comunicazione affidabile tra i domini.

Processo di installazione e migrazione

La procedura strutturata e passo-passo descritta in questo documento copre sia le nuove installazioni dell'HIN Gateway sia le migrazioni da un HIN Mail Gateway (MGW) esistente. A seconda dello scenario di deployment, alcuni passaggi potrebbero applicarsi solo alle migrazioni.

1. Preparazione e pianificazione del deployment, incluso il piano di fallback ove applicabile
2. Installazione e configurazione dell'HIN Gateway
3. Attivazione del dominio e validazione del certificato
4. Integrazione nell'ambiente di posta esistente e configurazione del routing
5. Test, transizione in produzione e validazione post-deployment
6. Per le migrazioni: disattivazione del MGW esistente dopo una validazione riuscita

Migrazione

L'obiettivo di HIN è garantire un deployment sicuro, fluido e completamente validato, con un impatto minimo sulle operazioni e una continuità ininterrotta dei servizi email. Negli scenari di migrazione, il MGW esistente dovrebbe rimanere disponibile come opzione di fallback finché l'HIN Gateway non sia stato validato con successo in produzione. Dovrebbe essere dismesso solo una volta completata la migrazione e confermato un funzionamento stabile.

Domande frequenti

Posso eseguire l'installazione o la migrazione autonomamente?

Sì, l'installazione o la migrazione possono essere completate interamente dal cliente.

Per lo scenario di migrazione, l'unica eccezione è il "Passo 1.3 - Esportazione delle chiavi private". Per motivi di sicurezza e per mantenere al sicuro la tua chiave privata, devi contattare il Supporto HIN o partecipare alla chiamata di migrazione pianificata per ricevere il codice necessario a esportare la chiave privata dal Mail Gateway attualmente in funzione.

Se l'installazione o la migrazione non possono essere completate con successo, partecipa alla chiamata di supporto pianificata con i nostri ingegneri.

Ci sarà un'interruzione nella consegna delle email durante il processo di configurazione?

Migrazione: tra il "Passo 1.5 - Spegnimento del MGW VM esistente" e il "Passo 18 - Configurazione del server di posta", tutte le email verranno messe in coda sul server di posta. Una volta completato il "Passo 18 - Configurazione del server di posta", le email in coda verranno inviate o consegnate alla cassetta postale.

Nuova installazione: durante la configurazione delle regole del flusso email, tutte le email verranno messe in coda sul server di posta. Una volta completato il "Passo 18 - Configurazione del server di posta", le email in coda verranno inviate o consegnate alla cassetta postale.

Verranno perse email durante l'installazione e la migrazione?

No, nessuna email andrà persa durante l'installazione e la migrazione. Alcune email potrebbero subire un ritardo.

Panoramica dei passaggi di installazione

Passo	Argomento	Responsabilità	Migrazione	Nuova installazione
0	Verifica prerequisiti	Cliente	Sì	Sì
1.1	Smoke test	Cliente	Sì	N/A
1.2	Backup del MGW esistente	Cliente	Sì	N/A
1.3	Esportazione delle chiavi private	Cliente / HIN	Sì	N/A
1.4	Piano di contingenza / scenario di fallback	Cliente	Sì	N/A
1.5	Spegnimento del MGW VM esistente	Cliente	Sì	N/A
2	WireGuard	Cliente	Sì	Sì
3	Selezione VM di destinazione	Cliente	Sì	Sì
4	Caricamento dell'immagine VM	Cliente	Sì	Sì
5	Connessione di rete alla VM	Cliente	Sì	Sì
6	Accesso tramite browser	Cliente	Sì	Sì
7	Inserimento codice di attivazione	Cliente	Sì	Sì
8	Configurazione rete mesh	Cliente	Sì	Sì
9	Creazione rete mesh sicura	Cliente	Sì	Sì
10	Accesso a Keycloak	Cliente	Sì	Sì
11	Aggiornamento password	Cliente	Sì	Sì
12	Aggiornamento informazioni account	Cliente	Sì	Sì
13	Configurazione iniziale e setup domini	Cliente	Sì	Sì
14	Configurazione trasporto posta	Cliente	Sì	Sì
15	Configurazione intestazioni whitelist	Cliente	Sì	Sì
16	Certificati peer	HIN	Sì	Sì
17	Validazione certificati peer	Cliente	Sì	Sì
18	Configurazione server di posta	Cliente	Sì	Sì
19	Test e validazione	Cliente	Sì	Sì
20	Modifica della password della VM	Cliente	Sì	Sì
21	Disattivazione del MGW esistente	Cliente	Sì	N/A
Allegato 1	Backup e ripristino delle impostazioni dell'appliance	Cliente	Sì	N/A

Passaggi dettagliati

Passo 0 - Verifica prerequisiti

Assicurati che tutti i passaggi preparatori necessari siano stati completati prima dell'inizio delle attività di migrazione dell'HIN Gateway.

I seguenti elementi devono essere disponibili o confermati prima dell'installazione:

• Le credenziali ti saranno fornite da HIN

  • Credenziale VM
  • Credenziale Keycloak
  • Codice di attivazione

• Esportazione della chiave privata Nota: applicabile solo in caso di migrazione

  • Se stai lavorando su una macchina Windows che ha accesso alla VM del Mail Gateway tramite la porta 22, possiamo supportarti durante la chiamata nell'abilitare l'esportazione della chiave privata dal MGW.
  • Se non hai accesso a tale macchina, contatta il Supporto HIN via email o telefono (support@hin.ch / 0848 830 740) per aiutarti a stabilire una connessione di supporto tramite Amministrazione sistema → Connessione di supporto → Connetti.
• Scarica l'ultima versione dell'immagine VM
• Firewall:
  • Consentire il traffico: da qualsiasi origine a HIN Gateway e da HIN Gateway a qualsiasi destinazione
    • WireGuard: fare riferimento a Requisiti del server - Accesso alla rete in ingresso:
      • Configurare la porta WireGuard 19818 (TCP/UDP) nel firewall
        • Traffico in ingresso e in uscita
  • Consentire il traffico: macchina amministrativa → VM HIN Gateway
    • Requisiti per l'installazione:
      • Porta HTTPS 443
        • Traffico in ingresso e in uscita
      • Porta Keycloak 8180
        • Traffico in ingresso e in uscita
    • Requisiti per la risoluzione dei problemi (opzionale, necessario per visualizzare i log e modificare tutti i parametri):
      • Porta SSH 22
        • Traffico in ingresso e in uscita
      • Porta Dozzle 8190
        • Traffico in ingresso e in uscita
• L'accesso DHCP dovrebbe essere disponibile per il "Passo 5 - Connessione di rete alla VM" (raccomandato).
• Requisiti di backup: vedere "Allegato 1 - Backup e ripristino delle impostazioni dell'appliance". Nota: applicabile solo in caso di migrazione
• Nota: applicabile solo in caso di migrazione. Conferma che il MGW esistente non verrà eliminato fino al completamento dell'accettazione.
• Accesso a DNS, connettori del server di posta, regole di trasporto e impostazioni di relay.

Perché WireGuard?

La porta WireGuard assolve due importanti funzioni:

1. L'HIN Gateway utilizza questa porta per ottenere certificati peer dalla CA HIN.
2. Utilizza questa porta per stabilire un tunnel sicuro verso altri HIN Gateway, attraverso il quale avviene lo scambio sicuro di dati (es. traffico email).

!!! tip "Esportazione della chiave privata" - Applicabile solo in caso di migrazione Se stai lavorando su una macchina Windows che ha accesso alla VM del Mail Gateway tramite la porta 22, possiamo supportarti durante la chiamata nell'abilitare l'esportazione della chiave privata dal MGW.

Se non hai accesso a tale macchina, contatta il Supporto HIN via email o telefono (**support@hin.ch** / **0848 830 740**) per aiutarti a stabilire una connessione di supporto tramite **Amministrazione sistema → Connessione di supporto → Connetti**.

Passo 1.1 - Smoke test

Info

Questo passaggio si applica solo alle migrazioni a dominio singolo e multiplo

Invia email di test ai seguenti destinatari, utilizzando cassette postali a cui hai accesso in modo da poter verificare che la consegna avvenga con successo:

• Un indirizzo email HIN o un indirizzo email all'interno del tuo dominio della Comunità HIN, ad esempio: user@hin.ch
• Un indirizzo email esterno al di fuori della Comunità HIN, ad esempio: Bluewin, Gmail, Yahoo o GMX

Per il destinatario esterno, invia una email dalla Comunità HIN con (confidenziale) inserito nell'oggetto.

Testa il flusso di posta in entrambe le direzioni:

• Dal dominio HIN affidabile all'indirizzo email esterno
• Dall'indirizzo email esterno alla Comunità HIN

Verifica che tutte le email di test vengano consegnate con successo e che oggetto, contenuto del messaggio e allegati (se presenti) vengano ricevuti correttamente.

Passo 1.2 - Backup del MGW esistente

Info

Questo passaggio si applica solo alle migrazioni a dominio singolo e multiplo

Crea un backup dell'appliance MGW esistente e assicurati che la VM venga conservata fino al completamento e all'accettazione formale della migrazione. Per maggiori informazioni, vedere "Allegato 1 - Backup e ripristino delle impostazioni dell'appliance".

Verifica della configurazione di routing attuale del MGW

Prima di spegnere il MGW esistente, verifica i seguenti valori di configurazione e annotali. Probabilmente ti serviranno in seguito per configurare l'HIN Gateway:

1. Accedi al MGW e vai su "Mail System → Outgoing server" e verifica se è configurato qualcosa.
2. Per ogni dominio ospitato sul MGW, vai su Mail System → <dominio> → Forwarding server e Mail System → <dominio> → Send ALL outgoing mails from this domain to the following SMTP server, e registra i valori attuali.
   

Verifica dell'header check del MGW

Se utilizzi l'opzione Header check nel MGW, annota anche il valore configurato. Potrai impostare lo stesso header check in seguito nell'HIN Gateway.

Passo 1.3 - Esportazione delle chiavi private

Info

Questo passaggio si applica solo alle migrazioni a dominio singolo e multiplo

Per le migrazioni multi-dominio, esegui l'operazione per ciascun dominio

Assistenza HIN richiesta

Per questo passaggio è necessario un codice di sblocco. Il codice viene fornito da un HIN Support Engineer.

Se desideri continuare l'installazione autonomamente, contatta il Supporto HIN per richiedere il codice di sblocco. In caso contrario, il codice di sblocco ti sarà fornito durante la chiamata di migrazione pianificata.

1. Accedi alla webGUI del MGW esistente.
2. Aprire "Mail System".
   
3. Avviare l'applicazione cliccando su HIN_Migration-Tool_v*.exe se si desidera eseguire l'installazione autonomamente. In alternativa, è possibile attendere la chiamata di migrazione, durante la quale il support engineer assisterà l'utente durante l'installazione.
   
4. Inserire il codice di sblocco fornito dal tecnico dell'assistenza.
   
5. Selezionare "Enable export".
   
6. Inserire l'indirizzo IP dell'MGW.
   
7. Attendere la conferma.
   
8. Selezionare il dominio attendibile nella webGUI dell'MGW.
   
9. Scorrere verso il basso e selezionare l'impronta digitale gestita.
   
10. Scorrere fino alla sezione "PKCS12 download" (facoltativamente è possibile inserire una password per crittografare la chiave). Fare clic su "Download PKCS12" e salvare il file *.p12 sul computer.
    
11. Tornare all'applicazione HIN_Migration-Tool_v*.exe e disattivare il pulsante Export.
    

Passo 1.4 - Piano di contingenza / scenario di fallback

Info

Questo passaggio si applica solo alle migrazioni a dominio singolo e multiplo

Scenario di rollback - se è richiesto un rollback:

1. Arresta il nuovo HIN Gateway.
2. Accendi il MGW esistente.
3. Verifica che il traffico email in entrata e in uscita funzioni correttamente tramite il MGW esistente.
   • Per le migrazioni multi-dominio, esegui l'operazione di verifica per ciascun dominio

Passo 1.5 - Spegnimento del MGW VM esistente

Info

Questo passaggio si applica solo alle migrazioni a dominio singolo e multiplo

Spegni il MGW VM esistente.

Warning

Questo passaggio interromperà il flusso di posta. Durante l'interruzione, le email verranno messe in coda sul server di posta e consegnate dopo il completamento dell'installazione (vedere "Passo 18 - Configurazione del server di posta").

Passo 2 - WireGuard

Assicurati di aver configurato la porta WireGuard 19818 (TCP/UDP) nel tuo firewall:

• Traffico in entrata e in uscita
• Consenti traffico: any-to-HIN Gateway e HIN Gateway-to-any

Passo 3 - Selezione VM di destinazione

Seleziona una delle immagini virtuali disponibili e forniscila come descritto nella guida all'installazione nella pagina del servizio HIN Gateway:

Info

Per motivi di sicurezza e supportabilità, assicurati che il tuo hypervisor non stia eseguendo una versione end-of-life. L'appliance HIN Gateway è supportata sull'ultima versione dell'hypervisor e sulla versione maggiore immediatamente precedente.

• Installazione immagine VM:
  • Immagine VM Azure
  • Immagine Windows 11 Pro (Hyper-V)
  • Immagine VMware
  • Immagine Proxmox
  • Cloudscale
• Configurazione di Microsoft Exchange

Passo 4 - Caricamento dell'immagine VM

Carica l'immagine VM selezionata sul tuo hypervisor.

Secondo disco richiesto: il disco dati

L'appliance usa due dischi: il disco del sistema operativo dall'immagine e un disco dati separato che contiene tutta la configurazione, i secret, la posta e i database. Questa separazione consente a un aggiornamento dell'immagine di sostituire il sistema operativo senza toccare i tuoi dati.

L'OVA VMware include già questo disco. Su tutte le altre piattaforme (Proxmox, Hyper-V, Azure, Cloudscale) l'immagine è un unico disco di sistema: collega quindi un secondo disco vuoto di almeno 30 GB prima del primo avvio.

Non formattarlo né partizionarlo manualmente. Al primo avvio l'appliance formatta il disco vuoto (etichetta VEREIGN-DATA) e lo monta su /var/data. Senza di esso, il primo avvio fallisce il controllo di integrità ed esegue il rollback.

Passo 5 - Connessione di rete alla VM

Assicurati che la VM abbia una connessione di rete e che le sia stato assegnato un indirizzo IP statico.

Opzione A: Configura l'indirizzo IP della macchina virtuale direttamente nell'hypervisor che stai utilizzando.

Opzione B: Puoi configurare il server DHCP del tuo router per assegnare sempre lo stesso indirizzo IP in base all'indirizzo MAC della VM.

Opzione C: Accedi localmente tramite la console VM e configura manualmente un indirizzo IP statico. NOTA: L'immagine VM esegue un'installazione automatica durante il primo avvio. Se la rete non è configurata in questa fase, l'installazione fallirà perché l'indirizzo IP del server non può essere determinato.

Aggiungere un indirizzo IP su Linux:

1. Esegui il comando "nmtui" nella console

   nmtui
   

2. Usa i tasti freccia per navigare, quindi premi "Enter" per selezionare la "Ethernet connection" per la quale desideri modificare l'indirizzo IP.
   

3. Naviga a "IPv4 Configuration" e modifica l'impostazione da "Automatic" a "Manual".
   
4. Usa i tasti freccia per navigare ai campi dove puoi inserire l'indirizzo IP, il gateway e il server DNS. Quindi seleziona "OK".
   

5. Dopo aver salvato la configurazione dell'indirizzo IP, esegui il seguente comando nella console:

   sudo systemctl restart NetworkManager
   

Cloud-init sovrascrive le impostazioni di rete della VM dopo il riavvio

Questo riguarda solo l'immagine legacy. L'appliance bootc, ora l'impostazione predefinita, non usa cloud-init per gestire la rete, quindi non è interessata e non include gli alias cloud-init-net-* usati di seguito.

Sull'immagine legacy (tipicamente su VMware/ESXi), cloud-init non ha un'origine dati, ripiega su "DHCP sulla prima NIC" e rigenera la configurazione di rete a ogni avvio, quindi un indirizzo statico impostato con nmtui viene ripristinato dopo un riavvio. Un alias risolve la cosa in un solo passaggio disabilitando solo il rendering di rete di cloud-init, così un indirizzo impostato successivamente sul profilo esistente persiste:

1. Impedire a cloud-init di rigenerare la rete a ogni avvio:

   cloud-init-net-disable
   

2. Esegui nmtui, modifica la connessione esistente cloud-init <iface> e imposta lì l'IP statico, il gateway e il DNS. Non aggiungere un secondo profilo per la stessa interfaccia: quello di cloud-init ha una priorità di autoconnessione più alta e prevarrebbe.

   nmtui
   

3. Riavvia e verifica che l'indirizzo persista:

   sudo reboot
   # dopo il riavvio:
   nmcli device status; ip -4 addr
   

cloud-init-net-enable ripristina la rete predefinita gestita da cloud-init. Senza l'alias, il passaggio 1 è lo stesso file drop-in a mano:

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

Tip

Se hai utilizzato l'Opzione C e configurato la rete manualmente, devi eseguire i seguenti comandi:

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

Lo script di installazione rileva automaticamente l'indirizzo IP del server dalla route predefinita a ogni esecuzione: non è necessario modificare manualmente customer-config.sh. È sufficiente qualsiasi indirizzo IP raggiungibile, pubblico o privato. L'endpoint pubblico effettivo viene configurato successivamente tramite il dashboard.

Dietro NAT o un IP flottante?

Se il tuo server viene raggiunto su un IP pubblico o flottante diverso da quello della sua interfaccia di rete (comune con il NAT), imposta SERVER_STATIC_IP su quell'indirizzo raggiungibile in customer-config.sh prima di eseguire install.sh. In caso contrario lascialo vuoto in modo che venga rilevato automaticamente.

Dopo il completamento con successo degli script, procedi al "Passo 6 - Accesso tramite browser"

Question

Se non disponi delle credenziali di amministratore HIN, contatta il Supporto HIN via email o telefono (support@hin.ch / 0848 830 740). Fai riferimento alla Sezione Supporto.

Clicca qui per inviare un'email

Passo 6 - Accesso tramite browser

Apri un browser e inserisci l'indirizzo IP configurato per la VM. Dovresti vedere la schermata di configurazione iniziale.

https://<VM IP address>

Passo 7 - Inserimento codice di attivazione

Seleziona la lingua preferita e inserisci il codice di attivazione che hai ricevuto via email da HIN. Fai clic su "Next".

Non ho un codice di attivazione

Se non disponi del codice di attivazione, contatta il Supporto HIN via email o telefono (support@hin.ch / 0848 830 740). Fai riferimento alla Sezione Supporto.

Clicca qui per inviare un'email

Passo 8 - Configurazione rete mesh

Verifica la configurazione della rete mesh:

• Indirizzo IP - L'IP pubblico del traffico in uscita (rilevato automaticamente).
• Trasporto - Il protocollo di trasporto (predefinito: tcp).
• Porta - La porta WireGuard (predefinita: 19818).

Cos'è un IP pubblico?

Questo è l'indirizzo IP che la macchina utilizzerà per essere accessibile tramite Internet. Non si tratta dell'indirizzo IP interno della macchina dietro firewall o NAT, ad esempio 10.0.0.0/8, 172.16.0.0/12 o 192.168.0.0/16.

Conferma che i valori siano corretti e fai clic su "Next".

Passo 9 - Creazione rete mesh sicura

Il sistema stabilirà ora la connessione alla rete mesh sicura. Questo passaggio collega l'HIN Gateway alla rete mesh e sincronizza i certificati.

Attendi il completamento del processo. Gli indicatori di stato mostreranno "Up" quando la connessione sarà stabilita con successo. Fai clic su "Finish".

Se la connessione fallisce

Se lo stato dell'Iris Agent o della sincronizzazione dei certificati rimane "Down":

• Verifica che la porta 19818 (TCP/UDP) sia aperta nel tuo firewall (vedere "Passo 2 - WireGuard").
• Verifica che l'indirizzo IP nel "Passo 8 - Configurazione rete mesh" sia corretto e raggiungibile da Internet.
• Riavvia il processo o contatta il Supporto HIN via email o telefono (support@hin.ch / 0848 830 740).

Passo 10 - Accesso a Keycloak

Warning

La porta 8180 deve essere aperta per Keycloak. Non è necessario che sia accessibile da Internet a livello globale. Deve invece essere accessibile tra il tuo computer di amministrazione e la VM che stai installando. In caso contrario, non potrai connetterti a Keycloak e proseguire con l'installazione.

Cosa fare se viene visualizzato un errore di connessione

Verifica che la porta 8180 sia accessibile dal tuo computer verso la VM. Non appena aggiorni la configurazione, torna all'interfaccia utente all'indirizzo https://<VM IP address> e fai clic sul pulsante "Login".

Una volta stabilita la rete mesh, verrai reindirizzato alla pagina di accesso di Keycloak. Inserisci il nome utente e la password ricevuti da HIN.

Question

Se non disponi di questi dati di accesso, contatta il Supporto HIN via email o telefono (support@hin.ch / 0848 830 740). Fai riferimento alla Sezione Supporto.

Clicca qui per inviare un'email

Passo 11 - Aggiornamento password

Al primo accesso, ti verrà richiesto di cambiare la password. Inserisci una nuova password sicura e confermala.

Assicurati di ricordare la password!

Passo 12 - Aggiornamento informazioni account

Completa il tuo profilo account inserendo nome e cognome. L'indirizzo email è precompilato. Fai clic su "Submit" per continuare.

Passo 13 - Configurazione iniziale e setup domini

Info

Per le migrazioni multi-dominio, esegui l'operazione per ogni dominio che stai attivando in quel momento.

In questa schermata, configura le tue impostazioni iniziali:

• Verifica che tutti i tuoi domini fidati attuali all'interno della Comunità HIN siano visualizzati correttamente.
• Seleziona quali domini fidati devono essere Abilitati per ottenere certificati peer dalla HIN Certification Authority (HIN CA).
• Indica per quale/i dominio/i il prefisso sec.<domain> è già configurato ("Use sec-prefix").

Come verificare se il mio dominio è configurato con un Security Prefix?

Apri il nostro strumento online nel browser: https://trust.hin.ls-infra.me/, inserisci sec.<domain> e fai clic sul pulsante Check. Se viene visualizzato il messaggio:

✅ Questo dominio è crittografato.

Allora il tuo dominio è configurato con un Security Prefix e devi abilitare l'opzione Use sec-prefix.

• Verifica che il nome dell'organizzazione e i proprietari del dominio siano corretti.
  
  
• Importa il file del certificato S/MIME esistente (.p12/.pfx) dal MGW esistente:
  1. Espandi il dominio e seleziona l'opzione P12/PFX File.
  2. Se non è stata impostata una password per il file del certificato, lascia vuoto il campo password.
  3. Fai clic su "Import Certificate".
  4. Dopo l'importazione del certificato, viene visualizzato il messaggio Certificate imported successfully.
• Fai clic su "Save Configuration" alla fine della pagina per salvare le modifiche.

Warning

• Almeno un dominio deve essere Abilitato per continuare con il processo di onboarding. Il pulsante "Save configuration" diventerà attivo solo una volta soddisfatto questo requisito.
• Se noti che non tutti i domini fidati sono visualizzati o che le informazioni organizzative non sono corrette, contatta il Supporto HIN via email o telefono (support@hin.ch / 0848 830 740).

Importa la tua chiave privata esistente

Nota: applicabile per lo scenario di migrazione!

Se non importi la chiave privata dal tuo MGW esistente, verrà emessa una nuova chiave. Ciò potrebbe comportare l'impossibilità di decriptare i messaggi per un massimo di 6 ore, il che potrebbe portare a perdita di dati.

Impostazione	Descrizione
Mail server host name	Il FQDN di questa istanza del gateway di posta (es. mail.example.com).
Mail server IP addresses	Gli indirizzi IP pubblici di questo server. Aggiungi IP aggiuntivi se il server è raggiungibile su più indirizzi.
DNS	Il DNS dell'host che verrà utilizzato per risolvere i record MX e altri record DNS

Scenario di migrazione graduale multi-dominio

Durante la sessione di supporto alla migrazione, gli ingegneri HIN assisteranno il cliente nella migrazione di un dominio. Una volta completata con successo la migrazione del primo dominio, il cliente è responsabile della migrazione dei domini rimanenti in autonomia.

Passo 14 - Configurazione trasporto posta

Accederai alla dashboard dell'HIN Gateway nella pagina Domains

Pagina Domains

Info

Per le migrazioni multi-dominio, esegui l'operazione per ogni dominio attivo.

Nel menu Domains, per ogni dominio disponibile puoi configurare una rotta di trasporto specifica:

Impostazione	Descrizione
Inbound relay	Il relay SMTP per la consegna in entrata per il dominio selezionato
Outbound relay	Il relay SMTP per la consegna in uscita per il dominio selezionato. Questa impostazione corrisponde all'impostazione Forwarding server del vecchio MGW
Trusted networks	Reti aggiuntive autorizzate a fare relay tramite questo gateway. Per maggiori informazioni consulta il "Passo 18 - Configurazione del server di posta"
Configure TLS	Impostazioni del certificato TLS per le connessioni SMTP; dal pulsante Generate TLS certificate puoi generare un certificato TLS
Email authentication	Per tutte le impostazioni della sezione Email authentication fai riferimento alla sezione Email authentication (DKIM ARC SPF DMARC)

Come testare una connessione TLS?

È sempre possibile verificare se il certificato TLS configurato è stato applicato alla connessione al HIN Gateway. Eseguire il seguente comando direttamente nel terminale del HIN Gateway:

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

Oppure direttamente dal proprio computer locale:

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

Nell'output saranno visualizzati tutti i dati relativi alla connessione TLS e al certificato utilizzato.

Come convertire un certificato TLS da pfx a pem?

Utilizzare il seguente comando openssl:

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

Ad esempio:

openssl pkcs12 -in certificate.pfx -out keyStore.pem -nodes
# A volte è necessario aggiungere l'argomento -legacy sui sistemi con generatori di certificati meno recenti
openssl pkcs12 -in certificate.pfx -out keyStore.pem -nodes -legacy

Azioni aggiuntive:

• Aggiungi domini aggiuntivi facendo clic su "Add domain", se necessario.
  • se il dominio non è protetto da HIN, apparirà nell'elenco Domains come Type: Routed, il che significa che può essere gestito solo localmente

Note

Assicurati che tutte le configurazioni dell'host di relay e dei domini siano corrette prima di procedere.

Una volta rivista e completata la configurazione, fai clic su "Save" per continuare.

Pagina Settings

In questa pagina, nel menu Settings, configura le impostazioni globali di trasporto della posta per il setup del relay di posta sicuro, comuni all'intera istanza. La configurazione dettagliata per ogni dominio può essere effettuata in Domains -> $domain

Nel menu Settings sono disponibili le seguenti impostazioni:

Impostazione	Descrizione
Mail server host name	Il FQDN di questa istanza del gateway di posta (es. mail.example.com).
Mail server IP addresses	Gli indirizzi IP pubblici di questo server. Aggiungi IP aggiuntivi se il server è raggiungibile su più indirizzi.
DNS	Il DNS dell'host che verrà utilizzato per risolvere i record MX e altri record DNS
Default inbound relay	Il relay SMTP predefinito per la consegna in entrata
Default outbound relay	Il relay SMTP predefinito per la consegna in uscita

Passo 15 - Configurazione intestazioni whitelist

Info

Per il multi-dominio, esegui l'operazione per ogni dominio attivo.

Fai clic su "Domains" -> "Seleziona dominio", quindi seleziona "Whitelist headers".

Inserisci la chiave esattamente come configurata nel server di posta.

Passo 16 - Certificati peer

I certificati peer vengono emessi dalla HIN Certification Authority (HIN CA) per i domini abilitati.

Una volta completato l'onboarding, naviga alla sezione Peer certificates nel dashboard e fai clic sul pulsante "Sync certificates" per sincronizzare i tuoi certificati peer dalla HIN CA.

Passo 17 - Validazione certificati peer

Assicurati che il tuo dominio abbia ricevuto il suo certificato peer basato su policy, in fondo a "Domains" -> "nomeDominio". Lo stato di ciascun dominio deve essere "Good".

Question

Contatta il Supporto HIN via email o telefono (support@hin.ch / 0848 830 740) se riscontri problemi.

Passo 18 - Configurazione del server di posta e dell'HIN Gateway

Se hai seguito l'approccio consigliato esportando la chiave privata, importandola nell'HIN Gateway e mantenendo lo stesso indirizzo IP del MGW esistente, non è necessario apportare alcuna modifica al server di posta elettronica.

In caso contrario, configura il tuo server di posta o i componenti associati in modo che il traffico venga instradato tramite il nuovo HIN Gateway. Verifica e aggiorna le seguenti impostazioni, se necessario:

Server di posta elettronica

• Relay SMTP / smart host
• Connettori
• Regole di trasporto
• Domini di routing

Consulta Integrazione con Exchange per istruzioni dettagliate.

Configurazione dell'HIN Gateway

Pagina Domains

Info

Per le migrazioni multi-dominio, esegui l'operazione per ogni dominio attivo.

Nel menu Domains, per ogni dominio disponibile puoi configurare una rotta di trasporto specifica:

Impostazione	Descrizione
Inbound relay	Il relay SMTP per la consegna in entrata per il dominio selezionato
Outbound relay	Il relay SMTP per la consegna in uscita per il dominio selezionato. Questa impostazione corrisponde all'impostazione Forwarding server del vecchio MGW
Trusted networks	Reti aggiuntive autorizzate a fare relay tramite questo gateway. Per maggiori informazioni consulta il "Passo 18 - Configurazione del server di posta"
Configure TLS	Impostazioni del certificato TLS per le connessioni SMTP; dal pulsante Generate TLS certificate puoi generare un certificato TLS
Email authentication	Per tutte le impostazioni della sezione Email authentication fai riferimento alla sezione Email authentication (DKIM ARC SPF DMARC)

• Nota per lo scenario di migrazione: vai alla pagina di ogni dominio e aggiungi un Outbound host utilizzando il valore registrato dal campo Forwarding server del MGW nel "Passo 1.2 - Backup del MGW esistente".

• Se utilizzi Microsoft 365 / Exchange Online, aggiungi i relativi intervalli di IP in uscita pubblicati a Trusted networks affinché l'HIN Gateway consideri attendibile e inoltri la posta proveniente da Exchange Online:

  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
  

Pagina Settings

In questa pagina, nel menu Settings, configura le impostazioni globali di trasporto della posta per il setup del relay di posta sicuro, comuni all'intera istanza. La configurazione dettagliata per ogni dominio può essere effettuata in Domains -> $domain

Nel menu Settings sono disponibili le seguenti impostazioni:

Impostazione	Descrizione
Mail server host name	Il FQDN di questa istanza del gateway di posta (es. mail.example.com).
Mail server IP addresses	Gli indirizzi IP pubblici di questo server. Aggiungi IP aggiuntivi se il server è raggiungibile su più indirizzi.
DNS	Il DNS dell'host che verrà utilizzato per risolvere i record MX e altri record DNS
Default inbound relay	Il relay SMTP predefinito per la consegna in entrata
Default outbound relay	Il relay SMTP predefinito per la consegna in uscita

Passo 19 - Test e validazione

In uscita:

• Verifica che il server di posta sia configurato per inviare email all'HIN Gateway utilizzando un relay SMTP o un connettore Exchange.
• Verifica che l'HIN Gateway possa inviare email a destinatari al di fuori della Comunità HIN.
• Verifica che l'HIN Gateway possa inviare email a destinatari all'interno della Comunità HIN tramite WireGuard.
• Invia una email dalla Comunità HIN a un indirizzo email esterno (ad esempio Bluewin, Gmail, Yahoo o GMX) con (confidenziale) inserito nell'oggetto, e verifica che venga consegnata con successo.

In entrata:

• Verifica che le email crittografate possano essere ricevute dalla Comunità HIN tramite WireGuard. Un mittente del dominio hin.ch è il percorso di test più semplice.
• Verifica che le email crittografate possano essere ricevute dalla Comunità HIN tramite SMTP utilizzando S/MIME.
• Verifica che le risposte da mittenti al di fuori della Comunità HIN a una email sicura iniziale (HIN Mail-SEAL) possano raggiungere l'HIN Gateway.
• Verifica che le email in testo semplice possano essere ricevute da mittenti esterni al di fuori della Comunità HIN.
• Invia una email da un indirizzo email esterno alla Comunità HIN e verifica che venga ricevuta con successo.

Conferma:

• Le email vengono consegnate con successo in entrambe le direzioni tra il dominio HIN affidabile e gli indirizzi email esterni.
• La crittografia viene applicata dove richiesto.
• Nessun ritardo o rimbalzo inatteso.
• Il logging funziona correttamente.

Compila l'Acceptance Report e consegnalo al tuo rappresentante HIN.

Passo 20 - Modifica della password della VM

Assicurati che le credenziali della VM che ti sono state fornite inizialmente vengano modificate con una password definita da te, e conservale in un luogo sicuro e protetto.

Passo 21 - Disattivazione del MGW esistente

Info

Questo passaggio si applica solo alle migrazioni a dominio singolo e multiplo

Warning

Non eliminare immediatamente il MGW VM esistente - tienilo al sicuro fino a quando tutto non è in funzione.

1. Assicurati che non ci sia traffico attivo - controlla:
   • Nessun dominio punta al MGW (DNS, SMTP, connettori).
   • Nessuna email viene inoltrata tramite la vecchia appliance.
2. Archivia i log - esporta e salva:
   • Log delle email
   • Log di sicurezza/audit
   • Richiesti per conformità e risoluzione dei problemi
3. Pulizia (opzionale) - rimuovi:
   • Regole del firewall
   • Voci DNS
   • Configurazioni di routing che fanno riferimento al MGW esistente

Allegato 1 - Backup e ripristino delle impostazioni dell'appliance

Info

Questo passaggio si applica solo alle migrazioni a dominio singolo e multiplo

Per eseguire il backup o il ripristino delle impostazioni della tua appliance HIN, fai clic sul menu "Administration" nel portale di amministrazione web.

Backup delle impostazioni

Prima di creare un backup delle impostazioni correnti dell'appliance HIN, devi impostare una password di backup. Questa password è richiesta se devi ripristinare il backup in seguito.

• Per impostare o modificare la password di backup, fai clic su "Change Password".
• Per creare e scaricare un file di backup, fai clic su "Download".

Modifica della password di backup

Per modificare la password per i backup futuri, fai clic su "Change Password".

Note

La nuova password si applica solo ai backup creati dopo che la password è stata modificata. I file di backup esistenti rimangono protetti dalla password impostata al momento della loro creazione.

Ripristino delle impostazioni

Per ripristinare le impostazioni dell'appliance da un file di backup, fai clic su "Import Backup File...".

Nella finestra di dialogo, seleziona il file di backup richiesto e inserisci la password associata a quel backup. Le impostazioni dell'appliance verranno quindi ripristinate dal file di backup selezionato.

Backup tramite SCP

Il MGW supporta il backup dell'appliance tramite SCP.

Per utilizzare questa opzione, la chiave pubblica del sistema che accederà al MGW deve essere memorizzata in "Backup using SCP". Il backup viene generato automaticamente ogni giorno a mezzanotte e viene memorizzato sul MGW come backup.tgz.

Utilizzando la chiave pubblica configurata, il file di backup può essere recuperato tramite SCP con l'utente del sistema operativo backup. Un tipico comando SCP per recuperare il file di backup è:

scp backup@192.168.1.60:/backup.tgz .

Questo comando scarica il file backup.tgz dal MGW alla directory locale corrente.

Note

Se inserisci una nuova chiave pubblica, la chiave esistente verrà sostituita.

Scenario di migrazione multidominio

MGW → HIN Gateway – architettura del flusso di posta, implementazione graduale e piano di rollback

Fase 1: Avvio – situazione iniziale (tutti i domini su MGW)

Stato iniziale

• Tutti i domini sono instradati attraverso MGW. Esempio: domain1.ch, domain2.ch, domain3.ch, un-domain1.ch, un-domain2.ch
• Preparazione del deployment di HIN Gateway – nessun traffico reale ancora attivo
• I record DNS MX/SPF continuano a puntare all’IP pubblico A (MGW) – nel caso in cui il MGW sia il gateway esposto verso Internet oppure l’ultimo MTA

Checklist preliminare

• Definire i parametri di riferimento della capacità attuale MGW e dei log del flusso di posta
• Verificare la connettività di Stargate lab verso Online Protect / Exchange Online / server di posta elettronica on-premise
• Allineare gli stakeholder sul calendario di migrazione e sul piano di comunicazione
• Esaminare la documentazione relativa a firewall/porte prima dell’assegnazione dell’IP pubblico B (fase 2, passaggio 1)

Fase 2: Migrazione – esempio di migrazione graduale, dominio per dominio

Procedura di migrazione

1. Abilitazione di HIN Gateway – assegnare Public IP B e aggiornare le regole del firewall (si veda la documentazione di rete per le porte richieste)
2. Creare due connettori su Exchange Online – uno in entrata e uno in uscita – che puntino a Stargate
3. Aggiungere una regola del flusso di posta che instradi in base al dominio: domain1.ch → HIN Gateway, tutti gli altri domini rimangono su MGW
4. Ripetere gradualmente – spostare un dominio alla volta fino a quando tutti i domini non saranno su HIN Gateway

Rollback (per dominio)

• Reindirizzare la regola del flusso di posta del dominio interessato verso MGW
• Lasciare attivi i connettori di Stargate in vista del tentativo successivo
• Tenere un log delle modifiche per ogni variazione apportata a connettori/regole, in ordine cronologico – il rollback dovrà riprodurlo in ordine inverso

Prestare attenzione alle intestazioni specifiche del cliente

Alcuni domini utilizzano X-header personalizzati (instradamento, liste di autorizzazione antispam, tag di compliance). Verificare che i connettori di Stargate conservino/replichino queste intestazioni prima di spostare un dominio – l’assenza di intestazioni può causare un instradamento errato o il rifiuto della posta.

Fase 3: Conclusione – migrazione completa a HIN Gateway

Stato finale

• Tutti i domini passano attraverso HIN Gateway
• MGW non trasporta traffico di produzione
• DNS / SPF puntano all’IP pubblico B (nel caso in cui HIN Gateway sia il gateway esposto verso Internet oppure l’ultimo MTA)

Checklist per operazioni di pulizia

• Rimuovere i vecchi connettori MGW e le regole del flusso di posta
• Disattivare la VM di MGW una volta confermata dal monitoraggio l’assenza di traffico e verificato il corretto funzionamento del flusso della posta elettronica
• Procedere al rilascio dell’IP pubblico A qualora non sia più necessario
• Aggiornare i runbook e la documentazione del DNS

Confronto tra strategie di migrazione

Consigliata – trasferire tutti i domini in una sola volta

• Non è richiesto alcun indirizzo IP pubblico aggiuntivo
• Nessuna modifica temporanea al connettore o alle regole del flusso di posta
• Rollback semplice: spegnere Stargate e riaccendere la vecchia VM di MGW
• Finestra di cutover più breve – minima probabilità di scostamenti nella configurazione

Alternativa – graduale, dominio per dominio

• Raggio d’azione ridotto per ogni passaggio – solo un dominio alla volta è a rischio
• Richiede un secondo indirizzo IP pubblico e regole/connettori temporanei di split
• È necessario gestire le intestazioni specifiche del cliente per ciascun dominio
• Il rollback richiede la riproduzione in ordine inverso dell’esatta sequenza delle modifiche

---

Warning

Prima di eseguire qualsiasi procedura di installazione verificare che le porte del firewall e le impostazioni del connettore corrispondano esattamente a quanto indicato nell’aggiornata documentazione di rete.

Note

Consultare le indicazioni specifiche riportate nella Guida all’installazione del dominio relative alla migrazione multidominio.

Configurazione tecnica e Integrazione

Panoramica delle applicazioni

Applicazioni

• smimekeys-client - Servizio client chiavi S/MIME (porta 8081)
• policy - Servizio policy (porta 8082)
• irisagent - Servizio IRIS Agent (porta 8083, WireGuard: 19818/udp, 19818/tcp)
• mxengine - Servizio MX Engine (porta 8084, SMTP: 1587)
• stalwart - Server di posta Stalwart MTA (porta 25, 10026)
• clamav - Antivirus ClamAV; scansiona le email nella fase SMTP DATA di Stalwart tramite il protocollo milter (porta 7357)
• mtaconf - Demone di configurazione MTA (API: 8080)
• dashboard - Interfaccia di amministrazione web per onboarding, gestione dei domini e monitoraggio (porta 443)
• policy-sync - Sincronizza le policy OPA/Rego dal repository Git al database (viene eseguito in continuazione)

Infrastruttura

• PostgreSQL - Database (porta 5432)
• Vault - Gestione dei segreti (porta interna 8200, non pubblicata sull'host)
• MinIO - Storage compatibile S3 (API sulla porta host 9000; console non pubblicata sull'host)
• Keycloak - Provider di identità e autenticazione OIDC (porta 8180)
• APISIX - Gateway API con autenticazione OIDC bearer (porta 9080)
• NATS - Messaggistica inter-servizi (attiva i ricaricamenti di Stalwart dal dashboard)

Container di inizializzazione

• vault-init - Inizializza e scongela Vault al primo avvio
• seaweedfs-init - Crea il bucket S3
• apisix-init - Genera la configurazione APISIX dal modello
• keycloak-init - Imposta la password amministratore iniziale

Monitoraggio

• node-exporter - Metriche dell'host per Prometheus (porta 9100)
• version-collector - Raccoglie le versioni delle app dagli endpoint /liveness per node-exporter
• Alloy - Collettore di log per Loki (invia i log delle app)
• Dozzle - Visualizzatore di log dei container in tempo reale (porta 8190, HTTPS, dietro SSO Keycloak tramite oauth2-proxy; opzionale, abilitato con DOZZLE_ENABLED)
• oauth2-proxy - Parte affidabile OIDC che autentica l'accesso Dozzle contro Keycloak (si avvia insieme a Dozzle)

Vedere Monitoraggio e Log per configurazione dettagliata e utilizzo.

Panoramica dell'architettura

Panoramica dell'architettura VM

Monitoraggio e Log

Stargate include servizi integrati di monitoraggio e raccolta log che vengono eseguiti insieme ai container delle applicazioni.

Componenti

Servizio	Porta	Scopo
node-exporter	9100	Metriche a livello host (CPU, memoria, disco, rete) per Prometheus
version-collector	-	Raccoglie le versioni delle app dagli endpoint /liveness
Alloy	12345	Collettore di log Docker - invia i log dei container a Loki
Loki	3100 (interno)	Backend locale di aggregazione log
Dozzle	8190	Visualizzatore di log dei container basato sul web (HTTPS, SSO Keycloak; opzionale)
oauth2-proxy	8190	Parte affidabile OIDC che autentica l'accesso Dozzle (con Dozzle)

---

Dozzle - Visualizzatore di log locale

Dozzle fornisce un'interfaccia web per visualizzare i log in tempo reale di tutti i container Stargate. È opzionale e abilitato impostando DOZZLE_ENABLED="true" in customer-config.sh.

L'accesso è protetto da Keycloak: un oauth2-proxy si trova davanti a Dozzle e richiede lo stesso login del dashboard (il realm stargate). Dozzle stesso non è esposto direttamente.

Accesso: aprire https://<IP_SERVER>:8190 in un browser e accedere con le credenziali HIN Gateway (Keycloak).

Note

La porta 8190 (HTTPS) deve essere raggiungibile dalla tua rete. Se limiti l'accesso per IP o firewall, consenti 8190/tcp come fai per il dashboard e Keycloak.

I log sono organizzati per servizio. Selezionando un servizio specifico, è possibile visualizzare le relative voci di log e i dettagli.

---

Grafana Alloy - Inoltro log

Grafana Alloy raccoglie i log da tutti i container delle applicazioni Stargate e li scrive nell'istanza Loki locale. Opzionalmente, i log possono anche essere inoltrati a un endpoint remoto compatibile con Loki per il monitoraggio centralizzato.

Come funziona

1. Alloy scopre i container Stargate tramite il socket Docker
2. I log vengono sempre scritti nell'istanza Loki locale (utilizzata dal dashboard per l'esportazione dei log)
3. Se un URL Loki remoto è configurato, i log vengono inoltrati anche a quell'endpoint

Configurazione dell'inoltro log remoto

Dal dashboard HIN Gateway, navigare alla pagina Impostazioni. Nella sezione Grafana Alloy, inserire l'URL di push Loki del server di raccolta log remoto:

L'URL deve seguire il formato standard dell'API di push Loki:

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

Lasciare il campo vuoto per disabilitare l'inoltro log remoto.

Note

Le modifiche hanno effetto entro 1 minuto (Alloy interroga la configurazione del dashboard a quell'intervallo). Non è necessario riavviare il container.

Requisiti lato remoto

Il tuo endpoint Loki remoto deve essere raggiungibile dal server Stargate via HTTPS (porta 443). Se utilizzi l'inserimento in whitelist basato su IP sul tuo ingress, aggiungi l'IP pubblico del server Stargate.

---

Metriche Prometheus

Stargate espone endpoint di metriche compatibili con Prometheus dai suoi container applicativi. Questi possono essere raccolti da qualsiasi server compatibile con Prometheus per la raccolta centralizzata delle metriche.

Endpoint disponibili

Servizio	Porta	Percorso
smimekeys-client	2113	/metrics
irisagent	2114	/metrics
policy	2115	/metrics
mxengine	2116	/metrics
node-exporter	9100	/metrics
APISIX	9091	/apisix/prometheus/metrics

Configurazione di raccolta

Aggiungi il server Stargate come target nella configurazione di Prometheus. Esempio per una singola istanza:

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

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

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

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

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

Sostituisci <IP_STARGATE> con l'IP pubblico o privato del server e <nome> con un identificatore di deployment (es., prod, nome-cliente).

Tip

Le etichette environment e service consentono il filtraggio nei dashboard Grafana su più istanze Stargate.

Requisiti firewall

Le porte delle metriche (2113-2116, 9100) devono essere raggiungibili dal server Prometheus. Se limiti l'accesso per IP, aggiungi l'IP del server di monitoraggio alle regole del firewall.

---

Node Exporter

Il servizio node-exporter espone metriche standard a livello host (CPU, memoria, I/O del disco, rete) sulla porta 9100. Include anche un raccoglitore di file di testo che espone metriche personalizzate dal sidecar version-collector (informazioni sulla versione delle applicazioni).

---

Riepilogo delle porte esposte

Porta	Servizio	Protocollo	Scopo
8190	Dozzle (via oauth2-proxy)	HTTPS	Interfaccia di visualizzazione log autenticata (SSO Keycloak)
9100	node-exporter	HTTP	Metriche dell'host (Prometheus)
2113	smimekeys-client	HTTP	Metriche dell'app (Prometheus)
2114	irisagent	HTTP	Metriche dell'app (Prometheus)
2115	policy	HTTP	Metriche dell'app (Prometheus)
2116	mxengine	HTTP	Metriche dell'app (Prometheus)
9091	APISIX	HTTP	Metriche del gateway (Prometheus)

Integrazione Exchange con Stargate

Questa guida spiega come configurare Microsoft Exchange (Online e On-Premises) per instradare la posta attraverso il gateway Stargate per la firma e la crittografia S/MIME.

Panoramica

Stargate agisce come relay di posta tra server di posta esterni e l'ambiente Exchange. Sono supportati due modelli di integrazione:

Modello A - Exchange Online come MX primario con regole di trasporto:

flowchart LR
    I1 --> EO --> TR --> C --> S1 --> EO
    E2 --> TR2 --> OC --> S2 --> I2
    I1["Internet"]
    I2["Internet"]
    EO["Exchange Online"]
    E2["Exchange Online"]
    TR["Regola di trasporto"]
    TR2["Regola di trasporto"]
    OC["Connettore in uscita"]
    C["Connettore"]
    S1["Stargate"]
    S2["Stargate"]

Modello B - Stargate come MX primario:

flowchart LR
    I1 --> mx15 --> mx20
    EO --> TR --> OC --> Stargate --> I2
    I1["Internet"]
    I2["Internet"]
    mx15["Stargate (priorità MX 15)"]
    mx20["Exchange Online (priorità MX 20)"]
    EO["Exchange Online"]
    TR["Regola di trasporto"]
    OC["Connettore in uscita"]
    Stargate

In entrambi i modelli, sono necessari:

1. Record DNS che puntano al server Stargate
2. Connettore in uscita - instrada la posta da Exchange a Stargate
3. Connettore in entrata - accetta la posta da Stargate in Exchange
4. Regola di trasporto - attiva il connettore in uscita per i destinatari esterni

Prerequisiti

Prima di configurare Exchange, assicurarsi che:

• Stargate sia installato e in esecuzione (istruzioni di deployment)
• Si disponga dell'indirizzo IP pubblico del server Stargate (indicato come <STARGATE_IP> di seguito)
• Si disponga del nome host di posta del server Stargate (indicato come <MAIL_HOSTNAME>, es. mail.example.com)
• Si conosca il dominio di posta (indicato come <YOUR_DOMAIN>, es. example.com)
• Si abbia accesso admin Exchange (Centro di amministrazione Exchange o Shell di gestione Exchange on-premises)
• I record DNS siano configurati secondo la Guida alla configurazione DNS (A, MX, SPF come minimo)

---

Parte 1: Configurazione DNS

Vedere la Guida alla configurazione DNS per istruzioni complete sulla configurazione dei record A, MX, SPF, PTR, DMARC e DKIM.

Come minimo, prima di procedere con la configurazione Exchange di seguito, è necessario:

• Record A: <MAIL_HOSTNAME> che punta a <STARGATE_IP>
• Record MX: <YOUR_DOMAIN> con Stargate a priorità più alta (numero inferiore) rispetto a Exchange
• Record SPF: ip4:<STARGATE_IP> e ip4:<HIN_SEALER_IP> aggiunti al record TXT del dominio (vedere Guida alla configurazione DNS - SPF per gli IP del sigillatore)

---

Parte 2: Configurazione Exchange Online

Passo A: Creare il connettore in uscita (Office 365 → Stargate)

Questo connettore instrada la posta in uscita da Exchange Online al server relay Stargate.

1. Accedere al Centro di amministrazione Exchange - Connettori

2. Fare clic su "+ Aggiungi un connettore"

3. Connessione da: Selezionare "Office 365"

4. Connessione a: Selezionare "Server di posta della tua organizzazione"

5. Fare clic su "Avanti"

6. Nome connettore: Inserire un nome descrittivo, es.:

From Office 365 to Stargate relay server

• Selezionare "Mantieni intestazioni email interne di Exchange"

• Fare clic su "Avanti"

• Utilizzo del connettore: Selezionare "Solo quando ho una regola di trasporto che reindirizza i messaggi a questo connettore"

• Fare clic su "Avanti"

Tip

Questo è importante - il connettore non instraderà alcuna posta da solo. Verrà utilizzato solo quando attivato dalla regola di trasporto creata al Passo C.

1. Routing: Selezionare "Instrada le email attraverso questi smart host"
2. Inserire l'indirizzo IP del server Stargate: <STARGATE_IP>

3. Fare clic su "+" per aggiungerlo, quindi su "Avanti"

4. Restrizioni di sicurezza: Selezionare "Qualsiasi certificato digitale, inclusi i certificati auto-firmati"

5. Fare clic su "Avanti"

Note

Il MTA di Stargate (Stalwart) accetta TLS opportunistico sulle connessioni in entrata. Selezionare "qualsiasi certificato digitale" garantisce la connettività anche con certificati auto-firmati.

1. Email di validazione: Inserire un indirizzo email valido per il dominio (es. user@<YOUR_DOMAIN>)
2. Fare clic su "+", quindi su "Convalida"
3. Attendere il completamento della validazione, quindi fare clic su "Avanti"

Tip

Affinché la validazione riesca, il server Stargate deve essere in esecuzione e accettare posta sulla porta 25.

1. Rivedere le impostazioni e fare clic su "Crea connettore"

2. Nella schermata di conferma, fare clic su "Fine"

Passo B: Creare il connettore in entrata (Stargate → Office 365)

Questo connettore accetta la posta dal server relay Stargate in Exchange Online.

1. Dalla pagina Connettori, fare clic su "+ Aggiungi un connettore"

2. Connessione da: Selezionare "Server di posta della tua organizzazione"

3. Connessione a: Mostra "Office 365" (automatico)

4. Fare clic su "Avanti"

5. Nome connettore: Inserire un nome descrittivo, es.:

Receive mail from Stargate relay server

• Selezionare "Mantieni intestazioni email interne di Exchange"

• Fare clic su "Avanti"

• Autenticazione dell'email inviata: Selezionare "Verificando che l'indirizzo IP del server di invio corrisponda a uno dei seguenti indirizzi IP che appartengono esclusivamente alla tua organizzazione"

• Inserire l'indirizzo IP del server Stargate: <STARGATE_IP>
• Fare clic su "+" per aggiungerlo, quindi su "Avanti"

Note

Questo dice a Exchange Online di fidarsi della posta da questo specifico indirizzo IP, bypassando ulteriori controlli di spam/autenticazione per la posta già elaborata da Stargate.

1. Rivedere le impostazioni e fare clic su "Crea connettore"

2. Fare clic su "Fine"

Verificare i connettori

Dopo aver creato entrambi i connettori, la pagina Connettori dovrebbe mostrare:

Stato	Nome	Da	A
Attivo	Receive mail from Stargate relay server	La tua org	O365
Attivo	From Office 365 to Stargate relay server	O365	La tua org

Passo C: Creare la regola di trasporto

La regola di trasporto reindirizza tutta la posta in uscita attraverso il connettore in uscita Stargate, eccetto la posta proveniente da Stargate stesso (per prevenire loop di posta).

1. Accedere al Centro di amministrazione Exchange - Regole

2. Fare clic su "+ Aggiungi una regola" → "Crea una nuova regola"

3. Nome regola: Inserire un nome descrittivo, es.:

Relay all mail to Stargate except mail coming from it

1. Applica questa regola se: Selezionare "Il destinatario..." → "è esterno/interno" → "Fuori dall'organizzazione"
2. Fare clic su "Salva"

Note

Questa condizione garantisce che solo la posta in uscita (verso destinatari esterni) venga reindirizzata attraverso Stargate.

1. Fai quanto segue: Selezionare "Reindirizza il messaggio a..." → "il seguente connettore" → selezionare il connettore in uscita creato al Passo A (es. "From Office 365 to Stargate relay server")

2. Fare clic su "Salva"

3. Eccetto se: Fare clic su "+" per aggiungere un'eccezione

4. Selezionare "Il mittente..." → "L'indirizzo IP si trova in uno di questi intervalli"
5. Inserire l'indirizzo IP del server Stargate: <STARGATE_IP>
6. Fare clic su "Aggiungi", verificare che l'IP sia elencato, quindi fare clic su "Salva"

Warning

Questa eccezione è critica - previene i loop di posta. Senza di essa, la posta da Stargate che arriva a Exchange Online verrebbe reindirizzata a Stargate in un loop infinito.

1. Rivedere il riepilogo della regola. Dovrebbe mostrare:
2. Applica questa regola se: Il destinatario si trova Fuori dall'organizzazione
3. Fai quanto segue: Reindirizza il messaggio al connettore "From Office 365 to Stargate relay server"

4. Eccetto se: L'indirizzo IP del mittente si trova in uno di questi intervalli: <STARGATE_IP>

5. Fare clic su "Avanti", poi "Avanti" di nuovo, poi "Fine", poi "Fine"

6. Abilitare la regola: La regola viene creata in stato disabilitato. Fare clic sulla regola nell'elenco e impostare "Abilita o disabilita regola" su "Abilitato"

Tip

Non dimenticare di abilitare la regola - non funzionerà finché non sarà abilitata.

---

Parte 3: Configurazione del server Exchange On-Premises

Per Exchange Server On-Premises (2016, 2019), la configurazione è simile ma eseguita tramite la Console di gestione Exchange (EAC) o la Shell di gestione Exchange (PowerShell).

Connettore di invio (On-Premises → Stargate)

Creare un connettore di invio per instradare la posta in uscita attraverso Stargate:

Shell di gestione Exchange (PowerShell):

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

Centro di amministrazione Exchange (GUI):

1. Accedere a Flusso di posta → Connettori di invio
2. Fare clic su + per creare un nuovo connettore
3. Nome: "To Stargate Relay"
4. Tipo: Selezionare "Internet"
5. Impostazioni di rete: Selezionare "Instrada la posta attraverso smart host", aggiungere <STARGATE_IP>
6. Autenticazione smart host: Selezionare "Nessuna"
7. Spazio degli indirizzi: Aggiungere * (tutti i domini) o domini esterni specifici
8. Server sorgente: Selezionare il/i server di trasporto Exchange

Connettore di ricezione (Stargate → On-Premises)

Creare o modificare un connettore di ricezione per accettare la posta da Stargate:

Shell di gestione Exchange (PowerShell):

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

Centro di amministrazione Exchange (GUI):

1. Accedere a Flusso di posta → Connettori di ricezione
2. Fare clic su + per creare un nuovo connettore
3. Nome: "From Stargate Relay"
4. Tipo: Selezionare "Trasporto frontend"
5. Binding adattatore di rete: Lasciare predefinito o associare a IP specifico
6. Impostazioni di rete remote: Rimuovere il valore predefinito 0.0.0.0-255.255.255.255 e aggiungere solo <STARGATE_IP>
7. Autenticazione: Selezionare "Sicurezza esterna"
8. Gruppi di autorizzazioni: Selezionare "Server Exchange"

Regola di trasporto (On-Premises)

Creare una regola di trasporto per reindirizzare la posta in uscita attraverso il connettore di invio:

Shell di gestione Exchange (PowerShell):

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

Centro di amministrazione Exchange (GUI):

1. Accedere a Flusso di posta → Regole
2. Fare clic su + → "Crea una nuova regola"
3. Nome: "Relay outbound via Stargate"
4. Applica questa regola se: "Il destinatario si trova..." → "Fuori dall'organizzazione"
5. Fai quanto segue: "Reindirizza il messaggio a..." → "il seguente connettore" → "To Stargate Relay"
6. Eccetto se: "L'indirizzo IP del mittente è in..." → aggiungere <STARGATE_IP>

---

Parte 4: Configurazione lato Stargate

Configurazione automatica (Predefinita)

Per impostazione predefinita, Stalwart scopre automaticamente dove consegnare la posta elaborata cercando i record MX per ogni dominio configurato tramite la pagina /mail del dashboard. Filtra il proprio nome host e utilizza le voci MX rimanenti come destinazioni di consegna.

Funziona quando:

• Il dominio ha record MX che puntano sia a Stargate che a Exchange
• Stargate ha un record MX con priorità più alta (numero inferiore) rispetto a Exchange

Sostituzione manuale tramite il dashboard

Se si desidera che tutta la posta in uscita da Stargate vada a un singolo endpoint Exchange (es. Exchange Online Protection), impostare l'host di relay tramite la pagina /mail del dashboard (es. [smtp.office365.com]). Il dashboard invia il valore all'API REST di mtaconf e il demone lo applica a Stalwart.

Note

Un singolo host di relay invia tutta la posta attraverso un server e non supporta il routing per dominio. Per più domini instradati attraverso server Exchange diversi, utilizzare la mappa di relay per dominio sulla stessa pagina del dashboard (configura sender_dependent_relayhost_maps internamente) - vedere Configurazione multi-dominio di seguito.

Configurazione multi-dominio

Per configurazioni con più domini e server Exchange diversi (es. BALZ Informatik AG con 26 domini), utilizzare i record MX per il routing per dominio:

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

I record MX di ogni dominio dicono a Stargate dove consegnare la posta elaborata per quel dominio specifico.

Verificare la configurazione di Stargate

Dopo la configurazione, verificare la configurazione di Stalwart:

Verificare la configurazione del relay

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

Verificare la coda di posta (dovrebbe essere vuota quando tutto funziona)

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

Inviare un'email di test e controllare i log

docker logs stargate-stalwart --tail 50

Risoluzione dei problemi

La posta non esce da Exchange Online

• Verificare che la regola di trasporto sia abilitata (viene creata in stato disabilitato)
• Controllare le condizioni della regola - dovrebbe applicarsi ai destinatari "Fuori dall'organizzazione"
• Verificare che la validazione del connettore in uscita sia riuscita
• Controllare la traccia dei messaggi Exchange nel Centro di amministrazione per lo stato di consegna

Loop di posta (messaggi duplicati)

• Assicurarsi che la regola di trasporto abbia l'eccezione per l'indirizzo IP di Stargate
• Senza questa eccezione, la posta da Stargate che arriva a Exchange viene reindirizzata a Stargate

Stargate non accetta posta da Exchange

• Controllare che la porta 25 sia aperta sul firewall del server Stargate
• Verificare che il record SPF includa l'IP Stargate
• Controllare i log Stalwart: docker logs stargate-stalwart

Exchange Online rifiuta la posta da Stargate

• Verificare che il connettore in entrata sia configurato con il corretto IP Stargate
• Controllare che l'IP Stargate non sia cambiato
• Verificare che il connettore sia abilitato (Stato: Attivo)

Errori del certificato TLS

Stargate utilizza TLS opportunistico con un certificato auto-firmato. Il connettore in uscita in Exchange deve essere configurato per accettare "Qualsiasi certificato digitale, inclusi i certificati auto-firmati". Se si vedono errori relativi a TLS:

• Verificare che l'impostazione di sicurezza del connettore in uscita consenta certificati auto-firmati
• Per Exchange On-Premises, assicurarsi che il connettore di invio non richieda TLS (-RequireTLS $false)

La validazione fallisce durante la creazione del connettore

La validazione del connettore in uscita richiede:

• Il server Stargate è in esecuzione e accetta connessioni sulla porta 25
• L'indirizzo email di validazione è valido per il dominio
• Il percorso di rete tra Exchange Online e Stargate è aperto (nessun blocco firewall)

---

Riferimento rapido

Componente	Posizione Exchange Online	Scopo
Connettore in uscita	Centro di amministrazione → Flusso di posta → Connettori	Instradare la posta in uscita a Stargate
Connettore in entrata	Centro di amministrazione → Flusso di posta → Connettori	Accettare la posta da Stargate
Regola di trasporto	Centro di amministrazione → Flusso di posta → Regole	Attivare il connettore in uscita per i destinatari esterni

Record DNS	Esempio	Scopo
A	mail IN A <STARGATE_IP>	Puntare il nome host a Stargate
MX (Stargate)	@ IN MX 15 mail.<YOUR_DOMAIN>.	La posta in entrata colpisce prima Stargate
MX (Exchange)	@ IN MX 20 <DOMAIN>.mail.protection.outlook.com.	Fallback / destinazione di consegna
SPF	ip4:<STARGATE_IP> e ip4:<HIN_SEALER_IP> aggiunti al record TXT esistente	Autorizzare Stargate e il sigillatore HIN a inviare posta

Per la configurazione DNS completa (inclusi PTR, DMARC, DKIM e multi-dominio), vedere la Guida alla configurazione DNS.

Configurazione del relay di posta Stargate

Creare un relay Stargate per un dominio di posta ospitato in Microsoft Office 365

Per il relay, abbiamo bisogno di una VM o di un server con un indirizzo IP statico reale.

In questo esempio utilizzeremo una VM con indirizzo IP 128.140.117.200 e nome host mail.vrgnservices.eu per inoltrare la posta per il dominio vrgnservices.eu.

Configurare i record DNS

Vedi la Guida alla configurazione DNS per istruzioni complete su tutti i record richiesti (A, MX, SPF, PTR, DMARC, DKIM).

Esempio rapido per il dominio vrgnservices.eu con IP Stargate 128.140.117.200:

• Record A: mail.vrgnservices.eu → 128.140.117.200
• Record MX: MX @ 15 mail.vrgnservices.eu. (priorità più alta rispetto all'Exchange MX esistente a 20)
• Record SPF: v=spf1 ip4:128.140.117.200 include:spf.protection.outlook.com -all

Verifica:

# host mail.vrgnservices.eu
mail.vrgnservices.eu ha indirizzo 128.140.117.200

# host -t mx vrgnservices.eu
vrgnservices.eu la posta è gestita da 20 vrgnservices-eu.mail.protection.outlook.com.
vrgnservices.eu la posta è gestita da 15 mail.vrgnservices.eu.

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

Installare i container docker compose di Stargate

Deployment Stargate

Requisiti

• 2 core CPU (minimo)
• 4 GB di RAM (minimo)
• 20 GB di storage (minimo)
• Accesso root: Deve essere eseguito come root o con sudo
• Distribuzioni supportate:
  • Distribuzioni compatibili con RHEL 8, 9 e 10 come Alma Linux, Rocky Linux, CentOS Stream
  • Ubuntu 22 e 24
  • Debian 11, 12 e 13
• Indirizzo IPv4 reale
• Record DNS validi: Il dominio deve avere:
  • Record MX che puntano ai server di posta
  • Record SPF che definisce le reti di invio consentite

Lo script installa tutti i componenti e li avvia. I domini di posta e il nome host di Stalwart vengono poi configurati in fase di esecuzione tramite la pagina /mail del dashboard (il demone mtaconf estrae le impostazioni di relay di posta necessarie dal DNS in base a quei domini).

Configurare Exchange

Dobbiamo configurare connettori e una regola di trasporto in Exchange per inoltrare tutta la posta in uscita al relay Stargate e consentire la posta in entrata da esso.

Naviga su https://admin.exchange.microsoft.com/#/connectors

Connettore in uscita

Crea un connettore di posta in uscita, fai clic su "Aggiungi":

Seleziona "Connessione da": "Office 365" "Connessione a": "server di posta della tua organizzazione", fai clic su "Avanti".

Dagli un nome come "From Office 365 to Stargate relay server" e seleziona "Mantieni intestazioni email interne di Exchange", fai clic su "Avanti".

Seleziona "Solo quando ho una regola di trasporto configurata che reindirizza i messaggi a questo connettore", fai clic su "Avanti".

Inserisci l'indirizzo IP del server relay Stargate, fai clic su "+", fai clic su "Avanti".

Seleziona "Qualsiasi certificato digitale, inclusi i certificati auto-firmati", fai clic su "Avanti".

Inserisci un indirizzo email valido per il tuo dominio, fai clic su "+", fai clic su "Convalida", fai clic su "Avanti".

Fai clic su "Crea connettore".

Fai clic su "Aggiungi un altro connettore".

Connettore in entrata

Crea un connettore di posta in entrata, scegli "Connessione da": "Server di posta della tua organizzazione", fai clic su "Avanti".

Dagli un nome come "Receive mail from Stargate relay server" e seleziona "Mantieni intestazioni email interne di Exchange", fai clic su "Avanti".

Seleziona "Verificando che l'indirizzo IP del server di invio corrisponda a uno dei seguenti indirizzi IP", digita l'indirizzo IP del server Stargate, fai clic su "+", fai clic su "Avanti".

Fai clic su "Crea connettore".

Fai clic su "Fine".

Ecco come appare quando è completato:

Regola di trasporto

Crea la regola di trasporto. Naviga su https://admin.exchange.microsoft.com/#/transportrules

Fai clic su "+Aggiungi una regola" → "Crea una nuova regola".

Dagli un nome come "Relay all mail to Stargate except mail coming from it", scegli "Applica questa regola se" "Il destinatario:" "è esterno/interno" "Fuori dall'organizzazione", fai clic su "Salva".

Scegli "Fai quanto segue" "Reindirizza il messaggio al seguente connettore" "From Office 365 to Stargate relay server", fai clic su "Salva".

Scegli "Eccetto se L'indirizzo IP del mittente si trova in uno di questi intervalli" inserisci l'indirizzo IP del server Stargate, fai clic su "Aggiungi", controlla l'indirizzo IP e fai clic su "Salva".

Questo è necessario per prevenire loop di posta, poiché questa regola si applica anche ad altri domini ospitati in Office 365.

Ora dovrebbe apparire così, fai clic su "Avanti":

Fai clic su "Avanti".

Fai clic su "Fine".

Fai clic su "Fine".

Fai clic sulla regola e imposta "Abilita o disabilita regola" su "Abilitato"

Configurazione DNS per Stargate

Questa guida copre tutti i record DNS richiesti per un deployment funzionante di Stargate. Configurare questi record prima di installare Stargate o immediatamente dopo, a seconda del tipo di record.

In questa guida:

• <STARGATE_IP> - l'indirizzo IP pubblico statico del server Stargate (SERVER_STATIC_IP in customer-config.sh)
• <MAIL_HOSTNAME> - il FQDN del relay Stargate (es. mail.example.ch; configurato tramite la pagina /mail del dashboard)
• <YOUR_DOMAIN> - il dominio di posta (es. example.ch; configurato tramite la pagina /mail del dashboard)

---

Riepilogo dei record

Record	Nome	Valore	Richiesto	Quando
A	<MAIL_HOSTNAME>	<STARGATE_IP>	Sì	Prima dell'installazione
MX	<YOUR_DOMAIN>	<MAIL_HOSTNAME> (priorità 15)	Sì	Prima dell'installazione
SPF	<YOUR_DOMAIN>	ip4:<STARGATE_IP> aggiunto a TXT	Sì	Prima dell'installazione
PTR	<STARGATE_IP>	<MAIL_HOSTNAME>	Raccomandato	Prima dell'installazione
DMARC	_dmarc.<YOUR_DOMAIN>	v=DMARC1; p=none; ...	Raccomandato	Dopo l'installazione
DKIM	selector._domainkey.<YOUR_DOMAIN>	Da M365/provider	Raccomandato	Dopo l'installazione

Per deployment multi-dominio, ripetere i record MX, SPF, DMARC e DKIM per ogni dominio elencato in MAIL_DOMAINS.

---

Record richiesti

Record A

Creare un record A che punti il nome host di posta Stargate all'IP pubblico del server:

<MAIL_HOSTNAME>.    A    <STARGATE_IP>

Esempio:

mail.example.ch.    A    128.140.117.200

Se Stargate ha un indirizzo IPv6, aggiungere anche un record AAAA:

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

Perché: I server di posta esterni si connettono a questo nome host per consegnare le email. Senza il record A, il record MX sottostante non è risolvibile.

Record MX

Aggiungere un record MX per Stargate con una priorità più alta (numero inferiore) rispetto al server di posta esistente. Ciò garantisce che le email in entrata raggiungano prima Stargate per l'elaborazione S/MIME prima di essere inoltrate a Exchange o alla piattaforma di posta.

<YOUR_DOMAIN>.    MX    15    <MAIL_HOSTNAME>.

Mantenere il record MX esistente di Exchange / server di posta con una priorità inferiore (numero superiore):

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

Esempio (insieme MX completo):

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

Info

Il numero MX inferiore significa priorità più alta. Stargate con priorità 15 riceve le email prima di Exchange Online con priorità 20.

Perché: Stargate intercetta le email in entrata, elabora S/MIME, quindi le inoltra al successivo MX (Exchange). Il secondo record MX è utilizzato anche da Stalwart per sapere dove inoltrare le email elaborate.

Importante: Se Stargate è l'unico record MX per un dominio, Stalwart filtrerà il proprio nome host e non avrà alcuna destinazione di consegna. Mantenere sempre un secondo MX che punti al server di posta effettivo.

Record SPF

Aggiungere l'IP del server Stargate e l'IP del sigillatore HIN al record SPF del dominio in modo che le email in uscita inoltrate attraverso di esso superino i controlli SPF presso il destinatario.

Se si utilizza M365 / Exchange Online:

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

Se non si utilizza M365 / Google Workspace:

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

Esempio:

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

Perché l'IP del sigillatore HIN è richiesto

Quando Stargate produce un messaggio SIGILLATO (crittografato) per un destinatario non HIN, l'ultimo salto in uscita verso il destinatario è il sigillatore HIN, non il vostro Stargate o M365. Senza l'IP del sigillatore nel record SPF, ogni messaggio in uscita SIGILLATO fallirà il controllo SPF presso il destinatario e - poiché non c'è una firma DKIM sul payload SIGILLATO - anche DMARC fallirà. I destinatari con DMARC rigoroso (Gmail, Outlook con enforcement p=reject, Proofpoint) respingeranno o cestineranno il messaggio.

IP del sigillatore da aggiungere in SPF:

Ambiente	Host del sigillatore	IP da aggiungere a SPF
HIN Test (alpha/beta)	mx3.hintest.ch	193.247.208.66
HIN Produzione	TBD - richiedere lista canonica a HIN prima del go-live	TBD

Se HIN pubblica più di un host di sigillatura (es. mx1, mx2, mx3), includere tutti i loro IP. Risolverli con dig +short mx hintest.ch seguito da dig +short A <ogni-mx>. Fino a quando non si ha la lista completa, lasciare la policy SPF a ~all (softfail) invece di -all (hardfail) in modo che le email SIGILLATE legittime attraverso un IP di sigillatore non elencato non vengano immediatamente respinte.

Limite di ricerca SPF

La catena include: totale in un record SPF deve rimanere al di sotto di 10 ricerche DNS. L'aggiunta di voci ip4: non conta verso questo limite. Verificare il conteggio con MXToolbox SPF lookup.

Come Stargate utilizza SPF: Il demone mtaconf risolve il record SPF di ogni dominio per popolare automaticamente l'elenco degli IP autorizzati a inoltrare attraverso Stargate senza autenticazione. Ecco come gli IP in uscita di Microsoft 365 vengono automaticamente inseriti nella whitelist - appaiono nella catena include:spf.protection.outlook.com.

---

Record raccomandati

PTR (DNS inverso)

Configurare il record DNS inverso (PTR) per l'IP Stargate in modo che corrisponda a <MAIL_HOSTNAME>:

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

Questo viene configurato presso il provider di hosting (Hetzner, Azure, AWS, ecc.), non nel pannello DNS del registrar del dominio. La maggior parte dei provider ha un'impostazione "DNS inverso" o "rDNS" nella pagina di gestione del server/IP.

Perché: Molti server di posta riceventi (inclusi Gmail e Outlook) controllano che il record PTR dell'IP di connessione risolva un nome host e che quel nome host risolva lo stesso IP (DNS inverso a conferma diretta / FCrDNS). Un PTR mancante o non corrispondente è un forte segnale di spam e può causare fallimenti di consegna.

Record DMARC

Pubblicare una policy DMARC per ogni dominio mittente. Iniziare con p=none (solo monitoraggio), quindi rafforzare dopo aver confermato l'allineamento:

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

Esempio:

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

Una volta che i report aggregati DMARC confermano che SPF e/o DKIM passano costantemente, rafforzare la policy:

1. p=none - solo monitoraggio (iniziare qui)
2. p=quarantine - le email sospette vanno in spam
3. p=reject - le email non autorizzate vengono respinte

Perché: DMARC lega insieme SPF e DKIM e dice ai destinatari cosa fare con le email che falliscono entrambi. Anche p=none è sufficiente per rimuovere il banner "non possiamo verificare questo mittente" di Outlook, purché SPF passi.

Verificare il record DMARC: MXToolbox DMARC lookup

Record DKIM

Se il dominio è un dominio accettato in M365 o Google Workspace, abilitare la firma DKIM nel centro amministrativo e pubblicare i record CNAME come indicato:

Esempio M365:

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

Note

Pubblicare i record CNAME da soli non è sufficiente - la firma DKIM deve anche essere abilitata nel centro amministrativo M365 (portale Defender > Autenticazione email > DKIM).

Perché: DKIM dimostra che il corpo del messaggio non è stato manomesso durante il transito. Combinato con SPF e DMARC, fornisce la più forte autenticazione del mittente.

---

Configurazione multi-dominio

Per deployment che gestiscono più domini di posta (configurati tramite la pagina /mail del dashboard), ogni dominio necessita del proprio set di record DNS.

Record per dominio

Per ogni dominio configurato:

Record	Richiesto
MX che punta a <MAIL_HOSTNAME>	Sì
SPF che include ip4:<STARGATE_IP>	Sì
DMARC (_dmarc.<domain>)	Raccomandato
DKIM (dal provider di posta)	Raccomandato

Il record A e il record PTR sono condivisi (puntano al server Stargate, non ai singoli domini).

Routing di posta per dominio

I record MX di ogni dominio dicono a Stargate dove consegnare le email elaborate. Se domini diversi utilizzano server Exchange diversi:

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.

In alternativa, configurare destinazioni di relay esplicite per dominio tramite la pagina /mail del dashboard (campo host di relay per dominio) per sovrascrivere il routing basato su MX.

---

Verifica

Dopo aver configurato tutti i record, verificarli:

# Record A
host <MAIL_HOSTNAME>
# Previsto: <MAIL_HOSTNAME> ha indirizzo <STARGATE_IP>

# Record MX
host -t mx <YOUR_DOMAIN>
# Previsto: Entrambi i record MX di Stargate ed Exchange elencati

# Record SPF
host -t txt <YOUR_DOMAIN> | grep v=spf1
# Previsto: Il record SPF include ip4:<STARGATE_IP>

# PTR (DNS inverso)
host <STARGATE_IP>
# Previsto: <STARGATE_IP> → <MAIL_HOSTNAME>

# DNS inverso a conferma diretta (FCrDNS)
host $(host <STARGATE_IP> | awk '{print $NF}' | sed 's/\.$//')
# Previsto: risolve in <STARGATE_IP>

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

# DKIM (M365)
host -t cname selector1._domainkey.<YOUR_DOMAIN>
# Previsto: CNAME verso il onmicrosoft.com del tenant

Esempio di output:

$ host mail.example.ch
mail.example.ch ha indirizzo 128.140.117.200

$ host -t mx example.ch
example.ch la posta è gestita da 15 mail.example.ch.
example.ch la posta è gestita da 20 example-ch.mail.protection.outlook.com.

$ host -t txt example.ch | grep v=spf1
example.ch testo descrittivo "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 puntatore nome dominio mail.example.ch.

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

Strumenti online:

• MXToolbox MX Lookup
• MXToolbox SPF Check (include conteggio ricerche)
• MXToolbox DMARC Check
• Mail-Tester (inviare una email di test per ottenere un punteggio di deliverability)

---

Risoluzione dei problemi

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

Stalwart sta rifiutando il server mittente perché il suo IP non è nell'elenco dei relay autorizzati. Questo di solito significa:

• Il record SPF del dominio non include l'intervallo IP del server mittente
• La configurazione della posta non è stata ricaricata da quando il record SPF è stato aggiornato

Ricaricare la configurazione della posta tramite la pagina /mail del dashboard (inviare di nuovo la configurazione) o riavviare il container: docker compose restart stalwart

Email contrassegnata come spam / "impossibile verificare il mittente"

• SPF manca o non include l'IP Stargate - aggiungere ip4:<STARGATE_IP> al record SPF
• DMARC non è pubblicato - aggiungere almeno v=DMARC1; p=none
• Il record PTR manca o non corrisponde - configurare il DNS inverso presso il provider di hosting
• DKIM non è abilitato nel tenant M365/provider

La ricerca MX restituisce solo Stargate

Se Stargate è l'unico MX per un dominio, Stalwart filtra il proprio nome host e non ha alcuna destinazione di relay. Aggiungere un secondo record MX che punti al server di posta:

example.ch.    MX    15    mail.example.ch.          ← Stargate (in entrata)
example.ch.    MX    20    example-ch.mail.protection.outlook.com.  ← Exchange (destinazione relay)

Conteggio ricerche SPF superato (> 10)

Ogni include: nel record SPF attiva ulteriori ricerche DNS. La catena totale deve rimanere sotto 10. Soluzioni:

• Utilizzare voci ip4: / ip6: invece di include: dove possibile (non contano)
• Appiattire gli include nidificati usando uno strumento come SPF Flattener
• Rimuovere le voci include: inutilizzate da vecchi provider

Porta 25 bloccata dal provider di hosting

Alcuni provider cloud (Azure, alcuni piani Hetzner) bloccano la porta 25 in uscita per impostazione predefinita. Verificare con il provider e richiedere un'eccezione. Questo influisce sia sulla consegna in entrata (server esterni che si connettono a Stargate) sia sul relay in uscita (Stargate che consegna alle destinazioni MX).

Autenticazione e mail (DKIM / ARC / SPF / DMARC)

Modulo: HIN Mail Gateway -> Domains -> [dominio] -> Email authentication Si applica a: Amministratori di dominio che configurano la firma in uscita e la verifica in entrata per un dominio di posta

---

La sezione Email authentication controlla come viene dimostrata l'autenticità della posta e con quale rigore viene verificata l'autenticità della posta in entrata, ovvero la verifica DKIM/ARC/SPF/DMARC. Genera inoltre i record DNS TXT che devono essere pubblicati affinché i server di posta esterni possano verificare la posta del vostro dominio.

Si accede alla sezione tramite:

Domains -> selezionare un dominio -> Email authentication

Il pannello è composto da cinque sottosezioni:

1. DKIM
2. ARC
3. SPF
4. DMARC
5. Record DNS da pubblicare

Le modifiche vengono applicate solo dopo aver cliccato sul pulsante Save in fondo alla pagina.

---

Cosa fa ciascun protocollo

Protocollo	Direzione	Scopo
DKIM (DomainKeys Identified Mail)	Firma in uscita / Verifica in entrata	Firma crittograficamente i messaggi in uscita con una chiave privata, associata a una chiave pubblica pubblicata nel DNS, in modo che i destinatari possano confermare che il messaggio non è stato alterato durante il transito e proviene realmente da questo dominio
ARC (Authenticated Received Chain)	Firma della verifica in entrata per il relay successivo	Preserva i risultati di autenticazione DKIM/SPF originali quando un messaggio passa attraverso intermediari (ad es. mailing list, servizi di inoltro) che altrimenti comprometterebbero le firme DKIM
SPF (Sender Policy Framework)	Verifica in entrata	Verifica che l'indirizzo IP del server di posta mittente sia autorizzato a inviare posta per il dominio del mittente, sulla base di un record DNS pubblicato da quel dominio
DMARC (Domain-based Message Authentication, Reporting & Conformance)	Verifica in entrata	Collega tra loro i risultati di DKIM e SPF e indica ai server destinatari come comportarsi

Configurare correttamente DKIM e DMARC per il proprio dominio protegge la deliverability e il marchio dallo spoofing. Le impostazioni di verifica (i menu a tendina di verifica DKIM, ARC, SPF, DMARC) controllano invece con quanto rigore il gateway si fida di questi segnali sulla posta in entrata proveniente da altri domini.

---

DKIM

Campo	Descrizione
Enable DKIM signing	Quando attivo, il gateway firma tutta la posta in uscita da questo dominio con la chiave privata configurata. Attivare questa opzione prima di pubblicare il record DNS DKIM
Generate DKIM key (pulsante, in alto a destra)	Genera una nuova coppia di chiavi RSA-2048 per questo dominio e popola il campo Private key (PEM)
DKIM verification	Controlla con quale rigore un'e mail viene verificata rispetto al record DKIM pubblicato del mittente
Selector	Il selettore DKIM (ad es. s1) usato per pubblicare e cercare la chiave pubblica all'indirizzo <selector>._domainkey.<domain>. Modificare questo valore solo se è necessario eseguire più chiavi in parallelo (ad es. durante una rotazione delle chiavi): ogni selettore richiede il proprio record DNS TXT
Private key (PEM)	La chiave privata RSA usata per firmare la posta in uscita. È possibile cliccare su Generate DKIM key per crearne una, oppure incollare una propria chiave privata RSA-2048 in formato PEM

Come configurare DKIM per un nuovo dominio

1. Cliccare su Generate DKIM key (oppure incollare una chiave PEM RSA-2048 esistente gestita esternamente)
2. Lasciare Selector sul valore predefinito (s1) a meno che non ci sia un motivo per modificarlo
3. Impostare Enable DKIM signing su Active
4. Cliccare su Save
5. Copiare il record TXT s1._domainkey.<domain> generato dal riquadro DNS records to publish (vedere §7) e aggiungerlo presso il proprio provider DNS
6. Una volta propagato il record DNS, la posta firmata da questo dominio porterà una firma DKIM valida

Come ruotare una chiave DKIM

1. Cliccare su Replace key accanto a Private key (PEM)
2. Generare una nuova chiave (oppure incollarne una nuova)
3. Pubblicare il record TXT del nuovo selettore nel DNS prima di salvarlo/attivarlo in produzione, per evitare una finestra temporale in cui la posta firmata non può essere verificata
4. Salvare, quindi rimuovere il record DNS del vecchio selettore una volta confermato che la nuova chiave sta firmando correttamente

---

ARC

Campo	Descrizione
ARC verification (menu a tendina)	Controlla con quale rigore vengono validate le catene ARC in entrata
Enable ARC signing	Quando attivo, il gateway aggiunge un sigillo ARC alla posta inoltrata, preservando i risultati di autenticazione se il messaggio viene successivamente inoltrato tramite un altro sistema
Reuse DKIM key (interruttore)	Quando attivo, la firma ARC utilizza la stessa chiave RSA configurata nella sezione DKIM sopra, invece di richiederne una separata. Consigliato a meno che non ci sia una necessità specifica di mantenere le due firme crittograficamente separate

---

SPF

Campo	Descrizione
SPF verification	Controlla con quale rigore la posta in entrata viene verificata rispetto al record SPF pubblicato del dominio mittente

Nota: Questo pannello controlla solo la verifica dell'SPF in entrata; non genera un record SPF TXT in uscita per il proprio dominio (nessuna voce SPF compare nella §7 "DNS records to publish"). Se questo dominio invia posta tramite un relay esterno (ad es. Microsoft 365, configurato in Mail routing -> Outbound relay), assicurarsi che il meccanismo include: di quel provider sia già pubblicato nel record SPF del proprio dominio presso il proprio provider DNS, indipendentemente da questo gateway.

---

DMARC

Campo	Descrizione
DMARC verification	Controlla con quale rigore la posta in entrata viene verificata rispetto alla policy DMARC del mittente

Valore di verifica

Etichetta interfaccia	Valore	Comportamento
Disabled	disable	Non viene verificato affatto. Il meccanismo non viene eseguito
Optional	relaxed	Viene verificato e segnalato in Authentication-Results. Il messaggio viene sempre accettato, sia in caso di esito positivo che negativo
Required	strict	Viene verificato e segnalato, e il messaggio viene rifiutato in caso di fallimento definitivo. Altrimenti viene accettato

In sintesi: Disabled significa che non viene effettuato alcun controllo; Optional e Required verificano entrambi ed registrano il risultato. L'unica differenza tra i due è l'applicazione: Optional non rifiuta mai, Required rifiuta in caso di fallimento definitivo.

Cosa costituisce un "fallimento definitivo" per Required (per meccanismo): - DKIM: il messaggio contiene firme e tutte falliscono. Nessuna firma presente equivale a none, non un fallimento, quindi non viene rifiutato. - SPF: un fallimento definitivo -all. SoftFail/neutral/none/temp error vengono segnalati ma non provocano il rifiuto. - DMARC: né DKIM né SPF risultano allineati, e c'è un verdetto di fallimento effettivo. Nessun record DMARC pubblicato equivale a none, quindi non viene rifiutato. - ARC: la catena ARC fallisce la convalida. Nessuna catena equivale a none, quindi non viene rifiutato.

Due note importanti: - DKIM viene sempre eseguito internamente perché DMARC ne ha bisogno. L'impostazione DKIM controlla solo se viene registrato un risultato dkim= e se un fallimento DKIM può causare un rifiuto; non modifica mai il verdetto DMARC. - Ogni meccanismo è indipendente, quindi è possibile ad esempio impostare DMARC = Required mantenendo DKIM/SPF = Optional: la posta problematica viene rifiutata in base al verdetto DMARC, e si ottengono comunque righe dkim=/spf= individuali nell'header per una migliore visibilità.

---

Record DNS da pubblicare

Questo riquadro mostra i record TXT esatti da creare presso il provider DNS del proprio dominio, affinché i server di posta esterni possano verificare la posta di questo dominio. I record mostrati si aggiornano automaticamente in base al selettore DKIM e alle impostazioni della policy DMARC sopra indicate.

Record	Host	Tipo	Valore
Chiave pubblica DKIM	<selector>._domainkey.<domain> (ad es. s1._domainkey.vrgnservices.eu)	TXT	v=DKIM1; k=rsa; p=<public key>
Policy DMARC	_dmarc.<domain> (ad es. _dmarc.vrgnservices.eu)	TXT	v=DMARC1; p=<policy> (ad es. p=none)

Usare l'icona di copia nell'angolo in alto a destra di ciascun riquadro record per copiarne il valore esatto. Incollare ciascun record come nuovo record TXT presso il proprio registrar/provider DNS, usando Host/Name e Value come mostrato.

Le modifiche DNS possono impiegare da pochi minuti fino a 48 ore per propagarsi, a seconda delle impostazioni TTL del proprio provider. L'applicazione DKIM/DMARC non dovrebbe essere resa più severa (ad es. attivando la firma o spostando la policy DMARC oltre none) finché non si è confermato che i record si sono propagati e vengono risolti correttamente.

---

Salvataggio delle modifiche

Nessuna delle impostazioni sopra ha effetto finché non si clicca sul pulsante arancione Save in fondo alla pagina. Save applica insieme tutte le modifiche su DKIM, ARC, SPF e DMARC; non esiste un salvataggio per singola sezione.

---

Risoluzione dei problemi

Sintomo	Causa probabile
La posta in uscita fallisce il controllo DKIM presso i server destinatari	La firma DKIM è attiva ma il record DNS TXT non è ancora pubblicato/propagato, oppure c'è una discrepanza di selettore tra gateway e DNS.
Il sigillo ARC manca sulla posta inoltrata	Enable ARC signing è disattivato, oppure Reuse DKIM key è disattivato senza che sia configurata una chiave ARC separata.
Non è possibile vedere la chiave privata DKIM per copiarla altrove	È voluto: una volta salvata, la chiave viene mascherata (<hidden>) e non può essere visualizzata nuovamente. Usare Replace key per emetterne una nuova se è necessario spostarla su un sistema che non ne possiede già una copia.
La posta legittima inizia a essere messa in quarantena/rifiutata dopo una modifica della policy DMARC	Una fonte di invio legittima non è ancora allineata a DKIM/SPF. Riportare la policy a none, identificare la fonte problematica, correggere l'allineamento, quindi rendere di nuovo più severa la policy.

Aggiornare HIN Gateway

Questo documento spiega:

• Come aggiornare un'istanza HIN Gateway a una versione più recente.
• Come eseguire il rollback a una versione precedente.

Versioni applicabili

Questa procedura si applica solo alle versioni 0.6.x e successive.

Come aggiornare

1. Andare alla pagina Settings e scorrere fino alla sezione System version.

1. Fare clic su Other versions.

2. Dall'elenco delle versioni disponibili, selezionare la versione di destinazione.

3. Le versioni più recenti utilizzano una numerazione incrementale, quindi la versione di destinazione avrà un numero superiore a quella attuale.

4. Fare clic sul pulsante Download. Questa azione avvia solo il download, l'aggiornamento non viene ancora installato.

1. Al termine del download, viene visualizzata una finestra di conferma con due opzioni:

2. Restart now: riavvia immediatamente la macchina e installa la nuova versione.

3. Later: rimanda l'aggiornamento. La nuova versione viene installata al successivo riavvio della macchina.

Come eseguire il rollback

1. Andare alla pagina Settings e scorrere fino alla sezione System version.

1. Fare clic sul pulsante Roll back to vX.X.X.

2. Confermare l'azione nella schermata di conferma. Il sistema si riavvia e installa la versione stabile precedente.

Installazione server

Container

Deployment Docker di Stargate

Prerequisiti

Requisiti del server:

Fare riferimento a Requisiti raccomandati

• Docker verrà installato automaticamente se mancante
• Assicurarsi che ci sia una connessione Internet sulla macchina dove si stanno installando i servizi Stargate
• Assicurarsi che il traffico sia configurato correttamente per raggiungere l'istanza Stargate

Passo 1: Configurare le impostazioni cliente

Tip

È possibile clonare il nostro repository con tutti i dati e le configurazioni di esempio all'interno con il comando:

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

Se non si ha git installato, è sempre possibile ottenere un archivio con tutti i file all'interno. Scaricarlo tramite il seguente link. Scarica come ZIP

Lo script di installazione crea automaticamente customer-config.sh dal modello fornito al primo avvio, quindi una nuova installazione non richiede alcuna configurazione manuale. Se si preferisce crearlo manualmente, copiare il modello:

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

Non è necessario modificarlo - ogni valore viene rilevato automaticamente oppure configurato successivamente tramite la dashboard:

Impostazione	Come viene impostata
SERVER_STATIC_IP	Rilevato automaticamente dall'interfaccia di rete principale del server.
CUSTOMER_NAME	Per impostazione predefinita, il nome host del sistema.
DEPLOYMENT_NAME	Derivato da CUSTOMER_NAME (utilizzato nelle etichette dei log e nel nome host di Alloy).
Password e chiavi (POSTGRES_PASSWORD, S3_SECRET_KEY, VAULT_TOKEN, WG_PRIVATE_KEY)	Generate in modo sicuro al primo avvio e riscritte in customer-config.sh.

I domini di posta, il nome host di posta, i certificati S/MIME e i peer WireGuard sono tutti configurati in fase di esecuzione tramite la dashboard dopo l'avvio dello stack - non fanno parte di customer-config.sh.

Dietro NAT o un IP flottante?

Il rilevamento automatico utilizza l'IP dell'interfaccia principale del server. Se il server è raggiungibile tramite un IP pubblico o flottante diverso (comune con il NAT), impostare SERVER_STATIC_IP su quell'IP pubblico in customer-config.sh prima dell'installazione, in modo che gli URL della dashboard e di login di Keycloak puntino all'indirizzo raggiungibile. In caso contrario, lasciarlo vuoto.

Impostazioni auto-derivate — lasciare vuote a meno che non sia necessario sovrascriverle:

Impostazione	Derivata da	Predefinito
MXENGINE_PUBLIC_ADDRESS	SERVER_STATIC_IP	http://<SERVER_STATIC_IP>:8084

Impostazioni del certificato S/MIME:

Impostazione	Descrizione	Predefinito
CERT_CA_IRISAGENT_DOMAIN	Dominio CA per l'emissione del certificato tramite tunnel WireGuard	hintest.ch

Note

La configurazione del peer WireGuard viene eseguita in fase di esecuzione tramite il dashboard (pagina /installation). I dettagli del peer sono configurati per deployment dopo che lo stack è attivo - non fanno parte di customer-config.sh.

Impostazioni locali WireGuard (in genere lasciate ai valori predefiniti):

Impostazione	Predefinito	Descrizione
WG_PRIVATE_KEY	(auto-generato)	Generato da IRISAgent al primo avvio, poi salvato in customer-config.sh
WG_LOCAL_IP	SERVER_STATIC_IP	Auto-derivato. Sovrascrivere solo se è necessario un indirizzo di tunnel diverso.
WG_INTERFACE_PORT	19818	Porta del tunnel WireGuard (sia TCP che UDP sono esposti)
WG_TRANSPORT_MODE	tcp	Protocollo di trasporto: tcp (predefinito, funziona attraverso la maggior parte dei firewall) o udp

Impostazioni opzionali (hanno valori predefiniti ragionevoli):

Impostazione	Predefinito	Descrizione
POSTGRES_PASSWORD	(auto-generato)	Password casuale di 24 caratteri auto-generata se vuota
S3_SECRET_KEY	(auto-generato)	Chiave segreta S3 per lo storage di oggetti
OUTBOUND_SEALER_MX_DOMAIN	hintest.ch	Dominio MX del sigillatore per la consegna dei sigilli in uscita
POLICY_SYNC_REPO_URL	GitHub HIN Stargate policies	URL del repository Git per la sincronizzazione delle policy OPA/Rego
LOKI_URL	(non impostato)	Endpoint Loki per l'invio centralizzato dei log (es. https://loki.example.com)

Auto-generati (non impostare manualmente):

• VAULT_TOKEN — Generato da Vault durante la prima inizializzazione, salvato in customer-config.sh
• WG_PRIVATE_KEY — Generato da IRISAgent al primo avvio, salvato in customer-config.sh

Passo 2: Deploy su un server

Tip

È possibile clonare il nostro repository con tutti i dati e le configurazioni di esempio all'interno con il comando:

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

Se non si ha git installato, è sempre possibile ottenere un archivio con tutti i file all'interno ed estrarlo:

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

Copiare manualmente i file sul server

scp -r docker-compose/* tuo-server:/percorso/verso/stargate/

SSH al server

ssh tuo-server
cd /percorso/verso/stargate

Creare la configurazione cliente dal modello e compilare le impostazioni richieste (vedere Passo 1)

cp customer-config-prod.example.sh customer-config.sh
nano customer-config.sh   # Compilare le impostazioni richieste (vedere Passo 1)

Eseguire l'installazione

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

Passo 3: Cosa fa l'installazione

Lo script di installazione (install.sh) esegue i seguenti passi:

1. Controllare le dipendenze — Rileva Docker, Docker Compose e jq. Se mancano, li installa automaticamente (supporta Ubuntu/Debian, RHEL/AlmaLinux/Rocky).
2. Caricare e validare customer-config.sh — Controlla i campi richiesti (SERVER_STATIC_IP, CUSTOMER_NAME, DEPLOYMENT_NAME). Deriva automaticamente i campi opzionali (URL MXEngine, ecc.).
3. Generare .env dalla configurazione cliente — Genera automaticamente le password se non impostate.
4. Avviare tutti i servizi tramite Docker Compose (infrastruttura + applicazioni).
5. Inizializzare Vault — Il container vault-init inizializza, scongela e crea i mount dei segreti KV-v2. Scrive opzionalmente la chiave privata WireGuard in Vault.
6. Salvare le chiavi Vault in secrets/vault-keys.json e aggiornare .env con il token root. Il token viene anche salvato in customer-config.sh per la persistenza attraverso le ricreazioni della VM.
7. Riavviare i servizi applicativi per applicare il token Vault.
8. Salvare la chiave privata WireGuard in customer-config.sh — estratta da Vault dopo che IRISAgent l'ha generata.
9. Impostare il cron job di backup giornaliero (viene eseguito alle 2:00 AM).

Una volta completata l'installazione, lo stack è in esecuzione ma non sono ancora configurati domini di posta, certificato S/MIME o peer WireGuard. Continuare con Passo 4: Onboarding tramite il dashboard.

Passo 4: Onboarding tramite il dashboard

Dopo l'installazione, completare l'onboarding tramite il dashboard all'indirizzo https://<SERVER_STATIC_IP>. Il dashboard guida attraverso tre pagine in ordine:

/installation — Configurazione del peer WireGuard

Esegue l'handshake nonce/HIN per stabilire una connessione peer WireGuard e salva la configurazione WireGuard risultante nel servizio IRISAgent.

/onboarding — Certificato S/MIME

Genera la chiave di firma S/MIME e il CSR tramite il servizio smimekeys e invia il CSR alla CA attraverso il tunnel WireGuard ora stabilito. (Questo sostituisce il precedente flusso di certificati basato su script.)

/mail — Domini di posta e configurazione del relay

Invia il nome host e l'elenco dei domini di relay al servizio mtaconf tramite la sua API REST. Il demone applica la configurazione a Stalwart senza riavviare il container.

Aggiungere o modificare domini in seguito

Riaprire la pagina /mail nel dashboard, modificare l'elenco dei domini e inviare. Il demone applica la modifica in fase di esecuzione - nessuna invocazione di script, nessuna modifica di .env, nessun riavvio del servizio necessario.

Passo 5: Registrazione del peer WireGuard

L'invio del CSR S/MIME su /onboarding fallirà se l'istanza Stargate non è ancora registrata come peer WireGuard sul lato CA HIN. Questo è il problema più comune durante la configurazione iniziale.

La pagina /installation del dashboard gestisce automaticamente la registrazione del peer WireGuard tramite l'handshake nonce/HIN. Se la registrazione automatica fallisce, è possibile effettuare la registrazione manuale fornendo i seguenti valori a HIN:

1. Chiave pubblica WireGuard — estrarre dai log irisagent:

docker compose logs irisagent | grep "public key"

1. DEPLOYMENT_NAME — dal proprio customer-config.sh
2. SERVER_STATIC_IP — l'IP pubblico del server Stargate
3. WG_INTERFACE_PORT — solo se modificato rispetto al valore predefinito 19818

Dopo la conferma della registrazione del peer:

Rieseguire la pagina /onboarding nel dashboard per rigenerare il CSR e inviarlo attraverso il tunnel ora attivo.

Per verificare il tunnel prima di richiedere il certificato:

Riavviare solo irisagent

docker compose restart irisagent

Verificare l'handshake WireGuard riuscito

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

Tip

Controllare il firewall: La porta 19818/TCP deve essere aperta in entrambe le direzioni, in entrata e in uscita sul server Stargate.

Passo 6: Raccomandazioni post-onboarding

Una volta emesso il certificato e la posta in circolazione, due elementi di configurazione sono fortemente raccomandati per qualsiasi deployment in produzione. Saltarli non rompe la crittografia, ma degrada la reputazione del mittente, causa avvisi "non possiamo verificare il mittente" in Outlook/Gmail e può portare a un blocco della posta in uscita.

Passo 6.1 SPF / DKIM / DMARC per i domini mittente

Stargate invia la posta dal proprio IP pubblico per conto degli utenti. Senza record di autenticazione DNS corretti, i destinatari vedranno avvisi "non possiamo verificare questo mittente" e potrebbero rifiutare la posta.

Per istruzioni complete sulla configurazione dei record SPF, DKIM, DMARC e PTR, vedere la Guida alla configurazione DNS.

Come minimo, per ogni dominio instradato attraverso Stargate:

• SPF: aggiungere ip4:<STARGATE_IP> al record TXT del dominio
• DMARC: pubblicare v=DMARC1; p=none su _dmarc.<YOUR_DOMAIN>
• PTR: impostare il DNS inverso per l'IP Stargate in modo che corrisponda a MAIL_HOSTNAME

Passo 6.2 Relay della posta in uscita attraverso la piattaforma di posta (raccomandato per M365 / Exchange Online)

Per impostazione predefinita, dopo che Stargate firma/crittografa una posta in uscita, la consegna direttamente al MX del destinatario. Questo funziona, ma l'IP di connessione è l'IP di Stargate - e a meno che quell'IP non abbia anni di reputazione positiva, può finire su liste nere di terze parti (es. Barracuda, Abusix), causando fallimenti di consegna intermittenti.

Il modello raccomandato è inviare la posta firmata attraverso il tenant M365 / Exchange in modo che l'ultimo salto verso Internet sia l'infrastruttura ben reputata di Microsoft. Stargate firma e verifica ancora ogni messaggio secondo le policy; solo l'ultimo salto cambia. Questo rispecchia il modello di connettore "Invia a MX" del vecchio HIN MGW.

Lato Stargate — relay per dominio

Configurare il relay per dominio tramite la pagina /mail del dashboard. Ogni dominio può essere mappato al proprio endpoint in entrata M365 / Exchange; il dashboard invia il mapping all'API REST di mtaconf e Stalwart viene riconfigurato in fase di esecuzione.

Dopo che mxengine firma la posta, Stalwart la restituirà al tenant sulla porta 25 con TLS invece di consegnarla direttamente al MX del destinatario. Vedere Exchange-integration.md per la sintassi completa per dominio.

Lato M365 / Exchange Online

Si ricrea essenzialmente lo stesso insieme di connettori + regole di trasporto del vecchio HIN MGW (il manuale O365 originale di HIN MGW è il riferimento - si applicano le stesse cinque regole). Il minimo è:

1. Connettore in entrata - accetta la posta da Stargate, identificato dal certificato TLS (il soggetto del certificato deve corrispondere a un dominio accettato nel tenant). Un certificato auto-firmato su Stargate sarà respinto da questo connettore - utilizzare un certificato valido emesso da CA (Let's Encrypt va bene).
2. Connettore in uscita "Invia a MX" - consegna al MX del destinatario, attivato solo dalla regola di trasporto.
3. Regola di trasporto set_header - etichetta la posta in uscita con un header come outgoing: outgoing_<dominio> prima che lasci O365 la prima volta, in modo che il viaggio di ritorno possa riconoscerlo.
4. Regola di trasporto outgoing_to_mx - corrisponde all'header outgoing_<dominio> sulla posta che torna da Stargate e la instrada tramite il connettore "Invia a MX".
5. Regola di trasporto mgw_bypass_antispam - bypassa il filtraggio antispam sulla posta che torna da Stargate.

mxengine non rimuove header arbitrari, quindi il tag outgoing_<dominio> impostato da set_header sopravvive al viaggio di andata e ritorno e attiva correttamente outgoing_to_mx.

Perché questo modello è importante

Con la configurazione di relay di ritorno, il mittente pubblico verso Internet è Microsoft. Combinato con SPF/DKIM/DMARC corretti (sezione 6.1), i destinatari vedono un IP Microsoft con spf=pass e dkim=pass allineati al dominio - che è il profilo di reputazione più pulito che si possa dare loro.

Vedere Exchange-integration.md per istruzioni dettagliate passo-passo incluse schermate.

Avvii successivi (dopo il riavvio)

L'installatore abilita un'unità systemd stargate, quindi lo stack si avvia automaticamente all'avvio. Per avviarlo manualmente:

sudo systemctl start stargate

Questo esegue start.sh, che:

1. Avvia i servizi di infrastruttura
2. Scongela Vault utilizzando le chiavi memorizzate
3. Avvia i servizi applicativi

(./scripts/start.sh funziona ancora direttamente se si preferisce.)

Arrestare i servizi

sudo systemctl stop stargate

(o direttamente ./scripts/stop.sh)

Questo arresta i container ma preserva tutti i dati.

Persistenza dei dati

Tutti i dati sono memorizzati in volumi Docker e persistono attraverso i riavvii.

Servizio	Volume	Dati
PostgreSQL	postgres_data	Tutti i database (smimekeys, policy, irisagent, mxengine)
Vault	vault_data	Chiavi di crittografia, segreti, chiavi S/MIME
SeaweedFS	seaweedfs_data	Storage di oggetti (messaggi, allegati)
Stalwart	stalwart_data	Stato del server di posta

Operazioni sicure (dati preservati)

Arrestare e avviare:

sudo systemctl stop stargate
sudo systemctl start stargate

O utilizzando direttamente gli script:

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

Non utilizzare i comandi docker compose direttamente

Utilizzare sempre systemctl o gli script forniti (start.sh / stop.sh) per gestire il deployment. L'esecuzione diretta di docker compose up, docker compose down o docker compose restart non scongelerà Vault, lasciando i servizi dipendenti impossibilitati ad avviarsi. Lo script start.sh gestisce automaticamente la procedura di scongelamento di Vault.

Comportamento di scongelamento di Vault

Vault si congela quando il suo container viene riavviato. Questa è una funzionalità di sicurezza.

Lo script start.sh (e il servizio systemd) scongelano automaticamente Vault utilizzando le chiavi memorizzate in secrets/vault-keys.json. Questo è il motivo per cui è necessario utilizzare sempre gli script forniti o il servizio systemd per gestire lo stack.

Operazioni distruttive (dati cancellati)

Warning

Questi comandi CANCELLANO TUTTI I DATI - usare con cautela!

È possibile ripristinare i dati solo se si eseguono operazioni di backup prima e si salva il backup in un luogo sicuro.

Danger

Eliminare tutto (volumi, segreti, config)

./scripts/purge.sh

Riferimento script

Script	Scopo
install.sh	Prima installazione (Docker, Vault). La configurazione di dominio/certificato/peer avviene successivamente nel dashboard.
update.sh	Aggiornare le immagini dei servizi (preserva il token Vault, ricrea i container)
start.sh	Avviare i servizi e scongelare Vault
stop.sh	Arrestare i container (dati preservati)
backup.sh	Backup completo (database, chiavi Vault, configurazione, certificati)
restore.sh	Ripristinare da archivio di backup (funziona su macchina nuova)
purge.sh	Eliminare TUTTI i dati (richiede conferma)
health-check.sh	Health check completo di tutti i servizi (exit 0 = healthy, 1 = fallimenti)
init-vault.sh	Inizializzazione Vault (utilizzato dal container vault-init, non chiamato direttamente)
init-keycloak.sh	Impostazione password amministratore Keycloak (utilizzato dal container keycloak-init, non chiamato direttamente)
gather-app-versions.sh	Raccoglie le versioni delle app dagli endpoint /liveness per node-exporter (viene eseguito nel container version-collector)

File di configurazione

File	Scopo
customer-config-prod.example.sh	Modello per le impostazioni cliente (copiare in customer-config.sh)
customer-config.sh	Impostazioni specifiche del cliente (create dal modello, compilare prima dell'installazione)
.env	File di ambiente generato (creato da install.sh)
secrets/vault-keys.json	Chiavi di scongelamento Vault e token root (effettuare backup sicuro!)
secrets/signing-key.csr	CSR generato per il certificato S/MIME

Supporto

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance Stargate, contattare il supporto HIN.

Includere informazioni rilevanti come il nome del cliente, la versione dell'appliance e schermate/log dove applicabile, per aiutarci a elaborare la richiesta in modo efficiente.

Configurazione avanzata di Stargate Docker

Backup

Backup automatici

• I backup giornalieri vengono eseguiti alle 2:00 AM tramite cron (impostati durante l'installazione)
• I backup vengono archiviati in ./backups/ come file .tar.gz con timestamp
• I vecchi backup (>7 giorni) vengono automaticamente eliminati

Cosa è incluso nei backup

• Dump PostgreSQL completo (tutti i database con utenti e permessi)
• Dump di database individuali (per ripristino parziale se necessario)
• Chiavi Vault (vault-keys.json per lo scongelamento)
• Configurazione cliente (customer-config.sh con chiave WireGuard)
• CSR e certificati S/MIME (tutti i file .crt, .pem, .cer)
• Manifesto del backup (manifest.json con metadati)

Backup manuale

./scripts/backup.sh

Crea un archivio compresso in ./backups/YYYYMMDD_HHMMSS.tar.gz.

Ripristino dal backup

Per ripristinare su una nuova macchina o dopo una pulizia. Copiare l'archivio di backup sulla nuova macchina ed eseguire:

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

Lo script di ripristino:

1. Arresta tutti i servizi in esecuzione
2. Estrae e valida il backup
3. Installa Docker se necessario
4. Ripristina la configurazione cliente
5. Avvia i servizi di infrastruttura (PostgreSQL, Vault, MinIO)
6. Ripristina il database
7. Scongela Vault con le chiavi di backup
8. Avvia i servizi applicativi

Ripristino parziale (database singolo)

Se è necessario ripristinare solo un database:

Estrarre il backup

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

Ripristinare un database specifico

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

Aggiornamento di Stargate

Aggiornare script di deployment e configurazione

Il repository di deployment di Stargate riceve aggiornamenti per script (install.sh, start.sh, health-check.sh, restore.sh, ecc.), modelli di configurazione e documentazione. Per applicare questi aggiornamenti:

1. Creare un backup prima dell'aggiornamento

./scripts/backup.sh

2. Recuperare e applicare le ultime modifiche

Il repository è l'unica fonte di verità per i file tracciati. Aggiornare quindi ripristinando all'ultima revisione. Questo sostituisce i file tracciati (script, docker-compose.yml, modelli di configurazione) con le versioni del repository:

git fetch origin
git reset --hard origin/main

3. Riavviare i servizi per applicare eventuali modifiche a script o configurazione

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

Note

customer-config.sh, .env e la directory secrets/ sono in .gitignore, quindi questa operazione non li tocca - la configurazione e le credenziali vengono preservate. Effettuare sempre le personalizzazioni in customer-config.sh, mai modificando file tracciati come docker-compose.yml: un hard reset - e gli aggiornamenti automatici attivati dalla dashboard - annullerà qualsiasi modifica ai file tracciati. Ciò è intenzionale; mantenere ogni distribuzione identica al repository è ciò che consente agli aggiornamenti di essere applicati in modo affidabile e senza risoluzione manuale dei conflitti.

Se l'aggiornamento include modifiche al modello di configurazione, confrontarlo con la configurazione esistente per vedere se sono state aggiunte nuove variabili:

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

Aggiornare le immagini dei servizi

Le versioni delle applicazioni sono gestite esclusivamente tramite la dashboard. Ogni release è un manifest con versione che fissa insieme una combinazione nota e testata di tutte le versioni dei servizi; la pagina di aggiornamento della dashboard elenca le release disponibili e applicandone una vengono scaricate le immagini corrispondenti e ricreati per voi i servizi interessati.

Per aggiornare:

1. Aprire la dashboard e andare alla pagina di aggiornamento.
2. Selezionare la release desiderata.
3. Confermare - la dashboard applica il manifest della release e ricrea i servizi modificati.

Non modificare le versioni manualmente

Non modificare i singoli valori *_VERSION in customer-config.sh o .env per aggiornare le applicazioni. Le versioni vengono rilasciate e testate insieme come un insieme - sceglierne una manualmente produce una combinazione non testata e la modifica verrebbe comunque annullata dal successivo aggiornamento della dashboard. Aggiornare sempre dalla dashboard.

Pulire le vecchie immagini

Dopo gli aggiornamenti, rimuovere le immagini inutilizzate per liberare spazio su disco:

docker image prune -f

Rollback

Per eseguire un rollback, selezionare una release precedente nella pagina di aggiornamento della dashboard e applicarla - lo stesso meccanismo viene eseguito al contrario, fissando l'insieme testato precedente. Non eseguire il rollback modificando le versioni manualmente.

Configurazione

Il file .env viene generato da install.sh da customer-config.sh. Le impostazioni di dominio, certificato e WireGuard sono gestite in fase di esecuzione dal dashboard (/installation, /onboarding, /mail) — non sono conservate in .env. Per personalizzare le impostazioni di installazione, modificare customer-config.sh e rieseguire install.sh.

Sezioni chiave nel .env generato:

## PostgreSQL (auto-generato se vuoto in customer-config.sh)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<auto-generato>

## Vault (auto-populato dopo l'inizializzazione)
VAULT_TOKEN=<auto-generato>

## Storage di oggetti S3 (SeaweedFS)
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=<auto-generato>

## Versioni delle applicazioni
SMIMEKEYS_VERSION=v0.0.5
POLICY_VERSION=v0.0.5
IRISAGENT_VERSION=v0.0.6-branch
MXENGINE_VERSION=v0.0.35
MTACONF_VERSION=dev

## Percorso posta in uscita
MXENGINE_PUBLIC_ADDRESS=http://203.0.113.50:8084
OUTBOUND_SEALER_MX_DOMAIN=hintest.ch

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

Warning

Non modificare .env direttamente. Le modifiche verranno sovrascritte alla successiva esecuzione di install.sh. Per la configurazione in fase di esecuzione (domini, nome host, peer, S/MIME), utilizzare il dashboard.

URL dei servizi

Servizio	URL/Porta
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
Gateway APISIX	http://localhost:9080
Keycloak	https://localhost:8180

Health Check

Tutti i servizi espongono un endpoint /liveness:

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

Monitoraggio

Metriche Prometheus

Tutti i servizi applicativi espongono metriche Prometheus sulla porta 2112 (internamente), mappate a diverse porte host:

Servizio	Porta metriche	URL metriche
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

Esempio di configurazione scrape Prometheus

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

Controllo rapido delle metriche

## Controllare tutti gli endpoint delle metriche
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

Raccolta log (Alloy → Loki)

Alloy raccoglie i log dai container delle applicazioni e li invia a Loki.

Container monitorati:

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

Configurazione in .env:

## URL di push Loki
LOKI_URL=https://loki.example.com

## Etichetta nome host per i log (auto-impostata su DEPLOYMENT_NAME)
ALLOY_HOSTNAME=stargate-acme

Etichette aggiunte ai log:

• environment=<DEPLOYMENT_NAME> - Identifica il deployment
• host=<ALLOY_HOSTNAME> - Identifica l'host (come il nome del deployment)
• container=<nome-container> - Nome del container
• service=<nome-servizio> - Nome del servizio (es., smimekeys-client, policy)
• level=<livello-log> - Estratto dai log JSON se disponibile

Interrogare i log in Grafana:

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

Verificare che Alloy funzioni:

Controllare lo stato di Alloy e l'attività recenteSonda di salute (dall'interno del network Docker)

docker logs stargate-alloy

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

Nota: L'IP pubblico della VM deve essere nella whitelist della configurazione di ingress di Loki.

Stalwart MTA + mtaconf

Stargate utilizza Stalwart come mail transfer agent e mtaconf come demone di configurazione. Il dashboard invia la configurazione di domini e relay all'API REST di mtaconf, che la invia a Stalwart tramite la CLI di gestione.

Architettura del flusso di posta

Server di posta esterno
         │
         ▼ (porta 25)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Porta 25 (listener smtp)                           │
│    │                                                │
│    ▼                                                │
│  content_filter → smtp:[mxengine]:1587              │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (porta 1587)
┌─────────────────────────────────────────────────────┐
│ MXEngine (stargate-mxengine)                        │
│                                                     │
│  Porta 1587 (ingresso SMTP)                         │
│    │                                                │
│    ▼                                                │
│  Firmare/crittografare/elaborare la posta           │
│    │                                                │
│    ▼                                                │
│  Consegnare a stalwart per il relay                 │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (porta 10026)
┌─────────────────────────────────────────────────────┐
│ stalwart (stargate-stalwart)                        │
│                                                     │
│  Porta 10026 (listener di reiniezione)              │
│    │                                                │
│    ▼                                                │
│  transport → relay al MX di destinazione            │
│    │                                                │
└────┼────────────────────────────────────────────────┘
     │
     ▼ (porta 25)
Server di posta di destinazione (tramite ricerca MX)

Scansione antivirus: La posta in entrata viene scansionata da ClamAV (stargate-clamav), collegato a Stalwart come milter nella fase SMTP DATA sia sul listener pubblico (:25) che su quello di reiniezione (:10026). La posta infetta viene respinta a livello SMTP; se ClamAV non è raggiungibile, il messaggio viene rinviato piuttosto che consegnato non scansionato (fail-closed). Il database delle firme di ClamAV risiede nel volume clamav_data e viene mantenuto aggiornato da freshclam in background.

Flusso di callback di sigillatura (in entrata): Quando un sigillatore remoto deve consegnare un messaggio sigillato, chiama MXENGINE_PUBLIC_ADDRESS (predefinito: http://<SERVER_STATIC_IP>:8084). Il protocollo http:// è corretto - TLS non è richiesto perché il payload del sigillo è già crittografato.

Configurazione del relay di posta

Tutta la configurazione di posta che varia per deployment (domini di posta, nome host, host di relay, mappe di relay per dominio, reti consentite) viene impostata tramite la pagina /mail del dashboard in fase di esecuzione. Il dashboard invia la configurazione tramite POST all'API REST di mtaconf, che la applica a Stalwart senza riavviare il container.

Non c'è configurazione per dominio in customer-config.sh o .env - gli operatori aggiungono o modificano i domini tramite l'interfaccia utente.

Routing della posta (Migrazione dal vecchio MGW)

Differenza chiave rispetto al vecchio HIN-MGW

Nel vecchio MGW, era necessario configurare manualmente un server di destinazione per dominio. In Stargate, il routing della posta è deciso da record MX DNS per impostazione predefinita - Stalwart risolve il MX di ogni dominio al momento della consegna. La pagina /mail del dashboard consente di sovrascrivere questo comportamento per dominio (es. per relayare attraverso il tenant M365 / Exchange) senza toccare il DNS.

Predefinito - automatico tramite DNS MX:

Per ciascuno dei propri domini, assicurarsi che ci sia un record MX nel DNS che punti al corrispondente server Exchange (o altro server di posta):

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

Funziona per qualsiasi numero di domini - ogni dominio può puntare a un server di posta diverso e Stalwart instraderà di conseguenza.

Se Stargate è l'unico record MX per un dominio, Stalwart lo filtrerà e non avrà alcuna destinazione di consegna. Aggiungere un secondo record MX che punti al server di posta con una priorità più alta (= numero inferiore) in modo che Stalwart lo utilizzi come destinazione di consegna:

example.com    MX 10  exchange.example.com      ← destinazione di consegna (server di posta)
example.com    MX 20  stargate.example.com      ← gateway in entrata (Stargate)

Alternativa - relay esplicito per dominio (basato sul mittente):

Per il relay di ritorno attraverso M365 / Exchange Online, configurare le destinazioni di relay per dominio tramite la pagina /mail del dashboard. La posta dai mittenti non nella mappa ricade sulla ricerca MX.

Porte

Porta	Scopo
25	Listener SMTP principale (connessioni esterne)
10026	Porta di reiniezione (mxengine → stalwart, solo interno)
1587	Ingresso SMTP MXEngine (stalwart → mxengine, solo interno)
8080	API di gestione Stalwart + API REST mtaconf (solo interno)

Si utilizza Exchange?

Vedere Exchange-integration per la configurazione completa dei connettori e delle regole di trasporto Exchange Online / On-Premises.

Verifica

Controllare lo stato di Stalwart

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

Controllare i log

docker logs stargate-stalwart

Testare la connessione alla porta 25

telnet localhost 25

Testare la porta interna 10026 (dal container mxengine)

docker exec stargate-mxengine nc -zv stalwart 10026

Aggiornamento dell'immagine mtaconf

Come ogni servizio, la versione dell'immagine mtaconf fa parte di una release e si aggiorna tramite la dashboard - non modificando il suo tag manualmente. Selezionare la release desiderata nella pagina di aggiornamento della dashboard per applicarla.

Risoluzione dei problemi di Stargate

Posta non elaborata da mxengine:

• Verificare che content_filter sia configurato: controllare che i log mtaconf mostrino il push riuscito
• Verificare che mxengine sia raggiungibile: docker exec stargate-stalwart nc -zv mxengine 1587

Posta bloccata dopo l'elaborazione di mxengine:

• Verificare la configurazione in uscita di mxengine: OUTBOUND_SMTP_HOST=stalwart, OUTBOUND_SMTP_PORT=10026
• Verificare che il listener sulla porta 10026 sia attivo in Stalwart
• Verificare che le reti di relay consentite includano la rete Docker (172.x.x.x/16)

Errori di greylisting (450 4.7.1):

• È normale! Il server di destinazione sta rifiutando temporaneamente la posta
• Stalwart riprova automaticamente dopo un ritardo configurabile
• Controllare la coda tramite l'API di gestione

Microsoft blocca l'IP (S3140):

• L'IP del server ha una cattiva reputazione presso Microsoft
• Richiedere la rimozione dalla lista su: https://sender.office.com
• Potrebbero essere necessarie 24-48 ore per avere effetto

Fallimenti di ricerca DNS:

• Utilizzare la pagina /mail del dashboard per impostare un host di relay esplicito o una mappa di relay per dominio (salta la scoperta basata su MX)

Connessione rifiutata sulla porta 25:

• Assicurarsi che la porta 25 non sia bloccata dal firewall
• Verificare se un altro servizio sta utilizzando la porta 25: ss -tlnp | grep :25

WireGuard (Comunicazione Agente-Agente)

IRISAgent utilizza WireGuard per stabilire tunnel crittografati sicuri tra istanze Stargate per la consegna di messaggi sigillati.

Come funziona

Ogni istanza Stargate utilizza l'IP pubblico statico reale del proprio server come indirizzo del tunnel WireGuard. Questo garantisce l'unicità tra tutti i deployment senza coordinazione manuale.

block
columns 5
  block:Stargate["Il tuo Stargate (203.0.113.50)"]:2
    columns 1
    A
    space
    A --> B
    A["IRISAgent (203.0.113.50:19818)"]
    B["Consegna messaggio sigillato tramite tunnel WG"]
  end

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

  block:mxengine["HIN Test (5.102.144.182)"]:2
    columns 1
    C
    space
    C --> D
    C["IRISAgent (5.102.144.182:19818)"]
    D["Ricevi messaggio sigillato"]
  end

Configurazione WireGuard

Impostazioni WireGuard in customer-config.sh:

## ==============================================================================
## IP del server — utilizzato come indirizzo del tunnel WireGuard e URL di callback MXEngine
## ==============================================================================
SERVER_STATIC_IP="203.0.113.50"       # L'IP pubblico statico reale del server

## ==============================================================================
## Impostazioni locali WireGuard (in genere lasciate ai valori predefiniti)
## ==============================================================================
WG_PRIVATE_KEY=""                     # Auto-generato da IRISAgent, poi salvato nella configurazione
WG_INTERFACE_PORT="19818"             # Porta WireGuard predefinita
WG_TRANSPORT_MODE="tcp"               # "tcp" (predefinito) o "udp"

Info

WG_LOCAL_IP è auto-derivato da SERVER_STATIC_IP. Non è necessario impostarlo separatamente.

Configurazione della connessione peer

I dettagli del peer WireGuard (chiave pubblica, endpoint, IP consentiti, ecc.) sono configurati in fase di esecuzione tramite la pagina /installation del dashboard. Non c'è più un blocco WG_PEER_* in customer-config.sh — il peer viene configurato dopo che lo stack è attivo.

Per la configurazione iniziale con l'ambiente HIN Test:

1. Avviare lo stack con ./scripts/install.sh.
2. Aprire il dashboard, seguire /installation per avviare l'handshake nonce / HIN.
3. Aprire i log IRISAgent (docker compose logs irisagent) e copiare la riga wireguard public key:. Inviarla insieme a DEPLOYMENT_NAME e SERVER_STATIC_IP a Vereign (kalin.canov@vereign.com) in modo che possano registrare il peer sul lato CA.
4. Dopo la conferma della registrazione da parte di Vereign, completare /onboarding nel dashboard per emettere il certificato S/MIME.

Per qualsiasi peer aggiuntivo (peer-to-peer tra due Stargate), scambiare chiavi pubbliche + endpoint con l'altra parte e aggiungere la connessione tramite l'API IRISAgent:

curl --location 'localhost:8083/v1/connections' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "allowedIps": "<IP del nuovo peer>/32",
  "description": "<breve descrizione>",
  "endpoint": "<IP del nuovo peer>:19818",
  "externalId": [
    "<dominio del nuovo peer>"
  ],
  "name": "<Nome del nuovo peer>",
  "presharedKey": "",
  "publicKey": "<chiave pubblica del nuovo peer>",
  "status": "completed",
  "transport": "tcp",
  "wireguardIp": "<IP del nuovo peer>",
  "wireguardPort": 10080
}'

Verifica WireGuard

Controllare l'interfaccia WireGuard di IRISAgent

docker exec stargate-irisagent wg show

Controllare la connessione nel database

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

Controllare gli ID esterni della connessione (utilizzati per il routing)

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

Testare la connettività WireGuard (controllare lo stato del tunnel dall'host)

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

Controllare i log IRISAgent per l'attività del tunnel

docker logs stargate-irisagent | grep -i wireguard

Risoluzione dei problemi WireGuard

Nessuna interfaccia WireGuard:

• Controllare i log IRISAgent: docker logs stargate-irisagent
• Verificare che WG_LOCAL_IP sia impostato in .env (auto-derivato da SERVER_STATIC_IP — dovrebbe essere l'IP pubblico statico di questo server)

Peer non raggiungibile:

• Verificare che l'endpoint remoto sia accessibile: nc -zv <host_endpoint> <porta_endpoint>
• Controllare che il firewall consenta la porta TCP+UDP 19818
• Verificare che le chiavi pubbliche corrispondano su entrambe le estremità
• Se TCP ha problemi, provare a impostare WG_TRANSPORT_MODE="udp" in customer-config.sh

Connessione non presente nel database:

• Rieseguire la pagina /installation del dashboard per ristabilire la connessione peer
• Controllare i log irisagent: docker logs stargate-irisagent

Sincronizzazione delle policy

Il servizio policy-sync sincronizza automaticamente le policy OPA/Rego da un repository Git al database PostgreSQL.

Come funziona Policy Sync

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

      policies/
        alpha/
        outbound/
        ..."]
    A-->B
    B["policy-sync:

      - Clone/Pull repo
      - Parse .rego files
      - Upsert to database
      - Runs every 1h"]
    B-->C
    C["PostgreSQL

      - policy database
      - policies table"]

Configurazione di Policy Sync

Impostazioni in customer-config.sh:

## Repository Git contenente le policy (preconfigurato con le policy HIN Stargate)
POLICY_SYNC_REPO_URL="https://github.com/Health-Info-Net-AG/Stargate-policies.git"

## Opzionale: Autenticazione per repo privati
POLICY_SYNC_REPO_USER=""
POLICY_SYNC_REPO_PASS=""

## Opzionale: Branch specifico (predefinito: main)
POLICY_SYNC_REPO_BRANCH=""

## Opzionale: Sottocartella nel repo contenente le policy
POLICY_SYNC_REPO_FOLDER=""

## Intervallo di sincronizzazione (predefinito: 1h)
POLICY_SYNC_INTERVAL="1h"

Verifica di Policy Sync

Controllare lo stato di policy-syncVisualizzare le policy sincronizzateVisualizzare il contenuto di una policy specifica

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

Attivazione manuale

Per forzare una sincronizzazione immediata:

docker restart stargate-policy-sync

Vault

Montaggi Vault

La porta API/UI di Vault (8200) non è pubblicata sull'host; accedere a Vault tramite la CLI all'interno del container (vedere Operazioni manuali Vault di seguito).

I seguenti motori di segreti KV-v2 vengono creati:

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

Operazioni manuali Vault

Controllare lo statoElencare i montaggiScrivere un segreto

docker exec stargate-vault vault status

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

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

Database

Database PostgreSQL creati:

• smimekeys_client
• policy
• irisagent
• mxengine

Connettersi a PostgreSQL

docker exec -it stargate-postgres psql -U postgres

O connettersi esternamente

psql -h localhost -U postgres -d smimekeys_client

Policy (Rego)

MXEngine utilizza policy OPA/Rego memorizzate in PostgreSQL per determinare la strategia di consegna della posta.

Raccomandato: Utilizzare policy-sync per sincronizzare automaticamente le policy da un repository Git. Vedere la sezione Policy Sync.

Visualizzare la policy corrente

Elencare tutte le policyVisualizzare il contenuto della policy

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

Posizione delle policy

• Configurazione MXEngine: POLICY_OUTBOUND: "outbound/delivery"
• Database: database policy, tabella policies
• Gestito da: servizio policy-sync (sincronizza dal repository Git)

Log

Tutti i serviziServizio specifico

docker compose logs -f

docker compose logs -f <servizio>

Es.:

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

Risoluzione dei problemi

Emissione certificato fallita / Tunnel WireGuard non stabilito

Questo è il problema più comune dopo l'installazione iniziale. Il certificato S/MIME non può essere emesso perché il tunnel WireGuard verso la CA HIN non è stabilito.

Sintomi:

• La pagina /onboarding del dashboard segnala un fallimento di invio del CSR
• I log smimekeys-client mostrano: issue certificate error: certcatunnel: error sending request: irisagent: ... context deadline exceeded

Cause profonde (controllare in ordine):

1. Peer non registrato sulla CA HIN - La chiave pubblica WireGuard deve essere registrata sul lato HIN. Fornire a HIN:

# Ottenere la chiave pubblica WireGuard
docker compose logs irisagent | grep "public key"

Insieme a DEPLOYMENT_NAME, SERVER_STATIC_IP e WG_INTERFACE_PORT (se modificato da 19818).

1. Firewall che blocca la porta 19818 - Assicurarsi che 19818/TCP sia aperto sia in entrata che in uscita sul server Stargate.

2. Nome host errato - Se il nome host di Stalwart è ancora impostato sul valore predefinito del modello (mail.example.com), aggiornarlo tramite la pagina /mail del dashboard.

Dopo la risoluzione del problema:

Riaprire la pagina /onboarding del dashboard per rigenerare il CSR e inviarlo nuovamente attraverso il tunnel ora attivo.

Vedere Passo 5: Registrazione del peer WireGuard per il processo completo.

Vault è congelato dopo il riavvio

Eseguire lo script di avvio che gestisce lo scongelamento:

./scripts/start.sh

Impossibile scaricare le immagini

Accedere al registry:

docker login hub.docker.com

Il servizio non si avvia

Controllare i log:

docker compose logs <nome-servizio>

Reimpostare tutto

Warning

Questi comandi CANCELLANO TUTTI I DATI - usare con cautela!

È possibile ripristinare i dati solo se si eseguono operazioni di backup prima e si salva il backup in un luogo sicuro.

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

Struttura dei file

stargate/
├── backups/                      # Backup completi (gitignorato)
│   └── *.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          # Configurazione invio log Alloy
│   └── vault
│       └── vault.hcl             # Configurazione Vault
├── customer-config-prod.example.sh     # Modello di configurazione (copiare in customer-config.sh)
├── customer-config.sh            # Impostazioni specifiche del cliente (copiate dal modello)
├── docker-compose.yml            # File compose principale
├── .env                          # Variabili d'ambiente (generate da install.sh)
├── init
│   └── postgres
│       └── 01-create-databases.sql
├── scripts
│   ├── backup.sh                 # Backup completo (DB, Vault, config, certificati)
│   ├── gather-app-versions.sh    # Raccoglie le versioni delle app per le metriche node-exporter
│   ├── health-check.sh           # Health check completo di tutti i servizi
│   ├── init-keycloak.sh
│   ├── init-vault.sh             # Inizializzazione Vault (utilizzato dal container vault-init)
│   ├── install.sh                # Prima installazione (Docker, Vault). La configurazione di dominio/certificato/peer avviene successivamente nel dashboard.
│   ├── purge.sh                  # Elimina tutti i dati (distruttivo!)
│   ├── restore.sh                # Ripristina da archivio di backup
│   ├── send-logs-to-support.sh   # Incolla i log online e ottieni un link da fornire al supporto
│   ├── start.sh                  # Avvia i servizi + scongela Vault
│   ├── stop.sh                   # Arresta i container (preserva i dati)
│   └── update.sh
└── secrets/                      # Creato al primo avvio (gitignorato)
    ├── vault-keys.json           # Chiavi di scongelamento Vault (FARE BACKUP!)
    └── signing-key.csr           # Richiesta di firma certificato S/MIME

Controlli rapidi di salute e log

Eseguire il health check completo

Health check rapidoOutput dettagliato

./scripts/health-check.sh

./scripts/health-check.sh -v

Con output dettagliato (mostra dettagli WireGuard, risposte liveness).

Questo controlla:

• Tutti gli stati dei container (in esecuzione, healthy)
• Endpoint Liveness (smimekeys-client, policy, irisagent, mxengine)
• Stato di scongelamento di Vault
• Connettività PostgreSQL e tutti i 4 database
• Salute di MinIO
• Stato del tunnel WireGuard e handshake dei peer
• Stalwart MTA (in esecuzione, porta 25, porta 10026)
• Endpoint delle metriche Prometheus
• Utilizzo del disco e della memoria

Per l'ispezione manuale dei log:

Controllare i log (ultime 10 righe)

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

Seguire i log in tempo reale

docker logs -f stargate-mxengine

Controllare tutti gli stati dei container

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

Seguire tutti i log dei container in tempo reale

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

Fornire log al supporto

È possibile fornire log al nostro supporto tramite pastebin.hin-infra.ch e il comando CLI:

Caricare i log di tutti i container:

TuttiPer l'ultima ora (1h)Ultime 500 righe di log

Utilizzare il nostro script:

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

O eseguire manualmente:

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

Questa operazione può raggiungere i nostri limiti di upload - 20 Mb.

Utilizzare il nostro script:

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

O eseguire manualmente:

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

Questo è il valore predefinito

--tail 500 è il valore predefinito del nostro script, ma è comunque possibile fornirlo.

Utilizzare il nostro script:

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

O eseguire manualmente:

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

Caricare i log di container specifici:

TuttiPer l'ultima ora (1h)Ultime 500 righe di log

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

Tip

Questa operazione può raggiungere i nostri limiti di upload - 20 Mb. Se ciò accade, provare a ridurre la quantità di log impostando un limite di tempo o un numero di righe.

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

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

Dopo di che, si riceverà un link unico nel formato https://pastebin.hin-infra.ch/<20 simboli> da fornire al supporto / ticket.

Warning

La scadenza è impostata a 30 giorni. Se alcune parti dei log o i log stessi devono essere conservati per un periodo più lungo, assicurarsi di conservarne una copia.

Deployment Helm

Info

Presto disponibile

Questo file contiene le istruzioni per il deployment Helm dell'istanza HIN MGW.

Deployment VM

Deployment Stargate su Azure tramite immagine

Distribuisci Stargate su Azure

Requisiti della porta 25 (SMTP) di Azure

Warning

Prima di iniziare l'installazione su Microsoft Azure, esamina i seguenti requisiti relativi alla connettività SMTP in uscita sulla porta 25. Saltare questo passaggio potrebbe causare il fallimento della consegna delle email dopo l'installazione.

La disponibilità della porta 25 dipende dal tipo di abbonamento Azure:

• Enterprise Agreement (EA) o MCA-E - Lo SMTP in uscita sulla porta 25 non è bloccato. Nota che i domini esterni potrebbero comunque rifiutare le email - questo è al di fuori del controllo di Azure.
• Enterprise Dev/Test - Bloccato per impostazione predefinita, ma può essere rimosso. Per richiedere la rimozione, vai a Diagnostica e risoluzione > Impossibile inviare email (SMTP-Port 25) nella risorsa Rete virtuale di Azure nel portale Azure.
• Tutti gli altri tipi di abbonamento - Bloccato e non può essere sbloccato.

Riferimento: Risolvere i problemi di connettività SMTP in uscita in Azure

Ottenere il file immagine

• Scarica l'ultimo file immagine VHD. Fare riferimento al Catalogo VM

Caricare il file immagine VHD di Azure

• Naviga su https://portal.azure.com/#home
• Fai clic su Account di archiviazione.
• Seleziona l'account di archiviazione da utilizzare o creane uno nuovo.
• Fai clic su Servizio Bloc e poi Contenitori.
• Seleziona il contenitore in cui caricare il file o creane uno nuovo se non hai un contenitore.
• Fai clic su Carica e scegli il file immagine VHD.
• Assicurati che il tipo di blob sia Page Blob.

Creare l'immagine

• Naviga su https://portal.azure.com/#home
• Fai clic su Immagini.
• Fai clic su Crea.
• Scegli il gruppo di risorse da utilizzare o creane uno nuovo.
• Digita un nome per l'immagine.
• Scegli il tipo di sistema operativo Linux e Generazione VM Gen 2
• In Storage blob, fai clic su sfoglia e seleziona l'immagine VHD appena caricata.
• Fai clic su Rivedi e crea.
• Fai clic su Crea.

Creare una VM

• Naviga su https://portal.azure.com/#home
• Fai clic su Macchine virtuali.
• Fai clic su Crea e scegli Macchina virtuale dal menu a tendina.
• Scegli il gruppo di risorse.
• Digita un nome per la VM.
• In Immagine, fai clic su "Vedi tutte le immagini", fai clic su "Le mie immagini" e scegli la nuova immagine creata.
• Scegli la dimensione della VM.
• Scegli il tipo di autenticazione.
• Fai clic su Avanti: Dischi
• Seleziona una dimensione del disco del sistema operativo di almeno 20 GiB. Fare riferimento ai Requisiti del server.
• Fai clic su Rivedi + crea
• Fai clic su Crea

Trovare l'indirizzo IP pubblico della nuova VM e aggiungere le regole del firewall in entrata

• Naviga su https://portal.azure.com/#home
• Fai clic su Macchine virtuali.
• Fai clic sulla nuova VM.
• Puoi vedere l'indirizzo IP pubblico sotto "IP pubblico della scheda di rete primaria"
• Scorri verso il basso fino a Rete e fai clic su di essa
• Fai clic su + Crea regola di porta, Regola di porta in entrata, Intervalli di porte di destinazione 25, Protocollo TCP, chiamala SMTP. Ripeti per l'altra porta in entrata richiesta — 19818 (WireGuard). Vedi Requisiti del server → Accesso di rete in entrata per l'elenco completo.

Collega prima il disco dati

Prima del primo avvio, collega un secondo disco vuoto di almeno 30 GB. Al primo avvio l'appliance lo formatta come disco dati (VEREIGN-DATA, montato su /var/data) e vi conserva tutta la configurazione e i dati; senza di esso l'avvio fallisce ed esegue il rollback. Vedi Guida all'installazione → Passo 4.

Accedi e inizializza l'istanza Stargate

• Accedi alla VM con l'utente scelto durante la creazione della VM e l'indirizzo IP pubblico della nuova VM:
• Per ottenere la password hinadmin, invia un'email a support@hin.ch con oggetto: "Password required for VM installation."

Clicca qui per inviare un'email

ssh hinadmin@11.22.33.44 

• Una volta effettuato l'accesso alla VM:

sudo su -
cd ~/stargate-deployment/docker-compose/

• Utilizza vi/nano per modificare customer-config.sh
• I dettagli di configurazione si trovano nel README - Passo 1: Configurare le impostazioni cliente
• Esegui lo script di installazione:

./scripts/install.sh

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance Stargate, contatta il supporto HIN.

Includi informazioni rilevanti come il nome del cliente, la versione dell'appliance e screenshot/log dove applicabile, per aiutarci a elaborare la tua richiesta in modo efficiente.

Deployment Stargate su VMware ESXi tramite immagine

Distribuisci Stargate su VMware

Ottenere il file immagine

• Scarica l'ultimo file immagine OVA (o OVF e VMDK se preferisci). Fare riferimento al Catalogo VM

Navigare all'interfaccia web di ESXi

• Fai clic su Macchine virtuali
• Fai clic su Crea/Registra VM
• Scegli "Distribuisci una macchina virtuale da un file OVF o OVA"
• Fai clic su Avanti
• Digita un nome per la VM
• Fai clic su Avanti
• Fai clic per selezionare i file e scegli il file immagine OVA (o OVF e VMDK se preferisci)
• Fai clic su Avanti
• Scegli uno storage da utilizzare
• Fai clic su Avanti
• Scegli Rete e Disco per il provisioning
• Fai clic su Avanti
• Fai clic su Fine

Disco dati incluso

L'OVA contiene già il disco dati dell'appliance (VEREIGN-DATA, montato su /var/data) — non c'è alcun disco aggiuntivo da collegare. Vedi Guida all'installazione → Passo 4.

Accedi e inizializza l'istanza Stargate

• Accedi alla console VM con l'utente hinadmin per configurare e installare i componenti Stargate.
• Per ottenere la password hinadmin, invia un'email a support@hin.ch con oggetto: "Password required for VM installation."

Clicca qui per inviare un'email

sudo su -
cd ~/stargate-deployment/docker-compose/

• Utilizza vi/nano per modificare customer-config.sh
• I dettagli di configurazione si trovano nel README - Passo 1: Configurare le impostazioni cliente
• Esegui lo script di installazione:

./scripts/install.sh

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance Stargate, contatta il supporto HIN.

Includi informazioni rilevanti come il nome del cliente, la versione dell'appliance e screenshot/log dove applicabile, per aiutarci a elaborare la tua richiesta in modo efficiente.

Deployment Proxmox tramite immagine

Distribuisci Stargate su Proxmox

Ottenere l'URL del file immagine

• Fai riferimento al Catalogo VM per un elenco di immagini con URL.
• Copia l'URL negli appunti, ad esempio https://images.hin.ch/vm-images/hingateway_v0.0.0.x86_64.qcow2

Importare il file immagine in Proxmox

• Nell'interfaccia web di Proxmox, naviga al menu Storage e fai clic su Importa
• Fai clic su Scarica da URL, incolla l'URL copiato e fai clic su "Interroga URL".
• Fai clic su Scarica e attendi che "TASK OK" appaia alla fine del log di output.
• Chiudi la finestra di download del Visualizzatore attività.

Creare una VM

• Fai clic su "Crea VM"
• Digita un nome per la VM
• Fai clic su "Avanti"
• Scegli "Non utilizzare alcun supporto"
• Fai clic su "Avanti"
• Fai clic su "Avanti"
• Fai clic sull'"icona del cestino" accanto a "scsi0" per rimuoverla.
• Fai clic su "Importa" e in "Seleziona immagine", scegli il file immagine appena importato.
• Fai clic su "Avanti"
• Seleziona 4 core CPU e scegli il tipo di CPU (o usa "host"). Fare riferimento ai Requisiti del server.
• Fai clic su "Avanti"
• Seleziona 8192 MiB di memoria. Fare riferimento ai Requisiti del server.
• Fai clic su "Avanti"
• Fai clic su "Avanti"
• Attendi fino al termine del processo di creazione della VM, quindi fai clic sulla nuova VM, fai clic su "Console", fai clic su "Avvia ora"

Collega prima il disco dati

Prima del primo avvio, collega un secondo disco vuoto di almeno 30 GB. Al primo avvio l'appliance lo formatta come disco dati (VEREIGN-DATA, montato su /var/data) e vi conserva tutta la configurazione e i dati; senza di esso l'avvio fallisce ed esegue il rollback. Vedi Guida all'installazione → Passo 4.

Installare HIN Gateway

Dopo che la VM è stata creata con successo, procedi con i passaggi di installazione e onboarding come descritto nelle istruzioni fornite.

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance Stargate, contatta il supporto HIN.

Includi informazioni rilevanti come il nome del cliente, la versione dell'appliance e screenshot/log dove applicabile, per aiutarci a elaborare la tua richiesta in modo efficiente.

Deployment Windows 11 Pro tramite immagine

Distribuisci Stargate su Windows Pro (le versioni non-Pro non supportano Hyper-V)

Installare Hyper-V

• Fai clic sul pulsante Start, quindi digita "Attiva o disattiva funzionalità di Windows"
• Fai clic su quel pulsante
• Seleziona Hyper-V e fai clic su "OK"
• Dopo il completamento dell'installazione, fai clic su "Riavvia ora" e attendi il riavvio di Windows

Nota: Si consiglia di distribuire la VM utilizzando Hyper-V Generazione 2

Ottenere l'immagine

• Scarica il file immagine .vhdx. Fare riferimento al Catalogo VM

Importare il file immagine e creare una VM con esso

• Fai clic sul pulsante "Start" e digita "Creazione rapida Hyper-V"
• Fai clic su quell'icona
• Scegli "Sorgente di installazione locale"
• Deseleziona "Questo computer eseguirà Windows"
• Fai clic su "Cambia sorgente di installazione", naviga all'immagine .VHDX scaricata e fai clic su di essa
• Fai clic su "Crea macchina virtuale"
• Fai clic su "Modifica impostazioni"
• In "Memoria", scegli "RAM" 8192 MB. Fare riferimento ai Requisiti del server.
• In "Processore", scegli "Numero di processori virtuali" 4. Fare riferimento ai Requisiti del server.
• Fai clic su "OK"
• Fai clic su "Connetti"
• Fai clic su "Avvia"

Collega prima il disco dati

Prima del primo avvio, collega un secondo disco vuoto di almeno 30 GB. Al primo avvio l'appliance lo formatta come disco dati (VEREIGN-DATA, montato su /var/data) e vi conserva tutta la configurazione e i dati; senza di esso l'avvio fallisce ed esegue il rollback. Vedi Guida all'installazione → Passo 4.

Accedi e inizializza l'istanza Stargate

• Accedi alla console VM con l'utente hinadmin per configurare e installare i componenti Stargate.
• Per ottenere la password hinadmin, invia un'email a support@hin.ch con oggetto: "Password required for VM installation."

Clicca qui per inviare un'email

sudo su -
cd ~/stargate-deployment/docker-compose/

• Utilizza vi/nano per modificare customer-config.sh
• I dettagli di configurazione si trovano nel README - Passo 1: Configurare le impostazioni cliente
• Esegui lo script di installazione:

./scripts/install.sh

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance Stargate, contatta il supporto HIN.

Includi informazioni rilevanti come il nome del cliente, la versione dell'appliance e screenshot/log dove applicabile, per aiutarci a elaborare la tua richiesta in modo efficiente.

Deployment Stargate su Cloudscale tramite immagine

Ottenere l'URL del file immagine

• Fai riferimento al Catalogo VM per le immagini disponibili con URL.
• Copia l'URL qcow2 negli appunti.

Importare il file immagine in Cloudscale

• Nell'interfaccia web di Cloudscale, naviga al menu "Immagini personalizzate" e fai clic su "Importa un'immagine personalizzata".
• Imposta un Nome immagine appropriato.
• Definisci uno Slug, ad esempio "stargate".
• Incolla l'URL dell'immagine Stargate nel campo URL di download.
• Imposta Formato sorgente sul formato di caricamento, consigliato: qcow2.
• Configura eventuali impostazioni aggiuntive se necessario.
• Fai clic su Importa.

Creare una VM

• Naviga su Server e fai clic su Avvia un nuovo server.
• Inserisci il tuo FQDN o nome host preferito.
• In Sistema operativo, seleziona Immagini personalizzate e scegli l'immagine importata.
• In Flavor di calcolo, seleziona Flex-4-2 o Flex-8-2 a seconda del carico previsto (può essere regolato in seguito). Vedi Requisiti del server per i dettagli.
• In Capacità di archiviazione, imposta almeno 30 GB. Fare riferimento ai Requisiti del server.
• In Posizione del server, seleziona la zona preferita.
• In Gestione della rete, abilita solo IPv4 se l'istanza Stargate deve essere accessibile via Internet (es., per Office 365).
• In Sicurezza di accesso, seleziona la tua chiave SSH (utilizzabile con l'utente almalinux).
• Nella sezione Password, imposta una password sicura a tua scelta.

Senza una password, l'autenticazione SSH tramite password è disabilitata

Per il primo accesso devi comunque utilizzare la password iniziale fornita da HIN. Tuttavia, se non imposti una nuova password, cloud-init disabiliterà l'autenticazione SSH tramite password per tutti gli utenti, consentendo l'accesso SSH solo tramite chiave pubblica.

• Fai clic su Avvia.

Collega prima il disco dati

Prima del primo avvio, collega un secondo disco vuoto di almeno 30 GB. Al primo avvio l'appliance lo formatta come disco dati (VEREIGN-DATA, montato su /var/data) e vi conserva tutta la configurazione e i dati; senza di esso l'avvio fallisce ed esegue il rollback. Vedi Guida all'installazione → Passo 4.

Accedi e inizializza l'istanza Stargate

• Accedi alla console VM con l'utente hinadmin per configurare e installare i componenti Stargate.
• Per ottenere la password hinadmin, invia un'email a support@hin.ch con oggetto: "Password required for VM installation."

Clicca qui per inviare un'email

sudo su -
cd ~/stargate-deployment/docker-compose/

• Utilizza vi/nano per modificare customer-config.sh
• I dettagli di configurazione si trovano nel README - Passo 1: Configurare le impostazioni cliente
• Esegui lo script di installazione:

./scripts/install.sh

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance Stargate, contatta il supporto HIN.

Includi informazioni rilevanti come il nome del cliente, la versione dell'appliance e screenshot/log dove applicabile, per aiutarci a elaborare la tua richiesta in modo efficiente.

Catalogo immagini VM

Qui puoi trovare un catalogo VM attuale per diverse piattaforme. Non dimenticare di verificare l'hash SHA-256 delle immagini scaricate. Puoi utilizzare il file https://images.hin.ch/vm-images/SHA256SUMS per confrontarlo.

Come eseguire il controllo dell'hash SHA256 localmente

Puoi calcolare l'hash SHA256 dei file scaricati con il seguente comando e poi confrontarlo con i valori nella tabella sottostante.

Linux e macOSWindows

Apri il Terminale ed esegui:

sha256sum <Nome del file>

Come variante più avanzata, puoi eseguire il seguente comando e incollare la somma di controllo predefinita come SHA256_VALUE e il nome del file come IMAGE_NAME:

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

Apri PowerShell ed esegui:

Get-FileHash "<Nome del file>"

Puoi aggiungere l'argomento -Algorithm SHA256 per forzare l'uso di SHA256.

Nome immagine	Tipo immagine	Dimensione immagine	Link	Somma di controllo SHA256
hingateway-v0.6.1.x86_64.mf		4.0K / 364 bytes	Download	755f7645304bc61012d5a4970a1700f033553a872cc562926fb9d9ec052e4589
hingateway-v0.6.1.x86_64.ova		3.2G / 3429335040 bytes	Download	a63cbec510511f736a5df5326c8d0528997f181220e24415a2f37cb5bfd82597
hingateway-v0.6.1.x86_64.ovf		12K / 9322 bytes	Download	878128433cdd49fd2198611fca204ff9b0ebae91dcdadc1b6e0e17cb29831b4d
hingateway-v0.6.1.x86_64.qcow2		3.3G / 3458072576 bytes	Download	c60497fb6d215df343c456a88315058c539337d50cf062d3dcc5dd0e89c0737b
hingateway-v0.6.1.x86_64.raw		30G / 32212254720 bytes	Download	ece449d140bb475910fc9d79108cb929b7e8004a0046e8de0a9019998967d57a
hingateway-v0.6.1.x86_64.raw.gz		3.2G / 3410152384 bytes	Download	6195b21b4e79c89929b1beea5f9fe8d200f339435f1f8bd69f0e14d788e411ca
hingateway-v0.6.1.x86_64.vhd		31G / 32212255232 bytes	Download	a6f030f1598e12f187be60c65ae34b1c201da8afc1351ddbead1360979269017
hingateway-v0.6.1.x86_64.vhd.gz		3.2G / 3410152459 bytes	Download	92b138f5b03c03ab4dcb8ff64769181414a00f8a82c595a269435ef661835e1c
hingateway-v0.6.1.x86_64.vhdx		4.6G / 4857004032 bytes	Download	80856d27a9d0d03ec44b4330d5357bcc4e9f857847f9103a4344d567f42c3b66
hingateway-v0.6.1.x86_64.vmdk		3.2G / 3425249280 bytes	Download	8f4de40dcf9f920275b9a37ec126a9cd4f12f22b74a0cf5b26b6f18fb2a3a936
SHA256SUMS		4.0K / 979 bytes	Download	d375123bfe3a749990b435cd6c8c89e2fa6edd099ae878b3bf107950a0c07e31

Troubleshooting e diagnostica

Una guida strutturata alla diagnosi di un'appliance Stargate via riga di comando: aspetti da verificare, posizione dei log e misure di ripristino sicuro.

Dove eseguire questi comandi

Eseguire tutto ciò che segue dalla directory di deployment - la cartella contenente docker-compose.yml e scripts/ (nelle immagini VM si tratta generalmente di /usr/share/stargate-deployment/docker-compose, oppure la directory in cui è stata effettuata l'installazione). Tutti i comandi docker compose e ./scripts/* presuppongono questa directory di lavoro.

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

---

1. Per iniziare: controllo dell'integrità

Un unico comando riassume l'intera appliance:

QuickVerbose

./scripts/health-check.sh

./scripts/health-check.sh -v

Segnala «superato / non superato» per: container (in esecuzione / integri), liveness endpoint (smimekeys, policy, irisagent, mxengine), stato di blocco Vault, connettività e database PostgreSQL, SeaweedFS, tunnel WireGuard e handshake tra peer, Stalwart MTA (porte 25 / 10026), endpoint metriche Prometheus e disco/memoria.

Tip

Eseguire questo comando per primo. Una singola riga FAIL di solito rimanda direttamente alla sezione sottostante.

---

2. Posizione dei log

Livello	Comando	Visualizzazione
Avvio / prima installazione / avvio automatico	sudo journalctl -u stargate -n 200 --no-pager	Il servizio systemd che esegue start.sh all'avvio e durante l'installazione al primo avvio
Aggiornamenti	cat ../update.log (cartella root di deployment, un livello sopra docker-compose/)	Output dell'ultimo update.sh avviato da dashboard/host
Un unico servizio	docker logs stargate-<service> --tail 100	ad es. stargate-dashboard, stargate-mxengine, stargate-keycloak
Seguire un servizio live	docker logs -f stargate-mxengine	In tempo reale
Tutti i container live	docker ps -a --format '{{.Names}}' \| xargs -I{} sh -c 'docker logs --timestamps -f {} 2>&1 \| sed "s/^/[{}] /"'	Accorpati, con il nome del container come prefisso
Visualizzatore log web	Dozzle su https://<SERVER_IP>:8190 (login Keycloak)	Consente di consultare tutti i log dei container in un'interfaccia utente

Per inviare i log all'Assistenza HIN, utilizzare lo script di caricamento e condividere il link generato - si veda Fornire log all'Assistenza:

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

---

3. Container che non si avviano o si riavviano

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

Leggere la colonna Status:

Status	Significato	Azione
Up ... (healthy)	In esecuzione, correttamente	-
Up ... (senza controllo dell'integrità)	In esecuzione; nessun controllo dell'integrità definito	Verificare i docker logs se si sospetta un problema
Restarting	Crash-looping	docker logs stargate-<svc> - correggere l'errore alla radice (config, secret, dipendenza)
Exited (0)	Inizializzazione one-shot conclusa correttamente (ad es. *-init, vault-data-fixer)	Normale
Exited (1+)	Fallito	docker logs stargate-<svc> - le ultime righe indicano il motivo
Created	Mai avviato - una dipendenza non è disponibile	Verificare da cosa dipende (depends_on, di solito Postgres/Vault); risolvere prima quello

Riavviare un singolo servizio (in modo sicuro e non distruttivo):

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

Ordine di avvio

I servizi attendono le proprie dipendenze (depends_on + controlli dell'integrità). Durante un riavvio completo, brevi righe come connection refused / database system is starting up mentre Postgres/Vault si avviano sono normali e scompaiono entro un minuto.

---

4. Diagnosi in base ai sintomi

Dashboard o Keycloak non si caricano / non è possibile effettuare l'accesso

• Entrambi sono esposti tramite Caddy: la Dashboard sulla porta :443, Keycloak sulla porta :8180.
• Controllare l'intera catena: docker logs stargate-caddy, stargate-dashboard, stargate-keycloak, stargate-apisix.
• Keycloak deve essere integro affinché la dashboard funzioni: docker compose ps keycloak.
• È normale che nel browser compaia un avviso TLS (self-signed cert) - accettare e proseguire.
• Gli errori nei reindirizzamenti durante l'accesso indicano generalmente che l'URL pubblico non corrisponde alla modalità con cui si raggiunge l'appliance - verificare che KEYCLOAK_PUBLIC_URL / DASHBOARD_PUBLIC_URL in .env puntino effettivamente all'IP o all'host realmente utilizzato.

Tunnel WireGuard inattivo / errore nell'emissione del certificato

È il problema più comune - i certificati non vengono emessi quando il tunnel è inattivo, pertanto occorre sempre risolvere prima il problema del tunnel.

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

• Verificare che il firewall consenta 19818 (UDP e TCP) in entrata e in uscita.
• Verificare che il peer sia registrato sul lato HIN (passaggio a carico dell'Assistenza) - occorre fornire la chiave pubblica WG, DEPLOYMENT_NAME, SERVER_STATIC_IP, WG_INTERFACE_PORT.
• Non appena il tunnel mostra un handshake recente, riprovare a emettere il certificato dalla dashboard.

Vault bloccato o inizializzazione fallita

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

• Il Vault deve essere sbloccato affinché smimekeys/mxengine/policy funzionino. Le chiavi si trovano in secrets/vault-keys.json.
• Se vault-init è terminato con un codice di uscita diverso da zero, il file delle chiavi potrebbe mancare o essere danneggiato - controllare i relativi log; rilanciando ./scripts/init-vault.sh si tenta un nuovo sblocco.

Non eliminare secrets/vault-keys.json

Perdere il file significherebbe perdere l'accesso a tutti i secret memorizzati. Eseguire un backup.

PostgreSQL / connettività al database

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

• È normale che the database system is starting up (57P03) si verifichi subito dopo un riavvio - i servizi si riconnettono automaticamente.
• Gli errori di autenticazione ricorrenti indicano solitamente che POSTGRES_PASSWORD nel file .env non corrisponde più a quello memorizzato nel volume dati - consultare le note relative agli aggiornamenti e ai secret, ed evitare di modificarlo manualmente.

La posta non viene recapitata

• La posta in entrata arriva sulla porta :25 (Stalwart). Molti fornitori di servizi cloud bloccano la porta 25 per impostazione predefinita:

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

  Se la porta 25 è bloccata, bisogna richiedere un'eccezione al proprio provider. - Posta in uscita / sealing: segue il percorso Stalwart → mxengine (:8084 callback di blocco, SMTP :1587): docker logs stargate-mxengine. - I loop di posta si manifestano con la ripetizione dello stesso messaggio - verificare che il record MX del proprio dominio non venga risolto nell'indirizzo IP di questa stessa appliance. - Vedere Configurazione relay di posta e Configurazione DNS per il routing previsto.

Aggiornamento fallito

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

• L'ops-agent recupera il manifesto di release, scrive le versioni nel file customer-config.sh, quindi esegue lo script update.sh sull'host.
• Al termine, confermare le versioni applicate: ./scripts/gather-app-versions.sh (oppure verificare i tag delle immagini con docker compose ps).
• Se un servizio si blocca dopo un aggiornamento, eseguire docker compose up -d <service> per ricrearlo.

L'aggiornamento si avvia ma non succede nulla (aggiornamento da una versione precedente). Se il log dell'ops-agent si blocca su pulling deployment repo ... e l'aggiornamento non procede, il repository sulla VM molto probabilmente presenta modifiche locali a un file monitorato (solitamente un docker-compose.yml modificato manualmente). Questo fa sì che il git checkout dell'ops-agent si rifiuti di essere eseguito, e l'aggiornamento resta bloccato. Forzare il ripristino del repository all'ultima revisione, quindi ripetere l'aggiornamento. Git è l'unica fonte affidabile; questa operazione elimina esclusivamente le modifiche locali ai file monitorati - customer-config.sh, .env e secrets/ sono esclusi tramite .gitignore e vengono preservati:

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

update.sh rigenera il file .env, scarica le immagini e ricrea i servizi interessati - non è necessario riavviare Stargate manualmente. Al termine, ripetere l'aggiornamento dalla dashboard: a questo punto procederà correttamente.

Warning

Non utilizzare git pull in questo caso. Su un working tree con modifiche locali il comando si interrompe con l'errore "local changes would be overwritten", il che costringe a un percorso alternativo con git stash, conflitti di merge o un ripristino manuale. La sequenza git checkout -f + git reset --hard riportata sopra evita completamente questo problema ed è il metodo sicuro e ripetibile per riportare il repository allo stato aggiornato.

Dozzle (log viewer) non raggiungibile

• L'URL è https://<SERVER_IP>:8190; richiede il login a Keycloak (stesso realm della dashboard) tramite oauth2-proxy.
• Funziona solo quando DOZZLE_ENABLED="true". Verificare con: docker compose ps dozzle oauth2-proxy.
• Assicurarsi che il firewall consenta il traffico in entrata sulla porta :8190. Vedere Monitoraggio e Log.

---

5. Archiviazione e disco

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

• I log dei container sono soggetti a un limite massimo (file json, 100 MB × 5 per container), quindi non dovrebbero saturare il disco - a differenza di immagini e volumi.
• Per liberare spazio in sicurezza: docker image prune -af (rimuove solo le immagini non utilizzate). Evitare docker system prune --volumes - elimina i volumi con i dati.
• L'archiviazione a oggetti è SeaweedFS (stargate-seaweedfs): docker logs stargate-seaweedfs --tail 50.

---

6. Risorse VM

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

Le metriche dell'host vengono esportate anche per Prometheus sulla porta :9100/metrics (vedere Monitoraggio). Se l'appliance è in swap o al limite delle risorse, è probabile che i controlli dell'integrità presentino fluttuazioni e che gli aggiornamenti risultino lenti.

---

7. Rete e porte

Verifica rapida della raggiungibilità delle principali porte in entrata:

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

Porta	Servizio	Direzione
25	Stalwart SMTP (posta in entrata)	in entrata
443	Dashboard (HTTPS)	in entrata
8180	Keycloak	in entrata
8190	Dozzle (opzionale)	in entrata
19818	WireGuard (UDP e TCP)	in entrata / in uscita

È necessario l'accesso in uscita al registro dei container, all'autorità di certificazione S/MIME (tramite il tunnel WireGuard) e a qualsiasi istanza remota di Loki configurata. Per la tabella completa delle porte, vedere la home page e la panoramica delle applicazioni.

---

8. Misure di ripristino

In ordine crescente di impatto:

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

Backup e ripristino distruttivo

./scripts/backup.sh e ./scripts/restore.sh gestiscono il backup e il ripristino dei dati. Lo script ./scripts/purge.sh elimina tutti i dati (database, Vault, archiviazione) per consentire una reinstallazione pulita - utilizzare solo come ultima risorsa e solo se si dispone di un backup recente. Dettagli: Configurazione avanzata di Docker.

---

9. Quando contattare l'Assistenza

Se, dopo aver seguito i passaggi sopra indicati, il controllo dell'integrità continua a segnalare errori, aprire un ticket tramite Assistenza / Contattaci e includere:

• La versione dell'appliance (./scripts/gather-app-versions.sh) e il nome del cliente.
• L'output del controllo dell'integrità (./scripts/health-check.sh -v).
• Un link al pacchetto di log generato da ./scripts/send-logs-to-support.sh (vedere Fornire log all'Assistenza).
• Cosa si stava facendo quando si è verificato il problema, ed eventuali screenshot.

Aggiornamento dell'istanza Verimesh

Le seguenti istruzioni descrivono come aggiornare un'istanza Verimesh dalla versione v0.5.1 alla versione v0.5.3.

Nota: è necessario effettuare l'accesso alla VM utilizzando l'account amministratore Linux.

Procedura di aggiornamento

1. Modificare il file .env e aggiornare la versione di ops-agent a v0.0.3.
2. Modificare la configurazione del cliente e aggiornare anche lì la versione di ops-agent a v0.0.3.
3. Passare al branch main: git checkout main
4. Scaricare le ultime modifiche: git pull
5. Aggiornare il container ops-agent: docker compose up -d ops-agent
6. Accedere alla Dashboard.
7. Accedere alle Impostazioni.
8. Nella sezione Update in fondo alla pagina, inserire la versione di destinazione (v0.5.3) e avviare la procedura di aggiornamento.

Configurazione aggiornata di Keycloak

Nota: le presenti istruzioni sono valide se si utilizza l'immagine VM v0.5.1 e si è successivamente eseguito l'aggiornamento a una versione più recente.

In seguito all'ultimo aggiornamento di Keycloak, un breaking change fa sì che gli utenti autenticati vengano reindirizzati in modo imprevisto alla pagina di login quando accedono a determinati percorsi dell'applicazione (ad es. Peers, Peer Certificates).

Per risolvere il problema, occorre completare la seguente configurazione manuale nella interfaccia utente di Keycloak.

Procedura di risoluzione

1. Aprire Keycloak nell'ambiente e inserire l'URL - <VM IP address>/admin/master/console/ Nome utente: Admin Password: recuperare la password amministratore dal file .env della macchina (è necessario effettuare l'accesso alla console Linux)

2. Console Admin - modificare il realm in → realm stargate:

3. Selezionare Clients → dashboard
4. Accedere alla scheda Client scopes → cliccare su dashboard-dedicated
5. Selezionare Configure a new mapper → Audience

6. Impostare le seguenti configurazioni:

   • Name: apisix-audience
   • Included client audience: apisix (selezionare dal menu a tendina)
   • Included custom audience: (lasciare vuoto)
   • Add to access token: On
   • Add to token introspection: On
   • Add to ID token / lightweight token: Off

7. Cliccare su Save

Release Notes

v0.6.1

Released on 4 September 2026.

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

What’s new and improved

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

Fixes

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

v0.6.0

Released on 31 August 2026.

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

What’s new and improved

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

Fixes

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

Important information for appliance migrations

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

v0.5.3

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

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

Hotfix, 5 August 2026

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

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

What’s new and improved

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

Fixes

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

v0.5.1

Our initial release.

Contattaci

Contattaci via email

Supporto

Per qualsiasi domanda o problema relativo al deployment e al funzionamento dell'appliance Stargate, contatta il supporto HIN via email o telefono:

• support@hin.ch
• 0848 830 740
• Modulo web

Puoi trovare maggiori informazioni nella nostra pagina Contatti: https://support.hin.ch/de/kontakt.cfm

Includi informazioni rilevanti come il nome del cliente, la versione dell'appliance e screenshot/log dove applicabile, per aiutarci a elaborare la tua richiesta in modo efficiente.