Creating a Secure Repository with Subversion

Subversion is an open source revision control system. It’s well documented, and commercial support, training, and consulting are available through Collabnet and OpenLogic. The Collabnet Enterprise Edition also provides an integrated suite of software development, lifecycle management and collaboration tools in an extensible web-based platform.

Not only is a revision control system considered an essential tool in software development, it can also be a valuable addition to any department that uses files. A revision control system allows you to archive your electronic files so that you have a copy of every saved version of a file as well as that file’s history and comments about its changes, which are recorded and can be viewed later. The ability to rollback means that any past version can become the current version. Rollback can come in mighty handy: imagine a system administrator who discovers a configuration error and needs to quickly return to a previously working configuration file, or an employee who discovers a spreadsheet error that was introduced several versions ago. How about a manager who prefers an earlier graphic in a promotional brochure? A revision control system also provides file locks, authentication mechanisms and permissions—all of which make it an ideal environment to manage multiple user edits.

Before You Start

There are two methods for providing secure (that is, encrypted) access to a Subversion repository. The first method is quite portable and easy to use, but the set-up process is fairly complex. In contrast, set-up’s a snap with our second method, but you’ll find that advantage offset by a steeper learning curve for users—as well as additional time spent installing client software. We suggest that you base your decision about which method best suits your environment on three main criteria: your operating system, the experience level of the administrator available for initial setup, and the experience level of the users who will be accessing the repository.

Method 1: Through Apache

This method is the easiest to use as well as the most portable (the Apache web server can be installed on most operating systems), but it’s also the most complex to setup. We recommend that you consider using this method if you already have an Apache web server and a system administrator experienced in WebDAV since users will not require any additional utilities or training to use the Subversion repository. They’ll be able to browse the repository using their web browser, and can use a WebDAV client to commit (upload) files to the repository. A list of WebDAV utilities includes Microsoft Office, Adobe Dreamweaver and Photoshop, Mac OSX (which has built-in support), Novell NetDrive, KDE Konqueror, and Gnome Nautilus.

Using this method also scores you some benefits provided by Apache to your Subversion repository.  You’ll take advantage of all of Apache’s authentication mechanisms as well as its logging, and you won’t need to reconfigure any firewall rules since it will use HTTPS and can take advantage of any existing caching, load balancing, or proxying servers. However, you’ll find that this method is slower than Method 2 because of the nature of the HTTP protocol.

Method 2: Through SSH

Compared to Method 1, set-up through SSH is trivial. You’ll save time, which is great—but that time will in turn be devoted to installing client software, educating your users on how to use a utility to interact with the Subversion repository, and teaching them to authenticate when they access the repository. Method 2  is better suited to BSD and Linux servers, which typically ship with an SSH server installed. Windows systems do not ship with an SSH server, which means that additional configuration will be required. Windows SSH servers are available from SSHWindows and freeSSHd.

Subversion provides a command line client that needs to be installed on each client. It might not be suitable for users familiar with a graphical environment. Fortunately, there are over a dozen free and commercial graphical clients available for Windows, Mac OS X, and Linux/BSD systems.

A Note on Certificates and Keys

If you’re using Method 1 and don’t have a certificate for Apache, instructions for generating the SSL certificate and configuring Apache for SSL can be found in the SSL FAQ. Modern browsers require user interaction to access a web server whose certificate authority is not recognized. You’ll lessen the confusion of your users by having the certificate signed by an authority from the browser’s certificate authorities list. Different browsers support different authorities, so be sure to choose a certificate authority supported by all the browsers that are in use.

If you’re using Method 2, the key pair used by the SSH server should have been generated during installation of the server. If you wish to use certificates for client authentication, you’ll find instructions for generating and distributing client keys here. This reference also describes agent forwarding, which will reduce the number of times the user has to enter their pass phrase when interacting with the Subversion repository.

Meat & Potatoes

Method 1: Configuring Subversion through Apache and WebDAV

We mentioned before that while this method is the most user-friendly, it is very complex to setup. Before beginning, it’s important that the administrator read, with attention,  the Apache configuration and WebDAV sections of the online Subversion book. The administrator will also need to be familiar with configuring Apache modules and directives.

Since the necessary steps, considerations, and gotchas are well covered in the online Subversion book, we will instead provide a checklist of the steps needed:

1. Make sure the system has Apache 2.x and Subversion installed. If installing Subversion from source, make sure Apache is already installed and include –enable-dav in the configure command.
2. Configure Apache for SSL.
3. Create the Subversion repository using svnadmin and svn import.
4. Modify httpd.conf to load the mod_dav_svn module.
5. Add a Location section to httpd.conf that points to the Subversion repository.
6. Configure the desired method of authentication.
7. Configure the desired access control.
8. Make sure Apache and Subversion permissions match up.
9. Configure MIME types for the types of files that will be saved in the repository.
10. Add a CustomLog directive.

Once Apache is configured, the administrator will want to spend time testing to ensure that authentication and access control work as expected. Testing should be performed from each operating system used by clients, as well as from each WebDAV application to be employed by end-users.

The Subversion book also explains how to configure write-through proxying, which allows one repository to be hosted on multiple Apache servers in a master/slave replication scenario. This allows several offices or geographically separated departments to use the same Subversion repository.

Method 2: Configuring Subversion through SSH

For this method, it’s best that the administrator be familiar with Unix permissions and the creation of users/groups, as well as the basic SSH concepts involved in configuring a Subversion repository to use SSH. When using Subversion through an SSH connection, access control is limited to Unix-style permissions and the umask, which sets the default permissions for new files.

You’ll need to create a user account and group for the Subversion server to employ as well as decide on a umask that is appropriate for the repository, as the default umask for a user account does not typically allow group write access. The default umask can be changed in the Subversion user’s shell file, as described in this how-to (which also explains how to create a wrapper script if you’re unsure of the umask compiled into your Subversion binary). Finally, every user requiring access to the repository will need a user account on the server so they can login over SSH. Make sure each user is added to the Subversion group so they have write access to the repository.

Once the repository and user accounts have been created, providing access to the repository through SSH is a simple matter of starting svnserve (the Subversion server) in tunnel mode, as seen in this how-to. When clients wish to connect, either through the command line or a GUI client, they preface the server address and repository path with “svn+ssh” just like in this example:

svn+ssh://192.168.1.100/home/svn/repository/sharedfiles

The administrator should test that users can connect and that permissions work as expected.  Users who are comfortable with command line connections can be provided with a cheat sheet of commonly used svn commands. An example cheat sheet includes:

svn checkout     #use this the first time you connect to download a working copy of
                 #the repository
svn update       #use this command EVERY time you access the repository and before
                 #making changes to ensure you have the latest copies of files and
                 #to avoid conflicts
svn add          #use this after you create a new file to add to the repository
svn commit       #use this whenever you make changes to a file
svn delete       #use this command to delete a file NEVER use rm
svn log          #use this to see the latest changes

A complete listing of all svn commands and their use is available in the Subversion Complete Reference.

In environments where users prefer a graphical utility, the administrator should spend some time trying out the various graphical clients in order to become familiar with their features. No graphical client provides access to every svn command, but any client should provide access to the most commonly used commands listed above. Being aware of the available features ahead of time will make educating users much easier and encourage them to actually use the repository.

Two examples of popular graphic clients are seen below:

TortoiseSVN Adds Menu Items to Windows Explorer

RapidSVN on Windows

Finishing Up

Regardless of the method implemented, education is key. Users will need to invest some time becoming familiar with the basic work cycle and selecting a client with which they’re comfortable accessing the repository and making changes. But soon enough your investment in user education will pay off in increased productivity and ease of collaboration, and users will wonder how they ever lived without a secure repository!

Share this post: