Cosa fa#
Tecnica SSH che apre una pipe cifrata tra una porta locale (host) e una porta remota (target). Il processo ssh -N ascolta sulla porta locale e inoltra (forwarda) tutto il traffico al server remoto, agendo come un proxy sicuro senza richiedere servizi in ascolto sulla macchina locale.
Come funziona#
Il traffico viene incapsulato all'interno della sessione SSH esistente tra il tuo Mac e il server remoto.
Il tuo Mac Server remoto
porta locale (es. 5433) SSH daemon
│ │
│ ── traffico cifrato via SSH ──► │
│ │
└── aperta dal processo ssh -N └──► destinazione:porta
(es. 172.17.0.X:5432)Anatomia del flag -L#
ssh -L [porta_locale]:[host_destinazione]:[porta_remota] user@server
-L 5433 : 172.17.0.2 : 5432
│ │ │
│ │ └─ porta sul host_destinazione
│ └──────────────── indirizzo visto dal server remoto
└──────────────────────────── porta che si apre sul tuo MacNota:
host_destinazioneè risolto dal server remoto, non dal tuo Mac. Quindilocalhostsi riferisce al server stesso, mentre172.17.0.Xsi riferisce agli IP della rete interna del server (es. container Docker).
Caso Reale: PostgreSQL dentro Docker#
Nel progetto pippoai, il database gira in un container. localhost dal server remoto non raggiunge il container; è necessario l'IP interno.
Il tuo Mac Server remoto
┌─────────────┐ SSH tunnel ┌──────────────────────────┐
│ │ ──────────────► │ Host Docker │
│ pg_dump / │ │ │
│ psql │ │ ┌────────────────────┐ │
│ porta 5433 │ ◄────────────── │ │ container postgres │ │
│ │ dati DB │ │ IP: 172.17.0.X │ │
└─────────────┘ │ │ porta: 5432 │ │
│ └────────────────────┘ │
└──────────────────────────┘Comandi essenziali#
| Comando | Cosa fa |
|---|---|
ssh -L 5433:localhost:5432 user@host -N | Tunnel base verso il server stesso. |
ssh -L 5433:172.17.0.X:5432 user@host -N | Tunnel verso l'IP specifico di un container Docker. |
lsof -i :5433 | Verifica che il tunnel sia attivo (mostra il processo ssh). |
docker inspect [nome] | grep IPAddress | Trova l'IP interno del container (da eseguire sul server). |
Combinazioni utili#
# Apri il tunnel (tienilo aperto in un terminale separato)
ssh -L 5433:172.17.0.X:5432 barno@host -p 2222 -i ~/.ssh/chiave -N -v
# Esegui il dump del database attraverso il tunnel (disabilitando GSSAPI per evitare errori Kerberos)
PGPASSWORD='password' pg_dump \
"host=localhost port=5433 dbname=rag user=rag_user gssencmode=disable" \
--format=custom --no-owner --no-acl --file=rag_dump.dumpTroubleshooting#
| Errore | Causa | Soluzione |
|---|---|---|
lsof -i vuoto | Tunnel non aperto o caduto. | Riapri con -v per vedere i messaggi di errore. |
| GSSAPI error | Interferenza Kerberos/GSSAPI. | Aggiungi gssencmode=disable alla connection string. |
| Auth failed | Caratteri speciali nella password. | Usa virgolette singole: PGPASSWORD='...'. |
| Conn. refused | Porta locale già occupata. | Cambia porta locale (es. 5434) o usa kill $(lsof -t -i :5433). |
| Conn. closed | localhost non vede il container. | Usa l'IP interno trovato con docker inspect. |
Dove l'ho usato#
- system — Tunnel verso PostgreSQL dentro Docker per operazioni di dump/restore e debug del RAG.
Note personali#
Analyst Tip: Il tunnel deve rimanere aperto in un terminale dedicato. Se chiudi quel processo, la connessione cade istantaneamente. Per Docker, non fidarti mai di
localhost: controlla sempre l'IP del container condocker inspect.
