Come inoltrare un terminale direttamente nel browser usando WeTTY

Immagina questo: hai urgentemente bisogno di accedere a un server domestico o a una macchina virtuale di lavoro da un tablet, dal laptop di qualcun altro o da un computer aziendale con rigide policy di sicurezza dove la porta 22 è completamente bloccata e non puoi installare un client SSH adeguato. Apri un browser, digiti un indirizzo e ottieni una riga di comando completa con la tua shell familiare.

Questo è esattamente ciò per cui è stato creato il progetto WeTTY (Web + TTY).

Sotto il cofano

Le soluzioni precedenti come Ajaxterm o Anyterm erano terribilmente lente perché si basavano su richieste HTTP regolari avanti e indietro. WeTTY funziona in modo diverso. Il backend è costruito con TypeScript e Node.js, la comunicazione con il browser avviene tramite WebSocket e il rendering è gestito dall'emulatore di terminale xterm.js (lo stesso che alimenta VS Code).

Grazie alla combinazione di xterm.js e WebSocket, la latenza di input è appena percettibile se hai una connessione internet stabile. Le utility con pseudo-grafica funzionano senza problemi nella finestra del browser: htop, tmux, mc, vim e nano. Il supporto del mouse, le scorciatoie da tastiera e i colori del terminale funzionano tutti come previsto.

Come avviare

Puoi distribuire l'utility in due modi rapidi: tramite npm o in un container Docker.

Opzione 1. Installazione tramite npm

Se la macchina ha già Node.js versione 20 o superiore, insieme agli strumenti di build (make, python, build-essential), l'utility può essere installata con un singolo comando:

Dopo l'installazione, avvia il servizio:

Ora naviga su http://localhost:3000 e accedi con l'utente desiderato. Se WeTTY è in esecuzione come utente normale, stabilirà una sessione SSH verso localhost per impostazione predefinita. L'esecuzione come root invocherà invece /bin/login.

Opzione 2. Esecuzione in Docker

Personalmente trovo più semplice mantenere utility come questa nei container per evitare di ingombrare l'host con pacchetti globali Node.js non necessari:

Sostituisci 192.168.1.50 con l'indirizzo IP dell'host a cui vuoi connetterti tramite SSH.

Parametri di avvio utili

L'utility offre una configurazione flessibile tramite flag da riga di comando:

• --ssh-host e --ssh-port reindirizzano la connessione a un server remoto separato.
• --ssh-user imposta un utente predefinito per non dover digitare il login ogni volta.
• --ssl-key e --ssl-cert abilitano la crittografia diretta del traffico.
• --allow-iframe permette di incorporare il terminale in iframe su altri siti (ad esempio, in dashboard o pannelli di monitoraggio).

Se non vuoi specificare i flag ogni volta che avvii, puoi raggruppare i parametri in un file di configurazione e passarlo tramite --conf.

Sicurezza e uso in produzione

Esporre una porta HTTP non protetta di WeTTY a internet non è assolutamente consigliato. Qualsiasi attaccante potrebbe tentare attacchi brute-force sulle password o intercettare il traffico non crittografato.

In pratica, un reverse proxy (NGINX, Traefik o Caddy) viene tipicamente posizionato davanti a WeTTY per gestire molteplici responsabilità:

1. Emissione e rinnovo di certificati SSL gratuiti da Let's Encrypt.
2. Proxy delle connessioni WebSocket.
3. Un ulteriore livello di autorizzazione tramite Basic Auth o Authelia.
4. Restrizione dell'accesso basata su whitelist di indirizzi IP.

Ecco un esempio tipico di configurazione NGINX:

Non dimenticare di eseguire WeTTY stesso con il flag --base /wetty/ in modo che i percorsi di routing si allineino correttamente.

A chi è rivolto questo progetto

WeTTY risponde a esigenze pratiche specifiche:

• Amministrazione rapida di server domestici (Home Lab) e router direttamente da un telefono cellulare o iPad.
• Configurazione di ambienti demo e sandbox di formazione dove gli studenti necessitano di accesso shell senza configurare client SSH.
• Integrazione di una finestra terminale nei pannelli di gestione dell'infrastruttura web interni.
• Accesso a server da reti aziendali isolate dove sono aperti solo le porte 80 e 443.

Se hai bisogno di un modo leggero per avviare un terminale nel browser senza interfacce web pesanti come Cockpit o Proxmox, WeTTY gestisce tutto in un paio di minuti. Basta avviare il container dietro un reverse proxy e aggiungere l'autenticazione.