Jump to: navigation, search

Difference between revisions of "Committer access (Buckminster)"

(Prerequisites)
(The more complicated way - using public key encryption)
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
=Setting up Subclipse for committer access to the Buckminster repo=
 
=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. After some trial and horror, these are the steps I made to make everything work smoothly.
+
In order to commit to our SVN repository at Eclipse.org, you need to setup the svn+ssh protocol. This used to be complicated, but is now quite simple when using password authentication and SVNKit. It is recommended that you use the simpler approach (unless you for some reason want to master the black art of ssh and public key encryption - instructions how to do this  are outlined on this page, but there is no guarantee that the information is up to date).
 +
 
 +
=Simplest way to set up SVN access=
 +
With this simple set up you will be using password authentication instead of public key encryption. You can do al of the setup yourself and you will be up and running in minutes.
 +
 
 +
# Make sure you have SSH support on you machine
 +
## On On '''Windows''' you can use Putty from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
 +
## On '''Mac''', Leopard users have SSH support - you do not have to do anything.
 +
# Install Subclipse into your Eclipse IDE using the Eclipse update manager. Point your update manager to ''<nowiki>http://subclipse.tigris.org/update_1.0.x</nowiki>''
 +
# Go to Eclipse Preferences > Team > SVN, and select to use SVNKit instead of the default javaHL.
 +
# Add the buckminster respository in the SVN repository view: "svn+ssh://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster"
 +
# Done
 +
 
 +
??? Unclear if a SSH is needed on windows when using SVNKit.
 +
 
 +
=The more complicated way - using public key encryption=
 +
This is not the recommended approach. Configuration is complicated, and you need to contact eclipse webmaster to get access to the eclipse servers to generate your key. Although they are responsive, you may have to wait a business day or so until you complete the setup. Also note that if your setup is not correct you will probably attempt to access the eclipse servers too many times with the wrong credentials which will block you from further access. If this happens you need to contact eclipse webmaster to remove the block.
  
 
==Prerequisites==
 
==Prerequisites==
 
# Install Subclipse into your Eclipse IDE using the Eclipse update manager. Point your update manager to ''<nowiki>http://subclipse.tigris.org/update_1.0.x</nowiki>''
 
# Install Subclipse into your Eclipse IDE using the Eclipse update manager. Point your update manager to ''<nowiki>http://subclipse.tigris.org/update_1.0.x</nowiki>''
 
# Download and install a ssh client that will allow you to login to the server. <br/>
 
# Download and install a ssh client that will allow you to login to the server. <br/>
* On windows you can use Putty from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
+
* On '''Windows''' you can use Putty from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
* On OS X (Leopard, not tried earlier version), you can use the Terminal (found under Applications > Utilities in the standard Leopard installation).
+
* 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==
 
==Server configuration==
 
# 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'')
 
# 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'')
 
# 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.
 
# 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.
# Make sure you are in your home directory and  create a public/private key pair with ssh-keygen. Do '''not''' use a passphrase (you avoid the passphrase by using the -N <nowiki>''</nowiki> 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:
+
# 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:
#: ssh-keygen -b 1024 -t dsa -f mykey -N <nowiki>''</nowiki>
+
## 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.
 +
## Windows users should either consult the [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html 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.
 +
## Linux users have several options to run such a service ([http://www.sshkeychain.org/ SSHKeychain] is one such service)
 +
## 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 <nowiki>''</nowiki> 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:
 +
# Type the command:
 +
#: <tt>ssh-keygen -b 1024 -t dsa -f mykey -N <nowiki>'password'</nowiki></tt>
 
# Create the .ssh folder and copy your public key to the authorized_keys file in that folder.
 
# Create the .ssh folder and copy your public key to the authorized_keys file in that folder.
#: mkdir .ssh  
+
#: <tt>mkdir .ssh </tt>
#: cp mykey.pub .ssh/authorized_keys
+
#: <tt>cp mykey.pub .ssh/authorized_keys</tt>
 
# Set the correct permissions
 
# Set the correct permissions
#: chmod 700 ~/.ssh  
+
#: <tt>chmod 700 ~/.ssh </tt>
#: chmod 600 ~/.ssh/authorized_keys  
+
#: <tt>chmod 600 ~/.ssh/authorized_keys </tt>
 
# 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.
 
# 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 Windows==
+
==Client configuration==
 +
===Configuring Windows Client===
 
# Convert the key into a format that is usable by PuTTY and plink.
 
# Convert the key into a format that is usable by PuTTY and plink.
 
## Download http://the.earth.li/~sgtatham/putty/latest/x86/puttygen.exe (if this is not already included in your Putty installation)
 
## Download http://the.earth.li/~sgtatham/putty/latest/x86/puttygen.exe (if this is not already included in your Putty installation)
Line 45: Line 67:
 
# When you hit Finish, the Finish button will get pressed in, and then nothing appears to happen for a long time...
 
# When you hit Finish, the Finish button will get pressed in, and then nothing appears to happen for a long time...
  
==Optional==
+
====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).
 
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).
  
Line 53: Line 75:
 
Now TortoiseSVN should work fine as well.
 
Now TortoiseSVN should work fine as well.
  
==Observations and hints==
+
====Observations and hints====
 
<p>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.</p>
 
<p>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.</p>
 
<p>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").</p>
 
<p>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").</p>
 +
 +
===Configuring OS X (Leopard) Client===
 +
====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).
 +
 +
# If you are a ssh newbie / OS X newbie - then you may want to read [http://www.dribin.org/dave/blog/archives/2007/11/28/ssh_agent_leopard/ 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).
 +
# 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.
 +
# Add the key to your OS X Keychain Access. Open "Applications > Utilities", and launch "Keychain Access"
 +
# 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:'''
 +
# Go to http://metissian.com/projects/macosx/subversion/
 +
# Download the latest subversion dmg (recommend doing this in Safari, as it knows what to do with the dmg file)
 +
# When it is downloaded click 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.
 +
# Test your installation by (as suggested in the README file for the installation) i.e. type this command in a terminal window: <tt><nowiki>svn cat http://svn.collab.net/repos/svn/trunk/README </nowiki></tt>
 +
# 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.=
 
=Working and merging.=

Latest revision as of 08:22, 10 September 2008

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. This used to be complicated, but is now quite simple when using password authentication and SVNKit. It is recommended that you use the simpler approach (unless you for some reason want to master the black art of ssh and public key encryption - instructions how to do this are outlined on this page, but there is no guarantee that the information is up to date).

Simplest way to set up SVN access

With this simple set up you will be using password authentication instead of public key encryption. You can do al of the setup yourself and you will be up and running in minutes.

  1. Make sure you have SSH support on you machine
    1. On On Windows you can use Putty from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
    2. On Mac, Leopard users have SSH support - you do not have to do anything.
  2. Install Subclipse into your Eclipse IDE using the Eclipse update manager. Point your update manager to http://subclipse.tigris.org/update_1.0.x
  3. Go to Eclipse Preferences > Team > SVN, and select to use SVNKit instead of the default javaHL.
  4. Add the buckminster respository in the SVN repository view: "svn+ssh://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster"
  5. Done

??? Unclear if a SSH is needed on windows when using SVNKit.

The more complicated way - using public key encryption

This is not the recommended approach. Configuration is complicated, and you need to contact eclipse webmaster to get access to the eclipse servers to generate your key. Although they are responsive, you may have to wait a business day or so until you complete the setup. Also note that if your setup is not correct you will probably attempt to access the eclipse servers too many times with the wrong credentials which will block you from further access. If this happens you need to contact eclipse webmaster to remove the block.

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

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 click 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.