# Benannte Tunnel

Standardmäßig verwendet Termbridge die kontolosen Cloudflare Quick Tunnels (`trycloudflare.com`). Sie sind praktisch, können bei intensiver Nutzung aber einer Ratenbegrenzung unterliegen.

Wenn du Termbridge häufig verwendest, richte mit deinem Cloudflare-Konto einen benannten Tunnel ein.

## Warum einen benannten Tunnel verwenden?

- **Keine Ratenbegrenzungen**: Bei intensiver Nutzung können Quick Tunnels Fehler 429 zurückgeben
- **Konsistente URL**: Erhalte eine stabile Subdomain statt zufälliger Zeichenfolgen
- **Eigene Domain**: Verwende eine eigene Domain wie `term.example.com`
- **Höhere Zuverlässigkeit**: Benannte Tunnel sind bei langen Sitzungen stabiler

## Einrichtung

### 1. Cloudflare-Konto erstellen

Registriere dich unter [cloudflare.com](https://cloudflare.com), falls du noch kein Konto hast.

### 2. Tunnel in Zero Trust erstellen

1. Öffne [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)
2. Gehe zu **Networks** → **Tunnels**
3. Klicke auf **Create a tunnel**
4. Wähle **Cloudflared** als Connector
5. Benenne deinen Tunnel (e.g, `termbridge`)
6. Kopiere das Tunnel-Token

### 3. Öffentlichen Hostnamen hinzufügen

1. Öffne in den Tunneleinstellungen **Public Hostname**
2. Füge einen Hostnamen hinzu, der auf `http://localhost:8080` (oder deinen gewünschten Port) verweist
3. Verwende eine Subdomain wie `term.example.com`

### 4. Termbridge mit deinem Token ausführen

```bash
termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com
```

Oder verwende Umgebungsvariablen:

```bash
export TERMBRIDGE_TUNNEL_TOKEN=<TOKEN>
export TERMBRIDGE_TUNNEL_URL=https://term.example.com

termbridge --port 8080
```

> **Hinweis**
> Bei benannten Tunneln ist die Option `--port` erforderlich, da der Hostname auf einen bestimmten Port verweist.


## Konfigurationsoptionen

| Option | Umgebungsvariable | Beschreibung |
|------|---------------------|-------------|
| `--port <port>` | - | Lokaler Port (bei benannten Tunneln erforderlich) |
| `--tunnel-token <token>` | `TERMBRIDGE_TUNNEL_TOKEN` | Dein Tunnel-Token |
| `--tunnel-url <url>` | `TERMBRIDGE_TUNNEL_URL` | Dein öffentlicher Hostname URL |

## Tunnel vollständig deaktivieren

Wenn du einen eigenen Reverse-Proxy oder eine öffentliche URL hast:

```bash
termbridge --no-tunnel --public-url https://your-server.com
```

Oder:

```bash
export TERMBRIDGE_TUNNEL=none
export TERMBRIDGE_PUBLIC_URL=https://your-server.com

termbridge
```

Termbridge überspringt den Tunnelstart und verwendet deine angegebene URL für den QR-Code.

## Fehlerbehebung

### „429 Too Many Requests“

Das bedeutet, dass Quick Tunnels einer Ratenbegrenzung unterliegen. Mögliche Lösungen:

1. Warte ein paar Minuten und versuche es erneut
2. Beende alle veralteten `cloudflared`-Prozesse: `pkill cloudflared`
3. Wechsle zu einem benannten Tunnel (empfohlen)

### Tunnel startet, aber URL funktioniert nicht

- Überprüfe, ob der Hostname in Cloudflare mit `--tunnel-url` übereinstimmt
- Prüfe, ob der Port in Cloudflare mit `--port` übereinstimmt
- Stelle sicher, dass cloudflared aktuell ist: `cloudflared update`

### Verbindung zum benannten Tunnel schlägt fehl

- Überprüfe, ob dein Token korrekt ist
- Sieh im Dashboard von Cloudflare Zero Trust nach Fehlern
- Führe `cloudflared tunnel run <TOKEN>` direkt aus, um Fehlermeldungen zu sehen