Oplossing voor 'unknown terminal type' bij SSH

Wat "unknown terminal type" betekent

Een "unknown terminal type"-fout via SSH betekent dat de naam in TERM geen overeenkomstige vermelding heeft in de terminfo-database op de server. Uw emulator stelt die naam in op uw laptop. De database die deze moet herkennen, bevindt zich op de externe machine. Wanneer de opzoekactie mislukt, stopt elk curses-programma op die server voordat het iets tekent, omdat het geen beschrijving heeft van wat uw terminal kan.

De oplossing die alle functies van uw emulator behoudt, is één commando: compileer uw eigen terminfo-vermelding naar ~/.terminfo op de server. ncurses doorzoekt uw home-directory vóór elke systeemdirectory, dus dit vereist geen root-rechten en verandert niets voor andere gebruikers.

TERM is een naam, terminfo is de database

TERM bevat één string, en die string is slechts een sleutel. terminfo is een gecompileerde database met terminalbeschrijvingen, en de sleutel bepaalt hoe een programma de juiste beschrijving vindt. Een beschrijving legt vast hoeveel kleuren de terminal ondersteunt, welke bytes de cursor naar rij 12 kolom 40 verplaatsen, welke bytes de F5-toets verstuurt en of de terminal een gestileerde onderstreping kan tekenen. ncurses, de bibliotheek waarop vrijwel elke tekstgebaseerde gebruikersinterface op Linux is gebouwd, leest deze beschrijving bij het opstarten. Programma's zoals top, less, nano en watch kunnen zonder deze informatie geen enkel scherm opbouwen.

Bekijk uw eigen invoer:

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

tput longname toont de leesbare beschrijving van wat TERM benoemt. Voor xterm-256color voert het dit uit:

xterm with 256 colors

infocmp -1 decompileert de volledige invoer en drukt één eigenschap per regel af. Als beide commando's werken, kent de database op deze machine deze terminal. Dat is de status die u ook aan de andere kant van een SSH-verbinding nodig heeft.

Waarom het alleen via SSH misgaat

SSH verstuurt alleen de naam en niets anders. Wanneer de client om een pseudo-terminal vraagt, reist TERM mee met dat verzoek. De handleiding van OpenSSH is expliciet: "de TERM-omgevingsvariabele wordt altijd verzonden wanneer een pseudo-terminal wordt aangevraagd, aangezien dit vereist is door het protocol". Uw login-shell op de VPS ontvangt dus TERM=xterm-ghostty, of xterm-kitty, of welke naam uw emulator ook gebruikt. De beschrijving achter die naam blijft op uw laptop staan, in de database van uw laptop. Een server die gebouwd is voordat uw emulator bestond, heeft nog nooit van die naam gehoord. Niets in de SSH-verbinding zelf kopieert terminalbeschrijvingen, en dat is een bewuste keuze: het protocol draagt een naam, geen dump van mogelijkheden.

Reproduceer de fout op uw eigen machine met een naam die gegarandeerd niet bestaat:

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

tput: unknown terminal "xterm-nosuchthing"

De exit-status is 3, wat ncurses documenteert als een onbekend terminaltype of een ontbrekende database. Elk curses-programma voert dezelfde opzoekactie uit, dus één ontbrekende naam produceert een andere melding bij elk programma, terwijl de oorzaak voor allemaal hetzelfde is. nano stopt met Error opening terminal: xterm-nosuchthing., de standaard ncurses-foutmelding wanneer het bij het opstarten geen beschrijving kan laden. vim print E558: Terminal entry not found in terminfo. less print WARNING: terminal is not fully functional. Een pager die half werkt en een editor die weigert te starten lijken op ongerelateerde bugs. Het is hetzelfde ontbrekende bestand.

Waar ncurses zoekt naar de entry

ncurses doorzoekt locaties in een vaste volgorde, zoals gedocumenteerd in terminfo(5):

1. $TERMINFO, indien deze is ingesteld. Alleen die map wordt doorzocht.
2. $HOME/.terminfo.
3. elke map die wordt vermeld in $TERMINFO_DIRS.
4. de ingebouwde locaties, die op Debian en Ubuntu bestaan uit /etc/terminfo, /lib/terminfo en /usr/share/terminfo.

Voer infocmp -D uit op de server om de lijst af te drukken die de eigen ncurses-build gebruikt, in plaats van te vertrouwen op de bovenstaande paden. Stap 2 is de gehele truc. Uw home-map wordt doorzocht vóór elke systeemmap, dus één bestand onder ~/.terminfo lost de lookup voor uw account op zonder pakketinstallatie en zonder root.

Oplossing 1: gebruik een TERM die de server al kent

De snelste manier om de blokkade op te heffen is door voor één verbinding een andere terminalnaam op te geven:

TERM=xterm-256color ssh user@203.0.113.10

Maak dit permanent voor die host in ~/.ssh/config op uw laptop:

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

SetEnv vereist OpenSSH 7.8 of nieuwer op de client, uitgebracht in augustus 2018. TERM is de enige variabele waarvoor geen toestemming van de server nodig is: de handleiding stelt: "Net als bij SendEnv, met uitzondering van de TERM-variabele, moet de server bereid zijn de omgevingsvariabele te accepteren". Dit werkt dus zelfs tegen een beveiligde sshd zonder enige AcceptEnv-regel.

Wat dit kost: alles wat uw emulator beschrijft buiten de standaard xterm-256color. Dit omvat 24-bit kleur die wordt geadverteerd via de RGB-mogelijkheid en gestileerde onderstrepingen via Smulx. Programma's kunnen die mogelijkheden niet langer zien, dus vallen ze terug op 256 kleuren en een standaard onderstreping. Het scherm werkt. Het is simpelweg minder geavanceerd dan de terminal die u heeft gekozen.

Los dit niet op door export TERM=xterm-256color toe te voegen aan uw .bashrc op de server. Dat bestand wordt uitgevoerd bij elke verbinding, inclusief verbindingen vanaf een terminal waarvan de server de naam wel kent, waardoor sessies die al correct werkten worden gedegradeerd. Houd de override op de client, waar u weet welke emulator u gebruikt.

Oplossing 2: stuur uw terminfo-entry eenmalig naar de server

Dit is de oplossing waarmee uw emulator intact blijft. Decompileer de entry lokaal, stuur deze via SSH door en compileer deze aan de ontvangende kant:

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

infocmp -x print de entry voor uw huidige TERM als brontekst, inclusief uitgebreide (door de gebruiker gedefinieerde) functionaliteiten. tic -x compileert die brontekst terug naar een binaire beschrijving op de server. De -x aan beide kanten is van belang, omdat zonder deze vlag functionaliteiten zoals Smulx tijdens het transport verloren gaan en u een gedegradeerde kopie van uw eigen terminal verstuurt.

tic schrijft naar de systeemmappen wanneer dit mogelijk is, en valt terug op $HOME/.terminfo wanneer de gebruiker daar geen schrijfrechten heeft. Een standaardaccount op een VPS gebruikt de thuismap, wat precies is wat u wilt. U kunt ook de doelbestemming opgeven:

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

De aanhalingstekens rond ~/.terminfo zijn geen versiering. ssh voegt de commando-onderdelen samen tot één string en geeft deze door aan de externe shell; een niet-gequote ~ wordt namelijk eerst door uw lokale shell geëxpandeerd. U stuurt dan een letterlijke /home/yourname/.terminfo naar een machine waar uw account mogelijk een andere naam heeft. tic faalt dan met een toegangsrechtenfout, of schrijft naar een pad dat ncurses nooit doorzoekt. Quote de tilde zodat de externe shell deze expandeert.

Log in en controleer:

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

tput longname dat de beschrijving van uw terminal wordt geprint, betekent dat het opzoeken nu slaagt, en ls toont het gecompileerde bestand in een submap die vernoemd is naar de eerste letter van de terminalnaam. Voer daarna top uit, of watch -n1 uptime, die de weergave ververst via dezelfde bibliotheek, om te bevestigen dat een echt curses-programma het scherm correct tekent.

Wat het kost: één stap per server, en de entry bevindt zich in de thuismap van één account op één machine. Bouw de VPS opnieuw op en de entry is verdwenen. Voeg het commando toe aan de tool die u gebruikt voor het provisioneren en beheren van meerdere servers tegelijk, zodat een nieuwe host direct met de gecompileerde entry wordt opgeleverd.

Oplossing 3: installeer de uitgebreide terminfo-database

Als u root-toegang heeft en wilt dat de naam voor elk account op de server wordt opgelost:

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

ncurses-term bevat de terminalbeschrijvingen die in de basisinstallatie ontbreken. Dit lost de naam op voor root en voor elke andere gebruiker, wat bij oplossing 2 niet het geval is.

Dit helpt alleen als de entry van uw terminal bestaat in de ncurses-release die uw distributie meelevert; controleer dit dus in plaats van ervan uit te gaan. Ubuntu 24.04 levert ncurses-bin 6.4+20240113-1ubuntu2.1 (stand augustus 2026). De entry voor Ghostty is upstream toegevoegd in ncurses 6.5-20241228, wat nieuwer is. Daarom kan apt install ncurses-term op Ubuntu 24.04 geen xterm-ghostty-entry genereren, hoe vaak u het ook uitvoert. tput -T <name> longname is de controle: het print de beschrijving als de entry aanwezig is, en unknown terminal met exit-status 3 als dat niet zo is.

Om een enkele entry systeembreed te installeren in plaats van het hele pakket, kopieert u de broncode en compileert u deze als 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

De -t in het tweede commando wijst een pseudo-terminal toe, zodat sudo om het wachtwoord kan vragen. Zonder dit argument kan sudo afsluiten met sudo: no tty present and no askpass program specified.

Laat de emulator de overdracht uitvoeren

Sommige emulators bevatten een hulpfunctie die correctie 2 voor u uitvoert. kitty heeft een ssh kitten: kitten ssh myserver maakt verbinding en kopieert de terminfo van kitty automatisch naar de externe host. De documentatie biedt ook de handmatige vorm, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, waarbij de tilde is geëscaped om de hierboven beschreven reden. Ghostty documenteert infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - en levert shell-integratie (ssh-env en ssh-terminfo) plus een +ssh-actie die beide correcties automatiseert.

Deze hulpfuncties voeren dezelfde commando's uit die u zojuist handmatig heeft uitgevoerd. Het is nog steeds van belang om de handmatige vorm te kennen, omdat de hulpfunctie niet kan ingrijpen wanneer de verbinding elders start, zoals op een jump host of binnen een script.

Wanneer de fout terugkeert

Onder sudo -i. Een login-shell als root heeft HOME=/root, en sudo behoudt uw TERM. ncurses doorzoekt nu /root/.terminfo, dat uw invoer niet bevat, waardoor de foutmelding alleen voor root terugkeert. Bevestig dit met sudo -i env en lees de regels HOME en TERM. Installeer de invoer in de systeemdirectory of plaats een kopie in /root/.terminfo.

Binnen tmux of screen. Deze stellen hun eigen TERM in voor de programma's die erin draaien, meestal screen-256color of tmux-256color. Een oudere server kent screen-256color en kent mogelijk tmux-256color niet, waardoor de buitenste shell correct functioneert terwijl alles binnen de sessie faalt. Dezelfde oorzaak, andere naam. Voer tput -T tmux-256color longname uit op de server om te zien welke van de twee aanwezig is. Een terminal-werkbank gebouwd rond tmux verbergt dit totdat u op een dag verbinding maakt vanaf een host die u nog niet heeft gecorrigeerd.

Op een nieuwe server. ~/.terminfo is per account en per machine, dus een opnieuw geïnstalleerde VPS begint weer leeg.

Scherm tekent, toetsen werken niet naar behoren. Als het beeld in orde is, maar Home, End of de functietoetsen vreemde tekens invoegen, dan is de naam opgelost naar een invoer die niet overeenkomt met uw terminal. Toetssequenties zijn afkomstig van dezelfde terminfo-invoer als de tekenmogelijkheden, dus een benaderende invoer geeft benaderende toetsen. Dat is het gebruikelijke resultaat van fix 1 op een emulator waarvan de toetssequenties afwijken van xterm. Fix 2 is het antwoord, omdat alleen de werkelijke invoer van uw emulator de juiste sequenties bevat.

FAQ

Waarom zie ik alleen "unknown terminal type" via SSH?

Omdat de database die de definitie van uw terminal moet bevatten, zich op de server bevindt. Uw emulator installeert de beschrijving op de machine waarop deze draait, waardoor lokale programma's deze zonder extra inspanning vinden. SSH verstuurt alleen de waarde van TERM, aangezien het protocol die naam meeneemt met het pseudo-terminalverzoek. De externe ncurses zoekt de naam op in de externe database en vindt niets, waardoor initscr faalt en het programma stopt.

Kan ik dit oplossen zonder root-rechten op de server?

Ja. ncurses doorzoekt $HOME/.terminfo vóór elke systeemmap, dus een definitie op die locatie is voldoende voor uw account. Voer infocmp -x | ssh user@host -- tic -x - eenmalig uit per server. tic schrijft naar uw home-directory wanneer het niet naar het systeempad kan schrijven, wat de normale situatie is voor een account zonder privileges. Log in en voer tput longname uit om te bevestigen dat de opzoekactie nu correct verloopt.

Wat verlies ik door TERM=xterm-256color in te stellen voor een host?

Elke functionaliteit die uw emulator beschrijft buiten de xterm-256color-definitie, zoals 24-bit kleur via RGB en gestileerde onderstrepingen via Smulx. Programma's kunnen die mogelijkheden niet zien, waardoor ze terugvallen op de meest nabije optie. Functietoetsreeksen kunnen ook afwijken van uw werkelijke terminal. Plaats de instelling op de client in ~/.ssh/config in plaats van in een .bashrc op de server, aangezien dat sessies van terminals die al werkten zou degraderen.

Waarom keert de fout terug na sudo -i?

sudo -i start een login-shell als root met HOME=/root, terwijl uw TERM-waarde behouden blijft. ncurses doorzoekt vervolgens /root/.terminfo in plaats van uw eigen home-directory en vindt niets, waardoor root dezelfde fout ziet die uw account niet langer ervaart. Voer sudo -i env uit en controleer de HOME- en TERM-regels. Compileer de definitie in de systeemmap met sudo tic -x -o /usr/share/terminfo, of kopieer deze naar /root/.terminfo.

Lost apt install ncurses-term het altijd op?

Nee. Het voegt alleen de definities toe die bestonden in de ncurses-release die uw distributie heeft verpakt. Ubuntu 24.04 levert ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.1, per augustus 2026), en de definitie van Ghostty werd upstream toegevoegd in ncurses 6.5-20241228, dus dat pakket kan deze niet bevatten. Controleer met tput -T <name> longname voordat u op het pakket vertrouwt, en lever de definitie zelf aan wanneer de controle nog steeds een onbekende terminal rapporteert.