Mac 上出现 ssh-add: illegal option -- apple-use-keychain 或 Bad configuration option: UseKeychain:先看你在用哪一个 ssh
Frank Zhang
- 7 分钟阅读 - 3143 字TL;DR
这两句通常说明正在跑的 ssh 或 ssh-add 不是 /usr/bin 里的那一份。先看 which -a 和版本行,再按路径调用 /usr/bin/ssh-add。IgnoreUnknown 只压掉未知选项。
Mac 上先对上屏幕里的这一句,再决定要不要改 PATH、卸包,或者动 ~/.ssh。Terminal 里会看到,别的程序替你去跑 ssh 或 ssh-add 时也会看到:
ssh-add: illegal option -- apple-use-keychain
Bad configuration option: UseKeychain
第一句 GitHub 单独写了一页,标题就是 Error: ssh-add: illegal option – apple-use-keychain。第二句在 Generating a new SSH key and adding it to the ssh-agent 里写成 Bad configuration option: usekeychain。配置文件里的关键字是 UseKeychain。写作时读到的 OpenSSH readconf.c 会先把关键字转成小写,再报 Bad configuration option:,所以句子里是 usekeychain,同一行还会带上文件名和你这份文件里的行号。这篇不指定是第几行。大小写不同,指的是同一个选项。
两句通常是同一件事:这次 shell 找到的 ssh 或 ssh-add 不是 Apple 的。--apple-use-keychain 和 UseKeychain 在 Apple 的 /usr/bin/ssh、/usr/bin/ssh-add 上。Homebrew、MacPorts,或另一份 OpenSSH,没有实现它们。旗标就变成 illegal option,配置项就变成 Bad configuration option。这不能说明钥匙坏了,也不是把 ~/.ssh 删掉的理由。
站上没有记下谁在自己的 Mac 上碰到过这两句,也没有记下为这个题目跑出来的 which -a 或 ssh -V。下面是一般指导,加上 GitHub 文档和手册里已经写明的部分。这些命令没有为这篇在 Mac 上重跑。Mac 自带它自己的那一份 OpenSSH。你机器上的 man 和这里不一致时,以你的手册为准。GitHub 再改文案时,以文档页为准。
屏幕上如果是 Permission denied (publickey),先读 Mac 终端里 git@github.com: Permission denied (publickey):先读 ssh -vT 递出去的钥匙。那篇在指纹对上之后,才写该用哪一个 ssh-add。这篇只处理那些 Keychain 步骤自己报错的情况。
三十秒:先看是哪一个二进制
| 屏幕上的原文 | 在这篇里怎么读 | 第一条只读命令 |
|---|---|---|
ssh-add: illegal option -- apple-use-keychain | 这个 ssh-add 不认识 Apple 的旗标。 | which -a ssh-add |
Bad configuration option: UseKeychain,或 GitHub 写的 usekeychain | 打开 ~/.ssh/config 的那个 ssh 不认识 UseKeychain。 | which -a ssh |
Permission denied (publickey) | 服务器拒绝了递出去的用户钥匙。 | 上面那篇 publickey。 |
先读路径,再改文件
这三条不写 ~/.ssh/config,不加钥匙,也不卸软件:
which -a ssh ssh-add
ssh -V
/usr/bin/ssh -V
which -a 按 PATH 的查找顺序,把每个名字的全部匹配打出来。每个名字的第一行,就是直接敲 ssh 或 ssh-add 时会跑的那一个。ssh 的第一行和 ssh-add 的第一行可以来自不同前缀。读你刚刚失败的那一个命令对应的行。
接下来要用 Apple 的钥匙串旗标时,要出现的是 /usr/bin/ssh 和 /usr/bin/ssh-add。GitHub 的生成文档写明:把钥匙加进 agent 时,用 macOS 自带的 ssh-add,不用 MacPorts、Homebrew 或其他外部来源装的那一个。/opt/homebrew/bin 或 /opt/local/bin,或别的前缀,排在第一行时,这个 shell 跑的就是非 Apple 的二进制。这篇没有记录哪一台机器打出过 /opt/homebrew/bin。这两个前缀是 Homebrew 和 MacPorts 常见的安装位置,拿来和你自己的 which -a 对照。
ssh -V 是 PATH 上的 ssh。/usr/bin/ssh -V 是 Apple 的那一份。两行文字不同,直接敲 ssh 跑到的就是另一份构建。macOS 上,Apple 的版本行里常见 LibreSSL,Homebrew 的构建里常见 OpenSSL。库名差别是常见样子,不是这篇量到的版本号。以你机器上打出来的那一行字为准。ssh -V 不能用来判断 ssh-add。旗标报错时,看 which -a 里 ssh-add 自己的那一行。
用绝对路径调用 Apple 的 ssh-add
GitHub 排错页把私钥加进 agent 的写法,是直接调用 Apple 的二进制:
/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_ed25519
私钥不叫 id_ed25519 时,把文件名换成你的。那一页的说明是:--apple-use-keychain 在 Apple 标准的 ssh-add 里,把钥匙加进 agent 时顺便把 passphrase 放进钥匙串。macOS Monterey(12.0)之前,用 -K,不用 --apple-use-keychain。
生成文档在 Apple 的 ssh-add 已经排在 PATH 前面时,写成不带 /usr/bin 前缀的同一条旗标。钥匙没有 passphrase 时,去掉 --apple-use-keychain。同一则说明写明:12.0 之前,--apple-use-keychain 和 --apple-load-keychain 分别是 -K 和 -A。--apple-load-keychain(更早写成 -A)用来把已经放在钥匙串里的钥匙重新载入。这篇没有跑过它,也没有记下它失败或成功。
Homebrew 或 MacPorts 的 ssh 可以留着,平时的连接继续用。眼前的修法是按路径调用 /usr/bin/ssh-add。把另一份 OpenSSH 卸掉,是后面的可选项,只在你希望 which 的第一行变成 Apple 的 ssh 时再考虑。顺序在上面的只读之后。这篇没有记下谁卸过它。
Bad configuration option 的两种情况
改 ~/.ssh/config 之前先看 which -a ssh。同一句报错,常见有两种来源。两种都是一般指导。
读配置的 ssh 不是 Apple 的
UseKeychain 是 Apple 的选项。GitHub 生成文档用它把 passphrase 放进钥匙串,并写明钥匙没有 passphrase 时删掉这一行。非 Apple 的 ssh 不认识这个关键字,读文件时就会停。
GitHub 对 Bad configuration option: usekeychain 给的例子,是在 Host github.com 块里加一行 IgnoreUnknown:
Host github.com
IgnoreUnknown UseKeychain
ssh_config(5) 写明:IgnoreUnknown 是一组要忽略的未知选项,并且建议写在靠前的位置,因为它不会作用于出现在它前面的未知选项。所以 IgnoreUnknown UseKeychain 要排在 UseKeychain 上面。这个 Host 块的其余部分,包括 IdentityFile 指哪一把钥匙,留在 publickey 那篇。这篇不替你选钥匙。
IgnoreUnknown 只是压掉「不认识这个选项」的报错。它不会给非 Apple 的 ssh 补上钥匙串。那个二进制不会把 passphrase 存进钥匙串,后面用同一个 ssh 去连,也不会从钥匙串里把 passphrase 读回来。要用 UseKeychain,读这个文件的 ssh 得是 Apple 的。这次工作按路径调用 /usr/bin/ssh,或在你用来做这件事的 PATH 里把 /usr/bin 放在另一个前缀前面。平时的连接可以继续用另一个 ssh。
Apple 的存档说明 Technical Note TN2449 也是这一对:把 IgnoreUnknown UseKeychain 写在 UseKeychain 上面,给不认识这个选项的 OpenSSH 共用同一份文件。那则说明讲的是共享配置。它不会给另一个 ssh 加上钥匙串。
Linux、Windows,或 CI
UseKeychain 只属于 Apple 的 ssh。Linux、Windows 或 CI 镜像里的客户端会拒绝这个关键字,因为那一份构建里没有它。所以同一句报错也会出现在 Mac 以外。一般指导就一步:那些环境里删掉 UseKeychain 这一行,或者在它上面保留 IgnoreUnknown UseKeychain,这样同一份配置可以拷去别处。IgnoreUnknown 仍然不会在那些系统上变出钥匙串。这篇不展开 Windows 的 OpenSSH,也不展开 Linux 客户端。
先别动的东西
/opt/homebrew/bin/ssh、/opt/homebrew/bin/ssh-add,以及/opt/local/bin下的那两份,留在原地。GitHub 写明的修法是按路径调用/usr/bin/ssh-add。~/.ssh留着。这两句报错说的是哪一个二进制读了旗标或配置行。目录里还有私钥、config和known_hosts。~/.ssh的权限先别改。chmod 777是反方向。权限失败是另一句报错,在 publickey 那篇。- 先看完
which -a,再考虑brew uninstall openssh或port uninstall openssh。卸载是可选项,而且放在后面。 - 非官方的 tap 先别装。给另一份 OpenSSH 打钥匙串补丁的第三方包不在这篇的范围内,也不是 GitHub 那一页上的修法。
ssh-add不要加sudo。sudo读的是 root 的家目录。系统完整性保护保持打开。系统自带的ssh-agent留在原地。git 和ssh为什么不要混用sudo,publickey 那篇已经写了。- 私钥文件,以及 GitHub 账号上的公钥,交给 publickey 那篇。这篇不生成钥匙,也不让你把钥匙贴出去。
这篇停在这里
- 这里没有一份
which -a的输出,也没有一台机器的ssh -V原文。-K和-A的分界是 GitHub 写明的 Monterey(12.0)。机器上的man和这里不一致时,以你的手册为准。 Permission denied (publickey)仍在 那一篇。WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED是主机密钥那一层:先核对指纹,再改 known_hosts。核对之后,known_hosts 修复命令生成器 可以填删除那一条的命令。ssh: connect to host … port 22: Connection refused还没有试过钥匙:从 Mac 连出去,还是连进这台 Mac。- 隧道地址和端口一直在变,是另一层。一次ssh排错经历 记的是那条隧道,不是这两句报错。
- 其他阅读路线见 自部署阅读路线。英文稿是同一题的另一份写法:ssh-add: illegal option – apple-use-keychain, or Bad configuration option: UseKeychain, on a Mac。
- 搜索量。这篇没有另做外部数据。
这篇如果有用,欢迎自愿赞助,用来继续更新博客和自部署笔记。这不是慈善捐赠。