# Tunnel con nome

Per impostazione predefinita, Termbridge usa i Quick Tunnel di Cloudflare senza account (`trycloudflare.com`). Sono comodi, ma un uso intenso può comportare limiti di frequenza.

Se usate spesso Termbridge, configurate un tunnel con nome associato al vostro account Cloudflare.

## Perché usare un tunnel con nome?

- **Nessun limite di frequenza**: con un uso intenso, i Quick Tunnel possono restituire errori 429
- **URL costante**: ottenete un sottodominio stabile invece di stringhe casuali
- **Dominio personalizzato**: usate un vostro dominio, ad esempio `term.example.com`
- **Maggiore affidabilità**: i tunnel con nome sono più stabili nelle sessioni lunghe

## Configurazione

### 1. Create un account Cloudflare

Iscrivetevi su [cloudflare.com](https://cloudflare.com) se non ne avete già uno.

### 2. Create un tunnel in Zero Trust

1. Andate su [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)
2. Andate a **Networks** → **Tunnels**
3. Fate clic su **Create a tunnel**
4. Scegliete **Cloudflared** come connettore
5. Assegnate un nome al tunnel (ad es. e.g, `termbridge`)
6. Copiate il token del tunnel

### 3. Aggiungete un hostname pubblico

1. Nelle impostazioni del tunnel, andate a **Public Hostname**
2. Aggiungete un hostname che punti a `http://localhost:8080` (o alla porta scelta)
3. Usate un sottodominio come `term.example.com`

### 4. Eseguite Termbridge con il vostro token

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

Oppure usate le variabili d'ambiente:

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

termbridge --port 8080
```

> **Nota**
> Il flag `--port` è obbligatorio con i tunnel con nome, perché l'hostname è configurato per puntare a una porta specifica.


## Opzioni di configurazione

| Flag | Variabile d'ambiente | Descrizione |
|------|---------------------|-------------|
| `--port <port>` | - | Porta locale (obbligatoria con i tunnel con nome) |
| `--tunnel-token <token>` | `TERMBRIDGE_TUNNEL_TOKEN` | Token del tunnel |
| `--tunnel-url <url>` | `TERMBRIDGE_TUNNEL_URL` | Hostname pubblico URL |

## Disattivare completamente il tunnel

Se avete un vostro reverse proxy o un URL pubblico:

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

Oppure:

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

termbridge
```

Termbridge non avvierà un tunnel e userà il vostro URL per il codice QR.

## Risoluzione dei problemi

### "429 Troppe richieste"

Significa che i Quick Tunnel sono soggetti a limiti di frequenza. Soluzioni:

1. Aspettate qualche minuto e riprovate
2. Terminate eventuali processi `cloudflared` rimasti attivi: `pkill cloudflared`
3. Passate a un tunnel con nome (consigliato)

### Il tunnel si avvia, ma URL non funziona

- Verificate che l'hostname in Cloudflare corrisponda a `--tunnel-url`
- Verificate che la porta in Cloudflare corrisponda a `--port`
- Assicuratevi che cloudflared sia aggiornato: `cloudflared update`

### Il tunnel con nome non si connette

- Verificate che il token sia corretto
- Controllate la dashboard Cloudflare Zero Trust per individuare eventuali errori
- Provate a eseguire direttamente `cloudflared tunnel run <TOKEN>` per visualizzare i messaggi di errore