> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/gateway/it/knowledge-base/knowledge-base-articles/agent-tunnel.md).

# Agent tunnel

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

{% hint style="warning" %}
**Sperimentale** (Devolutions Gateway e Agent **2026.2.0+**). Da testare prima di un'implementazione su larga scala.
{% endhint %}

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

Installi 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. In seguito, qualsiasi sessione che apre 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 Devolutions Server 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`

```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 una stringa di registrazione in Devolutions Server

In Devolutions Server, 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***.

{% hint style="warning" %}
La stringa di registrazione è un segreto monouso. La conservi al sicuro e ne generi una nuova se scade prima che abbia finito.
{% endhint %}

### 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 la stringa 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 Devolutions Server, l'agent dovrebbe ora risultare ***Online*** con le sue subnet, i domini e l'ora dell'ultimo contatto.

{% hint style="info" %}
Per dismettere un agent, lo rimuova da qui e lo disinstalli sulla macchina.
{% endhint %}

### 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 Remote Desktop Manager, 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

<table><thead><tr><th width="280">Problema</th><th>Verifica</th></tr></thead><tbody><tr><td><strong>La registrazione non riesce durante l'installazione</strong></td><td>Stringa di registrazione scaduta o digitata in modo errato; gateway non raggiungibile tramite HTTPS; Agent Tunnel non abilitato sul gateway</td></tr><tr><td><strong>Il test di connessione non riesce alla fine dell'installazione</strong></td><td>La porta UDP 4433 verso il gateway è bloccata, oppure il <code>Hostname</code> del gateway è errato</td></tr><tr><td><strong>L'agent è Online ma la sessione si connette ancora direttamente</strong></td><td>Il target non si trova all'interno di una subnet o di un dominio annunciato; il target è solo IPv6 (usi invece un dominio)</td></tr><tr><td><strong>L'agent è visualizzato come Offline</strong></td><td>Riavvii il servizio Devolutions Agent sulla macchina del sito</td></tr></tbody></table>

Per testare il tunnel dalla macchina dell'agent:

```bat
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, ed è per questo che funziona dietro NAT.
* Poiché il gateway è il punto d'incontro di ogni connessione, deve trovarsi in una posizione raggiungibile sia dagli agent *sia* dai client di Devolutions Server e Remote Desktop Manager. 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ù di recente, quindi di fatto vince 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/secondario" 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 una stringa di registrazione di breve durata generata in Devolutions Server. È solo una credenziale di bootstrap, non la fiducia 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 Devolutions Server, Devolutions Cloud o PAM. Agent Tunnel cambia solo *come* 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 agent; quando è associata, deve usare quell'agent e fallisce anziché ricorrere silenziosamente a una connessione diretta. Ciò significa che un'associazione non può essere usata per aggirare 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 toccarli, poiché il programma di installazione e Devolutions Server li gestisce.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.devolutions.net/gateway/it/knowledge-base/knowledge-base-articles/agent-tunnel.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.