Resolving "Bad configuration option: UseKeychain" Error in .ssh/config on macOS Sierra

Problem Background and Error Analysis

On macOS Sierra 10.12.6, users may encounter configuration errors when trying to set up SSH to store key passphrases in the keychain. The traditional method using ssh-add -K ~/.ssh/id_rsa may no longer work in some cases, due to changes in SSH behavior after macOS 10.12.2 as per Apple's official documentation. The recommended fix is to add UseKeychain yes to the SSH config. However, after adding this to the .ssh/config file, connecting to a remote host results in an error: /Users/USER/.ssh/config: line 16: Bad configuration option: usekeychain. This error indicates that the SSH client does not recognize the UseKeychain option, often due to an older client version or parsing limitations.

Core Solution: The IgnoreUnknown Directive

The key to resolving this issue is using the IgnoreUnknown configuration directive. This allows the SSH client to ignore unknown options, preventing parsing errors. A basic example is:

Host *
  IgnoreUnknown UseKeychain
  UseKeychain yes

Here, IgnoreUnknown UseKeychain instructs the SSH client to ignore the UseKeychain option, even if unrecognized, avoiding errors. Then, UseKeychain yes enables keychain functionality in supported environments. This method, based on Apple's documentation, effectively bypasses version compatibility issues.

Handling Multiple Unknown Options

If the configuration file includes multiple unknown options, such as AddKeysToAgent and UseKeychain, extend the IgnoreUnknown directive with comma-separated values. Example configuration:

Host *
  IgnoreUnknown AddKeysToAgent,UseKeychain
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

This ensures the SSH client ignores both options, preventing connection interruptions. In practice, users should adjust IgnoreUnknown values based on their config files to handle all relevant options properly.

Configuration File Structure and Best Practices

To ensure configuration effectiveness, pay attention to the structure of the .ssh/config file. If multiple Host blocks use the UseKeychain option, place the IgnoreUnknown UseKeychain directive at the top or before the first block that uses it. For example:

Host *
  IgnoreUnknown UseKeychain

Host my-host
  HostName example.com
  User myuser
  UseKeychain yes

This structure applies global settings first, avoiding errors in subsequent blocks. Additionally, regularly checking SSH client versions and updating configurations can prevent similar compatibility issues.

Command-Line Parameter Alternative

For users who prefer not to or cannot modify the SSH config file, pass the IgnoreUnknown option via command-line parameters. Example command:

ssh -o IgnoreUnknown=UseKeychain my-host

This method is useful for temporary connections or testing, avoiding risks of direct file modifications. It allows dynamic specification of ignored options, increasing flexibility. Note that command-line parameters apply only to single sessions and are not suitable for long-term configuration.

Summary and Recommendations

By using the IgnoreUnknown directive, users can resolve the UseKeychain error in macOS Sierra SSH configurations, ensuring secure storage of key passphrases in the keychain. It is recommended to choose between file modifications or command-line parameters based on needs, and keep the SSH client updated for better compatibility. In practice, combining Apple's documentation with community insights enhances SSH connection reliability and security.