> 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/fr/knowledge-base/knowledge-base-articles/agent-tunnel.md).

# Agent tunnel

Configurez Agent Tunnel pour acheminer les sessions de Devolutions Gateway par Devolutions Agent, afin de joindre les machines d'un réseau privé sans connectivité directe.

{% hint style="warning" %}
**Expérimental** (Devolutions Gateway et Agent **2026.2.0+**). Testez avant un déploiement à grande échelle.
{% endhint %}

Agent Tunnel permet à Devolutions Gateway de joindre des machines sur un réseau privé auquel il ne peut pas se connecter directement.

Vous installez Devolutions Agent sur une machine à l'intérieur de ce réseau (un hôte Jump ou un serveur de site). L'agent compose vers l'extérieur vers la passerelle et annonce les plages d'adresses IP et les domaines qu'il peut joindre. Ensuite, toute session que vous ouvrez par la passerelle vers l'une de ces cibles est acheminée automatiquement par l'agent. Rien ne change pour l'utilisateur.

Ce guide montre comment connecter une passerelle à un agent et acheminer le trafic par celui-ci.

### Avant de commencer

* Devolutions Gateway **2026.2.0+** et Devolutions Agent **2026.2.0+**.
* La machine de l'agent peut joindre la passerelle par **HTTPS** (pour s'inscrire) et par **UDP sur le port 4433** (le tunnel).
* Sur la passerelle/le pare-feu : autorisez le **UDP 4433 entrant** provenant des sites où les agents s'exécutent.
* Un compte Devolutions Server pouvant gérer la passerelle.

### Activer Agent Tunnel sur la passerelle

Modifiez `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
  }
}
```

Réglez `Hostname` à l'adresse que les agents utilisent pour joindre la passerelle, puis redémarrez le service Devolutions Gateway.

### Générer une chaîne d'inscription dans Devolutions Server

Dans Devolutions Server, ouvrez ***Administration*** – ***Devolutions Gateway***, sélectionnez votre passerelle, puis cliquez sur ***Agent Tunnel***.

Cliquez sur le bouton ***+*** pour ajouter un agent.

Saisissez un ***Nom d'agent*** et une ***Durée de vie***, puis cliquez sur ***Générer***.

Copiez la ***Chaîne d'inscription***.

{% hint style="warning" %}
La chaîne d'inscription est un secret à usage unique. Conservez-la en sécurité, et générez-en une nouvelle si elle expire avant que vous ayez terminé.
{% endhint %}

### Installer l'agent sur la machine du site

Exécutez le programme d'installation de Devolutions Agent sur la machine située à l'intérieur du réseau privé.

Activez la fonctionnalité ***Agent Tunnel***.

Collez la chaîne d'inscription dans ***Chaîne d'inscription***.

Définissez les routes que cet agent doit joindre :

* ***Annoncer les sous-réseaux***: plages d'adresses IP (par exemple `10.10.0.0/24`). Laissez vide pour détecter automatiquement les sous-réseaux locaux.
* ***Annoncer les domaines***: suffixes DNS (par exemple `*.example.com`).

Terminez l'assistant. Le programme d'installation inscrit l'agent et teste la connexion; s'il ne peut pas joindre la passerelle, l'installation échoue afin que vous puissiez corriger le pare-feu sur-le-champ.

### Confirmer que l'agent est en ligne

De retour dans le dialogue ***Agent Tunnel*** de Devolutions Server, l'agent devrait maintenant afficher ***En ligne*** avec ses sous-réseaux, ses domaines et l'heure de dernière activité.

{% hint style="info" %}
Pour retirer un agent, supprimez-le ici et désinstallez-le sur la machine.
{% endhint %}

### Se connecter via la passerelle

Les utilisateurs n'installent rien. Ils se connectent via la passerelle comme d'habitude, et celle-ci achemine automatiquement le trafic par l'agent lorsque la destination correspond.

Dans Remote Desktop Manager, ouvrez une session pour un hôte situé dans une plage annoncée. Dans ***VPN/tunnel/passerelle***, réglez le type sur ***Devolutions Gateway*** et choisissez la passerelle auprès de laquelle l'agent s'est inscrit.

Réglez le champ ***Hôte*** à la cible interne (par exemple `10.10.0.20`).

Connectez-vous.

La session s'ouvre via la passerelle et l'agent.

### Dépannage

<table><thead><tr><th width="280">Problème</th><th>Vérification</th></tr></thead><tbody><tr><td><strong>L'inscription échoue pendant l'installation</strong></td><td>Chaîne d'inscription expirée ou mal saisie; passerelle inaccessible en HTTPS; Agent Tunnel non activé sur la passerelle</td></tr><tr><td><strong>Le test de connexion échoue à la fin de l'installation</strong></td><td>Le port UDP 4433 vers la passerelle est bloqué, ou le <code>Hostname</code> de la passerelle est incorrect</td></tr><tr><td><strong>L'agent est en ligne, mais la session se connecte toujours directement</strong></td><td>La cible ne se trouve pas dans un sous-réseau ou un domaine annoncé; la cible est uniquement en IPv6 (utilisez plutôt un domaine)</td></tr><tr><td><strong>L'agent affiche Hors ligne</strong></td><td>Redémarrez le service Devolutions Agent sur la machine du site</td></tr></tbody></table>

Pour tester le tunnel à partir de la machine de l'agent :

```bat
DevolutionsAgent.exe probe
```

### Fonctionnement

Les étapes ci-dessus sont tout ce dont vous avez besoin pour acheminer le trafic. Cette section est destinée aux lecteurs qui veulent connaître les détails en coulisses.

#### Qu'est-ce que l'« annonce », et quelle topologie exige-t-elle?

Lorsqu'un agent se connecte, il indique à la passerelle quels sous-réseaux IPv4 (par exemple `10.10.0.0/24`) et quels suffixes de domaine DNS (par exemple `*.example.com`) il peut joindre. Cette liste constitue l'*annonce*. L'agent la renvoie périodiquement afin que la passerelle ait toujours le portrait à jour, et la passerelle conserve une table de routage par agent connecté.

Topologie :

* L'agent établit une seule connexion sortante vers la passerelle (UDP 4433). Rien sur le site n'a besoin d'une adresse IP publique ni d'une règle de pare-feu entrante, ce qui explique pourquoi cela fonctionne derrière un NAT.
* Puisque la passerelle est le point de rencontre de chaque connexion, elle doit se trouver à un endroit accessible à la fois par les agents *et* par les clients Devolutions Server et Remote Desktop Manager. Si l'un ou l'autre côté ne peut pas joindre la passerelle, l'acheminement par un agent ne peut pas fonctionner.
* La passerelle doit être accessible en UDP 4433 entrant depuis les sites des agents, en plus de son écouteur HTTPS normal pour l'inscription.
* L'agent doit avoir une accessibilité réseau ordinaire (routage + DNS) vers les cibles qu'il annonce. L'agent est en réalité le « dernier saut » sur le réseau privé.

Une passerelle peut héberger plusieurs agents; un site peut exécuter plus d'un agent pour la redondance.

#### Où les domaines et les IP sont-ils résolus?

Deux choses différentes se produisent :

1. **Correspondance de route (sur la passerelle).** Lorsqu'une session démarre, la passerelle prend la cible de la session et la compare à l'annonce de chaque agent connecté :
   * Une cible IP est comparée aux sous-réseaux annoncés.
   * Une cible de type nom d'hôte est comparée aux domaines annoncés (correspondance de suffixe). La passerelle n'effectue *pas* de recherche DNS ici. Elle compare des noms.
   * La correspondance la plus spécifique gagne (une correspondance de sous-réseau prime sur une correspondance de domaine; un suffixe de domaine plus long prime sur un plus court).
   * Lorsque deux agents en ligne annoncent la même route (une correspondance de spécificité égale), la passerelle privilégie celui dont l'annonce est arrivée le plus récemment, de sorte que le plus récent l'emporte en pratique. Il est essayé en premier, et la passerelle se rabat sur les autres seulement si cet agent ne peut pas établir la connexion. Cela signifie qu'il n'y a pas de « principal/secours » fixe; l'agent qui s'est (re)connecté ou qui a actualisé ses routes en dernier prend le relais.
   * Si rien ne correspond, la passerelle se connecte directement, exactement comme elle le faisait avant l'existence d'Agent Tunnel.
2. **Résolution de noms réelle (sur l'agent).** La passerelle transmet la cible (hôte et port) à l'agent choisi, et l'agent résout le nom DNS et ouvre la connexion depuis l'intérieur du réseau privé. C'est tout l'intérêt : le DNS propre au site résout des noms que la passerelle ne peut pas voir. Cela signifie aussi que vous annoncez des domaines pour les hôtes qui n'existent que dans le DNS interne, et des sous-réseaux pour les hôtes que vous adressez par IP.

Comme la correspondance de sous-réseau est aujourd'hui basée sur IPv4, joignez un hôte uniquement en IPv6 en annonçant plutôt un domaine qui le couvre.

#### Comment la sécurité est-elle assurée?

* **L'inscription** utilise une chaîne d'inscription de courte durée générée dans Devolutions Server. Il ne s'agit que d'un identifiant d'amorçage, et non de la confiance à long terme.
* L'agent génère sa propre biclé localement et n'envoie qu'une demande de certificat à la passerelle. La clé privée ne quitte jamais la machine de l'agent.
* Le tunnel est en QUIC avec TLS mutuel : la passerelle authentifie l'agent par son certificat, et l'agent authentifie la passerelle. En plus de cela, l'agent épingle l'identité exacte de la passerelle qu'il a vue lors de l'inscription, de sorte qu'une autorité de certification mal émise ou malveillante ne peut toujours pas se faire passer pour la passerelle.
* L'agent applique sa propre liste d'autorisation : il refuse d'ouvrir une connexion vers quoi que ce soit en dehors des sous-réseaux et des domaines qu'il annonce, même si on le lui demande. L'annonce est à la fois un indice de routage et une frontière stricte.
* L'autorisation des utilisateurs est inchangée. Chaque session nécessite toujours une autorisation de passerelle normale provenant de Devolutions Server, de Devolutions Cloud ou de la gestion des accès privilégiés. Agent Tunnel change seulement *comment* la passerelle joint la cible, jamais *qui* est autorisé à se connecter.

#### Quelques autres questions posées par les utilisateurs avancés

* **Pourquoi QUIC/UDP plutôt que TCP?** Une seule connexion sortante multiplexe de nombreuses sessions simultanées et survit à de brefs changements de réseau (itinérance, interruptions de VPN) sans interrompre toutes les sessions.
* **Puis-je forcer un agent précis?** Oui. Une session peut être épinglée à un agent; lorsqu'elle est épinglée, elle doit utiliser cet agent et elle échouera plutôt que de se rabattre silencieusement sur une connexion directe. Cela signifie qu'un épinglage ne peut pas servir à contourner le chemin prévu.
* **Puis-je désactiver Agent Tunnel pour une seule session?** Pas aujourd'hui. Il n'existe pas d'exclusion par session : la passerelle détermine le chemin uniquement à partir de la destination. Si une cible correspond aux routes annoncées d'un agent en ligne, la session passe par cet agent. Pour forcer une connexion directe, la destination ne doit correspondre à aucune route annoncée (ou l'agent doit être hors ligne ou retiré).
* **Que se passe-t-il si l'agent tombe en panne?** Il est marqué Hors ligne peu après avoir cessé d'envoyer des mises à jour, et la passerelle cesse d'y acheminer le trafic (se rabattant sur une connexion directe ou sur un autre agent correspondant). L'agent se reconnecte de lui-même avec un délai progressif lorsque le réseau est rétabli.
* **Dois-je renouveler les certificats?** Non. L'agent renouvelle automatiquement son certificat avant son expiration, tant que le service continue de fonctionner et de se reconnecter.
* **Le trafic est-il toujours visible pour la passerelle?** Oui. La passerelle demeure le relais et termine la session, de sorte que vos stratégies de passerelle existantes s'appliquent. Le saut par l'agent concerne uniquement le transport.
* **Où se trouvent les fichiers de l'agent?** Sous `%ProgramData%\Devolutions\Agent\` sur Windows (les certificats dans le sous-dossier `certs`). Vous n'y touchez normalement jamais, puisque le programme d'installation et Devolutions Server les gèrent.


---

# 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/fr/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.