Pubblicare un servizio con Cloudflare Tunnel
Pubblicare un'applicazione ospitata su Debian o Ubuntu senza aprire porte in entrata grazie a Cloudflare Tunnel, proteggere un'interfaccia di amministrazione con Cloudflare Access, aggiornare ed eseguire il backup.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come pubblicare un'applicazione ospitata sul tuo server senza aprire porte in entrata. Il programma cloudflared stabilisce una connessione in uscita verso Cloudflare. I visitatori arrivano su https://app.tuo-dominio.com, Cloudflare gestisce il certificato e inoltra le richieste in questo tunnel.
Al termine della guida, l'applicazione resta in ascolto in locale, il tunnel si avvia insieme al server e sai riservare un'interfaccia sensibile a persone identificate.
Ordina un Server
Questa guida si applica ai server che amministri tu stesso:
Prerequisiti
- Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
- Un accesso SSH con un utente che dispone di
sudo - Un account Cloudflare
- Un dominio attivo su questo account
- Un'applicazione in ascolto in locale, ad esempio su
127.0.0.1:3000
Aggiungere il dominio a Cloudflare
Se il dominio non è ancora su Cloudflare:
- Aggiungilo dalla dashboard, poi scegli un piano.
- Controlla i record DNS importati. Verifica soprattutto i record MX e quelli della posta, perché la scansione automatica può dimenticarne alcuni.
- Disattiva DNSSEC presso il tuo registrar se è attivo.
- Sostituisci i server dei nomi del dominio con quelli indicati da Cloudflare. Per un dominio gestito presso HostMyServers, consulta la guida Server DNS.
Porte utilizzate
| Porta | Direzione | Ruolo | Azione |
|---|---|---|---|
| 7844/tcp e 7844/udp | In uscita | Connessione del tunnel verso Cloudflare | Da autorizzare se le uscite sono filtrate |
| 443/tcp | In uscita | Funzioni accessorie, come il controllo degli aggiornamenti | Facoltativa |
| 3000/tcp | Locale | Applicazione di esempio | Non aprire |
| Nessuna | In entrata | Il tunnel non ha bisogno di nessuna porta in entrata | Niente da aprire |
Passo 1: verificare l'applicazione
L'applicazione deve rispondere sul loopback:
curl -I http://127.0.0.1:3000
sudo ss -ltnp | grep 3000L'indirizzo di ascolto deve essere 127.0.0.1. Se l'applicazione gira in Docker, pubblica la sua porta nella forma 127.0.0.1:3000:3000. Una pubblicazione 3000:3000 resterebbe raggiungibile da Internet, perché Docker inserisce le proprie regole di firewall.
Passo 2: installare cloudflared
Aggiungi il repository ufficiale di Cloudflare, poi installa il pacchetto:
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt-get update
sudo apt-get install -y cloudflared
cloudflared --versionPasso 3: creare il tunnel
Autentica cloudflared. Il comando mostra un URL da aprire nel browser, dove scegli il tuo dominio:
sudo cloudflared tunnel loginIl certificato dell'account viene salvato in /root/.cloudflared/cert.pem. Crea poi il tunnel:
sudo cloudflared tunnel create hms-tunnel
sudo cloudflared tunnel listAnnota l'identificatore mostrato, chiamato qui TUNNEL_UUID. Copia il suo file di credenziali nella cartella usata dal servizio:
sudo install -d -m 700 /etc/cloudflared
sudo install -m 600 /root/.cloudflared/TUNNEL_UUID.json /etc/cloudflared/TUNNEL_UUID.jsonPasso 4: configurare il tunnel
sudo nano /etc/cloudflared/config.ymltunnel: TUNNEL_UUID
credentials-file: /etc/cloudflared/TUNNEL_UUID.json
ingress:
- hostname: app.tuo-dominio.com
service: http://127.0.0.1:3000
- service: http_status:404Le regole vengono lette in ordine. L'ultima, senza nome host, è obbligatoria: risponde 404 a qualsiasi richiesta che non corrisponde ad alcun servizio.
Controlla il file e l'instradamento di un URL:
sudo cloudflared tunnel --config /etc/cloudflared/config.yml ingress validate
sudo cloudflared tunnel --config /etc/cloudflared/config.yml ingress rule https://app.tuo-dominio.comPasso 5: proteggere un'interfaccia di amministrazione
Salta questo passo solo se il servizio è destinato al pubblico e dispone di una propria autenticazione. Per un'interfaccia di amministrazione, crea la protezione prima di pubblicare il nome: senza un'applicazione Access, l'indirizzo è aperto a tutto Internet.
Nella dashboard di Cloudflare:
- Vai in Zero Trust > Access controls > Applications.
- Seleziona Create new application, poi Self-hosted and private.
- Seleziona Add public hostname e indica
app.tuo-dominio.com. - Sotto Access policies, crea una policy con l'azione Allow e una regola Include di tipo Emails, contenente il tuo indirizzo.
- Scegli la modalità di accesso. Se vuoi ricevere un codice via e-mail, aggiungi One-time PIN in Zero Trust > Integrations > Identity providers.
- Seleziona Create.
Le etichette possono cambiare: in caso di differenze, segui la documentazione di Cloudflare Access.
Puoi anche chiedere a cloudflared di verificare il token Access. L'Application Audience (AUD) Tag si trova in Additional settings dell'applicazione. In config.yml, completa la regola interessata:
ingress:
- hostname: app.tuo-dominio.com
service: http://127.0.0.1:3000
originRequest:
access:
required: true
teamName: TEAM_NAME
audTag:
- AUD_TAG
- service: http_status:404TEAM_NAME è il nome del tuo team Cloudflare One, quello che precede .cloudflareaccess.com. Riesegui poi la convalida del passo 4.
Passo 6: pubblicare il nome di dominio
Crea il record DNS che punta al tunnel:
sudo cloudflared tunnel route dns hms-tunnel app.tuo-dominio.comSe gestisci più domini, verifica nella dashboard che il record CNAME sia stato creato nella zona giusta. Deve puntare a TUNNEL_UUID.cfargotunnel.com.
Passo 7: avviare il tunnel come servizio
sudo cloudflared service install
systemctl status cloudflared --no-pagerIl comando crea il servizio cloudflared, lo attiva all'avvio e lo lancia con /etc/cloudflared/config.yml.
Verificare il risultato
sudo journalctl -u cloudflared --no-pager -n 50 | grep 'Registered tunnel connection'
sudo cloudflared tunnel info hms-tunnel
curl -I https://app.tuo-dominio.comI log devono indicare connessioni registrate e l'URL deve rispondere. Se hai creato un'applicazione Access, apri l'indirizzo in una finestra di navigazione privata: la pagina di accesso deve comparire prima dell'applicazione.
Dal tuo computer, l'accesso diretto deve fallire:
curl -m 5 -I http://IP_DEL_TUO_SERVER:3000Chiudere gli accessi diventati inutili
Se in precedenza l'applicazione era pubblicata sulle porte web e nient'altro le usa più, rimuovi le loro regole UFW:
sudo ufw status numbered
sudo ufw delete allow 80/tcp
sudo ufw delete allow 443/tcpIl tunnel funziona con una policy in entrata chiusa. Mantieni la tua regola SSH, a meno che tu non passi da una rete privata come Tailscale.
Il file cert.pem consente di gestire tutti i tunnel dell'account, mentre il servizio ha bisogno solo del file di credenziali del tunnel. Se non amministri i tuoi tunnel da questo server, eliminalo:
sudo shred -u /root/.cloudflared/cert.pemDovrai rieseguire sudo cloudflared tunnel login prima di qualsiasi comando di gestione, come tunnel route dns o tunnel info. Eliminare questo file non revoca il token che contiene: per farlo, elimina il token Cloudflare Tunnel API Token o Argo Tunnel API Token in My Profile > API Tokens.
Pubblicare un altro servizio
Aggiungi una regola prima della regola finale:
ingress:
- hostname: app.tuo-dominio.com
service: http://127.0.0.1:3000
- hostname: docs.tuo-dominio.com
service: http://127.0.0.1:8080
- service: http_status:404Convalida, crea il nome DNS, poi riavvia il servizio:
sudo cloudflared tunnel --config /etc/cloudflared/config.yml ingress validate
sudo cloudflared tunnel route dns hms-tunnel docs.tuo-dominio.com
sudo systemctl restart cloudflaredSe cert.pem è stato eliminato, puoi anche creare nel DNS di Cloudflare un record CNAME verso TUNNEL_UUID.cfargotunnel.com.
Variante: gestire il tunnel dalla dashboard
Cloudflare permette anche di gestire il tunnel da remoto, senza config.yml:
- Vai in Networking > Tunnels, poi seleziona Create a tunnel.
- Assegna un nome al tunnel, scegli il tuo sistema ed esegui sul server il comando proposto. Contiene un token segreto.
- Nella scheda Routes, seleziona Add route, poi Published application.
- Indica il sottodominio, il dominio e l'URL del servizio, ad esempio
http://127.0.0.1:3000.
Una macchina può eseguire un solo servizio cloudflared. Aggiungi le tue applicazioni al tunnel esistente anziché installarne un secondo.
Limiti da conoscere
- L'applicazione vede le richieste arrivare da
cloudflared. L'indirizzo reale del visitatore si trova nell'headerCF-Connecting-IP. - La dimensione delle richieste dipende dal tuo piano Cloudflare: 100 MB sui piani Free e Pro.
- I termini di Cloudflare regolano la distribuzione di video e di file voluminosi sui piani Free, Pro e Business.
- Un sottodominio a più livelli, come
a.b.tuo-dominio.com, richiede un certificato avanzato. - Questa guida copre le applicazioni web. SSH o altri protocolli TCP richiedono anche una configurazione lato client.
Aggiornare
cloudflared installato tramite pacchetto si aggiorna con APT, poi il servizio deve essere riavviato. Il traffico in corso viene brevemente interrotto:
sudo apt-get update
sudo apt-get install --only-upgrade -y cloudflared
sudo systemctl restart cloudflared
cloudflared --versionBackup e ripristino
La cartella /etc/cloudflared contiene la configurazione e il file di credenziali del tunnel:
sudo tar -czf /root/cloudflared-$(date +%F).tar.gz -C /etc cloudflared
sudo chmod 600 /root/cloudflared-$(date +%F).tar.gzQuesto file di credenziali non scade e permette di eseguire il tunnel: conserva l'archivio cifrato, fuori dal server.
Per ripristinare su un server in cui cloudflared è installato, sostituendo AAAA-MM-GG con la sua data:
sudo tar -xzf /root/cloudflared-AAAA-MM-GG.tar.gz -C /etc
sudo cloudflared service installArresta prima il tunnel sul vecchio server se non vuoi che entrambi ricevano traffico.
In caso di problemi
Errore 1033
Cloudflare non trova nessuna istanza attiva del tunnel. Verifica il servizio e i suoi log:
systemctl status cloudflared --no-pager
sudo journalctl -u cloudflared --no-pager -n 100Se il servizio funziona, controlla che il CNAME punti al TUNNEL_UUID.cfargotunnel.com corretto.
Errore 502 e Unable to reach the origin service
Il tunnel è connesso, ma cloudflared non raggiunge l'applicazione. Verifica che sia in funzione, poi confronta la sua porta e il suo protocollo con la riga service:
curl -I http://127.0.0.1:3000ERR_TOO_MANY_REDIRECTS
L'applicazione reindirizza HTTP a HTTPS mentre la regola usa http://. Disattiva questo reindirizzamento nell'applicazione, oppure usa https:// in service con un certificato valido.
x509: certificate signed by unknown authority o certificate is valid for
Con un'applicazione in HTTPS, cloudflared non riconosce il suo certificato. Indica l'autorità con caPool, oppure il nome atteso con originServerName, in originRequest. Usa noTLSVerify solo per il tempo di una diagnosi.
remote error: tls: handshake failure
Il nome pubblico non è coperto da un certificato, spesso perché si tratta di un sottodominio a più livelli. Usa un solo livello oppure ordina un certificato avanzato.
Tunnel credentials file ... doesn't exist or is not a file
Il percorso credentials-file non è corretto. Verifica che corrisponda al file presente in /etc/cloudflared:
sudo ls -l /etc/cloudflaredAn A, AAAA, or CNAME record with that host already exists
Il nome è già usato nella tua zona DNS. Elimina il vecchio record in Cloudflare dopo aver verificato che non serva più, oppure scegli un altro nome. Per sostituire volontariamente il record:
sudo cloudflared tunnel route dns --overwrite-dns hms-tunnel app.tuo-dominio.comcloudflared service is already installed
Esiste già un servizio sulla macchina. Aggiungi la tua applicazione al tunnel esistente, oppure disinstalla il servizio prima di ricominciare:
sudo cloudflared service uninstallpossible conflicting configuration
Esistono due file di configurazione, spesso /root/.cloudflared/config.yml e /etc/cloudflared/config.yml. Mantieni quello di /etc/cloudflared, poi indicalo esplicitamente:
sudo cloudflared --config /etc/cloudflared/config.yml service installIl tunnel non si connette
cloudflared usa QUIC su UDP e ripiega su HTTP/2 su TCP se l'UDP non passa. La porta in uscita 7844 deve quindi essere aperta. Testala dal server:
sudo apt-get install -y netcat-openbsd
nc -vz -w 3 region1.v2.argotunnel.com 7844
nc -uvz -w 3 region1.v2.argotunnel.com 7844Il test UDP può riuscire anche se i pacchetti sono filtrati: il test TCP è il più indicativo. Se le tue regole locali sono corrette e la porta resta bloccata, contatta il supporto dalla tua area clienti.
failed to sufficiently increase receive buffer size
Questo messaggio riguarda il buffer UDP di QUIC. In genere è senza conseguenze e non richiede nessuna azione.