Checklist tecnico per validare end-to-end il tunnel WireGuard con Rela AI: dal primo handshake alla lettura del PLC, con comandi copy-paste e troubleshooting per categoria.

Come testare che la VPN funzioni

Questa guida è scritta per il tecnico IT del cliente — qualcuno che ha appena incollato la config WireGuard nel router e vuole confermare che tutto sia operativo prima di passare il testimone al team di stabilimento. Ogni passo include il comando esatto e il risultato atteso.

A cosa serve questa guida

Perché incolla-e-dimentica non diventi "alle 2 di lunedì nessuno raggiunge il PLC". Verificherai 6 layer in ordine: handshake → routing → connettività IP → porta TCP → richiesta Modbus → dashboard. Se qualche layer fallisce, il messaggio di errore punta esattamente al layer colpevole.

Come funziona la diagnosi per layer

Quando una connessione WireGuard non va, l'errore è quasi sempre in UN layer specifico — e ogni layer ha il suo strumento di diagnosi. Andare dal basso verso l'alto (handshake prima, Modbus alla fine) ti risparmia ore di "ho controllato tutto e non funziona".

Benefici


Diagnosi sistematica	Quando fallisce, sai esattamente quale layer aggiustare.
Meno chiamate al supporto	Il 95% dei problemi si risolve con questo checklist.
Evidenze per il tuo IT	Log e output concreti da allegare a un ticket se escali.

Prerequisiti

Prima di iniziare:

Config WireGuard applicata al tuo router/firewall (vedi Configurazione e Setup).
Accesso terminal (SSH / console web) al router o alla macchina che gira WireGuard.
IP privato del PLC conosciuto (dentro la tua rete locale).
Subnet assegnata da Rela AI (visibile nel dashboard al momento della creazione del peer — formato 10.200.X.0/24).

Layer 1 — Handshake WireGuard

Verifichiamo che il tuo router e il concentratore Rela AI si siano salutati.

pfSense / OPNsense

Menu: Status → WireGuard. Dovresti vedere:

Interfaccia rela_vpn in verde.
Sul peer, Latest Handshake con valore inferiore a 2 minuti.
Transfer con byte crescenti (rx e tx).

Mikrotik RouterOS

/interface wireguard peers print

Risultato atteso:

 # INTERFACE=rela-vpn  PUBLIC-KEY=clrU9+Aj...  LAST-HANDSHAKE=15s  RX=2.8KiB  TX=3.1KiB

Se LAST-HANDSHAKE dice never o un numero molto grande (>1 ora), l'handshake non è mai avvenuto. Salta a troubleshooting: Layer 1.

Ubiquiti EdgeOS

show interfaces wireguard wg0

Cerca peer: <pubkey> seguito da latest handshake: X seconds ago.

Linux (wg-quick)

sudo wg show wg0

Risultato atteso:

interface: wg0
  public key: <your-pubkey>
  listening port: 51820

peer: clrU9+AjXQ4GdSEV4NhIWs4uspF76tlemYpE8mZR6z0=
  endpoint: 34.22.248.0:51820
  allowed ips: 10.200.0.0/16
  latest handshake: 18 seconds ago
  transfer: 3.2 KiB received, 4.8 KiB sent
  persistent keepalive: every 25 seconds

Docker (linuxserver/wireguard)

docker exec rela-vpn wg show

Stesso formato del Linux diretto.

Criterio di approvazione: latest handshake < 120 secondi + transfer > 0 byte in entrambe le direzioni.

Layer 2 — Routing

La rotta verso la subnet assegnata da Rela AI deve passare per l'interfaccia WireGuard.

Linux / router con shell

ip route get 10.200.7.2  # sostituisci con IP dentro la tua subnet assegnata

Atteso:

10.200.7.2 dev wg0 src 10.200.7.2 uid 0

La chiave: dev wg0 (o rela-vpn secondo il nome che hai dato). Se appare dev eth0 o simile, la rotta è sbagliata e il traffico non va per il tunnel.

Mikrotik

/ip route print where dst-address=10.200.X.0/24

Dovrebbe mostrare una rotta GATEWAY=rela-vpn.

pfSense / OPNsense

Diagnostics → Routes e cerca 10.200.X.0/24 — deve puntare all'interfaccia rela_vpn.

Criterio di approvazione: il prefisso 10.200.X.0/24 (la tua subnet assegnata) ha una rotta via l'interfaccia WireGuard.

Layer 3 — Connettività IP (ping)

Dal tuo router/gateway, ping a un IP nella subnet assegnata da Rela AI:

ping -c 4 10.200.7.2

Atteso: 0% packet loss, RTT tipicamente 30–150 ms (dipende dalla tua posizione geografica rispetto a europe-west1).

Nota: Solo gli IP "del lato Rela AI" rispondono al ping se abbiamo un sim lì (testbed). In produzione la tua subnet è riservata solo per i tuoi dispositivi, quindi il ping fallirà finché non hai configurato un PLC o un test peer. L'assenza di ping a 10.200.X.2 non è necessariamente un errore in produzione.

Quando SÌ importa: dal lato dello stabilimento, ping <IP_del_PLC> (IP interno, NON l'IP VPN) deve funzionare. Se non funziona, il PLC o la tua LAN hanno problema — non è la VPN.

Criterio di approvazione: ping al PLC dal router (LAN locale) funziona.

Layer 4 — Porta TCP

Ora verifichiamo che la porta Modbus (502) del PLC risponda:

# Dal router / gateway, se ha nc o ncat:
nc -zv <IP_DEL_PLC> 502

# Alternativa con telnet:
telnet <IP_DEL_PLC> 502

Atteso:

Connection to 192.168.1.50 502 port [tcp/*] succeeded!

Se vedi Connection refused o No route to host, il problema è nello stabilimento — non nella VPN. Controlla:

Firewall locale dello stabilimento tra router e PLC.
Il servizio Modbus del PLC è acceso.
L'IP corretto — consulta la configurazione di rete del PLC.

Criterio di approvazione: nc/telnet alla porta 502 del PLC dice succeeded.

Layer 5 — Lettura Modbus reale

Prova di un read_holding_registers contro il PLC. Diversi strumenti:

Da Linux con pymodbus-client (più tecnico)

pip install pymodbus
python3 <<EOF
import asyncio
from pymodbus.client import AsyncModbusTcpClient
async def main():
    c = AsyncModbusTcpClient("192.168.1.50", port=502)
    await c.connect()
    r = await c.read_holding_registers(address=0, count=1, device_id=1)
    print("value:", r.registers if hasattr(r, "registers") else r)
    c.close()
asyncio.run(main())
EOF

Atteso: un numero (per esempio [785] se è temperatura × 10).

Da Windows con Modbus Poll (GUI)

Installare Modbus Poll (trial gratis).
Connect → Modbus TCP/IP → IP del PLC, porta 502, Unit 1.
Setup → Read/Write Definition → Holding Register, Address 0, Quantity 1.
Dovrebbe mostrare il valore in tempo reale.

Dal Dashboard Rela AI

Se hai già creato la fonte Modbus che punta al PLC:

Dashboard → Allarmi → Fonti → la-tua-fonte.
Clic su Test connection.
Si apre un pannello con:
- rtt_ms: latenza di andata e ritorno (deve essere inferiore a 500 ms).
- sample_values: tabella con il nome del registro + valore decodificato.

Criterio di approvazione: leggi un valore numerico che cambia col processo reale (se guardi per 10-30 secondi, dovrebbe variare leggermente se il processo è attivo).

Layer 6 — Pipeline completo nel Dashboard

L'ultimo miglio: gli eventi arrivano all'inbox.

Dashboard → Allarmi → Inbox.
Entro 1-5 minuti dall'attivazione della fonte, dovresti vedere eventi col nome del tuo registro come event_type (per esempio reactor.temperature).
L'inbox consolida detection dalla stessa fonte sotto lo stesso asset; se vedi una riga che cresce con count × N, funziona.

Criterio di approvazione: eventi col tuo event_type appaiono nell'inbox.

Troubleshooting Layer 1: l'handshake non arriva mai

Se Last Handshake = never o RX/TX a 0:

1. Firewall in uscita

Il tuo router deve poter fare una connessione in uscita UDP porta 51820 verso l'IP pubblico del nostro concentratore. Molti firewall corporate bloccano UDP di default.

Check: dal router, prova nc -uvz <ip-concentratore> 51820 (resta appeso per qualche secondo e finisce). Se il firewall permette, passa al prossimo passo; se blocca, chiedi all'IT di aprire quel flusso in uscita.

2. Chiave pubblica corretta

Un solo carattere perso nel copy-paste rompe l'handshake. Verifica che la PublicKey del peer nel tuo router coincida esattamente con quella mostrata dal dashboard.

3. NAT che chiude il mapping

Se il tuo router è dietro doppio NAT (ISP + corporate), il mapping UDP può chiudersi prima del prossimo handshake. Assicurati che PersistentKeepalive = 25 sia attivo. Questo forza un handshake ogni 25s e mantiene il NAT vivo.

4. MTU mismatch

Raro ma possibile: se la tua connessione ha MTU inferiore a 1420, i pacchetti WG si frammentano. Nei log del router puoi vedere "packet too big".

Fix: abbassa l'MTU dell'interfaccia WG a 1380:

pfSense: VPN → WireGuard → Settings → MTU = 1380
Linux: ip link set mtu 1380 dev wg0

Troubleshooting Layer 3-4: handshake OK ma non arrivi al PLC

1. Forwarding disabilitato nel router

Il tuo router deve avere net.ipv4.ip_forward=1 per passare traffico tra interfacce.

Linux: sudo sysctl -w net.ipv4.ip_forward=1 (persistere in /etc/sysctl.conf).
pfSense: abilitato di default.
Mikrotik: abilitato di default.

2. Regole firewall LAN

Il tuo router deve permettere traffico dall'interfaccia WG verso la tua LAN OT.

pfSense: Firewall → Rules → WireGuard interface. Aggiungi regola Allow from any to LAN subnet.
OPNsense: uguale.
Mikrotik: verifica che non ci sia regola di drop in /ip firewall filter per pacchetti in-interface=rela-vpn.

3. Il PLC non accetta connessioni fuori dalla sua LAN

Alcuni PLC hanno whitelist interna di IP. L'origine del TCP dal nostro worker è 10.200.X.2 (l'IP assegnato nella tua subnet VPN). Assicurati che il PLC non blocchi quell'IP.

Troubleshooting Layer 5-6: Modbus risponde in locale ma Rela AI no

1. Il worker non ha Direct VPC Egress abilitato

Se il tuo account ha appena attivato la connettività VPN, può esserci un ritardo di qualche minuto finché Cloud Run non si ridispiega. Aspetta 5 minuti e riprova.

2. Deployment mode sbagliato

Se il PLC è dietro la tua VPN, la fonte deve avere deployment_mode = cloud_direct.
Se usi rela-ai-edge invece della VPN, deve essere deployment_mode = edge + assegnare edge_gateway_id.

3. Unit ID sbagliato

Verifica nel PLC quale slave ID risponde (1 è default ma alcuni PLC arrivano con 2 o 255).

4. Data type / byte order

Se la connessione funziona ma il valore sembra assurdo, è problema di decodifica. Vedi il troubleshooting nella guida Modbus.

Checklist rapido da stampare

[ ] wg show mostra latest handshake < 2 min
[ ] ip route get <IP_subnet_assegnata> → dev wgX
[ ] ping dal router al PLC locale funziona
[ ] nc -zv <PLC_IP> 502 → succeeded
[ ] read_holding_registers dal router restituisce valore reale
[ ] Dashboard: Test connection con rtt_ms < 500 + sample_values corretti
[ ] Inbox: eventi con event_type=<nome_registro> appaiono entro 2 min

Se tutti i 7 check sono ✓, il tuo tunnel è pronto per produzione. Passa il testimone al team di stabilimento perché inizi a configurare allarmi e regole.

Se qualche check fallisce, hai l'angolo esatto da controllare — usa il troubleshooting corrispondente sopra.

Come testare che la VPN funzioni

In questa pagina