Mothers Ruin Software: SSHChain: FAQ

Frequently Asked Questions

What version of Mac OS X does SSHChain require?

SSHChain requires Mac OS X 10.5 (Leopard, but see below), Mac OS X 10.4 (Tiger) or Mac OS X 10.3.9 (Panther). It will not run on earlier versions of Panther, nor under Mac OS X 10.2 (Jaguar), at least as distributed on the download page. You may still be able to compile from the source on earlier systems.

Does SSHChain work on Mac OS X 10.5 (Leopard)?

Yes, but you don't need it in Leopard. In Mac OS X 10.5, Apple has provided built-in integration of ssh-agent with the keychain.

Mac OS X 10.5 automatically creates a socket and sets the SSH_AUTH_SOCK environment variable. (This is done by launchd, via the system-installed launch agent at /System/Library/LaunchAgents/org.openbsd.ssh-agent.plist.) The first time you make an SSH connection, launchd starts ssh-agent, and you will see a dialog box, asking for your password for the SSH identity:

If you check the Remember password in my keychain checkbox, ssh-add will automatically retrieve the password from your keychain in the future. (Note that the Mac OS X version of ssh-add now includes a couple of keychain-specific options; see the man page for details.)

How do I uninstall SSHChain to use the Leopard mechanism?

If you already have SSHChain installed, the SSH_AUTH_SOCK variable for SSHChain will hide the one created by Mac OS X 10.5. Edit your ~/.MacOSX/environment.plist file to remove the SSH_AUTH_SOCK definition. Then, stop SSHChain from launching automatically at login: double-click the SSHChain icon to open the Preferences dialog, uncheck Launch SSHChain Helper on login, and click OK.

Log out and back in again, and make an SSH connection: you should get the standard Mac OS X dialog shown above. You can now trash the SSHChain application. (Thanks for using it!)

How do I upgrade or uninstall SSHChain?

If you configure SSHChain to start automatically on log in, you may have trouble replacing or trashing it, since the background helper application is running. The easiest way around this is to double-click the SSHChain icon to open the Preferences dialog, click Restart Agent, and then Quit SSHChain. You should then be able to replace or trash the SSHChain application.

Why does ssh-add report could not open a connection to your authentication agent?

The most likely cause for this is that the socket path you've set via the environment.plist does not match the one specified in the SSHChain Preferences dialog. Another possibility is that the environment.plist is not being loaded correctly. Check the value of the SSH_AUTH_SOCK variable in the shell.

Why does ssh-add report agent has no identities?

This indicates that SSHChain did not find any SSH identities to add to the agent. Open Keychain Access and make sure that the SSH identities were added as password items, and that the Name field is given as ssh-agent (only entries with exactly this name field will be found by SSHChain). Also ensure that the entry is in your default keychain, since SSHChain uses the default keychain search to find the identities.

Why does SSHChain report attempt to add key with ssh-add failed?

Either the specified identity file could not be found, or the passphrase entered into the Keychain for that identity was not accepted by ssh-add. Use Keychain Access to double-check both the identity path and the passphrase.

After using Keychain Access to update the information, click Relaunch Agent to restart the agent and reload the identities. Alternatively, select Configure... to return to the Preferences dialog, or Quit SSHChain to terminate the agent and SSHChain.

Why does SSHChain report that the socket path already exists?

The most common cause for this error is that SSHChain did not quit cleanly the last time — for example, due to a system crash. When SSHChain restarts, the socket indicated by SSH_AUTH_SOCK already exists, but has no ssh-agent associated with it.

Click Overwrite to have SSHChain delete this orphaned socket before starting ssh-agent. If you've started ssh-agent outside of SSHChain, and this socket isn't orphaned, you can click Configure... to return to the Preferences dialog and change the socket path.

Why does the new version of SSHChain no longer start at login?

Because of the new code signing requirements in Mac OS X 10.5 (Leopard), the SSHChainHelper background application had to be moved in SSHChain Version 1.1. This requires that the path stored in your Login Items list be updated.

The first time you open Version 1.1, it attempts to make this update to your Login Items automatically. But if this doesn't work, delete the old entry from Login Items manually (using the Accounts pane of System Preferences). Then open SSHChain and recheck Launch SSHChain Helper on login. (Don't try to add the new entry via System Preferences, because you won't be able to select the background application directly.) See below for more information on SSHChainHelper.

What is the SSHChainHelper application that appears in security alerts?

SSHChainHelper is the background application that does the real work of SSHChain: it starts when you login (if you've enabled that), starts the ssh-agent and loads the identities from your keychain. It stays running until you log out, and then terminates the agent. Since SSHChainHelper accesses your keychain, its name will appear in the related security alerts.

SSHChainHelper lives inside the main SSHChain bundle that you see in the Finder. (Specifically, it lives in SSHChain.app/Contents/SharedSupport/SSHChainHelper.app, as of Version 1.1.) When you double-click the visible SSHChain icon in the Finder, this simply tells SSHChainHelper to open the SSHChain Preferences dialog.

Mothers Ruin Software