(revision 0.5 by (c) Marc Logemann)

Because many new subversion users run into problems when attempting to use subversion with SSH, I compiled a HowTo for that issue. Perhaps I will expand this HowTo later on and submit it to the Subversion or TortoiseSVN docs.

-------------------------
Our Scenario:
-------------------------
Server: Linux or unix like system
Client: Windows 2000/XP (or variant)

-----------------------------------------
Installing subversion (server)
-----------------------------------------
I won't go into details here, because this topic is covered in great length in the official Subversion documentation. But one thing I want to point out nevertheless. If you compile subversion from source and don't provide any argument to ./configure, Subversion creates a "bin" directory under /usr/local and places its binaries there. This is no problem as long as you run subversion as daemon, but if you want to use tunnelling mode with SSH, you have to be aware that the user logging into via SSH can execute the svnserve program and some other binaries. For this reason, either place /usr/local/bin into the PATH variable or create symlinks of your binaries to the /usr/sbin directory or any other directory which is commonly in the PATH.

To make sure that everything is OK. Login in with SSH and the target user to the system later on and type: "which svnserve". This command should tell you if svnserve is reachable.
To check if svnserve is available through ssh, type: "ssh svnserve"

Furthermore this document assumes that you already have a subversion repository created with "svnadmin create". Please pay attention to the ACL of the repository in order to reduce possible problems. Check that each user coming in via SSH has appropriate rights to work with the repository.

Sometimes your system has 'mesg y' put into the global bashrc file. This will make connections with TortoisePlink fail, since that line will make SSH throw out an error "stdin: is not a tty". You must remove that line from your bashrc file.
------------------------------------------------
OpenSSH and certificates (server)
------------------------------------------------
Again I wont go into details about OpenSSH installation as this is covered elsewhere better. But on most systems, enabling SSH is just a matter of installing an RPM. If you rent a pre-installed linux server from a hosting company, SSH is most likely already installed. To be sure everything is in place, type: "ps xa | grep sshd" and watch out for SSH jobs.

Assuming OpenSSH is installed, one of the most important steps is to create a keypair for authentication. There are two possible ways of creating the keys. The first way is to create the keys with puttygen (a program of the putty family), upload the public key to your server and use the private key with putty. Because of some problems with this approach, I prefer the other way. This way creates the keypair with the OpenSSH tool ssh-keygen, downloads the private key to your client and converts the private key to a putty-style private key.

Lets do this step by step:

- login to your server
- type: ssh-keygen -b 1024 -t dsa -N passphrase -f mykey
- change "passphrase" to a secret keyword only you know
- type: ls -l mykey*

We just created a SSH2 DSA key with 1024 bit keyphrase. You will see two files. One named "mykey" and one named "mykey.pub". As you might guess, the .pub file is the public key file, the other is the private one. Next create a user on the server with a home directory:

- type: useradd -m myuser

You will have a directory under /home with the name "myuser", create a new directory in "myuser" called ".ssh":

- type: cd /home/myuser
- type: mkdir .ssh

Then go to the directory where you created your keys and copy the public key to the .ssh userfolder with the following command:

- type: cp mykey.pub /home/myuser/.ssh/authorized_keys

or if you already have some keys in place

- type: cat mykey.pub >> /home/myuser/.ssh/authorized_keys

Please pay attention to the filename, it really must be "authorized_keys". In some old OpenSSH implementations, it was "authorized_keys2". Now download the private key file to your client computer. Remember, the file was "mykey"

------------------------------------------------------------
SSH key generation and connection check (client)
------------------------------------------------------------
Grab the tools we need for doing SSH on Windows on this site:
https://www.chiark.greenend.org.uk/~sgtatham/putty/

Just go to the download section and get "Putty", "Plink", "Pageant" and "Puttygen"

In order to use the private key we get from the server, we have to convert it to a putty format. This is because the private key file format is not specified by some standard body. To do this we simple open "puttygen" and open the "conversions" menu and chose "Import Key". Then browse to your file "mykey" which you got from the server enter your provided passphrase upon creation of the key. Finally click "Save private key" and save the file as "mykey.PPK" somewhere on disk.

Now we are ready to use this key for the first time to test the connection. In order to do this, we open the program "putty" and create a new session like this:

Session->HostName: Hostname or IP Address of your server
Session->Protocol: SSH
Session->Saved Sessions: MyConnection
SSH->Preferred SSH Protocol version: 2
SSH->Auth->Private Key file for auth: $PATH$\mykey.PKK (replace $PATH$ with real path to the mykey.PKK file)

Then go back to Session tab and hit "save" button. You will see "MyConnection" in the list of available connections.

Next click "open" and you should see a telnet login prompt. Use "myuser" as username (without double quotes of course) and if everything is OK, you don't have to provide a password to your system. If the system still requires a password, something went wrong. See Debugging Section of this HowTo.

-----------------------------------------------
Testing SSH with TortoiseSVN (client)
-----------------------------------------------
After installing TortoiseSVN right click on some folder inside your Windows Explorer. You will see a menu item called TortoiseSVN->RepoBrowser. After opening the browser you have to enter a URL like this:

svn+ssh://myuser@MyConnection/usr/local/repos

Lets talk briefly about the URL (if you need more infos, check the subversion docs). The Schema name is "svn+ssh", this tells Tortoise how to handle the requests to the server. After the double slashed, you can provide the user which is trying to connect to the server, in our case this is "myuser". After the "@", we supply our putty session name. This session name contains all details like where to find the private key and the servers IP or DNS. Last we have to provide the full path to the repository. Its assumed that a subversion repository resides at /usr/local/repos

If you submit the URL, you will see an opened tree on the next screen until the node "repos". Yet, there has not been made any connection, because the tree representation comes from the supplied URL. When you hit the "+" button in front of "repos", the connection will be established and you will see the "+" sign disappearing if you don't have anything in the repository or you will see your already imported projects and files.

Right now, you should have a running SSH Tunnel in conjunction with TortoiseSVN.

-----------------------------------------------
Configuration Variants (pageant)
-----------------------------------------------
Now I will continue to show some configuration variants, that can be helpful during everyday work.

One way to simplify the URL in TortoiseSVN is to set the user inside the putty session. For this you have to load your already defined session "MyConnection" in putty make the following entry:

connection->Auto Login username: myuser

Then save your putty session as before and try the following URL inside Tortoise:
svn+ssh://MyConnection/usr/local/repos

This time we only provide the putty session "MyConnection" to the SSH client TortoiseSVN uses (TortoisePlink.exe). This client is capable of checking the session for all necessary details like loginuser or server ip.

Some people like using pageant for storing all their keys and in fact each howto explains that it is important to place your keys there. In fact, because a putty session is capable of storing a key, you don't need pageant for normal business. But imagine you want to store keys for several users, in that case, you would have to edit the putty session over and over again, depending on the user you are trying to connect with. For this situation pageant makes perfectly sense, because when putty, plink, TortoisePlink or any other putty-based tool is trying to connect to a SSH server, it checks all private keys that pageant carries to initiate the connection.

For this task, simply start pageant and add a key. It should be the same private key you defined in the putty session above. If you use pageant for private keys storage, you can delete the "SSH->Auth->Private Key file for auth" section inside your putty session. You can add more keys for other systems or other users of course. If you don't want to repeat this procedure after every reboot of your client, you should place the pageant in autostart group of your Windows installation. You can append the keys with complete paths as command line arguments to pageant.exe

The last way to connect to a SSH server is by just using this URL inside TortoiseSVN:

svn+ssh://[email protected]/usr/local/repos

As you can see, we dont use a saved putty session but an IP address as connection target. We also supply the user, but you might ask how the private key file will be found. Because TortoisePlink.exe (the standard SSH client for TortoiseSVN) is a modified version of the plink tool from the putty suite, also TortoiseSVN looks for a running pageant and will try all the keys stored in pageant.

----------------------------------------
Feedback
-------------------
For comments or corrections on this howto, please use the TortoiseSVN mailinglist

This is a copy of the original which was at http://www.logemann.org/day/archives/000099.html (page removed)
Thanks to Marc!