Istruzioni di deployment Stargate¶

Cos'è Stargate?

Guida rapida¶

Opzioni di installazione¶

Installazione tramite immagine VM:

🖨️

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

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

# Consenti le connessioni TCP in uscita verso le porte aperte
iptables -A OUTPUT -p tcp -m multiport --dports 25,8084,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

Porta	Protocollo	Scopo
`25`	TCP	SMTP - ricezione di posta da server esterni
`8084`	TCP	HTTP - callback di sigillatura da servizio di sigillatura remoto
`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
hub.docker.com	`443`	TCP	Registry delle immagini Docker
mxengine-dev.k8s.vereign-cdn.com	`443`	TCP	Servizio di sigillatura remoto
smimekeys-ca-dev.k8s.vereign-cdn.com	`443`	TCP	Servizio CA S/MIME
loki.example.com	`443`	TCP	Invio log (Alloy → Loki, opzionale)
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

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 Mail Gateway - Processo di installazione tecnica¶

Tip

Processo di installazione tecnica per architettura di posta a dominio singolo con Microsoft 365

Introduzione¶

Questo documento fornisce una guida completa al processo di installazione tecnica e migrazione verso il nuovo HIN Gateway ("Stargate Appliance"). Si applica alle architetture di posta Microsoft 365 che utilizzano un singolo dominio fidato.

La guida è destinata ai clienti HIN, amministratori IT e ingegneri di sistema responsabili del deployment e della configurazione del nuovo HIN Gateway, e 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 applicate 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 domini.

Processo di installazione e migrazione¶

La procedura strutturata passo-passo descritta in questo documento copre i seguenti punti:

Preparazione e pianificazione del fallback
Installazione e configurazione dell'HIN Gateway
Attivazione del dominio e validazione del certificato
Integrazione del server di posta e configurazione del routing
Test, transizione alla produzione e validazione post-migrazione
Disattivazione del MGW esistente

L'obiettivo di HIN in questo processo è garantire una migrazione sicura, fluida e completamente validata che causi il minimo disturbo alle operazioni e garantisca la continuità ininterrotta dei servizi email.

Domande frequenti¶

Posso eseguire l'installazione e la migrazione autonomamente?

Sì, l'installazione e la migrazione possono essere completate interamente dal cliente, ad eccezione del "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 per esportare la chiave privata dal Mail Gateway attualmente in funzione.

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

Ci saranno interruzioni nella consegna delle email durante la migrazione?

Tra "Passo 1.5 - Spegnimento del MGW VM esistente" e "Passo 18 - Configurazione del server di posta", tutte le email saranno 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.

Panoramica dei passaggi di installazione¶

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

Passaggi dettagliati¶

Passo 0 - Verifica prerequisiti¶

Si prega di rivedere le "Istruzioni di deployment Stargate" e assicurarsi 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 della migrazione:

Le credenziali ti saranno fornite da HIN
- Credenziale VM
- Credenziale Keycloak
- Codice di attivazione
Esportazione della chiave privata
- 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".
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:

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

Esportazione della chiave privata

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¶

Invia una email di test ai seguenti destinatari, dove hai accesso alla cassetta postale per verificare la corretta ricezione:

Un indirizzo email HIN o un dominio della comunità HIN di tua proprietà, ad esempio: user@hin.ch
Un indirizzo email al di fuori della comunità HIN, ad esempio: user@bluewin.ch

Verifica che entrambe le email vengano consegnate con successo, inclusi oggetto, contenuto e allegato (se inviato).

Passo 1.2 - Backup del MGW esistente¶

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

Passo 1.3 - Esportazione delle chiavi private¶

Assistenza HIN richiesta

Per questo passaggio è necessario un codice di sblocco. Il codice viene fornito da un support engineer HIN. Se desidera proseguire l’installazione autonomamente, La invitiamo a contattare il supporto HIN per richiedere il codice di sblocco. In caso contrario, il codice di sblocco Le sarà fornito durante la chiamata di migrazione pianificata.

Accedi alla webGUI del MGW esistente.
Aprire "Mail System".
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.
Inserire il codice di sblocco fornito dal tecnico dell'assistenza.
Selezionare "Enable export".
Inserire l'indirizzo IP dell'MGW.
Attendere la conferma.
Selezionare il dominio attendibile nella webGUI dell'MGW.
Scorrere verso il basso e selezionare l'impronta digitale gestita.
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.
Tornare all'applicazione HIN_Migration-Tool_v*.exe e disattivare il pulsante Export.

Passo 1.4 - Piano di contingenza / scenario di fallback¶

Scenario di rollback - se è richiesto un rollback:

Arresta il nuovo HIN Gateway.
Accendi il MGW esistente.
Verifica che il traffico email in entrata e in uscita funzioni correttamente tramite il MGW esistente.

Passo 1.5 - Spegnimento del MGW VM esistente¶

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:
Configurazione di Microsoft Exchange

Passo 4 - Caricamento dell'immagine VM¶

Carica l'immagine VM selezionata sul tuo hypervisor.

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:

Esegui il comando "nmtui" nella console
```
nmtui
```
Usa i tasti freccia per navigare, quindi premi "Invio" per selezionare la "Connessione Ethernet" per la quale desideri modificare l'indirizzo IP.
Naviga a "Configurazione IPv4" e modifica l'impostazione da "Automatico" a "Manuale".
Usa i tasti freccia per navigare ai campi dove puoi inserire l'indirizzo IP, il gateway e il server DNS. Quindi seleziona "OK".
Dopo aver salvato la configurazione dell'indirizzo IP, esegui il seguente comando nella console:
```
sudo systemctl restart NetworkManager
```

La rete deve essere configurata prima del primo avvio

L'immagine VM esegue un'installazione automatica al primo avvio. Se la rete non è ancora configurata (nessun indirizzo IP assegnato tramite DHCP o config statico), l'installazione fallirà perché l'IP del server non può essere rilevato.

Se ciò accade, configura la rete manualmente, quindi esegui:

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

Lo script di installazione rileverà automaticamente l'IP del server dalla route predefinita. Qualsiasi IP raggiungibile (pubblico o privato) è sufficiente - l'endpoint pubblico effettivo viene configurato successivamente tramite il dashboard.

Tip

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

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

Lo script di installazione rileverà automaticamente l'indirizzo IP del server dalla route predefinita. Qualsiasi indirizzo IP raggiungibile, pubblico o privato, è sufficiente. L'endpoint pubblico effettivo viene configurato successivamente tramite il dashboard.

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). Fare 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). Fare 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 ora stabilirà la connessione di rete mesh sicura. Questo passaggio collega l'HIN Gateway all'Iris Agent e sincronizza i certificati.

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

Se la connessione fallisce

Se lo stato di Iris Agent o di 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. Deve invece essere accessibile tra il computer di amministrazione e la VM che si sta installando. In caso contrario, non sarà possibile connettersi a Keycloak e proseguire con l'installazione.

Cosa fare se viene visualizzato un errore di connessione

Verificare che la porta 8180 sia accessibile dal computer alla VM. Dopo aver aggiornato la configurazione, tornare all'interfaccia utente all'indirizzo https://<VM IP address> e fare 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). Fare 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.

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¶

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

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.

Passo 14 - Configurazione trasporto posta¶

In questa schermata, configura le impostazioni di trasporto della posta per il setup del relay di posta sicuro.

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.
Domains	Ogni dominio gestito da questo gateway, insieme al suo host di relay (il server di posta interno a cui viene consegnata la posta in entrata).
Default relay host	Il relay SMTP predefinito per la consegna in uscita.

Nella sezione Advanced, puoi facoltativamente configurare:

Impostazione	Descrizione
Configure TLS	Impostazioni del certificato TLS per le connessioni SMTP.
Content filter	L'endpoint del filtro contenuti interno (predefinito: `mxengine:1587`).
Trusted networks	Reti aggiuntive autorizzate a fare relay attraverso questo gateway.

Azioni aggiuntive:

Aggiungi domini aggiuntivi facendo clic su "Add domain", se necessario.
Espandi la sezione Advanced per ottimizzare i parametri di trasporto della posta.

Note

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

Una volta che la configurazione è stata rivista e completata, fai clic su "Apply configuration" per continuare.

Passo 15 - Configurazione intestazioni whitelist¶

Fai clic su "Domains", 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 "Domains". 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 server di posta¶

Se hai seguito l'approccio raccomandato esportando la chiave privata, importandola nell'HIN Gateway e mantenendo lo stesso indirizzo IP del MGW esistente, non sono richieste modifiche sul server di posta.

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

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

Vedere Integrazione Exchange per istruzioni dettagliate.

Passo 19 - Test prima del passaggio¶

Ripeti il "Passo 1.1 - Smoke test". In aggiunta allo smoke test, testa e conferma quanto segue:

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.

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.

Passo 20 - Validazione dopo il passaggio¶

Conferma:

Email consegnate
Crittografia applicata
Nessun ritardo o rimbalzo
Logging riuscito

Compila il "Acceptance Report" e consegnalo al tuo rappresentante HIN.

Passo 21 - Disattivazione del MGW esistente¶

Warning

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

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

Passo 22 - Modifica della password della VM¶

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

Allegato 1 - Backup e ripristino delle impostazioni dell'appliance¶

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.

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¶

Alloy scopre i container Stargate tramite il socket Docker
I log vengono sempre scritti nell'istanza Loki locale (utilizzata dal dashboard per l'esportazione dei log)
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 - Stargate come MX primario (raccomandato per l'elaborazione S/MIME in entrata):

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

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

In entrambi i modelli, sono necessari:

Record DNS che puntano al server Stargate
Connettore in uscita - instrada la posta da Exchange a Stargate
Connettore in entrata - accetta la posta da Stargate in Exchange
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.

Accedere al Centro di amministrazione Exchange - Connettori
Fare clic su "+ Aggiungi un connettore"
Connessione da: Selezionare "Office 365"
Connessione a: Selezionare "Server di posta della tua organizzazione"
Fare clic su "Avanti"
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.

Routing: Selezionare "Instrada le email attraverso questi smart host"
Inserire l'indirizzo IP del server Stargate: <STARGATE_IP>
Fare clic su "+" per aggiungerlo, quindi su "Avanti"
Restrizioni di sicurezza: Selezionare "Qualsiasi certificato digitale, inclusi i certificati auto-firmati"
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.

Email di validazione: Inserire un indirizzo email valido per il dominio (es. user@<YOUR_DOMAIN>)
Fare clic su "+", quindi su "Convalida"
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.

Rivedere le impostazioni e fare clic su "Crea connettore"
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.

Dalla pagina Connettori, fare clic su "+ Aggiungi un connettore"
Connessione da: Selezionare "Server di posta della tua organizzazione"
Connessione a: Mostra "Office 365" (automatico)
Fare clic su "Avanti"
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.

Rivedere le impostazioni e fare clic su "Crea connettore"
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).

Accedere al Centro di amministrazione Exchange - Regole
Fare clic su "+ Aggiungi una regola" → "Crea una nuova regola"
Nome regola: Inserire un nome descrittivo, es.:

Relay all mail to Stargate except mail coming from it

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

Note

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

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")
Fare clic su "Salva"
Eccetto se: Fare clic su "+" per aggiungere un'eccezione
Selezionare "Il mittente..." → "L'indirizzo IP si trova in uno di questi intervalli"
Inserire l'indirizzo IP del server Stargate: <STARGATE_IP>
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.

Rivedere il riepilogo della regola. Dovrebbe mostrare:
Applica questa regola se: Il destinatario si trova Fuori dall'organizzazione
Fai quanto segue: Reindirizza il messaggio al connettore "From Office 365 to Stargate relay server"
Eccetto se: L'indirizzo IP del mittente si trova in uno di questi intervalli: <STARGATE_IP>
Fare clic su "Avanti", poi "Avanti" di nuovo, poi "Fine", poi "Fine"
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):

Accedere a Flusso di posta → Connettori di invio
Fare clic su + per creare un nuovo connettore
Nome: "To Stargate Relay"
Tipo: Selezionare "Internet"
Impostazioni di rete: Selezionare "Instrada la posta attraverso smart host", aggiungere <STARGATE_IP>
Autenticazione smart host: Selezionare "Nessuna"
Spazio degli indirizzi: Aggiungere * (tutti i domini) o domini esterni specifici
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):

Accedere a Flusso di posta → Connettori di ricezione
Fare clic su + per creare un nuovo connettore
Nome: "From Stargate Relay"
Tipo: Selezionare "Trasporto frontend"
Binding adattatore di rete: Lasciare predefinito o associare a IP specifico
Impostazioni di rete remote: Rimuovere il valore predefinito 0.0.0.0-255.255.255.255 e aggiungere solo <STARGATE_IP>
Autenticazione: Selezionare "Sicurezza esterna"
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):

Accedere a Flusso di posta → Regole
Fare clic su + → "Crea una nuova regola"
Nome: "Relay outbound via Stargate"
Applica questa regola se: "Il destinatario si trova..." → "Fuori dall'organizzazione"
Fai quanto segue: "Reindirizza il messaggio a..." → "il seguente connettore" → "To Stargate Relay"
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 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:

p=none - solo monitoraggio (iniziare qui)
p=quarantine - le email sospette vanno in spam
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).

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:

Controllare le dipendenze — Rileva Docker, Docker Compose e jq. Se mancano, li installa automaticamente (supporta Ubuntu/Debian, RHEL/AlmaLinux/Rocky).
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.).
Generare .env dalla configurazione cliente — Genera automaticamente le password se non impostate.
Avviare tutti i servizi tramite Docker Compose (infrastruttura + applicazioni).
Inizializzare Vault — Il container vault-init inizializza, scongela e crea i mount dei segreti KV-v2. Scrive opzionalmente la chiave privata WireGuard in Vault.
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.
Riavviare i servizi applicativi per applicare il token Vault.
Salvare la chiave privata WireGuard in customer-config.sh — estratta da Vault dopo che IRISAgent l'ha generata.
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:

Chiave pubblica WireGuard — estrarre dai log irisagent:

docker compose logs irisagent | grep "public key"

DEPLOYMENT_NAME — dal proprio customer-config.sh
SERVER_STATIC_IP — l'IP pubblico del server Stargate
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 è:

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).
Connettore in uscita "Invia a MX" - consegna al MX del destinatario, attivato solo dalla regola di trasporto.
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.
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".
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:

Avvia i servizi di infrastruttura
Scongela Vault utilizzando le chiavi memorizzate
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

O rimuovere manualmente i volumi. Il flag -v rimuove i volumi

docker compose down -v

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:

Arresta tutti i servizi in esecuzione
Estrae e valida il backup
Installa Docker se necessario
Ripristina la configurazione cliente
Avvia i servizi di infrastruttura (PostgreSQL, Vault, MinIO)
Ripristina il database
Scongela Vault con le chiavi di backup
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:

Aprire la dashboard e andare alla pagina di aggiornamento.
Selezionare la release desiderata.
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). Questo è il motivo per cui la porta 8084 deve essere aperta per il traffico in entrata. 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:

Avviare lo stack con ./scripts/install.sh.
Aprire il dashboard, seguire /installation per avviare l'handshake nonce / HIN.
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.
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):

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

Firewall che blocca la porta 19818 - Assicurarsi che 19818/TCP sia aperto sia in entrata che in uscita sul server Stargate.
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 lo stesso passaggio con l'intervallo di porte di destinazione 1587 e chiamala mxengine

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

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

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"

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.

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

Release Notes¶

v0.5.3¶

...

v0.5.1¶

Our initial release.

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:

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.