Operations tramite tunnel

Questo documento illustra «Operations tramite tunnel» del pannello: far collegare al pannello i server privi di IP pubblico.

In una frase

Con i dispositivi senza IP pubblico (macchine di rete interna, dispositivi dietro NAT, telefoni Android) non puoi «connettersi dall'esterno». Operations tramite tunnel fa sì che questi dispositivi si connettano «verso l'esterno» al server del pannello; dopo di che potrai gestirli come un normale server.

Panoramica della funzione

Per i dispositivi del tutto privi di un indirizzo pubblico raggiungibile (macchine di rete interna, dispositivi dietro NAT, telefoni Android ecc.) la connessione SSH diretta non è possibile. Operations tramite tunnel, tramite un tunnel inverso, fa sì che questi dispositivi si connettano attivamente al server del pannello; dopo di che potrai gestirli come un normale server.

Principio

• il server del pannello (con IP pubblico) esegue un servizio di tunnel
• sul dispositivo di destinazione viene installato un Agent leggero, che «chiama» attivamente il server del pannello
• una volta stabilita la connessione, il pannello può risalire il tunnel e fare SSH inverso verso il dispositivo di destinazione

> In parole semplici: il dispositivo di destinazione «telefona» al server del pannello; a chiamata attiva, il pannello può controllarlo attraverso questa «linea dedicata».

Quando serve

• gestire i dispositivi di rete interna di casa (Raspberry Pi, NAS, router software)
• gestire VPS economici senza IP pubblico (server NAT)
• gestire telefoni Android (ambiente Termux)

Come si usa (tre passi)

1. Apri «Operations tramite tunnel» e clicca «Script di installazione con un clic» per generare un comando dedicato

2. Incolla il comando sul dispositivo di destinazione ed eseguilo una volta (installa automaticamente l'Agent + imposta l'avvio automatico)

3. Dopo circa 10 secondi il dispositivo compare automaticamente nel pannello: puoi connetterti via SSH e usare tutte le funzioni

> Il comando di installazione è stato volutamente reso corto, per poterlo digitare a mano prima che tutto sia pronto:

> - Linux (curl): curl -sSL http://server:5501/i/<token> | sudo bash

> - Termux: curl -sSL http://server:5501/t/<token> | bash

> - Se sei già root puoi togliere sudo; su Alpine usa wget -qO- … | sudo bash, su BSD fetch -o - … | sudo bash

>

> Posizione di installazione: su Linux viene installato in /opt/sshe-agent per impostazione predefinita (se /opt manca o non è scrivibile lo script ripiega automaticamente su ~/sshe-agent, senza errori); su Termux in ~/sshe-agent (avvio insieme a Termux).

>

> Connessione senza password: al termine dell'installazione il pannello si connette al dispositivo senza password grazie a una chiave iniettata in precedenza, senza dover digitare nulla ogni volta.

Ambienti supportati dall'Agent

> ⚠️ macOS non è ancora supportato: le differenze di autenticazione SSH tra le versioni di macOS sono notevoli e non è possibile garantire una connessione stabile tra versioni diverse; questa versione quindi non fornisce l'accesso tramite tunnel su macOS. Per Operations tramite tunnel usa dispositivi Linux / Termux.

Stato online dell'Agent

• Online: la connessione del tunnel è regolare e il dispositivo è gestibile in qualsiasi momento
• Offline: il dispositivo è disconnesso (spento, rete caduta, Agent fermo). Il record offline viene conservato per un certo tempo e alla riconnessione il dispositivo torna automaticamente online

> 📌 Come si determina lo stato sulla scheda server: per i dispositivi in tunnel l'«online/offline» è deciso dall'heartbeat dell'Agent. Quando l'Agent è online, attraverso il tunnel viene creato dinamicamente un canale SSH per raccogliere i dati reali di integrità (carico/memoria/disco/tempo di attività/batteria/temperatura), esattamente come per un normale server.

Avvertenze

1. L'Agent è l'unico programma che il pannello deve installare sul dispositivo di destinazione (un'eccezione alla filosofia «zero impronta»). Infatti i dispositivi senza IP pubblico non possono essere contattati dall'esterno: possono solo connettersi loro.

2. L'Agent consuma risorse minime (un processo Python + una connessione persistente).

3. L'Agent trasmette su un tunnel cifrato: la comunicazione è sicura.

4. Se l'IP del dispositivo cambia o l'Agent smette di funzionare, basta rieseguire lo script di installazione per ripristinare tutto.

Rapporto con il Tunnel di porta

Operations tramite tunnel si occupa di «collegare il dispositivo al pannello», il Tunnel di porta di «esporre su Internet le porte applicative del dispositivo». I due lavorano insieme: prima colleghi i dispositivi senza IP pubblico con Operations tramite tunnel, poi con il Tunnel di porta mappi le sue applicazioni (come Navidrome, Nextcloud) sulle porte pubbliche del server del pannello.