Come risolvere "unknown terminal type" via SSH

Cosa significa "unknown terminal type"

Un errore di tipo terminale sconosciuto tramite SSH indica che il nome contenuto in TERM non ha una voce corrispondente nel database terminfo sul server. L'emulatore imposta questo nome sul laptop. Il database che deve riconoscerlo si trova sul computer remoto. Quando la ricerca non trova una corrispondenza, ogni programma curses su quel server si interrompe prima di visualizzare qualsiasi elemento, perché non dispone della descrizione delle funzionalità del terminale.

La soluzione che mantiene tutte le funzionalità dell'emulatore consiste nell'eseguire un solo comando: compilare la propria voce terminfo in ~/.terminfo sul server. ncurses cerca prima nella directory home dell'utente e poi nelle directory di sistema. Non sono quindi necessari i privilegi root e non cambia nulla per gli altri utenti.

TERM è un nome, terminfo è il database

TERM contiene una stringa, che è soltanto una chiave. terminfo è un database compilato di descrizioni di terminale e la chiave consente a un programma di individuare quella corretta. Una descrizione specifica quanti colori supporta il terminale, quali byte spostano il cursore alla riga 12 e alla colonna 40, quali byte invia il tasto F5 e se il terminale può visualizzare una sottolineatura con stile. ncurses, la libreria su cui si basa quasi ogni interfaccia utente testuale in Linux, legge questa descrizione all'avvio. Programmi come top, less, nano e watch non possono visualizzare neppure una schermata senza di essa.

Esaminare la propria voce:

echo "$TERM"
tput longname
infocmp -1 | head -20

tput longname stampa la descrizione leggibile della voce identificata da TERM. Per xterm-256color stampa:

xterm with 256 colors

infocmp -1 decompila l'intera voce e stampa una capacità per riga. Se entrambi i comandi funzionano, il database di questa macchina contiene questo terminale. È lo stato che deve essere disponibile anche dall'altra parte di una connessione SSH.

Perché si verifica solo tramite SSH

SSH invia il nome e nient’altro. Quando il client richiede uno pseudo-terminale, TERM viene trasmesso insieme a quella richiesta. Il manuale di OpenSSH è esplicito: "la variabile d’ambiente TERM viene sempre inviata quando viene richiesto uno pseudo-terminale, perché è necessaria al protocollo". La shell di login sulla VPS riceve quindi TERM=xterm-ghostty, oppure xterm-kitty, o qualsiasi altro nome utilizzi il tuo emulatore. La descrizione associata a quel nome resta sul laptop, nel database del laptop. Un server realizzato prima dell’esistenza del tuo emulatore non ha mai riconosciuto quel nome. Nulla nella connessione SSH stessa copia le descrizioni dei terminali, ed è una scelta intenzionale: il protocollo trasporta un nome, non un elenco delle funzionalità.

Riproduci il problema sul tuo computer usando un nome che sicuramente non esiste:

TERM=xterm-nosuchthing tput colors
echo "$?"

tput: unknown terminal "xterm-nosuchthing"

Il codice di uscita è 3, che ncurses documenta come tipo di terminale sconosciuto o database mancante. Ogni programma curses esegue la stessa ricerca, quindi un nome mancante produce un messaggio diverso per ogni programma, ma con un’unica causa comune. nano si interrompe con Error opening terminal: xterm-nosuchthing., l’errore standard di ncurses quando non riesce a caricare una descrizione all’avvio. vim visualizza E558: Terminal entry not found in terminfo. less visualizza WARNING: terminal is not fully functional. Un pager che funziona solo parzialmente e un editor che rifiuta di avviarsi sembrano problemi non correlati. In realtà dipendono dallo stesso file mancante.

Dove cerca la voce ncurses

ncurses cerca in un ordine fisso, documentato in terminfo(5):

1. $TERMINFO, se impostata. Viene cercata soltanto questa directory.
2. $HOME/.terminfo.
3. Ogni directory elencata in $TERMINFO_DIRS.
4. Le posizioni compilate nel programma, che su Debian e Ubuntu includono /etc/terminfo, /lib/terminfo e /usr/share/terminfo.

Eseguire infocmp -D sul server per visualizzare l’elenco usato dalla build ncurses presente sul server, invece di affidarsi ai percorsi indicati sopra. Il passaggio 2 è l’elemento fondamentale. La directory home viene cercata prima di qualsiasi directory di sistema. Di conseguenza, un solo file in ~/.terminfo risolve la ricerca per il proprio account, senza installare pacchetti e senza usare root.

Correzione 1: usare un TERM già riconosciuto dal server

Il modo più rapido per sbloccare la situazione consiste nell'indicare un terminale diverso per una connessione:

TERM=xterm-256color ssh user@203.0.113.10

Per renderlo permanente per quell'host, aggiungilo a ~/.ssh/config sul laptop:

Host vps1
    HostName 203.0.113.10
    User deploy
    SetEnv TERM=xterm-256color

SetEnv richiede OpenSSH 7.8 o versione successiva sul client, rilasciata ad agosto 2018. TERM è l'unica variabile per la quale non è necessaria l'autorizzazione del server: il manuale specifica che «Analogamente a SendEnv, fatta eccezione per la variabile TERM, il server deve essere predisposto per accettare la variabile d'ambiente». Pertanto funziona anche con un sshd configurato in modo restrittivo e privo di qualsiasi riga AcceptEnv.

Il costo è la perdita di tutto ciò che l'emulatore descrive oltre a xterm-256color semplice. Sono inclusi il colore a 24 bit pubblicizzato tramite la capacità RGB e i caratteri sottolineati con stile tramite Smulx. I programmi non possono più rilevare queste capacità, quindi usano 256 colori e una sottolineatura semplice. Lo schermo funziona. Offre semplicemente meno capacità rispetto al terminale selezionato.

Non risolvere il problema aggiungendo export TERM=xterm-256color a .bashrc sul server. Quel file viene eseguito per ogni connessione, comprese quelle provenienti da un terminale il cui nome è riconosciuto dal server, quindi riduce le capacità delle sessioni che funzionavano già correttamente. Mantieni l'override sul client, dove sai quale emulatore stai utilizzando.

Correzione 2: inviare una volta la voce terminfo al server

Questa correzione mantiene intatto il tuo emulatore. Decompila localmente la voce, inoltrala tramite SSH e compilala sul server remoto:

infocmp -x | ssh user@203.0.113.10 -- tic -x -

infocmp -x stampa la voce corrispondente al tuo TERM corrente come testo sorgente, incluse le funzionalità estese, definite dall'utente. tic -x ricompila il sorgente in una descrizione binaria sul server. -x su entrambi i lati è importante, perché senza questa opzione funzionalità come Smulx vengono eliminate durante il trasferimento e sul server viene installata una copia con capacità ridotte del terminale originale.

tic scrive nella directory di sistema quando possibile e usa $HOME/.terminfo come fallback quando l'utente non dispone dei permessi di scrittura. Un account ordinario su un VPS usa la directory home, che è la scelta corretta. Puoi anche specificare la destinazione:

infocmp -x | ssh user@203.0.113.10 -- tic -x -o '~/.terminfo' /dev/stdin

Le virgolette intorno a ~/.terminfo sono necessarie. ssh unisce le parole del comando in un'unica stringa e la passa alla shell remota, quindi un ~ non racchiuso tra virgolette viene espanso prima dalla shell locale. In questo modo invii un /home/yourname/.terminfo letterale a una macchina in cui l'account potrebbe avere un nome diverso. tic restituisce un errore di autorizzazione oppure scrive in un percorso che ncurses non cerca. Racchiudi la tilde tra virgolette e lascia che sia la shell remota a espanderla.

Accedi e verifica:

ssh user@203.0.113.10
tput longname
ls -R ~/.terminfo

La stampa della descrizione del terminale da parte di tput longname indica che la ricerca ora ha esito positivo; ls mostra il file compilato in una sottodirectory denominata con la prima lettera del nome del terminale. Esegui quindi top oppure watch -n1 uptime, che ridisegna l'output usando la stessa libreria, per verificare che un programma curses reale visualizzi correttamente lo schermo.

Costo operativo: un passaggio per ogni server, con la voce memorizzata nella directory home dell'account su una sola macchina. Se ricrei il VPS, la voce viene eliminata. Inserisci il comando nello strumento che usi per predisporre e gestire più server contemporaneamente, così ogni nuovo host viene fornito con la voce già compilata.

Correzione 3: installare il database terminfo esteso

Se disponi dell'account root e vuoi che il nome venga risolto per ogni account sul server:

sudo apt update
sudo apt install ncurses-term
tput -T xterm-ghostty longname

ncurses-term contiene le descrizioni dei terminali che l'installazione di base non include. Risolve il problema del nome per root e per tutti gli altri utenti, a differenza della correzione 2.

Funziona solo se la voce del tuo terminale è presente nella versione di ncurses inclusa nella distribuzione. Verificalo invece di dare per scontato che lo sia. Ubuntu 24.04 include ncurses-bin 6.4+20240113-1ubuntu2.1 (ad agosto 2026). La voce di Ghostty è stata aggiunta upstream in ncurses 6.5-20241228, che è più recente. Di conseguenza, apt install ncurses-term su Ubuntu 24.04 non può produrre una voce xterm-ghostty, indipendentemente dal numero di volte in cui lo esegui. tput -T <name> longname esegue il controllo: stampa la descrizione quando la voce è presente e unknown terminal con codice di uscita 3 quando non lo è.

Per installare una singola voce a livello di sistema invece dell'intero pacchetto, copia il sorgente e compilalo come root:

infocmp -x | ssh user@203.0.113.10 -- 'cat > /tmp/term.src'
ssh -t user@203.0.113.10 -- sudo tic -x -o /usr/share/terminfo /tmp/term.src

-t nel secondo comando alloca un terminale pseudo-TTY, così sudo può richiedere la password. Senza di esso, sudo potrebbe terminare con sudo: no tty present and no askpass program specified.

Lascia che sia l’emulatore a eseguire il trasferimento

Alcuni emulatori includono un componente che applica automaticamente la correzione 2. kitty include il ssh kitten: kitten ssh myserver si connette e copia automaticamente il terminfo di kitty sull’host remoto. La documentazione riporta anche la forma manuale, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, con il carattere tilde protetto per il motivo descritto sopra. Ghostty documenta infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - e include l’integrazione con la shell (ssh-env e ssh-terminfo), oltre all’azione +ssh, che automatizza entrambe le correzioni.

Questi strumenti eseguono gli stessi comandi che hai appena eseguito manualmente. Conoscere la forma manuale resta importante, perché lo strumento non può intervenire quando la connessione viene avviata altrove, su un jump host o all’interno di uno script.

Quando l’errore ricompare

Con sudo -i. Una shell di login come root ha impostato HOME=/root e sudo conserva il valore di TERM. ncurses cerca quindi /root/.terminfo, che non contiene la relativa voce; l’errore ricompare per il solo account root. Verifica con sudo -i env e leggi le righe HOME e TERM. Installa la voce nella directory di sistema oppure inseriscine una copia in /root/.terminfo.

All’interno di tmux o screen. Questi programmi impostano un proprio TERM per i programmi eseguiti al loro interno, in genere screen-256color o tmux-256color. Un server meno recente riconosce screen-256color e potrebbe non riconoscere tmux-256color; la shell esterna funziona, mentre tutto ciò che viene eseguito nella sessione non funziona. La causa è la stessa, ma cambia il nome. Esegui tput -T tmux-256color longname sul server per verificare quale dei due valori è disponibile. Un ambiente di lavoro per terminale basato su tmux nasconde il problema fino al giorno in cui ti connetti a un host che non hai ancora corretto.

Su un server appena installato. ~/.terminfo è specifico dell’account e della macchina, quindi un VPS ricreato torna a essere vuoto.

Il display viene visualizzato, ma i tasti non funzionano correttamente. Se il display è corretto, ma Home, End o i tasti funzione inseriscono caratteri anomali, il nome è stato risolto in una voce che non corrisponde al tuo terminale. Le sequenze dei tasti provengono dalla stessa voce terminfo delle funzionalità di visualizzazione, quindi una voce approssimativa produce sequenze di tasti approssimative. Questo è il risultato tipico della correzione 1 su un emulatore le cui sequenze di tasti differiscono da xterm. La correzione 2 risolve il problema, perché solo la voce reale del tuo emulatore contiene le sequenze corrette.

FAQ

Perché tramite SSH viene visualizzato solo "unknown terminal type"?

Il database che deve contenere la voce del terminale è quello del server. L'emulatore installa la propria descrizione sulla macchina su cui viene eseguito, quindi i programmi locali la trovano senza interventi da parte dell'utente. SSH invia solo il valore di TERM, perché il protocollo trasmette questo nome nella richiesta dello pseudo-terminale. ncurses sul sistema remoto cerca il nome nel database remoto, ma non trova alcuna voce. Di conseguenza initscr non riesce e il programma si interrompe.

Posso risolvere il problema senza avere root sul server?

Sì. ncurses cerca $HOME/.terminfo prima di qualsiasi directory di sistema, quindi è sufficiente inserire lì la voce per renderla disponibile al proprio account. Esegui infocmp -x | ssh user@host -- tic -x - una volta per ogni server. tic scrive nella directory home dell'utente quando non può scrivere nel percorso di sistema, che è il comportamento normale per un account senza privilegi. Accedi al server ed esegui tput longname per verificare che la ricerca ora vada a buon fine.

Cosa perdo impostando TERM=xterm-256color per un host?

Tutte le funzionalità descritte dal tuo emulatore oltre alla voce xterm-256color, ad esempio il colore a 24 bit tramite RGB e le sottolineature con stile tramite Smulx. I programmi non possono rilevare queste funzionalità, quindi usano il fallback più vicino. Anche le sequenze dei tasti funzione possono differire da quelle del terminale reale. Inserisci l'impostazione sul client in ~/.ssh/config, non in un .bashrc sul server: quest'ultima soluzione ridurrebbe le funzionalità anche delle sessioni avviate da terminali che funzionavano già.

Perché l'errore ricompare dopo sudo -i?

sudo -i avvia una shell di login come root con HOME=/root, mantenendo il valore di TERM. ncurses cerca quindi /root/.terminfo invece della directory home dell'utente e non trova alcuna voce. root visualizza così lo stesso errore che non viene più visualizzato dal tuo account. Esegui sudo -i env e controlla le righe HOME e TERM. Compila la voce nella directory di sistema con sudo tic -x -o /usr/share/terminfo oppure copiala in /root/.terminfo.

apt install ncurses-term risolve sempre il problema?

No. Aggiunge solo le voci presenti nella release di ncurses inclusa nella distribuzione. Ubuntu 24.04 include ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.1, ad agosto 2026), mentre la voce di Ghostty è stata aggiunta upstream in ncurses 6.5-20241228. Quel pacchetto quindi non può contenerla. Verifica con tput -T <name> longname prima di fare affidamento sul pacchetto e installa autonomamente la voce se il controllo continua a segnalare un terminale sconosciuto.