Tunnel dell'Agent

Configuri Agent Tunnel per instradare le sessioni di Devolutions Gateway attraverso Devolutions Agent, raggiungendo le macchine della rete privata senza connettività diretta.

Sperimentale (Devolutions Gateway e Agent 2026.2.0+). Da testare prima di un'implementazione su larga scala.

Agent Tunnel consente a Devolutions Gateway di raggiungere macchine su una rete privata a cui non può connettersi direttamente.

Si installa Devolutions Agent su una macchina all'interno di quella rete (un jump host o un server di sito). L'agent contatta il gateway verso l'esterno e annuncia gli intervalli IP e i domini che può raggiungere. Da quel momento, qualsiasi sessione aperta tramite il gateway verso uno di quei target viene instradata automaticamente attraverso l'agent — per l'utente non cambia nulla.

Questa guida mostra come collegare un gateway a un agent e instradare il traffico attraverso di esso.

Prima di iniziare

• Devolutions Gateway 2026.2.0+ e Devolutions Agent 2026.2.0+.
• La macchina dell'agent può raggiungere il gateway tramite HTTPS (per la registrazione) e tramite UDP sulla porta 4433 (il tunnel).
• Sul gateway/firewall: consenta il traffico UDP 4433 in entrata dai siti in cui vengono eseguiti gli agent.
• Un account DVLS che può gestire il gateway.

Abilitare Agent Tunnel sul gateway

Modifichi gateway.json:

• Windows: %ProgramData%\Devolutions\Gateway\gateway.json
• Linux: /etc/devolutions-gateway/gateway.json
• macOS: /Library/Application Support/devolutions-gateway/gateway.json

{
  "Hostname": "gateway.contoso.com",
  "AgentTunnel": {
    "Enabled": true,
    "ListenPort": 4433
  },
  "__debug__": {
    "enable_unstable": true
  }
}

Imposti Hostname sull'indirizzo che gli agent usano per raggiungere il gateway, poi riavvii il servizio Devolutions Gateway.

Generare un token di registrazione in DVLS

In DVLS, apra Administration – Devolutions Gateway, selezioni il suo gateway e clicchi su Agent Tunnel.

Clicchi sul pulsante + per aggiungere un agent.

Inserisca un Agent Name e una Lifetime, poi clicchi su Generate.

Copi la Enrollment string.

La stringa di registrazione è un segreto monouso — la conservi in modo sicuro e ne generi una nuova se scade prima di aver terminato.

Installare l'agent sulla macchina del sito

Esegua il programma di installazione di Devolutions Agent sulla macchina all'interno della rete privata.

Abiliti la funzionalità Agent Tunnel.

Incolli il token di registrazione in Enrollment String.

Imposti le route che questo agent deve raggiungere:

• Advertise Subnets — intervalli IP (per esempio 10.10.0.0/24). Lasci vuoto per rilevare automaticamente le subnet locali.
• Advertise Domains — suffissi DNS (per esempio *.example.com).

Completi la procedura guidata. Il programma di installazione registra l'agent e testa la connessione; se non riesce a raggiungere il gateway, la configurazione non va a buon fine, così può correggere subito il firewall.

Verificare che l'agent sia online

Di nuovo nella finestra di dialogo Agent Tunnel di DVLS, l'agent dovrebbe ora essere visualizzato come Online con le sue subnet, i domini e l'ora dell'ultimo contatto.

Per dismettere un agent, lo rimuova da qui e lo disinstalli sulla macchina.

Connettersi tramite il gateway

Gli utenti non installano nulla. Si connettono tramite il gateway come sempre, e questo instrada automaticamente attraverso l'agent quando la destinazione corrisponde.

In RDM, apra una sessione per un host all'interno di un intervallo annunciato. In VPN/tunnel/gateway, imposti il tipo su Devolutions Gateway e scelga il gateway con cui l'agent si è registrato.

Imposti l'Host sul target interno (per esempio 10.10.0.20).

Si connetta.

La sessione si apre tramite il gateway e l'agent.

Risoluzione dei problemi

Problema	Verifica
La registrazione non riesce durante l'installazione	Token scaduto o digitato in modo errato; gateway non raggiungibile tramite HTTPS; Agent Tunnel non abilitato sul gateway
Il test di connessione non riesce alla fine dell'installazione	La porta UDP 4433 verso il gateway è bloccata, oppure il Hostname del gateway è errato
L'agent è Online ma la sessione si connette ancora direttamente	Il target non si trova all'interno di una subnet o di un dominio annunciato; il target è solo IPv6 (usi invece un dominio)
L'agent è visualizzato come Offline	Riavvii il servizio Devolutions Agent sulla macchina del sito

Per testare il tunnel dalla macchina dell'agent:

DevolutionsAgent.exe probe

Come funziona

I passaggi precedenti sono tutto ciò che serve per instradare il traffico. Questa sezione è per i lettori che desiderano conoscere i dettagli dietro le quinte.

Che cos'è l'"annuncio" e quale topologia richiede?

Quando un agent si connette, comunica al gateway quali subnet IPv4 (per esempio 10.10.0.0/24) e quali suffissi di dominio DNS (per esempio *.example.com) può raggiungere. Quell'elenco è l'annuncio. L'agent lo invia di nuovo periodicamente affinché il gateway abbia sempre il quadro aggiornato, e il gateway mantiene una tabella di route per ogni agent connesso.

Topologia:

• L'agent stabilisce una singola connessione in uscita verso il gateway (UDP 4433). Nel sito non serve alcun IP pubblico né alcuna regola firewall in entrata — per questo funziona dietro NAT.
• Poiché il gateway è il punto d'incontro per ogni connessione, deve trovarsi in una posizione raggiungibile sia dagli agent sia dai client DVLS/RDM. Se uno dei due lati non riesce a raggiungere il gateway, l'instradamento attraverso un agent non può funzionare.
• Il gateway richiede che la porta UDP 4433 in entrata sia raggiungibile dai siti degli agent, oltre al suo normale listener HTTPS per la registrazione.
• L'agent deve avere una normale raggiungibilità di rete (routing + DNS) verso i target che annuncia. L'agent è di fatto l'"ultimo hop" sulla rete privata.

Un gateway può contenere molti agent; un sito può eseguire più di un agent per ridondanza.

Dove vengono risolti domini e IP?

Succedono due cose diverse:

1. Corrispondenza delle route (sul gateway). Quando una sessione viene avviata, il gateway prende il target dalla sessione e lo confronta con l'annuncio di ogni agent connesso:

   • Un target IP viene confrontato con le subnet annunciate.
   • Un target hostname viene confrontato con i domini annunciati (corrispondenza per suffisso). Qui il gateway non esegue una ricerca DNS — confronta i nomi.
   • Vince la corrispondenza più specifica (una corrispondenza di subnet prevale su una corrispondenza di dominio; un suffisso di dominio più lungo prevale su uno più corto).
   • Quando due agent online annunciano la stessa route (una corrispondenza altrettanto specifica), il gateway preferisce quello il cui annuncio è arrivato più recentemente — vince di fatto il più recente. Viene provato per primo, e il gateway passa agli altri solo se quell'agent non riesce a completare la connessione. Ciò significa che non esiste un "primario/di backup" fisso: prende il controllo l'agent che si è (ri)connesso o ha aggiornato le sue route per ultimo.
   • Se non c'è alcuna corrispondenza, il gateway si connette direttamente, esattamente come faceva prima dell'esistenza di Agent Tunnel.
2. Risoluzione effettiva dei nomi (sull'agent). Il gateway passa il target (host e porta) all'agent scelto, e l'agent risolve il nome DNS e apre la connessione dall'interno della rete privata. Questo è tutto il senso dell'operazione: il DNS del sito risolve nomi che il gateway non può vedere. Ciò significa anche che si annunciano domini per gli host che esistono solo nel DNS interno e subnet per gli host che si indirizzano tramite IP.

Poiché oggi la corrispondenza delle subnet è basata su IPv4, per raggiungere un host solo IPv6 annunci invece un dominio che lo includa.

Come viene garantita la sicurezza?

• La registrazione usa un token di breve durata generato in DVLS. È solo una credenziale di bootstrap — non è il trust a lungo termine.
• L'agent genera localmente la propria coppia di chiavi e invia al gateway soltanto una richiesta di certificato. La chiave privata non lascia mai la macchina dell'agent.
• Il tunnel è QUIC con TLS mutuo: il gateway autentica l'agent tramite il suo certificato e l'agent autentica il gateway. Inoltre, l'agent applica il pinning dell'identità esatta del gateway rilevata durante la registrazione, così un'autorità di certificazione compromessa o che ha emesso certificati in modo errato non può comunque impersonare il gateway.
• L'agent applica la propria lista di elementi consentiti: rifiuta di aprire una connessione verso qualsiasi cosa al di fuori delle subnet e dei domini che annuncia, anche se richiesto. L'annuncio è al tempo stesso un suggerimento di instradamento e un confine rigido.
• L'autorizzazione degli utenti non cambia. Ogni sessione richiede comunque una normale autorizzazione del gateway da DVLS/Hub/PAM. Agent Tunnel cambia solo il modo in cui il gateway raggiunge il target, mai chi è autorizzato a connettersi.

Altre cose che chiedono gli utenti esperti

• Perché QUIC/UDP invece di TCP? Una singola connessione in uscita multiplexa molte sessioni simultanee e sopravvive a brevi cambiamenti di rete (roaming, interruzioni della VPN) senza far cadere tutte le sessioni.
• Posso forzare un agent specifico? Sì. Una sessione può essere associata a un solo agent; quando è associata, deve usare quell'agent e fallirà anziché ricorrere silenziosamente a una connessione diretta — quindi un'associazione non può essere usata per bypassare il percorso previsto.
• Posso disattivare Agent Tunnel per una singola sessione? Non oggi. Non esiste un'esclusione per singola sessione: il gateway decide il percorso unicamente in base alla destinazione. Se un target corrisponde alle route annunciate da un agent online, la sessione passa attraverso quell'agent. Per forzare una connessione diretta, la destinazione non deve corrispondere ad alcuna route annunciata (oppure l'agent deve essere offline/rimosso).
• Cosa succede se l'agent si arresta? Viene contrassegnato come Offline poco dopo aver smesso di inviare aggiornamenti, e il gateway interrompe l'instradamento verso di esso (ricorrendo alla connessione diretta o a un altro agent corrispondente). L'agent si riconnette da solo con backoff quando la rete si ripristina.
• Devo rinnovare i certificati? No. L'agent rinnova automaticamente il proprio certificato prima della scadenza, purché il servizio continui a essere in esecuzione e a riconnettersi.
• Il traffico è ancora visibile al gateway? Sì. Il gateway è ancora il relay e termina la sessione, quindi si applicano le policy del gateway esistenti. L'hop dell'agent è solo di trasporto.
• Dove si trovano i file dell'agent? In %ProgramData%\Devolutions\Agent\ su Windows (i certificati nella sottocartella certs). Normalmente non è necessario intervenire su questi file — il programma di installazione e DVLS li gestiscono.