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

# Agent-Tunnel

Konfigurieren Sie Agent Tunnel, um Devolutions Gateway-Sitzungen über Devolutions Agent zu leiten und Maschinen in privaten Netzwerken ohne direkte Konnektivität zu erreichen.

{% hint style="warning" %}
**Experimentell** (Devolutions Gateway und Agent **2026.2.0+**). Testen Sie vor einer breiten Einführung.
{% endhint %}

Agent Tunnel ermöglicht Devolutions Gateway den Zugriff auf Maschinen in einem privaten Netzwerk, zu dem es keine direkte Verbindung herstellen kann.

Sie installieren Devolutions Agent auf einer Maschine in diesem Netzwerk (einem Jump-Host oder Standortserver). Der Agent wählt sich nach außen zum Gateway und kündigt die IP-Bereiche und Domänen an, die er erreichen kann. Danach wird jede Sitzung, die Sie über das Gateway zu einem dieser Ziele öffnen, automatisch über den Agent geleitet. Für den Benutzer ändert sich nichts.

Diese Anleitung zeigt, wie Sie ein Gateway mit einem Agent verbinden und Traffic darüber leiten.

### Bevor Sie beginnen

* Devolutions Gateway **2026.2.0+** und Devolutions Agent **2026.2.0+**.
* Die Agent-Maschine kann das Gateway über **HTTPS** (zur Registrierung) und über **UDP auf Port 4433** (den Tunnel) erreichen.
* Auf dem Gateway/der Firewall: **eingehendes UDP 4433** von den Standorten zulassen, an denen Agents ausgeführt werden.
* Ein Devolutions Server-Konto, das das Gateway verwalten kann.

### Agent Tunnel auf dem Gateway aktivieren

`gateway.json` bearbeiten:

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

Setzen Sie `Hostname` auf die Adresse, über die Agents das Gateway erreichen, und starten Sie dann den Devolutions Gateway-Dienst neu.

### Registrierungszeichenfolge in Devolutions Server generieren

Öffnen Sie in Devolutions Server ***Administration*** – ***Devolutions Gateway***, wählen Sie Ihr Gateway aus und klicken Sie auf ***Agent Tunnel***.

Klicken Sie auf die Schaltfläche ***+***, um einen Agent hinzuzufügen.

Geben Sie einen ***Agentnamen*** und eine ***Lebensdauer*** ein und klicken Sie dann auf ***Generieren***.

Kopieren Sie die ***Registrierungszeichenfolge***.

{% hint style="warning" %}
Die Registrierungszeichenfolge ist ein einmaliges Geheimnis. Bewahren Sie sie sicher auf, und generieren Sie eine neue, falls sie abläuft, bevor Sie fertig sind.
{% endhint %}

### Den Agent auf der Standortmaschine installieren

Führen Sie das Devolutions Agent-Installationsprogramm auf der Maschine innerhalb des privaten Netzwerks aus.

Aktivieren Sie die Funktion ***Agent Tunnel***.

Fügen Sie die Registrierungszeichenfolge in ***Registrierungszeichenfolge*** ein.

Legen Sie die Routen fest, die dieser Agent erreichen soll:

* ***Subnetze ankündigen***: IP-Bereiche (zum Beispiel `10.10.0.0/24`). Lassen Sie das Feld leer, um lokale Subnetze automatisch zu erkennen.
* ***Domänen ankündigen***: DNS-Suffixe (zum Beispiel `*.example.com`).

Schließen Sie den Assistenten ab. Das Installationsprogramm registriert den Agent und testet die Verbindung; wenn es das Gateway nicht erreichen kann, schlägt die Einrichtung fehl, sodass Sie die Firewall gleich vor Ort korrigieren können.

### Überprüfen, ob der Agent online ist

Zurück im Dialogfeld ***Agent Tunnel*** von Devolutions Server sollte der Agent nun als ***Online*** mit seinen Subnetzen, Domänen und dem Zeitpunkt der letzten Sichtung angezeigt werden.

{% hint style="info" %}
Um einen Agent außer Betrieb zu nehmen, entfernen Sie ihn hier und deinstallieren Sie ihn auf der Maschine.
{% endhint %}

### Über das Gateway verbinden

Benutzer installieren nichts. Sie verbinden sich wie gewohnt über das Gateway, und dieses leitet automatisch über den Agent, wenn das Ziel übereinstimmt.

Öffnen Sie in Remote Desktop Manager eine Sitzung für einen Host innerhalb eines angekündigten Bereichs. Setzen Sie in ***VPN/Tunnel/Gateway*** den Typ auf ***Devolutions Gateway*** und wählen Sie das Gateway aus, bei dem der Agent registriert wurde.

Setzen Sie den ***Host*** auf das interne Ziel (zum Beispiel `10.10.0.20`).

Verbinden.

Die Sitzung wird über das Gateway und den Agent geöffnet.

### Fehlerbehebung

<table><thead><tr><th width="280">Problem</th><th>Prüfen</th></tr></thead><tbody><tr><td><strong>Registrierung schlägt während der Installation fehl</strong></td><td>Registrierungszeichenfolge abgelaufen oder falsch eingegeben; Gateway über HTTPS nicht erreichbar; Agent Tunnel auf dem Gateway nicht aktiviert</td></tr><tr><td><strong>Verbindungstest schlägt am Ende der Installation fehl</strong></td><td>UDP-Port 4433 zum Gateway ist blockiert oder der <code>Hostname</code> des Gateways ist falsch</td></tr><tr><td><strong>Agent ist online, die Sitzung verbindet sich aber weiterhin direkt</strong></td><td>Das Ziel liegt nicht innerhalb eines angekündigten Subnetzes oder einer angekündigten Domäne; das Ziel ist nur über IPv6 erreichbar (verwenden Sie stattdessen eine Domäne)</td></tr><tr><td><strong>Agent wird als Offline angezeigt</strong></td><td>Starten Sie den Devolutions Agent-Dienst auf der Standortmaschine neu</td></tr></tbody></table>

So testen Sie den Tunnel von der Agent-Maschine aus:

```bat
DevolutionsAgent.exe probe
```

### Funktionsweise

Die obigen Schritte sind alles, was Sie zum Leiten von Traffic benötigen. Dieser Abschnitt ist für Leser, die die Details hinter den Kulissen wissen möchten.

#### Was ist eine „Ankündigung“ und welche Topologie erfordert sie?

Wenn ein Agent eine Verbindung herstellt, teilt er dem Gateway mit, welche IPv4-Subnetze (zum Beispiel `10.10.0.0/24`) und DNS-Domänensuffixe (zum Beispiel `*.example.com`) er erreichen kann. Diese Liste ist die *Ankündigung*. Der Agent sendet sie periodisch erneut, damit das Gateway immer das aktuelle Bild hat, und das Gateway führt eine Routentabelle pro verbundenem Agent.

Topologie:

* Der Agent stellt eine einzige ausgehende Verbindung zum Gateway her (UDP 4433). Am Standort benötigt nichts eine öffentliche IP oder eine eingehende Firewallregel, weshalb es hinter NAT funktioniert.
* Da das Gateway der Treffpunkt für jede Verbindung ist, muss es an einem Ort stehen, der sowohl für die Agents *als auch* für die Clients von Devolutions Server und Remote Desktop Manager erreichbar ist. Wenn eine der beiden Seiten das Gateway nicht erreichen kann, kann das Routing über einen Agent nicht funktionieren.
* Das Gateway benötigt eingehendes UDP 4433, erreichbar von den Agent-Standorten, sowie seinen normalen HTTPS-Listener für die Registrierung.
* Der Agent muss über gewöhnliche Netzwerkerreichbarkeit (Routing + DNS) zu den Zielen verfügen, die er ankündigt. Der Agent ist praktisch der „letzte Hop“ im privaten Netzwerk.

Ein Gateway kann viele Agents aufnehmen; an einem Standort kann zur Redundanz mehr als ein Agent betrieben werden.

#### Wo werden Domänen und IP-Adressen aufgelöst?

Es passieren zwei verschiedene Dinge:

1. **Routenabgleich (auf dem Gateway).** Wenn eine Sitzung gestartet wird, nimmt das Gateway das Ziel aus der Sitzung und vergleicht es mit der Ankündigung jedes verbundenen Agents:
   * Ein IP-Ziel wird mit den angekündigten Subnetzen abgeglichen.
   * Ein Hostname-Ziel wird mit den angekündigten Domänen abgeglichen (Suffixabgleich). Das Gateway führt hier *keine* DNS-Abfrage durch. Es vergleicht Namen.
   * Die spezifischste Übereinstimmung gewinnt (eine Subnetz-Übereinstimmung rangiert vor einer Domänen-Übereinstimmung; ein längeres Domänensuffix rangiert vor einem kürzeren).
   * Wenn zwei Online-Agents dieselbe Route ankündigen (eine gleich spezifische Übereinstimmung), bevorzugt das Gateway denjenigen, dessen Ankündigung zuletzt eingetroffen ist, sodass der neueste praktisch gewinnt. Er wird zuerst versucht, und das Gateway greift nur dann auf die anderen zurück, wenn dieser Agent die Verbindung nicht herstellen kann. Das bedeutet, es gibt kein festes „primär/Sekundär“; der Agent, der sich zuletzt (wieder)verbunden oder seine Routen aktualisiert hat, übernimmt.
   * Wenn nichts übereinstimmt, verbindet sich das Gateway direkt, genau wie vor der Existenz von Agent Tunnel.
2. **Tatsächliche Namensauflösung (auf dem Agent).** Das Gateway übergibt das Ziel (Host und Port) an den ausgewählten Agent, und der Agent löst den DNS-Namen auf und öffnet die Verbindung von innerhalb des privaten Netzwerks. Genau darum geht es: Das eigene DNS des Standorts löst Namen auf, die das Gateway nicht sehen kann. Das bedeutet auch, dass Sie Domänen für Hosts ankündigen, die nur im internen DNS existieren, und Subnetze für Hosts, die Sie über die IP-Adresse adressieren.

Da der Subnetzabgleich heute auf IPv4 basiert, erreichen Sie einen ausschließlich über IPv6 erreichbaren Host stattdessen, indem Sie eine Domäne ankündigen, die ihn abdeckt.

#### Wie wird die Sicherheit gewährleistet?

* **Die Registrierung** verwendet eine kurzlebige Registrierungszeichenfolge, die in Devolutions Server generiert wird. Sie ist nur eine Bootstrap-Anmeldeinformation und nicht die langfristige Vertrauensbasis.
* Der Agent generiert sein eigenes Schlüsselpaar lokal und sendet nur eine Zertifikatsanforderung an das Gateway. Der private Schlüssel verlässt die Agent-Maschine nie.
* Der Tunnel ist QUIC mit gegenseitigem TLS: Das Gateway authentifiziert den Agent über sein Zertifikat, und der Agent authentifiziert das Gateway. Darüber hinaus pinnt der Agent die exakte Gateway-Identität, die er bei der Registrierung gesehen hat, sodass eine fehlerhaft ausgestellte oder betrügerische Zertifizierungsstelle das Gateway dennoch nicht imitieren kann.
* Der Agent erzwingt seine eigene Zulassungsliste: Er weigert sich, eine Verbindung zu etwas außerhalb der von ihm angekündigten Subnetze und Domänen zu öffnen, selbst wenn er dazu aufgefordert wird. Die Ankündigung ist sowohl ein Routing-Hinweis als auch eine harte Grenze.
* Die Benutzerautorisierung bleibt unverändert. Jede Sitzung benötigt weiterhin eine normale Gateway-Autorisierung von Devolutions Server, Devolutions Cloud oder PAM. Agent Tunnel ändert nur, *wie* das Gateway das Ziel erreicht, niemals, *wer* sich verbinden darf.

#### Einige weitere Dinge, die Power-User fragen

* **Warum QUIC/UDP anstelle von TCP?** Eine ausgehende Verbindung multiplext viele gleichzeitige Sitzungen und übersteht kurze Netzwerkänderungen (Roaming, VPN-Aussetzer), ohne jede Sitzung zu trennen.
* **Kann ich einen bestimmten Agent erzwingen?** Ja. Eine Sitzung kann an einen Agent gepinnt werden; wenn sie gepinnt ist, muss sie diesen Agent verwenden und schlägt fehl, anstatt stillschweigend auf eine direkte Verbindung zurückzufallen. Das bedeutet, ein Pin kann nicht verwendet werden, um den vorgesehenen Pfad zu umgehen.
* **Kann ich Agent Tunnel für eine einzelne Sitzung deaktivieren?** Heute nicht. Es gibt kein Opt-out pro Sitzung: Das Gateway entscheidet den Pfad ausschließlich anhand des Ziels. Wenn ein Ziel mit den angekündigten Routen eines Online-Agents übereinstimmt, läuft die Sitzung über diesen Agent. Um eine direkte Verbindung zu erzwingen, darf das Ziel mit keiner angekündigten Route übereinstimmen (oder der Agent muss offline bzw. entfernt sein).
* **Was passiert, wenn der Agent ausfällt?** Er wird kurz nachdem er keine Updates mehr sendet als Offline markiert, und das Gateway leitet nicht mehr über ihn (und fällt auf eine direkte Verbindung oder einen anderen passenden Agent zurück). Der Agent verbindet sich von selbst mit Backoff wieder, sobald das Netzwerk wiederhergestellt ist.
* **Muss ich Zertifikate erneuern?** Nein. Der Agent erneuert sein Zertifikat automatisch, bevor es abläuft, solange der Dienst weiterläuft und sich erneut verbindet.
* **Ist der Traffic für das Gateway weiterhin sichtbar?** Ja. Das Gateway ist weiterhin das Relay und terminiert die Sitzung, sodass Ihre bestehenden Gateway-Richtlinien gelten. Der Agent-Hop dient nur dem Transport.
* **Wo befinden sich die Dateien des Agents?** Unter `%ProgramData%\Devolutions\Agent\` auf Windows (Zertifikate im Unterordner `certs`). Normalerweise fassen Sie diese nie an, da das Installationsprogramm und Devolutions Server sie verwalten.


---

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