putty and msysgit
Copyright: Thomas Berezansky (tsbere (at) mvlc (dot) org). Licensed under CC-BY-SA unported 3.0, https://creativecommons.org/licenses/by-sa/3.0/
This document is intended for those who wish to use Putty/Plink with msysgit.
If you need more help with putty or component programs I suggest looking at the official putty documentation.
If you are not already using Putty for SSH it is recommended you do NOT use it with msysgit.
Please note that this only covers the client side of things, and does not involve server side components to troubleshooting. For that, please see the ssh-troubleshooting document.
msysgit setup
Provided you have putty sessions msysgit should give you the option of specifying a location to plink. If it did not then you will need to add an environment variable named "GIT_SSH" to point at plink.exe, wherever you have that sitting.
How to do that on your version of windows will likely vary, and is not covered here. For purposes of example, on a 64 bit Windows Vista machine the GIT_SSH value could be:
C:\Program Files (x86)\PuTTY\plink.exe
Note the lack of quotes.
Testing that msysgit is properly configured can be done from the git bash shell. Simply type (case sensitive, include the quotes):
"$GIT_SSH" -V
You should get a response similar to this:
plink: Release 0.60
If instead you get a "command not found" type error you likely have a typo in your environment variable.
Going back to OpenSSH
If you wish to go back to OpenSSH all you need to do is delete the GIT_SSH environment variable. This will vary by your version of windows and thus is not covered here.
Putty keys
If you do not already have putty private key files (.ppk) you will need to make at least one. You can either make a new one or convert an existing key to putty private key format.
Either way, you will want to use puttygen. Note that you can go the other way if you want to stop using putty but keep the key by exporting the key to OpenSSH format.
Creating a new key
To make it simple, I suggest SSH-2 RSA and a bit size of at least 1024. Larger keys will take longer to generate and will take longer to authenticate you on most systems. Making the key is as simple at hitting "Generate".
It is recommended to give the key a meaningful comment.
Importing an existing key
If you already have an OpenSSH or ssh.com key you can import it using the "Import" option on the "Conversions" menu.
If the key does not have a meaningful comment I would suggest adding one at this point.
Loading an existing key
If you need to load an existing key to edit or view it you can do so from the File menu.
Public key
To get your public key for use with gitolite, load (or generate, or import) your key into puttygen. There is a box labeled "Public key for pasting into OpenSSH authorized_keys file" there. Copy the text into your preferred text editor and save.
Putty ageant
Though not required in all cases you may wish to use the putty ageant, pageant, to load your key(s). This will allow for your key(s) to be passphrase protected but not have to enter the passphrase when you go to use them, provided you have already loaded the key into the ageant.
Sessionless or raw hostname usage
When using plink without a putty session you pretty much have to load your keys with putty ageant, if only so that plink can find them.
Putty sessions
In addition to hostnames msysgit can, when using putty, use putty sessions. This works in a manner similar to definitions in OpenSSH's ssh_config file. All settings in the session that apply to plink usage will be loaded, including the key file to use and even the username to connect to. Thus, instead of:
ssh://user@host.example.ext:port/repo
You can use:
ssh://session_name/repo
Host key authentication
Whether you are using hostnames or sessions you still run into one potential problem. Plink currently wants to validate the server's SSH host key before allowing you to connect, and when git calls plink there is no way to tell it yes. Thus, you may get something like this:
The server's host key is not cached in the registry. You
have no guarantee that the server is the computer you
think it is.
The server's rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Connection abandoned.
fatal: The remote end hung up unexpectedly
Or, in the case of the host key changing, something like this:
WARNING - POTENTIAL SECURITY BREACH!
The server's host key does not match the one PuTTY has
cached in the registry. This means that either the
server administrator has changed the host key, or you
have actually connected to another computer pretending
to be the server.
The new rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Connection abandoned.
fatal: The remote end hung up unexpectedly
The solution is to call plink directly, or start putty and connect with it first. To use plink, open the Git Bash shell and enter:
"$GIT_SSH" hostname_or_session_name
When you do you will see something like this:
The server's host key is not cached in the registry. You
have no guarantee that the server is the computer you
think it is.
The server's rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
If you trust this host, enter "y" to add the key to
PuTTY's cache and carry on connecting.
If you want to carry on connecting just once, without
adding the key to the cache, enter "n".
If you do not trust this host, press Return to abandon the
connection.
Store key in cache? (y/n)
Or, in the case of a changed key, a response like this:
WARNING - POTENTIAL SECURITY BREACH!
The server's host key does not match the one PuTTY has
cached in the registry. This means that either the
server administrator has changed the host key, or you
have actually connected to another computer pretending
to be the server.
The new rsa2 key fingerprint is:
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
If you were expecting this change and trust the new key,
enter "y" to update PuTTY's cache and continue connecting.
If you want to carry on connecting but without updating
the cache, enter "n".
If you want to abandon the connection completely, press
Return to cancel. Pressing Return is the ONLY guaranteed
safe choice.
Update cached key? (y/n, Return cancels connection)
In either case hit y and the key will be stored.
Debugging multiple putty ageant keys
In the event you are using putty ageant with multiple keys loaded you may see the wrong key being used. In general, pageant keys are tried in the order they were loaded into the ageant. If you have descriptive comment on each of your keys you can try connecting with plink in verbose mode to see what keys are being tried. Simply open the Git bash shell and run:
"$GIT_SSH" -v user@hostname
Or, if using sessions with a pre-entered username:
"$GIT_SSH" -v session_name
In either case, you should look for lines like:
Trying Pageant key #0
Authenticating with public key "My Key" from agent
The first says which (numerical) key the ageant is trying. The second tells you the key comment for the authenticating key. To my knowledge the second line should only show up once, for the valid key.
Setperms and other commands
When using wildcard repos the setperms command is very important, and other commands can come in handy as well. See their documentation for how to use them, but where they use:
ssh user@host command etc etc
You will want to use:
"$GIT_SSH" user@host command etc etc
Otherwise everything should be identical.
About this document
This document was written by Thomas Berezansky (tsbere (at) mvlc (dot) org) in the hopes that it would be useful to those using putty on windows and wishing to use git/gitolite with their putty keys and sessions.