Committer access (Buckminster)

Setting up Subclipse for committer access to the Buckminster repo

In order to commit to our SVN repository at Eclipse.org, you need to setup the svn+ssh protocol. Thomas: After some trial and horror, these are the steps I made to make everything work smoothly. Henrik: After some additional 'trial and horrors' trying to set up access on OS X Leopard we discovered that there is a 'much simpler' way to access the source repo.

We are currently testing how well this simpler approach is. In essence, instead of using the JavaHL bridge from the Subclipse client to subversion, and where subversion uses public key encryption, you can simply use the SVNKit in Java and use password authentication! These are just settings in Eclipse Preferences for Team > SVN. (You do still need to download ssh if you are on windows).

This page should be edited to show the simple way.

Prerequisites

1. Install Subclipse into your Eclipse IDE using the Eclipse update manager. Point your update manager to http://subclipse.tigris.org/update_1.0.x
2. Download and install a ssh client that will allow you to login to the server.
   

• On Windows you can use Putty from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
• On Mac OS X (Leopard, not tried earlier version), you can use the Terminal (found under Applications > Utilities in the standard Leopard installation), and use the ssh command (as described further on in the text).

Server configuration

1. Using your ssh client and your committer login/password, login to "dev.eclipse.org". (On Windows you can use Putty, on OS X Leopard, just use the included Terminal, and type ssh -l mylogin dev.eclipse.org)
2. if you have been given a restricted shell you can not do much - (if you are using Putty and just hit enter, the putty SSH client will terminate without a message, and on OS C from the command line, you are told that commands can no be executed and the connection closes). So - if you can hit enter at the prompt, you can proceed with the steps below. Otherwise contact webmaster@eclipse.org and explain your problem.
3. Make sure you are in your home directory and create a public/private key pair with ssh-keygen, but before you do that look at the options:
   1. If you are on OS X Leopard you should use a passphrase for the private key (Instructions on this page assumes that you do). Leopard will store this passphrase in the secure local keychain for you, so you do not have to reenter it for every command.
   2. Windows users should either consult the Putty documentation how to set up a service kalled Pageant that keeps the passphrase in memory during the session, or generate the key without a passphrase.
   3. Linux users have several options to run such a service (SSHKeychain is one such service)
   4. Unless you have OS X Leopard, or a service to handle the passphrase - Do not use a passphrase (you avoid the passphrase by using the -N '' at the end of the command - that is -N followed by a space and then two single quotes). If you do use a passphrase, you'll be asked for it over and over again by the svn client:
4. Type the command:

   ssh-keygen -b 1024 -t dsa -f mykey -N 'password'

5. Create the .ssh folder and copy your public key to the authorized_keys file in that folder.

   mkdir .ssh

   cp mykey.pub .ssh/authorized_keys

6. Set the correct permissions

   chmod 700 ~/.ssh

   chmod 600 ~/.ssh/authorized_keys

7. Copy the contents of the private key (the file named mykey with no extension) to your clipboard and paste it into temporary file on your local computer.

Client configuration

Configuring Windows Client

1. Convert the key into a format that is usable by PuTTY and plink.
   1. Download http://the.earth.li/~sgtatham/putty/latest/x86/puttygen.exe (if this is not already included in your Putty installation)
   2. Import the temporary file you just stored. Use Conversions -> Import key.
   3. Save the converted private key to a file of choice by clicking on "Save Private Key" and then select a filename - I use "c:\Documents and Settings\Thomas Hallgren\SSHKeys\eclipse_key.ppk". (Note that you should *not* press "generate" that creates a new key. Also note that the PuttyKeyGenerator may crash when selecting location and file name to save the key in - check if the file was created if you suspect that it crashed, and try again). You can check that the generated .ppk file starts as follows if you are having trouble.

PuTTY-User-Key-File-2: ssh-dss
Encryption: none

1. Download and install Tortoise for SVN from: http://tortoisesvn.net/downloads. The plink.exe supplied with Tortoise is a command line client that is silent (i.e. doesn't pop up an annoying cmd window each time it's called).
2. Find your subversion configuration file and the section called [tunnels]. Make sure this section is not commented out. The file is found at %APPDATA%\Subversion\config on a typical windows installation.
3. Add the following line, substituting your home folder, login name, and the path to the private key file that you saved in step #1. Be sure to use double backslashes.

   ssh = "C:\\Program Files\\TortoiseSVN\\bin\\TortoisePlink.exe" -ssh -l <your login> -i "c:\\Documents and Settings\\<your home>\\SSHKeys\\eclipse_key.ppk"

You should be able to use subclipse from now on. Our SVN repo is at:

svn+ssh://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster

But note that when you supply a URL to set up access you should not include the path - the URL is: svn+ssh://dev.eclipse.org/svnroot/tools

If you have previously set up anonymous access to (for read only) access to buckminster. Use Subclipse Repository Relocation.

1. Open all your Buckminster projects in the Eclipse IDE
2. use the object menu (right mouse click) over the previous location) and select "Relocate"
3. use the new URL svn+ssh://dev.eclipse.org/svnroot/tools (no buckminster at the end)
4. When you hit Finish, the Finish button will get pressed in, and then nothing appears to happen for a long time...

Optional

In order to use the TortoiseSVN GUI you also need to tell that client what SSH it should use (for some reason look at the SVN config file).

1. Right click on any folder in your normal Windows file explorer. Select TortoiseSVN -> Settings -> Network.
2. Copy the ssh = ... line from the config file. Leave out the leading "ssh =" and substitute all double \\ for single \. (keep the " characters if you have spaces in the file paths, otherwise the quotes are not needed).

Now TortoiseSVN should work fine as well.

Observations and hints

If you have PuTTY installed, be sure you have the "Default settings" configured to use SSH version "2" or "2 only", otherwise the SSH key doesn't work.

If you happen to set up the PuTTY Default Settings for SSH version "1" and you are not able to change this setting using PuTTY gui (this can happen e.g. if you import registry settings), you can edit the windows registry (HKEY_CURRENT_USER/Software/Simon Tatham/PuTTY/Sessions/Default%20Settings/SshProt, set to value "2").

Configuring OS X (Leopard) Client

(WIP - I am trying to set things up right now, and document the steps - this section is not yet finished) After going through the motions of setting up javaHL, and understanding how SSH and private keys work on OS X I learned that there is a simpler way. All that is needed is to use the java SVNKit instead of javaHL.

Here is what you need to to do:

• Go to Eclipse Preferences > Team > SVN, and select to use SVNKit instead of javaHL.
• Add the respository in the SVN repository view: "svn+ssh://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster"
• Done ! (none of the below setup of a private key is required).

Install the private key

The good news is that if you are using Leopard, the handling of the "ssh keys" is well integrated into the environment and the steps are quite simple. The not so good news is if you are using Tiger or earlier versions where you have to make a tradeoff between convenience and security. For Tiger there are downloadable software that can make handling of SSH keys just as convenient as when operating with less secure handling. If you are a Tiger user - you will need to figure these things out on your own (hint: the suggested article below has links to information).

1. If you are a ssh newbie / OS X newbie - then you may want to read this excellent article. In short - the OS X "Keychain Access" is integrated with the ssh-agent that handles the client side keys in such a way that you do not have to manually start the ssh-agent before you start your ssh connection (as is required on Tiger).
2. Before you go on to the next step - you need to have the private part of the key on a file on your client. If you don't - earlier in the process - you created a key on the server, and installed the public part. The private part is now needed on your client. A simple method is to show it in the terminal window and then copy paste it to a file on your local machine - when doing so you need to make sure that line endings are not changed as this makes the key useless.
3. Add the key to your OS X Keychain Access. Open "Applications > Utilities", and launch "Keychain Access"
4. Follow the instructions below (or if you want even stronger security - follow the instructions in the suggested article above).

Install Subversion

The first thing you need is to install Subversion as it comes with the required java bridge (JavaHL). (This is required in addition to having a subversion client in your Eclipse). There are several ways to obtain Subversion for OS X. The easiest is to use a packaged dmg that can be found here: http://metissian.com/projects/macosx/subversion/ but if you like a more linux flavored install you can use Fink (http://www.finkproject.org/) or Macports (http://www.macports.org) to get subversion. If you want to use Fink, or MacPorts, you have to consult their instructions.

Get Subversion from Metissian:

1. Go to http://metissian.com/projects/macosx/subversion/
2. Download the latest subversion dmg (recommend doing this in Safari, as it knows what to do with the dmg file)
3. When it is downloaded klick on the pkg file to start installation - just click through using defaults. Note that you will need to enter your OS X admin password to install.
4. Test your installation by (as suggested in the README file for the installation) i.e. type this command in a terminal window: svn cat http://svn.collab.net/repos/svn/trunk/README
5. If your Eclipse was started while you made the installation - you need to restart it, it will otherwise not find the javahl, and will complain if you go to the preference page for Team > SVN (you will get an error dialog stating that it can not find javahl)

Working and merging.

All Buckminster development work should be done on the trunk. The CQUERY to set things up is http://www.eclipse.org/buckminster/samples/queries/buckminster-dev.cquery. Once you've materialized your workspace, it's likely that you want to "Relocate" from the "svn" protocol" to "svn+ssh". Unlike CVS, this is not done automatically using our svn client (we need to address that as a bugzilla).

NOTE: The "normal" buckminster.cquery will give you the 3.2.x branch. You have to use buckminster-dev.cquery to get the trunk!

We do Buckminster work on the trunk and merge relevant things to the 3.2.x branch. This does *not* apply to Cloudsmith work. Cloudsmith work uses Eclipse 3.2.x everywhere. We don't want to be sensitive to changes in Eclipse 3.3 when developing the Cloudsmith server or website. So it's OK to add patches driven by Cloudsmith work to the 3.2.x branch and later merge them to the trunk.

Before you do anything, I recommend reading the "Subclipse - Subversion Eclipse Plugin" -> "Tasks" -> "Maintaining branches" chapter in the Eclipse Help.

1. Set up two workspaces. One for the trunk (using buckminster-dev.cquery) and one for branches/3.2.x (using buckminster.cquery).
2. Use Eclipse 3.3M5eh (or what's latest) on the trunk and Eclipse 3.2.2 on the 3.2.x branch.
3. Perform relevant changes on the trunk. Commit these changes.
4. Switch Eclipse (and workspace) to the 3.2.x.
5. Use Team -> Merge. Change the URL so that the "/branches/3.2.x/" part reads "/trunk/"
6. Click "Show Log" and select the relevant version (i.e. the last one).
7. Click Merge.
8. Verify that everything looks OK, change things if necessary.
9. Commit the 3.2.x branch.