Pangolin: Alternativa Self-Hosted a Cloudflare Tunnel

SelfHosted 19 feb 2025

Nel mondo self-hosting, la sicurezza e la gestione dell'accesso alle risorse private sono fondamentali. Oggi andiamo a vedere un'alternativa ai tunnel Cloudflare senza dover affidare il proprio traffico a servizi di terze parti, in questo articolo, esploreremo cos'è Pangolin, come funziona e perché potrebbe essere la scelta giusta per la nostra infrastruttura.

Cos'è Pangolin?

Pangolin è un proxy inverso con gestione dell'identità e degli accessi, progettato per esporre in modo sicuro risorse private attraverso tunnel crittografati basati su WireGuard. A differenza di Cloudflare Tunnel, che si appoggia ai server di Cloudflare per instradare il traffico, Pangolin ci permette di mantenere il controllo totale sulla nostra rete, ospitandolo direttamente su un server privato. Pangolin non opera da solo, fa parte di un ecosistema di strumenti che lavorano insieme per garantire la connettività sicura e la gestione degli accessi.
Ecco i suoi componenti principali:

Pangolin (Server centrale):
• Gestisce la logica principale del sistema.
• Fornisce API REST per l’interazione con gli altri componenti.
• Include un server WebSocket per la gestione dei client.
• Offre un’interfaccia web per la configurazione e il monitoraggio.
• Gestisce il database principale per la memorizzazione dei dati.

Gerbil (Gestione di WireGuard):
• Funziona come intermediario per la gestione delle configurazioni di WireGuard.
• Crea e mantiene i tunnel sicuri tra i client e il server Pangolin.

Traefik (Proxy inverso):
• Instrada le richieste HTTP alle risorse interne.
• Supporta plug-in per migliorare la sicurezza e la gestione degli accessi.
• Si integra con Badger per autenticare le richieste.

Badger (Plug-in di autenticazione per Traefik):
• Verifica le richieste prima di inoltrarle al backend.
• Redirige le richieste non autenticate al server Pangolin per la verifica.

Newt (Client WireGuard senza privilegi):
• Funziona come un client leggero per connettere le reti private a Pangolin.
• Si collega a Gerbil senza richiedere privilegi di root.
• Facilita la gestione dei proxy TCP per il tunneling dei servizi.

Perché dovremmo utilizzare Pangolin?

• Privacy e controllo totale;
• Sicurezza avanzata grazie all'utilizzo del Protocollo Wireguard;

Installazione di Pangolin

1) Prerequisiti

Per poter procedere all'installazione dobbiamo avere i seguenti requisiti:

• Un VPS (Virtual Provide Server);
• Un dominio Web
• Docker e Docker Compose;

Scelta del VPS:
Esistono diversi provider che offrono VPS a costi mensili irrisori e non, visto che comunque lo stack di Pangolin è veramente leggero (Richiede infatti 1 vCPU, 1 GB di RAM e 8 GB di SSD per girare), il mio consiglio è quello di acquistare un VPS attraverso IONOS, che offre una configurazione con i requisiti minimi chiesti da Pangolin:

Se optate di scegliere questo VPS vi consiglio di installare Debian e non Ubuntu.
Scelta del dominio:
Come detto per il Cloud Server VPS esistono milioni di provider anche per la vendita di domini, il mio consiglio è quello di acquistare un dominio attraverso OVH Cloud attraverso l'estensione .ovh che ha un costo di pochi euro annui (circa 1,99).

2) Installazione

Effettuato l'acquisto del nostro VPS e del nostro dominio iniziamo ad installare Docker e Docker Compose, successivamente ricordiamoci di rendere sicuro il nostro VPS. A questo punto accediamo al provider del dominio e creiamo due record così:
Record A (o AAAA per IPv6)
*.example.com punta all'indirizzo IP del VPS;
example.com punta all'indirizzo IP del VPS;
A questo punto, accediamo nuovamente al nostro VPS ed impostiamo il firewall per aprire le porte necessarie al funzionamento di pangolin:

sudo ufw allow 80,443/tcp comment "Allow Pangolin from anywhere"

sudo ufw allow 51820/udp comment "Allow Pangolin from anywhere"

Creiamo una cartella nella nostra home chiamata pangolin:

mkdir pangolin

entriamo dentro la cartella

cd pangolin

procediamo adesso con scaricare l'ultima versione attraversi git dal repository github ufficiale di Pangolin (l'ultima versione è verificabile qui https://github.com/fosrl/pangolin/releases)

wget -O installer "https://github.com/fosrl/pangolin/releases/download/1.0.0-beta.14/installer_linux_amd64" && chmod +x ./installer

I file scaricati verranno nominati "installer" nella directory corrente, eseguiamolo con il comando:

sudo ./installer

A video l'installer ci chiederà le seguenti informazioni:
Nome dominio base:
Dobbiamo inserire il nostro dominio di base (example.com) scelto in precedenza;
Nome dominio pangolin:
Il dominio in cui verrà ospitata l'applicazione. Questo è usato per molte cose, inclusa la generazione di collegamenti. È possibile eseguire Pangolin su un dominio di sottodominio o root;
E-mail per i certificati Lets Encrypt:
Qui dobbiamo fornire un indirizzo e-mail per la registrazione del certificato SSL con Lets Encrypt. Questa dovrebbe essere un'e-mail reale a cui abbiamo accesso;
A questo punto procediamo creando un account amministratore, abilitiamo o disabilitiamo le iscrizioni ed il server SMTP (opzionale).
Una volta fatto questo vedremo una schermata simile a questa:

Una volta completato il "pulling" ed iniziato il container possiamo recarci all'indirizzo impostato in precedenza (pangolin.example.com) dal nostro browser vedremo una schermata simile a questa:

Adesso effettuiamo il Log In inserendo le credenziali create in precedenza, al primo accesso ci chiederà di creare un Organizzazione, basta scegliere un nome e un ID. Da notare che l'ID non può essere modificato in un secondo momento. Il resto può essere skippato.

A questo punto non ci resta che collegare un nostro server domestico, quindi nella home clicchiamo su "+ Add Site", consiglio di effettuare come metodo di collegamento Newt in quanto è più veloce e ben ottimizzato per Pangolin:

Lasciamo la pagina aperta senza clicca "Create Site" ed accediamo al server che vogliamo collegare, digitiamo sul terminale:

wget -O newt "https://github.com/fosrl/newt/releases/download/1.0.0-beta.3/newt_linux_amd64" && chmod +x ./newt

A questo punto spostiamo nel PATH per averlo come comando:

sudo mv ./newt /usr/local/bin

Adesso creiamo un servizio tramite systemd per abilitare il collegamento in maniera permanente:

sudo nano /etc/system/systemd/newt.service

Copiamo la seguente configurazione del servizio:

[Unit]
Description=Newt Service
After=network.target

[Service]
ExecStart=/usr/local/bin/newt --id tuoid123 --secret secret123 --endpoint https://pangolin.example.com
Restart=always
User=root # Inserire il nome utente
WorkingDirectory=/root
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Adesso abilitiamo l'avvio automatico

sudo systemctl enable newt.service

Ed infine avviamo il servizio

sudo systemctl start newt.service

Per essere sicuri che tutto stia funzionando controlliamo il servizio con il comando

sudo systemctl status newt.service

A video riceveremo una risposta simile a questa:

Adesso riprendiamo la schermata di pangolin sul browser lascia aperta prima e creiamo il sito cliccando su "Create Site", facciamo passare qualche secondo e troveremo il nostro server con lo stato "online" come da foto allegata:

Come aggiungere una risorsa:

Ammettiamo di voler raggiungere fuori casa un nostro servizio, innanzi tutto rechiamoci nella voce in alto a destra "Resources", successivamente clicchiamo sul pulsante arancione "Add Resource" successivamente compiliamo i campi che ci vengono proposti come: Nome risorsa, subdomain ed il "sito" creato in precedenza, ecco un esempio:

A questo punto clicchiamo su "Create Resource" e dalla pagina che ci appare inseriamo un "Target", ovvero inseriamo l'indirizzo IP della macchina dove c'è il servizio che vogliamo esporre online e la sua porta, nel caso dell'esempio esponiamo online la VM con IP 192.168.0.109 porta 8086 che gira sul protocollo http, quindi inseriamo i dati richiesti e clicchiamo su "Add Target":

Adesso se apriamo una pagina del browser e digitiamo l'indirizzo impostato in precedenza (subdomain.example.com) ci troviamo online il nostro servizio.
Se vogliamo, possiamo anche aggiungere un layer di autenticazione al nostro servizio online come ad esempio: aggiungere un pin per effettuare il log-in tramite pangolin prima di accedere al servizio o inserire una password e così via, queste funzionalità li troviamo nella sezione "Autentication":

Come effettuare l'upgrade di Pangolin

Per poter aggiornare il nostro server Pangolin ci basterà accedere alla directory dove abbiamo scaricato l'applicativo:

cd pangolin

Stoppare il container docker:

sudo docker compose down

Modifichiamo l'immagine prendendo la più aggiornata dal docker hub:

services:
  pangolin:
    image: fosrl/pangolin:1.0.0-beta.15 # Verifichiamo prima l'ultima immagine disponibile da qui https://hub.docker.com/r/fosrl/pangolin/tags
    container_name: pangolin
    restart: unless-stopped

A questo punto facciamo il pull dell'immagine: