Content

1. Intro
2. SSH Protocol
3. Using Linux/Unix/mac OSX/BSD
4. Using Microsoft Windows, Putty and TortoiseCVS or TortoiseSVN
5. Keys and key-agents on Apple MAC-OS X
6. CVS and Eclipse
7. Subversion and IDE's
   • Subversion and Eclipse under windows
   • Subversion and Netbeans
8. Some IBM articles on ssh key chains.

Remote CVS or SVN connection with ssh

Concurrent versions system and Subversion (SVN) are source code management systems that are able to maintain several versions of so called configuration items in a store, otherwise known as repository. The configuration items are stored on the repository server and can be accessed through client software, possibly over a network.

Purpose of this page

In this text we describe the steps to be performed both for Linux and other Unix or Unix like operating systems (like Apple OSX, *-BSD) and then for windows using freely available software components.

Documentation on how to use CVS or SVN itself can be found in the online document called cederqvist after the original author, or the svn book for SVN.
Information on CVS is available at the cvs wiki.

For the intended audience of this website, students of the 'Techniek' department of the Fontys technical university in Venlo, the Netherlands, there is more documentation on what this server is all about. They support this site by paying the monthly fee.

SubVersion on fontysvenlo.org too

For the impatient there is a small guide to create a svn repository structure in a jiffy.

Now we support both CVS and subversion(SVN) as this is gaining popularity and has some additional benefits. So those that would like to, can start using SVN. Note that for private/personal repositories we still only support ssh connections, no http(s) connections, for various reasons.
Below you see that aplications that have a close connection to the open source world also integrate well with either CVS (included as standard) or subversion (a plugin for netbeans and eclipse).
The situation is not as good in Microsoft country, for they have a competing product integrated in Visual Studio and there are some commercial products whose creators have payed the integration licence fee. Of course you can use tortoiseXXX. See below For the visual studio fans there is a extra plus for subversion: There are two clients for the Microsoft^® VisualStudio^© IDE development environment:

1. VisualSVN is a commercial client VisualSVN. It has a 30 day trial version. After that, you have to pay, but then that is normal in a commercial envorinment and you chose it. (The fee is small though).
2. Ankhsvn is a opensource client hosted by the tigris website, website which is big on opensource stuff and svn. The jury is still out on the meaning of the first four letters in A N K H S V N.

Note that I do not have experience with either product.

Notation

In this text code formatted in this way is the example text in a Linux session. The emphasized text is what you have to enter.

like this:
you@client:~ $ ls -l

The examples assume that you are the user called you... and that you have accounts on both the client named client and the server called server.

Communication Protocol

The default communication protocol used by cvs is the so called pserver protocol. This protocol is fine for a LAN network, but has the problem that the authentication is done in a way that makes it 'clear-text' equivalent. This declares in unusable on the Internet. The same applies for the svn protocol and the other protocol supported by svn: http. Luckily the protocols can be tunneled through other communication protocols, of which the secure shell (SSH) protocol is a good choice.

Configuring SSH with public key encryption/authentication

The ssh protocol uses a symmetrical encryption for the data transport per se, but starts with using an asymmetrical encryption protocol with a private/public key pair to exchange the symmetrical key for the data transport. This first phase of the protocol requires that the client and server authenticate each other and explains why ssh asks if you want to add the server's public key to the known_hosts list, the first time you login using ssh. After the software is ready authenticating, the user has to authenticate himself by entering his password. This is acceptable for a one time login but becomes a burden when using ssh as a tunneling protocol, for it would ask for the user's password on each transaction. (In terms of cvs: on each add, commit, update or checkout). This can be helped by also creating a private/public key pair for the user.

In this document I make a distinction between a password and a pass phrase. The password is used to login to the server, the pass phrase is used in combination with the ssh-keys and the ssh-key agent.

Some articles about SSH key management by Daniel Robbins

• OpenSSH key management Part 1
• OpenSSH key management Part 2
• OpenSSH key management Part 3

Generating user keys for the ssh protocol for *x operating systems

Generating the key pair is quite simple.

The user should login on the/a computer that he wants to use as the client. Normally this is NOT the repository server.

Execute the steps in this order:

1. Login into the client computer. You know how to do that, don't you?

2. Generate a ssh-key pair

   you@client:~ $ ssh-keygen -t rsa

   You will be asked where to store the file. Accept the default.

   Generating public/private rsa key pair.
Enter file in which to save the key (/home/you/.ssh/id_rsa):

   You will be asked for a 'pass phrase'. Enter some text (can be longer then a word and include spaces) you can type and remember.

   The text you enter will not be echoed, so to test your typing skills you are asked to enter the text twice...

   By the way, you could use the same key pair for more client/server connections, although its safer not to do so.

3. If your machine provides the ssh-copy-id, then that is the most comfortable way to transfer your key:
   you@client:~ ssh-copy-id -i /home/you/.ssh/id_rsa you@server
   Then continue with using the agent. See its short man page for the details.

   Otherwise:
   

   Copy the public key to the server and enter it in the file ~/.ssh/authorized_keys. In the next two steps you will be asked for the 'normal' password on server. Enjoy it; These will be the last times.
   you@client:~ scp .ssh/id_rsa.pub you@server:~
you@client:~ ssh you@server 'cat id_rsa.pub >> .ssh/authorized_keys'
you@client:~

   You are still at client now. The server has your public key. Thereby it can authenticate you or your processes since they can get at the private key on your client.

4. Start the key agent. This is your buddy. He remembers the pass phrase entered and manages the keys that you have. You have to use a specific syntax to start the agent.

   you@client:~ eval `ssh-agent`
   Note the backward quote characters in this command. On the default us keyboard they are on the same key as the tilde (~), left of the '1' key. If your shell is bash (the default under most Linuxes) the you may also write
   you@client:~ eval $(ssh-agent)
   

   If you often use ssh in this way, it is more comfortable to add the previous syntax to your .profile file. In this way the ssh-agent is already started at log on time. And if you are using a graphical shell (KDE, Gnome and the like), the key activated in one shell is available to all your other processes.

5. Add the key to the key-agent. You must do this once per session, thus normally once after you login. You will be asked for the pass phrase for this. Enter it. The pass phrase will not be echoed. Not even stars ;-)

   you@client:~ ssh-add
Enter passphrase for /home/you/.ssh/id_rsa:

6. Test it.
   If you login to the server with ssh, the agent can provide ssh with a key and you do not have to enter any password. This applies to all applications that use ssh as a tunneling protocol. So once the agent has the key, all applications during that session can use that key.

   you@client:~ ssh server
you@server:~ $ echo "Look Ma, I am in! Without a password..." | mail ma@home.nl -s nohands
   Note that you should substitute your mothers real email address to make the previous command work ;-).

7. CVS specific: CVSROOT and protocol

   For cvs to use the proper cvsroot and protocol, set the environment variables CVSROOT and CVS_RSH. CVSROOT specifies the protocol(ext), user(you),server(server) and absolute path on that server (/home/you/cvsroot) to the cvs repository. Of course you could set these environment variables in your .profile file.

   you@client:~ export CVSROOT=:ext:you@server:/home/you/cvsroot
you@client:~ export CVS_RSH=`which ssh`
   

   If you are using eclipse, stick to the :ext: protocol and do not use the :extssh: offered by eclipse. Use the methods described above. Although it seems conventient, as you can let eclipse handle a few steps, like remembering your password, :extssh: is NOT an approved CVS protocol, so other CVS clients then Eclipse will not be able to access the protocol. This is especially annoying if you have tortoiseCVS installed. Everything looks like a sandbox from a reposity, but is not usable as such. :extssh: will also be unsuable from December 19 2008 as it is not compatible to public key authentication.

8. SVN specific: selecting the protocol through the url.

   For svn to use the proper protocol, select svn+ssh:// as the url prefix.Then for the rest it will work as with CVS.

If all this was succesfull, you have to start the ssh-agent as described in step 4 once per session, add the key('s) once thereafter and all should work smoothly.

You can use CVS as you were used to. Or start using it as intended and described in the previously mentioned sources.

Windows: The putty suite and Tortoise(CVS|SVN)

If you conceptually understand the previous chapter, than you should be able to grasp the rationale behind the steps to take when you want to access the repository from windows.

1. Install the putty suite. Enter putty in the google search engine and use the second link to download the Putty suite. Unpack it somewhere convenient. The directory where you unpack is the installation directory. So that′s simple.

2. Create a pub/priv key pair.
   

   Start puttygen.exe.

   

   Select the radio button SSH2 RSA key type (at the bottom). Click generate key. Move your mouse around in the empty gray area to generate some random data. If you don't, you'll be sitting here all day. Then enter a Key pass phrase (something you can remember) and then enter it once more in the box Confirm pass phrase to test your typing skills. Then click Save private key and choose a good place to store this private key. A USB memory stick could be handy here. Then you can take your key pairs to other sites. Save the pub key too. Name its file something like my_key.pub (Bit of a silly name if you're called you...)
   

   By the way, you could use the same key pair for more client/server connections, allthough its safer not to do so.

3. Copy the public key to the server.
   This IS especially easy if save the key in the same directory as used to install the putty suite. You can use the command line program pscp.exe in that directory to copy the pub key to the server.

   You start cmd.exe (if you live on a NT or win2k or XP box) from start>run and navigate (with cd and possibly <driverletter>:, but hey, you knew that, this is DOS. Then execute the command
   C:\putty>pscp server.pub you@server:
   Mind the final colon (:). The ssh protocol will ask you for the password on the server in the same way as usual.

4. Import the key into the ~/.ssh/authorized_keys file.

   This is easy if you use this script import_putty_key installed on the server. Which it is on this server.

   C:\putty>plink you@server "import_putty_key server.pub"
   which executes the import_putty_key with the appropriate argument on the server.

5. Now start the application pageant.exe. This is the key-agent, your trustworthy buddy that remembers your key and pass phrases. Load the key you prepared in step 2. It ask for the pass phrase. You should know what that means by now. Once you are done everything is in place and you can use putty to start an ssh session to the server or use the ssh protocol with e.g. tortoiseCVS. (See the tortoiseCVS download page.) or tortoiseSVN or locally from here for your convenience. An MD5 file is here too.

6. Install tortoiseXXX. Then you′ll have to restart windows :-(. Sorry, Windows.

7. Of course, each time you log in you have to start the key-agent pageant once and load the appropriate key. Same as under Unix.

8. Configuring tortoiseCVS for ssh and the server is a matter of specifying ext as the protocol to use. TortoiseCVS will use ssh as the protocol in that case. You should also specify host (server) username and directory to he repository. Then start doing your versioning things.

   TortoiseSVN can use ssh also. Specify svn+ssh://you@server/path/to/repos as the protocol/path.

9. Both putty and tortoiseCVS have help files. So don't ask me but read them.

Keys and key-agents on Apple MAC-OS X,

which is based on unix by the way, you can produce the keys just as it is done on the linux platform, see above. This is clear for the knowledgeable, since MAC-OS has a BSD background and (open)ssh originated in that part of the Unix universe.

But there is one caveat: if you put all the necessary stuff in your .profile file, you can get along after you entered ssh-add and so-on, but that works only in that specific terminal session and for all programs started from that terminal session; If you start a new terminal, a new agent is started in that new terminal.

You can fix this easily using one of the following tools:

• There is a tool for managing the agent: SSH-Agent
• There also is a tool for making things very easy, especially if you add the following program to your start-up items: SSHKeychain

FIXME If you use subversion on apple, you might also want to use the javahl library, to get the described comfort see below

Using CVS and eclipse

Simon Wegert provided me with a handy description on how to use cvs in combination with eclipse. The description also explains how to activate the cvs edit funtionality within eclipse.

Subversion and IDE's

For SVN with Eclipse you need a plugin. SubClipse is the official one from the SVN boys and girls. It will be installed on the Linux boxes in the lab.

To get the same, optimum comfort as described above with eclipse and subversion, use the javahl library. This library is part of the subversion distribution.

On *nix this means that you have to add the directory in which the javahl library resides to the java.library.path. On SuSE linux for instance this means that you could set this in either /etc/eclipse.conf if you have root, or in ~/.eclipserc. The line that works for me in /etc/eclipse.conf is

# Arguments to pass to the JVM.
VM_ARGS="-Xms64M -Xmx256M -Djava.library.path=/usr/lib"
      

which means that I set the java.library.path to /usr/lib. The other args where already there. A similar effect can be achieved by copying the same line to your ~/.eclipserc file. But have a look in your /etc/eclipse.conf first to get the other args right.

On *nix (including Apples I suppose, FIXME) eclipse is started with a shell script. Do not change that, but use the facilities already programmed into that shell scipt, like sourcing the /etc/eclipse.conf or the $HOME/.eclipserc configuration files, as in the example above.

Windows, subversion and eclipse.

On windows javahl should also work as it comes with the subversion part of tortoiseSVN.
To get javahl working on windows, the trick is to make sure you have a ssh.exe program in the %PATH%. As a tortoiseXXX fan, I am glad to tell you that tortoiseSVN brings along just the thing you need: TortoisePlink.exe in its bin directory. This originates from the putty suite. The trick is to copy this program to a directory on the path, for instance c:\windows on your machine, and rename that copy to ssh.exe. Now the JNI interface is able to find an external ssh program that fits its purpose to create an ssh tunnel for you. Thanks to Eric Hicks for helping me testing it on his machine.

Netbeans and Subversion

On the page FaqSubversionSSH you can read that you should add a few things to your $HOME/.subversion/config file. This file has several named sections like [helpers], [tunnels] etc In the [tunnels] section add

ssh = $SVN_SSH ssh -l <username on server>

The same applies for windows, with the small exception that you can use putty's plink as the ssh program. Like in

ssh = $SVN_SSH plink -l <username on server>

You might have to add plink.exe to the %PATH%

This makes everything work with the same comfort on all platfoms (one time passphrase entry to the ssh-agent) as with the other programs.

Some IBM articles on ssh key chains.

IBM has a lot of usefull stuff on opensource, java and other interresting things for the hacker. Here is some on ssh key chains.

• OpenSSHkey management Part 1
• OpenSSHkey management Part 2
• OpenSSHkey management Part 3

Happy committing visitor number Charlie!

The picture of my wonderful assistant Charlie. His full name is Charlie Vernon Smythe, which by pure change happens to yield the same initials as our favourite version control tool. He′s been pictured by Nathan Thomas. I borrowed the picture from the tortoiseCVS site. He's cute, don't you think?.

---

Pieter van den Hombergh Docent fontys