Getting started with the Maths multi-user subversion server

Introduction

This started off as a draft document with instructions on how to use the multi-user SVN (Subversion) server that was set up in May 2011 alongside the traditional single-user SVN server set up earlier in February. Although initially launched as an experimental service (since subversion servers are intended by design to be run either by individuals or by a nominated SVN administrator with normally only one SVN repository per physical or virtual server) this experimental server has now matured sufficiently to be regarded as a permanent production service that is being extensively used by other departments as well as Maths.

The multi-user subversion server is svn.ma.ic.ac.uk and can be accessed through both ssh and from any web browser. svn can be accessed by repository owners from outside college via ssh but on a non-standard port for security reasons while external access to the repositories by both owners and users is through a web interface. Users, their accounts, their home directories and SVN repositories have no connection with college computer accounts and home directories and apart from its location and network connection, it is both isolated from and independent of the college and Maths IT infrastructure for security reasons.

How do I use it?

Setting up and activating your subversion repository can be broken down into the following steps:

1. first, ask for an account on the subversion server

2. logging into svn for the first time

3. uploading the data you want to share through SVN to the svn server

4. creating your SVN repository using the recommended layout

5. importing your uploaded data into the repository

6. deciding on who should have access to your repository, choosing usernames and passwords for others to access your repository through the web interface

7. deciding on what level of access these user(s) should have (read only, read and write or none) and whether certain parts of your repository should/should not be accessible to certain users, etc

8. letting the SVN administrator know how you want users and access permissions set up so that this can be set up for you

and that's it. Once you have created the repository and imported the initial data into it, all further interaction with it can be done through the comfort of your web browser although you can still log into the server and use the SVN command line utilities to manage this.

Getting a SVN account

To get an account on the SVN server, simply contact Andy Thomas and ask for one - you will need to give your full name and your college username (or login name). You will receive an email confirming this has been set up along with your username and initial password, both of which will be different to your college username and password.

Logging into svn

svn accepts direct logins via ssh (SecureSHell) both from from within college and on port 10022 for external logins - note that this port for external connections is not the default ssh port 22. If you are using Linux, a Mac or some other UNIX-like system you can log into the SVN server from outside the college with a command like this:

ssh -p 10022 username@svn.ma.ic.ac.uk

if you are a Windows user, you can use PuTTY to connect to svn but do remember to select port 10022 when you do this otherwise your connection attempt will be rejected.

If you are connecting from within college or from outside via the Imperial VPN service, then you don't need to specify port 10022 as the connection will be made using the standard ssh port 22.

Once you have logged in for the first time, please change youur password! The password you have been given in the email confirming your account is a random one known only to the SVN administrator but you should change it to something more memorable to yourself. You can do this using the passwd command:

jbloggs@svn:~ $ passwd
Changing password for user jbloggs.
Changing password for jbloggs.
(current) UNIX password: 
New password: 
Retype new password: 
passwd: all authentication tokens updated successfully.

Uploading your data to the SVN server

The data you will want to serve from the SVN server will be some kind of directory or tree structure containing one or more subdirectories (folders) and files. Although you could log into svn and set up the same directory tree structure there and copy the files over one by one, it is much easier & quicker to archive what you already have into a single file and upload this to your SVN account. How you do this is up to you - you can use tar, or tar with the -z compression option to create a .tar.gz or .tgz compressed tar file, or use the -j option to tar to create a .tar.bz or .tbz compressed archive. Alternatively, if your data is on a Windows PC, you can create a .zip archive - svn supports all of these archival formats.

Once you have assembled your data into the single archive file suitable for upload, you can upload it with scp (Secure CoPy) or sftp (Secure FTP); here's an example of using scp on a Linux/UNIX/Mac system where /path/to/archive_file/ is the path (if any) to the location of your archive_file - if you happen to be in the same subdirectory as your archive file when you give this command, you can omit the path:

scp -P 10022 /path/to/archive_file/archive_file username@svn.ma.ic.ac.uk:

and you will be prompted for your SVN server password before the upload starts. More information on how to use scp

Creating your repository

Log back into svn as before and unpack your archive using the appropriate utility or combination of these (tar, unzip, gzip, bzip2, etc). Now create the repository with the following command:

svnadmin create --fs-type fsfs /srv/svn/username

replacing 'username' with your own username. This is your top level repository and if you contemplate creating multiple repositories for different projects or purposes, you can create these subrepositories yourself after you have set up the top level repository, as in the following example:

cd /srv/svn/username
mkdir repos1 repos2 repos3

this will create 3 subrepositories called repos1, repos2 and repos3. You can chose any name you like but do try to stick to UNIX/URL file and folder naming conventions - no illegal characters or punctuation and (Windows users take note) no spaces either.

At this stage you are ready to import your uploaded data into your repository (or subrepository) but you may want to adopt the SVN convention of using the "branches, tags and trunk" directory layout within each of your repositories. This is not essential but as so much Subversion documentation assumes you are using this layout, it's a good idea to use it even if all your working files are in trunk and you never use the branches or tags directories. A quick way of creating all these additional subdirectories is as follows:

cd /srv/svn/username
mkdir repos1/{branches,tags,trunk}
mkdir repos2/{branches,tags,trunk}
mkdir repos3/{branches,tags,trunk}

You can check that all is well with your repository framework with the list option to the svn command:

svn list file:///srv/svn/username

which will list your repository and subrepositories, if present, as in this example:

svn list file:///srv/svn/username
repos1
repos2
repos3

and adding the name of any subrepository you may have created to the end of this command will confirm the existence of the trunk directory:

svn list file:///srv/svn/username/repos2
trunk

With your repository (and perhaps repositories) with the recommended directory layout set up, you're ready import your data.

Importing your data into your repository

Assuming you have unpacked your data archive into your home directory on the SVN server and the data is in a directory called 'my_project4', you can import this data into the repos1 subrepository's trunk directory as the tree called 'My_Project_4' with the command:

cd $HOME
svn import my_project4 file:///srv/svn/username/repos1/trunk/My_Project_4 -m "initial import"

Note that the name of the data tree as imported into your repository is 'My_Project_4' rather than 'my_project4' - this was done deliberately in this example to illustrate the fact you can use any name you like for your trees in your repository, or you can keep it the same as the original. If you do change the name it's wise to stick to the usual UNIX/web file-naming conventions (no spaces and no characters or punctuation that are illegal in URLs) otherwise your users may run into trouble later with accessing these.

You can verify the import has been successful with:

svn list file:///srv/svn/username/repos1/My_Project_4/trunk
go_down_btn.gif
go_next_btn.gif
go_prev_btn.gif
go_top_btn.gif
go_up_btn.gif
help_btn.gif
index.html

which will list the files that were in your original data tree (in this example, it's a web page plus some GIF images). You have now successfully created your first repository and loaded it with your data - now we move on to the web interface and controlling who has access and what they can do with your repository.

Accessing your repository with a web browser

The base URL for the subversion server's web interface is:

http://svn.ma.ic.ac.uk

and to this you need to add the path to your own repository to be able to access it. This path is of the form:

/subversion/username/repository/trunk/

So to access the My_Project_4 repository we have been using as an example, the URL would be:

http://svn.ma.ic.ac.uk/subversion/username/repos1/My_Project_4/trunk

You will be prompted for a username and password if you try to access any area of the SVN server, not just your own repository. Usernames and passwords are chosen by the subversion server's users (ie, you) to control access to the repositories and without a valid username and password, no-one can access any of the repositories.

Access control and security

To get a username and password created for your top level repository, please send an email to Andy Thomas containing the following information:

• your SVN username
• the username you would like others to use to access to your repository
• the password you would like others to use with this username

You can have more than one username/password combination if you like but do try to chose sane usernames with no punctuation characters and no spaces; on the other hand passwords can contain any of these characters but if you chose to use unprintable control characters (eg, ctrl-A), etc then not only will you find it hard to remember these afterwards, but it will be difficult to mail these to me!

Where multiple usernames come into play is when you want to control access to different parts of your repository and using different usernames with different passwords, this can be done. For example, your repository's contents may be laid out like this:

/repos1/My_Project_4/trunk
                                |
                                |---/images
                                |      |
                                |      |---/photos
                                |      |---/icons
                                |      |---/line_drawings
                                |
                                |---/text
                                |      |
                                |      |---/chapter1
                                |      |---/chapter2
                                |
                                |---/PDF
                                |      |
                                |      |---/section1
                                |      |---/section2
                                |      |---/section3
                                |
                                |---/code
                                       |
                                       |---/headers
                                       |---/main
                                       |---/drivers
                                       |---/modules
                                       |---/optional

and you want to restrict access to certain subfolders to certain users; you might decide to use the username 'climate' (assuming your repository is to do with climate change) to enable access to your repository as a whole. If you then decide you don't want everyone who uses the 'climate' username to be able to access your PDFs in ../PDF/section2 but only a select subset of these users, then you can request another username/password pair be set up for this (for example, the username 'clim_pdf_sect2') which will allow this subset of your users to access this area. As well as read access, you can also define whether they can have write access too (that is, the ability to check SVN items back in after they have been checked out and worked on).

Unfortunately, setting up usernames & passwords can only be done by the svn server administrator while setting finer grained access controls at subdirectory and path level is done by the SVN administrator. The latter is particularly complex and not easy to do so it's certainly not something that can be offered to users to do themselves, especially as these settings can affect access to other user's repositories.

Further information about SVN

Subversion and CVS servers are quite complex and discussion of these is beyond the scope of these notes but Cambridge Computer Laboratory have a good article on what it does and how it is used while one of subversion's original developers at Collabnet looks at subversion from the perspectives of the different types of user who may be using a subversion system.