subversion logo hor-468x64.png @ PSI

1 Overview

Subversion is a widely-used version control system. AIT provides a Subversion service for INTRANET as well as INTERNET users. The service can be used for software development at PSI as well as for worldwide collaborations. It is directly accessible from all over the world via SSH and HTTPS.

For the time being Subversion repositories are supported inside an AFS project or group path only.

You should avoid huge repositories. One repository for everything is inviting first, but in the course of time the repository may grow beyond of manageability. Splitting a huge repository isn't fun at all. We strongly recommended to use different repositories for unrelated sub-projects.

1.1 Step by step setup

  1. apply for a new AFS project, if the new repository doesn't match an existing project.
  2. (optional and for advanced users only)Setup AFS groups.
  3. (for the first repository)Setup the root directory for the repositories,
  4. Create new repository and setup AFS access control lists.
  5. Configure the Subversion server.
  6. Configure path based authorization.
The steps 4.-6. are mandatory for all new repositories!

1.2 Important notes

  • We run Subversion 1.6.11 on the server. This is not the newest version but the repositories are compatible with 1.7. This may be an issue in the future.
  • The repository type fsfs must be used. Berkeley DB doesn't work on AFS (and other network filesystems).
  • By default access is granted for the "anonymous" user svn with password svn. Please read the section about authorization to disabled anonymous access!
  • After creating the directory svn in your project, it may take up to one hour for the repository to become accessible via the documented path.

1.3 Abbreviations used in this document

$A
AFS group to administer the repository (-ies)
$P
Project name
$PP
Path of project /afs/psi.ch/project/$P
$R
Repository name
$S
A subversion server (like savannah01.psi.ch). For the time being we run two Subversion servers.


2 Setup AFS groups

This step is for more advanced users and use cases only. In the most cases you can skip this step.

In case the project administrators don't want to administrate the Subversion repositories, they can delegate this task to another group. A project administrator must create one of the following AFS groups and add the appropriate members:

$ $P:svn.administrators: If the project administrators want to delegate the administration of all repositories in project $P.

$ $P:svn.administrators.$R: If the project administrators want to delegate the administration only for the repository $R in project $P.

3 Setup the repository root

3.1 New projects

If you got new project space, this step is not necessary any more. The root for your Subversion project is already initialized. But anyway it's better to verify the existence of a directory named svn in your project space.

3.2 The easy way - for old projects

To create the root directory with default setup, change to the appropriate project or group path and run /afs/psi.ch/service/bin/create_svn_root. That's all.

This will work in most cases. Following preconditions must be full-filled (assuming that $P is the project/group):
  • The project/group directory must exist.
  • The AFS group $P or $P:administrators must exists.
  • You must be member of this group.
  • This group must have AFS administer rights on the project/group directory.
Example
$ cd /afs/psi.ch/project/opal
$ /afs/psi.ch/service/bin/create_svn_root 
Creating new Subversion root in /afs/psi.ch/project/opal


The script accepts several arguments, please run the script with --help to get a more information.

3.3 By hand

3.3.1 Create the root directory

All Subversion repository of a project must be in the directory /afs/psi.ch/project/$P/svn:
$ mkdir /afs/psi.ch/project/$P/svn

3.3.2 Set AFS access control lists for the root directory

Setup the AFS access control list as follows:
Directory AFS group ACL
$PP/svn $A rlidwka
$PP/svn softwarehosting:svnhosts l
Where $A is either:
  • $P if the project administrators also administer the repositories. Notabene: In same cases the name of the project administrator group is $P:administrators!
  • $P:svn.administrators if the project administrators delegate the administration of all repositories.
  • $P:svn.administrators.$R if the project administrators delegate the administration of repository $R to this special group.
Remove all other ACLs! The ACL listing should look like:
$ fs la /afs/psi.ch/project/linux/svn
Access list for /afs/psi.ch/project/linux/svn is
Normal rights:
  linux:administrators rlidwka
  softwarehosting:svnhosts l

4 Create Repository

4.1 The easy way

To create a new repository $R with default setup in a project/group $P, change to the appropriate path and run
$ /afs/psi.ch/service/bin/create_svn_repo $R
That's all.

This will work in most cases. Following preconditions must be full-filled:
  • The project/group directory must exist.
  • The AFS group $P or $P:administrators must exists.
  • You must be member of this group.
  • This group must have AFS administer rights on the project/group directory.
Example
$ cd /afs/psi.ch/project/opal
$ /afs/psi.ch/service/bin/create_svn_repo src
Creating new Subversion repository "src" in project "opal"


The script accepts several arguments, please run the script with --help to get a more information.

4.2 By hand

4.2.1 Create repository

Change directory to /afs/psi.ch/project/$P/svn and run the command

svnadmin create --fs-type fsfs $R
  • The repository type fsfs must be used. Berkeley DB doesn't work on AFS (and other network filesystems).
  • We are still runnning Subversion 1.4 on the server-site. The option --pre-1.5-compatible must be specified with newer clients. Omit the option, if you have Subversion 1.4. You can check the version of the installed Subversion with the command svn --version.

4.2.2 Setup AFS access control lists

The rights to access your repository is not handled via AFS access control lists. Authorization - the right to access a repository - has to be configured in the file conf/authz of the repository. Please read the section about path based authorization for more information. Nevertheless the administrators of the repository and the Subversion servers themselves must have appropriate access rights to the repository.

4.2.3 ACLs for the repository administrator group

Set the following access rights for the repository administrators, substitute $A with the appropriate AFS group name:
Directory AFS group ACL
$PP/svn/$R $A rla
$PP/svn/$R/dav $A rla
$PP/svn/$R/locks $A rla
$PP/svn/$R/hooks $A rlidwka
$PP/svn/$R/conf $A rlidwka
$PP/svn/$R/db $A rla
$PP/svn/$R/db/revs $A rla
$PP/svn/$R/db/revprops $A rla
$PP/svn/$R/db/transactions $A rla

4.2.4 ACLs for the Subversion servers

All Subversion servers at PSI are managed in the group softwarehosting:svnhosts. Grant following access rights to this group:
Directory AFS group ACL
$PP/svn/$R softwarehosting:svnhosts rl
$PP/svn/$R/conf softwarehosting:svnhosts rl
$PP/svn/$R/dav softwarehosting:svnhosts rlidwk
$PP/svn/$R/db softwarehosting:svnhosts rlidwk
$PP/svn/$R/db/revprops softwarehosting:svnhosts rlidwk
$PP/svn/$R/db/revs softwarehosting:svnhosts rlidwk
$PP/svn/$R/db/transactions softwarehosting:svnhosts rlidwk
$PP/svn/$R/hooks softwarehosting:svnhosts rl
$PP/svn/$R/locks softwarehosting:svnhosts rlidwk

4.2.5 Example

$ fs la /afs/psi.ch/project/linux/svn/sl5/*
Access list for /afs/psi.ch/project/linux/svn/sl5/README.txt is
Normal rights:
  linux:administrators rla
  softwarehosting:svnhosts rl

Access list for /afs/psi.ch/project/linux/svn/sl5/conf is
Normal rights:
  linux:administrators rlidwka
  softwarehosting:svnhosts rl

Access list for /afs/psi.ch/project/linux/svn/sl5/dav is
Normal rights:
  linux:administrators rla
  softwarehosting:svnhosts rlidwk

Access list for /afs/psi.ch/project/linux/svn/sl5/db is
Normal rights:
  linux:administrators rla
  softwarehosting:svnhosts rlidwk

Access list for /afs/psi.ch/project/linux/svn/sl5/format is
Normal rights:
  linux:administrators rla
  softwarehosting:svnhosts rl

Access list for /afs/psi.ch/project/linux/svn/sl5/hooks is
Normal rights:
  linux:administrators rlidwka
  softwarehosting:svnhosts rl

Access list for /afs/psi.ch/project/linux/svn/sl5/locks is
Normal rights:
  linux:administrators rla
  softwarehosting:svnhosts rlidwk

5 Configure the Subversion server

Setup the Subversion configuration in /afs/psi.ch/project/$P/svn/$R/conf/svnserve.conf as follows:
[general]
anon-access = none
auth-access = write
authz-db = authz

6 Configure path based authorization

The Subversion authorization mechanism must be used. The file for per-directory access control is /afs/psi.ch/project/$P/svn/$R/conf/authz.

Please read the Subversion documentation about path based authorization for more details.
  • You should add * = as last line. Otherwise the repository is open to everybody.
  • In the Subversion documentation the question "Do You Really Need Path-Based Access Control?" is posed. In contradiction to their recommendation, you really should setup path based access control! But keep it as simple as possible.

6.1 Example

[groups]
users = harry,sally

[/]
# grant read and write access to the group users
@users = rw

# Bob can only read
bob = r

# the next line diables anonymous access!
* =

7 Accessing your repositories

7.1 Subversion servers

Currently we have two Subversion server running, both serving the same repositories and setup identically.

savannah01.psi.ch and savannah02.psi.ch
These are the server names. You can use both systems, neither is preferred.


savannah.psi.ch and svn.psi.ch
Are alias names for savannah01.psi.ch.

7.2 Authentication

You can authenticate with your PSI account.

This is the short answer. Unfortunately - for the time being - the long answer is a bit more complicate. The UNIX attributes must be set in your account. Everything is fine, if you have an AFS/Linux account or one of the new "external" accounts with Subversion access. If you are unsure whether have the right account setup or not, just try to SSH to one of the Subversion servers as described in the troubleshooting section.

7.3 Supported Access Methods

The Subversion servers at PSI support Subversion access via SSH and HTTPS. Direct access is possible, but not recommended and not documented here.

Both supported methods provide worldwide access to the repositories. Single-sign-on (SSO) is supported via GSSAPI/Kerberos5. So there is no need to enter the password again and again (SSH) or to store the password somewhere on the filesystem (HTTPS). Please read the section about password-less authentication.

7.3.1 Access via svn+ssh

Access via svn+ssh is the recommended method for the most use cases. It is available "out of the box" after initializing the repository and setting the AFS access rights without any additional configuration.

To access repository $R in project $P on server $S via the svn+ssh -method use the following URL:
svn+ssh://$S/repos/$P/$R


Notes
  • Public key authentication is not available - use GSSAPI/Kerberos5 for password-less authentication.
  • Password authentication may ask you for the password several times - depending on the operation. This can be very annoying.

7.3.2 Access via https

If you need access to your repositories via the HTTPS-method, please contact the Help-Desk. This method is not available by default.

To access repository $R in project $P on server $S via the HTTPS -method use the following URL:
https://$S/repos/$P/$R


Notes
  • You must use https.
  • Performance can be very slow on large repositories.
  • It is possible to restrict the repository access to dedicated networks, e.g. the PSI intranet. If you need this, please contact the Help-Desk.



8 Password-less authentication

Public-key authentication to the Subversion servers is not possible, but you can authenticate via GSSAPI/Kerberos5. Since the unified logon service at PSI is based on Kerberos5, you can access you repositories without entering a password. But you may have to configure your application!

Please contact the Helpdesk, if you do not use a PSI installation of Linux or Windows and Kerberos5 is not already configured.

8.1 SSH on Linux and Mac OS X

You must enable GSSAPI Authentication on the client. Add the following line to ~/.ssh/config to /etc/ssh/ssh_config.
GSSAPIAuthentication yes

8.2 TortoiseSVN

TortoiseSVN talks to the Subversion server either via HTTP(S) or svn+ssh. Since HTTP(S) requires configuration on the server and is much slower than svn+ssh, we strongly recommend to use svn+ssh.

The following procedure will not work for Windows installation without PSI customization.
  • Check whether a command-line SSH-client with GSSAPI/Kerberos5 support is installed on your system:
    • Open a cmd-window
    • Run plink -V
      • If plink is installed, the above command outputs the version,
      • otherwise you will get the message 'plink' is not recognized as an internal or external command
    • If plink is not installed or the version is less than 0.60, download the current version from the PuTTY web site.
  • Before you can use plink with TortoiseSVN, you must add the host key of savannah01.psi.ch to the cache of known hosts. Run the command:
    plink savannah01.psi.ch
    . Type 'yes' to accept the host key. You should not be prompted to enter a password. If everything works fine, the connection will be closed immediately after successful authentication by the remote system.
  • Configure TortoiseSVN to use the kerberized PuTTY
    • Open Windows Explorer
    • Right click in a folder and select TortoiseSVN > Settings
    • Click on the "Network" section
    • Put the path to the kerberized plinkw.exe in here (e.g. "C:\Program Files\Quest Software\PuTTY\Plinkw.exe")
    • Click OK
In addition to TortoiseSVN we recommend the installation of a command line Subversion client like SlikSVN.

9 Troubleshooting

Troubleshooting Subversion can be tedious. Sometimes error messages are meaningless or hard to understand. The best way to debug problems is with SSH on the command line. SlikSVN is a command line client for Subversion on Windows.

9.1 Authentication

To test whether you can authenticate to our Subversion servers, try to connect to one of them with SSH.

Example if authentication was successful:
$ ssh svn.psi.ch
Last login: Mon Jan 14 15:33:27 2013 from nienor.psi.ch

Hi gsell!
You've successfully authenticated, but this system does not provide shell access.
Good bye ...

Connection to svn.psi.ch closed.

9.2 Authorization

Run (substitute $P with the corresponding project/group and $R with the repository):
svn list svn+ssh://svn.psi.ch/repos/$P/$R
If you get the message
svn: E170001: Authorization failed
authentication was successful, but you don't have permissions to access the repository. Please read the section about path based authorization.

9.3 Access via HTTPS

Access via the HTTPS method is not configured by default and you get really stupid error messages;
$ svn list https://svn.psi.ch/repos/pifg/POLAR/
svn: E175002: Unable to connect to a repository at URL 'https://svn.psi.ch/repos/pifg/POLAR'
svn: E175002: The OPTIONS request returned invalid XML in the response: XML parse error at line 1: no element found (https://svn.psi.ch/repos/pifg/POLAR)
In case of problems with the HTTPS method, please test authentication and authorization via SSH first.

10 Browsing your Repositories

If you want to browse your repositories with a web-browser, please contact the help-desk to enable this.

VievVCScreenShoot.png

11 Some AFS commands

11.1 Create group for repository administrators

pts creategroup NAME -owner OWNER
If the name of the project administrator group is $P
pts creategroup  $P:svn.administrators -owner $P
If the name of project administrator group is $P:administrators
pts creategroup $P:svn.administrators -owner $P:administrators

11.2 Add user to a group

pts addu USER GROUP

11.3 Set ACL

fs setacl DIR GROUP RIGHTS

11.4 Clear ACL

fs setacl DIR GROUP none

12 Links

Subversion home page

The book "Version Control with Subversion"

PuTTY home page

Command line client for Windows

TortoisSVN