Gentoo Wiki



SSH Basics

Tips & Tricks

Other Gentoo-wiki SSH


Keychain is a wonderful program, and quite easy to use. For those unfamiliar with the joy that is keychain, it acts as a front end to the dreaded ssh-agent utility, and lets you have a single ssh-agent process per system, rather than per login. Further, you only need to enter your passphrase once - even if you log out. And if you do log out, your shell scripts can still use your keys! The docs are here, and you should probably read them sometime, but we can skip that for now.

First, if keychain isn't installed on your system, you need to install it. We're using Gentoo, so this is pretty easy:

emerge -n keychain

Next up we have to make sure keychain executes when you first log in. You normally do this in some file which is automagically executed on login. For bash, that's .bash_profile. ** Please note: For some terminals (such as urxvt) it does not login each time, meaning to do this automatically you must put these lines in ~/.bashrc. ** For zsh, .zlogin. Either way, this code should work:

keychain id_dsa
. ~/.keychain/$HOSTNAME-sh

For zsh the exact code is:

keychain id_dsa
source ~/.keychain/$HOST-sh

Bourne shells may need something like this:

keychain id_dsa
. ~/.keychain/`uname -n`-sh

And csh and tcsh something like this:

keychain id_dsa
source $HOME/.keychain/`uname -n`-csh

If your home folders are shared among many hosts (for example, NFS mounted home folders), you might want to add a condition that checks for keychain availability on the host you log on. Put the code above inside something like:

if which keychain 1>/dev/null 2>&1

This works if you have a private key called id_dsa in your ~/.ssh directory. If your key is called something else, substitute its name in place of id_dsa. If you don't have a private key yet, read up on ssh-keygen and run it to create a private key:

man ssh-keygen
ssh-keygen -t dsa

Answer the defaults to the questions. Make sure you enter a strong passphrase!

In any case, the basic idea is to call keychain with the name of your private key (or keys, seperated by spaces), then to load some useful environment variables from a special keychain directory. What this means in practice is that the first time you log on to the system, keychain will find a new key, and ask you for the passphrase. After that, every time you log on to the system the key will still be loaded - at least until either ssh-agent crashes (unlikely), or the computer is rebooted.


For more info:

man keychain

To use keychain with your X11 session, you will need to install gtk2-ssh-askpass or x11-ssh-askpass. These utilities give an X interface that prompt you for a passphrase.

emerge gtk2-ssh-askpass
# or if you don't want the gtk2 version:
emerge x11-ssh-askpass

Strange Behaviours

Although keychain's main functionality is to load up ssh-agent with your private keys and prompt you for their keyphrases (should your keys have them) and to leave ssh-agent resident in memory even after you logout, keychain has a rather annoying behaviour. If you public key is not available in your .ssh directory, it refuses to load your private key and does not prompt you for your keyphrase. There doesn't seem to be a valid reason for this that I can think of.

This can be observed in version 2.6.1 of Keychain. I have not tested this on other versions. Anyhow, if for the life of you, you cannot figure out why keychain is not prompting you for your private key's passphrase, just make sure you also have that key's public key equivalent available in the .ssh directory.

See also

Retrieved from ""

Last modified: Sat, 06 Sep 2008 13:10:00 +0000 Hits: 26,157