Lỗi xác thực lúc 2 giờ sáng
Bạn vừa kết thúc một phiên lập trình dài và sẵn sàng đẩy (push) công việc của mình. Bạn nhập lệnh quen thuộc để tải khóa SSH vào macOS Keychain: ssh-add -K ~/.ssh/id_ed25519. Nhưng thay vì thông báo thành công như thường lệ, terminal lại hiển thị một loạt văn bản lỗi.
ssh-add: illegal option -- K
usage: ssh-add [-cDlLqXx] [-t life] [file ...]
ssh-add -s pkcs11
ssh-add -e pkcs11
Hôm qua nó vẫn hoạt động. Nó vẫn chạy tốt trên chiếc MacBook cũ của bạn. Nhưng trên macOS Monterey hoặc mới hơn, thói quen cũ của bạn giờ đây lại gây ra lỗi. Điều này xảy ra do Apple đã thay đổi cách hoạt động của các flag SSH tùy chỉnh để đảm bảo tương thích với OpenSSH tiêu chuẩn.
Có gì thay đổi trên macOS?
Apple đã cập nhật phiên bản OpenSSH tích hợp lên 8.6p1 bắt đầu từ macOS Monterey (12.0). Trước bản cập nhật này, Apple đã sử dụng một bản vá tùy chỉnh để thêm các flag -K và -A. Đây là các phím tắt không tiêu chuẩn được sử dụng riêng để giao tiếp với macOS Keychain.
Để phù hợp với các tiêu chuẩn OpenSSH hiện đại, Apple đã đổi tên các flag này. -K cũ giờ là --apple-use-keychain, và -A hiện là --apple-load-keychain. Nếu bạn cố gắng sử dụng các phiên bản một chữ cái cũ, tệp thực thi (binary) đã cập nhật sẽ đơn giản là không nhận ra chúng. Đây là một thay đổi nhỏ, nhưng nó phá vỡ thói quen nhiều năm của nhiều lập trình viên.
Cách khắc phục nhanh (Lệnh thủ công)
Nếu bạn cần đẩy code ngay bây giờ, chỉ cần sử dụng flag dạng đầy đủ. Thay thế -K bằng phiên bản mô tả mới:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Lưu ý: Nếu bạn sử dụng khóa RSA cũ, hãy thay thế id_ed25519 bằng id_rsa.
Tương tự, nếu bạn thường chạy ssh-add -A sau khi khởi động lại để nạp lại tất cả các khóa vào agent, hãy sử dụng lệnh này thay thế:
ssh-add --apple-load-keychain
Cách khắc phục vĩnh viễn (Cấu hình SSH)
Việc chạy các lệnh thủ công mỗi khi bạn khởi động lại terminal rất tốn thời gian. Cách tiếp cận tốt hơn là cập nhật cấu hình SSH của bạn. Điều này yêu cầu macOS tự động tìm kiếm trong Keychain bất cứ khi nào bạn cố gắng kết nối với máy chủ.
- Mở tệp cấu hình SSH của bạn bằng nano hoặc trình chỉnh sửa yêu thích:
nano ~/.ssh/config
- Dán các dòng sau vào. Cấu hình này đảm bảo SSH tự động xử lý Keychain và quản lý agent cho bạn:
Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519
Các dòng này thực sự có tác dụng gì:
- AddKeysToAgent yes: Lệnh này tự động tải khóa của bạn vào
ssh-agentngay trong lần đầu tiên bạn sử dụng. Không còn phải chạyssh-addthủ công nữa. - UseKeychain yes: Đây là "bí quyết" riêng của macOS. Nó yêu cầu hệ thống lưu trữ và lấy mật khẩu (passphrase) của bạn từ macOS Keychain.
- IdentityFile: Dòng này trỏ đến khóa cụ thể của bạn. Nếu bạn có nhiều khóa cho các công việc khác nhau, bạn có thể thêm nhiều dòng
IdentityFiletại đây.
- Lưu và thoát (Nhấn Ctrl+O, Enter, sau đó là Ctrl+X).
Kiểm tra thiết lập
Hãy đảm bảo mọi thứ hoạt động như mong đợi. Đầu tiên, hãy xóa phiên hiện tại bằng cách dừng agent đang hoạt động:
killall ssh-agent
Bây giờ, hãy thử kết nối với GitHub:
ssh -T git@github.com
Nếu cấu hình của bạn chính xác, một hộp thoại macOS sẽ hiện lên yêu cầu mật khẩu SSH. Hãy đảm bảo bạn đã tích vào ô "Remember password in my keychain" (Ghi nhớ mật khẩu trong keychain của tôi). Sau khi thực hiện việc này một lần, bạn sẽ không bao giờ phải nhập lại mật khẩu nữa.
Các lỗi thường gặp
Quyền hạn nghiêm ngặt (Strict Permissions): SSH sẽ bỏ qua tệp cấu hình của bạn nếu quyền hạn quá rộng. Bảo mật ở đây rất chặt chẽ. Đảm bảo thư mục .ssh và tệp config có quyền sở hữu chính xác:
chmod 700 ~/.ssh
chmod 600 ~/.ssh/config
Alias Shell cũ: Kiểm tra tệp .zshrc hoặc .bash_profile của bạn. Nếu bạn có một alias cũ như alias sload='ssh-add -K', nó vẫn sẽ lỗi. Hãy cập nhật các alias đó để sử dụng flag --apple-use-keychain hoặc xóa chúng hoàn toàn vì tệp cấu hình của bạn hiện đã đảm nhận công việc nặng nhọc này rồi.