SSH: Bad configuration option: usekeychain

I synchronise my .ssh/config file between (most of) my laptops, including some Linux and macOS ones. On Mac, it’s quite nice to be able to use the UseKeychain option to store SSH passphrases in the secure keychain thing.

That is, until you try to use that same config file on Linux (or Windows/WSL) and it explodes.

The issue is that UseKeychain isn’t actually part of standard OpenSSH; it’s a custom patch Apple adds to the version bundled with macOS. So when “upstream” OpenSSH (on Linux, Windows, or even Homebrew) sees it, it panics.

Thankfully, the IgnoreUnknown option exists to tell SSH to stop whining about a bad configuration option. Originally, I tried doing this inside the host block:

Host [heheh no]
    User theresnotime
    IdentityFile ~/.ssh/keys/path/to/key
    AddKeysToAgent yes
    IgnoreUnknown UseKeychain
    UseKeychain yes

However, Linux sometimes decides to ignore the inline IgnoreUnknown UseKeychain and instead present the error SSH: Bad configuration option: usekeychain anyway.

The Fix

It turns out order matters. The SSH parser reads line-by-line; if it hits UseKeychain before it has fully processed the instruction to ignore it, it crashes. This tends to occur just as I’m urgently having to SSH into something, resulting in me editing .ssh/config to remove lines in a huff.

To fix this permanently (and stop it breaking on my Windows/WSL setups too), the IgnoreUnknown directive needs to be at the very top of the file, in the global scope:

# ----------------------------
# Global Options
# ----------------------------
IgnoreUnknown UseKeychain

# ----------------------------
# Host Defaults
# ----------------------------
Host *
    AddKeysToAgent yes
    UseKeychain yes

Adding that to the top of .ssh/config seems to have fixed it everywhere, as sorta suggested by https://www.unixtutorial.org/ssh-bad-configuration-option-usekeychain :-)

The more you know, etc...