Sửa lỗi SSH “unknown terminal type” không cần root
Lỗi “unknown terminal type” làm chương trình curses qua SSH dừng vì server thiếu terminfo. Compile entry vào ~/.terminfo để sửa, không cần root.
Ý nghĩa của lỗi "unknown terminal type"
Lỗi "unknown terminal type" qua SSH có nghĩa là tên trong TERM không có entry tương ứng trong cơ sở dữ liệu terminfo trên server. Terminal emulator của bạn đặt tên đó trên laptop. Cơ sở dữ liệu cần nhận diện tên này nằm trên máy từ xa. Khi tra cứu thất bại, mọi chương trình curses trên server đó đều dừng trước khi vẽ bất kỳ nội dung nào, vì không có mô tả về khả năng của terminal bạn đang dùng.
Cách khắc phục mà vẫn giữ toàn bộ tính năng của terminal emulator là chạy một command để compile entry terminfo của riêng bạn vào ~/.terminfo trên server. Với bản build tiêu chuẩn như Debian, ncurses sẽ tìm trong thư mục home của bạn trước mọi thư mục hệ thống (chỉ biến $TERMINFO, nếu được đặt, mới được kiểm tra trước), nên không cần root và không thay đổi gì đối với người dùng khác. Việc tra cứu trong thư mục home là tùy chọn trong ncurses, vì vậy bước kiểm tra sau khi khắc phục là cần thiết.
TERM là tên, terminfo là cơ sở dữ liệu
TERM chứa một chuỗi, và chuỗi đó chỉ là một key. terminfo là cơ sở dữ liệu đã biên dịch chứa các mô tả terminal, còn key là cách để chương trình tìm đúng mô tả. Một mô tả ghi lại terminal có bao nhiêu màu, những byte nào di chuyển con trỏ đến hàng 12 cột 40, phím F5 gửi những byte nào và terminal có thể hiển thị gạch chân có kiểu hay không. ncurses, thư viện mà gần như mọi giao diện người dùng dạng văn bản trên Linux đều sử dụng, đọc mô tả đó khi khởi động. Các chương trình như top, less, nano và watch không thể hiển thị dù chỉ một màn hình nếu thiếu mô tả này.
Xem entry của chính bạn:
echo "$TERM"
tput longname
infocmp -1 | head -20tput longname in mô tả ở dạng người có thể đọc của entry mà TERM chỉ định. Với xterm-256color, lệnh này in:
xterm with 256 colorsinfocmp -1 dịch ngược entry và in mỗi capability trên một dòng. Lệnh này bỏ qua các capability mở rộng do người dùng định nghĩa, trừ khi bạn thêm -x, như trong infocmp -1 -x. Nếu cả hai lệnh đều chạy được, cơ sở dữ liệu trên máy này đã biết terminal này. Bạn cũng cần trạng thái tương tự ở đầu bên kia của kết nối SSH.
Vì sao lỗi chỉ xảy ra khi dùng SSH
SSH chỉ gửi tên terminal, không gửi thêm thông tin nào khác. Khi client yêu cầu pseudo-terminal, TERM được gửi cùng yêu cầu đó. Manual của OpenSSH nêu rõ: "biến môi trường TERM luôn được gửi khi pseudo-terminal được yêu cầu vì giao thức cần biến này". Vì vậy, login shell trên VPS nhận được TERM=xterm-ghostty, xterm-kitty hoặc tên mà terminal emulator của bạn đang dùng. Mô tả tương ứng với tên đó vẫn nằm trên laptop, trong database của laptop. Một server được xây dựng trước khi terminal emulator của bạn tồn tại chưa từng biết đến tên này. Không có thành phần nào trong kết nối SSH tự nó sao chép mô tả terminal, và đây là chủ ý thiết kế: giao thức chỉ truyền tên, không truyền toàn bộ thông tin về capability.
Bạn có thể tái hiện lỗi trên máy của mình bằng một tên chắc chắn không tồn tại:
TERM=xterm-nosuchthing tput colors
echo "$?"tput: unknown terminal "xterm-nosuchthing"Exit status là 3. Manual của tput mô tả giá trị này là "loại terminal không được nhận dạng". Mọi chương trình curses đều thực hiện cùng một lần tra cứu. Vì vậy, một tên bị thiếu tạo ra thông báo khác nhau trong từng chương trình, nhưng nguyên nhân phía sau đều là một. nano dừng với Error opening terminal: xterm-nosuchthing., lỗi chuẩn của ncurses khi không thể tải mô tả lúc khởi động. vim in E558: Terminal entry not found in terminfo. less in WARNING: terminal is not fully functional. Một pager hoạt động không đầy đủ và một editor từ chối khởi động trông như hai lỗi không liên quan. Thực ra chúng cùng thiếu một file.
ncurses tìm entry ở đâu
ncurses tìm kiếm theo thứ tự cố định, được ghi trong terminfo(5):
$TERMINFO, nếu biến này được đặt. Đây là nơi được kiểm tra đầu tiên.$HOME/.terminfo. Tài liệu gọi đây là “một tính năng tùy chọn có thể bị loại bỏ hoàn toàn khỏi thư viện”, hoặc có thể giới hạn để các chương trình có quyền đặc biệt không vô tình sử dụng nó.- mọi thư mục được liệt kê trong
$TERMINFO_DIRS. - các vị trí được biên dịch sẵn vào thư viện. Trên Debian và Ubuntu, các vị trí này gồm
/etc/terminfo,/lib/terminfovà/usr/share/terminfo.
Chạy infocmp -D trên server để in danh sách mà bản build ncurses của chính server đó sử dụng, thay vì tin vào các đường dẫn ở trên. Bước 2 là mấu chốt. Bản build ncurses của Debian không tắt tính năng này. Khi tính năng có mặt, thư mục home của bạn được tìm kiếm trước mọi thư mục hệ thống. Vì vậy, một file trong ~/.terminfo có thể sửa lookup cho tài khoản của bạn mà không cần cài package và không cần root. Chạy tput longname sau khi sửa để kiểm tra bản build trên server có hỗ trợ cơ chế này hay không. Ngoại lệ duy nhất là bước 1: nếu echo "$TERMINFO" in ra một vị trí trên server, vị trí đó được kiểm tra trước. Một entry tại đó có cùng tên sẽ được ưu tiên hơn entry của bạn.
Cách khắc phục 1: dùng TERM mà server đã biết
Cách bỏ chặn nhanh nhất là chỉ định một terminal khác cho một kết nối:
TERM=xterm-256color ssh user@203.0.113.10Để áp dụng vĩnh viễn cho host đó trong ~/.ssh/config trên laptop của bạn:
Host vps1
HostName 203.0.113.10
User deploy
SetEnv TERM=xterm-256colorDùng SetEnv để ghi đè TERM yêu cầu client chạy OpenSSH 8.7 trở lên, được phát hành vào tháng 8 năm 2021. Client cũ hơn vẫn gửi TERM của emulator, bất kể có dòng này hay không. TERM là biến duy nhất không cần server cho phép: tài liệu hướng dẫn ghi rằng “Tương tự SendEnv, ngoại trừ biến TERM, server phải được cấu hình để chấp nhận biến môi trường”. Vì vậy, cách này vẫn hoạt động với sshd đã được harden và hoàn toàn không có dòng AcceptEnv.
Đổi lại, bạn mất mọi khả năng mà emulator mô tả ngoài xterm-256color cơ bản. Trong đó có màu 24-bit được quảng bá qua capability RGB và gạch chân có kiểu qua Smulx. Các chương trình dựa vào entry terminfo sẽ không còn thấy những capability này, nên chúng chuyển về 256 màu và gạch chân thường, trừ khi bạn cấu hình để chúng vẫn gửi các sequence tương ứng. Ví dụ, Vim vẫn có thể hiển thị màu 24-bit bằng set termguicolors, vì các sequence t_8f và t_8b tích hợp sẵn của Vim hoạt động với hầu hết terminal. Màn hình vẫn hiển thị được. Chỉ là terminal này có ít capability hơn terminal bạn đã chọn.
Không khắc phục bằng cách thêm export TERM=xterm-256color vào .bashrc trên server. File đó được chạy cho mọi kết nối, bao gồm cả kết nối từ terminal mà server đã biết tên, nên nó sẽ hạ capability của những session vốn đã hoạt động bình thường. Hãy giữ override ở client, nơi bạn biết mình đang chạy emulator nào.
Sửa 2: gửi entry terminfo lên server một lần
Đây là cách sửa vẫn giữ nguyên emulator của bạn. Decompile entry trên máy cục bộ, pipe qua SSH rồi compile ở máy đích:
infocmp -x | ssh user@203.0.113.10 -- tic -x -infocmp -x in entry của TERM hiện tại dưới dạng source text, bao gồm cả các capability mở rộng (do người dùng tự định nghĩa). tic -x compile source đó trở lại thành binary description trên server. -x ở cả hai phía rất quan trọng, vì nếu thiếu nó thì các capability như Smulx sẽ bị loại bỏ trong quá trình truyền, khiến bạn triển khai một bản terminal của chính mình đã bị hạ cấp.
tic ghi vào system directory nếu có thể, rồi fallback sang $HOME/.terminfo khi user không có quyền ghi tại đó. Account thông thường trên VPS sẽ dùng home directory, đúng với mục đích ở đây. Bạn cũng có thể chỉ định destination:
infocmp -x | ssh user@203.0.113.10 -- tic -x -o '~/.terminfo' /dev/stdinDấu ngoặc kép quanh ~/.terminfo không phải để trang trí. ssh nối các từ của command thành một string rồi truyền cho remote shell, nên ~ không có dấu ngoặc kép sẽ được local shell mở rộng trước. Sau đó bạn gửi một /home/yourname/.terminfo literal đến máy mà account của bạn có thể mang tên khác. tic sẽ fail với lỗi permission, hoặc ghi vào một path mà ncurses không bao giờ tìm kiếm. Hãy đặt dấu ngoặc kép quanh dấu ngã để remote shell mở rộng nó.
Đăng nhập rồi kiểm tra:
ssh user@203.0.113.10
tput longname
ls -R ~/.terminfotput longname in ra description của terminal, cho biết việc lookup đã thành công. ls hiển thị compiled file bên trong một subdirectory được đặt tên theo chữ cái đầu tiên của tên terminal. Sau đó chạy top, hoặc dùng watch -n1 uptime để redraw qua cùng library, nhằm xác nhận một chương trình curses thực sự render được màn hình.
Chi phí là một bước cho mỗi server, và entry nằm trong home directory của một account trên một máy duy nhất. Nếu rebuild VPS thì entry sẽ mất. Đưa command này vào công cụ bạn dùng để provision và quản lý nhiều server cùng lúc để host mới có entry được compile sẵn.
Cách khắc phục 3: cài cơ sở dữ liệu terminfo mở rộng
Nếu bạn có quyền root và muốn tên này được phân giải cho mọi account trên máy:
sudo apt update
sudo apt install ncurses-term
tput -T xterm-ghostty longnamencurses-term chứa các mô tả terminal bị bản cài đặt cơ sở lược bỏ. Nó sửa lỗi tên cho root và mọi user khác, điều mà cách khắc phục 2 không làm được.
Cách này chỉ hữu ích khi entry của terminal bạn tồn tại trong bản ncurses mà bản phân phối đóng gói, vì vậy hãy kiểm tra thay vì giả định. Ubuntu 24.04 cung cấp ncurses-bin 6.4+20240113-1ubuntu2.2 (tính đến tháng 11 năm 2026). Entry của Ghostty được thêm vào upstream trong ncurses 6.5-20241228, là bản mới hơn, nên apt install ncurses-term trên Ubuntu 24.04 không thể tạo entry xterm-ghostty dù bạn chạy lệnh bao nhiêu lần. tput -T <name> longname là lệnh kiểm tra: nó in mô tả khi entry tồn tại, và unknown terminal với exit status 3 khi entry không tồn tại.
Để cài một entry riêng trên toàn hệ thống thay vì cài cả package, hãy copy source sang máy rồi compile bằng 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 trong lệnh thứ hai cấp phát một pseudo terminal để sudo có thể yêu cầu nhập password. Nếu không có tùy chọn này, ssh không cấp terminal cho remote command, và sudo dừng với sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper khi cần password. Lỗi đó liên quan đến tty bị thiếu, không liên quan đến terminfo.
Để emulator tự chuyển terminfo
Một số emulator có helper thực hiện fix 2 tự động. kitty có một ssh kitten: kitten ssh myserver kết nối và tự động sao chép terminfo của kitty sang host từ xa. Tài liệu của kitty cũng nêu cách chạy thủ công là infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, trong đó ký tự tilde được escape vì lý do đã mô tả ở trên. Ghostty có tài liệu cho infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -. Từ version 1.2.0, Ghostty có thêm các tính năng shell integration cần bật thủ công (ssh-env và ssh-terminfo) để tự động thực hiện cả hai fix. Ghostty 1.4.0, phát hành ngày 27 tháng 10 năm 2026, thêm wrapper ghostty +ssh mà các bản 1.3.x không có; hai tính năng cần bật thủ công này hiện gọi wrapper đó. Wrapper cài terminfo đi kèm Ghostty trên host từ xa trước khi kết nối. Nếu cài đặt thất bại, chẳng hạn khi server không có tic, wrapper dùng TERM=xterm-256color. Trong 1.4, ssh-env cũng không còn ghi đè các dòng SetEnv trong ~/.ssh/config, nên override theo từng host từ fix 1 được giữ nguyên.
Các helper này chạy đúng những lệnh mà bạn vừa chạy thủ công. Bạn vẫn cần biết cách chạy thủ công, vì helper không thể hoạt động khi kết nối được khởi tạo từ nơi khác, chẳng hạn trên jump host hoặc bên trong script.
Khi lỗi quay lại
Trong sudo -i. Một login shell chạy dưới root có HOME=/root, còn sudo giữ nguyên TERM của bạn. ncurses lúc này tìm trong /root/.terminfo, nhưng thư mục đó không chứa entry của bạn, nên chỉ root gặp lại lỗi. Xác nhận bằng sudo -i env rồi đọc các dòng HOME và TERM. Cài entry vào thư mục hệ thống. Bản sao trong /root/.terminfo cũng có thể hoạt động, nhưng ncurses có thể hạn chế việc tìm trong thư mục home đối với process có quyền cao. Vì vậy, hãy chạy tput longname dưới root để xác nhận.
Bên trong tmux hoặc screen. Các chương trình này đặt TERM riêng cho những chương trình chạy bên trong chúng, thường là screen-256color hoặc tmux-256color. Một server cũ biết screen-256color nhưng có thể không biết tmux-256color, nên shell bên ngoài vẫn hoạt động bình thường trong khi mọi thứ bên trong session đều lỗi. Nguyên nhân giống nhau, chỉ khác tên. Chạy tput -T tmux-256color longname trên server để xem server có entry nào trong hai entry này. Một terminal workbench xây dựng trên tmux có thể che khuất vấn đề này cho đến khi bạn attach vào một host chưa được sửa.
Trên server mới tạo. ~/.terminfo là thiết lập riêng theo từng account và từng máy, nên VPS được dựng lại sẽ lại bắt đầu từ trạng thái trống.
Màn hình hiển thị đúng nhưng phím hoạt động sai. Nếu màn hình hiển thị bình thường nhưng Home, End hoặc các phím chức năng chèn ký tự lạ, tên đã được resolve thành một entry không khớp với terminal của bạn. Các chuỗi phím và khả năng hiển thị đều lấy từ cùng một entry terminfo, nên entry gần đúng chỉ cho các phím gần đúng. Đây là kết quả thường gặp khi dùng cách sửa 1 trên emulator có chuỗi phím khác với xterm. Cách sửa 2 là lựa chọn sạch nhất, vì entry thực của emulator chứa đúng các chuỗi phím cho mọi chương trình cùng lúc. Đây không phải cách duy nhất: tài liệu Vim nói rằng bạn có thể "thay đổi mã phím bằng lệnh :set", và Vim hỏi trực tiếp một xterm mới về mã phím khi khởi động, thay vì chỉ dựa vào entry.
FAQ
Vì sao qua SSH tôi chỉ thấy "unknown terminal type"?
Vì cơ sở dữ liệu chứa entry của terminal phải nằm trên server. Terminal emulator cài mô tả của nó trên máy đang chạy emulator, nên các chương trình local có thể tìm thấy mà bạn không phải làm gì thêm. SSH chỉ gửi giá trị của TERM, vì protocol truyền tên đó cùng yêu cầu pseudo-terminal. ncurses trên máy remote tra tên này trong cơ sở dữ liệu remote nhưng không tìm thấy, nên initscr thất bại và chương trình dừng.
Có thể sửa lỗi này mà không cần root trên server không?
Có, với bản build tiêu chuẩn như Debian. ncurses tìm $HOME/.terminfo trước mọi thư mục hệ thống, và chỉ có biến $TERMINFO được set trên server là được kiểm tra sớm hơn. Vì vậy, trong trường hợp thông thường, chỉ cần có entry ở đó là đủ cho account của bạn. Việc tìm trong home directory là tùy chọn trong ncurses, nên bước kiểm tra tput longname bên dưới rất quan trọng. Chạy infocmp -x | ssh user@host -- tic -x - một lần trên mỗi server. tic sẽ ghi vào home directory của bạn khi không thể ghi vào system path, đây là trường hợp bình thường đối với account không có quyền. Đăng nhập rồi chạy tput longname để xác nhận việc tra cứu đã tìm thấy entry.
Tôi mất gì khi set TERM=xterm-256color cho một host?
Bạn mất mọi capability mà emulator mô tả ngoài entry xterm-256color, chẳng hạn màu 24-bit thông qua RGB và gạch chân có style thông qua Smulx. Các chương trình phụ thuộc vào terminfo entry sẽ không thấy những capability này, nên dùng fallback gần nhất trừ khi bạn cấu hình khác đi, như tùy chọn termguicolors của Vim dùng cho màu. Chuỗi phím chức năng cũng có thể khác terminal thực tế của bạn. Đặt cấu hình trên client trong ~/.ssh/config thay vì trong một .bashrc trên server. Nếu đặt trên server, các session từ những terminal vốn đã hoạt động sẽ bị hạ capability.
Vì sao lỗi quay lại sau sudo -i?
sudo -i khởi động login shell với quyền root bằng HOME=/root, nhưng vẫn giữ giá trị TERM của bạn. Sau đó ncurses tìm trong /root/.terminfo thay vì home directory của bạn và không tìm thấy gì, nên root gặp cùng lỗi mà account của bạn không còn gặp nữa. Chạy sudo -i env rồi kiểm tra các dòng HOME và TERM. Compile entry vào system directory bằng sudo tic -x -o /usr/share/terminfo. Một bản copy trong /root/.terminfo cũng có thể hoạt động, nhưng ncurses có thể hạn chế việc tìm trong home directory đối với process có quyền cao. Vì vậy, hãy xác nhận bằng tput longname khi đang chạy với quyền root.
apt install ncurses-term có luôn sửa được lỗi này không?
Không. Lệnh này chỉ thêm những entry tồn tại trong bản ncurses mà distribution của bạn đã đóng gói. Ubuntu 24.04 đi kèm ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.2, tính đến tháng 11 năm 2026), còn entry của Ghostty được thêm upstream trong ncurses 6.5-20241228, nên package đó không thể chứa entry này. Kiểm tra bằng tput -T <name> longname trước khi phụ thuộc vào package. Nếu kết quả vẫn báo unknown terminal, hãy tự cung cấp entry.