Cara Mengatasi 'unknown terminal type' lewat SSH

Apa arti "unknown terminal type"

Error unknown terminal type melalui SSH berarti nama dalam TERM tidak memiliki entri yang cocok dalam database terminfo di server. Emulator Anda menetapkan nama tersebut pada laptop Anda. Database yang harus mengenalinya berada di mesin remote. Jika pencarian gagal, setiap program curses pada server berhenti sebelum menampilkan apa pun karena program tersebut tidak memiliki deskripsi kemampuan terminal Anda.

Perbaikannya tetap mempertahankan semua fitur emulator Anda: kompilasikan entri terminfo sendiri ke ~/.terminfo pada server. ncurses mencari database tersebut di direktori home Anda sebelum direktori sistem mana pun. Karena itu, Anda tidak memerlukan root dan tidak mengubah apa pun untuk pengguna lain.

TERM adalah nama, sedangkan terminfo adalah database

TERM menyimpan satu string, dan string tersebut hanya berupa key. terminfo adalah database terkompilasi yang berisi deskripsi terminal. Key tersebut digunakan program untuk menemukan deskripsi yang sesuai. Deskripsi itu mencatat jumlah warna yang didukung terminal, byte yang memindahkan kursor ke baris 12 kolom 40, byte yang dikirim oleh tombol F5, serta apakah terminal dapat menampilkan garis bawah dengan gaya tertentu. ncurses, yaitu library yang digunakan untuk membangun hampir semua antarmuka pengguna berbasis teks di Linux, membaca deskripsi tersebut saat start. Program seperti top, less, nano, dan watch tidak dapat menampilkan satu layar pun tanpanya.

Lihat entry Anda sendiri:

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

tput longname mencetak deskripsi yang dapat dibaca manusia dari apa pun yang ditetapkan oleh TERM. Untuk xterm-256color, perintah tersebut mencetak:

xterm with 256 colors

infocmp -1 mendekompilasi seluruh entry dan mencetak satu capability per baris. Jika kedua perintah berhasil, database pada mesin ini mengenali terminal tersebut. Kondisi yang sama juga diperlukan di sisi lain koneksi SSH.

Mengapa masalah ini hanya terjadi melalui SSH

SSH mengirimkan nama terminal dan tidak mengirimkan hal lain. Saat klien meminta pseudo-terminal, TERM dikirim bersama permintaan tersebut. Manual OpenSSH menjelaskannya secara eksplisit: "variabel lingkungan TERM selalu dikirim setiap kali pseudo-terminal diminta karena diperlukan oleh protokol". Jadi, shell login Anda pada VPS menerima TERM=xterm-ghostty, atau xterm-kitty, atau nama apa pun yang digunakan emulator Anda. Deskripsi di balik nama tersebut tetap berada pada laptop Anda, di basis data laptop Anda. Server yang dibuat sebelum emulator Anda ada tidak pernah mengenal nama tersebut. Tidak ada bagian dari koneksi SSH itu sendiri yang menyalin deskripsi terminal, dan ini memang disengaja: protokol hanya membawa nama, bukan seluruh kapabilitas.

Reproduksi kegagalan tersebut pada mesin Anda sendiri menggunakan nama yang pasti tidak ada:

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

tput: unknown terminal "xterm-nosuchthing"

Status keluar adalah 3, yang didokumentasikan oleh ncurses sebagai jenis terminal yang tidak dikenal atau basis data yang tidak tersedia. Setiap program curses melakukan pencarian yang sama. Karena itu, satu nama yang hilang menghasilkan pesan yang berbeda dari setiap program, dengan satu penyebab yang sama. nano berhenti dengan Error opening terminal: xterm-nosuchthing., yaitu kegagalan ncurses standar saat tidak dapat memuat deskripsi ketika dijalankan. vim mencetak E558: Terminal entry not found in terminfo. less mencetak WARNING: terminal is not fully functional. Pager yang hanya berfungsi sebagian dan editor yang menolak dijalankan tampak seperti bug yang tidak berkaitan. Keduanya disebabkan oleh file yang sama-sama hilang.

Lokasi ncurses mencari entri

ncurses mencari entri dalam urutan tetap yang didokumentasikan di terminfo(5):

1. $TERMINFO, jika variabel tersebut ditetapkan. Hanya direktori itu yang dicari.
2. $HOME/.terminfo.
3. setiap direktori yang tercantum dalam $TERMINFO_DIRS.
4. lokasi yang dikompilasi ke dalam ncurses. Pada Debian dan Ubuntu, lokasi tersebut mencakup /etc/terminfo, /lib/terminfo, dan /usr/share/terminfo.

Jalankan infocmp -D di server untuk menampilkan daftar yang digunakan oleh build ncurses pada server tersebut. Jangan hanya mengandalkan path di atas. Langkah 2 adalah inti solusinya. Direktori home Anda dicari sebelum direktori sistem mana pun. Jadi, satu file di bawah ~/.terminfo memperbaiki pencarian untuk akun Anda tanpa menginstal paket dan tanpa akses root.

Perbaikan 1: gunakan TERM yang sudah dikenali server

Cara tercepat untuk mengatasi masalah ini adalah menetapkan terminal lain untuk satu koneksi:

TERM=xterm-256color ssh user@203.0.113.10

Agar berlaku permanen untuk host tersebut, tambahkan pengaturan ini ke ~/.ssh/config di laptop Anda:

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

SetEnv memerlukan OpenSSH 7.8 atau yang lebih baru pada client, yang dirilis pada Agustus 2018. TERM adalah satu-satunya variabel yang tidak memerlukan izin server. Manual menyatakan, "Seperti SendEnv, kecuali untuk variabel TERM, server harus disiapkan untuk menerima variabel lingkungan tersebut." Jadi, cara ini tetap berfungsi pada sshd yang diperketat, meskipun tidak memiliki baris AcceptEnv sama sekali.

Konsekuensinya adalah semua kemampuan yang dijelaskan emulator Anda di luar xterm-256color biasa tidak tersedia. Ini mencakup warna 24-bit yang diiklankan melalui kemampuan RGB dan garis bawah bergaya melalui Smulx. Program tidak lagi dapat mendeteksi kemampuan tersebut, sehingga kembali menggunakan 256 warna dan garis bawah biasa. Layar tetap berfungsi. Kemampuannya hanya lebih terbatas dibandingkan terminal yang Anda pilih.

Jangan mengatasi masalah ini dengan menambahkan export TERM=xterm-256color ke .bashrc di server. File tersebut dijalankan untuk setiap koneksi, termasuk koneksi dari terminal yang namanya sudah dikenali server. Akibatnya, sesi yang sebelumnya sudah berfungsi akan diturunkan kemampuannya. Pertahankan penggantian ini di client, karena di sana Anda mengetahui emulator yang sedang digunakan.

Perbaikan 2: kirim entri terminfo Anda ke server satu kali

Perbaikan ini mempertahankan emulator Anda. Dekompilasi entri secara lokal, teruskan melalui SSH, lalu kompilasi di sisi server:

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

infocmp -x mencetak entri untuk TERM Anda saat ini sebagai teks sumber, termasuk kemampuan tambahan (yang ditentukan pengguna). tic -x mengompilasi kembali sumber tersebut menjadi deskripsi biner di server. -x pada kedua sisi penting, karena tanpa opsi tersebut, kemampuan seperti Smulx akan hilang selama transfer dan Anda akan mengirim salinan terminal Anda sendiri dengan kemampuan yang lebih rendah.

tic menulis ke direktori sistem jika memungkinkan, lalu menggunakan $HOME/.terminfo sebagai fallback jika pengguna tidak memiliki akses tulis ke direktori tersebut. Akun biasa pada VPS menggunakan direktori home, dan itulah yang Anda perlukan. Anda juga dapat menentukan tujuan:

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

Tanda kutip di sekitar ~/.terminfo bukan hiasan. ssh menggabungkan kata-kata perintah menjadi satu string dan menyerahkannya kepada shell remote. Karena itu, ~ yang tidak diberi tanda kutip akan diperluas terlebih dahulu oleh shell lokal Anda. Anda kemudian mengirim /home/yourname/.terminfo literal ke mesin yang mungkin menggunakan nama akun berbeda. tic akan gagal dengan error izin, atau menulis ke path yang tidak pernah dicari oleh ncurses. Beri tanda kutip pada tilde agar shell remote yang memperluasnya.

Login dan periksa:

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

tput longname yang mencetak deskripsi terminal Anda berarti pencarian kini berhasil, dan ls menampilkan file yang telah dikompilasi di bawah subdirektori yang namanya berasal dari huruf pertama nama terminal. Selanjutnya, jalankan top, atau pantau uptime dengan watch -n1, yang menggambar ulang tampilan melalui library yang sama, untuk memastikan program curses yang sebenarnya dapat menampilkan layar.

Konsekuensinya: satu langkah per server, dan entri tersebut tersimpan di direktori home satu akun pada satu mesin. Jika VPS dibuat ulang, entri itu akan hilang. Masukkan perintah tersebut ke alat yang Anda gunakan untuk melakukan provisioning dan mengelola beberapa server sekaligus agar host baru sudah memiliki entri yang dikompilasi.

Perbaikan 3: instal database terminfo lengkap

Jika Anda memiliki akses root dan ingin nama tersebut dapat ditemukan untuk setiap akun pada server:

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

ncurses-term berisi deskripsi terminal yang tidak disertakan dalam instalasi dasar. Ini memperbaiki nama tersebut untuk root dan semua pengguna lain, sedangkan perbaikan 2 tidak.

Ini hanya membantu jika entri terminal Anda tersedia dalam rilis ncurses yang dikemas oleh distribusi Anda. Karena itu, lakukan pemeriksaan dan jangan berasumsi. Ubuntu 24.04 menyertakan ncurses-bin 6.4+20240113-1ubuntu2.1 (per Agustus 2026). Entri Ghostty ditambahkan upstream dalam ncurses 6.5-20241228, yang lebih baru. Karena itu, apt install ncurses-term pada Ubuntu 24.04 tidak dapat menghasilkan entri xterm-ghostty, sesering apa pun Anda menjalankannya. tput -T <name> longname adalah pemeriksaannya: perintah ini mencetak deskripsi jika entri tersedia, dan unknown terminal dengan status keluar 3 jika entri tidak tersedia.

Untuk menginstal satu entri secara global, bukan seluruh paket, salin sumbernya lalu kompilasikan sebagai 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 pada perintah kedua mengalokasikan pseudo-terminal agar sudo dapat meminta kata sandi. Tanpa opsi tersebut, sudo dapat keluar dengan sudo: no tty present and no askpass program specified.

Biarkan emulator melakukan transfer

Beberapa emulator menyediakan helper yang menerapkan perbaikan 2 secara otomatis. kitty memiliki kitten ssh: kitten ssh myserver terhubung dan menyalin terminfo kitty ke host remote secara otomatis. Dokumentasinya juga mencantumkan bentuk manual, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, dengan karakter tilde yang di-escape karena alasan yang dijelaskan di atas. Ghostty mendokumentasikan infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -, serta menyediakan integrasi shell (ssh-env dan ssh-terminfo) dan action +ssh yang mengotomatiskan kedua perbaikan tersebut.

Helper ini menjalankan perintah yang sama seperti yang baru saja Anda jalankan secara manual. Bentuk manual tetap penting karena helper tidak dapat bertindak ketika koneksi dimulai dari tempat lain, seperti pada jump host atau di dalam script.

Saat error muncul kembali

Di bawah sudo -i. Shell login sebagai root memiliki HOME=/root, dan sudo mempertahankan TERM Anda. ncurses sekarang mencari /root/.terminfo, yang tidak memiliki entri Anda, sehingga kegagalan kembali terjadi hanya untuk root. Konfirmasikan dengan sudo -i env, lalu baca baris HOME dan TERM. Instal entri tersebut ke direktori sistem, atau letakkan salinannya di /root/.terminfo.

Di dalam tmux atau screen. Keduanya menetapkan TERM sendiri untuk program yang berjalan di dalamnya, biasanya screen-256color atau tmux-256color. Server yang lebih lama mengenali screen-256color dan mungkin tidak mengenali tmux-256color, sehingga shell luar berjalan normal sementara semua yang ada di dalam sesi gagal. Penyebabnya sama, tetapi namanya berbeda. Jalankan tput -T tmux-256color longname pada server untuk melihat nama yang tersedia di antara keduanya. Workbench terminal berbasis tmux dapat menyembunyikan masalah ini sampai Anda melakukan attach pada host yang belum diperbaiki.

Pada server baru. ~/.terminfo berlaku per akun dan per mesin, sehingga VPS yang dibangun ulang kembali kosong.

Layar tampil, tetapi tombol bermasalah. Jika tampilan normal, tetapi tombol Home, End, atau tombol fungsi memasukkan karakter yang tidak semestinya, nama tersebut mengarah ke entri yang tidak sesuai dengan terminal Anda. Urutan tombol berasal dari entri terminfo yang sama dengan kapabilitas tampilan, sehingga entri perkiraan menghasilkan perilaku tombol yang juga tidak tepat. Ini biasanya terjadi setelah perbaikan 1 pada emulator yang urutan tombolnya berbeda dari xterm. Perbaikan 2 adalah solusinya karena hanya entri emulator Anda yang sebenarnya yang memiliki urutan yang benar.

FAQ

Mengapa saya hanya melihat pesan "unknown terminal type" melalui SSH?

Karena database yang harus memuat entri terminal Anda berada di server. Emulator Anda memasang deskripsinya pada mesin tempat emulator tersebut berjalan, sehingga program lokal dapat menemukannya tanpa tindakan tambahan dari Anda. SSH hanya mengirim nilai TERM karena protokol membawa nama tersebut bersama permintaan pseudo-terminal. ncurses di remote mencari nama itu dalam database remote, tetapi tidak menemukannya. Akibatnya, initscr gagal dan program berhenti.

Apakah saya dapat memperbaikinya tanpa akses root di server?

Ya. ncurses mencari $HOME/.terminfo sebelum direktori sistem mana pun, sehingga entri di sana sudah cukup untuk akun Anda. Jalankan infocmp -x | ssh user@host -- tic -x - sekali untuk setiap server. tic menulis ke direktori home Anda jika tidak dapat menulis ke path sistem, yang merupakan kondisi normal untuk akun tanpa hak istimewa. Login lalu jalankan tput longname untuk memastikan pencarian kini berhasil.

Apa yang hilang jika saya menetapkan TERM=xterm-256color untuk suatu host?

Semua kapabilitas yang dijelaskan emulator Anda di luar entri xterm-256color, seperti warna 24-bit melalui RGB dan garis bawah bergaya melalui Smulx. Program tidak dapat melihat kapabilitas tersebut, sehingga menggunakan fallback terdekat. Urutan tombol fungsi juga dapat berbeda dari terminal sebenarnya. Terapkan pengaturan pada client di ~/.ssh/config, bukan dalam .bashrc di server, karena pengaturan tersebut akan menurunkan kapabilitas sesi dari terminal yang sebelumnya sudah berfungsi.

Mengapa error muncul lagi setelah sudo -i?

sudo -i memulai login shell sebagai root dengan HOME=/root, tetapi tetap mempertahankan nilai TERM Anda. ncurses kemudian mencari /root/.terminfo, bukan direktori home Anda sendiri, dan tidak menemukan apa pun. Akibatnya, root mengalami kegagalan yang sama, sementara akun Anda tidak lagi mengalaminya. Jalankan sudo -i env, lalu periksa baris HOME dan TERM. Compile entri tersebut ke dalam direktori sistem dengan sudo tic -x -o /usr/share/terminfo, atau salin ke /root/.terminfo.

Apakah apt install ncurses-term selalu memperbaikinya?

Tidak. Perintah tersebut hanya menambahkan entri yang tersedia dalam rilis ncurses yang dipaketkan oleh distribusi Anda. Ubuntu 24.04 merilis ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.1, per Agustus 2026), sedangkan entri Ghostty ditambahkan upstream dalam ncurses 6.5-20241228. Karena itu, paket tersebut tidak dapat memuatnya. Periksa dengan tput -T <name> longname sebelum mengandalkan paket tersebut. Jika hasil pemeriksaan masih melaporkan terminal yang tidak dikenal, sediakan entri itu sendiri.